@sadrmanesh/commerce-agent-skills 0.0.0-stage → 0.3.0

package/skills/woocommerce-rest-api/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: woocommerce-rest-api
+description: "Call the WooCommerce REST API at wc/v3, including authentication, pagination, batch writes, and webhook registration, and keep it separate from the Store API. Use when an external system integrates with a WooCommerce store over HTTP."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# WooCommerce REST API
+
+Use this skill for a server-side client of a WooCommerce store. The browser checkout uses a different API. Payment notification handling belongs to the webhook reliability skill.
+
+## Which API
+
+| API | Namespace | Who calls it |
+| --- | --- | --- |
+| WooCommerce REST API | `/wp-json/wc/v3/` | Your server, with a consumer key and secret. |
+| Store API | `/wp-json/wc/store/v1/` | The storefront, with a cart token and nonce. |
+| Legacy REST API | `/wc-api/v3/` | Old clients only. Do not start new work here. |
+
+The current REST API requires WooCommerce 3.5+, WordPress 4.4+, and pretty permalinks. Default permalinks do not serve these routes.
+
+Never put a consumer secret in browser JavaScript, a mobile binary, or a Store API request.
+
+## Authentication
+
+Create a key at **WooCommerce > Settings > Advanced > REST API**. The key inherits the WordPress user you bind it to, and the permission you select: Read, Write, or Read/Write. Deleting that user disables the key. The consumer secret is shown once.
+
+Over HTTPS, send HTTP Basic authentication with the consumer key as the username and the consumer secret as the password.
+
+```bash
+curl --user "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET" \
+  "https://shop.example/wp-json/wc/v3/orders?per_page=20"
+```
+
+Some FastCGI hosts drop the `Authorization` header and WooCommerce then reports that the consumer key is missing. Only then, and only over HTTPS, send `consumer_key` and `consumer_secret` as query parameters. Query secrets land in access logs and caches. Prefer fixing the host header.
+
+Over plain HTTP, WooCommerce expects one-legged OAuth 1.0a. For a new integration, use HTTPS instead of adding an OAuth client.
+
+Store the secret in the server environment or a secret manager. Do not commit it.
+
+## Reads
+
+- Follow pages with `page` and `per_page`. `per_page` above 100 is rejected. Read `X-WP-Total` and `X-WP-TotalPages`.
+- Request only the fields you need when the endpoint supports `_fields`.
+- Compare instants with `date_created_gmt` and `date_modified_gmt`. The unsuffixed fields are in the site timezone.
+- Product variations are a child resource: `/wp-json/wc/v3/products/<id>/variations`.
+- Error bodies use the WordPress shape `{ "code", "message", "data": { "status" } }`. Branch on `code` and HTTP status, not on the message string.
+
+Endpoint groups and the batch body are in [the endpoint notes](references/endpoints.md).
+
+## Writes
+
+The REST API does not provide a general idempotency key. A retried `POST /orders` can create a second order.
+
+1. Put your own key in meta, for example `meta_data: [{ "key": "_idempotency_key", "value": "<key>" }]`.
+2. Before creating, search orders by that meta. Treat a hit as the original result.
+3. Meta search is not a unique index. Two concurrent creates can still both miss. For payments, dedupe on the provider transaction id as well. See the order and webhook skill.
+
+Batch routes (`POST /products/batch`, `/orders/batch`, and the customer and coupon equivalents) accept `create`, `update`, and `delete`. The batch is not one database transaction. Read each item result. A 200 response can still contain per-item errors.
+
+Update orders and products with the resource id. Do not match a later update on SKU alone unless you have already resolved the SKU to one id. SKUs can change.
+
+## Webhooks registered over REST
+
+`POST /wp-json/wc/v3/webhooks` with `name`, `topic`, `delivery_url`, and `secret`. The secret is write-only on later reads. If you omit it, WooCommerce falls back to the API user's consumer secret. Set an explicit secret.
+
+The first save of an active webhook delivers a ping, not a full order or product. Acknowledge that ping with a 2xx response and do not create an order from it.
+
+Topic names look like `order.updated` and `product.created`. The delivered resource body matches the REST representation. Verify `X-WC-Webhook-Signature` against the raw body before trusting it. The signature procedure is in the order and webhook skill.
+
+## Gotchas
+
+- A Read key cannot create products. A Write key cannot list orders. Check the key permission and the user's capability when you get `401` or `403`.
+- Order status names in the API omit the `wc-` prefix (`processing`, not `wc-processing`).
+- Prices are strings in major currency units, such as `"19.00"`. Do not send a float.
+- HPOS does not change the REST shape. Clients should keep using this API rather than reading the database.
+- Webhook delivery that returns `301` or `302` can be counted as success while `WC_Webhook::deliver()` sends the body with redirects disabled. Serve the JSON handler on the exact `delivery_url`.
+
+## Verification
+
+- A request with the wrong secret returns 401 and creates nothing.
+- Listing orders walks every `X-WP-TotalPages` page without duplicating or skipping ids.
+- Repeating the same create with the same idempotency key returns one order.
+- A webhook ping does not create an order. A signed `order.updated` delivery updates the matching local record.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/woocommerce-rest-api/evals/examples/https-basic-auth.md

