Initial import of zappier-edge from zapier monorepo

docs/USER-MANAGEMENT.md

@@ -0,0 +1,111 @@
+# User Management Walkthrough
+
+How the company manages pricing, customer types, and customer accounts in the
+**admin console** at `/admin`.
+
+> Audience: operations staff. For invoicing/reports see `ACCOUNTING.md`; for
+> the end-user view see `CUSTOMER-PORTAL.md`.
+
+---
+
+## 1. Admin accounts
+
+Admin sign-ins live in the `admin_users` table — passwords are stored as
+**scrypt hashes**, never in plain text. On an empty database the table is
+seeded from the environment:
+
+| Account | Username | Password (dev default) | Env override |
+|---|---|---|---|
+| Primary admin | `admin` | `admin-dev-key` | `ADMIN_USER` / `ADMIN_KEY` |
+| Demo / stakeholder | `demo` | `$$$Adm1n###` | `DEMO_ADMIN_USER` / `DEMO_ADMIN_PASSWORD` |
+
+The seed runs **only when the table is empty** — after that, accounts are
+managed in the console and survive restarts (SQLite) and env changes.
+
+Sign-in issues a session token; API access is also possible with the
+`x-admin-key: $ADMIN_KEY` header (used by automation).
+
+## 2. Users tab (admin account management)
+
+The **Users** tab lists every admin account and manages their lifecycle:
+
+![Admin users](screenshots/admin-users.png)
+
+- **Create** — username (letters, digits, `.` `_` `-`) plus a password of at
+  least 8 characters. The new account can sign in immediately.
+- **Deactivate / Activate** — a deactivated account is blocked from signing in
+  right away (401), and reactivation restores access. Deactivation persists in
+  the database.
+- **Safety guard** — the console refuses to deactivate the **last active
+  admin**, so you can never lock everyone out.
+
+Existing sessions stay valid until sign-out or server restart; deactivation
+blocks *new* logins.
+
+## 3. Rate card (per-endpoint pricing)
+
+The **Rate card** tab sets list prices per API operation. Changes apply to the
+**next API call** — no restart.
+
+![Rate card](screenshots/admin-rate-card.png)
+
+Three price kinds:
+
+- **free** — never charged (e.g. `status`, `storage-list`).
+- **fixed** — a flat `fixedCents` per call (e.g. `transform` at 4¢).
+- **variable** — `baseCents` per call plus size-based charges:
+  `perKbCents` per KB of metadata and `perMbCents` per MB of file attachments
+  (e.g. `storage`: 10¢ + 1¢/KB + 50¢/MB). This is how storing data with
+  metadata or attachments is priced by size.
+
+Add an endpoint with its `operationId` from `openapi.yaml`. Deleting an
+endpoint makes calls to it fail with 403 unless the customer's type has a
+default rule.
+
+## 4. Customer types (tiers)
+
+The **Customer types** tab defines plans:
+
+![Customer types](screenshots/admin-tiers.png)
+
+- **Multiplier** — scales every list price (0.5 = 50% of list, 0.25 = 75% off).
+- **Monthly credit (cents)** — free included usage per month, consumed before
+  anything is billable.
+
+Defaults: `free` (1×, $1 credit), `pro` (0.5×, $10 credit, 8¢ default rule),
+`business` (0.25×, $100 credit, 8¢ default rule).
+
+## 5. Customers
+
+The **Customers** tab manages individual accounts:
+
+![Customers](screenshots/admin-customers.png)
+
+- **Type** — assign any tier.
+- **Multiplier override** — a per-customer deal that replaces the tier
+  multiplier (e.g. a strategic account at 0.2×).
+- **Email** — used for portal login/claiming and email invoicing.
+- **Billing** — `Stripe` (metered via the billing job) or `Purchase order`
+  (manual invoicing with PO numbers and 30-day terms).
+- **Create** — generates a customer id and API key. **The API key is shown
+  once** in the notification — copy it immediately.
+
+Customers created here can **claim** their portal account: the first signup at
+`/portal` with a matching email sets their password on the existing account
+instead of creating a new one.
+
+## 6. Admin API reference
+
+Everything the UI does is available over HTTP (`x-admin-key` or session
+Bearer):
+
+- `POST /admin/api/login`
+- `GET /admin/api/users` · `POST /admin/api/users`
+  · `POST /admin/api/users/:username/activate|deactivate`
+- `GET /admin/api/pricing` · `PUT/DELETE /admin/api/endpoints/:id`
+- `PUT/DELETE /admin/api/tiers/:id`
+- `GET/POST /admin/api/customers` · `PUT /admin/api/customers/:id`
+- `POST /admin/api/invoices/generate` · `GET /admin/api/invoices`
+  · `POST /admin/api/invoices/:id/issue|paid`
+- `GET /admin/api/reports/billing` · `GET /admin/api/reports/usage-trend`
+- `GET /admin/api/zapier/status`