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

package/skills/product-description-guardrails/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "facts-only",
+      "task": "Write a cotton shirt description that states only the catalog facts and the real price.",
+      "expects": {
+        "must_include": [
+          "19.00 USD",
+          "cotton"
+        ],
+        "must_not_include": [
+          "clinically proven"
+        ]
+      }
+    },
+    {
+      "id": "label-generated",
+      "task": "Mark a generated Merchant Center description so it is not submitted as a human-written description attribute.",
+      "expects": {
+        "must_include": [
+          "trained_algorithmic_media",
+          "structured_description"
+        ],
+        "must_not_include": [
+          "organic cotton"
+        ]
+      }
+    }
+  ]
+}

package/skills/product-description-guardrails/references/claims.md

@@ -0,0 +1,24 @@
+# Claims the description checker refuses
+
+The checker is a lexical guard, not a review of advertising law. Merchants still need their own review for regulated goods.
+
+Refused unless the same phrase is listed in `allowedClaims`:
+
+- `cure` and `cures`
+- `clinically proven`
+- `guaranteed to`
+- `100% effective`
+- `risk-free`
+
+Prices must match `/^(\d+\.\d{2}) ([A-Z]{3})$/` against the source. `19.00 USD` matches a source price of `19.00` and currency `USD`. `$19.00` is ignored by this pattern. Do not rely on that gap. The writer still must not invent a dollar amount.
+
+## Merchant Center labeling
+
+| How the text was produced | Attribute |
+| --- | --- |
+| Written or translated by a person from the catalog | `title`, `description` |
+| Generated | `structured_title` or `structured_description` with `digital_source_type` `trained_algorithmic_media` |
+
+Omitting `digital_source_type` means Google treats the structured value as `default` (not generated). Do not omit it for generated text.
+
+Lengths from the product data specification: title content at most 150 characters, description content at most 5000.

package/skills/product-description-guardrails/scripts/check-description.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const REFUSED = [
+  { label: "cure", pattern: /\bcures?\b/i },
+  { label: "clinically proven", pattern: /\bclinically proven\b/i },
+  { label: "guaranteed to", pattern: /\bguaranteed to\b/i },
+  { label: "100% effective", pattern: /\b100% effective\b/i },
+  { label: "risk-free", pattern: /\brisk[- ]free\b/i },
+];
+
+export function checkProductDescription(description, source) {
+  const errors = [];
+  if (typeof description !== "string" || description.trim() === "") {
+    return ["Description is empty."];
+  }
+  if (description.length > 5000) {
+    errors.push(`Description is ${description.length} characters; the maximum is 5000.`);
+  }
+  if (!source || typeof source.price !== "string" || typeof source.currency !== "string") {
+    errors.push("Source price and currency are required.");
+    return errors;
+  }
+  const allowed = Array.isArray(source.allowedClaims) ? source.allowedClaims.join("\n") : "";
+  for (const rule of REFUSED) {
+    if (rule.pattern.test(description) && !rule.pattern.test(allowed)) {
+      errors.push(`Unsupported claim: ${rule.label}`);
+    }
+  }
+  for (const match of description.matchAll(/(\d+\.\d{2})\s+([A-Z]{3})/g)) {
+    if (match[1] !== source.price || match[2] !== source.currency) {
+      errors.push(`Price ${match[1]} ${match[2]} does not match ${source.price} ${source.currency}.`);
+    }
+  }
+  return errors;
+}
+
+function readOption(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+const isCli = process.argv[1] && process.argv[1].endsWith("check-description.mjs");
+if (isCli) {
+  const descriptionFile = readOption("--description");
+  const sourceFile = readOption("--source");
+  if (!descriptionFile || !sourceFile) {
+    console.error("Usage: node check-description.mjs --description copy.txt --source source.json");
+    process.exit(2);
+  }
+  const description = await readFile(descriptionFile, "utf8");
+  const source = JSON.parse(await readFile(sourceFile, "utf8"));
+  const errors = checkProductDescription(description, source);
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`ERROR ${error}`);
+    }
+    process.exit(1);
+  }
+  console.log("Description passed the local checks.");
+}