@@ -0,0 +1,8 @@
+Call the current REST API from the server.
+
+```bash
+curl --user "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET" \
+  "https://shop.example/wp-json/wc/v3/orders"
+```
+
+Send the consumer key and secret as HTTP Basic authentication over HTTPS only.

package/skills/woocommerce-rest-api/evals/examples/idempotent-order-create.md

@@ -0,0 +1,7 @@
+Search for an existing order by meta before posting a new one.
+
+```json
+{ "meta_data": [ { "key": "_idempotency_key", "value": "checkout-1042" } ] }
+```
+
+If `wc_get` style search on `_idempotency_key` hits, return that order instead of creating another.

package/skills/woocommerce-rest-api/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "https-basic-auth",
+      "task": "Authenticate a server-side WooCommerce REST client over HTTPS without putting the secret in the browser.",
+      "expects": {
+        "must_include": [
+          "/wp-json/wc/v3/",
+          "Basic"
+        ],
+        "must_not_include": [
+          "wc-api/v3"
+        ]
+      }
+    },
+    {
+      "id": "idempotent-order-create",
+      "task": "Create an order through the REST API so a retried POST does not create a second order.",
+      "expects": {
+        "must_include": [
+          "meta_data",
+          "_idempotency_key"
+        ],
+        "must_not_include": [
+          "consumer_secret="
+        ]
+      }
+    }
+  ]
+}

package/skills/woocommerce-rest-api/references/endpoints.md

