hookwright 1.1.1 → 1.2.0

package/README.md

@@ -124,6 +124,17 @@ Each provider owns its gate, signature scheme, field map, payload shape and summ
 - **Razorpay Magic** is root-level, uses capitalised shipping keys (`Shipping_address.Address1`) and sends `line_items_total` as a **string in paise** — matching [Razorpay's abandoned cart webhook docs](https://razorpay.com/docs/payments/magic-checkout/abandoned-cart/). Its gate is "non-empty `abandoned_checkout_url`" rather than an exact value.
 - **Nitro** keys off `eventName` and requires `eventVal.customer.phone` on *every* event, parsed against root `country`. Choose the event with `--event`, or from the menu in the UI.
 
+Nitro's eight events are about different things, so each asks for a different subject:
+
+| event | you pick | cart |
+|---|---|---|
+| `view` | nothing | — |
+| `category_view` | one collection (fetched from Shopify, custom **and** smart) | — |
+| `product_view` | one product | — |
+| `addtocart` · `removefromcart` · `checkout` · `orders/create` · `orders/updated` | products and quantities | ✅ |
+
+A page view has no cart, so it is never asked for a discount; a category view emits the collection's real id, title and URL and carries no line items.
+
 Adding one is a single file in `src/providers/` exporting `buildPayload`, `sign`, `webhookUrl`, `summarize`, a `gate` and a `fieldMap` — see [docs/cashfree-occ.md](docs/cashfree-occ.md).
 
 ## Development
@@ -131,7 +142,7 @@ Adding one is a single file in `src/providers/` exporting `buildPayload`, `sign`
 ```bash
 npm install
 npm run dev     # esbuild watch
-npm test        # 179 tests, no network required
+npm test        # 185 tests, no network required
 npm start       # build + run
 ```
 

package/dist/cli.js

@@ -24,7 +24,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "hookwright",
-      version: "1.1.1",
+      version: "1.2.0",
       description: "Build real, signed e-commerce webhooks from a live Shopify catalogue \u2014 interactive terminal UI, no backend",
       keywords: [
         "webhook",
@@ -407,6 +407,16 @@ function cartPermalink(domain, items) {
 function money2(value) {
   return Math.round(Number(value) * 100) / 100;
 }
+function normalizeCollection(collection) {
+  return {
+    id: String(collection.id),
+    title: collection.title,
+    handle: collection.handle,
+    kind: collection.kind,
+    image: collection.image?.src ?? "",
+    productsCount: collection.products_count ?? null
+  };
+}
 
 // src/providers/cashfree-occ.mjs
 var GATE_PATH = "type";
@@ -757,15 +767,18 @@ var razorpay_magic_default = {
 // src/providers/nitro.mjs
 import crypto3 from "node:crypto";
 var EVENTS = [
-  { eventName: "view", type: "nitro_view", label: "Page View" },
-  { eventName: "category_view", type: "nitro_category_view", label: "Category View" },
-  { eventName: "product_view", type: "nitro_product_view", label: "Product View" },
-  { eventName: "addtocart", type: "nitro_addtocart", label: "Add To Cart" },
-  { eventName: "removefromcart", type: "nitro_removefromcart", label: "Remove From Cart" },
-  { eventName: "checkout", type: "nitro_checkout", label: "Checkout" },
-  { eventName: "orders/create", type: "nitro_orders_create", label: "Order Created" },
-  { eventName: "orders/updated", type: "nitro_orders_updated", label: "Order Updated" }
+  { eventName: "view", type: "nitro_view", label: "Page View", selection: "none", subject: "a page, no product" },
+  { eventName: "category_view", type: "nitro_category_view", label: "Category View", selection: "collection", subject: "one collection" },
+  { eventName: "product_view", type: "nitro_product_view", label: "Product View", selection: "product", subject: "one product" },
+  { eventName: "addtocart", type: "nitro_addtocart", label: "Add To Cart", selection: "cart", subject: "cart contents" },
+  { eventName: "removefromcart", type: "nitro_removefromcart", label: "Remove From Cart", selection: "cart", subject: "cart contents" },
+  { eventName: "checkout", type: "nitro_checkout", label: "Checkout", selection: "cart", subject: "cart contents" },
+  { eventName: "orders/create", type: "nitro_orders_create", label: "Order Created", selection: "cart", subject: "ordered items" },
+  { eventName: "orders/updated", type: "nitro_orders_updated", label: "Order Updated", selection: "cart", subject: "ordered items" }
 ];
+function selectionFor(eventName) {
+  return EVENTS.find((e) => e.eventName === eventName)?.selection ?? "cart";
+}
 var DEFAULT_EVENT = "addtocart";
 var COMMON_FIELDS = [
   { source: "eventName", target: "\xABgate\xBB", required: true, note: "must match the schema exactly" },
@@ -783,8 +796,9 @@ var FIELD_MAPS = {
   category_view: [
     ...COMMON_FIELDS,
     ...PAGE_FIELDS,
-    { source: "eventVal.resource_id", target: "eventVal.resource_id", required: true },
+    { source: "eventVal.resource_id", target: "eventVal.resource_id", required: true, note: "the collection id" },
     { source: "eventVal.resource", target: "eventVal.resource" },
+    { source: "eventVal.title", target: "collection name", required: true },
     { source: "eventVal.domain", target: "eventVal.domain" }
   ],
   product_view: [
@@ -848,6 +862,17 @@ var EDITABLE = {
     { group: "Page", path: "eventVal.l", label: "Location URL" },
     { group: "Page", path: "eventVal._ss", label: "Session id" }
   ],
+  collection: [
+    { group: "Collection", path: "eventVal.resource_id", label: "Collection id" },
+    { group: "Collection", path: "eventVal.title", label: "Collection name" },
+    { group: "Collection", path: "eventVal.l", label: "Collection URL" }
+  ],
+  product: [
+    { group: "Product", path: "eventVal.resource_id", label: "Product id" },
+    { group: "Product", path: "eventVal.title", label: "Product title" },
+    { group: "Product", path: "eventVal.price", label: "Price", type: "number" },
+    { group: "Product", path: "eventVal.image", label: "Image URL" }
+  ],
   cart: [
     { group: "Cart", path: "eventVal.cart_value", label: "Cart value", type: "number" },
     { group: "Cart", path: "eventVal.init_cart", label: "Init cart" },
@@ -866,7 +891,8 @@ var EDITABLE = {
 function editableFieldsFor(eventName) {
   const e = EDITABLE;
   if (eventName === "view") return [...e.common, ...e.page];
-  if (eventName === "category_view" || eventName === "product_view") return [...e.common, ...e.page];
+  if (eventName === "category_view") return [...e.common, ...e.page, ...e.collection];
+  if (eventName === "product_view") return [...e.common, ...e.page, ...e.product];
   if (eventName === "addtocart" || eventName === "removefromcart") return [...e.common, ...e.cart];
   if (eventName === "checkout") return [...e.common, ...e.cart];
   if (eventName.startsWith("orders/")) return [...e.common, ...e.order];
@@ -919,17 +945,22 @@ function buildPayload3(ctx) {
   let eventVal;
   switch (eventName) {
     case "view":
-      eventVal = { ...page, page: "home", l: `https://${domain}`, customer };
+      eventVal = { page: "home", h: domain, l: `https://${domain}`, _ss: session, domain, customer };
       break;
-    case "category_view":
+    case "category_view": {
+      const collection = ctx.collection;
       eventVal = {
         ...page,
+        page: "collection",
         resource: "collection",
-        resource_id: String(first?.product?.id ?? ""),
-        l: `https://${domain}/collections/all`,
+        resource_id: String(collection?.id ?? ""),
+        title: collection?.title,
+        image: collection?.image || void 0,
+        l: collection?.handle ? `https://${domain}/collections/${collection.handle}` : `https://${domain}/collections/all`,
         customer
       };
       break;
+    }
     case "product_view":
       eventVal = {
         ...page,
@@ -1029,6 +1060,7 @@ var nitro_default = {
   fieldMapFor: (eventName) => FIELD_MAPS[eventName] ?? FIELD_MAPS[DEFAULT_EVENT],
   editableFields: editableFields3,
   editableFieldsFor,
+  selectionFor,
   buildPayload: buildPayload3,
   sign: sign3,
   webhookUrl: webhookUrl3,
@@ -1378,6 +1410,20 @@ var ShopifyClient = class {
     const { json } = await this.request("/products/count.json");
     return json?.count ?? 0;
   }
+  /**
+   * Collections, from both endpoints Shopify splits them across: custom
+   * (manually curated) and smart (rule based). Either can back a category page.
+   */
+  async collections({ limit = 50, title } = {}) {
+    const [custom, smart] = await Promise.all([
+      this.request("/custom_collections.json", { query: { limit, title } }).catch(() => ({ json: null })),
+      this.request("/smart_collections.json", { query: { limit, title } }).catch(() => ({ json: null }))
+    ]);
+    return [
+      ...(custom.json?.custom_collections ?? []).map((c2) => ({ ...c2, kind: "custom" })),
+      ...(smart.json?.smart_collections ?? []).map((c2) => ({ ...c2, kind: "smart" }))
+    ];
+  }
 };
 function normalizeDomain(domain) {
   return String(domain).trim().replace(/^https?:\/\//, "").replace(/\/.*$/, "").toLowerCase();
@@ -1403,6 +1449,11 @@ async function fetchCatalogue(cfg, { search, pages = 1, limit = 50 } = {}) {
   const raw = await client.products({ title: search, pages, limit });
   return raw.map(normalizeProduct).filter((p) => p.variants.length);
 }
+async function fetchCollections(cfg, { search, limit = 50 } = {}) {
+  const client = new ShopifyClient(cfg.shopify);
+  const raw = await client.collections({ title: search, limit });
+  return raw.map(normalizeCollection);
+}
 function autoSelect(products, count = 1) {
   return products.slice(0, count).map((product) => ({
     product,
@@ -1808,7 +1859,7 @@ function loadPayload(file) {
 }
 
 // src/core/build.mjs
-function draftPayload({ cfg, providerId = "cashfree-occ", items, discount = 0, phone, eventName }) {
+function draftPayload({ cfg, providerId = "cashfree-occ", items, discount = 0, phone, eventName, collection }) {
   const provider = getProvider(providerId);
   const event = eventName ?? provider.defaultEvent;
   const resolvedPhone = phone ?? cfg.customer.phone;
@@ -1818,6 +1869,7 @@ function draftPayload({ cfg, providerId = "cashfree-occ", items, discount = 0, p
     items,
     discount,
     eventName: event,
+    collection,
     phone: parsed.ok ? parsed.value : String(resolvedPhone ?? "")
   });
   const editable = provider.editableFieldsFor ? provider.editableFieldsFor(event) : provider.editableFields;
@@ -1833,14 +1885,16 @@ function applyEdits(payload, fields, edits) {
   }
   return payload;
 }
-async function buildPayload4({ cfg, providerId = "cashfree-occ", items, discount = 0, phone, checkImageUrls = true, payload: prebuilt, eventName }) {
-  if (!items?.length) throw new ConfigError("no products selected");
+async function buildPayload4({ cfg, providerId = "cashfree-occ", items = [], discount = 0, phone, checkImageUrls = true, payload: prebuilt, eventName, collection }) {
+  const provider0 = getProvider(providerId);
+  const needsItems = !provider0.selectionFor || ["cart", "product"].includes(provider0.selectionFor(eventName ?? provider0.defaultEvent));
+  if (needsItems && !items.length) throw new ConfigError("no products selected");
   const provider = getProvider(providerId);
   const resolvedPhone = phone ?? cfg.customer.phone;
   const parsed = toE164(resolvedPhone, cfg.customer.countryCode);
   if (!parsed.ok) throw new ConfigError(`phone is unusable: ${parsed.reason}`);
   const event = eventName ?? provider.defaultEvent;
-  const payload = prebuilt ?? provider.buildPayload({ config: cfg, items, discount, phone: parsed.value, eventName: event });
+  const payload = prebuilt ?? provider.buildPayload({ config: cfg, items, discount, phone: parsed.value, eventName: event, collection });
   const body = JSON.stringify(payload);
   const report = await runAll({ payload, body, provider, config: cfg, checkImageUrls, eventName: event });
   const summary = provider.summarize ? provider.summarize(payload) : {};
@@ -2040,6 +2094,7 @@ import { jsx as jsx8, jsxs as jsxs8 } from "react/jsx-runtime";
 var STEP = {
   EVENT: "event",
   LOADING: "loading",
+  COLLECTION: "collection",
   PICK: "pick",
   VARIANT: "variant",
   QUANTITY: "quantity",
@@ -2060,6 +2115,8 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
   const [eventName, setEventName] = useState(provider.defaultEvent);
   const [step, setStep] = useState(multiEvent ? STEP.EVENT : STEP.LOADING);
   const [products, setProducts] = useState([]);
+  const [collections, setCollections] = useState([]);
+  const [collection, setCollection] = useState(null);
   const [chosen, setChosen] = useState([]);
   const [cursor, setCursor] = useState(0);
   const [items, setItems] = useState([]);
@@ -2079,6 +2136,7 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
       case STEP.EVENT:
         return onDone();
       case STEP.PICK:
+      case STEP.COLLECTION:
         return multiEvent ? setStep(STEP.EVENT) : onDone();
       case STEP.VARIANT:
         if (cursor === 0) return setStep(STEP.PICK);
@@ -2090,6 +2148,8 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
         setItems(items.slice(0, -1));
         return stepInto(cursor - 1);
       case STEP.DISCOUNT: {
+        if (selection === "none") return multiEvent ? setStep(STEP.EVENT) : onDone();
+        if (selection === "collection") return setStep(STEP.COLLECTION);
         const last = chosen.length - 1;
         setItems(items.slice(0, -1));
         return stepInto(last);
@@ -2130,9 +2190,36 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
     if (input === "j" && built) copy(built.body).then((r) => setCopied({ ...r, what: "payload JSON" }));
     if ((input === "s" || key.return) && built?.report.ok) doSend();
   });
+  const selection = provider.selectionFor ? provider.selectionFor(eventName) : "cart";
   useEffect(() => {
     if (step === STEP.EVENT) return;
     let alive = true;
+    if (selection === "none") {
+      startReview(0);
+      return () => {
+        alive = false;
+      };
+    }
+    if (selection === "collection") {
+      fetchCollections(config).then((list) => {
+        if (!alive) return;
+        if (!list.length) {
+          setError({ message: "this store has no collections", hint: "create one in Shopify, or pick a different event" });
+          setStep(STEP.ERROR);
+          return;
+        }
+        setCollections(list);
+        setStep(STEP.COLLECTION);
+      }).catch((err) => {
+        if (alive) {
+          setError({ message: err.message, hint: err.hint });
+          setStep(STEP.ERROR);
+        }
+      });
+      return () => {
+        alive = false;
+      };
+    }
     fetchCatalogue(config).then((list) => {
       if (!alive) return;
       if (!list.length) {
@@ -2150,11 +2237,12 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
     return () => {
       alive = false;
     };
-  }, [step === STEP.EVENT]);
+  }, [step === STEP.EVENT, eventName]);
   const advance = (nextItems, nextCursor) => {
     if (nextCursor >= chosen.length) {
       setItems(nextItems);
-      setStep(STEP.DISCOUNT);
+      if (selection === "cart") setStep(STEP.DISCOUNT);
+      else startReview(0, collection, nextItems);
       return;
     }
     setItems(nextItems);
@@ -2167,6 +2255,24 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
       setStep(STEP.QUANTITY);
     }
   };
+  const onSingleProductPicked = (id) => {
+    const product = products.find((p) => p.id === id);
+    if (!product) return;
+    setChosen([product]);
+    setCursor(0);
+    setItems([]);
+    if (product.variants.length > 1) setStep(STEP.VARIANT);
+    else {
+      setPendingVariant(product.variants[0]);
+      setStep(STEP.QUANTITY);
+    }
+  };
+  const onCollectionPicked = (id) => {
+    const picked = collections.find((c2) => c2.id === id);
+    if (!picked) return;
+    setCollection(picked);
+    startReview(0, picked);
+  };
   const onProductsPicked = (ids) => {
     const picked = ids.map((id) => products.find((p) => p.id === id)).filter(Boolean);
     if (!picked.length) return;
@@ -2191,10 +2297,16 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
     const nextItems = [...items, { product, variant: pendingVariant, quantity: qty }];
     advance(nextItems, cursor + 1);
   };
-  const onDiscount = (raw) => {
-    const discount = Math.max(0, Number.parseFloat(raw) || 0);
+  const startReview = (discount, chosenCollection = collection, chosenItems = items) => {
     try {
-      const next = draftPayload({ cfg: config, providerId, items, discount, eventName });
+      const next = draftPayload({
+        cfg: config,
+        providerId,
+        items: chosenItems,
+        discount,
+        eventName,
+        collection: chosenCollection
+      });
       setDraft({ ...next, discount });
       setStep(STEP.MODE);
     } catch (err) {
@@ -2202,9 +2314,10 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
       setStep(STEP.ERROR);
     }
   };
+  const onDiscount = (raw) => startReview(Math.max(0, Number.parseFloat(raw) || 0));
   const finalise = (payload) => {
     setStep(STEP.BUILDING);
-    buildPayload4({ cfg: config, providerId, items, discount: draft.discount, payload, eventName }).then(async (result) => {
+    buildPayload4({ cfg: config, providerId, items, discount: draft.discount, payload, eventName, collection }).then(async (result) => {
       setBuilt(result);
       let req = null;
       let command = "";
@@ -2278,9 +2391,37 @@ function Build({ config, providerId = "cashfree-occ", onDone }) {
       ) })
     ] }),
     step === STEP.LOADING && /* @__PURE__ */ jsx8(Spinner, { label: `fetching live products from ${store}\u2026` }),
-    step === STEP.PICK && /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", children: [
+    step === STEP.COLLECTION && /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsx8(Text8, { children: "Which collection was viewed?" }),
+      /* @__PURE__ */ jsx8(Box8, { marginTop: 1, children: /* @__PURE__ */ jsx8(
+        Select4,
+        {
+          visibleOptionCount: 10,
+          options: collections.map((c2) => ({
+            label: `${truncate(c2.title, 40).padEnd(41)} ${c2.productsCount != null ? `${c2.productsCount} products` : c2.kind}`,
+            value: c2.id
+          })),
+          onChange: onCollectionPicked
+        }
+      ) })
+    ] }),
+    step === STEP.PICK && selection === "product" && /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsx8(Text8, { children: "Which product was viewed?" }),
+      /* @__PURE__ */ jsx8(Box8, { marginTop: 1, children: /* @__PURE__ */ jsx8(
+        Select4,
+        {
+          visibleOptionCount: 10,
+          options: products.map((p) => ({
+            label: `${truncate(p.title, 44).padEnd(45)} ${money(p.variants[0]?.price, currency)}`,
+            value: p.id
+          })),
+          onChange: onSingleProductPicked
+        }
+      ) })
+    ] }),
+    step === STEP.PICK && selection !== "product" && /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", children: [
       /* @__PURE__ */ jsxs8(Text8, { children: [
-        `Select the products in the abandoned cart `,
+        `Select the products in the cart `,
         /* @__PURE__ */ jsx8(Text8, { color: palette.dim, children: "(space toggles \xB7 enter confirms)" })
       ] }),
       /* @__PURE__ */ jsx8(Box8, { marginTop: 1, children: /* @__PURE__ */ jsx8(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookwright",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Build real, signed e-commerce webhooks from a live Shopify catalogue — interactive terminal UI, no backend",
   "keywords": [
     "webhook",