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

package/skills/mcp-store-tooling/scripts/check-tool-definitions.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Check MCP tool definitions for store safety rules.
+// Usage: node check-tool-definitions.mjs <tools.json>
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+const WRITE_VERB = /^(create|update|delete|refund|cancel|set|add|remove|bulk|send|apply|adjust)_/;
+const RISKY_VERB = /^(delete|refund|cancel|bulk|remove)_/;
+
+/** Returns a list of problems with a list of tool definitions. */
+export function checkToolDefinitions(tools) {
+  if (!Array.isArray(tools)) return ["tools must be an array"];
+  const errors = [];
+  const names = new Set();
+  for (const [index, tool] of tools.entries()) {
+    const label = typeof tool?.name === "string" ? tool.name : `tool ${index}`;
+    if (!tool || typeof tool !== "object") {
+      errors.push(`${label}: must be an object`);
+      continue;
+    }
+    if (typeof tool.name !== "string" || !NAME.test(tool.name)) errors.push(`${label}: name must be lowercase snake_case`);
+    else if (names.has(tool.name)) errors.push(`${label}: duplicate name`);
+    else names.add(tool.name);
+    if (typeof tool.description !== "string" || tool.description.trim().length < 20) errors.push(`${label}: description must be at least 20 characters`);
+    if (tool.inputSchema?.type !== "object") errors.push(`${label}: inputSchema.type must be "object"`);
+    const annotations = tool.annotations;
+    if (!annotations || typeof annotations.readOnlyHint !== "boolean") {
+      errors.push(`${label}: annotations.readOnlyHint must be set`);
+      continue;
+    }
+    const writes = WRITE_VERB.test(tool.name ?? "");
+    if (writes && annotations.readOnlyHint) errors.push(`${label}: looks like a write but readOnlyHint is true`);
+    if (!annotations.readOnlyHint && typeof annotations.destructiveHint !== "boolean") {
+      errors.push(`${label}: write tools must set destructiveHint`);
+    }
+    if (!annotations.readOnlyHint && typeof annotations.idempotentHint !== "boolean") {
+      errors.push(`${label}: write tools must set idempotentHint`);
+    }
+    if (RISKY_VERB.test(tool.name ?? "")) {
+      const properties = tool.inputSchema?.properties ?? {};
+      if (!properties.dryRun) errors.push(`${label}: risky writes need a dryRun input`);
+      if (!properties.confirm) errors.push(`${label}: risky writes need a confirm input`);
+    }
+    const list = /^list_/.test(tool.name ?? "");
+    if (list) {
+      const properties = tool.inputSchema?.properties ?? {};
+      const perPage = properties.perPage ?? properties.limit;
+      if (!perPage || typeof perPage.maximum !== "number") errors.push(`${label}: list tools need a perPage or limit with a maximum`);
+    }
+  }
+  return errors;
+}
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+  const [file] = process.argv.slice(2);
+  if (!file) {
+    console.error("Usage: node check-tool-definitions.mjs <tools.json>");
+    process.exit(2);
+  }
+  const errors = checkToolDefinitions(JSON.parse(await readFile(file, "utf8")));
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+  console.log("Tool definitions look safe.");
+}

