tapimo 0.12.0 → 0.14.0

package/src/db/tables/fundingTransferTransactions.ts

@@ -17,15 +17,87 @@ export function insert(db: Db.Db, record: Record): Promise<Record | undefined> {
     .insertInto('funding_transfer_transactions')
     .values({
       ...record,
-      transactionRef: record.chainId.startsWith('eip155:')
-        ? record.transactionRef.toLowerCase()
-        : record.transactionRef,
+      transactionRef: normalize(record.chainId, record.transactionRef),
     })
     .onConflict((oc) => oc.columns(['transferId', 'role', 'transactionRef']).doNothing())
     .returningAll()
     .executeTakeFirst()
 }
 
+/** Claims a source transaction for one transfer without racing another transfer. */
+export async function claimSource(db: Db.Db, record: Record): Promise<claimSource.Result> {
+  const transactionRef = normalize(record.chainId, record.transactionRef)
+  const inserted = await db.kysely
+    .insertInto('funding_transfer_transactions')
+    .values({ ...record, transactionRef })
+    .onConflict((oc) => oc.doNothing())
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return { record: inserted, type: 'claimed' }
+  const existing = await getSource(db, {
+    chainId: record.chainId,
+    transactionRef,
+  })
+  if (existing?.transferId === record.transferId) return { record: existing, type: 'replayed' }
+  return { type: 'conflict' }
+}
+
+export declare namespace claimSource {
+  /** Source transaction ownership outcome. */
+  type Result =
+    | { record: Record; type: 'claimed' }
+    | { record: Record; type: 'replayed' }
+    | { type: 'conflict' }
+}
+
+/** Gets the transfer that owns one source transaction reference. */
+export function getSource(db: Db.Db, options: getSource.Options): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_transfer_transactions')
+    .selectAll()
+    .where('chainId', '=', options.chainId)
+    .where('role', '=', 'source')
+    .where('transactionRef', '=', normalize(options.chainId, options.transactionRef))
+    .executeTakeFirst()
+}
+
+export declare namespace getSource {
+  /** Source transaction identity. */
+  type Options = {
+    /** CAIP-2 chain containing the transaction. */
+    chainId: string
+    /** EVM transaction hash or case-sensitive chain reference. */
+    transactionRef: string
+  }
+}
+
+/** Removes one source transaction only when the transfer still owns it. */
+export function removeSource(
+  db: Db.Db,
+  options: removeSource.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .deleteFrom('funding_transfer_transactions')
+    .where('chainId', '=', options.chainId)
+    .where('role', '=', 'source')
+    .where('transactionRef', '=', normalize(options.chainId, options.transactionHash))
+    .where('transferId', '=', options.transferId)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace removeSource {
+  /** Exact source evidence identity and owner. */
+  type Options = {
+    /** CAIP-2 chain containing the transaction. */
+    chainId: string
+    /** Source transaction reference. */
+    transactionHash: string
+    /** Owning transfer id (`ftr_…`). */
+    transferId: string
+  }
+}
+
 /** Lists a transfer's transaction references, oldest first. */
 export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]> {
   return db.kysely
@@ -35,3 +107,7 @@ export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]>
     .orderBy('createdAt', 'asc')
     .execute()
 }
+
+function normalize(chainId: string, transactionRef: string): string {
+  return chainId.startsWith('eip155:') ? transactionRef.toLowerCase() : transactionRef
+}

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

@@ -49,6 +49,32 @@ describe('list', () => {
   })
 })
 
