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

package/skills/fraud-and-risk-basics/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "wait-for-3ds",
+      "task": "Do not capture a card payment while 3-D Secure is still waiting for the shopper.",
+      "expects": {
+        "must_include": [
+          "3-D Secure",
+          "do not capture"
+        ],
+"must_not_include": [
+        "4111111111111111"
+      ]
+      }
+    },
+    {
+      "id": "review-queue",
+      "task": "Queue a high-amount AVS mismatch for a person to capture or void, and ignore a risk flag from the browser.",
+      "expects": {
+        "must_include": [
+          "review",
+          "AVS"
+        ],
+        "must_not_include": [
+          "risk: low"
+        ]
+      }
+    }
+  ]
+}

package/skills/google-merchant-product-feeds/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: google-merchant-product-feeds
+description: "Build a Google Merchant Center product feed item with the required id, title, description, link, image, availability, and price fields. Use when exporting products to Merchant Center, Content API items, or a product feed file."
+license: MIT
+compatibility: "The feed item checker requires Node.js 20 or newer. No network access."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Google Merchant product feeds
+
+Use this skill when a catalog becomes a Merchant Center item. On-page JSON-LD is the structured-data skill. Generated titles and descriptions follow the description-guardrails skill, then the structured-title rules below.
+
+Attribute names and limits below follow Google's Merchant Center product data specification. Re-check that specification when a disapproval cites an attribute this skill does not list. The local checker does not call Google.
+
+## Procedure
+
+1. Emit one item per purchasable unit. A variant gets its own `id`. Variants that shoppers choose among share `item_group_id`.
+2. Fill the required attributes: `id`, `title` or `structured_title`, `description` or `structured_description`, `link`, `image_link`, `availability`, and `price`.
+3. Match the landing page. The title, description, price, and availability a shopper sees are the values in the feed.
+4. Run `node scripts/check-feed-item.mjs --file item.json` from this skill directory.
+5. Keep `id` stable for the life of that unit. A new id on every export creates a new product and drops history.
+
+Field limits and the variant rules are in [the attribute notes](references/attributes.md). An item that passes the checker is in [`assets/example-item.json`](assets/example-item.json). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Required values
+
+| Attribute | Rule |
+| --- | --- |
+| `id` | Unique, stable, at most 50 characters. Use the SKU when the SKU fits. |
+| `title` | Plain text, at most 150 characters, or `structured_title` when the title was generated. |
+| `description` | Plain text, at most 5000 characters, or `structured_description` when the description was generated. |
+| `link` | `http` or `https` URL of the product landing page on the verified domain. |
+| `image_link` | `http` or `https` URL of the main product image. |
+| `availability` | `in_stock`, `out_of_stock`, `preorder`, or `backorder`. |
+| `price` | Decimal major units with a period, a space, and an ISO 4217 code, such as `15.00 USD`. |
+
+`availability_date` is required when `availability` is `preorder`. Provide it for `backorder` as well. The product data specification asks for that date on both.
+
+## Variants
+
+Set `item_group_id` to the parent id for every variant. Google's specification marks `item_group_id` as required for variants in free listings, and for variants targeted at Brazil, France, Germany, Japan, the United Kingdom, and the United States. Put the variant's color or size in `color` and `size` when those attributes distinguish the unit. Apparel in those countries has extra required attributes (`color`, `size`, `gender`, `age_group`). Do not guess them. Read them from the catalog or leave the item out of the feed until they exist.
+
+## Generated text
+
+If a title or description was produced by a generative system, do not put it only in `title` or `description`. Use `structured_title` or `structured_description` and set `digital_source_type` to `trained_algorithmic_media`. The ordinary `title` and `description` attributes are for text that was not created that way. The content still has to match the landing page and stay within 150 and 5000 characters.
+
+## Images
+
+Merchant Center has announced a minimum image size of 500 by 500 pixels, with enforcement beginning 31 January 2027. Export images that already meet that size instead of waiting for the disapproval. The checker validates the URL, not the pixel size. Check dimensions in the image pipeline.
+
+## Gotchas
+
+- A formatted price such as `$15.00` or `15,00 USD` is not the `price` attribute. Use `15.00 USD`.
+- Changing `id` when the SKU gains a prefix splits the product in Merchant Center.
+- Out-of-stock items still need a price, and the landing page still needs to show that price.
+- Do not put "free shipping" or a competitor name in `title` or `description`.
+- GTIN is not universally required. Submit a real GTIN when the product has one. Do not invent digits. `identifier_exists` is the attribute Google documents when you do not have a GTIN; confirm the current rule for that category before setting it false.
+
+## Verification
+
+- The checker exits 0 on the feed file.
+- Each variant id is unique and stable, and shares `item_group_id` with its siblings.
+- A spot-check opens `link` and sees the same price text and availability.
+- A generated description is in `structured_description`, not only in `description`.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/google-merchant-product-feeds/assets/example-item.json

