@codelitdev/billing 0.1.0-alpha.1

package/docs/decisions/0001-extraction-discrepancies.md

@@ -0,0 +1,29 @@
+# ADR 0001: Resolve architecture §20 PRD vs SendLit discrepancies
+
+Status: accepted  
+Default: SendLit implemented behavior, except where a correctness defect is named.
+
+| #   | Topic                   | Package decision                                                                                                                         |
+| --- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Cancellation recovery   | `cancelled` may transition to `trialing`, `active`, or `past_due` (provider recovery before paid-through expiry). `expired` is terminal. |
+| 2   | Pending status          | Canonical status includes `pending`.                                                                                                     |
+| 3   | Envelope vs snapshot    | `VerifiedWebhookEnvelope` is wake-up evidence; `SubscriptionSnapshot` is retrieved truth.                                                |
+| 4   | Catalog availability    | Pending/invalid requested revision freezes checkout only. Last verified revision stays the active commercial projection.                 |
+| 5   | Provider cancellation   | Adapter requires `cancelSubscription`.                                                                                                   |
+| 6   | Metadata                | Allowlisted keys are `checkoutAttemptId` and `catalogKey`. No `sendlit*` keys.                                                           |
+| 7   | Clock                   | Decision functions and adapters take an injected `Clock`. Core never reads wall time.                                                    |
+| 8   | Reconciliation claims   | Durable `billing_reconciliation_jobs` leases. No row lock spans a provider call.                                                         |
+| 9   | Catalog failure         | Last verified revision remains `active`. Requested pending/invalid/abandoned revision makes `checkoutAvailable=false`.                   |
+| 10  | Existing-schema mapping | Config may remap table/column names; generator does not invent parallel tables.                                                          |
+| 11  | Config loading          | `billing.config.ts` is a pure schema description; generate does not connect to a DB or read provider secrets.                            |
+| 12  | Plan constraints        | Configured `planIds` become generated check constraints (schema SemVer).                                                                 |
+| 13  | Catalog provenance      | Subscriptions persist `catalogRevision` + offer key + price entry; lineage updates only from correlated checkout/change attempts.        |
+| 14  | Projection idempotency  | **Correctness defect vs SendLit.** Equivalent snapshots update freshness only. Material change increments `projectionVersion` once.      |
+| 15  | Snapshot time           | `providerOccurredAt` / `providerVersion` are distinct from `observedAt`. Retrieval time is not provider event time.                      |
+| 16  | Payer invariant         | Workflows compare persisted payer on customer/attempt/subscription. A fresh grant cannot substitute a different payer.                   |
+| 17  | Action grant            | Opaque single-use `BillingAuthorizationPort.consume`. Webhooks/reconciliation cannot present a human grant.                              |
+| 18  | Operator audit          | Mutating operator APIs require `OperatorContext` and the audit hook. Decrypt is a separate audit.                                        |
+| 19  | Read models             | Export `PublicBillingCatalog` and `CommercialBillingState` only. Product entitlements stay outside.                                      |
+| 20  | Mutation recovery       | Each mutation declares `idempotency_key` \| `lookup` \| `unsupported`. Contract tests inject side-effect-then-timeout.                   |
+| 21  | Plan-state              | Canonical row is `billableEntityId`, nullable `activeSubscriptionId`, `projectionVersion`. No Free plan column.                          |
+| 22  | Required audit hook     | Cloud composition without an audit hook is a composition error.                                                                          |

package/docs/runbooks.md

@@ -0,0 +1,140 @@
+# Operational runbooks
+
+Status: package-owned procedures for `@codelitdev/billing`  
+Audience: SendLit and CourseLit operators composing product-authenticated commands over `createOperations` and maintenance units  
+Package version: 0.1.0-alpha.1 (experimental workflows; not a v1 cutover)
+
+These runbooks name package units, not HTTP routes. Product CLIs and admin screens must supply `OperatorContext`, persist audit rows, and keep product nouns (organisation, school, trial, availability) outside canonical billing tables.
+
+Production canaries remain consumer-owned. Do not declare a v1/stable cutover until SendLit and CourseLit have each run a limited production canary.
+
+## Shared controls
+
+Bounded work units (the package does not start timers):
+
+- `recordRequestedCatalog` / `verifyRequestedCatalog` / `abandonRequestedCatalog`
+- `runWebhookInboxBatch`
+- `runReconciliationBatch` / `claimReconciliationJobs`
+- `runDeadlineBatch`
+- `purgeExpiredSensitiveValues`
+- operations: `inspectEntity`, `health`, `reconcileSubscription`, `retryWebhook`, `requestCancellation`, `decryptReplay`
+
+Multi-instance safety comes from database claims. Never hold an application transaction across a provider call.
+
+---
+
+## Webhook outage and replay
+
+1. Confirm `health().oldestInboxAgeMs`, `quarantinedWebhooks`, and provider status-page/outage.
+2. Keep ingesting: signature verification and durable insert must still 2xx before projection.
+3. Replay from the provider dashboard or stored ciphertext only through `decryptReplay` plus provider replay. Do not re-post unverified bodies.
+4. Drain with `runWebhookInboxBatch`. Duplicate `providerEventId` values must no-op.
+5. If events quarantine, inspect metadata (not raw SDK text) and either `retryWebhook(..., "preserve_attempts")` or start `new_budget` with an audit reason.
+
+## Catalog mismatch at startup
+
+1. Configuration validation is synchronous. Ordinary readiness must not wait on Dodo.
+2. `recordRequestedCatalog` writes `pending_verification` without contacting the provider.
+3. `verifyRequestedCatalog` retrieves products, then atomically inserts/reuses price entries, attaches revision items, retires the prior revision, and activates the new one.
+4. Pending or invalid requested revisions set `checkoutAvailable=false`. Last verified revision remains the commercial projection.
+5. Provider outage during verify leaves the revision pending; it does not mark it invalid.
+6. After reverting env, `abandonRequestedCatalog` with actor/reason restores checkout on the prior verified revision.
+7. An older instance cannot activate a lower revision over a newer active catalog.
+
+## Stuck checkout/change
+
+1. `health().stuckCreatingCheckouts` and entity `pendingCheckout` / `pendingPlanChange`.
+2. `runDeadlineBatch` expires open/creating checkouts past `expiresAt` and clears checkout URLs.
+3. `runReconciliationBatch` resumes `creating` attempts with the original idempotency key and stored payer email.
+4. Do not delete the attempt. Abandon only through an audited operator path once the provider session is known terminal.
+
+## Remote success with failed local persistence
+
+1. Symptom: provider customer/session exists, local attempt stays `creating`, reconciliation job queued.
+2. `runReconciliationBatch` must reuse the stored idempotency key and must not open a second provider customer/session identity.
+3. After success, attempt is `open` (checkout) or the subscription projection is material once. Equivalent snapshot refresh must not increment `projectionVersion`.
+
+## Duplicate provider customer
+
+1. Unique constraint is `(provider, payerId)` plus a partial unique on provider customer id.
+2. A second create for the same payer must return the stored row.
+3. If the provider created two remote customers, keep the locally recorded `providerCustomerId`. Quarantine conflicting jobs; do not merge by email.
+
+## Conflicting active subscriptions
+
+1. At most one `isEntitlementSource` subscription per billable entity.
+2. A second paid snapshot for the same entity quarantines rather than flipping the pointer.
+3. Immediate cancellation plus projection must clear `activeSubscriptionId`.
+4. Manual repair uses `reconcileSubscription` and audited projection, never a direct SQL pointer edit.
+
+## Manual reconciliation with immutable correction/audit
+
+1. `reconcileSubscription(context, subscriptionId)` requires actor/reason and writes an operator audit effect before work.
+2. Reconciliation retrieves current provider truth and applies the same transitions as webhooks.
+3. Corrections are new audited effects. Do not rewrite previous projection rows in place to hide history.
+
+## Reconciliation lease exhaustion, reclaim, and quarantine
+
+1. Claims use committed leases (`claimReconciliationJobs`). `FOR UPDATE SKIP LOCKED` must not span the provider call.
+2. A crashed worker’s lease expires; another worker reclaims the same job.
+3. Exhausted attempts or `operation_quarantined` / misconfigured provider errors move the job to `quarantined`.
+4. Operator retry must say `preserve_attempts` or `new_budget`. Setting `status=pending` in SQL is not a public API.
+
+## Entity close or payer removal blocked by live billing responsibility
+
+1. Before product close/delete, call `getBillableEntityBillingBlockers` and `getPayerBillingResponsibilities`.
+2. Live checkout, nonterminal subscription, or future paid-through entitlement must block close.
+3. Do not cancel at the provider as a side effect of entity delete. Cancel through the cancellation workflow or operator cancel, then wait for terminal projection and elapsed paid-through (`runDeadlineBatch`).
+
+## Sensitive action-token outage/replay and persisted payer mismatch
+
+1. Checkout, portal, plan change, and cancellation consume a single-use grant before mutation.
+2. A replayed grant returns `grant_consumed`.
+3. A fresh grant cannot substitute a different payer than the one persisted on the customer/attempt/subscription (`payer_mismatch` / `grant_invalid`).
+4. Token-issuer outage is an application/Platform incident. Billing must fail closed, not skip `consume`.
+
+## Operator retry-budget reset versus preservation
+
+1. `retryWebhook(context, providerEventId, "preserve_attempts")` requeues without clearing `processingAttempts`.
+2. `"new_budget"` zeroes attempts and is a distinct audit effect.
+3. Never expose retry as an unauthenticated script.
+
+## Audited replay-payload inspection and retention purge
+
+1. `decryptReplay` requires `OperatorContext` and a `SensitiveValuePort`. The decrypt is audited even when no row changes.
+2. Applications choose retention. `purgeExpiredSensitiveValues({ before, limit })` nulls terminal checkout URLs, plan-change payment URLs, and processed/ignored webhook payloads older than `before`.
+3. `before` must not be in the future. Purge is idempotent and writes one audit effect per cleared secret.
+4. Immutable catalog, attempt, and projection history remains.
+
+## Provider credential rotation
+
+1. Inject API keys and webhook secrets from the application. The Dodo adapter never reads `process.env`.
+2. Webhook secrets are a versioned list. Ingest tries unexpired versions; envelopes record `verifiedKeyVersion`.
+3. Rotate by adding a new version, deploying, then expiring the old secret. Do not change checkout provider in the same change.
+4. After rotation, run a sandbox retrieve (`BILLING_DODO_SANDBOX_*`) and a webhook ingest canary.
+
+## Package rollback with app-owned migrations
+
+1. The package never runs DDL on import, install, or worker start.
+2. Roll back application code only to a build compatible with the already-applied Drizzle migration.
+3. Do not reverse a billing migration that has expanded columns unless a reviewed down-migration exists in the product repo.
+4. Catalog revisions and price entries are immutable; rollback of application config may `abandonRequestedCatalog` but must not delete historical mappings needed by live subscriptions.
+
+## CourseLit trial/subscription expiry and public-availability verification
+
+1. CourseLit 14-day trials are application state. They must not create a fake provider subscription or a Free plan row.
+2. Canonical `runDeadlineBatch` clears entitlement when a cancelled subscription’s `paidThroughAt` has elapsed. Public school availability is CourseLit policy composed with `commercialState`.
+3. Two schools under one payer expire independently. Recovering one school must not re-open the other.
+4. Verify: unpaid school past trial is unavailable; paid school remains available; admin billing routes still load `commercialState`.
+
+## Canary checklist (consumer-owned)
+
+Until both products complete this list, keep `@codelitdev/billing@0.1.0-alpha.1` and treat workflows as experimental:
+
+- Feature-flag or percentage canary in SendLit first.
+- `generate --check` clean; reviewed Drizzle migration applied by the product job.
+- Catalog record/verify against Dodo test then live products.
+- One checkout, webhook, reconciliation reclaim, cancellation, and deadline/purge cycle.
+- Action-grant consume-once and payer-mismatch probes.
+- Operator audit visible for reconcile, retry, abandon, and decrypt.
+- CourseLit canary only after SendLit’s limited production canary is green.

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@codelitdev/billing",
+  "version": "0.1.0-alpha.1",
+  "description": "Provider-neutral billing engine for CodeLit products",
+  "author": "CodeLit",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "codelit-billing": "./dist/cli/bin.js"
+  },
+  "exports": {
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./catalog": {
+      "types": "./dist/catalog/index.d.ts",
+      "import": "./dist/catalog/index.js",
+      "default": "./dist/catalog/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
+    },
+    "./drizzle": {
+      "types": "./dist/adapters/drizzle/index.d.ts",
+      "import": "./dist/adapters/drizzle/index.js",
+      "default": "./dist/adapters/drizzle/index.js"
+    },
+    "./workflows": {
+      "types": "./dist/workflows/index.d.ts",
+      "import": "./dist/workflows/index.js",
+      "default": "./dist/workflows/index.js"
+    },
+    "./operations": {
+      "types": "./dist/operations/index.d.ts",
+      "import": "./dist/operations/index.js",
+      "default": "./dist/operations/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.js",
+      "default": "./dist/providers/index.js"
+    },
+    "./providers/dodo": {
+      "types": "./dist/providers/dodo/index.d.ts",
+      "import": "./dist/providers/dodo/index.js",
+      "default": "./dist/providers/dodo/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/architecture.md",
+    "docs/decisions",
+    "docs/runbooks.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "nanoid": "^5.1.6",
+    "tsx": "^4.20.6",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "dodopayments": "^2.48.0"
+  },
+  "peerDependenciesMeta": {
+    "dodopayments": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.14.1",
+    "dodopayments": "^2.48.0",
+    "drizzle-kit": "^0.28.1",
+    "eslint": "^10.9.1",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^17.11.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.2",
+    "prettier": "^3.0.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:packed": "node scripts/packed-consumer.mjs",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "lint": "eslint . --quiet",
+    "prettier": "prettier --write .",
+    "generate": "tsx src/cli/bin.ts generate",
+    "release:alpha": "pnpm test && pnpm typecheck && pnpm lint && pnpm build && pnpm test:packed"
+  }
+}