@sadrmanesh/commerce-agent-skills 0.3.0 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -0
- package/README.md +4 -2
- package/package.json +1 -1
- package/rules/order-and-webhook-reliability.md +1 -0
- package/skills/b2b-pricing/SKILL.md +1 -1
- package/skills/catalog-import-and-migration/SKILL.md +1 -1
- package/skills/checkout-ux-and-conversion/SKILL.md +1 -1
- package/skills/conversion-event-tracking/SKILL.md +1 -1
- package/skills/ecommerce-seo-structured-data/SKILL.md +1 -1
- package/skills/fraud-and-risk-basics/SKILL.md +1 -1
- package/skills/google-merchant-product-feeds/SKILL.md +1 -1
- package/skills/headless-nextjs-storefront/SKILL.md +1 -1
- package/skills/inventory-and-multi-warehouse/SKILL.md +1 -1
- package/skills/iranian-payment-gateways/SKILL.md +1 -1
- package/skills/marketplace-search-and-ranking/SKILL.md +1 -1
- package/skills/mcp-store-tooling/SKILL.md +1 -1
- package/skills/multi-vendor-payouts/SKILL.md +1 -1
- package/skills/order-and-webhook-reliability/SKILL.md +5 -1
- package/skills/order-and-webhook-reliability/evals/examples/redelivery-after-timeout.md +3 -0
- package/skills/order-and-webhook-reliability/evals/tasks.json +15 -0
- package/skills/payment-gateway-integration/SKILL.md +1 -1
- package/skills/product-catalog-modeling/SKILL.md +1 -1
- package/skills/product-description-guardrails/SKILL.md +1 -1
- package/skills/returns-and-refunds/SKILL.md +1 -1
- package/skills/rtl-and-persian-localization/SKILL.md +1 -1
- package/skills/shopify-app-development/SKILL.md +1 -1
- package/skills/storefront-accessibility/SKILL.md +1 -1
- package/skills/storefront-performance/SKILL.md +1 -1
- package/skills/stripe-payments/SKILL.md +1 -1
- package/skills/subscription-billing/SKILL.md +1 -1
- package/skills/tax-and-shipping/SKILL.md +1 -1
- package/skills/vector-product-search/SKILL.md +1 -1
- package/skills/woocommerce-plugin-development/SKILL.md +1 -1
- package/skills/woocommerce-rest-api/SKILL.md +1 -1
- package/skills/wordpress-plugin-security/SKILL.md +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,30 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [Unreleased]
|
|
4
|
+
|
|
5
|
+
## [0.3.2] - 2026-10-31
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- A `redelivery-after-timeout` eval task and worked example for `order-and-webhook-reliability`. The handler stored and applied the event, the sender timed out before the 2xx arrived and redelivered, and the answer must return 2xx without repeating a side effect such as a second fulfillment, email, or stock decrement. The skill explains this case, its verification list and gotchas cover it, and the rule has a matching line.
|
|
10
|
+
- The skills, rules, and evaluation tasks as a Hugging Face dataset, <https://huggingface.co/datasets/sadrmanesh/commerce-agent-skills>, with a `skills` table, an `evals` table, and the installable folders. The README, the docs home page, and the installation guide link to it.
|
|
11
|
+
- `.github/workflows/mirror.yml`, which mirrors `main` and tags to `gitlab.com/sadrmanesh/commerce-agent-skills` when the `GITLAB_TOKEN` secret is set, and skips cleanly otherwise.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- The package and every skill are now version 0.3.2.
|
|
16
|
+
|
|
17
|
+
## [0.3.1] - 2026-10-30
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
|
|
21
|
+
- The release workflow publishes `@sadrmanesh/commerce-agent-skills` to GitHub Packages after npm, using the workflow's `GITHUB_TOKEN`. npmjs.com remains the main registry.
|
|
22
|
+
- Install docs for GitHub Packages, with the `.npmrc` scope entry, in the installation guide and the README.
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
|
|
26
|
+
- The package and every skill are now version 0.3.1.
|
|
27
|
+
|
|
3
28
|
## [0.3.0] - 2026-10-30
|
|
4
29
|
|
|
5
30
|
### Added
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Skills and rules for AI coding agents that build e-commerce and marketplace products.
|
|
4
4
|
|
|
5
|
-
**Documentation:** <https://sadrmanesh.github.io/commerce-agent-skills/>
|
|
5
|
+
**Documentation:** <https://sadrmanesh.github.io/commerce-agent-skills/> · **Dataset:** [Hugging Face](https://huggingface.co/datasets/sadrmanesh/commerce-agent-skills)
|
|
6
6
|
|
|
7
7
|
The skills follow the [Agent Skills](https://agentskills.io/specification) format: a folder, a `SKILL.md` file with `name` and `description`, and optional reference files and scripts. An agent that supports that format can load them. The format does not name an install path. [Installation](docs/installation.md) explains how to point your agent at these folders.
|
|
8
8
|
|
|
@@ -72,6 +72,8 @@ npx @sadrmanesh/commerce-agent-skills init --skills-dir path/to/skills --rules-d
|
|
|
72
72
|
|
|
73
73
|
`init` skips skills that are already installed, `--force` replaces them, and `--dry-run` shows what would be written. From a checkout, `node bin/commerce-agent-skills.mjs` takes the same arguments. Details are in [docs/installation.md](docs/installation.md) and [docs/cli.md](docs/cli.md).
|
|
74
74
|
|
|
75
|
+
The package is on npmjs.com and, with the same name, on GitHub Packages. npmjs.com is the default; [docs/installation.md](docs/installation.md#install-from-github-packages) has the `.npmrc` lines for GitHub Packages.
|
|
76
|
+
|
|
75
77
|
## Work on the library
|
|
76
78
|
|
|
77
79
|
Clone the repository and check the skills:
|
|
@@ -113,7 +115,7 @@ The skill format is documented in [docs/skill-format.md](docs/skill-format.md).
|
|
|
113
115
|
|
|
114
116
|
The documentation lives at [sadrmanesh.github.io/commerce-agent-skills](https://sadrmanesh.github.io/commerce-agent-skills/). It is built with MkDocs Material, and the skill, rule, and guide pages are generated from this repository by `scripts/build-docs.mjs`, so they always match the files here. `.github/workflows/pages.yml` deploys it on pushes to `main`. See [docs/github-pages.md](docs/github-pages.md).
|
|
115
117
|
|
|
116
|
-
`.github/workflows/release.yml` runs when a `vX.Y.Z` tag is pushed. It checks that the tag matches `package.json`, runs the validator, evals, and tests, creates the GitHub release if it does not exist, and publishes `@sadrmanesh/commerce-agent-skills` to npm
|
|
118
|
+
`.github/workflows/release.yml` runs when a `vX.Y.Z` tag is pushed. It checks that the tag matches `package.json`, runs the validator, evals, and tests, creates the GitHub release if it does not exist, and publishes `@sadrmanesh/commerce-agent-skills` to npm and to GitHub Packages, which uses the workflow's `GITHUB_TOKEN`. Running it by hand with a version tags that version first.
|
|
117
119
|
|
|
118
120
|
## Roadmap
|
|
119
121
|
|
package/package.json
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
- Fetch the order or payment when the event is out of order or incomplete. Do not apply an older status over a newer one.
|
|
7
7
|
- Compare paid amounts in integer minor units.
|
|
8
8
|
- Make the paid transition idempotent so stock and receipt email run once.
|
|
9
|
+
- Treat a redelivery after a timeout as a duplicate: if the inbox row is already `applied`, return 2xx and run no side effect again.
|
|
9
10
|
- Write outbound webhooks from an outbox in the same transaction as the order change.
|
|
10
11
|
- Acknowledge a WooCommerce activation ping with 2xx and do not create an order from it.
|
|
11
12
|
- Return a retryable error only when the event was not stored. WooCommerce disables a webhook after more than five consecutive failures.
|
|
@@ -5,7 +5,7 @@ license: MIT
|
|
|
5
5
|
compatibility: "The signature checker requires Node.js 20 or newer. No network access."
|
|
6
6
|
metadata:
|
|
7
7
|
author: Naser Sadrmanesh
|
|
8
|
-
version: "0.3.
|
|
8
|
+
version: "0.3.2"
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
# Order and webhook reliability
|
|
@@ -34,6 +34,8 @@ Do not dedupe only on a delivery attempt id. Those change when the sender times
|
|
|
34
34
|
|
|
35
35
|
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.
|
|
36
36
|
|
|
37
|
+
The most common duplicate is a redelivery after a timeout. The handler stored and applied the event, but the sender timed out before the 2xx arrived and posts the same event again, often with a new delivery id. The retry must find the inbox row already `applied`, return 2xx, and run no side effect: no second fulfillment, no second confirmation email, no second stock decrement. This only holds when each side effect is recorded in the same transaction that marks the row `applied`, or is keyed on the event id where it runs.
|
|
38
|
+
|
|
37
39
|
## Apply rules
|
|
38
40
|
|
|
39
41
|
- Compare amounts in integer minor units before marking an order paid.
|
|
@@ -82,6 +84,7 @@ There is no separate backoff retry of one payload described here. Timeouts and r
|
|
|
82
84
|
|
|
83
85
|
- Parsing JSON and signing `JSON.stringify(object)` will not match. The sender signed the original bytes, including key order and spacing.
|
|
84
86
|
- Returning 200 before the inbox write loses the event if the process dies.
|
|
87
|
+
- A slow handler that applies the event and sends the email before answering invites a timeout, and the redelivery sends the email again unless the email is tied to the `applied` row.
|
|
85
88
|
- Applying events in arrival order without a version can reopen a canceled order.
|
|
86
89
|
- 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.
|
|
87
90
|
- A shared webhook secret across shops makes a signature from shop A valid on shop B. Use one secret per subscription.
|
|
@@ -90,6 +93,7 @@ There is no separate backoff retry of one payload described here. Timeouts and r
|
|
|
90
93
|
|
|
91
94
|
- The checker accepts a known body and secret and rejects a one-byte change.
|
|
92
95
|
- A duplicated delivery creates one inbox row and one state change.
|
|
96
|
+
- A redelivery after a sender timeout, where the first attempt was stored and applied but the 2xx never arrived, returns 2xx and repeats no side effect: one fulfillment, one email, one stock decrement.
|
|
93
97
|
- An older event received after a newer one does not downgrade a paid order.
|
|
94
98
|
- A wrong amount does not mark the order paid.
|
|
95
99
|
- Stopping the database makes the handler return a retryable status and, after recovery, the redelivered event still applies once.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
Treat the retry after a timeout as a duplicate of an event you already applied.
|
|
2
|
+
|
|
3
|
+
Look up the inbox row by topic, order id, and `date_modified_gmt`. When its status is already `applied`, return 2xx with the original result and run no side effect: no second fulfillment, no second confirmation email, and no second stock decrement. Record the fulfillment, the email, and the stock change in the same transaction that marks the row `applied`, so the first attempt either did all of them once or none of them.
|
|
@@ -24,6 +24,21 @@
|
|
|
24
24
|
"X-WC-Webhook-Delivery-ID"
|
|
25
25
|
]
|
|
26
26
|
}
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"id": "redelivery-after-timeout",
|
|
30
|
+
"task": "The order.paid handler stored and applied the event and created the fulfillment, but WooCommerce timed out before the 2xx arrived and posted the same event again. Make the retry safe.",
|
|
31
|
+
"expects": {
|
|
32
|
+
"must_include": [
|
|
33
|
+
"applied",
|
|
34
|
+
"2xx",
|
|
35
|
+
"side effect",
|
|
36
|
+
"timeout"
|
|
37
|
+
],
|
|
38
|
+
"must_not_include": [
|
|
39
|
+
"X-WC-Webhook-Delivery-ID"
|
|
40
|
+
]
|
|
41
|
+
}
|
|
27
42
|
}
|
|
28
43
|
]
|
|
29
44
|
}
|