Milestone 2: module/model docs (MD, Sphinx RST, PDF) and work log

74 source modules documented with extracted signatures, JSDoc params,
imports, and call graphs. 10 first-class models (PriceRule through
StatusResponse) have their own MD/RST/PDF. Sphinx HTML builds from
docs/sphinx. Per-module PDFs in docs/modules-pdf and docs/models-pdf.

Middleware gates 2–6 and 10 pass on MOCK_VERAE without NATS.

Learned: RST includes are relative to the RST file; keep one PDF per
module; Add Numbers remains the only push required tomorrow.
This commit is contained in:
George Lambert 2026-09-09 02:44:51 -04:00
commit 10c663cc0c
48 changed files with 17200 additions and 14 deletions

View file

@ -0,0 +1,71 @@
# `zappier/accounts`
**Package:** `zappier`
**Source:** `packages/zappier/src/accounts.ts`
**Lines:** 166
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`hashPassword`, `verifyPassword`, `base32Encode`, `base32Decode`, `hotp`, `totp`, `verifyTotp`, `generateTotpSecret`, `totpUri`, `PortalSession`, `SessionRepo`, `newSessionToken`, `InMemorySessionRepo`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `PortalSession` |
| interface | `SessionRepo` |
| class | `InMemorySessionRepo` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `hashPassword` | `password: string` | — | `unknown` | see Call graph |
| | _Format: scrypt:N:r:p:<salt b64>:<hash b64>_ | | | |
| `verifyPassword` | `password: string, stored: string` | — | `unknown` | see Call graph |
| `base32Encode` | `buf: Buffer` | — | `unknown` | see Call graph |
| `base32Decode` | `s: string` | — | `unknown` | see Call graph |
| `hotp` | `secret: string, counter: number, digits = 6` | — | `unknown` | see Call graph |
| `totp` | `secret: string, atMs: number, stepSec = 30, digits = 6` | — | `unknown` | see Call graph |
| `verifyTotp` | `secret: string,
code: string,
atMs: number,
window = 1,` | — | `unknown` | see Call graph |
| `generateTotpSecret` | `(none)` | — | `unknown` | see Call graph |
| | _160-bit secret, base32 without padding (authenticator-app standard)._ | | | |
| `totpUri` | `secret: string, email: string, issuer = 'Zappier'` | — | `unknown` | see Call graph |
| | _160-bit secret, base32 without padding (authenticator-app standard)._ | | | |
| `newSessionToken` | `(none)` | — | `unknown` | see Call graph |
| | _Returns the session, or undefined when unknown or expired at nowMs._ | | | |
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `create` | `customerId: string, ttlMs: number` |
| `get` | `token: string, nowMs?: number` |
| `delete` | `token: string` |
| `create` | `customerId: string, ttlMs: number` |
| `get` | `token: string, nowMs = Date.now(` |
| `delete` | `token: string` |
## What it imports / requires
- `crypto`
## Call graph (identifiers invoked)
`hashing`, `secrets`, `hashPassword`, `randomBytes`, `scryptSync`, `toString`, `verifyPassword`, `split`, `from`, `timingSafeEqual`, `base32`, `base32Encode`, `base32Decode`, `toUpperCase`, `replace`, `indexOf`, `push`, `hotp`, `alloc`, `writeBigUInt64BE`, `createHmac`, `update`, `digest`, `padStart`, `totp`, `floor`, `verifyTotp`, `test`, `padding`, `generateTotpSecret`, `totpUri`, `encodeURIComponent`, `create`, `get`, `delete`, `newSessionToken`, `now`, `set`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.accounts
================
Generated API sheet for ``zappier/accounts``.
.. include:: accounts.md
:literal:

View file

