tapimo 0.13.0 → 0.15.0

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

@@ -0,0 +1,160 @@
+import { nanoid } from 'nanoid'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as SponsoredTransactions from './sponsoredTransactions.js'
+import * as SponsorshipAttributions from './sponsorshipAttributions.js'
+
+const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
+
+describe('getExternal', () => {
+  test('behavior: reads only existing attributions in the owning organization', async () => {
+    const db = create()
+    await db.migrate()
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'partner-app',
+      orgId: 'org_1',
+    })
+
+    expect(
+      await SponsorshipAttributions.getExternal(db, { externalId: 'partner-app', orgId: 'org_1' }),
+    ).toStrictEqual(attribution)
+    expect(
+      await SponsorshipAttributions.getExternal(db, { externalId: 'partner-app', orgId: 'org_2' }),
+    ).toBeUndefined()
+    expect(
+      await SponsorshipAttributions.getExternal(db, { externalId: 'unknown-app', orgId: 'org_1' }),
+    ).toBeUndefined()
+    expect(await db.kysely.selectFrom('sponsorship_attributions').selectAll().execute()).toStrictEqual([attribution]) // prettier-ignore
+    await db.close()
+  })
+})
+
+describe('resolveExternal', () => {
+  test('behavior: resolves one canonical id per organization and external id', async () => {
+    const db = create()
+    await db.migrate()
+    const options = { externalId: 'privy-account-1', orgId: 'org_1' }
+
+    const [first, retried, otherOrganization] = await Promise.all([
+      SponsorshipAttributions.resolveExternal(db, options),
+      SponsorshipAttributions.resolveExternal(db, options),
+      SponsorshipAttributions.resolveExternal(db, { ...options, orgId: 'org_2' }),
+    ])
+
+    expect(retried.id).toBe(first.id)
+    expect(otherOrganization.id).not.toBe(first.id)
+    await db.close()
+  })
+})
+
+describe('resolveProject', () => {
+  test('behavior: resolves Tempo Projects through the canonical attribution table', async () => {
+    const db = create()
+    await db.migrate()
+
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: 'prj_1',
+    })
+
+    expect(attribution).toMatchObject({ externalId: null, orgId: 'org_1', projectId: 'prj_1' })
+    await db.close()
+  })
+
+  test('migration: preserves legacy project promotion state and spend attribution', async () => {
+    const db = create()
+    await db.migrate()
+    await db.kysely
+      .insertInto('projects')
+      .values({
+        createdAt: '2026-01-01T00:00:00.000Z',
+        id: 'prj_1',
+        name: 'App',
+        orgId: 'org_1',
+        sponsorshipSubsidyEndsAt: '2026-04-01T00:00:00.000Z',
+        sponsorshipSubsidyStartsAt: '2026-01-01T00:00:00.000Z',
+        sponsorshipSpendLimit: '1000000',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      })
+      .execute()
+    await SponsoredTransactions.upsert(db, {
+      apiKeyId: 'key_1',
+      billable: false,
+      chainId: 4217,
+      environment: 'production',
+      feeMax: '500000',
+      orgId: 'org_1',
+      projectId: 'prj_1',
+      signPayload: `0x${'11'.repeat(32)}`,
+      transaction: `0x${'22'.repeat(32)}`,
+    })
+    for (const name of [
+      '0156_project_sponsorship_attributions',
+      '0157_project_sponsored_transaction_attributions',
+    ]) {
+      const migration = Db.migrations.find((candidate) => candidate.name === name)
+      if (!migration) throw new Error(`Expected ${name}.`)
+      await migration.up(db.kysely).execute()
+    }
+
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: 'prj_1',
+    })
+    expect(attribution).toMatchObject({
+      endsAt: '2026-04-01T00:00:00.000Z',
+      spendLimit: '1000000',
+      startsAt: '2026-01-01T00:00:00.000Z',
+    })
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      { sponsorshipAttributionId: attribution.id },
+    ])
+    await db.close()
+  })
+})
+
+describe('activate', () => {
+  test('behavior: preserves the first promotion snapshot', async () => {
+    const db = create()
+    await db.migrate()
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+    const options = {
+      endsAt: '2026-04-01T00:00:00.000Z',
+      id: attribution.id,
+      orgId: 'org_1',
+      spendLimit: '1000000',
+      startsAt: '2026-01-01T00:00:00.000Z',
+    }
+
+    const first = await SponsorshipAttributions.activate(db, options)
+    const retried = await SponsorshipAttributions.activate(db, {
+      ...options,
+      endsAt: '2027-04-01T00:00:00.000Z',
+      spendLimit: '2000000',
+      startsAt: '2027-01-01T00:00:00.000Z',
+    })
+
+    expect(retried).toStrictEqual(first)
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: does not cross organization boundaries', async () => {
+    const db = create()
+    await db.migrate()
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+
+    expect(
+      await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_2' }),
+    ).toBeUndefined()
+    await db.close()
+  })
+})

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
+  }
+}