@@ -0,0 +1,66 @@
+# WooCommerce REST API endpoints
+
+Base path: `/wp-json/wc/v3/`. All routes below are relative to that base. Authenticate every call as described in `SKILL.md`.
+
+## Resources
+
+| Path | Typical use |
+| --- | --- |
+| `products` | Create and update the parent product. |
+| `products/<id>/variations` | Create and update purchasable variants. |
+| `products/attributes` | Global attributes. Taxonomy name is `pa_` plus the slug. |
+| `products/categories` | Product categories. |
+| `products/<id>/reviews` | Product reviews. |
+| `orders` | Order header, line items, shipping lines, fee lines, and coupons. |
+| `orders/<id>/notes` | Customer or private notes. `customer_note: true` emails the customer. |
+| `orders/<id>/refunds` | Create a refund. This is the REST equivalent of `wc_create_refund()`. |
+| `customers` | WordPress users who are customers. Guest orders are not customers until an account exists. |
+| `coupons` | Coupon definitions. Applying a coupon still happens in checkout or by editing the order. |
+| `webhooks` | Register, pause, or delete a webhook. `secret` is write-only. |
+| `taxes`, `shipping/zones`, `payment_gateways`, `settings` | Store configuration. Prefer the admin UI unless you are provisioning stores. |
+| `system_status` | Environment diagnostic. Do not require it on the hot path. |
+| `reports/sales` | Aggregates. For large extracts, page through `orders` instead of assuming one report call is complete. |
+
+`<id>` is the integer resource id.
+
+## Batch
+
+`POST products/batch`, `orders/batch`, `customers/batch`, and `coupons/batch`.
+
+```json
+{
+  "create": [],
+  "update": [{ "id": 10, "status": "draft" }],
+  "delete": [11]
+}
+```
+
+Inspect `create`, `update`, and `delete` in the response. An item error does not roll back its siblings.
+
+## Pagination and filters
+
+- `page` starts at 1. `per_page` defaults to 10 and cannot exceed 100.
+- Order list filters include `status`, `customer`, `product`, `after`, `before`, `modified_after`, and `modified_before`. Pass the date filters as ISO-8601 timestamps.
+- Use `modified_after` for an incremental sync. A record can change while you are paging. Keep an overlap and dedupe by id plus `date_modified_gmt`. If the installed WooCommerce rejects `modified_after`, fall back to `after` and `before`.
+
+## Status values
+
+Order statuses used by core: `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed`, and `checkout-draft`. Custom statuses registered with `woocommerce_register_shop_order_post_statuses` also appear. Do not send the `wc-` internal prefix.
+
+Product `status` uses WordPress post statuses such as `publish`, `draft`, and `private`. Catalog visibility is `catalog_visibility` (`visible`, `catalog`, `search`, `hidden`), which is not the same field.
+
+## Webhook topics
+
+Common topics: `order.created`, `order.updated`, `order.deleted`, `product.created`, `product.updated`, `product.deleted`, `customer.created`, `customer.updated`, `coupon.created`, `coupon.updated`. Action topics bind a webhook to a WooCommerce action name. Prefer a resource topic unless you need a specific action.
+
+Headers on delivery:
+
+- `X-WC-Webhook-Source`
+- `X-WC-Webhook-Topic`
+- `X-WC-Webhook-Resource`
+- `X-WC-Webhook-Event`
+- `X-WC-Webhook-Signature`
+- `X-WC-Webhook-ID`
+- `X-WC-Webhook-Delivery-ID`
+
+`X-WC-Webhook-Delivery-ID` changes on every attempt. Do not use it as the only idempotency key.

