Initial import of zappier-edge from zapier monorepo

docs/CUSTOMER-PORTAL.md

@@ -0,0 +1,98 @@
+# Customer Portal Walkthrough
+
+The self-service portal for end-user customers at `/portal`: account setup,
+two-factor authentication, usage and balance, invoices, reloads, and API
+documentation.
+
+> Audience: your API customers. For the company side see `ACCOUNTING.md` and
+> `USER-MANAGEMENT.md`.
+
+---
+
+## 1. Create your account
+
+Open `http://<host>:<port>/portal` and choose **Create an account**.
+
+![Sign up](screenshots/portal-signup.png)
+
+- Name, email, and a password of at least 8 characters.
+- You start on the **Free** plan and get an **API key immediately**.
+- If the company already created an account for you (you received an API key
+  by email), sign up with the **same email address** — your existing account,
+  plan, and API key are kept and the password you choose is attached to it.
+
+Sign-in afterwards is email + password on the same screen.
+
+![Sign in](screenshots/portal-login.png)
+
+---
+
+## 2. Dashboard
+
+![Dashboard](screenshots/portal-dashboard.png)
+
+- **Usage this month** — gross usage since the 1st (UTC).
+- **Included credit** — how much of your plan's monthly credit was consumed.
+- **Billable** — what exceeds the credit (what you'd be invoiced today).
+- **Prepaid balance** — funds available for automatic invoice payment.
+- **Your API key** — copy it, or **regenerate** it. Regenerating invalidates
+  the old key immediately; use it as the `x-api-key` header.
+
+## 3. Usage & pricing
+
+The **API & pricing** tab shows the live rate card (free / fixed / variable
+per endpoint, with size-based pricing for storage) and every plan's multiplier
+and monthly credit — the same numbers the server bills from.
+
+![API & pricing](screenshots/portal-docs.png)
+
+The interactive API reference (Swagger UI) is linked at the top (`/docs`).
+
+## 4. Invoices
+
+![Invoices](screenshots/portal-invoices.png)
+
+Your invoice history with status (`draft`, `issued`, `paid`), totals, credit,
+amount due, and due date. **View / print** opens a print-ready invoice — use
+the browser's **Print → Save as PDF** for a copy.
+
+![Printable invoice](screenshots/portal-invoice-html.png)
+
+Only your own invoices are visible; other customers' ids return "not found".
+
+## 5. Billing: reloads & email invoicing
+
+![Billing](screenshots/portal-billing.png)
+
+- **Reload balance** — add $1–$10,000. Your prepaid balance is **drawn down
+  automatically** when an invoice is issued: if it fully covers the amount
+  due, the invoice is paid instantly.
+- **Email invoicing** — receive a copy of each new invoice by email.
+
+## 6. Security: two-factor authentication
+
+On the **Security** tab, click **Set up 2FA**:
+
+![2FA setup](screenshots/portal-2fa-setup.png)
+
+1. Scan the QR code with any authenticator app (or type the secret manually).
+2. Enter the 6-digit code it shows to enable 2FA.
+
+From then on, sign-in requires the password **and** the current code. You can
+disable 2FA with a valid code from the same tab. Sessions expire after 7 days.
+
+---
+
+## Portal API reference
+
+Session-based (`Authorization: Bearer <token>` from signup/login):
+
+- `POST /portal/api/signup` · `POST /portal/api/login` · `POST /portal/api/logout`
+- `GET /portal/api/me` · `POST /portal/api/api-key`
+- `GET /portal/api/usage` · `GET /portal/api/pricing`
+- `GET /portal/api/invoices` · `GET /portal/api/invoices/:id[?format=html]`
+- `POST /portal/api/2fa/setup|enable|disable`
+- `POST /portal/api/reload` · `PUT /portal/api/email-invoicing`
+
+Security notes: passwords are stored as scrypt hashes; TOTP secrets are only
+shown during setup; no hash or secret is ever returned by the API.