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/sphinx/conf.py

@@ -0,0 +1,13 @@
+# Sphinx config for Verae × Zapier module reference.
+project = "Verae Time × Zapier"
+author = "Verae"
+release = "0.1.0"
+extensions = []
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+html_theme = "alabaster"
+html_static_path = []
+master_doc = "index"
+latex_documents = [
+    (master_doc, "verae-zapier-modules.tex", "Verae Time × Zapier Module Reference", author, "manual"),
+]

docs/sphinx/index.rst

@@ -0,0 +1,96 @@
+Verae × Zapier module reference
+=================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Models
+
+   models/PriceRule
+   models/TierConfig
+   models/RateCard
+   models/Quote
+   models/CallUsage
+   models/Customer
+   models/AddNumbersResult
+   models/TimestampRequest
+   models/TimestampResponse
+   models/StatusResponse
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Modules
+
+   modules/zappier/accounts
+   modules/zappier/admin-users
+   modules/zappier/admin
+   modules/zappier/app
+   modules/zappier/auth
+   modules/zappier/billing/credit
+   modules/zappier/billing/reload
+   modules/zappier/billing/stripe
+   modules/zappier/db/admin-user-repo
+   modules/zappier/db/billing-repo
+   modules/zappier/db/customer-repo
+   modules/zappier/db/invoice-repo
+   modules/zappier/db/pricing-store
+   modules/zappier/db/session-repo
+   modules/zappier/db/usage-repo
+   modules/zappier/index
+   modules/zappier/invoicing
+   modules/zappier/jobs/report-usage
+   modules/zappier/meter
+   modules/zappier/paths
+   modules/zappier/portal
+   modules/zappier/pricing
+   modules/zappier/reports
+   modules/zappier/usage
+   modules/verae-zapier-middleware/app
+   modules/verae-zapier-middleware/clients/veraeClient
+   modules/verae-zapier-middleware/config
+   modules/verae-zapier-middleware/debug/config
+   modules/verae-zapier-middleware/debug/index
+   modules/verae-zapier-middleware/debug/logger
+   modules/verae-zapier-middleware/debug/redact
+   modules/verae-zapier-middleware/debug/trace-context
+   modules/verae-zapier-middleware/debug/trace
+   modules/verae-zapier-middleware/errors
+   modules/verae-zapier-middleware/index
+   modules/verae-zapier-middleware/lib/tokens
+   modules/verae-zapier-middleware/middleware/authenticate
+   modules/verae-zapier-middleware/middleware/rateLimit
+   modules/verae-zapier-middleware/nats/connection
+   modules/verae-zapier-middleware/nats/publishers
+   modules/verae-zapier-middleware/nats/subjects
+   modules/verae-zapier-middleware/routes/authRoutes
+   modules/verae-zapier-middleware/routes/index
+   modules/verae-zapier-middleware/routes/statusRoutes
+   modules/verae-zapier-middleware/routes/tenantRoutes
+   modules/verae-zapier-middleware/routes/timestampRoutes
+   modules/verae-zapier-middleware/routes/verifyRoutes
+   modules/verae-zapier-middleware/routes/webhookRoutes
+   modules/verae-zapier-middleware/services/authService
+   modules/verae-zapier-middleware/services/entitlementService
+   modules/verae-zapier-middleware/services/tenantService
+   modules/verae-zapier-middleware/services/timestampService
+   modules/verae-zapier-middleware/services/verifyService
+   modules/verae-zapier-middleware/services/webhookService
+   modules/verae-zapier-middleware/store/db
+   modules/verae-zapier-middleware/store/jobWatchers
+   modules/verae-zapier-middleware/store/tenants
+   modules/verae-zapier-middleware/store/usage
+   modules/verae-zapier-middleware/store/webhooks
+   modules/verae-zapier-middleware/workers/inProcessJobPoller
+   modules/verae-zapier-middleware/workers/jobPollerWorker
+   modules/verae-zapier-middleware/workers/webhookWorker
+   modules/verae-activate/authentication
+   modules/verae-activate/creates/add_numbers
+   modules/verae-activate/index
+   modules/verae-zapier/authentication
+   modules/verae-zapier/creates/add_numbers
+   modules/verae-zapier/creates/batch_timestamp
+   modules/verae-zapier/creates/create_timestamp
+   modules/verae-zapier/creates/timestamp_and_wait
+   modules/verae-zapier/creates/verify_timestamp
+   modules/verae-zapier/index
+   modules/verae-zapier/searches/job_status
+   modules/verae-zapier/triggers/timestamp_completed

docs/sphinx/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/sphinx/models/AddNumbersResult.rst

@@ -0,0 +1,5 @@
+AddNumbersResult
+================
+
+.. include:: AddNumbersResult.md
+   :literal:

docs/sphinx/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/sphinx/models/CallUsage.rst

@@ -0,0 +1,5 @@
+CallUsage
+=========
+
+.. include:: CallUsage.md
+   :literal:

docs/sphinx/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/sphinx/models/Customer.rst

@@ -0,0 +1,5 @@
+Customer
+========
+
+.. include:: Customer.md
+   :literal:

docs/sphinx/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/sphinx/models/PriceRule.rst

@@ -0,0 +1,5 @@
+PriceRule
+=========
+
+.. include:: PriceRule.md
+   :literal:

docs/sphinx/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/sphinx/models/Quote.rst

@@ -0,0 +1,5 @@
+Quote
+=====
+
+.. include:: Quote.md
+   :literal:

docs/sphinx/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/sphinx/models/RateCard.rst

@@ -0,0 +1,5 @@
+RateCard
+========
+
+.. include:: RateCard.md
+   :literal:

docs/sphinx/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/sphinx/models/StatusResponse.rst

@@ -0,0 +1,5 @@
+StatusResponse
+==============
+
+.. include:: StatusResponse.md
+   :literal:

docs/sphinx/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/sphinx/models/TierConfig.rst

@@ -0,0 +1,5 @@
+TierConfig
+==========
+
+.. include:: TierConfig.md
+   :literal:

docs/sphinx/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/sphinx/models/TimestampRequest.rst

@@ -0,0 +1,5 @@
+TimestampRequest
+================
+
+.. include:: TimestampRequest.md
+   :literal: