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.

docs/models/AddNumbersResult.md

@@ -0,0 +1,25 @@
+# AddNumbersResult
+
+**Kind:** Zapier create output  
+**Defined in:** `packages/verae-activate/creates/add_numbers.js`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `number1` | `number` | First addend (finite) |
+| `number2` | `number` | Second addend (finite) |
+| `sum` | `number` | number1 + number2 |
+| `mode` | `'local' | 'hosted'` | local = Zapier cloud arithmetic; hosted = POST /v1/add |
+
+## Who constructs it
+
+perform(z, bundle) → single object (creates never return arrays)
+
+## Who consumes it
+
+`Zapier Add Numbers action`, `optional zappier POST /v1/add`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/CallUsage.md

@@ -0,0 +1,23 @@
+# CallUsage
+
+**Kind:** interface  
+**Defined in:** `packages/zappier/src/pricing.ts`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `metadataBytes` | `number` | UTF-8 length of metadata JSON |
+| `attachmentBytes` | `number` | Sum of uploaded file sizes |
+
+## Who constructs it
+
+constructed in meter middleware
+
+## Who consumes it
+
+`meter()`, `quoteCall()`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/Customer.md

@@ -0,0 +1,27 @@
+# Customer
+
+**Kind:** interface  
+**Defined in:** `packages/zappier/src/auth.ts`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `id` | `string` | cust_… |
+| `name` | `string` | Display |
+| `tierId` | `string` | Matches TierConfig.id |
+| `apiKey` | `string` | x-api-key value |
+| `multiplierOverride` | `number?` | Beats tier multiplier |
+| `email` | `string?` | Portal login |
+
+## Who constructs it
+
+CustomerRepo.findByApiKey / findById
+
+## Who consumes it
+
+`apiKeyAuth`, `portal`, `invoices`, `usage.summaryFor`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/PriceRule.md

@@ -0,0 +1,26 @@
+# PriceRule
+
+**Kind:** discriminated union  
+**Defined in:** `packages/zappier/src/pricing.ts`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `kind` | `'free' | 'fixed' | 'variable'` | Which list-price formula |
+| `fixedCents` | `number?` | When kind=fixed, cents per call |
+| `baseCents` | `number?` | When kind=variable, base cents |
+| `perKbCents` | `number?` | When kind=variable, per KB metadata |
+| `perMbCents` | `number?` | When kind=variable, per MB attachments |
+
+## Who constructs it
+
+RateCard.endpoints values
+
+## Who consumes it
+
+`quoteCall`, `meter`, `admin rate card UI`, `portal API & pricing tab`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/Quote.md

@@ -0,0 +1,27 @@
+# Quote
+
+**Kind:** interface  
+**Defined in:** `packages/zappier/src/pricing.ts`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `endpointId` | `string` | operationId priced |
+| `listCents` | `number` | Before multiplier |
+| `totalCents` | `number` | round(list * multiplier) |
+| `breakdown.baseCents` | `number` | Variable base |
+| `breakdown.metadataCents` | `number` | KB component |
+| `breakdown.attachmentCents` | `number` | MB component |
+
+## Who constructs it
+
+quoteCall(...) → Quote
+
+## Who consumes it
+
+`meter() sets res.locals.quote; JSON body.quote on /v1/*`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/README.md

@@ -0,0 +1,16 @@
+# Data models
+
+Each model has its own MD, Sphinx RST, and PDF under `docs/models/` and `docs/models-pdf/`.
+
+| Model | Defined in | Role |
+|-------|------------|------|
+| [PriceRule](PriceRule.md) | `packages/zappier/src/pricing.ts` | free / fixed / variable list price |
+| [TierConfig](TierConfig.md) | `pricing.ts` | multiplier + monthly credit |
+| [RateCard](RateCard.md) | `pricing.ts` | map of operationId → PriceRule |
+| [Quote](Quote.md) | `pricing.ts` | listCents, totalCents, breakdown |
+| [CallUsage](CallUsage.md) | `pricing.ts` | metadataBytes, attachmentBytes |
+| [Customer](Customer.md) | `packages/zappier/src/auth.ts` | id, tierId, apiKey |
+| [AddNumbersResult](AddNumbersResult.md) | `packages/verae-activate/creates/add_numbers.js` | number1, number2, sum, mode |
+| [TimestampRequest](TimestampRequest.md) | Verae OpenAPI | data, hashAlg |
+| [TimestampResponse](TimestampResponse.md) | Verae OpenAPI | jobId |
+| [StatusResponse](StatusResponse.md) | Verae OpenAPI | id, status, result, metadata |

docs/models/RateCard.md

@@ -0,0 +1,22 @@
+# RateCard
+
+**Kind:** interface  
+**Defined in:** `packages/zappier/src/pricing.ts`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `endpoints` | `Record<string, PriceRule>` | Keys are OpenAPI operationIds |
+
+## Who constructs it
+
+PricingStore.getRateCard()
+
+## Who consumes it
+
+`quoteCall`, `admin PUT /admin/api/endpoints/:id`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/StatusResponse.md

@@ -0,0 +1,27 @@
+# StatusResponse
+
+**Kind:** OpenAPI schema  
+**Defined in:** `docs/00-sources/veraetime-openapi.yaml`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `id` | `string` | jobId |
+| `status` | `'pending' | 'completed' | 'failed'` | Job state |
+| `error` | `string?` | If failed |
+| `result` | `string?` | Certificate if completed |
+| `completedAt` | `string date-time?` |  |
+| `metadata` | `object?` | blockIndex, timestamp, certificate, block, chain |
+
+## Who constructs it
+
+HTTP 200 JSON
+
+## Who consumes it
+
+`GET /api/status/{jobId}`, `Find Job Status search`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/TierConfig.md

@@ -0,0 +1,26 @@
+# TierConfig
+
+**Kind:** interface  
+**Defined in:** `packages/zappier/src/pricing.ts`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `id` | `string` | free | pro | business or custom |
+| `name` | `string` | Display name |
+| `multiplier` | `number` | Applied once to list cents |
+| `monthlyCreditCents` | `number` | Included usage before Stripe/invoice |
+| `defaultRule` | `PriceRule?` | Price for unlisted operationIds |
+
+## Who constructs it
+
+PricingStore.getTiers()
+
+## Who consumes it
+
+`quoteCall`, `applyMonthlyCredit`, `admin tiers`, `portal`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/TimestampRequest.md

@@ -0,0 +1,23 @@
+# TimestampRequest
+
+**Kind:** OpenAPI schema  
+**Defined in:** `docs/00-sources/veraetime-openapi.yaml`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `data` | `string (required)` | Payload to hash/timestamp |
+| `hashAlg` | `string?` | Defaults SHA256 |
+
+## Who constructs it
+
+request body only
+
+## Who consumes it
+
+`POST /api/timestamp`, `middleware timestampService.create`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.

docs/models/TimestampResponse.md

@@ -0,0 +1,22 @@
+# TimestampResponse
+
+**Kind:** OpenAPI schema  
+**Defined in:** `docs/00-sources/veraetime-openapi.yaml`
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `jobId` | `string` | UUID of async job |
+
+## Who constructs it
+
+HTTP 202 JSON
+
+## Who consumes it
+
+`Zapier Create Timestamp`
+
+## Related modules
+
+See `docs/modules/` for the functions that take these types as parameters and the values they return.