@bc-subscriptions/types

Shared TypeScript types for the bc-subscriptions monorepo — D1 row shapes, status enums, adapter contract types, primitives.

What lives here

| Category | Examples | Source of truth | |---|---|---| | Row types (snake_case, column-exact) | SubscriptionRow, ChargeRow, CustomerRow, PlanRow, … | apps/api/migrations/schema/0001_init.sql | | Status enums | SubscriptionStatus, ChargeStatus, MitSubtype, ChainPosition, … | CHECK constraints in the same migration | | Adapter contract | ChargeContext, ChargeResult | apps/api/HACKATHON-SCOPE.md + D17 spec | | Primitives | StoreHash, Money | — |

What deliberately doesn't live here

• Worker Env — app-specific binding shape; lives in apps/api/src/types.ts.
• BcSignedJwtPayload — BC platform integration shape; lives in apps/api/src/types.ts.
• Adapter implementations — only the contract types are shared; gateway-specific adapter code stays in its host app.

Consumers

• apps/api/ — re-exports the row + enum + contract types from apps/api/src/types.ts for backwards compatibility, while Env and BcSignedJwtPayload stay app-local.
• prototype/ — prototype/src/lib/api-client.ts imports row types directly; previously inlined them (since prototype/ had its own tsconfig and we'd punted on a shared types package per decision 45886741).
• Future: apps/admin/, packages/storefront-* — will import from this package once they land (per ADR-0012 and ADR-0013).

Wiring

The package is consumed via file: protocol in each consumer's package.json:

{
  "dependencies": {
    "@bc-subscriptions/types": "file:../../packages/types"
  }
}

npm install symlinks the built dist/ output into the consumer's node_modules. There's no root npm-workspaces config in this repo — each package keeps its own lockfile (per the precedent set by apps/i18n/).

Build

npm install
npm run build

Outputs dist/index.js (effectively empty — types-only) + dist/index.d.ts. Consumers resolve types via the exports map in package.json.

Updating the types

When apps/api/migrations/schema/*.sql changes (column added, enum extended, table added):

1. Update src/index.ts here to match.
2. npm run build.
3. Run npm run typecheck in both apps/api/ and prototype/ to surface drift.

Drift is the whole point of this package — a schema change should fail typecheck in every consumer at the next build, not surface as a runtime "field unavailable" rendering bug.

Why a shared package vs. cross-app paths mapping

Two apps consume the row types today (apps/api/, prototype/); two more will soon (apps/admin/, packages/storefront-*). TypeScript paths mapping requires every consumer's tsconfig.json to coordinate; a published package decouples them. The file: protocol lets us evolve the types in lockstep with the migrations without setting up a registry.