package/skills/returns-and-refunds/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: returns-and-refunds
+description: "Run returns as a tracked RMA from request to inspection, refund only what the policy and payment allow, and restock only inspected items. Use when building a returns portal, refund rules, exchanges, store credit, or restocking after a return."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Returns and refunds
+
+A return is a small workflow with its own record, not a status on the order. Keep the return, the refund, and the stock movement separate, and link them. Statuses and the refund calculation are in [the RMA notes](references/rma-states.md).
+
+## Procedure
+
+1. Create a return record (an RMA) with the order, the lines and quantities, the reason, and the requested outcome: refund, exchange, or store credit.
+2. Check eligibility on the server: the return window from the delivery date, the product's returnable flag, quantities not already returned, and final-sale items.
+3. Approve or reject with a reason. Approval issues return instructions or a label.
+4. When the parcel arrives, inspect each line and record the condition: resellable, damaged, or missing.
+5. Refund from the inspection result, not from the request. Use the refund calculation in the notes.
+6. Restock only resellable units, as a `return` stock movement. Damaged units go to a separate location or are written off.
+7. Close the return. The order shows refunded amounts and return history but keeps its original lines.
+
+## Refunding
+
+- Refund through the original payment method, using the gateway's refund API and an idempotency key per refund. Store the provider refund id.
+- The total refunded on an order can never exceed what was captured. Check the sum of earlier refunds first.
+- Refund tax in proportion to the refunded lines. Refund shipping only when the policy says so, such as for a wrong or damaged item.
+- A partial refund leaves the order paid for the rest. Use the platform's refunded status only when everything is refunded.
+- Store credit is a liability. Record it in a ledger with an expiry if the law allows one, not as a negative order.
+- In WooCommerce, create refunds with `wc_create_refund()` or `POST /wp-json/wc/v3/orders/{id}/refunds`. Set `api_refund` to `true` only when the gateway should return the money; otherwise it is a manual refund record.
+
+## Exchanges
+
+An exchange is a return plus a new order for the replacement, linked to the return. Reserve the replacement when the exchange is approved so it does not sell out while the parcel is in transit. Charge or refund the price difference on the new order.
+
+## Gotchas
+
+- Restocking at approval puts units that never come back, or come back broken, on sale.
+- Refunding at request time pays out for parcels that never arrive.
+- A refund that is created only in the payment provider's dashboard leaves the shop showing the order as fully paid. Import provider refunds by webhook.
+- Two staff members refunding the same line at once can exceed the captured amount. Lock the order or check the refund total inside the transaction.
+- Some laws give a minimum withdrawal period for distance sales, such as 14 days in the EU. The store's window cannot be shorter for those customers.
+
+## Verification
+
+- A return outside the window is refused with the reason shown.
+- A line cannot be returned twice beyond its purchased quantity.
+- A damaged unit is refunded per policy but not added to sellable stock.
+- The sum of refunds never exceeds the captured amount, even with two concurrent requests.
+- A partial refund leaves the order paid, with the refunded amount shown.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/returns-and-refunds/evals/examples/refund-after-inspection.md

@@ -0,0 +1,3 @@
+Approve the return for two mugs and wait for the parcel. Nothing is refunded or restocked at approval.
+
+When it arrives, inspect each unit. The intact mug is resellable: refund its paid price and tax and restock it with a `return` movement. The broken mug is damaged: if it broke in transit or was faulty, refund it per policy, but move it to a damaged location instead of sellable stock. The third mug stays with the shopper and the order stays paid for it.

package/skills/returns-and-refunds/evals/examples/woocommerce-partial-refund.md