package/skills/multi-vendor-payouts/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: multi-vendor-payouts
+description: "Split a marketplace order by vendor, record commission as ledger entries, and pay vendors only settled amounts. Use when adding vendor catalogs, commissions, refunds that cross vendors, or payout batches."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Multi-vendor payouts
+
+Use this skill when more than one vendor sells on one order. Catalog shape is the product-catalog skill. Charging the shopper is the payment skill. This skill records who is owed what after that charge.
+
+Do not name a vendor plugin's internal functions unless that plugin is in the project and you have read them. The ledger below is the model to implement, including when the store uses an existing multi-vendor extension.
+
+## Procedure
+
+1. Put `vendor_id` on every sellable line. A line without a vendor cannot be paid out.
+2. On payment, write ledger entries. Do not edit the line price to "take commission". Commission is its own entry.
+3. Decide, in data, who is merchant of record for the goods, the tax, and the shipping. Do not assume the vendor is.
+4. Hold entries until the refund window or the delivery rule you stored. A payout batch sums only entries that are payable.
+5. Send the payout with an idempotency key. A second run of the same batch does not pay twice.
+6. A refund writes reversing entries. It does not delete the original lines.
+
+The entry types are in [the ledger notes](references/ledger.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Ledger entry
+
+Each entry has: `id`, `order_id`, `vendor_id` or `platform`, `type`, `amount` in integer minor units, `currency`, `available_at`, and `payout_id` once paid.
+
+Amounts are signed. A sale credit to the vendor is positive. Commission the platform keeps is negative on the vendor and positive on the platform, or two explicit entries that sum to the same result. Pick one representation and use it everywhere.
+
+`amount` uses the order currency. Do not convert to a payout currency inside the entry. Conversion, if it exists, is a later payout step with its own rate and timestamp.
+
+## When money becomes payable
+
+- Authorization is not a sale. Write no payable entry until the payment skill marks the order paid.
+- `available_at` is at least the refund window, or the delivery confirmation, whichever the marketplace rule uses.
+- Pending entries can be displayed as upcoming. They are excluded from the payout sum.
+
+## Payout batch
+
+- Select entries where `available_at` is in the past, `payout_id` is null, and the vendor account is allowed to receive funds.
+- Group by vendor and currency.
+- Persist the batch and stamp `payout_id` in the same transaction as the decision to pay.
+- Call the payout provider with `payout_{batchId}`. If the call times out, retry with that key and do not create a second batch.
+- A provider failure clears nothing silently. The batch stays `processing` or moves to `failed` with the entries still reserved, so a retry cannot select them into a new batch.
+
+## Refunds
+
+- Refund the shopper through the payment skill for the amount they paid.
+- Reverse the vendor net and the commission in proportion to the refunded lines, including tax if the vendor was credited for tax.
+- If the payout already left, the reversal is a negative balance on the next batch, not a deleted history.
+
+## Gotchas
+
+- One order can contain two vendors. A single commission percent on the order total assigns one vendor's shipping to the other.
+- Paying the gross and also forgetting to retain commission overpays the vendor.
+- Summing order totals again at payout time double-counts if the ledger is also summed.
+- Blocking a vendor after entries are `processing` must not release those entries back into the selectable pool.
+
+## Verification
+
+- A paid two-vendor order produces entries whose vendor nets plus platform commission equal the goods total you intended to split.
+- An unpaid order produces no payable entries.
+- Running the payout job twice creates one provider payout per vendor.
+- A refund after payout reduces the next batch and leaves the original entries in place.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/multi-vendor-payouts/evals/examples/retry-payout.md

@@ -0,0 +1,3 @@
+Stamp `payout_id` on the selected entries in the same transaction as the batch.
+
+Retry the provider with that batch idempotency key. Do not select those entries into a second batch.

package/skills/multi-vendor-payouts/evals/examples/split-paid-order.md

@@ -0,0 +1,3 @@
+Write ledger entries when the shopper payment is confirmed.
+
+The vendor `goods` entry and the platform `commission` entry split the line total. The catalog line price stays what the shopper paid.

package/skills/multi-vendor-payouts/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "split-paid-order",
+      "task": "Record vendor goods and platform commission for a paid marketplace order without editing the line price.",
+      "expects": {
+        "must_include": [
+          "ledger",
+          "commission"
+        ],
+        "must_not_include": [
+          "edit the line price"
+        ]
+      }
+    },
+    {
+      "id": "retry-payout",
+      "task": "Run a vendor payout batch twice without sending the money twice.",
+      "expects": {
+        "must_include": [
+          "payout_id",
+          "idempotency"
+        ],
+        "must_not_include": [
+          "sum the order totals again"
+        ]
+      }
+    }
+  ]
+}

package/skills/multi-vendor-payouts/references/ledger.md