@@ -0,0 +1,11 @@
+{
+  "id": "SHIRT-BLUE",
+  "title": "Cotton shirt, blue",
+  "description": "Short-sleeve cotton shirt in blue.",
+  "link": "https://shop.example/shirt?color=blue",
+  "image_link": "https://shop.example/shirt-blue.jpg",
+  "availability": "in_stock",
+  "price": "19.00 USD",
+  "item_group_id": "shirt",
+  "color": "blue"
+}

package/skills/google-merchant-product-feeds/evals/examples/generated-title.md

@@ -0,0 +1,3 @@
+Put the generated words in structured_title.
+
+Set `digital_source_type` to `trained_algorithmic_media` and keep the content within 150 characters. Do not add promotional text.

package/skills/google-merchant-product-feeds/evals/examples/stable-variant-id.md

@@ -0,0 +1,3 @@
+One feed item for the purchasable color.
+
+`id` is `SHIRT-BLUE`, `item_group_id` is `shirt`, `availability` is `in_stock`, and `price` is `19.00 USD`. The link opens that variant.

package/skills/google-merchant-product-feeds/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "stable-variant-id",
+      "task": "Export the blue shirt variant to Merchant Center with a stable id, a grouped parent, and a decimal price.",
+      "expects": {
+        "must_include": [
+          "item_group_id",
+          "19.00 USD"
+        ],
+        "must_not_include": [
+          "$19.00"
+        ]
+      }
+    },
+    {
+      "id": "generated-title",
+      "task": "Label a generated product title so Merchant Center can tell it from a title a person wrote.",
+      "expects": {
+        "must_include": [
+          "trained_algorithmic_media",
+          "structured_title"
+        ],
+        "must_not_include": [
+          "free shipping"
+        ]
+      }
+    }
+  ]
+}

package/skills/google-merchant-product-feeds/references/attributes.md

@@ -0,0 +1,39 @@
+# Merchant Center item attributes
+
+Source: Google Merchant Center product data specification. Limits below are the ones that specification states for the common required attributes.
+
+## Identity
+
+- `id`: at most 50 characters, unique per product, stable across updates, same id for the same product across countries or languages when it is the same unit.
+- `item_group_id`: shared by variants. Required for variant free listings, and for variants in Brazil, France, Germany, Japan, the United Kingdom, and the United States.
+- `gtin`: submit only a real GTIN. The specification strongly recommends it when one exists. Maximum 50 numeric characters, at most 14 digits per value, ignoring added spaces and dashes.
+
+## Text
+
+- `title`: at most 150 characters. No promotional text such as "free shipping", and no all-capital slogans.
+- `description`: at most 5000 characters. Product information only. No store links, sale copy, or other products.
+- Generated text uses `structured_title` or `structured_description`. Set `digital_source_type` to `trained_algorithmic_media` and put the words in `content`. `default` means the text was not generated. If you omit `digital_source_type`, Google treats it as `default`.
+
+## Offer
+
+- `price`: `19.00 USD`. Period as the decimal separator. ISO 4217 currency code.
+- `sale_price`: same format, lower than `price`, and only while the landing page shows that sale.
+- `availability`: `in_stock`, `out_of_stock`, `preorder`, `backorder`.
+- `availability_date`: required for `preorder`. Also send it for `backorder`.
+- `link` and `image_link`: absolute `http` or `https` URLs. `link` is the landing page on the verified domain, not an interstitial.
+
+## Condition
+
+`condition` is required when the product is used or refurbished. Allowed values are `new`, `refurbished`, and `used`. Do not omit `new` on a new product if the target program asks for it; check the current specification for that program rather than guessing.
+
+## Checker
+
+`scripts/check-feed-item.mjs` checks one JSON object:
+
+- required keys `id`, `title` or structured title content, `description` or structured description content, `link`, `image_link`, `availability`, `price`
+- length limits for `id`, `title`, and `description`
+- price pattern and availability vocabulary
+- `availability_date` when availability is `preorder` or `backorder`
+- `https` or `http` URLs
+
+It does not upload the item, fetch the image, or know whether a category needs `color` or `gender`.