@@ -0,0 +1,3 @@
+Send `POST /wp-json/wc/v3/orders/{id}/refunds` with the `line_items` entry for that line, its `refund_total` and `refund_tax`, the summed `amount`, and `api_refund: true` so the gateway returns the money.
+
+This is a partial refund. WooCommerce keeps the order processing or completed and shows the refunded amount. Check that earlier refunds plus this one do not exceed the order total before you send it.

package/skills/returns-and-refunds/evals/tasks.json

@@ -0,0 +1,20 @@
+{
+  "tasks": [
+    {
+      "id": "refund-after-inspection",
+      "task": "A shopper returns two of three mugs. One arrives broken. Explain what is refunded, what is restocked, and when.",
+      "expects": {
+        "must_include": ["inspect", "resellable", "damaged", "restock"],
+        "must_not_include": ["restock both at approval"]
+      }
+    },
+    {
+      "id": "woocommerce-partial-refund",
+      "task": "Refund one line of a WooCommerce order through the payment gateway and keep the order paid for the rest.",
+      "expects": {
+        "must_include": ["orders/{id}/refunds", "api_refund", "partial"],
+        "must_not_include": ["set the order status to refunded"]
+      }
+    }
+  ]
+}

package/skills/returns-and-refunds/references/rma-states.md

@@ -0,0 +1,37 @@
+# RMA states and refund calculation
+
+## States
+
+| State | Next | Notes |
+| --- | --- | --- |
+| `requested` | `approved`, `rejected` | Created by the shopper or staff |
+| `approved` | `in_transit`, `canceled` | Instructions or label issued. Reserve exchange items here. |
+| `in_transit` | `received` | Carrier tracking attached |
+| `received` | `inspected` | Parcel arrived |
+| `inspected` | `refunded`, `exchanged`, `credited`, `rejected` | Condition recorded per line |
+| `refunded`, `exchanged`, `credited`, `rejected`, `canceled` | none | Final |
+
+Only move forward. Record who changed the state and when.
+
+## Refund calculation
+
+For each inspected line:
+
+```text
+line_refund = unit_price_paid * accepted_quantity
+            - restocking_fee (if the policy has one and the item was not faulty)
+tax_refund  = line_tax_paid * accepted_quantity / purchased_quantity
+```
+
+- `unit_price_paid` is after discounts. An order-level coupon is spread across lines in proportion to their price, the same way the order calculated it.
+- Add shipping only for faulty or wrong items, or when the whole order is returned and the policy refunds shipping.
+- Round each line in minor units, then add. Cap the total at `captured - already_refunded`.
+
+## Records
+
+| Record | Holds |
+| --- | --- |
+| Return | order id, lines, quantities, reason, state, outcome |
+| Inspection | line, condition, notes, photos, inspector |
+| Refund | amount, tax, shipping, provider refund id, status |
+| Stock movement | `return` into a sellable or quarantine location |

