hookwright 1.0.0 → 1.1.1

package/README.md

@@ -38,7 +38,7 @@ hookwright              # interactive UI — starts in the setup wizard on first
 | Setup | asks for |
 |---|---|
 | **Shopify** | store domain + Admin API access token (needs `read_products`). Verifies immediately and picks up currency, country, province and contact details from the store record |
-| **Webhook** | just the destination URL, plus the signing secret |
+| **Webhook** | one destination URL + signing secret **per integration** — Cashfree, Razorpay Magic and Nitro each get their own |
 | **Customer** | the shopper the abandoned cart belongs to |
 | **Defaults** | currency, platform |
 
@@ -50,14 +50,31 @@ Then **Integrations → Cashfree One Click Checkout** builds the payload:
 2. Variant and quantity per product
 3. Cart discount
 4. Either accept the suggested values, or **review every field** — each one is pre-filled with the generated suggestion, enter accepts it, typing replaces it
-5. Pre-flight report, then send
+5. Pre-flight report — every check, the full field coverage table, the signed request and the complete payload
+6. A **ready-to-paste `curl` is copied to your clipboard** automatically, then send
+
+The report page is a compact status board with a command bar — `s` send · `c` copy curl · `j` copy json · `u` curl · `p` payload · `f` fields · `v` checks · `r` request. Panels are collapsed by default, so you see the verdict first and the detail only when you ask for it.
+
+`esc` walks back one step at a time through the whole flow (report → mode → discount → quantity → variant → products → event), and only leaves the integration from the first step.
+
+### The curl is built for pasting
+
+The command is emitted in the exact shape Postman itself exports — `curl --location --request POST` with unindented `--header` / `--data` lines — and the body is inlined, never `@file`. Drop it straight into **Postman → Import → Raw text**, a colleague's terminal, or a bug report.
+
+Single quotes inside product titles (`Levi's 501`) are escaped, and the signature travels with the exact body it signs, so a pasted command verifies precisely as the original request would.
+
+Two things keep this honest: a test that executes the generated command verbatim against a receiver doing real HMAC verification, and a test that runs it through **`curl-to-postmanv2`** — the same parser Postman uses for Raw-text import — asserting the URL, method, every header and a byte-identical body all survive.
+
+In the report screen: `c` re-copies the curl · `j` copies the raw payload JSON · `p` toggles the full payload view.
 
 ## Headless usage
 
 Every command works without a TTY, for CI or scripting:
 
 ```bash
-hookwright build --items 2                 # build from the 2 first products
+hookwright build --items 2                              # cashfree-occ by default
+hookwright build --provider razorpay-magic --items 2
+hookwright build --provider nitro --event orders/create
 hookwright build --search "cold brew"      # only products matching a title
 hookwright build --items 3 --discount 250 --send
 hookwright send --dry-run                  # print the request + curl, send nothing
@@ -78,6 +95,7 @@ A generated payload is useless if the receiver silently drops it, so every build
 - **Phone** — parsed to E.164 using the shipping `country_code`, the same way the consumer does.
 - **Phone allow-list** — refuses to build for a number that isn't an approved test handset, so a live shopper can never be messaged by a test run.
 - **Product images** — every `image_url` is `HEAD`-checked; unreachable images fail the build.
+- **Endpoint exists** — before a signed payload is handed over, the destination is verified: the hostname must resolve, something must accept a TCP connection on the port, and the path must not 404. A typo'd host is caught here instead of looking like a silent delivery failure. The probe is `OPTIONS`, falling back to `HEAD` — **never a POST and never a body**, so it cannot create data on the receiving system. Timeouts and servers that reject `OPTIONS` warn rather than block. Skip with `--no-endpoint-check`, override with `--force`.
 - **Field coverage** — a table of every field the consumer reads, what it maps to, and its value. Missing required fields are flagged in red.
 
 Sending is also blocked when the target looks like production, unless `--force`.
@@ -94,18 +112,26 @@ Override both locations with `HOOKWRIGHT_HOME`, or point at one config with `--c
 
 ## Providers
 
-| provider | signature | headers |
-|---|---|---|
-| `cashfree-occ` | base64 HMAC-SHA256 over `timestamp + body` | `x-webhook-signature`, `x-webhook-timestamp` |
+| provider | signature | headers | events |
+|---|---|---|---|
+| `cashfree-occ` | base64 HMAC-SHA256 over `timestamp + body` | `x-webhook-signature`, `x-webhook-timestamp` | abandoned checkout |
+| `razorpay-magic` | hex HMAC-SHA256 over the body | `x-razorpay-signature` | abandoned checkout |
+| `nitro` | static bearer token, no body signature | `authorization` | 8 — page view, category view, product view, add to cart, remove from cart, checkout, order created, order updated |
+
+Each provider owns its gate, signature scheme, field map, payload shape and summary, so nothing is assumed across them:
+
+- **Cashfree OCC** nests everything under `data`; currency is read from `line_items[0]`, not the root.
+- **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.
 
-Adding one is a single file in `src/providers/` exporting `buildPayload`, `sign`, `webhookUrl`, a `gate` and a `fieldMap` — see [docs/cashfree-occ.md](docs/cashfree-occ.md).
+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
 
 ```bash
 npm install
 npm run dev     # esbuild watch
-npm test        # 54 tests, no network required
+npm test        # 179 tests, no network required
 npm start       # build + run
 ```