package/skills/google-merchant-product-feeds/scripts/check-feed-item.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const AVAILABILITY = new Set(["in_stock", "out_of_stock", "preorder", "backorder"]);
+
+export function checkFeedItem(item) {
+  const errors = [];
+  if (!item || typeof item !== "object") {
+    return ["Item must be an object."];
+  }
+  requireText(item.id, "id", 50, errors);
+  const title = textValue(item, "title", "structured_title");
+  const description = textValue(item, "description", "structured_description");
+  if (title === undefined) {
+    errors.push("title or structured_title.content is required");
+  } else if (title.length > 150) {
+    errors.push(`title is ${title.length} characters; the maximum is 150`);
+  }
+  if (description === undefined) {
+    errors.push("description or structured_description.content is required");
+  } else if (description.length > 5000) {
+    errors.push(`description is ${description.length} characters; the maximum is 5000`);
+  }
+  requireUrl(item.link, "link", errors);
+  requireUrl(item.image_link, "image_link", errors);
+  if (!AVAILABILITY.has(item.availability)) {
+    errors.push("availability must be in_stock, out_of_stock, preorder, or backorder");
+  }
+  if ((item.availability === "preorder" || item.availability === "backorder") && !nonEmpty(item.availability_date)) {
+    errors.push("availability_date is required for preorder and backorder");
+  }
+  if (typeof item.price !== "string" || !/^\d+\.\d{2} [A-Z]{3}$/.test(item.price)) {
+    errors.push('price must look like "15.00 USD"');
+  }
+  if (item.gtin !== undefined && !/^\d{8,14}$/.test(String(item.gtin))) {
+    errors.push("gtin must be 8 to 14 digits when present");
+  }
+  return errors;
+}
+
+function textValue(item, plainKey, structuredKey) {
+  if (nonEmpty(item[plainKey])) {
+    return String(item[plainKey]);
+  }
+  const structured = item[structuredKey];
+  if (structured && nonEmpty(structured.content)) {
+    return String(structured.content);
+  }
+  return undefined;
+}
+
+function requireText(value, label, max, errors) {
+  if (!nonEmpty(value)) {
+    errors.push(`${label} is required`);
+    return;
+  }
+  if (String(value).length > max) {
+    errors.push(`${label} is ${String(value).length} characters; the maximum is ${max}`);
+  }
+}
+
+function requireUrl(value, label, errors) {
+  if (typeof value !== "string" || !/^https?:\/\/\S+$/.test(value)) {
+    errors.push(`${label} must be an http or https URL`);
+  }
+}
+
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+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-feed-item.mjs");
+if (isCli) {
+  const file = readOption("--file");
+  if (!file) {
+    console.error("Usage: node check-feed-item.mjs --file item.json");
+    process.exit(2);
+  }
+  const errors = checkFeedItem(JSON.parse(await readFile(file, "utf8")));
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`ERROR ${error}`);
+    }
+    process.exit(1);
+  }
+  console.log("Feed item passed the local checks.");
+}

