tapimo 0.1.0 → 0.3.0

package/src/db/Db.ts

@@ -5,11 +5,20 @@ import {
   type Dialect,
   Kysely,
   PostgresDialect,
+  type RawBuilder,
   sql,
 } from 'kysely'
 import * as pg from 'pg'
 
+import type * as BillingSettings from './tables/billingSettings.js'
+import type * as Invitations from './tables/invitations.js'
+import type * as Memberships from './tables/memberships.js'
 import type * as Organizations from './tables/organizations.js'
+import type * as Projects from './tables/projects.js'
+import type * as RequestUsage from './tables/requestUsage.js'
+import type * as SponsoredTransactions from './tables/sponsoredTransactions.js'
+import type * as StripeCustomers from './tables/stripeCustomers.js'
+import type * as Users from './tables/users.js'
 import type * as VerifiedTokens from './tables/verifiedTokens.js'
 import type * as WebhookDeliveries from './tables/webhookDeliveries.js'
 import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
@@ -26,7 +35,16 @@ export type Database = {
     /** SQL as applied; null on rows written before the column existed. */
     sql: string | null
   }
+  billing_settings: BillingSettings.Table
+  invitations: Invitations.Table
+  memberships: Memberships.Table
   organizations: Organizations.Table
+  projects: Projects.Table
+  request_usage_buckets: RequestUsage.BucketTable
+  request_usage_meter_events: RequestUsage.MeterEventTable
+  sponsored_transactions: SponsoredTransactions.Table
+  stripe_customers: StripeCustomers.Table
+  users: Users.Table
   verified_token_lists: VerifiedTokens.ListTable
   verified_tokens: VerifiedTokens.Table
   webhook_deliveries: WebhookDeliveries.Table
@@ -235,8 +253,286 @@ export const migrations: readonly Migration[] = [
         .on('webhookDeliveries')
         .column('expiresAt'),
   },