@ -0,0 +1,59 @@
# `zappier/admin-users`
**Package:** `zappier`
**Source:** `packages/zappier/src/admin-users.ts`
**Lines:** 76
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`AdminUser`, `AdminUserRepo`, `newAdminUserId`, `seedAdminUsersFromEnv`, `makeAdminUser`, `InMemoryAdminUserRepo`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `AdminUser` |
| interface | `AdminUserRepo` |
| class | `InMemoryAdminUserRepo` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `newAdminUserId` | `(none)` | — | `unknown` | see Call graph |
| `seedAdminUsersFromEnv` | `(none)` | — | `unknown` | see Call graph |
| | _The env-backed seed accounts (preserved from the pre-table behavior)._ | | | |
| `makeAdminUser` | `username: string, password: string` | — | `unknown` | see Call graph |
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `list` | `(none)` |
| `findByUsername` | `username: string` |
| `save` | `user: AdminUser` |
| `list` | `(none)` |
| `findByUsername` | `username: string` |
| `save` | `user: AdminUser` |
## What it imports / requires
- `crypto`
- `./accounts`
## Call graph (identifiers invoked)
`list`, `findByUsername`, `save`, `newAdminUserId`, `randomBytes`, `toString`, `accounts`, `seedAdminUsersFromEnv`, `makeAdminUser`, `hashPassword`, `now`, `constructor`, `map`, `seeded`, `find`, `findIndex`, `push`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.admin-users
===================
Generated API sheet for ``zappier/admin-users``.
.. include:: admin-users.md
:literal:

View file

@ -0,0 +1,73 @@
# `zappier/admin`
**Package:** `zappier`
**Source:** `packages/zappier/src/admin.ts`
**Lines:** 486
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`adminLoginRouter`, `adminAuth`, `AccountingDeps`, `renderInvoiceHtml`, `adminRouter`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `AccountingDeps` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `adminLoginRouter` | `users: AdminUserRepo` | — | `unknown` | see Call graph |
| `adminAuth` | `(none)` | — | `unknown` | see Call graph |
| `isValidRule` | `rule: unknown` | — | `unknown` | see Call graph |
| `isValidTier` | `tier: unknown` | — | `unknown` | see Call graph |
| `periodWindow` | `period: string` | — | `unknown` | see Call graph |
| `parseDate` | `value: unknown` | — | `unknown` | see Call graph |
| `escapeHtml` | `s: string` | — | `unknown` | see Call graph |
| `renderInvoiceHtml` | `invoice: Invoice, customerName: string` | — | `unknown` | see Call graph |
| `adminRouter` | `store: PricingStore,
customers: CustomerRepo,
accounting: AccountingDeps,` | — | `unknown` | see Call graph |
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `return` | `req, res, next` |
| `return` | `typeof t.name === 'string' &&
typeof t.multiplier === 'number' &&
typeof t.monthlyCreditCents === 'number' &&
(t.defaultRule === undefined || isValidRule(t.defaultRule` |
## What it imports / requires
- `crypto`
- `fs`
- `path`
- `express`
- `./accounts`
- `./admin-users`
- `./auth`
- `./invoicing`
- `./pricing`
- `./paths`
- `./reports`
- `./usage`
## Call graph (identifiers invoked)
`tokens`, `adminLoginRouter`, `post`, `status`, `json`, `findByUsername`, `verifyPassword`, `randomBytes`, `toString`, `set`, `now`, `adminAuth`, `header`, `next`, `startsWith`, `slice`, `has`, `isValidRule`, `every`, `isValidTier`, `periodWindow`, `split`, `map`, `parseDate`, `trim`, `isNaN`, `getTime`, `escapeHtml`, `replace`, `toFixed`, `renderInvoiceHtml`, `dollars`, `join`, `toISOString`, `toUpperCase`, `adminRouter`, `get`, `getRateCard`, `getTiers`, `put`, `upsertEndpoint`, `delete`, `deleteEndpoint`, `upsertTier`, `deleteTier`, `list`, `randomUUID`, `save`, `find`, `test`, `push`, `listFor`, `filter`, `buildInvoice`, `nextSequence`, `type`, `send`, `untouched`, `flatMap`, `billingRows`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.admin
=============
Generated API sheet for ``zappier/admin``.
.. include:: admin.md
:literal:

View file

