tapimo 0.2.0 → 0.4.0

package/src/db/Db.ts

@@ -10,11 +10,14 @@ import {
 } 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'
@@ -32,11 +35,15 @@ 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
@@ -383,6 +390,136 @@ export const migrations: readonly Migration[] = [
     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
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -8,6 +8,31 @@ 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
@@ -104,12 +129,18 @@ export const SponsoredTransaction = z.object({
     .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.')),
@@ -122,6 +153,9 @@ export const SponsoredTransaction = z.object({
       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
@@ -141,6 +175,74 @@ export const SponsoredTransaction = z.object({
 /** 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
@@ -233,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())
@@ -282,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

package/src/db/tables/billingSettings.test.ts

@@ -0,0 +1,87 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as Db from '../Db.js'
+import * as BillingSettings from './billingSettings.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Redacts nondeterministic row fields (timestamps). */
+function redact(record: BillingSettings.Record) {
+  return { ...record, createdAt: '<timestamp>', updatedAt: '<timestamp>' }
+}
+
+describe('upsert', () => {
+  test('behavior: inserts defaults for fields not provided', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "currency": "usd",
+        "environment": "production",
+        "orgId": "org_1",
+        "period": "month",
+        "spendLimit": "250",
+        "txFeeLimit": null,
+        "updatedAt": "<timestamp>",
+      }
+    `)
+    await db.close()
+  })
+
+  test('behavior: absent fields keep their stored value', async () => {
+    const db = create()
+    await db.migrate()
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', txFeeLimit: '0.50' })
+    expect(record.spendLimit).toBe('250')
+    expect(record.txFeeLimit).toBe('0.50')
+    await db.close()
+  })
+
+  test('behavior: null clears a limit without touching the other', async () => {
+    const db = create()
+    await db.migrate()
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250', txFeeLimit: '0.50' }) // prettier-ignore
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: null })
+    expect(record.spendLimit).toBeNull()
+    expect(record.txFeeLimit).toBe('0.50')
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: returns the stored row, undefined for orgs without settings', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await BillingSettings.get(db, 'org_1')).toBeUndefined()
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', txFeeLimit: '1' })
+    expect(await BillingSettings.get(db, 'org_1')).toStrictEqual(record)
+    await db.close()
+  })
+
+  test('behavior: production and sandbox settings coexist per org and read disjointly', async () => {
+    const db = create()
+    await db.migrate()
+    const production = await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    const sandbox = await BillingSettings.upsert(db, { environment: 'sandbox', orgId: 'org_1', spendLimit: '10' }) // prettier-ignore
+    expect(sandbox.environment).toBe('sandbox')
+    expect(await BillingSettings.get(db, 'org_1')).toStrictEqual(production)
+    expect(await BillingSettings.get(db, 'org_1', 'sandbox')).toStrictEqual(sandbox)
+    await db.close()
+  })
+})
+
+describe('deleteByOrg', () => {
+  test('behavior: deletes the row and reports absence', async () => {
+    const db = create()
+    await db.migrate()
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    expect(await BillingSettings.deleteByOrg(db, 'org_1')).toBe(true)
+    expect(await BillingSettings.deleteByOrg(db, 'org_1')).toBe(false)
+    expect(await BillingSettings.get(db, 'org_1')).toBeUndefined()
+    await db.close()
+  })
+})

package/src/db/tables/billingSettings.ts

@@ -0,0 +1,108 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `billing_settings` table, derived from `Schema.BillingSettings`. */
+export type Table = db_Schema.BillingSettings
+
+/** A stored billing-settings row. */
+export type Record = Selectable<Table>
+
+/** Currencies limits may be denominated in; single-member today, widens without schema changes. */
+export const currencies = ['usd'] as const satisfies readonly Record['currency'][]
+
+/** Spend-limit windows; single-member today, widens without schema changes. */
+export const periods = ['month'] as const satisfies readonly Record['period'][]
+
+/**
+ * Reads an organization's billing settings.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param environment - The environment to read; defaults to `production`.
+ * @returns The stored record, or `undefined` when the org has none.
+ */
+export function get(
+  db: Db.Db,
+  orgId: string,
+  environment: Record['environment'] = 'production',
+): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('billing_settings')
+    .selectAll()
+    .where('orgId', '=', orgId)
+    .where('environment', '=', environment)
+    .executeTakeFirst()
+}
+
+/**
+ * Upserts an organization's billing settings with PATCH semantics: absent
+ * fields keep their stored value, `null` clears the limit.
+ *
+ * @param db - The database.
+ * @param input - The settings to apply.
+ * @returns The stored record.
+ */
+export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
+  const now = new Date().toISOString()
+  const environment = input.environment ?? 'production'
+  return await db.kysely
+    .insertInto('billing_settings')
+    .values({
+      createdAt: now,
+      currency: input.currency ?? 'usd',
+      environment,
+      orgId: input.orgId,
+      period: input.period ?? 'month',
+      spendLimit: input.spendLimit ?? null,
+      txFeeLimit: input.txFeeLimit ?? null,
+      updatedAt: now,
+    })
+    // Targets the `(org_id, environment)` unique index, which exists both
+    // before and after the org pkey drop release.
+    .onConflict((oc) =>
+      oc.columns(['orgId', 'environment']).doUpdateSet({
+        ...(input.currency !== undefined ? { currency: input.currency } : {}),
+        ...(input.period !== undefined ? { period: input.period } : {}),
+        ...(input.spendLimit !== undefined ? { spendLimit: input.spendLimit } : {}),
+        ...(input.txFeeLimit !== undefined ? { txFeeLimit: input.txFeeLimit } : {}),
+        updatedAt: now,
+      }),
+    )
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace upsert {
+  /** Fields accepted when upserting billing settings; absent = unchanged, null = cleared. */
+  type Input = {
+    /** Currency both limits are denominated in. */
+    currency?: Record['currency'] | undefined
+    /** Environment these settings apply to; defaults to `production`. */
+    environment?: Record['environment'] | undefined
+    /** Organization id (`org_…`) the settings belong to. */
+    orgId: string
+    /** Spend-limit window. */
+    period?: Record['period'] | undefined
+    /** Spend limit per period (decimal string in `currency` units), or null to clear. */
+    spendLimit?: string | null | undefined
+    /** Per-transaction fee cap (decimal string in `currency` units), or null to clear. */
+    txFeeLimit?: string | null | undefined
+  }
+}
+
+/**
+ * Deletes an organization's billing settings.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns Whether a settings row existed and was deleted.
+ */
+export async function deleteByOrg(db: Db.Db, orgId: string): Promise<boolean> {
+  const result = await db.kysely
+    .deleteFrom('billing_settings')
+    .where('orgId', '=', orgId)
+    .executeTakeFirst()
+  return result.numDeletedRows > 0n
+}

package/src/db/tables/invitations.ts

@@ -1,6 +1,6 @@
 import type { Selectable } from 'kysely'
-import { nanoid } from 'nanoid'
 
+import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 import * as Memberships from './memberships.js'
@@ -31,7 +31,7 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
       createdAt: now,
       email: input.email.toLowerCase(),
       expiresAt: input.expiresAt,
-      id: `inv_${nanoid()}`,
+      id: Id.generate('inv'),
       invitedBy: input.invitedBy,
       orgId: input.orgId,
       revokedAt: null,

package/src/db/tables/organizations.test.ts

@@ -12,7 +12,7 @@ function redact(record: Organizations.Record) {
   return {
     ...record,
     createdAt: '<timestamp>',
-    id: /^org_[\w-]{21}$/.test(record.id) ? 'org_<id>' : record.id,
+    id: /^org_[0-9A-Za-z]{24}$/.test(record.id) ? 'org_<id>' : record.id,
     updatedAt: '<timestamp>',
   }
 }

package/src/db/tables/organizations.ts

@@ -1,8 +1,9 @@
 import type { Selectable } from 'kysely'
-import { nanoid } from 'nanoid'
 
+import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
+import type * as Memberships from './memberships.js'
 
 /** Columns of the `organizations` table, derived from `Schema.Organization`. */
 export type Table = db_Schema.Organization
@@ -25,7 +26,7 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
     .values({
       createdAt: now,
       createdBy: input.createdBy ?? null,
-      id: input.id ?? `org_${nanoid()}`,
+      id: input.id ?? Id.generate('org'),
       name: input.name,
       updatedAt: now,
       userId: input.userId ?? null,
@@ -64,7 +65,7 @@ export function createOwned(db: Db.Db, input: createOwned.Input): Promise<Record
       .values({
         createdAt: now,
         createdBy: input.userId,
-        id: `org_${nanoid()}`,
+        id: Id.generate('org'),
         name: input.name,
         updatedAt: now,
         userId: input.userId,
@@ -109,9 +110,13 @@ export function deleteOrganization(db: Db.Db, id: string): Promise<boolean> {
       .where('ownerType', '=', 'api_key')
       .where('ownerId', '=', id)
       .execute()
+    await trx.deleteFrom('billing_settings').where('orgId', '=', id).execute()
     await trx.deleteFrom('invitations').where('orgId', '=', id).execute()
     await trx.deleteFrom('memberships').where('orgId', '=', id).execute()
     await trx.deleteFrom('projects').where('orgId', '=', id).execute()
+    await trx.deleteFrom('request_usage_buckets').where('orgId', '=', id).execute()
+    await trx.deleteFrom('request_usage_meter_events').where('orgId', '=', id).execute()
+    await trx.deleteFrom('stripe_customers').where('orgId', '=', id).execute()
     const result = await trx.deleteFrom('organizations').where('id', '=', id).executeTakeFirst()
     return result.numDeletedRows > 0n
   })
@@ -155,18 +160,23 @@ export function listByUser(db: Db.Db, userId: string): Promise<Record[]> {
 }
 
 /**
- * Lists organizations `userId` is a member of (any role), newest first.
+ * Lists organizations `userId` is a member of (any role), newest first. Each
+ * row carries the caller's membership `role`.
  *
  * @param db - The database.
  * @param userId - The member user id (`usr_…`).
  * @returns The records.
  */
-export function listByMember(db: Db.Db, userId: string): Promise<Record[]> {
+export function listByMember(
+  db: Db.Db,
+  userId: string,
+): Promise<(Record & { role: Memberships.Role })[]> {
   return db.kysely
     .selectFrom('organizations')
     .innerJoin('memberships', 'memberships.orgId', 'organizations.id')
     .where('memberships.userId', '=', userId)
     .selectAll('organizations')
+    .select('memberships.role')
     .orderBy('organizations.createdAt', 'desc')
     .execute()
 }

package/src/db/tables/projects.ts

@@ -1,6 +1,6 @@
 import type { Selectable } from 'kysely'
-import { nanoid } from 'nanoid'
 
+import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 
@@ -23,7 +23,7 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
     .insertInto('projects')
     .values({
       createdAt: now,
-      id: `prj_${nanoid()}`,
+      id: Id.generate('prj'),
       name: input.name,
       orgId: input.orgId,
       updatedAt: now,