+  {
+    name: '0012_users',
+    up: (db) =>
+      db.schema
+        .createTable('users')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('address', 'text', (c) => c.notNull().unique())
+        .addColumn('email', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0013_organizations_user_id',
+    // The schema builder cannot express `ADD COLUMN IF NOT EXISTS`; raw SQL
+    // (snake_case: the CamelCase plugin does not map raw statements).
+    up: (db) => raw(db, sql`ALTER TABLE organizations ADD COLUMN IF NOT EXISTS user_id text`),
+  },
+  {
+    name: '0014_projects',
+    up: (db) =>
+      db.schema
+        .createTable('projects')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0015_projects_org_index',
+    up: (db) =>
+      db.schema.createIndex('projects_org_idx').ifNotExists().on('projects').column('orgId'),
+  },
+  {
+    name: '0016_memberships',
+    up: (db) =>
+      db.schema
+        .createTable('memberships')
+        .ifNotExists()
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('userId', 'text', (c) => c.notNull())
+        .addColumn('role', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('memberships_pk', ['orgId', 'userId']),
+  },
+  {
+    name: '0017_memberships_user_index',
+    up: (db) =>
+      db.schema.createIndex('memberships_user_idx').ifNotExists().on('memberships').column('userId'), // prettier-ignore
+  },
+  {
+    name: '0018_memberships_owner_backfill',
+    // Raw SQL (snake_case: the CamelCase plugin does not map raw statements).
+    up: (db) =>
+      raw(
+        db,
+        sql`INSERT INTO memberships (org_id, user_id, role, created_at, updated_at) SELECT id, user_id, 'owner', created_at, updated_at FROM organizations WHERE user_id IS NOT NULL ON CONFLICT DO NOTHING`,
+      ),
+  },
+  {
+    name: '0019_invitations',
+    up: (db) =>
+      db.schema
+        .createTable('invitations')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('email', 'text', (c) => c.notNull())
+        .addColumn('role', 'text', (c) => c.notNull())
+        .addColumn('invitedBy', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull())
+        .addColumn('acceptedAt', 'text')
+        .addColumn('revokedAt', 'text'),
+  },
+  {
+    name: '0020_invitations_org_index',
+    up: (db) =>
+      db.schema.createIndex('invitations_org_idx').ifNotExists().on('invitations').column('orgId'),
+  },
+  {
+    name: '0021_invitations_email_index',
+    up: (db) =>
+      db.schema.createIndex('invitations_email_idx').ifNotExists().on('invitations').column('email'), // prettier-ignore
+  },
+  {
+    name: '0022_users_address_nullable',
+    // Raw SQL; a no-op when the column is already nullable.
+    up: (db) => raw(db, sql`ALTER TABLE users ALTER COLUMN address DROP NOT NULL`),
+  },
+  {
+    name: '0023_invitations_pending_unique',
+    // Raw SQL: a partial unique index (snake_case; the CamelCase plugin does
+    // not map raw statements). At most one live (unaccepted, unrevoked)
+    // invitation per (org, email); a re-invite upserts the existing row.
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE UNIQUE INDEX IF NOT EXISTS invitations_pending_unique ON invitations (org_id, email) WHERE accepted_at IS NULL AND revoked_at IS NULL`,
+      ),
+  },
+  {
+    name: '0024_sponsored_transactions',
+    up: (db) =>
+      db.schema
+        .createTable('sponsoredTransactions')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('projectId', 'text', (c) => c.notNull())
+        .addColumn('apiKeyId', 'text', (c) => c.notNull())
+        .addColumn('environment', 'text', (c) => c.notNull())
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('transactionHash', 'text')
+        .addColumn('signPayload', 'text', (c) => c.notNull())
+        .addColumn('transaction', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('feeAmount', 'text')
+        .addColumn('feeToken', 'text')
+        .addColumn('billable', 'boolean', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('finalizedAt', 'text')
+        .addUniqueConstraint('sponsored_transactions_sign_payload_key', ['signPayload']),
+  },
+  {
+    name: '0025_sponsored_transactions_status_index',
+    up: (db) =>
+      db.schema.createIndex('sponsored_transactions_status_idx').ifNotExists().on('sponsoredTransactions').columns(['status', 'createdAt']), // prettier-ignore
+  },
+  {
+    name: '0026_sponsored_transactions_org_index',
+    up: (db) =>
+      db.schema.createIndex('sponsored_transactions_org_idx').ifNotExists().on('sponsoredTransactions').columns(['orgId', 'createdAt']), // prettier-ignore
+  },
+  {
+    name: '0027_stripe_customers',
+    up: (db) =>
+      db.schema
+        .createTable('stripeCustomers')
+        .ifNotExists()
+        .addColumn('orgId', 'text', (c) => c.primaryKey())
+        .addColumn('stripeCustomerId', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull())
+        .addUniqueConstraint('stripe_customers_stripe_customer_id_key', ['stripeCustomerId']),
+  },
+  {
+    name: '0028_billing_settings',
+    up: (db) =>
+      db.schema
+        .createTable('billingSettings')
+        .ifNotExists()
+        .addColumn('orgId', 'text', (c) => c.primaryKey())
+        .addColumn('spendLimit', 'text')
+        .addColumn('txFeeLimit', 'text')
+        .addColumn('currency', 'text', (c) => c.notNull().defaultTo('usd'))
+        .addColumn('period', 'text', (c) => c.notNull().defaultTo('month'))
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0029_sponsored_transactions_fee_max',
+    up: (db) => raw(db, sql`ALTER TABLE sponsored_transactions ADD COLUMN IF NOT EXISTS fee_max text`), // prettier-ignore
+  },
+  {
+    name: '0030_sponsored_transactions_meter_reported_at',
+    up: (db) => raw(db, sql`ALTER TABLE sponsored_transactions ADD COLUMN IF NOT EXISTS meter_reported_at text`), // prettier-ignore
+  },
+  {
+    name: '0031_sponsored_transactions_billing_index',
+    // Partial: the spend-limit aggregate only ever scans billable rows.
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS sponsored_transactions_billing_idx ON sponsored_transactions (org_id, status, created_at) WHERE billable`), // prettier-ignore
+  },
+  {
+    name: '0032_sponsored_transactions_fee_amount_rescale',
+    // Rows finalized before fee scaling shipped stored attodollars (1e12× the
+    // token unit); `div` is exact ceiling division (`Fees.fromGas`). The
+    // threshold keeps re-runs idempotent: real scaled fees sit far below
+    // 1e9 ($1,000); attodollar values far above.
+    up: (db) => raw(db, sql`UPDATE sponsored_transactions SET fee_amount = div(fee_amount::numeric + 999999999999, 1000000000000)::text WHERE status = 'finalized' AND fee_amount IS NOT NULL AND fee_amount::numeric >= 1000000000`), // prettier-ignore
+  },
+  {
+    name: '0033_sponsored_transactions_unreported_index',
+    // Partial queue index: the per-minute reporter scans only unreported
+    // finalized billable rows, which marking immediately evicts.
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS sponsored_transactions_unreported_idx ON sponsored_transactions (finalized_at, id) WHERE billable AND status = 'finalized' AND meter_reported_at IS NULL`), // prettier-ignore
+  },
+  {
+    name: '0034_sponsored_transactions_currency',
+    up: (db) => raw(db, sql`ALTER TABLE sponsored_transactions ADD COLUMN IF NOT EXISTS currency text`), // prettier-ignore
+  },
+  {
+    name: '0035_sponsored_transactions_currency_backfill',
+    // Every fee payer to date sponsors in pathUSD, so rows predating the
+    // currency snapshot are USD. The predicate keeps re-runs idempotent.
+    up: (db) => raw(db, sql`UPDATE sponsored_transactions SET currency = 'usd' WHERE currency IS NULL`), // prettier-ignore
+  },
+  {
+    name: '0036_stripe_customers_environment',
+    up: (db) => raw(db, sql`ALTER TABLE stripe_customers ADD COLUMN IF NOT EXISTS environment text NOT NULL DEFAULT 'production'`), // prettier-ignore
+  },
+  {
+    name: '0037_stripe_customers_org_environment_key',
+    // Enables a second (sandbox) row per org; targeted by the upsert conflict
+    // arbiter so it survives the org pkey drop in the follow-up release.
+    up: (db) => raw(db, sql`CREATE UNIQUE INDEX IF NOT EXISTS stripe_customers_org_environment_key ON stripe_customers (org_id, environment)`), // prettier-ignore
+  },
+  {
+    name: '0038_billing_settings_environment',
+    up: (db) => raw(db, sql`ALTER TABLE billing_settings ADD COLUMN IF NOT EXISTS environment text NOT NULL DEFAULT 'production'`), // prettier-ignore
+  },
+  {
+    name: '0039_billing_settings_org_environment_key',
+    up: (db) => raw(db, sql`CREATE UNIQUE INDEX IF NOT EXISTS billing_settings_org_environment_key ON billing_settings (org_id, environment)`), // prettier-ignore
+  },
+  {
+    name: '0040_stripe_customers_drop_org_pkey',
+    // Release B: the `(org_id, environment)` unique index now guards uniqueness,
+    // so dropping the org pkey unblocks a second (sandbox) row per org.
+    up: (db) => raw(db, sql`ALTER TABLE stripe_customers DROP CONSTRAINT IF EXISTS stripe_customers_pkey`), // prettier-ignore
+  },
+  {
+    name: '0041_billing_settings_drop_org_pkey',
+    up: (db) => raw(db, sql`ALTER TABLE billing_settings DROP CONSTRAINT IF EXISTS billing_settings_pkey`), // prettier-ignore
+  },
+  {
+    name: '0042_request_usage_buckets',
+    up: (db) =>
+      db.schema
+        .createTable('requestUsageBuckets')
+        .ifNotExists()
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('environment', 'text', (c) => c.notNull())
+        .addColumn('bucketStart', 'text', (c) => c.notNull())
+        .addColumn('reportedCount', 'bigint', (c) => c.notNull().defaultTo(0))
+        .addColumn('updatedAt', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('request_usage_buckets_pkey', ['orgId', 'environment', 'bucketStart']), // prettier-ignore
+  },
+  {
+    name: '0043_request_usage_meter_events',
+    up: (db) =>
+      db.schema
+        .createTable('requestUsageMeterEvents')
+        .ifNotExists()
+        .addColumn('identifier', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('environment', 'text', (c) => c.notNull())
+        .addColumn('bucketStart', 'text', (c) => c.notNull())
+        .addColumn('sequence', 'integer', (c) => c.notNull())
+        .addColumn('deltaCount', 'bigint', (c) => c.notNull())
+        .addColumn('stripeCustomerId', 'text', (c) => c.notNull())
+        .addColumn('state', 'text', (c) => c.notNull())
+        .addColumn('reason', 'text')
+        .addColumn('error', 'text')
+        .addColumn('firstAttemptedAt', 'text', (c) => c.notNull())
+        .addColumn('reportedAt', 'text')
+        .addUniqueConstraint('request_usage_meter_events_bucket_sequence_key', ['orgId', 'environment', 'bucketStart', 'sequence']), // prettier-ignore
+  },
+  {
+    name: '0044_request_usage_meter_events_pending_index',
+    // Partial: the reporter scans only unreported (pending) rows.
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS request_usage_meter_events_pending_idx ON request_usage_meter_events (first_attempted_at, identifier) WHERE state = 'pending'`), // prettier-ignore
+  },
 ]
 