@@ -0,0 +1,35 @@
+# Marketplace ledger
+
+## Entry types
+
+| Type | Who is credited | When it is written |
+| --- | --- | --- |
+| `goods` | Vendor | Order is paid, for that vendor's line totals after line discounts |
+| `commission` | Platform | Same moment, as the platform's share of those lines |
+| `shipping` | Vendor or platform | Whoever the marketplace rule says keeps the shipping the shopper paid |
+| `tax` | Vendor or platform | Whoever is responsible for remitting that tax |
+| `refund_goods` | Reverses `goods` | Refund is confirmed |
+| `refund_commission` | Reverses `commission` | Refund is confirmed |
+| `adjustment` | Either | A person records a correction with a reason |
+
+`goods` plus `commission` for a line equals the line total the shopper paid for those goods, before the shipping and tax entries. If commission is stored as a negative vendor entry instead of a platform entry, the vendor net is `goods + commission` and the platform total is the absolute commission. Do not store it both ways.
+
+## Worked numbers
+
+Shopper pays 100.00 for vendor goods. Commission is 10%. Vendor shipping is 0. The currency has two minor units.
+
+- Vendor `goods`: `10000`
+- Vendor `commission`: `-1000` if commission is a negative vendor entry
+- Vendor payable after the hold: `9000`
+
+Tax and shipping stay out of that 100.00 until their own entries exist. Do not subtract commission from the tax entry unless the contract says the commission base includes tax.
+
+## Payout record
+
+`id`, `vendor_id`, `currency`, `amount` (sum of reserved entries), `status` (`processing`, `paid`, `failed`), `idempotency_key`, `provider_payout_id`.
+
+`paid` requires the provider id. `failed` keeps `idempotency_key` so the retry is the same payout.
+
+## Merchant of record
+
+Store `merchant_of_record` on the order or the line as `platform` or `vendor`. This is a business and legal choice the marketplace has already made. The ledger follows that flag. It does not decide it.