package/skills/headless-nextjs-storefront/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: headless-nextjs-storefront
+description: "Build a Next.js storefront that loads catalog data on the server, keeps admin secrets off the client, and revalidates price and stock. Use when adding product, cart, or checkout UI in a Next.js App Router storefront for WooCommerce or another headless commerce API."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Headless Next.js storefront
+
+Use this skill for a Next.js storefront that talks to a commerce API. WooCommerce HTTP details are in the REST API skill. Shopify admin apps are a different skill. Checkout field behavior is the checkout skill.
+
+This skill assumes the App Router (`app/`). Do not pin a Next.js major version you have not installed. Use the cache and route APIs that version documents.
+
+## Procedure
+
+1. Render product and category pages from the server. The HTML should contain the price and availability a shopper and a crawler see.
+2. Keep admin credentials and WooCommerce consumer secrets in server environment variables. Never import them into a client component.
+3. Use the public storefront API for the cart. For WooCommerce that is the Store API (`/wp-json/wc/store/v1/`), with its cart token and nonce. It is not `wc/v3`.
+4. Cache catalog reads. Invalidate that cache when price or stock changes. Do not cache a cart response as if it were a public product.
+5. Re-check the charged total on the server when checkout starts. The figure in React state is not the amount to capture.
+
+Cache and cart boundaries are in [the cache notes](references/cache-and-cart.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Data split
+
+| Data | Where it is read | Cache |
+| --- | --- | --- |
+| Product title, price, stock, images | Server component or a route handler | Public cache with a tag such as `product:<id>` |
+| Cart and checkout session | Server route that forwards the shopper's cart token | Do not use the public product cache |
+| Admin writes | Server only, with the admin credential | Do not expose the route to the browser without your own auth |
+
+Call `revalidateTag('product:<id>')` or `revalidatePath` from the server path that handles the catalog webhook. A client component cannot import `next/cache` revalidation and run it in the browser.
+
+## WooCommerce storefront
+
+- Product pages may use a read-only integration on the server. Prefer a key that cannot write, or a public product endpoint your store already exposes.
+- Cart requests send the `Cart-Token` the Store API returned. Store that token in an HTTP-only cookie set by your server route, not in `localStorage`, if the token would let someone else modify the cart.
+- The browser calls your Next.js route. Your route calls WooCommerce. Do not point the browser at `wc/v3` with a consumer secret.
+
+## Shopify storefront
+
+- Use the Storefront API for product and cart reads. The Storefront access token is still a secret if it can create checkouts. Follow the token type Shopify documents for that API.
+- Do not send the Admin API token to the browser.
+
+## Rendering
+
+- Format money with the storefront locale on the server so the HTML and the JSON-LD match. Persian digits belong in visible text, not in the amount you post to checkout. See the RTL skill.
+- Variant selection updates the visible price to that variant before add-to-cart.
+- Out-of-stock variants stay disabled even if a cached page is briefly stale. The add-to-cart route checks stock again.
+
+## Gotchas
+
+- `cache: 'force-cache'` on a cart GET will show one shopper another shopper's cart if the URL does not vary. Do not cache cart responses on a shared key.
+- A webhook that updates stock must revalidate the product tag. Restarting the Next.js process is not an invalidation strategy.
+- Client-side `fetch` to a route that embeds the admin secret in the response will leak it into the browser. Return only the fields the UI needs.
+- Draft-mode or preview cookies should not be cached as public product HTML.
+
+## Verification
+
+- The built HTML for a product contains the price without requiring client JavaScript.
+- Searching the client bundle finds no consumer secret and no Admin API token.
+- Updating a price and delivering the catalog webhook changes the next product response without a redeploy.
+- Two browsers do not share a cart token.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/headless-nextjs-storefront/evals/examples/revalidate-stock.md

@@ -0,0 +1,7 @@
+Tag the product fetch and invalidate that tag from the webhook route.
+
+```js
+revalidateTag(`product:${id}`);
+```
+
+Do not cache the cart response with the public product cache.

package/skills/headless-nextjs-storefront/evals/examples/server-price.md

@@ -0,0 +1,3 @@
+Load the product on the server and render the price in the HTML.
+
+The consumer secret stays in a server environment variable. The cart token is set in an HTTP-only cookie by a route handler.

package/skills/headless-nextjs-storefront/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "server-price",
+      "task": "Render a WooCommerce product price in a Next.js server component without shipping the consumer secret to the browser.",
+      "expects": {
+        "must_include": [
+          "server",
+          "consumer secret"
+        ],
+        "must_not_include": [
+          "localStorage"
+        ]
+      }
+    },
+    {
+      "id": "revalidate-stock",
+      "task": "Refresh a cached product page when a verified webhook says the variant stock changed.",
+      "expects": {
+        "must_include": [
+          "revalidateTag",
+          "product:"
+        ],
+        "must_not_include": [
+          "force-cache"
+        ]
+      }
+    }
+  ]
+}