+/**
+ * Adapts a raw statement to the migration contract (argument-less
+ * `compile`/`execute`) for DDL the schema builders cannot express.
+ */
+function raw(db: Kysely<Database>, statement: RawBuilder<unknown>) {
+  return {
+    compile: () => statement.compile(db),
+    execute: () => statement.execute(db),
+  }
+}
+
 /**
  * Builds a {@link Db} for any Kysely {@link Dialect}. All backends share
  * migrations, repositories, and the required {@link CamelCasePlugin} mapping.

package/src/db/Schema.ts

@@ -8,6 +8,74 @@ import type * as Webhooks from '../internal/Webhooks.js'
 // Domain-owned unions and jsonb values stay typed by their owning module via
 // `z.custom` (type-only imports) so the two cannot drift.
 
+/** An organization's billing configuration; source-agnostic (limits apply to any billing source). */
+export const BillingSettings = z.object({
+  createdAt: z.string().check(z.describe('When the settings row was created (ISO 8601).')),
+  currency: z
+    .enum(['usd'])
+    .check(z.describe('ISO 4217 currency (lowercase) both limits are denominated in.')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Environment these settings apply to; `production` or `sandbox`.')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`) these settings belong to.')),
+  period: z
+    .enum(['month'])
+    .check(z.describe('Window the spend limit applies over; `month` is a UTC calendar month.')),
+  spendLimit: z
+    .nullable(z.string())
+    .check(z.describe('Spend limit per period as a decimal string in `currency` units, or null for no limit.')), // prettier-ignore
+  txFeeLimit: z
+    .nullable(z.string())
+    .check(z.describe('Per-transaction fee cap as a decimal string in `currency` units, or null for the platform default.')), // prettier-ignore
+  updatedAt: z.string().check(z.describe('When the settings last changed (ISO 8601).')),
+})
+
+/** Columns of the `billing_settings` table. */
+export type BillingSettings = z.output<typeof BillingSettings>
+
+/** A pending, expiring offer of organization membership. */
+export const Invitation = z.object({
+  acceptedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the invitation was accepted (ISO 8601), or null while pending.')),
+  createdAt: z.string().check(z.describe('When the invitation was created (ISO 8601).')),
+  email: z
+    .string()
+    .check(z.describe('Invitee email (stored lowercase); matched against verified emails.')),
+  expiresAt: z.string().check(z.describe('When the invitation expires (ISO 8601).')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque invitation id (`inv_…`).'),
+      z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  invitedBy: z.string().check(z.describe('User id (`usr_…`) that created the invitation.')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`) the invitation joins.')),
+  revokedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the invitation was revoked (ISO 8601), or null.')),
+  role: z
+    .enum(['admin', 'member', 'owner'])
+    .check(z.describe('Role granted when the invitation is accepted.')),
+})
+
+/** Columns of the `invitations` table. */
+export type Invitation = z.output<typeof Invitation>
+
+/** A user's role within an organization. */
+export const Membership = z.object({
+  createdAt: z.string().check(z.describe('When the membership was created (ISO 8601).')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`).')),
+  role: z
+    .enum(['admin', 'member', 'owner'])
+    .check(z.describe("The member's role within the organization.")),
+  updatedAt: z.string().check(z.describe('When the membership was last updated (ISO 8601).')),
+  userId: z.string().check(z.describe('Member user id (`usr_…`).')),
+})
+
+/** Columns of the `memberships` table. */
+export type Membership = z.output<typeof Membership>
+
 /** An organization, the top-level tenant that owns API keys. */
 export const Organization = z.object({
   createdAt: z.string().check(z.describe('When the organization was created (ISO 8601).')),
@@ -24,11 +92,182 @@ export const Organization = z.object({
     .string()
     .check(z.describe('Human-readable organization name.'), z.meta({ examples: ['Acme, Inc.'] })),
   updatedAt: z.string().check(z.describe('When the organization was last updated (ISO 8601).')),
+  userId: z
+    .nullable(z.string())
+    .check(
+      z.describe('Owning user id (`usr_…`), or null for organizations created by the super admin.'),
+    ),
 })
 
 /** Columns of the `organizations` table. */
 export type Organization = z.output<typeof Organization>
 
+/** A project: an app or integration within an organization. */
+export const Project = z.object({
+  createdAt: z.string().check(z.describe('When the project was created (ISO 8601).')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque project id (`prj_…`).'),
+      z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  name: z
+    .string()
+    .check(z.describe('Human-readable project name.'), z.meta({ examples: ['Checkout'] })),
+  orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  updatedAt: z.string().check(z.describe('When the project was last updated (ISO 8601).')),
+})
+
+/** Columns of the `projects` table. */
+export type Project = z.output<typeof Project>
+
+/** A transaction sponsored by the managed fee payer — the billable unit of fee payer spend. */
+export const SponsoredTransaction = z.object({
+  apiKeyId: z.string().check(z.describe('API key id (`key_…`) that requested sponsorship.')),
+  billable: z
+    .boolean()
+    .check(z.describe('Whether the sponsorship accrues billable spend; false for sandbox.')),
+  chainId: z.number().check(z.describe('Chain the sponsored transaction targets.')),
+  createdAt: z.string().check(z.describe('When the sponsorship was recorded (ISO 8601).')),
+  currency: z
+    .nullable(z.string())
+    .check(z.describe('Lowercase fee currency the sponsorship settles in (`usd`), or null when the fee token is unverified.')), // prettier-ignore
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Key environment the sponsorship was requested under.')),
+  feeAmount: z
+    .nullable(z.string())
+    .check(z.describe('Actual fee paid in fee-token base units, or null until finalized.')),
+  feeMax: z
+    .nullable(z.string())
+    .check(z.describe('Signed fee cap (`gas × maxFeePerGas`) in base units; pending rows count it against spend limits.')), // prettier-ignore
+  feeToken: z
+    .nullable(z.string())
+    .check(z.describe('Fee token address, or null when the chain default applied.')),
+  finalizedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the sponsorship reached a terminal status (ISO 8601), or null.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque sponsored-transaction id (`stx_…`).'),
+      z.meta({ examples: ['stx_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  meterReportedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the row was reported to the billing meter (ISO 8601), or null; exactly-once marker.')), // prettier-ignore
+  orgId: z.string().check(z.describe('Organization id (`org_…`) the spend attributes to.')),
+  projectId: z.string().check(z.describe('Project id (`prj_…`) the spend attributes to.')),
+  signPayload: z
+    .string()
+    .check(z.describe('Fee-payer sign payload — a stable identity for the sponsored envelope.')),
+  status: z
+    .enum(['failed', 'finalized', 'pending'])
+    .check(z.describe('Pending until a receipt finalizes it or the pending TTL fails it.')),
+  transaction: z
+    .string()
+    .check(z.describe('Serialized sponsored transaction, kept for durable observability.')),
+  transactionHash: z
+    .nullable(z.string())
+    .check(z.describe('Transaction hash, or null for fill intents until reconciled.')),
+})
+
+/** Columns of the `sponsored_transactions` table. */
+export type SponsoredTransaction = z.output<typeof SponsoredTransaction>
+
+/** A per-hour request-count watermark: the running total already reported to the meter. */
+export const RequestUsageBucket = z.object({
+  bucketStart: z.string().check(z.describe('UTC hour start this bucket covers (ISO 8601).')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Environment the requests were served under; `production` or `sandbox`.')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`) the requests attribute to.')),
+  reportedCount: z
+    .number()
+    .check(z.describe('Cumulative request count already reported to the meter for this bucket.')),
+  updatedAt: z.string().check(z.describe('When the watermark last advanced (ISO 8601).')),
+})
+
+/** Columns of the `request_usage_buckets` table. */
+export type RequestUsageBucket = z.output<typeof RequestUsageBucket>
+
+/** One request-count meter event: a frozen additive delta with its exactly-once state. */
+export const RequestUsageMeterEvent = z.object({
+  bucketStart: z.string().check(z.describe('UTC hour start this event bills for (ISO 8601).')),
+  deltaCount: z
+    .number()
+    .check(z.describe('Frozen request count this event bills; a positive additive delta.')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Environment the requests were served under; `production` or `sandbox`.')),
+  error: z.nullable(z.string()).check(z.describe('Last failure detail while `pending`, or null.')),
+  firstAttemptedAt: z.string().check(z.describe('When this event was first claimed (ISO 8601).')),
+  identifier: z
+    .string()
+    .check(z.describe('Deterministic id; also the Stripe meter-event identifier and idempotency key.')), // prettier-ignore
+  orgId: z.string().check(z.describe('Organization id (`org_…`) the requests attribute to.')),
+  reason: z
+    .nullable(z.string())
+    .check(z.describe('Skip reason when `state` is `skipped` (`no_customer` | `customer_canceled`), or null.')), // prettier-ignore
+  reportedAt: z
+    .nullable(z.string())
+    .check(z.describe('When Stripe acknowledged the event (ISO 8601), or null.')),
+  sequence: z
+    .number()
+    .check(z.describe('Delta sequence within the bucket; `0` is the initial seal, `1..n` later deltas.')), // prettier-ignore
+  state: z
+    .enum(['pending', 'reported', 'skipped'])
+    .check(z.describe('Exactly-once state: `pending` retries, `reported` is done, `skipped` is audited.')), // prettier-ignore
+  stripeCustomerId: z.string().check(z.describe('Stripe customer id the event bills against.')),
+})
+
+/** Columns of the `request_usage_meter_events` table. */
+export type RequestUsageMeterEvent = z.output<typeof RequestUsageMeterEvent>
+
+/** An organization's Stripe billing source: the customer link and derived status. */
+export const StripeCustomer = z.object({
+  createdAt: z.string().check(z.describe('When the Stripe source was connected (ISO 8601).')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Environment this Stripe source backs; `production` (live) or `sandbox` (test).')), // prettier-ignore
+  orgId: z.string().check(z.describe('Organization id (`org_…`) this Stripe source belongs to.')),
+  status: z
+    .enum(['active', 'canceled', 'none', 'past_due'])
+    .check(z.describe('Billing status derived from Stripe state; gates production sponsorship.')),
+  stripeCustomerId: z
+    .string()
+    .check(z.describe('Stripe customer id backing this source; never deleted by us.')),
+  updatedAt: z.string().check(z.describe('When the billing status last changed (ISO 8601).')),
+})
+
+/** Columns of the `stripe_customers` table. */
+export type StripeCustomer = z.output<typeof StripeCustomer>
+
+/** A developer identity. */
+export const User = z.object({
+  address: z
+    .nullable(z.string())
+    .check(
+      z.describe(
+        'Wallet address that signs in as this user (stored lowercase), or null for non-wallet identities.',
+      ),
+    ),
+  createdAt: z.string().check(z.describe('When the user was created (ISO 8601).')),
+  email: z
+    .nullable(z.string())
+    .check(z.describe('Verified email from the wallet identity token, or null.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque user id (`usr_…`).'),
+      z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  updatedAt: z.string().check(z.describe('When the user was last updated (ISO 8601).')),
+})
+
+/** Columns of the `users` table. */
+export type User = z.output<typeof User>
+
 /**
  * A verified token: one row per curated token, ordered by `position` (list
  * order is canonical and surfaced to clients). Addresses are stored lowercase;
@@ -96,7 +335,7 @@ export const WebhookSubscription = z.object({
     .string()
     .check(
       z.describe('Subscription id (`wh_…`, lexically time-ordered).'),
-      z.meta({ examples: ['wh_0000019c1a2b3c4d5e6f7g8h'] }),
+      z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
     ),
   lastDeliveryAt: z
     .nullable(z.string())
@@ -145,7 +384,7 @@ export const WebhookDelivery = z.object({
     .string()
     .check(
       z.describe('Delivery id (`whd_…`, lexically time-ordered).'),
-      z.meta({ examples: ['whd_0000019c1a2b3c4d5e6f7g8h'] }),
+      z.meta({ examples: ['whd_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
     ),
   requestUrl: z.string().check(z.describe('Subscriber callback URL the attempt targeted.')),
   responseMs: z