package/skills/order-and-webhook-reliability/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: order-and-webhook-reliability
+description: "Accept order and payment webhooks with a raw-body signature check, durable deduplication, and reconciliation against the source of truth. Use when handling order events, payment notifications, or outbound webhook delivery."
+license: MIT
+compatibility: "The signature checker requires Node.js 20 or newer. No network access."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Order and webhook reliability
+
+Use this skill for inbound payment or order notifications and for outbound webhooks your shop sends. Provider-specific state mapping stays in the payment skill. WooCommerce header names and the failure limit are in [the WooCommerce webhook notes](references/woocommerce-webhooks.md).
+
+Verify a WooCommerce signature locally with [`scripts/verify-hmac-signature.mjs`](scripts/verify-hmac-signature.mjs).
+
+## Procedure
+
+1. Read the raw body before any JSON parser reorders or re-encodes it.
+2. Verify the signature with a constant-time compare. Reject unsigned or invalid requests before you look at the event type.
+3. Store the event in a durable inbox, unique on the provider event id when that id is stable across retries.
+4. Acknowledge with 2xx only after that store succeeds. Do the order update after the store, in the same transaction when you can, or in a worker that can retry.
+5. Apply the change only if this event is newer than what you stored, or if the fetched resource still matches the event.
+6. When the event is incomplete or out of order, fetch the order or payment from the source of truth and write that.
+
+## Inbox
+
+A practical unique key:
+
+- Provider event id, when the provider reuses it for retries of the same event.
+- Otherwise a hash of topic, resource id, and the resource's `date_modified_gmt` or equivalent version.
+
+Do not dedupe only on a delivery attempt id. Those change when the sender times out and posts again.
+
+Store: event id, topic, resource id, raw body, signature verification time, and processing status (`stored`, `applied`, `ignored`). Ignore a duplicate by returning 2xx and the original result. A second apply is a bug.
+
+## Apply rules
+
+- Compare amounts in integer minor units before marking an order paid.
+- Do not move an order backward because a late `pending` event arrived after `paid`, unless the source fetch shows the payment was reversed.
+- Record the provider payment id on the first paid transition. The paid transition itself is idempotent.
+- Outbound side effects (email, stock, fulfillment) run inside that same idempotent transition, not in the HTTP handler after a commit you might repeat.
+
+## Outbound webhooks
+
+When your shop sends webhooks:
+
+- Sign the exact bytes you send.
+- Include your event id and the resource version.
+- Retry with backoff on connection failures and 5xx. Stop on a 4xx that means the subscription is invalid.
+- Use an outbox row written in the same transaction as the order change. A webhook built only in memory is lost when the process dies after the order commit.
+- Receivers will see duplicates and gaps. Document the event id so they can dedupe.
+
+## Failures
+
+- Invalid signature: 401 or 403, and do not store the body as a trusted event. You may log the rejection id.
+- Unknown resource: 200 after you record the event as ignored, or 404 if the provider treats 404 as "do not retry" and you are sure the resource will never exist. Prefer recording it and fetching. A retry storm from a 500 is worse than an ignored row you can inspect.
+- Database down: 503 so the sender retries. The unique key makes the retry safe.
+- Handler bug after a durable store: leave the row unapplied and retry the worker. Do not ask the sender to redeliver once you have the bytes, unless you failed to store them.
+
+## WooCommerce receivers
+
+WooCommerce signs `base64(hmac_sha256(secret, raw_body))`. The secret is passed through `wp_specialchars_decode( $secret, ENT_QUOTES )` before the MAC. `decodeWebhookSecret()` in the checker matches that decode.
+
+```bash
+WEBHOOK_SECRET="..." node scripts/verify-hmac-signature.mjs \
+  --body payload.json \
+  --signature "$SIGNATURE"
+```
+
+You can pass `--secret-file` instead of the environment variable. The checker does not print the secret.
+
+`X-WC-Webhook-Delivery-ID` is a new log id per attempt. Dedupe on the resource id plus `date_modified_gmt` and the topic, then fetch `/wp-json/wc/v3/orders/<id>` if the payload is not enough.
+
+The activation ping is not an order event. Return 2xx and do not create an order.
+
+WooCommerce counts a delivery as failed when the status is outside `2xx`, `301`, and `302`. After more than five consecutive failures it disables the webhook. The threshold filter is `woocommerce_max_webhook_delivery_failures` (default 5). `WC_Webhook::deliver()` posts with redirects disabled, so a 301 does not mean the JSON was delivered to the next URL. Answer on the registered URL.
+
+There is no separate backoff retry of one payload described here. Timeouts and repeated order saves still deliver more than once. Handle duplicates anyway.
+
+## Gotchas
+
+- Parsing JSON and signing `JSON.stringify(object)` will not match. The sender signed the original bytes, including key order and spacing.
+- Returning 200 before the inbox write loses the event if the process dies.
+- Applying events in arrival order without a version can reopen a canceled order.
+- Logging the raw body of a payment webhook can capture data you did not mean to keep. Store the body in the inbox with restricted access, and keep card data out of application logs.
+- A shared webhook secret across shops makes a signature from shop A valid on shop B. Use one secret per subscription.
+
+## Verification
+
+- The checker accepts a known body and secret and rejects a one-byte change.
+- A duplicated delivery creates one inbox row and one state change.
+- An older event received after a newer one does not downgrade a paid order.
+- A wrong amount does not mark the order paid.
+- Stopping the database makes the handler return a retryable status and, after recovery, the redelivered event still applies once.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/order-and-webhook-reliability/evals/examples/dedupe-resource-version.md

@@ -0,0 +1,3 @@
+Store the topic, the order id, and `date_modified_gmt` as the inbox key.
+
+A repeat with the same version is acknowledged and not applied again. Fetch the order when the payload is older than the row you already stored.

package/skills/order-and-webhook-reliability/evals/examples/verify-raw-body.md

@@ -0,0 +1,3 @@
+Sign the comparison with the original raw body.
+
+Compute Base64 HMAC-SHA256 over those bytes with the webhook secret. Parse JSON only after the signature matches, and compare with a constant-time check.

package/skills/order-and-webhook-reliability/evals/tasks.json

@@ -0,0 +1,29 @@
+{
+  "tasks": [
+    {
+      "id": "verify-raw-body",
+      "task": "Verify a WooCommerce webhook signature against the exact posted bytes before parsing the JSON.",
+      "expects": {
+        "must_include": [
+          "raw body",
+          "HMAC-SHA256"
+        ],
+        "must_not_include": [
+          "JSON.stringify"
+        ]
+      }
+    },
+    {
+      "id": "dedupe-resource-version",
+      "task": "Dedupe an order.updated webhook when WooCommerce delivers it more than once.",
+      "expects": {
+        "must_include": [
+          "date_modified_gmt"
+        ],
+        "must_not_include": [
+          "X-WC-Webhook-Delivery-ID"
+        ]
+      }
+    }
+  ]
+}