+describe('listProcessing', () => {
+  test('returns only processing transfers for the provider', async () => {
+    const first = await seed({
+      snapshot: TestFunding.transferSnapshot({ provider: { id: 'stargate', name: 'Stargate' } }),
+    })
+    const second = await seed({
+      snapshot: TestFunding.transferSnapshot({ provider: { id: 'stargate', name: 'Stargate' } }),
+    })
+    const relay = await seed()
+    await Transfer.transition(db, { expectedVersion: 1, id: first.id, status: 'processing' })
+    await Transfer.transition(db, { expectedVersion: 1, id: second.id, status: 'processing' })
+    await Transfer.transition(db, { expectedVersion: 1, id: relay.id, status: 'processing' })
+
+    const page = await FundingTransfers.listProcessing(db, { limit: 1, providerId: 'stargate' })
+    const rest = await FundingTransfers.listProcessing(db, {
+      cursor: page[0]!.id,
+      limit: 1,
+      providerId: 'stargate',
+    })
+    expect([page.map((row) => row.id), rest.map((row) => row.id)]).toEqual([
+      [first.id],
+      [second.id],
+    ])
+  })
+})
+
 describe('count', () => {
   test('shares the list filter and stops at the cap', async () => {
     const total = await FundingTransfers.count(db, owner, { cap: 100 })

package/src/db/tables/fundingTransfers.ts

@@ -40,6 +40,39 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
     .executeTakeFirst()
 }
 
+/** Lists processing transfers for one provider, oldest first. */
+export function listProcessing(db: Db.Db, options: listProcessing.Options): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('providerId', '=', options.providerId)
+    .where('status', '=', 'processing')
+  if (options.cursor !== undefined) query = query.where('id', '>', options.cursor)
+  return query.orderBy('id', 'asc').limit(options.limit).execute()
+}
+
+export declare namespace listProcessing {
+  /** Provider filter for one recovery scan. */
+  type Options = {
+    /** Exclusive lower bound from the prior recovery page. */
+    cursor?: string | undefined
+    /** Maximum transfers returned in one recovery page. */
+    limit: number
+    /** Funding provider id. */
+    providerId: string
+  }
+}
+
+/** Gets and locks a transfer for one atomic domain mutation. */
+export function getForUpdate(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('id', '=', id)
+    .forUpdate()
+    .executeTakeFirst()
+}
+
 /** Gets an owner-visible transfer by id; `undefined` for absent or foreign rows. */
 export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record | undefined> {
   let query = db.kysely
@@ -120,6 +153,7 @@ export function update(db: Db.Db, options: update.Options): Promise<Record | und
   return db.kysely
     .updateTable('funding_transfers')
     .set({
+      providerState: options.providerState,
       snapshot: options.snapshot,
       status: options.status,
       statusReason: options.statusReason,
@@ -139,6 +173,8 @@ export declare namespace update {
     expectedVersion: number
     /** Transfer id (`ftr_…`). */
     id: string
+    /** Replacement private provider state; omitted keeps the stored value. */
+    providerState?: Record['providerState'] | undefined
     /** Replacement public snapshot. */
     snapshot: Record['snapshot']
     /** New lifecycle status. */

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

@@ -34,6 +34,8 @@ describe('create', () => {
         "createdBy": null,
         "id": "org_<id>",
         "name": "Acme, Inc.",
+        "sponsorshipSubsidyDurationDays": null,
+        "sponsorshipSubsidyProjectSpendLimit": null,
         "updatedAt": "<timestamp>",
         "userId": null,
       }
@@ -55,6 +57,8 @@ describe('create', () => {
         "createdBy": "admin@tempo.xyz",
         "id": "org_explicit",
         "name": "Explicit",
+        "sponsorshipSubsidyDurationDays": null,
+        "sponsorshipSubsidyProjectSpendLimit": null,
         "updatedAt": "<timestamp>",
         "userId": null,
       }
@@ -170,6 +174,43 @@ describe('update', () => {
   })
 })
 
+describe('setSponsorshipSubsidy', () => {
+  test('behavior: replaces and disables the organization policy', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+
+    const enabled = await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: 90,
+      projectSpendLimit: '100.00',
+    })
+    expect({
+      durationDays: enabled?.sponsorshipSubsidyDurationDays,
+      projectSpendLimit: enabled?.sponsorshipSubsidyProjectSpendLimit,
+    }).toMatchInlineSnapshot(`
+      {
+        "durationDays": 90,
+        "projectSpendLimit": "100.00",
+      }
+    `)
+
+    const disabled = await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: null,
+      projectSpendLimit: null,
+    })
+    expect({
+      durationDays: disabled?.sponsorshipSubsidyDurationDays,
+      projectSpendLimit: disabled?.sponsorshipSubsidyProjectSpendLimit,
+    }).toMatchInlineSnapshot(`
+      {
+        "durationDays": null,
+        "projectSpendLimit": null,
+      }
+    `)
+    await db.close()
+  })
+})
+
 describe('upsert', () => {
   test('behavior: inserts when absent, defaulting name to the id', async () => {
     const db = create()

package/src/db/tables/organizations.ts

@@ -31,6 +31,8 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
       createdBy: input.createdBy ?? null,
       id: input.id ?? Id.generate('org'),
       name: input.name,
+      sponsorshipSubsidyDurationDays: null,
+      sponsorshipSubsidyProjectSpendLimit: null,
       updatedAt: now,
       userId: input.userId ?? null,
     })
@@ -70,6 +72,8 @@ export function createOwned(db: Db.Db, input: createOwned.Input): Promise<Record
         createdBy: input.userId,
         id: Id.generate('org'),
         name: input.name,
+        sponsorshipSubsidyDurationDays: null,
+        sponsorshipSubsidyProjectSpendLimit: null,
         updatedAt: now,
         userId: input.userId,
       })
@@ -422,6 +426,49 @@ export declare namespace update {
   }
 }
 