package/skills/headless-nextjs-storefront/references/cache-and-cart.md

@@ -0,0 +1,39 @@
+# Cache and cart boundaries
+
+## Product cache
+
+Tag each product fetch with a stable id:
+
+```js
+const response = await fetch(productUrl, {
+  next: { tags: [`product:${id}`] },
+});
+```
+
+The exact `fetch` cache options depend on the installed Next.js version. Read that version's data-cache docs before copying the option names. The rule that does not change: a public product response may be cached; a cart response may not share that cache entry.
+
+Invalidate from a server route that has already verified the catalog webhook:
+
+```js
+import { revalidateTag } from "next/cache";
+
+revalidateTag(`product:${id}`);
+```
+
+Revalidate the parent and each variant tag when a variable product changes. Revalidating only the parent leaves a variant URL stale.
+
+## Cart route
+
+```text
+Browser -> Next.js route -> Store API
+                |                |
+         HTTP-only cart cookie   Cart-Token header
+```
+
+The route reads the cookie, calls the Store API, and returns the cart JSON the UI needs: lines, totals, and messages. It does not return the commerce admin credential.
+
+Set the cookie with `HttpOnly`, `Secure`, and `SameSite=Lax` (or `Strict` if your checkout flow stays on the same site). `SameSite=None` requires `Secure` and is only for a checkout that is actually cross-site.
+
+## Checkout handoff
+
+When the shopper pays, create or update the order on the server and pass the server-calculated total to the payment skill. If the Store API total and your cached product prices disagree, trust the cart or order total from the commerce server for the charge, then revalidate the product.

package/skills/inventory-and-multi-warehouse/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: inventory-and-multi-warehouse
+description: "Track stock per location with on-hand, reserved, and available quantities, reserve at checkout, and allocate orders across warehouses without overselling. Use when adding warehouses or stores as stock locations, reservations, transfers, or order routing."
+license: MIT
+compatibility: "The allocation checker needs Node.js 20 or newer and no packages."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Inventory and multi-warehouse
+
+A single stock number per product stops working once there are two places that ship, or a checkout that holds stock while the shopper pays. Model quantities per location and per state, and change them only through movements. Platform notes are in [the platform notes](references/platforms.md).
+
+## Procedure
+
+1. Key stock by purchasable unit (SKU or variation) **and** location. A product with sizes has one row per size per location.
+2. Keep separate quantities: `on_hand` (physically there), `reserved` (held for unpaid or unshipped orders), and `available = on_hand - reserved - safety_stock`. Sell only from `available`.
+3. Change stock only by writing a movement row: receipt, sale reservation, release, shipment, return, adjustment, or transfer. The current quantity is the sum of movements, or a cached total updated in the same transaction.
+4. Reserve at order creation with a conditional update, such as `UPDATE stock SET reserved = reserved + :qty WHERE sku = :sku AND location = :loc AND on_hand - reserved - safety_stock >= :qty`. Zero rows updated means not enough stock.
+5. Give each reservation an expiry. Release it when payment fails or the hold expires. Convert it to a shipment when the order ships.
+6. Allocate an order to locations with an explicit policy, then reserve at those locations. Store the allocation on the order lines.
+
+## Allocation
+
+A common policy, in order:
+
+1. Only locations that can ship to the destination and are active.
+2. One location that can fill every line, the closest or cheapest first.
+3. Otherwise split by line across the fewest locations.
+4. Otherwise back-order or reject the line, as the store policy says. Never reserve more than `available`.
+
+Run `node scripts/allocate-stock.mjs order.json stock.json` to test a policy on sample data. It returns the allocation per line and any shortfall, and never allocates more than a location has available.
+
+## Transfers
+
+A transfer is two movements: out of the source when it ships, and into the destination when it is received. Stock in transit is in neither `available` figure. Record `incoming` at the destination if buyers need to see it.
+
+## Counts and adjustments
+
+A stock count writes an adjustment movement for the difference, with a reason and the user. Do not overwrite `on_hand` directly, or the history and any reservations made during the count are lost.
+
+## Gotchas
+
+- Reading available stock and then writing it in a second statement oversells under load. Check and reserve in one conditional update or a row lock.
+- Decrementing `on_hand` at checkout and again at shipment counts the sale twice. Reserve at checkout, then move reserved to shipped.
+- A parent product's total is not a sellable quantity. Sell from the variation's row.
+- Safety stock that is not subtracted from `available` lets the last units sell online while the store floor still shows them.
+- Returns go back into stock only after inspection. Use a separate location or state such as `quality_control` until then.
+
+## Verification
+
+- Two concurrent checkouts for the last unit: one reserves, the other is refused.
+- An expired unpaid reservation returns its quantity to `available`.
+- An order for two lines that one warehouse can fill is not split.
+- A transfer in transit does not appear as available at either location.
+- The movement log sums to the current `on_hand` for every SKU and location.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/inventory-and-multi-warehouse/evals/examples/reserve-last-unit.md