package/skills/rtl-and-persian-localization/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: rtl-and-persian-localization
+description: "Localize a storefront for Persian (fa_IR) and right-to-left layout: logical CSS, digits, Yeh and Kaf, ZWNJ, currency display, and Gregorian storage. Use when building or reviewing Persian, Farsi, or RTL commerce UI."
+license: MIT
+compatibility: "The Persian normalizer requires Node.js 20 or newer. No network access."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# RTL and Persian localization
+
+Use this skill for a Persian storefront or any right-to-left commerce UI. Search matching uses the marketplace search skill. The normalizer in [`scripts/normalize-persian.mjs`](scripts/normalize-persian.mjs) is for display and for search text. Letter and digit rules are in [the Persian text notes](references/persian-text.md).
+
+## Procedure
+
+1. Set the document language and direction. For Persian, `lang="fa"` and `dir="rtl"`. In WordPress, the `fa_IR` locale is RTL and `is_rtl()` is the check to use in PHP.
+2. Lay out with CSS logical properties. Do not mirror the whole page with a plugin that flips `left` and `right` in existing files.
+3. Store catalog text as Unicode with Persian Yeh and Kaf and with ZWNJ where the word needs it. Store dates as Gregorian timestamps. Store money as a decimal amount plus an ISO currency code.
+4. Format digits for display only. APIs, SKUs, payment amounts, and HTML attributes stay ASCII.
+5. Translate user-facing strings with the plugin text domain. Do not hard-code Persian in a PHP string that should go through gettext, and do not hard-code English in a template that Persian shoppers see.
+
+## Direction
+
+- Prefer `margin-inline-start`, `padding-inline`, `inset-inline-start`, `border-inline-end`, and `text-align: start`.
+- Use flex and grid. `flex-direction: row` follows the document direction. Use `row-reverse` only when the order is intentionally opposite to the language.
+- Mirror directional icons such as back and forward. Do not mirror logos, payment marks, product photos, or numbers.
+- Form focus order follows the visual order. Test with the keyboard, not only with a screenshot.
+- WooCommerce emails that render the same template need the same direction. A storefront `dir="rtl"` does not change an email that is a separate HTML document.
+
+## Persian text
+
+- Locale code: `fa_IR`.
+- Fold Arabic Yeh `ي` (U+064A) to Persian Yeh `ی` (U+06CC) and Arabic Kaf `ك` (U+0643) to Persian Kaf `ک` (U+06A9) when you normalize input. Shoppers and old content use both.
+- Keep ZWNJ (U+200C) in stored and displayed words (`می‌روم`). Search normalization may remove it so the two spellings match. Display normalization must not.
+- Persian digits `۰۱۲۳۴۵۶۷۸۹` are a display format. Also accept Arabic-Indic digits `٠١٢٣٤٥٦٧٨٩` on input and normalize them.
+- Use a font that covers Arabic script. A Latin-only stack renders Persian as missing glyphs.
+
+Run the script:
+
+```bash
+node scripts/normalize-persian.mjs --file title.txt
+node scripts/normalize-persian.mjs --search "كالاي ۱۲"
+```
+
+`--search` prints the match form. The default prints the display form and keeps ZWNJ. `--persian-digits` converts ASCII digits to Persian digits for display.
+
+## Money, dates, addresses
+
+- WooCommerce currency for the Iranian rial is the ISO code `IRR`. Format the amount with the store's decimal settings (`wc_get_price_decimals()`), not with a hard-coded exponent.
+- Toman is a display and pricing decision: 1 toman equals 10 rials. If the shop charges in toman, say that in the currency label and store a consistent unit. Do not divide amounts by 10 only in the theme while checkout charges rials.
+- WordPress and WooCommerce store order dates in Gregorian, with a site timezone and a GMT field. A Jalali calendar is a presentation layer. Do not write Jalali strings into order date columns.
+- Iranian addresses need country `IR`, province, city, street, and a 10-digit postal code. Do not require a state from a country list that has no Iranian provinces unless those provinces are actually configured. Add them through WooCommerce's country locale and state list rather than a one-off checkout hack.
+- Phone numbers: accept a local mobile number without a North American mask. Store a normalized form you can dial, and display the local form.
+
+## WordPress and WooCommerce
+
+- Put every new string in gettext with the plugin text domain. Load private translations on `init`.
+- Switch field order and labels with `woocommerce_get_country_locale` and `woocommerce_localisation_address_formats` for `IR`, not by editing core templates first.
+- `body` gets the `rtl` class from WordPress when the locale is RTL. Theme CSS should key off `dir` or `.rtl` and still prefer logical properties so the same stylesheet serves both directions.
+- Prices in templates go through `wc_price()`. That helper uses the store currency settings. Do not concatenate a hard-coded `ریال` or `$` in front of a raw number.
+
+## Gotchas
+
+- `direction: rtl` on a single inner box, while the document is LTR, traps punctuation and mixed English SKUs. Set direction on the document, and on emails, not on random cards.
+- `left` and `right` in copied CSS survive an RTL locale and pin totals to the wrong side.
+- Replacing every digit in the HTML document breaks CSS, JSON, and payment signatures. Convert digits in text nodes you control.
+- Sorting Persian with a binary code-point order is not alphabetical. Use a Persian collation when the list is a dictionary. Do not use it for SKUs.
+- Translating a string that includes the price ("Pay 19.00") needs a placeholder, not concatenation: `sprintf( __( 'Pay %s', 'example' ), $formatted )`.
+
+## Verification
+
+- `fa_IR` renders the shopper-facing checkout RTL, with the total and the pay control aligned to the inline end.
+- A title that contains Arabic Yeh and Persian digits round-trips through display normalization without losing ZWNJ.
+- Search normalization makes `كالا` and `کالا` match. The stored title is unchanged.
+- An order date stored by WooCommerce remains Gregorian. Any Jalali label is display-only.
+- A test payment uses the same major units the shopper saw. Toman and rial are not mixed inside one order.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/rtl-and-persian-localization/evals/examples/document-direction.md

