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

package/skills/conversion-event-tracking/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "purchase-once",
+      "task": "Emit a purchase event after payment succeeds, with the order number as the transaction id and value excluding tax.",
+      "expects": {
+        "must_include": [
+          "transaction_id",
+          "value"
+        ],
+        "must_not_include": [
+          "transaction_id: \"\""
+        ]
+      }
+    },
+    {
+      "id": "variant-item-id",
+      "task": "Track add_to_cart for the blue shirt variant with that variant's SKU, not only the parent product id.",
+      "expects": {
+        "must_include": [
+          "add_to_cart",
+          "SHIRT-BLUE"
+        ],
+        "must_not_include": [
+          "button click purchase"
+        ]
+      }
+    }
+  ]
+}

package/skills/conversion-event-tracking/references/events.md

@@ -0,0 +1,36 @@
+# Commerce events
+
+Names follow GA4 recommended ecommerce events: `view_item`, `add_to_cart`, `begin_checkout`, `add_shipping_info`, `add_payment_info`, `purchase`, `refund`.
+
+## Purchase parameters
+
+| Parameter | Rule |
+| --- | --- |
+| `transaction_id` | Required, non-empty, unique per order. Not an email and not an empty string. |
+| `currency` | ISO 4217. Required when `value` is set. |
+| `value` | Sum of `price * quantity` for `items`. Exclude `tax` and `shipping`. |
+| `tax` | Optional number. Not included in `value`. |
+| `shipping` | Optional number. Not included in `value`. |
+| `items` | At least one item with `item_id` or `item_name`. |
+
+GA4's event reference marks `value` and `currency` with conditions. This project requires them on `purchase` so revenue is not an unlabeled number. `view_item` may omit `value`. If it includes `value`, it includes `currency`.
+
+## Checker
+
+`scripts/check-event.mjs` reads:
+
+```json
+{
+  "name": "purchase",
+  "params": {
+    "transaction_id": "1042",
+    "currency": "USD",
+    "value": 19.0,
+    "tax": 0,
+    "shipping": 0,
+    "items": [{ "item_id": "SHIRT-BLUE", "item_name": "Cotton shirt", "price": 19.0, "quantity": 1 }]
+  }
+}
+```
+
+It checks the name, the items, the purchase id, and the value sum when every item has a numeric price and quantity. It does not call an analytics API.

package/skills/conversion-event-tracking/scripts/check-event.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const NAMES = new Set([
+  "view_item",
+  "add_to_cart",
+  "begin_checkout",
+  "add_shipping_info",
+  "add_payment_info",
+  "purchase",
+  "refund",
+]);
+
+export function checkCommerceEvent(event) {
+  const errors = [];
+  if (!event || typeof event !== "object") {
+    return ["Event must be an object."];
+  }
+  if (!NAMES.has(event.name)) {
+    errors.push(`Unsupported event name: ${String(event.name)}`);
+    return errors;
+  }
+  const params = event.params;
+  if (!params || typeof params !== "object") {
+    return ["Event params are required."];
+  }
+  if (!Array.isArray(params.items) || params.items.length === 0) {
+    errors.push("items must contain at least one item");
+  } else {
+    params.items.forEach((item, index) => {
+      if (!item || (typeof item.item_id !== "string" && typeof item.item_name !== "string")) {
+        errors.push(`items[${index}] needs item_id or item_name`);
+      }
+    });
+  }
+  if (params.value !== undefined && (typeof params.currency !== "string" || !/^[A-Z]{3}$/.test(params.currency))) {
+    errors.push("currency is required when value is set and must be an ISO 4217 code");
+  }
+  if (event.name === "purchase" || event.name === "refund") {
+    if (typeof params.transaction_id !== "string" || params.transaction_id.trim() === "") {
+      errors.push(`${event.name} requires a non-empty transaction_id`);
+    }
+    if (typeof params.value !== "number") {
+      errors.push(`${event.name} requires a numeric value`);
+    }
+  }
+  if (event.name === "purchase" && Array.isArray(params.items)) {
+    const priced = params.items.every((item) => typeof item?.price === "number" && typeof item?.quantity === "number");
+    if (priced && typeof params.value === "number") {
+      const sum = params.items.reduce((total, item) => total + item.price * item.quantity, 0);
+      if (Math.abs(sum - params.value) > 0.001) {
+        errors.push("value must equal the sum of price times quantity and must exclude tax and shipping");
+      }
+    }
+  }
+  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-event.mjs");
+if (isCli) {
+  const file = readOption("--file");
+  if (!file) {
+    console.error("Usage: node check-event.mjs --file event.json");
+    process.exit(2);
+  }
+  const errors = checkCommerceEvent(JSON.parse(await readFile(file, "utf8")));
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`ERROR ${error}`);
+    }
+    process.exit(1);
+  }
+  console.log("Event passed the local checks.");
+}