@@ -0,0 +1,3 @@
+Keep `on_hand` and `reserved` per SKU and location, and compute `available` as on hand minus reserved minus safety stock.
+
+Reserve with one conditional update: `UPDATE stock_levels SET reserved = reserved + 1 WHERE sku = 'MUG-RED' AND location_id = 'main' AND on_hand - reserved - safety_stock >= 1`. The first checkout updates one row and continues. The second updates zero rows and is told the item is out of stock. Insert a `reserve` movement in the same transaction, and release it if payment fails.

package/skills/inventory-and-multi-warehouse/evals/examples/split-order.md

@@ -0,0 +1,3 @@
+The policy fills the order from one location when any eligible location can ship every line, because a split doubles shipping cost and parcels. Warehouse A can, so the allocation is both lines from A, even though B is closer.
+
+Only when no single location can fill the order do we split, using the fewest locations and preferring ones already used. Store the allocation on each order line and reserve at A in the same transaction.

package/skills/inventory-and-multi-warehouse/evals/tasks.json

@@ -0,0 +1,20 @@
+{
+  "tasks": [
+    {
+      "id": "reserve-last-unit",
+      "task": "Two shoppers check out the last unit of a SKU at the same time. Write the stock reservation so only one succeeds.",
+      "expects": {
+        "must_include": ["reserved", "available", "conditional update"],
+        "must_not_include": ["SELECT stock_quantity then UPDATE"]
+      }
+    },
+    {
+      "id": "split-order",
+      "task": "An order has two lines. Warehouse A has both items, warehouse B is closer but has only one. Decide the allocation and explain the policy.",
+      "expects": {
+        "must_include": ["one location", "split", "allocation"],
+        "must_not_include": ["always split"]
+      }
+    }
+  ]
+}

package/skills/inventory-and-multi-warehouse/references/platforms.md

