hookwright 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# hookwright
+
+Build **real, signed e-commerce webhooks** from a live Shopify catalogue — and send them to your own endpoint.
+
+Nothing in the payload is invented. Product titles, variant ids, prices and image URLs all come from your Shopify store through the Admin API; totals are computed from those real prices. It is a terminal app built with [Ink](https://github.com/vadimdemedes/ink) — there is no backend and no service to sign up for.
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ hookwright                                   Addy Fashion │
+╰──────────────────────────────────────────────────────────────╯
+ real catalogue → signed provider webhooks
+
+❯ Setup             Shopify and webhook destination
+  Integrations      build and send a provider webhook
+  History           review or re-send a saved payload
+  Doctor            check credentials and connectivity
+  Clear             remove cached data
+  Quit
+```
+
+## Install
+
+```bash
+npx hookwright          # no install
+npm i -g hookwright     # or install it
+```
+
+Requires Node 20+.
+
+## Quick start
+
+```bash
+hookwright              # interactive UI — starts in the setup wizard on first run
+```
+
+**Setup** and **Integrations** sit side by side. Setup is global — configure it once and every integration uses it:
+
+| 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 |
+| **Customer** | the shopper the abandoned cart belongs to |
+| **Defaults** | currency, platform |
+
+Stored in `~/.config/hookwright/config.json`, mode `0600` — it holds a Shopify token and a signing secret.
+
+Then **Integrations → Cashfree One Click Checkout** builds the payload:
+
+1. Products are fetched live from your store and listed — pick what goes in the cart
+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
+
+## 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 --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
+hookwright send --file ~/.local/state/hookwright/payloads/2026-…json
+hookwright doctor --json
+hookwright history
+hookwright clear --payloads --yes        # or --logs / --shop-cache / --disconnect / --all
+```
+
+Exit codes: `0` ok · `1` configuration/usage · `2` pre-flight failed · `3` endpoint rejected the webhook.
+
+## What it checks before sending
+
+A generated payload is useless if the receiver silently drops it, so every build runs pre-flight:
+
+- **Schema gate** — `type` must equal `ABANDONED_CHECKOUT`, or the consumer ignores the event without an error.
+- **JSON round-trip** — receivers that verify `HMAC(secret, timestamp + JSON.stringify(parsedBody))` can only match if `JSON.stringify(JSON.parse(raw)) === raw`. If it doesn't, you're told the exact byte offset.
+- **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.
+- **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`.
+
+## Safety
+
+- The config file is `0600` and secrets are redacted from the log file.
+- Dry-run prints a `curl` that reproduces the request exactly, using `--data-binary` so the signed bytes are preserved.
+- Payload history lives in `~/.local/state/hookwright/payloads/` and can be re-sent (re-signed with a fresh timestamp).
+
+Override both locations with `HOOKWRIGHT_HOME`, or point at one config with `--config <path>` / `HOOKWRIGHT_CONFIG`.
+
+**Clear** removes local state — saved payloads, the activity log, the cached store record, the Shopify credentials, or everything back to first-run state. It shows exactly what will be deleted and asks before doing it.
+
+## Providers
+
+| provider | signature | headers |
+|---|---|---|
+| `cashfree-occ` | base64 HMAC-SHA256 over `timestamp + body` | `x-webhook-signature`, `x-webhook-timestamp` |
+
+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).
+
+## Development
+
+```bash
+npm install
+npm run dev     # esbuild watch
+npm test        # 54 tests, no network required
+npm start       # build + run
+```
+
+The test suite includes an end-to-end run against a stub Shopify API and a stub consumer that verifies the signature exactly as the real one does, asserting the transmitted bytes are identical to the signed bytes.
+
+## License
+
+MIT