package/skills/ecommerce-seo-structured-data/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ecommerce-seo-structured-data
+description: "Add product JSON-LD that matches the visible offer, including price, currency, availability, and images, without a second conflicting Product node. Use when editing product-page SEO, schema.org markup, or merchant listing data."
+license: MIT
+compatibility: "The JSON-LD checker requires Node.js 20 or newer. No network access."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Ecommerce SEO structured data
+
+Use this skill when a product page needs schema.org data that matches what the shopper sees. Google's merchant listing and product snippet features have different required fields. Check a document with [`scripts/check-product-jsonld.mjs`](scripts/check-product-jsonld.mjs). The field list and the WooCommerce hook are in [the JSON-LD notes](references/product-jsonld.md). A passing merchant example is [`assets/example-product.jsonld`](assets/example-product.jsonld).
+
+Requirements below follow Google's Search Central product structured data documentation as reviewed for this skill. Rich result rules change. Re-check that documentation when a page is rejected, and do not promise a rich result.
+
+## Procedure
+
+1. Find existing Product markup before adding any. WooCommerce core prints Product data through `WC_Structured_Data` on the single product template. A second Product node for the same item conflicts with the first.
+2. Change WooCommerce output with the `woocommerce_structured_data_product` filter. Add a new JSON-LD script only on a headless or custom storefront that does not already emit one.
+3. Mark up the offer the page actually sells. A variant page uses that variant's price, currency, SKU, and availability. A parent page that spans several prices uses an `AggregateOffer` only for a product snippet, not as the sole offer for a merchant listing.
+4. Put JSON-LD in the server-rendered HTML. Google documents that Product markup built only in the browser can make shopping crawls less reliable for price and availability.
+5. Run the checker in the profile you are targeting:
+
+```bash
+node scripts/check-product-jsonld.mjs --file product.json --profile merchant
+node scripts/check-product-jsonld.mjs --file product.json --profile snippet
+```
+
+## Merchant listing profile
+
+The checker requires, for each Product:
+
+- `name`
+- `image` as a crawlable URL, an `ImageObject` with `url`, or a list of those
+- `offers` as one `Offer`, not an `AggregateOffer` and not an array
+- a numeric `price` greater than zero, or the same under `priceSpecification` when `offers.price` is absent
+- `priceCurrency` as a three-letter ISO 4217 code on the same object that carries the price
+
+If both `offers.price` and `offers.priceSpecification.price` are present, Google uses `offers.price`. The checker flags a non-positive `offers.price` in that case.
+
+`availability` is recommended. Use one schema.org value such as `https://schema.org/InStock` or `https://schema.org/OutOfStock`. Do not mark an out-of-stock variant as `InStock`.
+
+## Product snippet profile
+
+The checker requires `name` and at least one of `review`, `aggregateRating`, or `offers`.
+
+- An `Offer` needs a numeric price and `priceCurrency`.
+- An `AggregateOffer` needs numeric `lowPrice` and `highPrice`, `priceCurrency`, and a positive `offerCount`.
+- `aggregateRating`, when present, needs numeric `ratingValue` and either `reviewCount` or `ratingCount`.
+
+A snippet may describe a price range. A merchant listing, in the documentation this skill follows, needs a specific offer with a positive price.
+
+## Visible agreement
+
+- The price in JSON-LD is the price on the page, in the currency the shopper would be charged, without a thousands separator inside the JSON number.
+- The image URL returns the product image to an anonymous crawler.
+- `name` and `description` are the language of the page. Translate the schema with the page. Do not leave English schema on a Persian page unless the visible title is English.
+- RTL does not change the JSON. Do not insert Persian digits into `price` or `sku`. Display digits in HTML. Keep ASCII in the structured data.
+- Do not mark up products that are not on the page. A category page is not a single Product with one offer unless the page is actually one product.
+
+## Canonical and language
+
+- The page has one canonical URL, and the offer `url` matches the page the shopper landed on, including the selected variant when the variant has its own URL.
+- When several languages exist, each language URL's canonical and `hreflang` annotations have to agree. Structured data does not replace `hreflang`.
+
+## Gotchas
+
+- A formatted string such as `"19,00 USD"` or `"۱۹.۰۰"` is not a price. Use a JSON number.
+- `availability: InStock` on a parent while every variant is sold out contradicts the page.
+- Copying a review `ratingValue` you do not display, or marking up reviews the page does not show, is not a fix for a missing offer.
+- Sitewide `Organization` or return-policy markup is separate from the product offer. Add it once, on the pages where it is visible, rather than inventing a return policy inside every offer.
+
+## Verification
+
+- The checker exits 0 for the profile you ship.
+- View source shows one Product for the item, inside server-rendered HTML.
+- The price, currency, and availability match the variant on the page, including an out-of-stock variant.
+- A Persian product page keeps Persian text in `name` and ASCII in `price` and `priceCurrency`.
+- Disabling JavaScript still leaves the JSON-LD in the document.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/ecommerce-seo-structured-data/assets/example-product.jsonld