@@ -0,0 +1,40 @@
+# Platform notes
+
+## WooCommerce
+
+WooCommerce core keeps one `stock_quantity` per product or variation, with `manage_stock` and `stock_status`. A variation with `manage_stock` set to `parent` uses the parent's quantity. Core has no locations. Multi-location stock comes from an extension or an external inventory system that writes the summed `available` back to WooCommerce.
+
+- Core reduces stock when an order is paid or moves to processing, completed, or on hold. During checkout it reserves stock for pending orders, and the **Hold stock** setting cancels unpaid pending orders after that many minutes.
+- When an external system is the source of truth, turn off core stock reduction for those products or the store will reduce twice.
+- Write stock through the REST API `products/{id}` or `products/{id}/variations/{id}` with `stock_quantity`, or the batch endpoint for many items.
+
+## Shopify
+
+Shopify tracks quantities per inventory item per location with named states, including `available`, `committed`, `incoming`, `on_hand`, and `reserved`. Change them with the Admin GraphQL inventory mutations, such as `inventoryAdjustQuantities` for deltas, and give every change a reason. Fulfillment orders assign order lines to locations, and a merchant can move them.
+
+## Your own system
+
+A minimal schema:
+
+```sql
+CREATE TABLE stock_levels (
+  sku TEXT NOT NULL,
+  location_id TEXT NOT NULL,
+  on_hand INTEGER NOT NULL DEFAULT 0 CHECK (on_hand >= 0),
+  reserved INTEGER NOT NULL DEFAULT 0 CHECK (reserved >= 0),
+  safety_stock INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (sku, location_id)
+);
+
+CREATE TABLE stock_movements (
+  id BIGSERIAL PRIMARY KEY,
+  sku TEXT NOT NULL,
+  location_id TEXT NOT NULL,
+  kind TEXT NOT NULL,          -- receipt, reserve, release, ship, return, adjust, transfer_out, transfer_in
+  quantity INTEGER NOT NULL,   -- signed
+  reference TEXT,              -- order, transfer, or count id
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+Update `stock_levels` and insert the movement in one transaction.

package/skills/inventory-and-multi-warehouse/scripts/allocate-stock.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Allocate order lines to stock locations: one location if possible, otherwise the fewest.
+// Usage: node allocate-stock.mjs <order.json> <stock.json>
+// order.json: { "lines": [{ "sku": "TEE-M", "quantity": 2 }], "destination": "DE" }
+// stock.json: [{ "location": "berlin", "ships": ["DE", "AT"], "rank": 1, "levels": { "TEE-M": { "onHand": 5, "reserved": 1, "safetyStock": 0 } } }]
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function availableAt(location, sku) {
+  const level = location.levels?.[sku];
+  if (!level) return 0;
+  return Math.max(0, (level.onHand ?? 0) - (level.reserved ?? 0) - (level.safetyStock ?? 0));
+}
+
+/**
+ * Returns { allocations: [{ sku, location, quantity }], shortfalls: [{ sku, quantity }], locations }.
+ * Never allocates more than a location has available.
+ */
+export function allocateOrder(order, stock) {
+  const eligible = stock
+    .filter((location) => location.active !== false)
+    .filter((location) => !order.destination || !location.ships || location.ships.includes(order.destination))
+    .sort((a, b) => (a.rank ?? 0) - (b.rank ?? 0));
+  const lines = order.lines ?? [];
+  for (const line of lines) {
+    if (!Number.isInteger(line.quantity) || line.quantity <= 0) throw new Error(`${line.sku}: quantity must be a positive whole number`);
+  }
+
+  const single = eligible.find((location) => lines.every((line) => availableAt(location, line.sku) >= line.quantity));
+  if (single) {
+    const allocations = lines.map((line) => ({ sku: line.sku, location: single.location, quantity: line.quantity }));
+    return { allocations, shortfalls: [], locations: [single.location] };
+  }
+
+  const remaining = new Map(eligible.map((location) => [location.location, { ...location.levels }]));
+  const allocations = [];
+  const shortfalls = [];
+  const used = new Set();
+  for (const line of lines) {
+    let needed = line.quantity;
+    // Prefer locations already used for this order, then by rank.
+    const ordered = [...eligible].sort((a, b) => Number(used.has(b.location)) - Number(used.has(a.location)));
+    for (const location of ordered) {
+      if (needed === 0) break;
+      const levels = remaining.get(location.location);
+      const free = availableAt({ levels }, line.sku);
+      if (free === 0) continue;
+      const take = Math.min(free, needed);
+      allocations.push({ sku: line.sku, location: location.location, quantity: take });
+      levels[line.sku] = { ...levels[line.sku], reserved: (levels[line.sku].reserved ?? 0) + take };
+      used.add(location.location);
+      needed -= take;
+    }
+    if (needed > 0) shortfalls.push({ sku: line.sku, quantity: needed });
+  }
+  return { allocations, shortfalls, locations: [...used] };
+}
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+  const [orderFile, stockFile] = process.argv.slice(2);
+  if (!orderFile || !stockFile) {
+    console.error("Usage: node allocate-stock.mjs <order.json> <stock.json>");
+    process.exit(2);
+  }
+  const order = JSON.parse(await readFile(orderFile, "utf8"));
+  const stock = JSON.parse(await readFile(stockFile, "utf8"));
+  const result = allocateOrder(order, stock);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.shortfalls.length > 0 ? 1 : 0);
+}