tapimo 0.0.2 → 0.2.0

package/src/db/Db.ts

@@ -0,0 +1,542 @@
+import {
+  CamelCasePlugin,
+  type Compilable,
+  CompiledQuery,
+  type Dialect,
+  Kysely,
+  PostgresDialect,
+  type RawBuilder,
+  sql,
+} from 'kysely'
+import * as pg from 'pg'
+
+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 SponsoredTransactions from './tables/sponsoredTransactions.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'
+
+/**
+ * Kysely schema with camelCase columns. {@link CamelCasePlugin} maps table
+ * records, queries, and {@link migrations} DDL to snake_case storage columns.
+ */
+export type Database = {
+  migrations: {
+    appliedAt: string
+    checksum: string
+    name: string
+    /** SQL as applied; null on rows written before the column existed. */
+    sql: string | null
+  }
+  invitations: Invitations.Table
+  memberships: Memberships.Table
+  organizations: Organizations.Table
+  projects: Projects.Table
+  sponsored_transactions: SponsoredTransactions.Table
+  users: Users.Table
+  verified_token_lists: VerifiedTokens.ListTable
+  verified_tokens: VerifiedTokens.Table
+  webhook_deliveries: WebhookDeliveries.Table
+  webhook_subscriptions: WebhookSubscriptions.Table
+}
+
+/**
+ * A SQL-backed authoritative store: the underlying Kysely handle (table
+ * repository modules query through it), schema migrations, and transactions.
+ */
+export type Db = {
+  /** Closes the underlying connection/pool. */
+  close(): Promise<void>
+  /**
+   * Underlying Kysely handle. Transaction-scoped {@link Db} values carry the
+   * transaction handle, so repositories called with `tx` run inside it. */
+  kysely: Kysely<Database>
+  /** Applies any pending schema migrations; safe to call repeatedly and concurrently. */
+  migrate(): Promise<void>
+  /**
+   * Runs `fn` in a transaction — commits on return, rolls back on throw. `fn`
+   * receives a transaction-scoped {@link Db}; pass it (not the outer `Db`) to
+   * repositories so every query inside runs in the transaction.
+   */
+  transaction<value>(fn: (tx: Db) => Promise<value>): Promise<value>
+}
+
+/**
+ * A {@link Db}, or a factory for per-request Workers/Hyperdrive connections.
+ * Node can pass a long-lived singleton. Resolve at the leaf with {@link get}.
+ */
+export type Source = Db | (() => Db)
+
+/**
+ * Resolves a {@link Source} to a {@link Db}. Call at the request leaf so
+ * factories create per-request instances; singletons resolve to themselves.
+ *
+ * @param source - The database or factory.
+ * @returns The resolved {@link Db}.
+ */
+export function get(source: Source): Db {
+  return typeof source === 'function' ? source() : source
+}
+
+/**
+ * One schema migration. `up` builds a single idempotent Kysely DDL statement;
+ * {@link Db.migrate} compiles it for the checksum, then applies it.
+ */
+type Migration = {
+  /** Unique, ordered migration name (e.g. `0001_organizations`). */
+  name: string
+  /**
+   * Builds the migration's DDL against `db`. Use `.ifNotExists()` so the
+   * statement is safe to re-run without a wrapping transaction. */
+  up: (db: Kysely<Database>) => Compilable & { execute(): Promise<unknown> }
+}
+
+/**
+ * Ordered schema migrations for {@link Db.migrate}. Each `up` is one
+ * idempotent statement; compiled-SQL FNV-1a checksums reject edited applied
+ * migrations.
+ */
+export const migrations: readonly Migration[] = [
+  {
+    name: '0001_organizations',
+    up: (db) =>
+      db.schema
+        .createTable('organizations')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('createdBy', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0002_webhook_subscriptions',
+    up: (db) =>
+      db.schema
+        .createTable('webhookSubscriptions')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('ownerType', 'text', (c) => c.notNull())
+        .addColumn('ownerId', 'text', (c) => c.notNull())
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('eventType', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull().defaultTo('active'))
+        .addColumn('destination', 'jsonb', (c) => c.notNull())
+        .addColumn('filters', 'jsonb', (c) => c.notNull().defaultTo(sql`'{}'::jsonb`))
+        .addColumn('context', 'jsonb')
+        .addColumn('secret', 'text', (c) => c.notNull())
+        .addColumn('failureCount', 'integer', (c) => c.notNull().defaultTo(0))
+        .addColumn('lastDeliveryAt', 'text')
+        .addColumn('pollerCursor', 'text')
+        .addColumn('expiresAt', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0003_webhook_deliveries',
+    up: (db) =>
+      db.schema
+        .createTable('webhookDeliveries')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('subscriptionId', 'text', (c) =>
+          c.notNull().references('webhookSubscriptions.id').onDelete('cascade'),
+        )
+        .addColumn('eventId', 'text', (c) => c.notNull())
+        .addColumn('attempt', 'integer', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('requestUrl', 'text', (c) => c.notNull())
+        .addColumn('responseStatus', 'integer')
+        .addColumn('responseMs', 'integer')
+        .addColumn('error', 'text')
+        .addColumn('envelope', 'jsonb', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0004_verified_token_lists',
+    up: (db) =>
+      db.schema
+        .createTable('verifiedTokenLists')
+        .ifNotExists()
+        .addColumn('chainId', 'integer', (c) => c.primaryKey())
+        .addColumn('version', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0005_verified_tokens',
+    up: (db) =>
+      db.schema
+        .createTable('verifiedTokens')
+        .ifNotExists()
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('address', 'text', (c) => c.notNull())
+        .addColumn('symbol', 'text', (c) => c.notNull())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('currency', 'text', (c) => c.notNull())
+        .addColumn('decimals', 'integer', (c) => c.notNull())
+        .addColumn('logoUri', 'text')
+        .addColumn('position', 'integer', (c) => c.notNull())
+        .addPrimaryKeyConstraint('verified_tokens_pkey', ['chainId', 'address']),
+  },
+  {
+    // Case-insensitive symbol uniqueness per chain (`GET /tokens/:symbol`
+    // would otherwise be ambiguous).
+    name: '0006_verified_tokens_symbol_index',
+    up: (db) =>
+      db.schema
+        .createIndex('verified_tokens_symbol_idx')
+        .ifNotExists()
+        .unique()
+        .on('verifiedTokens')
+        .expression(sql`chain_id, lower(symbol)`),
+  },
+  {
+    // Owner list/count/cap scans and `id <` keyset paging.
+    name: '0007_webhook_subscriptions_owner_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_owner_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .columns(['ownerType', 'ownerId', 'id']),
+  },
+  {
+    // Partial index over active subscriptions: the poller's per-stream lookup.
+    // `sql.lit` keeps the predicate literal — DDL cannot carry parameters.
+    name: '0008_webhook_subscriptions_active_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_active_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .columns(['chainId', 'eventType'])
+        .where(sql.ref('status'), '=', sql.lit('active')),
+  },
+  {
+    name: '0009_webhook_subscriptions_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_expires_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .column('expiresAt')
+        .where('expiresAt', 'is not', null),
+  },
+  {
+    // Per-subscription delivery-log paging.
+    name: '0010_webhook_deliveries_subscription_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_deliveries_subscription_idx')
+        .ifNotExists()
+        .on('webhookDeliveries')
+        .columns(['subscriptionId', 'id']),
+  },
+  {
+    name: '0011_webhook_deliveries_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_deliveries_expires_idx')
+        .ifNotExists()
+        .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
+  },
+]
+
+/**
+ * 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.
+ *
+ * @param dialect - The Kysely dialect for the target backend.
+ * @returns The database.
+ */
+export function from(dialect: Dialect): Db {
+  // Builds Db over a top-level Kysely handle or transaction-scoped Kysely handle.
+  function build(kysely: Kysely<Database>): Db {
+    // Prevents same-handle nested transactions from deadlocking capped pools.
+    // Nested work must use the callback's scoped `tx`.
+    let active = false
+    return {
+      async close() {
+        await kysely.destroy()
+      },
+      kysely,
+      async migrate() {
+        // A session advisory lock serializes the full run, including bootstrap
+        // DDL and ledger inserts. Pin one connection and unlock in `finally`.
+        await kysely.connection().execute(async (db) => {
+          await sql`SELECT pg_advisory_lock(${migrateLockKey})`.execute(db)
+          try {
+            await sql`CREATE TABLE IF NOT EXISTS migrations (name TEXT PRIMARY KEY, checksum TEXT NOT NULL, applied_at TEXT NOT NULL)`.execute(
+              db,
+            )
+            await sql`ALTER TABLE migrations ADD COLUMN IF NOT EXISTS sql TEXT`.execute(db)
+            const applied = new Map(
+              (await db.selectFrom('migrations').select(['name', 'checksum', 'sql']).execute()).map(
+                (row) => [row.name, row] as const,
+              ),
+            )
+            for (const migration of migrations) {
+              // Build once: compile (no I/O) for the checksum, execute to apply.
+              const statement = migration.up(db)
+              const compiled = statement.compile().sql
+              const digest = checksum(compiled)
+              const existing = applied.get(migration.name)
+              if (existing !== undefined) {
+                // The digest hashes kysely's rendered SQL, so a kysely upgrade
+                // can flip it with unchanged sources. The stored `sql` is what
+                // actually ran — diff it against the new render to tell render
+                // drift from a real edit (re-baseline procedure in AGENTS.md).
+                if (existing.checksum !== digest)
+                  throw new Error(
+                    `Migration "${migration.name}" was modified after being applied (checksum mismatch). Diff the migrations table's stored sql against the current render before re-baselining.`,
+                  )
+                // Backfill rows from before the column existed; the matching
+                // checksum proves the current render is what was applied.
+                if (existing.sql === null)
+                  await db
+                    .updateTable('migrations')
+                    .set({ sql: compiled })
+                    .where('name', '=', migration.name)
+                    .execute()
+                continue
+              }
+              await statement.execute()
+              await db
+                .insertInto('migrations')
+                .values({
+                  appliedAt: new Date().toISOString(),
+                  checksum: digest,
+                  name: migration.name,
+                  sql: compiled,
+                })
+                .execute()
+            }
+          } finally {
+            await sql`SELECT pg_advisory_unlock(${migrateLockKey})`.execute(db)
+          }
+        })
+      },
+      async transaction(fn) {
+        if (active) throw new Error('Db.transaction does not support nesting.')
+        active = true
+        try {
+          return await kysely.transaction().execute((trx) => fn(build(trx)))
+        } finally {
+          active = false
+        }
+      },
+    }
+  }
+  return build(new Kysely<Database>({ dialect, plugins: [new CamelCasePlugin()] }))
+}
+
+/**
+ * Creates a Postgres-backed {@link Db} via Kysely's `PostgresDialect`. Optional
+ * `schema` scopes every pooled connection and caps the pool for test isolation.
+ *
+ * @param options - Postgres options.
+ * @returns The database.
+ */
+export function postgres(options: postgres.Options): Db {
+  const { connectionString, schema } = options
+  const pool = new pg.Pool(schema ? { connectionString, max: 1 } : { connectionString })
+  return from(
+    new PostgresDialect({
+      pool,
+      ...(schema
+        ? {
+            onCreateConnection: async (connection) => {
+              await connection.executeQuery(
+                CompiledQuery.raw(`CREATE SCHEMA IF NOT EXISTS "${schema}"`),
+              )
+              await connection.executeQuery(CompiledQuery.raw(`SET search_path TO "${schema}"`))
+            },
+          }
+        : {}),
+    }),
+  )
+}
+
+export declare namespace postgres {
+  /** Options for {@link postgres}. */
+  type Options = {
+    /** Postgres connection string (`postgresql://…`). */
+    connectionString: string
+    /** Schema to create and scope the session to (isolates concurrent tests). */
+    schema?: string | undefined
+  }
+}
+
+/**
+ * Fixed key for the {@link Db.migrate} Postgres session advisory lock: the
+ * ASCII bytes of `"tapi"`, making all migrators serialize together.
+ */
+const migrateLockKey = 0x74617069
+
+/**
+ * Deterministic FNV-1a hash of migration SQL, so an applied migration whose
+ * source later changes is rejected (instead of silently diverging). Not
+ * cryptographic — only needs collision resistance for typos.
+ */
+function checksum(sql: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < sql.length; i++) {
+    hash ^= sql.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0')
+}