Initial import of zappier-edge from zapier monorepo

2026-09-11 16:05:17 -04:00 · 2026-09-11 16:05:17 -04:00 · 2e035b1e80
commit 2e035b1e80
128 changed files with 20545 additions and 0 deletions
--- a/docs/WALKTHROUGH.md
+++ b/docs/WALKTHROUGH.md
@ -0,0 +1,154 @@
+# Zappier — Step-by-Step Usage Walkthrough
+
+**Version:** 0.1.0 · **Last updated:** 2026-07-27
+
+A full guided tour: from starting the server to pricing changes, customer
+creation, and live API calls. Every step shows the real screen you should see.
+Companion documents: [USER-MANUAL.md](USER-MANUAL.md) ·
+[DEVELOPER.md](DEVELOPER.md).
+
+---
+
+## Step 1 — Start the server
+
+```bash
+cd /Users/marchon/zappier
+npm install   # first time only
+npm run dev
+```
+
+Wait for the two "listening" lines:
+
+![Start the server](walkthrough/01-start-server.png)
+
+---
+
+## Step 2 — Open the admin UI and sign in
+
+Go to **http://localhost:3000/admin**. You'll see the sign-in screen:
+
+![Sign in](walkthrough/02-login.png)
+
+Two accounts are available:
+
+| Username | Password | Purpose |
+|---|---|---|
+| `admin` | the `ADMIN_KEY` env value (default `admin-dev-key`) | Primary operator |
+| `demo` | `$$$Adm1n###` | Demo / stakeholder access |
+
+> Override either credential with the `ADMIN_USER`, `ADMIN_KEY`,
+> `DEMO_ADMIN_USER`, and `DEMO_ADMIN_PASSWORD` environment variables.
+
+---
+
+## Step 3 — The rate card
+
+After sign-in you land on the **Rate card** — one row per API endpoint with
+its price in cents:
+
+![Rate card](walkthrough/03-rate-card.png)
+
+- `status`, `storage-list` — **free**
+- `transform` — **fixed** price per call
+- `storage` — **variable**: base + per-KB metadata + per-MB attachments
+
+---
+
+## Step 4 — Change a price
+
+Edit any cent field — here `transform` is changed from **4¢ to 6¢** — and click
+**Save**. The change is live on the very next API call; no restart, no deploy.
+
+![Edit a price](walkthrough/04-edit-price.png)
+
+After saving, the table re-reads from the server and shows the new value:
+
+![Price saved](walkthrough/04b-saved-toast.png)
+
+---
+
+## Step 5 — Customer types
+
+Click **Customer types** in the sidebar. Each type is a pricing tier:
+a **multiplier** applied to every list price and a **monthly credit** of free
+included usage (cents).
+
+![Customer types](walkthrough/05-tiers.png)
+
+---
+
+## Step 6 — Add a customer type
+
+Fill the **Add customer type** form — here `edu` / Education / ×0.6 — and click
+**Add**. The new type appears immediately and can be assigned to customers.
+
+![Add customer type](walkthrough/06-add-tier.png)
+
+> New types start with 0 monthly credit — edit the row and **Save** to grant one.
+
+---
+
+## Step 7 — Customers
+
+Click **Customers** in the sidebar. This is where accounts live: their type,
+and an optional **multiplier override** for per-customer deals (blank =
+inherit from type).
+
+![Customers](walkthrough/07-customers.png)
+
+---
+
+## Step 8 — Create a customer and copy the API key
+
+Enter a name, pick a type, click **Create**. The API key appears **once** in
+the notification at the bottom-right — copy it and send it to the customer;
+it is never shown again.
+
+![API key shown once](walkthrough/08b-api-key-toast.png)
+
+The new customer appears in the table right away:
+
+![Customer created](walkthrough/08-create-customer.png)
+
+---
+
+## Step 9 — Explore the interactive API docs
+
+Open **http://localhost:3000/docs** — full Swagger docs with a "Try it out"
+console. Click **Authorize** and paste a customer API key to make live calls
+from the browser.
+
+![API docs](walkthrough/09-api-docs.png)
+
+---
+
+## Step 10 — Make an API call
+
+Call the API with a customer key. Every priced response includes its **quote**,
+so the cost of every call is transparent:
+
+![API call with quote](walkthrough/10-api-call.png)
+
+Note how the quote reflects the walkthrough itself: the 6¢ price set in step 4,
+halved to 3¢ by Grace's Pro multiplier.
+
+---
+
+## Step 11 — Check usage and credits
+
+Customers can check their own month-to-date usage anytime:
+
+![Usage summary](walkthrough/11-usage.png)
+
+`includedCents` is covered by the type's monthly credit; `billableCents` is
+what the daily billing job would report to Stripe right now.
+
+---
+
+## Where to go next
+
+- **Daily billing** runs automatically at 06:17 ET — see
+  [USER-MANUAL.md §6](USER-MANUAL.md#6-billing-operations-stripe) for the
+  Stripe meter/product/price setup and how to verify a run.
+- **Troubleshooting:** [USER-MANUAL.md §9](USER-MANUAL.md#9-troubleshooting).
+- **Internals:** [DEVELOPER.md](DEVELOPER.md).