@@ -0,0 +1,7 @@
+Set the document for Persian.
+
+```html
+<html lang="fa" dir="rtl">
+```
+
+Use the `fa_IR` locale so `is_rtl()` is true. Space the total with `margin-inline-start`, not a physical left margin.

package/skills/rtl-and-persian-localization/evals/examples/rial-display.md

@@ -0,0 +1,7 @@
+Format the stored amount with the store currency.
+
+```php
+echo wp_kses_post( wc_price( $amount ) );
+```
+
+The ISO code is `IRR` when the shop charges rials. Do not divide the charged amount in the template.

package/skills/rtl-and-persian-localization/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "document-direction",
+      "task": "Render the Persian storefront in the fa_IR locale with right-to-left document direction and logical CSS.",
+      "expects": {
+        "must_include": [
+          "fa_IR",
+          "dir=\"rtl\""
+        ],
+        "must_not_include": [
+          "margin-left"
+        ]
+      }
+    },
+    {
+      "id": "rial-display",
+      "task": "Show an Iranian rial price through WooCommerce formatting without converting to toman only in the theme.",
+      "expects": {
+        "must_include": [
+          "IRR",
+          "wc_price"
+        ],
+        "must_not_include": [
+          "/ 10"
+        ]
+      }
+    }
+  ]
+}

package/skills/rtl-and-persian-localization/references/persian-text.md

@@ -0,0 +1,51 @@
+# Persian text handling
+
+Use this note when you change strings, search tokens, or formatted amounts. The functions in `scripts/normalize-persian.mjs` implement the folds below.
+
+## Letters
+
+| Input | Code point | Fold to |
+| --- | --- | --- |
+| Arabic Yeh `ي` | U+064A | Persian Yeh `ی` U+06CC |
+| Persian Yeh `ی` | U+06CC | unchanged |
+| Arabic Kaf `ك` | U+0643 | Persian Kaf `ک` U+06A9 |
+| Persian Kaf `ک` | U+06A9 | unchanged |
+
+Apply this fold on input and before search. Display the folded Persian letters.
+
+ZWNJ (U+200C) is part of Persian orthography. Display and storage keep it. Search text removes it so `می‌روم` and `میروم` match. Do not replace ZWNJ with a normal space. That splits one word into two.
+
+Arabic Teh Marbuta `ة` is not a Persian letter. Do not fold it to Heh unless you have a specific migration from Arabic copy. Leave it and show it.
+
+## Digits
+
+| Glyphs | Code points | Use |
+| --- | --- | --- |
+| `0-9` | U+0030–U+0039 | APIs, SKUs, JSON, payment minor units, HTML attributes |
+| `۰-۹` | U+06F0–U+06F9 | Optional Persian display |
+| `٠-٩` | U+0660–U+0669 | Accept on input, then fold to ASCII or to Persian digits |
+
+`toAsciiDigits` maps both Persian and Arabic-Indic digits. `toPersianDigits` maps ASCII to Persian. Do not run `toPersianDigits` on a whole HTML or JSON document.
+
+## Normalization entry points
+
+- `normalizePersianDisplay(text)` folds Yeh and Kaf, keeps ZWNJ, and leaves digits unless you pass `{ digits: "persian" }` or `{ digits: "ascii" }`.
+- `normalizePersianSearch(text)` folds letters, removes ZWNJ, converts digits to ASCII, lowercases Latin letters, and collapses whitespace.
+
+Latin lowercasing is for mixed catalog titles. Persian letters have no case.
+
+## Currency display
+
+ISO 4217 code in WooCommerce: `IRR` for the Iranian rial.
+
+If the merchant prices in toman, pick one stored unit and label it. A theme-only division by 10 will not match the amount sent to the payment provider. There is no separate ISO code to assume for toman in this skill. Do not invent a code in payment requests.
+
+Format through `wc_price()` so the decimal separator and currency symbol come from WooCommerce settings.
+
+## Dates
+
+Store `date_created_gmt` as WooCommerce provides it. Format for `fa_IR` with `wp_date()` for Gregorian output in the locale. A Jalali formatter, if the shop uses one, reads that timestamp and must not write back a Jalali string.
+
+## Addresses
+
+Postal codes in Iran are 10 digits. Validate the length after converting digits to ASCII. Province names should come from the configured state list for `IR` so shipping zones and the address form agree.

