tapimo 0.14.0 → 0.15.0

package/src/db/tables/sponsorshipAttributions.ts

@@ -0,0 +1,168 @@
+import type { Selectable } from 'kysely'
+
+import * as Id from '../../internal/Id.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `sponsorship_attributions` table. */
+export type Table = db_Schema.SponsorshipAttribution
+
+/** One organization-scoped sponsorship attribution. */
+export type Record = Selectable<Table>
+
+/** Reads a canonical attribution within its owning organization. */
+export function get(db: Db.Db, options: get.Options): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('sponsorship_attributions')
+    .selectAll()
+    .where('id', '=', options.id)
+    .where('orgId', '=', options.orgId)
+    .executeTakeFirst()
+}
+
+export declare namespace get {
+  /** Canonical attribution identity. */
+  type Options = {
+    /** Sponsorship attribution id (`sat_…`). */
+    id: string
+    /** Owning Tempo organization id. */
+    orgId: string
+  }
+}
+
+/** Reads an existing external attribution without granting a new promotion identity. */
+export function getExternal(db: Db.Db, options: getExternal.Options): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('sponsorship_attributions')
+    .selectAll()
+    .where('externalId', '=', options.externalId)
+    .where('orgId', '=', options.orgId)
+    .executeTakeFirst()
+}
+
+export declare namespace getExternal {
+  /** Organization-owned external attribution identity. */
+  type Options = {
+    /** Partner-provided opaque attribution id. */
+    externalId: string
+    /** Owning Tempo organization id. */
+    orgId: string
+  }
+}
+
+/** Provisions an organization-scoped external attribution through trusted server code. */
+export function resolveExternal(db: Db.Db, options: resolveExternal.Options): Promise<Record> {
+  return resolve(db, { externalId: options.externalId, orgId: options.orgId, projectId: null })
+}
+
+export declare namespace resolveExternal {
+  /** External attribution identity. */
+  type Options = {
+    /** Partner-provided opaque attribution id. */
+    externalId: string
+    /** Owning Tempo organization id. */
+    orgId: string
+  }
+}
+
+/** Resolves or creates an organization-scoped Tempo Project attribution. */
+export function resolveProject(db: Db.Db, options: resolveProject.Options): Promise<Record> {
+  return resolve(db, { externalId: null, orgId: options.orgId, projectId: options.projectId })
+}
+
+export declare namespace resolveProject {
+  /** Tempo Project attribution identity. */
+  type Options = {
+    /** Owning Tempo organization id. */
+    orgId: string
+    /** Tempo Project id (`prj_…`). */
+    projectId: string
+  }
+}
+
+async function resolve(db: Db.Db, options: resolve.Options): Promise<Record> {
+  const now = new Date().toISOString()
+  const inserted = await db.kysely
+    .insertInto('sponsorship_attributions')
+    .values({
+      createdAt: now,
+      endsAt: null,
+      externalId: options.externalId,
+      id: Id.generate('sat'),
+      orgId: options.orgId,
+      projectId: options.projectId,
+      spendLimit: null,
+      startsAt: null,
+      updatedAt: now,
+    })
+    .onConflict((oc) => oc.doNothing())
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return inserted
+  return db.kysely
+    .selectFrom('sponsorship_attributions')
+    .selectAll()
+    .where('orgId', '=', options.orgId)
+    .$if(options.externalId !== null, (query) => query.where('externalId', '=', options.externalId))
+    .$if(options.projectId !== null, (query) => query.where('projectId', '=', options.projectId))
+    .executeTakeFirstOrThrow()
+}
+
+declare namespace resolve {
+  /** Exactly one source for a canonical sponsorship attribution. */
+  type Options =
+    | {
+        /** Partner-provided opaque attribution id. */
+        externalId: string
+        /** Owning Tempo organization id. */
+        orgId: string
+        /** No Tempo Project source. */
+        projectId: null
+      }
+    | {
+        /** No external partner source. */
+        externalId: null
+        /** Owning Tempo organization id. */
+        orgId: string
+        /** Tempo Project id (`prj_…`). */
+        projectId: string
+      }
+}
+
+/** Atomically fixes an attribution's promotion policy on first activation. */
+export async function activate(db: Db.Db, options: activate.Options): Promise<Record> {
+  await db.kysely
+    .updateTable('sponsorship_attributions')
+    .set({
+      endsAt: options.endsAt,
+      spendLimit: options.spendLimit,
+      startsAt: options.startsAt,
+      updatedAt: options.startsAt,
+    })
+    .where('id', '=', options.id)
+    .where('orgId', '=', options.orgId)
+    .where('startsAt', 'is', null)
+    .execute()
+  return db.kysely
+    .selectFrom('sponsorship_attributions')
+    .selectAll()
+    .where('id', '=', options.id)
+    .where('orgId', '=', options.orgId)
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace activate {
+  /** Immutable first-activation inputs. */
+  type Options = {
+    /** Promotion end time. */
+    endsAt: string
+    /** Sponsorship attribution id (`sat_…`). */
+    id: string
+    /** Owning Tempo organization id. */
+    orgId: string
+    /** Optional promotion cap in fee-token base units. */
+    spendLimit: string | null
+    /** Promotion start time. */
+    startsAt: string
+  }
+}

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

@@ -0,0 +1,115 @@
+import { nanoid } from 'nanoid'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as SponsorshipReconciliationCursors from './sponsorshipReconciliationCursors.js'
+
+const identity = {
+  chainId: 42431,
+  feePayer: '0xfee0000000000000000000000000000000000000',
+} as const
+
+describe('load', () => {
+  test('behavior: concurrent initial reads share a durable revision', async () => {
+    const db = create()
+    await db.migrate()
+    const [first, second] = await Promise.all([
+      SponsorshipReconciliationCursors.load(db, identity),
+      SponsorshipReconciliationCursors.load(db, identity),
+    ])
+    expect(first).toStrictEqual(second)
+    expect(first).toMatchObject({ complete: true, retryCount: 0, retryKey: null })
+    await db.close()
+  })
+})
+
+describe('save', () => {
+  test('behavior: stale passes cannot overwrite progress or reset a newer scan', async () => {
+    const db = create()
+    await db.migrate()
+    const first = await SponsorshipReconciliationCursors.load(db, identity)
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...first,
+        blockNumber: '10',
+        complete: false,
+        transactionIndex: 2,
+      }),
+    ).toBe(true)
+    const second = await SponsorshipReconciliationCursors.load(db, identity)
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...second,
+        blockNumber: '9',
+        transactionIndex: 1,
+      }),
+    ).toBe(true)
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...second,
+        blockNumber: '10',
+        transactionIndex: 1,
+      }),
+    ).toBe(false)
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...first,
+        complete: true,
+      }),
+    ).toBe(false)
+    const current = await SponsorshipReconciliationCursors.load(db, identity)
+    expect(current).toMatchObject({ blockNumber: '9', complete: false, transactionIndex: 1 })
+
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...current,
+        complete: true,
+      }),
+    ).toBe(true)
+    const restarted = await SponsorshipReconciliationCursors.load(db, identity)
+    expect(restarted.revision).not.toBe(current.revision)
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...restarted,
+        blockNumber: '20',
+        complete: false,
+        transactionIndex: 0,
+      }),
+    ).toBe(true)
+    expect(
+      await SponsorshipReconciliationCursors.save(db, {
+        ...current,
+        complete: true,
+      }),
+    ).toBe(false)
+    expect(await SponsorshipReconciliationCursors.save(db, first)).toBe(false)
+    expect(await SponsorshipReconciliationCursors.load(db, identity)).toMatchObject({
+      blockNumber: '20',
+      complete: false,
+      transactionIndex: 0,
+    })
+    await db.close()
+  })
+
+  test('behavior: overlapping attempts increment a candidate retry only once', async () => {
+    const db = create()
+    await db.migrate()
+    const first = await SponsorshipReconciliationCursors.load(db, identity)
+    const retry = { ...first, retryCount: 1, retryKey: '10:2' }
+    const results = await Promise.all([
+      SponsorshipReconciliationCursors.save(db, retry),
+      SponsorshipReconciliationCursors.save(db, retry),
+    ])
+    expect(results.sort((left, right) => Number(left) - Number(right))).toStrictEqual([false, true])
+    expect(await SponsorshipReconciliationCursors.load(db, identity)).toMatchObject({
+      complete: true,
+      retryCount: 1,
+      retryKey: '10:2',
+    })
+    await db.close()
+  })
+})
+
+function create() {
+  return Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
+}