@@ -0,0 +1,15 @@
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Cotton shirt",
+  "image": "https://shop.example/shirt.jpg",
+  "description": "Short-sleeve cotton shirt.",
+  "sku": "SHIRT-BLUE",
+  "offers": {
+    "@type": "Offer",
+    "url": "https://shop.example/shirt?color=blue",
+    "priceCurrency": "USD",
+    "price": 19.0,
+    "availability": "https://schema.org/InStock"
+  }
+}

package/skills/ecommerce-seo-structured-data/evals/examples/extend-woocommerce-schema.md

@@ -0,0 +1,8 @@
+Filter the existing markup.
+
+```php
+add_filter( 'woocommerce_structured_data_product', function ( $markup, $product ) {
+    $markup['brand'] = array( '@type' => 'Brand', 'name' => 'Example' );
+    return $markup;
+}, 10, 2 );
+```

package/skills/ecommerce-seo-structured-data/evals/examples/variant-offer.md

@@ -0,0 +1,7 @@
+Use the variant offer.
+
+```json
+{ "price": 19.0, "priceCurrency": "USD", "availability": "https://schema.org/InStock" }
+```
+
+The JSON-LD price matches the blue shirt on the page.

package/skills/ecommerce-seo-structured-data/evals/tasks.json

@@ -0,0 +1,29 @@
+{
+  "tasks": [
+    {
+      "id": "extend-woocommerce-schema",
+      "task": "Add a brand to the product structured data WooCommerce already prints, without a second Product node.",
+      "expects": {
+        "must_include": [
+          "woocommerce_structured_data_product"
+        ],
+        "must_not_include": [
+          "second Product"
+        ]
+      }
+    },
+    {
+      "id": "variant-offer",
+      "task": "Mark up the blue variant that the page sells, including a numeric price and in-stock availability.",
+      "expects": {
+        "must_include": [
+          "priceCurrency",
+          "InStock"
+        ],
+        "must_not_include": [
+          "19,00 USD"
+        ]
+      }
+    }
+  ]
+}

package/skills/ecommerce-seo-structured-data/references/product-jsonld.md