package/skills/rtl-and-persian-localization/scripts/normalize-persian.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const ARABIC_YEH = /\u064A/g;
+const ARABIC_KAF = /\u0643/g;
+const PERSIAN_DIGITS = /[\u06F0-\u06F9]/g;
+const ARABIC_INDIC_DIGITS = /[\u0660-\u0669]/g;
+const ZWNJ = /\u200C/g;
+
+export function toAsciiDigits(text) {
+  return text
+    .replace(PERSIAN_DIGITS, (digit) => String(digit.charCodeAt(0) - 0x06f0))
+    .replace(ARABIC_INDIC_DIGITS, (digit) => String(digit.charCodeAt(0) - 0x0660));
+}
+
+export function toPersianDigits(text) {
+  return text.replace(/[0-9]/g, (digit) => String.fromCharCode(0x06f0 + Number(digit)));
+}
+
+function foldLetters(text) {
+  return text.normalize("NFC").replace(ARABIC_YEH, "\u06CC").replace(ARABIC_KAF, "\u06A9");
+}
+
+/** Display text: fold Arabic Yeh/Kaf to Persian, keep ZWNJ, optionally use Persian digits. */
+export function normalizePersianDisplay(text, { digits = "keep" } = {}) {
+  const folded = foldLetters(String(text));
+  if (digits === "persian") {
+    return toPersianDigits(toAsciiDigits(folded));
+  }
+  if (digits === "ascii") {
+    return toAsciiDigits(folded);
+  }
+  return folded;
+}
+
+/**
+ * Search text: fold letters, drop ZWNJ so می‌روم matches میروم, ASCII digits,
+ * and collapse whitespace. Latin letters are lowercased. Persian has no case.
+ */
+export function normalizePersianSearch(text) {
+  const folded = toAsciiDigits(foldLetters(String(text))).replace(ZWNJ, "").toLowerCase();
+  return folded.replace(/\s+/g, " ").trim();
+}
+
+const isCli = process.argv[1] && process.argv[1].endsWith("normalize-persian.mjs");
+if (isCli) {
+  const mode = process.argv.includes("--search") ? "search" : "display";
+  const fileFlag = process.argv.indexOf("--file");
+  const input =
+    fileFlag !== -1 && process.argv[fileFlag + 1]
+      ? await readFile(process.argv[fileFlag + 1], "utf8")
+      : process.argv.slice(2).filter((arg) => !arg.startsWith("--")).join(" ");
+  if (!input) {
+    console.error("Usage: node normalize-persian.mjs [--search] [--file input.txt] [text]");
+    process.exit(2);
+  }
+  const output =
+    mode === "search"
+      ? normalizePersianSearch(input)
+      : normalizePersianDisplay(input, { digits: process.argv.includes("--persian-digits") ? "persian" : "keep" });
+  process.stdout.write(output);
+}