package/src/db/tables/sponsorshipReconciliationCursors.ts

@@ -0,0 +1,67 @@
+import type { Selectable } from 'kysely'
+import { nanoid } from 'nanoid'
+import type { Address } from 'viem'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `sponsorship_reconciliation_cursors` table. */
+export type Table = db_Schema.SponsorshipReconciliationCursor
+
+/** A durable failed-sponsorship scan position. */
+export type Record = Selectable<Table>
+
+/** Loads or initializes a versioned scan for one chain and fee payer. */
+export async function load(db: Db.Db, options: load.Options): Promise<Record> {
+  await db.kysely
+    .insertInto('sponsorship_reconciliation_cursors')
+    .values({
+      ...options,
+      blockNumber: '0',
+      complete: true,
+      retryCount: 0,
+      retryKey: null,
+      revision: nanoid(),
+      transactionIndex: 0,
+      updatedAt: new Date().toISOString(),
+    })
+    .onConflict((oc) => oc.columns(['chainId', 'feePayer']).doNothing())
+    .execute()
+  return db.kysely
+    .selectFrom('sponsorship_reconciliation_cursors')
+    .selectAll()
+    .where('chainId', '=', options.chainId)
+    .where('feePayer', '=', options.feePayer)
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace load {
+  /** Identity of one failed-sponsorship scan. */
+  type Options = {
+    /** Chain whose fee-payer transactions are scanned. */
+    chainId: number
+    /** Lowercase managed fee-payer address. */
+    feePayer: Address
+  }
+}
+
+/** Saves progress only when the loaded revision is current, returning whether it changed. */
+export async function save(db: Db.Db, record: Record): Promise<boolean> {
+  // Retain completed rows so an older invocation cannot recreate a cleared scan.
+  const result = await db.kysely
+    .updateTable('sponsorship_reconciliation_cursors')
+    .set({
+      blockNumber: record.blockNumber,
+      complete: record.complete,
+      retryCount: record.retryCount,
+      retryKey: record.retryKey,
+      revision: nanoid(),
+      transactionIndex: record.transactionIndex,
+      updatedAt: new Date().toISOString(),
+    })
+    .where('chainId', '=', record.chainId)
+    .where('feePayer', '=', record.feePayer)
+    .where('revision', '=', record.revision)
+    .executeTakeFirst()
+  return result.numUpdatedRows > 0n
+}

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

@@ -1,5 +1,7 @@
+import { sql } from 'kysely'
 import { nanoid } from 'nanoid'
 
+import * as TestApp from '../../../test/App.js'
 import * as Runtime from '../../../test/runtime.js'
 import * as Db from '../Db.js'
 import * as StripeCustomers from './stripeCustomers.js'
@@ -107,3 +109,86 @@ describe('deleteByOrg', () => {
     await db.close()
   })
 })