@ -0,0 +1,59 @@
# `zappier/app`
**Package:** `zappier`
**Source:** `packages/zappier/src/app.ts`
**Lines:** 203
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`StoredItem`, `DEFAULT_CUSTOMERS`, `AppDeps`, `buildApp`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `StoredItem` |
| interface | `AppDeps` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `buildApp` | `deps: AppDeps = {}` | — | `unknown` | see Call graph |
## What it imports / requires
- `path`
- `crypto`
- `express`
- `express-openapi-validator`
- `swagger-ui-express`
- `yamljs`
- `./auth`
- `./meter`
- `./billing/credit`
- `./pricing`
- `./usage`
- `./admin`
- `./admin-users`
- `./accounts`
- `./invoicing`
- `./paths`
- `./portal`
## Call graph (identifiers invoked)
`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `apiKeyAuth`, `middleware`, `get`, `meter`, `post`, `toUpperCase`, `isFinite`, `randomUUID`, `map`, `toISOString`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.app
===========
Generated API sheet for ``zappier/app``.
.. include:: app.md
:literal:

View file

@ -0,0 +1,60 @@
# `zappier/auth`
**Package:** `zappier`
**Source:** `packages/zappier/src/auth.ts`
**Lines:** 84
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`BillingType`, `Customer`, `CustomerRepo`, `InMemoryCustomerRepo`, `apiKeyAuth`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `Customer` |
| interface | `CustomerRepo` |
| type | `BillingType` |
| class | `InMemoryCustomerRepo` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `apiKeyAuth` | `repo: CustomerRepo` | — | `unknown` | see Call graph |
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `findByApiKey` | `apiKey: string` |
| `findByEmail` | `email: string` |
| `list` | `(none)` |
| `save` | `customer: Customer` |
| `constructor` | `customers: Customer[] = []` |
| `findByApiKey` | `apiKey: string` |
| `findByEmail` | `email: string` |
| `list` | `(none)` |
| `save` | `customer: Customer` |
| `return` | `req, res, next` |
## What it imports / requires
- `express`
## Call graph (identifiers invoked)
`findByApiKey`, `findByEmail`, `list`, `save`, `constructor`, `arrays`, `map`, `find`, `toLowerCase`, `findIndex`, `push`, `apiKeyAuth`, `header`, `status`, `json`, `next`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.auth
============
Generated API sheet for ``zappier/auth``.
.. include:: auth.md
:literal:

View file

@ -0,0 +1,44 @@
# `zappier/billing/credit`
**Package:** `zappier`
**Source:** `packages/zappier/src/billing/credit.ts`
**Lines:** 20
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`BilledSummary`, `applyMonthlyCredit`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `BilledSummary` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `applyMonthlyCredit` | `summary: UsageSummary,
tier: TierConfig,` | — | `unknown` | see Call graph |
## What it imports / requires
- `../pricing`
- `../usage`
## Call graph (identifiers invoked)
`applyMonthlyCredit`, `min`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.billing.credit
======================
Generated API sheet for ``zappier/billing/credit``.
.. include:: credit.md
:literal:

View file

@ -0,0 +1,43 @@
# `zappier/billing/reload`
**Package:** `zappier`
**Source:** `packages/zappier/src/billing/reload.ts`
**Lines:** 32
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`stripePaymentClient`, `hasRealStripeKey`
## Types / interfaces / classes
_None extracted._
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `stripePaymentClient` | `secretKey: string` | — | `unknown` | see Call graph |
| `hasRealStripeKey` | `key: string \| undefined` | — | `unknown` | see Call graph |
| | _True when the key looks usable (not empty / not the setup placeholder)._ | | | |
## What it imports / requires
- `stripe`
- `../portal`
## Call graph (identifiers invoked)
`confirms`, `stripePaymentClient`, `async`, `create`, `usable`, `hasRealStripeKey`, `startsWith`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.billing.reload
======================
Generated API sheet for ``zappier/billing/reload``.
.. include:: reload.md
:literal:

View file

@ -0,0 +1,60 @@
# `zappier/billing/stripe`
**Package:** `zappier`
**Source:** `packages/zappier/src/billing/stripe.ts`
**Lines:** 42
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`METER_EVENT_NAME`, `MeterEventClient`, `computeBillableCents`, `computeDelta`, `reportUsage`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `MeterEventClient` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `computeBillableCents` | `entries: UsageEntry[], monthlyCreditCents: number` | — | `unknown` | see Call graph |
| | _Stripe-side dedup key; events with the same identifier are dropped._ | | | |
| `computeDelta` | `billableCents: number, previouslyReportedCents: number` | — | `unknown` | see Call graph |
| `reportUsage` | `client: MeterEventClient,
stripeCustomerId: string,
entries: UsageEntry[],
monthlyCreditCents: number,` | — | `unknown` | see Call graph |
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `createMeterEvent` | `params: {
eventName: string;
customerId: string;
value: string;
/** Stripe-side dedup key; events with the same identifier are dropped. */
identifier?: string;
}` |
## What it imports / requires
- `../usage`
## Call graph (identifiers invoked)
`createMeterEvent`, `computeBillableCents`, `reduce`, `max`, `computeDelta`, `ts`, `reportUsage`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.billing.stripe
======================
Generated API sheet for ``zappier/billing/stripe``.
.. include:: stripe.md
:literal:

View file

@ -0,0 +1,51 @@
# `zappier/db/admin-user-repo`
**Package:** `zappier`
**Source:** `packages/zappier/src/db/admin-user-repo.ts`
**Lines:** 72
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`SqliteAdminUserRepo`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| class | `SqliteAdminUserRepo` |
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `toAdminUser` | `r: Record<string, unknown>` | — | `unknown` | see Call graph |
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `list` | `(none)` |
| `findByUsername` | `username: string` |
| `save` | `user: AdminUser` |
## What it imports / requires
- `better-sqlite3`
- `../admin-users`
## Call graph (identifiers invoked)
`constructor`, `exec`, `admin_users`, `seeded`, `prepare`, `get`, `save`, `makeAdminUser`, `list`, `all`, `map`, `findByUsername`, `toAdminUser`, `run`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.db.admin-user-repo
==========================
Generated API sheet for ``zappier/db/admin-user-repo``.
.. include:: admin-user-repo.md
:literal:

View file

@ -0,0 +1,57 @@
# `zappier/db/billing-repo`
**Package:** `zappier`
**Source:** `packages/zappier/src/db/billing-repo.ts`
**Lines:** 69
## What this module is
Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`BillingReportRepo`, `JobLockRepo`, `SqliteBillingReportRepo`
## Types / interfaces / classes
| Kind | Name |
|------|------|
| interface | `BillingReportRepo` |
| interface | `JobLockRepo` |
| class | `SqliteBillingReportRepo` |
## Functions
_No top-level functions extracted._
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `getReportedCents` | `customerId: string, period: string` |
| `upsertReportedCents` | `customerId: string, period: string, cumulativeCents: number` |
| `tryAcquireLock` | `name: string, ttlMs: number` |
| `releaseLock` | `name: string` |
| `constructor` | `private db: Database.Database,
private now: (` |
| `getReportedCents` | `customerId: string, period: string` |
| `upsertReportedCents` | `customerId: string, period: string, cumulativeCents: number` |
| `tryAcquireLock` | `name: string, ttlMs: number` |
| `releaseLock` | `name: string` |
## What it imports / requires
- `better-sqlite3`
## Call graph (identifiers invoked)
`getReportedCents`, `upsertReportedCents`, `tryAcquireLock`, `releaseLock`, `constructor`, `exec`, `billing_reports`, `job_locks`, `prepare`, `get`, `run`, `now`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
## Return values (how to read this)
- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
- Pricing functions return integer **cents** on `Quote.totalCents`.

View file

@ -0,0 +1,7 @@
zappier.db.billing-repo
=======================
Generated API sheet for ``zappier/db/billing-repo``.
.. include:: billing-repo.md
:literal:

Some files were not shown because too many files have changed in this diff Show more