nextcloud-nodered-woocommerce/README.md

# nextcloud-nodered-woocommerce

Node-RED nodes for the [WooCommerce](https://woocommerce.com/) REST API. Part of the
[nextcloud-nodered](https://kode.hannesahlin.se/n3wk/) suite.

## Package

`node-red-contrib-nextcloud-woocommerce`

## Nodes

| Node | Type | Purpose |
|------|------|---------|
| `woocommerce-config` | config | Base URL + Consumer Key + Consumer Secret |
| `woocommerce-order` | function | list (with filters), get, updateStatus, addNote, getNotes |
| `woocommerce-customer` | function | search (by email), get, create |
| `woocommerce-product` | function | list, get (for enriching order data) |

## Installation

### Prerequisites

- An existing [nextcloud-node-red](https://kode.hannesahlin.se/n3wk/nextcloud-nodered-ocs-api) installation.
- WooCommerce API key with Read permission (preferably Read/Write), bound to an Administrator user.

### Quick install (recommended)

```bash
git clone https://kode.hannesahlin.se/n3wk/nextcloud-nodered-woocommerce.git
cd nextcloud-nodered-woocommerce
export NODERED_DIR=/path/to/your/nextcloud-node-red
bash bootstrap-install.sh
cd $NODERED_DIR
docker compose build --no-cache
docker compose up -d
```

### Manual install

```bash
export NODERED_DIR=/path/to/your/nextcloud-node-red
bash integrate-into-nodered.sh
```

The integrate script:
1. Copies all `.js` and `.html` files into `$NODERED_DIR/nodes/`.
2. Copies the package to `$NODERED_DIR/opt/nextcloud-nodes/node-red-contrib-nextcloud-woocommerce/`.
3. Patches `$NODERED_DIR/entrypoint.sh` to install the nodes on container start.
4. Is idempotent — safe to run multiple times.

## Authentication

| Method | Details |
|--------|---------|
| Consumer Key | From WooCommerce → Settings → Advanced → REST API |
| Consumer Secret | Paired with Consumer Key |

**Important:** Base URL is the WooCommerce REST API URL, e.g. `https://example.com/wp-json/wc/v3/`.
The API key must have at least Read permission. The user the key is bound to
must be an Administrator or have equivalent capabilities.

## Node Details

### woocommerce-order

Operations: `list`, `get`, `updateStatus`, `addNote`, `getNotes`.

**List with filters:**
```
msg.status   = "processing" | "completed" | "on-hold" | ...
msg.after    = "2026-10-01T00:00:00"  (ISO 8601)
msg.before   = "2026-10-31T23:59:59"
msg.customer = customer ID
msg.product  = product ID
msg.limit    = per_page (default 10)
msg.page     = page number
```

**Update status:**
```
msg.orderId  = 31921
msg.status   = "completed"
```

**Add note:**
```
msg.orderId      = 31921
msg.note         = "Customer contacted via phone"
msg.customerNote = true  (optional — visible to customer)
```

### woocommerce-customer

Operations: `search` (by email), `get`, `create`.

**Search by email:**
```
msg.email = "john.doe@example.com"
```

### woocommerce-product

Operations: `list`, `get`.

Useful for enriching order `line_items` with product name, SKU, images.

## Vertical Integration Flow: WooCommerce → Zammad → Nextcloud

This is the trigger half of the vertical flow. Combined with
[nextcloud-nodered-zammad](https://kode.hannesahlin.se/n3wk/nextcloud-nodered-zammad)
and the existing Nextcloud OCS nodes:

### Step 1: Poll for new orders (or webhook)

Use `woocommerce-order` with operation `list` and `msg.status = "processing"`
on a schedule (inject node with cron), or trigger via a WooCommerce webhook.

### Step 2: Extract order info in a Function node

```javascript
msg.title = "Order #" + msg.payload.number + " – " +
    msg.payload.billing.first_name + " " + msg.payload.billing.last_name +
    (msg.payload.billing.company ? " (" + msg.payload.billing.company + ")" : "");

msg.customer = msg.payload.billing.email;

msg.body = "Products:\n";
for (let item of msg.payload.line_items) {
    msg.body += "- " + item.name + " x" + item.quantity +
        " (" + msg.payload.currency + " " + item.total + ")\n";
}
msg.body += "\nTotal: " + msg.payload.currency + " " + msg.payload.total + "\n";
msg.body += "Address: " + msg.payload.billing.address_1 + ", " +
    msg.payload.billing.city + " " + msg.payload.billing.postcode + "\n";
msg.body += "Phone: " + msg.payload.billing.phone + "\n";
msg.body += "Email: " + msg.payload.billing.email;

msg.ticketId = msg.payload.id;
msg.tag = "woocommerce-order";

return msg;
```

### Step 3: Create Zammad ticket

`zammad-ticket` node (operation: create) receives the Function output.
Title: `Order #12345 – John Doe (Acme Corp)`
Customer: billing email
Body: product list + amount + address + phone

### Step 4: Tag the ticket

`zammad-ticket` (operation: addTag) with `msg.tag = "woocommerce-order"`.

### Step 5: Organize in Nextcloud

Existing Nextcloud OCS nodes:
- Create/update customer folder
- Create note or Deck card with order details
- Optional: calendar event for follow-up
- Link back to Zammad ticket in note/card

### Example Flow JSON

See `flows/woocommerce-to-zammad.json` for a complete example flow
(no real credentials included).

## Integration with Other Packages

- **nextcloud-nodered-zammad**: Creates and manages Zammad tickets from WooCommerce orders.
- **nextcloud-nodered-ocs-api**: Provides Nextcloud OCS nodes for creating folders, notes, deck cards, etc.
- **nextcloud-nodered-agent**: Agent-based nodes for complex orchestration.

## Credentials Security

- Consumer Key and Secret are stored **only** in the Node-RED config node (encrypted at rest).
- Never commit credentials to git (`.gitignore` excludes them).
- The config node uses Node-RED's built-in credential encryption.

## License

MIT