package/skills/order-and-webhook-reliability/references/woocommerce-webhooks.md

@@ -0,0 +1,58 @@
+# WooCommerce webhook delivery
+
+Source of this note: WooCommerce webhook documentation and `WC_Webhook::deliver()`. Confirm header names against the shop's WooCommerce version when you debug a live miss.
+
+## Request
+
+- Method: `POST`
+- Content type: `application/json`
+- Body: the REST representation of the resource, or a ping payload when the webhook is first activated
+- User-Agent contains `WooCommerce` and `Hookshot`. Do not authenticate with the User-Agent.
+
+Headers:
+
+| Header | Role |
+| --- | --- |
+| `X-WC-Webhook-Source` | Store home URL. |
+| `X-WC-Webhook-Topic` | For example `order.updated`. |
+| `X-WC-Webhook-Resource` | For example `order`. |
+| `X-WC-Webhook-Event` | For example `updated`. |
+| `X-WC-Webhook-Signature` | Base64 HMAC-SHA256 of the raw body. |
+| `X-WC-Webhook-ID` | Webhook id. |
+| `X-WC-Webhook-Delivery-ID` | This attempt's log id. Not stable across attempts. |
+
+The signature is computed after JSON encoding. The hash algorithm filter is `woocommerce_webhook_hash_algorithm` and defaults to `sha256`. If a shop changes that filter, a receiver that always uses SHA-256 will reject valid deliveries. Prefer leaving the filter at the default.
+
+The secret is the webhook's configured secret. If the secret was left empty, WooCommerce uses the current API user's consumer secret. Set an explicit secret when you register the webhook.
+
+## Signature check
+
+```js
+import { verifyWooCommerceSignature } from "../scripts/verify-hmac-signature.mjs";
+
+const result = verifyWooCommerceSignature({
+  secret,
+  rawBody,
+  signature: headerValue,
+});
+```
+
+`rawBody` is a Buffer or string of the exact POST body. `decodeWebhookSecret()` decodes `"`, `'`, `'`, `<`, `>`, and `&` to match `wp_specialchars_decode( $secret, ENT_QUOTES )`.
+
+## Success and automatic disable
+
+WooCommerce treats `2xx`, `301`, and `302` as success. Other statuses add to the consecutive failure count. The webhook is disabled after more than five consecutive failures. Filter: `woocommerce_max_webhook_delivery_failures`, default `5`.
+
+Disabled webhooks stay disabled until someone sets them back to active. A receiver outage that returns 500 long enough will stop delivery until the merchant notices. Return 2xx once the event is durable, and do slow work afterward.
+
+`deliver()` sets HTTP redirection to 0. Do not put a redirect on the delivery URL and expect the body to be posted to the target.
+
+## Ping
+
+Saving an active webhook sends a ping. Treat a body that is only a webhook probe as a health check. Acknowledge it. Do not require an order id.
+
+## Topics
+
+Resource topics include `order.created`, `order.updated`, `order.deleted`, `product.created`, `product.updated`, `product.deleted`, `customer.created`, `customer.updated`, and the coupon equivalents. `order.updated` fires for many status and meta changes. Your handler has to tolerate repeats with a newer `date_modified_gmt`.
+
+Deleted resources may arrive after your local copy is already gone. Record the delete and return 2xx.