+/**
+ * Replaces the organization's sponsorship subsidy policy. A null duration
+ * disables the program; an enabled policy may omit its per-project spend cap.
+ *
+ * @param db - The database.
+ * @param id - The organization id (`org_…`).
+ * @param input - The replacement subsidy policy.
+ * @returns The updated organization, or `undefined` when absent.
+ */
+export function setSponsorshipSubsidy(
+  db: Db.Db,
+  id: string,
+  input: setSponsorshipSubsidy.Input,
+): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('organizations')
+    .set({
+      sponsorshipSubsidyDurationDays: input.durationDays,
+      sponsorshipSubsidyProjectSpendLimit: input.projectSpendLimit,
+      updatedAt: new Date().toISOString(),
+    })
+    .where('id', '=', id)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace setSponsorshipSubsidy {
+  /** Replacement organization subsidy policy. */
+  type Input =
+    | {
+        /** Fixed promotion duration in days. */
+        durationDays: 90
+        /** Optional decimal USD spend cap applied independently to each project. */
+        projectSpendLimit: string | null
+      }
+    | {
+        /** Null disables the promotion. */
+        durationDays: null
+        /** Null disables the promotion. */
+        projectSpendLimit: null
+      }
+}
+
 /**
  * Inserts an organization when absent (`ON CONFLICT DO NOTHING`) — the
  * mint/backfill path, where a key's `orgId` must resolve to a real row. The
@@ -439,6 +486,8 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<void> {
       createdBy: input.createdBy ?? null,
       id: input.id,
       name: input.name ?? input.id,
+      sponsorshipSubsidyDurationDays: null,
+      sponsorshipSubsidyProjectSpendLimit: null,
       updatedAt: now,
     })
     .onConflict((oc) => oc.column('id').doNothing())

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

@@ -0,0 +1,55 @@
+import { nanoid } from 'nanoid'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as Projects from './projects.js'
+
+const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
+
+describe('activateSponsorship', () => {
+  test('behavior: stores the first activation time once', async () => {
+    const db = create()
+    await db.migrate()
+    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
+
+    const first = await Projects.activateSponsorship(db, {
+      at: '2026-01-01T00:00:00.000Z',
+      endsAt: '2026-04-01T00:00:00.000Z',
+      id: project.id,
+      orgId: 'org_1',
+      spendLimit: '100000000',
+    })
+    const second = await Projects.activateSponsorship(db, {
+      at: '2026-02-01T00:00:00.000Z',
+      endsAt: '2026-05-02T00:00:00.000Z',
+      id: project.id,
+      orgId: 'org_1',
+      spendLimit: '200000000',
+    })
+
+    expect(first?.sponsorshipSubsidyStartsAt).toMatchInlineSnapshot(`"2026-01-01T00:00:00.000Z"`)
+    expect(first?.sponsorshipSubsidyEndsAt).toMatchInlineSnapshot(`"2026-04-01T00:00:00.000Z"`)
+    expect(second?.sponsorshipSubsidyStartsAt).toBe(first?.sponsorshipSubsidyStartsAt)
+    expect(second?.sponsorshipSubsidyEndsAt).toBe(first?.sponsorshipSubsidyEndsAt)
+    expect(second?.sponsorshipSpendLimit).toBe(first?.sponsorshipSpendLimit)
+    expect(second?.sponsorshipSpendLimit).toBe('100000000')
+    await db.close()
+  })
+
+  test('behavior: requires matching organization ownership', async () => {
+    const db = create()
+    await db.migrate()
+    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
+
+    expect(
+      await Projects.activateSponsorship(db, {
+        at: '2026-01-01T00:00:00.000Z',
+        endsAt: '2026-04-01T00:00:00.000Z',
+        id: project.id,
+        orgId: 'org_2',
+        spendLimit: '100000000',
+      }),
+    ).toBeUndefined()
+    await db.close()
+  })
+})

package/src/db/tables/projects.ts

@@ -1,4 +1,4 @@
-import type { Selectable } from 'kysely'
+import { sql, type Selectable } from 'kysely'
 
 import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
@@ -26,6 +26,9 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
       id: Id.generate('prj'),
       name: input.name,
       orgId: input.orgId,
+      sponsorshipSubsidyEndsAt: null,
+      sponsorshipSubsidyStartsAt: null,
+      sponsorshipSpendLimit: null,
       updatedAt: now,
     })
     .returningAll()
@@ -65,6 +68,48 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('projects').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Sets a project's sponsorship activation time once. Concurrent first
+ * requests converge on the same stored timestamp.
+ *
+ * @param db - The database.
+ * @param options - Project ownership and activation time.
+ * @returns The project with its stable activation time, or `undefined` when absent.
+ */
+export function activateSponsorship(
+  db: Db.Db,
+  options: activateSponsorship.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('projects')
+    .set({
+      sponsorshipSpendLimit: sql`case when sponsorship_subsidy_starts_at is null then ${options.spendLimit} else sponsorship_spend_limit end`,
+      sponsorshipSubsidyEndsAt: sql`coalesce(sponsorship_subsidy_ends_at, ${options.endsAt})`,
+      sponsorshipSubsidyStartsAt: sql`coalesce(sponsorship_subsidy_starts_at, ${options.at})`,
+      updatedAt: sql`case when sponsorship_subsidy_starts_at is null then ${options.at} else updated_at end`,
+    })
+    .where('id', '=', options.id)
+    .where('orgId', '=', options.orgId)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace activateSponsorship {
+  /** Project activation inputs. */
+  type Options = {
+    /** Activation time used only when the project has not started its window. */
+    at: string
+    /** End of the promotion window, stored with the first activation. */
+    endsAt: string
+    /** Project id (`prj_…`). */
+    id: string
+    /** Owning organization id (`org_…`). */
+    orgId: string
+    /** Optional promotion cap in fee-token base units, stored only on first activation. */
+    spendLimit: string | null
+  }
+}
+
 /**
  * Reads projects by id for operational attribution displays.
  *