package/skills/wordpress-plugin-security/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: wordpress-plugin-security
+description: "Review and implement WordPress plugin security: capabilities, nonces, sanitization, escaping, prepared SQL, and REST permission callbacks. Use when adding admin screens, AJAX, uploads, hooks, or REST routes in a WordPress or WooCommerce plugin."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# WordPress plugin security
+
+Apply this skill to every new entry point: admin form, admin-ajax, admin-post, REST route, Store API extension, file upload, and any hook that reads `$_POST`, `$_GET`, or `$_REQUEST`.
+
+WooCommerce data access is covered by the WooCommerce plugin skill. This skill is the authorization and input/output layer around it.
+
+## Procedure
+
+1. Name the actor and the capability. Check `current_user_can()` with a capability, not a role name. WooCommerce capabilities include `manage_woocommerce`, `edit_shop_orders`, `edit_products`, and `edit_shop_coupons`.
+2. For a state change that uses a cookie session, require a nonce. Nonces stop cross-site request forgery. They do not identify the user and they expire.
+3. Sanitize input into a known type, then pass that value to CRUD or to `$wpdb->prepare()`. Escape at the point of HTML, attribute, or URL output.
+4. Give every REST route a real `permission_callback`. `__return_true` is only acceptable for data you would publish to anonymous visitors.
+5. Fail closed. A missing order, a failed nonce, or a missing capability returns without writing.
+
+Use [the review checklist](references/review-checklist.md) before finishing a change.
+
+## Forms and admin-post
+
+```php
+function example_save_desk_note() {
+    if ( ! current_user_can( 'edit_shop_orders' ) ) {
+        wp_die( esc_html__( 'You cannot edit orders.', 'example-plugin' ) );
+    }
+    check_admin_referer( 'example_order_panel', 'example_order_nonce' );
+
+    $order = wc_get_order( absint( wp_unslash( $_POST['order_id'] ?? 0 ) ) );
+    if ( ! $order ) {
+        wp_die( esc_html__( 'Order not found.', 'example-plugin' ) );
+    }
+
+    $note = sanitize_text_field( wp_unslash( $_POST['desk_note'] ?? '' ) );
+    $order->update_meta_data( '_desk_note', $note );
+    $order->save();
+}
+add_action( 'admin_post_example_save_desk_note', 'example_save_desk_note' );
+```
+
+Unslash, then sanitize. `wp_unslash()` reverses magic quotes behavior that WordPress still normalizes for. Cast ids with `absint()`. Allow limited HTML only with `wp_kses()` or `wp_kses_post()` against an explicit allow list.
+
+## AJAX
+
+- Logged-in actions use `wp_ajax_{action}`.
+- Anonymous actions use `wp_ajax_nopriv_{action}` and must not trust the visitor with shop data.
+- Verify with `check_ajax_referer()`.
+- Return JSON with `wp_send_json_success()` or `wp_send_json_error()`. Do not echo SQL, file paths, or secrets in the error payload.
+
+## REST routes
+
+```php
+register_rest_route(
+    'example/v1',
+    '/orders/(?P<id>\\d+)/desk-note',
+    array(
+        'methods'             => WP_REST_Server::EDITABLE,
+        'callback'            => 'example_rest_save_desk_note',
+        'permission_callback' => static function () {
+            return current_user_can( 'edit_shop_orders' );
+        },
+        'args'                => array(
+            'id'        => array( 'sanitize_callback' => 'absint' ),
+            'desk_note' => array( 'sanitize_callback' => 'sanitize_text_field' ),
+        ),
+    )
+);
+```
+
+The permission callback must authorize the object, not only the route. A user who can `edit_shop_orders` may still be blocked by a custom order cap. Check the specific order when the shop uses per-order restrictions.
+
+Do not accept a user id, order id, or price from the client as proof of identity. Load the object and derive the price on the server.
+
+## SQL
+
+```php
+$email = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );
+$rows  = $wpdb->get_results(
+    $wpdb->prepare(
+        'SELECT id FROM ' . $wpdb->prefix . 'wc_orders WHERE billing_email = %s',
+        $email
+    )
+);
+```
+
+Pass every variable through `prepare()`. Do not concatenate table names from request data. Hard-code a known suffix and prefix it with `$wpdb->prefix`. Prefer `wc_get_orders()` for order lookup. The SQL above is only a pattern for a report you have already decided must run against the HPOS orders table.
+
+## Uploads and files
+
+- Use `wp_handle_upload()` and check the returned error.
+- Allow a short extension list. Do not trust the browser MIME type alone.
+- Store uploads outside executable locations when they are not meant to be public. Never use a request parameter as a filesystem path.
+- `include` and `require` only files whose paths are built from constants you control.
+
+## Gotchas
+
+- `check_ajax_referer()` dies on failure by default. That is fine for AJAX. For a REST request, return a `WP_Error` with status 403 instead of dying.
+- Nonces in HTML must be created for the same action string you later verify. Copying a WooCommerce nonce from another screen will fail, and it should.
+- `current_user_can( 'administrator' )` misses shop managers who legitimately have `manage_woocommerce`, and it matches the wrong concept. Check the capability.
+- `esc_html()` does not make a URL safe. Use `esc_url()`. `esc_attr()` does not make HTML body text safe. Escape for the context you are in.
+- `unserialize()` on stored or posted data can instantiate objects. Store JSON, or use `maybe_unserialize()` only on data your own code wrote, and prefer JSON for new meta.
+- A hidden form field such as `order_id` is attacker-controlled. Capability checks happen after you load that order, not instead of loading it.
+- Logging `$_POST` on a checkout request can capture payment fields. Log ids and your own error codes.
+
+## Verification
+
+- Repeat the write while logged out. It does not change data.
+- Repeat the write as a subscriber or customer. It does not change shop data.
+- Repeat the write with the nonce removed. It does not change data.
+- A REST callback with the permission callback removed is a failed review, even if the happy path works.
+- An error response does not include a secret, a stack trace, or another customer's data.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/wordpress-plugin-security/evals/examples/admin-form-nonce.md