package/skills/shopify-app-development/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: shopify-app-development
+description: "Build a Shopify app with the configured Admin API version, session-token auth for embedded admin requests, and HMAC-verified webhooks. Use when creating or changing a Shopify app, Admin GraphQL call, app proxy, or Shopify webhook handler."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Shopify app development
+
+Use this skill for a Shopify app. Payment capture inside a shop you own is the payment skill. Webhook durability is the order and webhook skill. Storefront browsing without an admin token is the headless storefront skill.
+
+Shopify's developer docs are the source for request authentication and webhook delivery. Re-check them when an API version or header name is load-bearing. This skill records the contracts those docs describe.
+
+## Procedure
+
+1. Keep app configuration in `shopify.app.toml`, including the API version and app-specific webhook subscriptions. Do not hard-code an API version in a handler. The `X-Shopify-API-Version` header says which version serialized that delivery, and the app configuration selects it.
+2. Authenticate every request before using a shop domain from the query, body, or header.
+3. Call the GraphQL Admin API for new admin work. Do not start a new REST Admin API client.
+4. Ask for the narrowest access scopes the mutation needs.
+5. Verify HTTPS webhooks with the app client secret over the raw body, then dedupe on `X-Shopify-Webhook-Id`.
+
+Header and auth details are in [the webhook and auth notes](references/auth-and-webhooks.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Which credential
+
+| Request | Proof |
+| --- | --- |
+| Embedded app in the Shopify admin | Session token (ID token) validated for signature, expiry, audience, and destination. |
+| HTTPS webhook | HMAC-SHA256 of the raw body, Base64, in `X-Shopify-Hmac-Sha256`, keyed with the app client secret. Compare header names case-insensitively. |
+| App proxy from a storefront | App proxy signature. It proves the shop, not the person. Do not change shop settings from an app proxy route. |
+| Checkout or customer-account UI extension | That extension's session token. |
+| Browser call that skips the app proxy | Anonymous. It may read public data. It must not mutate the shop. |
+
+Reject a request that fails its check. Do not fall back to a `shop` parameter.
+
+## Webhooks
+
+Compute Base64 HMAC-SHA256 over the raw body with the client secret. If a JSON parser runs first, the signature will not match. Return 401 when the signature does not match.
+
+`X-Shopify-Webhook-Id` identifies one delivery. Store it and skip a repeat. `X-Shopify-Event-Id` is shared by deliveries from the same merchant action and is not a substitute for the delivery id when you are deduping retries of one POST.
+
+Topic and shop-domain headers are untrusted until the HMAC matches. App-specific subscriptions in `shopify.app.toml` are kept in sync by Shopify. Use `webhookSubscriptionCreate` when the subscription has to be shop-specific. You cannot set the webhook API version on that mutation; it follows the app's webhook API version.
+
+After the app client secret rotates, Shopify can keep signing with the previous secret for up to an hour. Accept that window only if you still have the previous secret stored for verification.
+
+Google Cloud Pub/Sub and Amazon EventBridge deliveries do not use this HMAC header. Do not pretend an HTTPS verifier applies to those transports.
+
+## Admin writes
+
+- Send the shop domain you got from the verified token, not from a form field.
+- Treat Admin GraphQL user errors and top-level errors as separate. A 200 response can still contain `userErrors`.
+- Write webhooks and billing changes so a second delivery does not create a second subscription or a second charge.
+- Do not log the access token, the client secret, or the raw HMAC.
+
+## Gotchas
+
+- `express.json()` before verification replaces the raw body. Capture the bytes first.
+- A shop domain check must be anchored. `example.myshopify.com.attacker.example` is not a shop domain.
+- OAuth `state` has to be bound to the browser that started the install and checked on return.
+- Scopes are not implied by installation. A missing scope is a failed call, not a reason to use a broader token you stored earlier.
+
+## Verification
+
+- A webhook with a changed byte returns 401 and writes nothing.
+- The same `X-Shopify-Webhook-Id` applied twice creates one record.
+- An embedded request with no valid session token does not run a mutation.
+- An app proxy request cannot change shop settings.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/shopify-app-development/evals/examples/dedupe-delivery.md

@@ -0,0 +1,3 @@
+Store `X-Shopify-Webhook-Id` after the HMAC matches.
+
+If that id is already in the inbox, return 200 and do not create another order record. Authorize the handler with the verified HMAC, not with an unverified shop field.

package/skills/shopify-app-development/evals/examples/verify-webhook.md

@@ -0,0 +1,3 @@
+Compute the HMAC over the raw body with the app client secret and compare it to `X-Shopify-Hmac-Sha256`.
+
+Reject the request when the digest does not match. Read `X-Shopify-Topic` only after that check.

package/skills/shopify-app-development/evals/tasks.json

@@ -0,0 +1,29 @@
+{
+  "tasks": [
+    {
+      "id": "verify-webhook",
+      "task": "Verify a Shopify HTTPS webhook with the app client secret before reading the topic or shop domain.",
+      "expects": {
+        "must_include": [
+          "X-Shopify-Hmac-Sha256",
+          "raw body"
+        ],
+        "must_not_include": [
+          "express.json()"
+        ]
+      }
+    },
+    {
+      "id": "dedupe-delivery",
+      "task": "Process a retried Shopify order webhook once using the delivery id Shopify sends.",
+      "expects": {
+        "must_include": [
+          "X-Shopify-Webhook-Id"
+        ],
+        "must_not_include": [
+          "shop query parameter"
+        ]
+      }
+    }
+  ]
+}

package/skills/shopify-app-development/references/auth-and-webhooks.md

@@ -0,0 +1,44 @@
+# Shopify auth and webhooks
+
+These notes follow Shopify's app authentication and webhook delivery docs. Header names are case-insensitive on the wire.
+
+## HTTPS webhook headers
+
+| Header | Use |
+| --- | --- |
+| `X-Shopify-Topic` | Topic, such as `products/update`. Untrusted until the HMAC matches. |
+| `X-Shopify-Hmac-Sha256` | Base64 HMAC-SHA256 of the raw body using the app client secret. |
+| `X-Shopify-Shop-Domain` | `myshopify.com` domain. Untrusted until the HMAC matches. |
+| `X-Shopify-API-Version` | Version used to serialize the payload. |
+| `X-Shopify-Webhook-Id` | Unique per delivery. Dedupe retries with this. |
+| `X-Shopify-Triggered-At` | When Shopify triggered the delivery. |
+| `X-Shopify-Event-Id` | Shared by deliveries from the same merchant action. |
+
+Manual check:
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function shopifyWebhookValid(secret, rawBody, header) {
+  const digest = createHmac("sha256", secret).update(rawBody).digest();
+  const received = Buffer.from(String(header), "base64");
+  if (digest.length !== received.length) {
+    return false;
+  }
+  return timingSafeEqual(digest, received);
+}
+```
+
+Compare the decoded digest bytes. A string compare of the Base64 text can disagree on padding. Reject when `header` is missing.
+
+## Session tokens
+
+For an embedded admin request, validate the ID token's signature, expiry, audience, and destination. The destination shop is the shop you may call. A `shop` query parameter is not that proof.
+
+## App configuration
+
+Prefer app-specific webhook subscriptions in `shopify.app.toml` when every install should receive the same topics. Use the Admin GraphQL `webhookSubscriptionCreate` mutation for a subscription that differs per shop. The webhook API version is the app's configured version in both cases.
+
+## Shop domain
+
+Accept a shop domain only when it matches a pattern anchored at both ends, such as a single label plus `.myshopify.com`. Do not use a substring or a suffix check that allows an extra domain on the right.