package/skills/order-and-webhook-reliability/scripts/verify-hmac-signature.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+/**
+ * WooCommerce signs the raw JSON body with HMAC-SHA256 and Base64.
+ * The secret is passed through wp_specialchars_decode( $secret, ENT_QUOTES )
+ * before hashing. decodeWebhookSecret matches that decode.
+ */
+export function decodeWebhookSecret(secret) {
+  return secret
+    .replaceAll(""", '"')
+    .replaceAll("'", "'")
+    .replaceAll("'", "'")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&amp;", "&");
+}
+
+export function woocommerceSignature(secret, rawBody) {
+  const key = decodeWebhookSecret(secret);
+  return createHmac("sha256", key).update(rawBody).digest("base64");
+}
+
+export function signaturesMatch(expected, received) {
+  if (typeof expected !== "string" || typeof received !== "string") {
+    return false;
+  }
+  const left = Buffer.from(expected);
+  const right = Buffer.from(received);
+  if (left.length === 0 || left.length !== right.length) {
+    return false;
+  }
+  return timingSafeEqual(left, right);
+}
+
+export function verifyWooCommerceSignature({ secret, rawBody, signature }) {
+  const expected = woocommerceSignature(secret, rawBody);
+  return {
+    ok: signaturesMatch(expected, signature),
+    expected,
+  };
+}
+
+function readOption(name) {
+  const index = process.argv.indexOf(name);
+  if (index === -1 || !process.argv[index + 1]) {
+    return undefined;
+  }
+  return process.argv[index + 1];
+}
+
+const isCli = process.argv[1] && process.argv[1].endsWith("verify-hmac-signature.mjs");
+if (isCli) {
+  const bodyPath = readOption("--body");
+  const signature = readOption("--signature");
+  const secretFile = readOption("--secret-file");
+  const secret = secretFile ? (await readFile(secretFile, "utf8")).replace(/\r?\n$/, "") : process.env.WEBHOOK_SECRET;
+
+  if (!bodyPath || !signature || !secret) {
+    console.error(
+      "Usage: node verify-hmac-signature.mjs --body payload.json --signature <base64> (--secret-file secret.txt | WEBHOOK_SECRET=...)",
+    );
+    process.exit(2);
+  }
+
+  const rawBody = await readFile(bodyPath);
+  const result = verifyWooCommerceSignature({
+    secret,
+    rawBody,
+    signature,
+  });
+  if (!result.ok) {
+    console.error("Signature mismatch.");
+    process.exit(1);
+  }
+  console.log("Signature matches.");
+}

package/skills/payment-gateway-integration/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: payment-gateway-integration
+description: "Integrate a payment provider with idempotent charges, signature-checked webhooks, and an explicit map from provider states to order states. Use when adding or changing checkout payment, capture, refund, or payment notification handling."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Payment gateway integration
+
+Apply this skill to any provider: card acquirer, wallet, bank redirect, or buy-now-pay-later. The WooCommerce class layout is in [the WooCommerce gateway notes](references/woocommerce-gateway.md). Read it when the store runs WooCommerce. The webhook inbox, signature check, and retries are in the order and webhook skill.
+
+## Procedure
+
+1. Keep card entry on the provider. Use hosted fields, a redirect, or a native wallet. Do not post the PAN or CVV to the merchant server and do not store them. Taking card data on the merchant server changes the store's PCI scope.
+2. Create the shop order before redirecting or confirming, with a status that means unpaid (`pending` or the platform's equivalent).
+3. Send the charge with an idempotency key tied to that order and attempt. Reuse the key if the HTTP call times out. Generate a new key only when the shopper starts a new attempt.
+4. Treat the browser return URL as a hint. Mark the order paid only from a signed server notification or from a server-side retrieve of the provider payment.
+5. Compare amount and currency in minor units on the server. Reject a notification whose amount or currency does not match the order.
+6. Record the provider payment id once. A second notification for the same payment id must not capture, email, or decrement stock again.
+7. Map provider states through one table. Do not sprinkle status writes through the client and the webhook.
+
+## State map
+
+Use one function from provider event to shop transition.
+
+| Provider observation | Shop effect |
+| --- | --- |
+| Authorized, not captured | Leave the order unpaid or set the platform's on-hold equivalent. Store the authorization id. |
+| Captured or paid | Mark paid through the platform's payment-complete path. Store the capture id. |
+| Pending asynchronous payment | On hold. Do not empty the cart until the policy says the order is accepted. |
+| Declined or failed | Failed. Keep the cart so the shopper can retry. |
+| Canceled by the shopper | Cancel only if the order is still unpaid. |
+| Refunded, full or partial | Create a refund record for the amount. Do not only change the status string. |
+| Chargeback or dispute opened | Record a dispute flag. Do not automatically refund unless the shop's policy says so. |
+
+Unknown states are logged and left unchanged. Do not default an unknown state to paid.
+
+## Idempotency
+
+- The provider idempotency key is a stable string for one attempt, such as `order-{id}-attempt-{n}`.
+- Persist `attempt -> provider payment id` before you depend on the response, or immediately after the first success, inside a unique constraint when the database allows it.
+- The webhook uniqueness key is the provider event id when that id is stable across retries. A delivery attempt id that changes on every POST is not enough.
+- If the notification arrives before your create call returns, the webhook must be able to find the order by the idempotency key or by metadata you sent to the provider.
+
+## Amounts
+
+Convert the shop total to integer minor units with the currency's exponent (`100` for a two-decimal currency, `1` for a zero-decimal currency). Read the exponent from the store or from the provider's currency table. Do not compare PHP floats.
+
+Reject the notification when the paid minor units differ from the order total. A mismatch is an exception for a person, not an automatic partial capture, unless the product explicitly sells partial payments.
+
+## Browser return
+
+The return URL may include a payment id. Use it only to look up the provider payment from your server. Ignore `status=success` query parameters. A shopper, or a third party, can send those.
+
+Show a pending confirmation when the webhook has not arrived yet. Poll your own order record, or retrieve the payment once from the provider. Do not poll the provider in a tight loop from the browser.
+
+## Refunds
+
+- Refund from the shop admin through the provider API. Do not ask staff to refund only in the provider dashboard unless the shop has a reconciliation job that pulls those refunds back.
+- Send an idempotency key per refund attempt.
+- Store the provider refund id on the shop refund record.
+- A partial refund leaves the order paid for the remainder. A full refund uses the platform's refunded state after the provider confirms it.
+
+## Secrets and logs
+
+- Webhook secrets and API keys stay in the server environment.
+- Log the order id, provider payment id, event id, and your decision. Do not log the PAN, CVV, full card number, or the webhook secret.
+- Verify signatures on the raw body of the request before parsing. The order and webhook skill includes a WooCommerce HMAC checker. For other providers, follow that provider's documented MAC and compare with a constant-time compare.
+
+## Gotchas
+
+- Emptying the cart before the provider confirms payment loses the shopper's items when they abandon the redirect.
+- Marking paid inside the browser return, and again in the webhook, sends two receipts and can reduce stock twice. The paid transition has to be idempotent.
+- Trusting the amount in the client payload lets a modified request pay a different total than the order.
+- A `200` to the provider means you stored the event, not that you have already fulfilled the order. Fulfillment can run after the response if the event is durable. A `4xx` for a signature failure is appropriate. A `5xx` asks the provider to retry, so the handler must tolerate a duplicate.
+- Test the failed, canceled, and duplicate paths. A sandbox success charge is not coverage.
+
+## Verification
+
+- Two identical charge requests with the same idempotency key create one provider payment.
+- A replayed signed webhook does not send a second receipt or reduce stock again.
+- A signed webhook with the wrong amount does not mark the order paid.
+- A forged browser return without a matching provider payment does not mark the order paid.
+- A declined payment returns the shopper to checkout with the cart intact and the order not paid.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/payment-gateway-integration/evals/examples/confirmed-capture.md

@@ -0,0 +1,9 @@
+Confirm capture through the payment-complete path.
+
+```php
+if ( ! $order->is_paid() ) {
+    $order->payment_complete( $transaction_id );
+}
+```
+
+Do not treat the browser return query as proof that the capture succeeded.

package/skills/payment-gateway-integration/evals/examples/replayed-webhook.md

@@ -0,0 +1,3 @@
+Verify the signature over the raw body, then ignore a duplicate.
+
+Store the provider payment id. If that id is already on the order, return 200 without a second capture. Use the same idempotency key when the original charge request times out.

package/skills/payment-gateway-integration/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "confirmed-capture",
+      "task": "Mark a WooCommerce order paid only after the provider confirms the capture, and store the transaction id.",
+      "expects": {
+        "must_include": [
+          "payment_complete",
+          "$transaction_id"
+        ],
+        "must_not_include": [
+          "add_post_meta"
+        ]
+      }
+    },
+    {
+      "id": "replayed-webhook",
+      "task": "Apply a signed payment webhook once when the provider retries the same captured payment.",
+      "expects": {
+        "must_include": [
+          "idempotency",
+          "raw body"
+        ],
+        "must_not_include": [
+          "status=success"
+        ]
+      }
+    }
+  ]
+}