@@ -0,0 +1,9 @@
+Verify the user and the nonce, then sanitize the field.
+
+```php
+if ( ! current_user_can( 'edit_shop_orders' ) ) {
+    wp_die( esc_html__( 'You cannot edit orders.', 'example-plugin' ) );
+}
+check_admin_referer( 'example_order_panel' );
+$note = sanitize_text_field( wp_unslash( $_POST['desk_note'] ?? '' ) );
+```

package/skills/wordpress-plugin-security/evals/examples/private-rest-route.md

@@ -0,0 +1,9 @@
+Register the route with a real permission callback.
+
+```php
+'permission_callback' => static function () {
+    return current_user_can( 'edit_shop_orders' );
+},
+```
+
+Sanitize the note and load the order on the server before writing.

package/skills/wordpress-plugin-security/evals/tasks.json

@@ -0,0 +1,31 @@
+{
+  "tasks": [
+    {
+      "id": "private-rest-route",
+      "task": "Register a REST route that updates an order note and rejects shoppers who cannot edit orders.",
+      "expects": {
+        "must_include": [
+          "permission_callback",
+          "current_user_can",
+          "edit_shop_orders"
+        ],
+        "must_not_include": [
+          "__return_true"
+        ]
+      }
+    },
+    {
+      "id": "admin-form-nonce",
+      "task": "Save an admin form that changes an order only when the user has the capability and a valid nonce.",
+      "expects": {
+        "must_include": [
+          "check_admin_referer",
+          "current_user_can"
+        ],
+        "must_not_include": [
+          "unserialize("
+        ]
+      }
+    }
+  ]
+}

package/skills/wordpress-plugin-security/references/review-checklist.md

@@ -0,0 +1,31 @@
+# Plugin security review
+
+Check each new entry point. Skip a line only when it does not apply, and say why.
+
+## Entry
+
+- The file starts with `defined( 'ABSPATH' ) || exit;` or is loaded only from a file that does.
+- Admin-post, admin-ajax, REST, and form handlers each have their own capability check.
+- State-changing browser requests verify a nonce bound to that action.
+- The REST `permission_callback` is a named function or closure that returns a capability check, never `__return_true`, for private data.
+
+## Input
+
+- Request values go through `wp_unslash()` and then a sanitizer: `absint`, `sanitize_text_field`, `sanitize_email`, `esc_url_raw`, `wp_kses_post`, or a strict allow list.
+- Prices, quantities, and statuses are validated against server-side rules. The client amount is not stored as the charged amount.
+- Sort columns, table names, and file paths are chosen from a fixed map, not from the request string.
+- Uploads use `wp_handle_upload()` and an extension allow list.
+
+## Output and storage
+
+- HTML text uses `esc_html()`. Attributes use `esc_attr()`. URLs use `esc_url()`. Translated strings use the escaping gettext variant.
+- SQL variables use `$wpdb->prepare()`.
+- New meta and options are JSON or scalars. No `unserialize()` of request data.
+- Secrets and card data are not written to logs, order notes, or the browser.
+
+## WooCommerce-specific
+
+- Order and product writes use CRUD.
+- The handler works for HPOS when it touches orders.
+- Checkout logic that must run for blocks is hooked to the Store API, not only to classic checkout.
+- Webhook handlers verify a signature instead of using a nonce. Nonces are for cookie sessions. Webhooks are not cookie sessions.