@@ -0,0 +1,83 @@
+# Product JSON-LD
+
+## One node on a WooCommerce product page
+
+WooCommerce builds product structured data in `WC_Structured_Data` and prints it with the single product template. Filter the array before it is encoded:
+
+```php
+add_filter(
+    'woocommerce_structured_data_product',
+    function ( $markup, $product ) {
+        if ( ! $product instanceof WC_Product ) {
+            return $markup;
+        }
+        $markup['brand'] = array(
+            '@type' => 'Brand',
+            'name'  => 'Example',
+        );
+        return $markup;
+    },
+    10,
+    2
+);
+```
+
+Only add fields you can see on the page. If a variable product page shows a range, do not force a single variant price into the parent markup.
+
+For a custom storefront, emit one `<script type="application/ld+json">` block from the server. Do not also emit WooCommerce's block if the theme already loaded it.
+
+## Merchant listing shape
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Cotton shirt",
+  "image": "https://shop.example/shirt.jpg",
+  "sku": "SHIRT-BLUE",
+  "description": "Short-sleeve cotton shirt.",
+  "offers": {
+    "@type": "Offer",
+    "url": "https://shop.example/shirt?color=blue",
+    "priceCurrency": "USD",
+    "price": 19.0,
+    "availability": "https://schema.org/InStock"
+  }
+}
+```
+
+`price` is a JSON number. `priceCurrency` is ISO 4217. Merchant listing documentation requires a positive price. Product snippets can use `AggregateOffer` with `lowPrice`, `highPrice`, `priceCurrency`, and `offerCount` when the page shows a range.
+
+## Availability values
+
+Use a single value:
+
+- `https://schema.org/InStock`
+- `https://schema.org/OutOfStock`
+- `https://schema.org/PreOrder`
+- `https://schema.org/BackOrder`
+- `https://schema.org/LimitedAvailability`
+- `https://schema.org/SoldOut`
+- `https://schema.org/Discontinued`
+- `https://schema.org/InStoreOnly`
+- `https://schema.org/OnlineOnly`
+- `https://schema.org/PreSale`
+
+The short name, such as `InStock`, is also accepted by the checker. Map WooCommerce `instock` to `InStock`, `outofstock` to `OutOfStock`, and `onbackorder` to `BackOrder`.
+
+## Checker
+
+`checkProductJsonLd(data, profile)` in `scripts/check-product-jsonld.mjs` reads a Product object or a `@graph` that contains one. Profiles:
+
+- `merchant` requires `name`, `image`, and one positive `Offer`.
+- `snippet` requires `name` and at least one of `review`, `aggregateRating`, or `offers`.
+
+Warnings do not fail the process. Errors do. A warning on a missing `availability` still means you should set it when the page shows stock.
+
+## Breadcrumbs
+
+WooCommerce can also emit `BreadcrumbList`. Add a breadcrumb node only when the visible breadcrumb is absent from existing structured data. Do not invent crumbs that are not on the page.
+
+## What this checker does not do
+
+It does not fetch the image URL, does not call Google's rich results test, and does not validate return-policy or shipping-policy shapes. Those policies have their own required fields in Google's documentation. Add them when the shop displays that policy, and re-read the current field list before shipping them.