+
+describe('withLock', () => {
+  test('serializes refreshes on one handle without blocking another environment', async () => {
+    const db = TestApp.databaseFactory()()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_prod' })
+    await StripeCustomers.create(db, { environment: 'sandbox', orgId: 'org_1', stripeCustomerId: 'cus_sandbox' }) // prettier-ignore
+    const entered = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const active = StripeCustomers.withLock(db, {
+      async fn(tx) {
+        entered.resolve()
+        await release.promise
+        return StripeCustomers.setStatus(tx, 'org_1', 'active')
+      },
+      stripeCustomerId: 'cus_prod',
+    })
+    await entered.promise
+    const detached = StripeCustomers.withLock(db, {
+      async fn(tx, record) {
+        expect(record?.status).toBe('active')
+        return StripeCustomers.setStatus(tx, 'org_1', 'none')
+      },
+      stripeCustomerId: 'cus_prod',
+    })
+    const sandbox = StripeCustomers.withLock(db, {
+      fn: (tx) => StripeCustomers.setStatus(tx, 'org_1', 'active', 'sandbox'),
+      stripeCustomerId: 'cus_sandbox',
+    })
+    try {
+      await expect
+        .poll(async () => {
+          const { rows } = await sql<{ blocked: boolean }>`
+            SELECT EXISTS (
+              SELECT 1 FROM pg_locks JOIN pg_stat_activity USING (pid)
+              WHERE relation = 'stripe_customers'::regclass AND wait_event_type = 'Lock'
+            ) AS blocked
+          `.execute(db.kysely)
+          return rows[0]!.blocked
+        })
+        .toBe(true)
+      expect((await sandbox)?.status).toBe('active')
+    } finally {
+      release.resolve()
+      await Promise.allSettled([active, detached, sandbox])
+    }
+    expect((await active)?.status).toBe('active')
+    expect((await detached)?.status).toBe('none')
+    expect((await StripeCustomers.get(db, 'org_1'))?.status).toBe('none')
+    expect((await StripeCustomers.get(db, 'org_1', 'sandbox'))?.status).toBe('active')
+    await db.close()
+  })
+
+  test('rolls back failed refreshes and releases the lock', async () => {
+    const db = TestApp.database()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_a' })
+    await expect(
+      StripeCustomers.withLock(db, {
+        async fn(tx) {
+          await StripeCustomers.setStatus(tx, 'org_1', 'active')
+          throw new Error('refresh failed')
+        },
+        stripeCustomerId: 'cus_a',
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Error: refresh failed]`)
+    expect((await StripeCustomers.get(db, 'org_1'))?.status).toBe('none')
+    const updated = await StripeCustomers.withLock(db, {
+      fn: (tx) => StripeCustomers.setStatus(tx, 'org_1', 'past_due'),
+      stripeCustomerId: 'cus_a',
+    })
+    expect(updated?.status).toBe('past_due')
+    await db.close()
+  })
+
+  test('passes an absent record for unknown customers', async () => {
+    const db = TestApp.database()
+    const record = await StripeCustomers.withLock(db, {
+      fn: async (_tx, record) => record,
+      stripeCustomerId: 'cus_unknown',
+    })
+    expect(record).toBeUndefined()
+    await db.close()
+  })
+})

package/src/db/tables/stripeCustomers.ts

@@ -160,3 +160,27 @@ export function setStatus(
     .returningAll()
     .executeTakeFirst()
 }
+
+/** Serializes a customer's Stripe refresh and status writes in one transaction. */
+export function withLock<result>(db: Db.Db, options: withLock.Options<result>): Promise<result> {
+  return db.kysely.transaction().execute(async (kysely) => {
+    const tx = { ...db, kysely }
+    const record = await kysely
+      .selectFrom('stripe_customers')
+      .selectAll()
+      .where('stripeCustomerId', '=', options.stripeCustomerId)
+      .forUpdate()
+      .executeTakeFirst()
+    return options.fn(tx, record)
+  })
+}
+
+export declare namespace withLock {
+  /** Options for a serialized customer refresh. */
+  type Options<result> = {
+    /** Refresh using the transaction-scoped database; the record is absent if deleted while waiting. */
+    fn: (db: Db.Db, record: Record | undefined) => Promise<result>
+    /** Stripe customer whose refreshes must run sequentially. */
+    stripeCustomerId: string
+  }
+}

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

@@ -0,0 +1,129 @@
+import { sql } from 'kysely'
+
+import * as TestApp from '../../../test/App.js'
+import * as Db from '../Db.js'
+import * as Users from './users.js'
+
+describe('getByEmail', () => {
+  test('normalizes email and returns the oldest matching user', async () => {
+    const db = TestApp.database()
+    try {
+      const first = await Users.upsertByAddress(db, { address: `0x${'11'.repeat(20)}` })
+      const second = await Users.upsertByAddress(db, { address: `0x${'22'.repeat(20)}` })
+      await db.kysely
+        .updateTable('users')
+        .set({ createdAt: '2026-01-01T00:00:00.000Z' })
+        .where('id', '=', first.id)
+        .execute()
+      await db.kysely
+        .updateTable('users')
+        .set({ createdAt: '2026-01-02T00:00:00.000Z' })
+        .where('id', '=', second.id)
+        .execute()
+      // Simulate the previous Worker writing after the normalization migration.
+      await db.kysely
+        .updateTable('users')
+        .set({ email: ' Developer@Example.com ', emailVerified: true })
+        .where('id', '=', first.id)
+        .execute()
+      await Users.setEmail(db, second.id, 'developer@example.com')
+
+      await expect(Users.getByEmail(db, ' DEVELOPER@example.com ')).resolves.toMatchObject({
+        id: first.id,
+      })
+    } finally {
+      await db.close()
+    }
+  })
+})
+
+describe('auth field migration compatibility', () => {
+  test('defaults fields omitted by the previous worker', async () => {
+    const db = TestApp.database()
+    try {
+      const now = new Date().toISOString()
+      await sql`INSERT INTO users (id, address, email, created_at, updated_at) VALUES ('usr_legacy_worker', ${`0x${'33'.repeat(20)}`}, NULL, ${now}, ${now})`.execute(
+        db.kysely,
+      )
+
+      await expect(Users.get(db, 'usr_legacy_worker')).resolves.toMatchObject({
+        emailVerified: false,
+        name: '',
+      })
+    } finally {
+      await db.close()
+    }
+  })
+})
+
+describe('email migration precondition', () => {
+  test('rejects a blank email', async () => {
+    const db = TestApp.database()
+    try {
+      const now = new Date().toISOString()
+      await db.kysely
+        .insertInto('users')
+        .values({
+          address: null,
+          createdAt: now,
+          email: ' ',
+          emailVerified: false,
+          id: 'usr_blank_email',
+          image: null,
+          name: 'Blank email',
+          updatedAt: now,
+        })
+        .execute()
+
+      const migration = Db.migrations.find(
+        (candidate) => candidate.name === '0166_users_email_auth_precondition',
+      )
+      if (!migration) throw new Error('Expected the user-email precondition migration.')
+      await expect(migration.up(db.kysely).execute()).rejects.toThrow(
+        'users.email contains blank values',
+      )
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('allows duplicate normalized emails during the compatibility deployment', async () => {
+    const db = TestApp.database()
+    try {
+      const now = new Date().toISOString()
+      await db.kysely
+        .insertInto('users')
+        .values([
+          {
+            address: null,
+            createdAt: now,
+            email: 'developer@example.com',
+            emailVerified: true,
+            id: 'usr_duplicate_one',
+            image: null,
+            name: 'Duplicate one',
+            updatedAt: now,
+          },
+          {
+            address: null,
+            createdAt: now,
+            email: ' Developer@Example.com ',
+            emailVerified: true,
+            id: 'usr_duplicate_two',
+            image: null,
+            name: 'Duplicate two',
+            updatedAt: now,
+          },
+        ])
+        .execute()
+
+      const migration = Db.migrations.find(
+        (candidate) => candidate.name === '0166_users_email_auth_precondition',
+      )
+      if (!migration) throw new Error('Expected the user-email precondition migration.')
+      await expect(migration.up(db.kysely).execute()).resolves.toBeDefined()
+    } finally {
+      await db.close()
+    }
+  })
+})

package/src/db/tables/users.ts

@@ -1,4 +1,4 @@
-import type { Selectable } from 'kysely'
+import { type Selectable, sql } from 'kysely'
 
 import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
@@ -37,6 +37,23 @@ export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]>
     .execute()
 }
 
+/**
+ * Reads a user by normalized verified email.
+ *
+ * @param db - The database.
+ * @param email - The verified email.
+ * @returns The oldest matching record, or `undefined` when absent.
+ */
+export function getByEmail(db: Db.Db, email: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('users')
+    .selectAll()
+    .where(sql<string>`lower(btrim(email))`, '=', email.trim().toLowerCase())
+    .orderBy('createdAt', 'asc')
+    .orderBy('id', 'asc')
+    .executeTakeFirst()
+}
+
 /**
  * Reads a user by wallet address (compared lowercase).
  *
@@ -52,6 +69,22 @@ export function getByAddress(db: Db.Db, address: string): Promise<Record | undef
     .executeTakeFirst()
 }
 
+/**
+ * Locks and reads a user by wallet address for identity reconciliation.
+ *
+ * @param db - The transaction-scoped database.
+ * @param address - The wallet address.
+ * @returns The locked record, or `undefined` when absent.
+ */
+export function getByAddressForUpdate(db: Db.Db, address: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('users')
+    .selectAll()
+    .where('address', '=', address.toLowerCase())
+    .forUpdate()
+    .executeTakeFirst()
+}
+
 /**
  * Inserts a user for `address` when absent and returns the stored record.
  * Existing users are returned unchanged, so repeated sign-ins are idempotent.
@@ -65,7 +98,16 @@ export async function upsertByAddress(db: Db.Db, input: upsertByAddress.Input):
   const now = new Date().toISOString()
   const inserted = await db.kysely
     .insertInto('users')
-    .values({ address, createdAt: now, email: null, id: Id.generate('usr'), updatedAt: now })
+    .values({
+      address,
+      createdAt: now,
+      email: null,
+      emailVerified: false,
+      id: Id.generate('usr'),
+      image: null,
+      name: address,
+      updatedAt: now,
+    })
     .onConflict((oc) => oc.column('address').doNothing())
     .returningAll()
     .executeTakeFirst()
@@ -95,7 +137,11 @@ export declare namespace upsertByAddress {
 export async function setEmail(db: Db.Db, id: string, email: string): Promise<void> {
   await db.kysely
     .updateTable('users')
-    .set({ email, updatedAt: new Date().toISOString() })
+    .set({
+      email: email.trim().toLowerCase(),
+      emailVerified: true,
+      updatedAt: new Date().toISOString(),
+    }) // prettier-ignore
     .where('id', '=', id)
     .execute()
 }