package/skills/ecommerce-seo-structured-data/scripts/check-product-jsonld.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const AVAILABILITY = new Set([
+  "BackOrder",
+  "Discontinued",
+  "InStock",
+  "InStoreOnly",
+  "LimitedAvailability",
+  "OnlineOnly",
+  "OutOfStock",
+  "PreOrder",
+  "PreSale",
+  "SoldOut",
+]);
+
+export function checkProductJsonLd(data, profile = "merchant") {
+  const errors = [];
+  const warnings = [];
+  const products = collectProducts(data);
+  if (products.length === 0) {
+    errors.push("No schema.org Product node found.");
+    return { errors, warnings };
+  }
+  products.forEach((product, index) => checkProduct(product, profile, `Product[${index}]`, errors, warnings));
+  return { errors, warnings };
+}
+
+function collectProducts(data) {
+  if (Array.isArray(data)) {
+    return data.flatMap((item) => collectProducts(item));
+  }
+  if (!data || typeof data !== "object") {
+    return [];
+  }
+  const found = [];
+  if (hasType(data, "Product")) {
+    found.push(data);
+  }
+  if (Array.isArray(data["@graph"])) {
+    found.push(...data["@graph"].flatMap((item) => collectProducts(item)));
+  }
+  return found;
+}
+
+function checkProduct(product, profile, label, errors, warnings) {
+  if (!nonEmptyString(product.name)) {
+    errors.push(`${label}: name is required`);
+  }
+  const hasReview = product.review !== undefined;
+  const hasRating = product.aggregateRating !== undefined;
+  const hasOffers = product.offers !== undefined;
+
+  if (product.aggregateRating) {
+    const rating = product.aggregateRating;
+    if (typeof rating.ratingValue !== "number") {
+      errors.push(`${label}: aggregateRating.ratingValue must be a number`);
+    }
+    if (typeof rating.reviewCount !== "number" && typeof rating.ratingCount !== "number") {
+      errors.push(`${label}: aggregateRating needs reviewCount or ratingCount`);
+    }
+  }
+
+  if (profile === "merchant") {
+    if (!hasImage(product.image)) {
+      errors.push(`${label}: merchant listings require image`);
+    }
+    if (!hasOffers) {
+      errors.push(`${label}: merchant listings require offers`);
+    } else {
+      checkMerchantOffers(product.offers, `${label}.offers`, errors, warnings);
+    }
+  } else if (!hasReview && !hasRating && !hasOffers) {
+    errors.push(`${label}: product snippets require review, aggregateRating, or offers`);
+  } else if (hasOffers) {
+    checkSnippetOffers(product.offers, `${label}.offers`, errors, warnings);
+  }
+
+  if (profile === "snippet" && !hasImage(product.image)) {
+    warnings.push(`${label}: image is recommended`);
+  }
+}
+
+function checkMerchantOffers(offers, label, errors, warnings) {
+  if (Array.isArray(offers)) {
+    errors.push(`${label}: merchant listings need one Offer, not an array`);
+    return;
+  }
+  if (hasType(offers, "AggregateOffer")) {
+    errors.push(`${label}: merchant listings need Offer, not AggregateOffer`);
+    return;
+  }
+  if (!hasType(offers, "Offer")) {
+    errors.push(`${label}: offers @type must be Offer`);
+    return;
+  }
+  checkActivePrice(offers, label, errors, { requirePositive: true });
+  checkAvailability(offers, label, warnings);
+}
+
+function checkSnippetOffers(offers, label, errors, warnings) {
+  const list = Array.isArray(offers) ? offers : [offers];
+  for (const [index, offer] of list.entries()) {
+    const itemLabel = Array.isArray(offers) ? `${label}[${index}]` : label;
+    if (hasType(offer, "AggregateOffer")) {
+      if (typeof offer.lowPrice !== "number" || typeof offer.highPrice !== "number") {
+        errors.push(`${itemLabel}: AggregateOffer needs numeric lowPrice and highPrice`);
+      }
+      if (!isoCurrency(offer.priceCurrency)) {
+        errors.push(`${itemLabel}: AggregateOffer.priceCurrency must be a 3-letter ISO 4217 code`);
+      }
+      if (typeof offer.offerCount !== "number" || offer.offerCount < 1) {
+        errors.push(`${itemLabel}: AggregateOffer.offerCount must be a positive number`);
+      }
+      continue;
+    }
+    if (!hasType(offer, "Offer")) {
+      errors.push(`${itemLabel}: offers @type must be Offer or AggregateOffer`);
+      continue;
+    }
+    checkActivePrice(offer, itemLabel, errors, { requirePositive: false });
+    checkAvailability(offer, itemLabel, warnings);
+  }
+}
+
+function checkActivePrice(offer, label, errors, { requirePositive }) {
+  const direct = offer.price;
+  const specified = offer.priceSpecification?.price;
+  const currency = offer.price !== undefined ? offer.priceCurrency : offer.priceSpecification?.priceCurrency;
+  const price = direct !== undefined ? direct : specified;
+  if (typeof price !== "number" || Number.isNaN(price)) {
+    errors.push(`${label}: price must be a JSON number`);
+  } else if (requirePositive && price <= 0) {
+    errors.push(`${label}: merchant listing price must be greater than zero`);
+  } else if (direct !== undefined && specified !== undefined && direct <= 0 && specified > 0) {
+    errors.push(`${label}: offers.price overrides priceSpecification and is not a positive price`);
+  }
+  if (!isoCurrency(currency)) {
+    errors.push(`${label}: priceCurrency must be a 3-letter ISO 4217 code`);
+  }
+}
+
+function checkAvailability(offer, label, warnings) {
+  if (offer.availability === undefined) {
+    warnings.push(`${label}: availability is recommended`);
+    return;
+  }
+  const shortName = String(offer.availability).replace("https://schema.org/", "");
+  if (!AVAILABILITY.has(shortName)) {
+    warnings.push(`${label}: unrecognized availability value ${offer.availability}`);
+  }
+}
+
+function hasImage(image) {
+  if (typeof image === "string" && image.trim() !== "") {
+    return true;
+  }
+  if (Array.isArray(image)) {
+    return image.length > 0 && image.every((item) => hasImage(item));
+  }
+  if (image && typeof image === "object" && typeof image.url === "string") {
+    return image.url.trim() !== "";
+  }
+  return false;
+}
+
+function hasType(node, type) {
+  if (!node || typeof node !== "object") {
+    return false;
+  }
+  const value = node["@type"];
+  return value === type || (Array.isArray(value) && value.includes(type));
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function isoCurrency(value) {
+  return typeof value === "string" && /^[A-Z]{3}$/.test(value);
+}
+
+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("check-product-jsonld.mjs");
+if (isCli) {
+  const file = readOption("--file");
+  const profile = readOption("--profile") ?? "merchant";
+  if (!file || (profile !== "merchant" && profile !== "snippet")) {
+    console.error("Usage: node check-product-jsonld.mjs --file product.json [--profile merchant|snippet]");
+    process.exit(2);
+  }
+  const data = JSON.parse(await readFile(file, "utf8"));
+  const result = checkProductJsonLd(data, profile);
+  for (const warning of result.warnings) {
+    console.error(`WARN ${warning}`);
+  }
+  if (result.errors.length > 0) {
+    for (const error of result.errors) {
+      console.error(`ERROR ${error}`);
+    }
+    process.exit(1);
+  }
+  console.log(`JSON-LD passed the ${profile} profile.`);
+}

package/skills/fraud-and-risk-basics/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fraud-and-risk-basics
+description: "Hold or review risky payments using provider signals, velocity, and 3-D Secure without storing card numbers. Use when adding payment risk checks, a manual review queue, or decline handling for card abuse."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Fraud and risk basics
+
+Use this skill to decide whether a confirmed payment attempt should capture, wait for review, or be declined. The payment skill still verifies the provider. This skill does not collect card numbers and it does not describe how to test stolen cards.
+
+## Procedure
+
+1. Let the payment provider collect the card. You store the provider payment id, AVS result, CVV result, and 3-D Secure result. You do not store PAN or CVV.
+2. Start from the provider's risk recommendation. Do not replace it with a score you computed from a single field.
+3. Add only signals you can explain: velocity, address mismatch, and a mismatch between the paid amount and the order.
+4. Map the outcome to one action: capture, authorize and review, or do not capture.
+5. A review queue shows the order id, amount, currency, and the signals. A person captures or voids. The queue does not auto-capture because it sat overnight.
+
+Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Actions
+
+| Situation | Action |
+| --- | --- |
+| Provider says the payment is acceptable and no local rule fired | Capture, or accept the provider's capture, through the payment skill. |
+| Provider asks for step-up authentication | Send the shopper through 3-D Secure. Do not capture before it finishes. |
+| AVS or CVV is a mismatch and the amount is above the store's review threshold | Authorize if the provider allows it, and queue for review. Do not capture yet. |
+| Velocity rule fires | Same review path. Do not silently decline every later order from that customer without a reason you store. |
+| Amount, currency, or order id does not match | Do not capture. Follow the payment skill's mismatch rule. |
+| Provider declines | Leave the order unpaid. Keep the cart. Do not retry the charge in a loop. |
+
+AVS and CVV are signals. A match is not proof the shopper is the cardholder. A mismatch is not proof of fraud. International addresses often fail AVS. Do not decline every AVS mismatch unless the store has chosen that policy.
+
+## Velocity
+
+Count paid and attempted orders by the identifiers you are allowed to store: account id, shipping address hash, and provider customer id. A default worth configuring is more than three payment attempts from one account in ten minutes, or more than two shipping addresses used by one account in one hour. Tune the numbers. Do not present them as measured fraud rates.
+
+Do not put the full card number into the velocity key.
+
+## Review queue
+
+- Store order id, amount, currency, provider payment id, the signals that fired, and the decision.
+- Capture and void go through the payment provider, idempotently.
+- The reviewer's user id is stored with the decision.
+- A shopper-facing page says the payment is being reviewed. It does not say the order shipped.
+
+## Gotchas
+
+- Capturing before 3-D Secure returns loses the liability shift the provider offered. Wait for the result.
+- A client-supplied `risk: low` field is not a signal. Ignore it.
+- Logging the full webhook body can store a PAN the provider included by mistake. Log ids and result codes.
+- Declining the renewal of every international card will cancel good subscriptions. Use the review path for subscriptions instead of an immediate cancel, unless the store has a written policy.
+
+## Verification
+
+- A mismatched amount is not captured.
+- A 3-D Secure challenge does not capture before the provider reports success.
+- The database and logs for a test payment contain no PAN and no CVV.
+- Two clicks in the review queue do not capture twice.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/fraud-and-risk-basics/evals/examples/review-queue.md

@@ -0,0 +1,3 @@
+When AVS mismatches and the amount is above the store threshold, authorize if the provider allows it and add a review row.
+
+The row stores the order id, amount, and AVS signal. A browser field named as a risk flag is ignored.

package/skills/fraud-and-risk-basics/evals/examples/wait-for-3ds.md

@@ -0,0 +1,3 @@
+Store the provider payment id and the 3-D Secure state.
+
+If authentication is pending, do not capture. Capture only after the provider reports success. Never store the PAN.