tapimo 0.7.1 → 0.8.0

package/src/db/tables/fundingDeposits.ts

@@ -0,0 +1,373 @@
+import { sql, type JSONColumnType, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_deposits` table. */
+export type Table = Omit<
+  db_Schema.FundingDeposit,
+  'providerRequestIds' | 'providerTransactionHashes'
+> & {
+  /** Private provider request identifiers stored as JSON. */
+  providerRequestIds: JSONColumnType<readonly string[], string, string>
+  /** Private provider transaction references stored as JSON. */
+  providerTransactionHashes: JSONColumnType<readonly string[], string, string>
+}
+
+/** A stored funding deposit. */
+export type Record = Selectable<Table>
+
+/** Ownership filter inherited from the deposit address. */
+export type Owner = {
+  /** Key environment. */
+  environment: Record['environment']
+  /** Owning organization id (`org_…`). */
+  orgId: string
+  /** Attributed project id for project-scoped API keys. */
+  projectId?: string | undefined
+}
+
+/** Inserts one provider-observed source transfer as a funding deposit. */
+export function insert(db: Db.Db, record: Record): Promise<Record> {
+  return db.kysely
+    .insertInto('funding_deposits')
+    .values({
+      ...record,
+      providerRequestIds: JSON.stringify(record.providerRequestIds),
+      providerTransactionHashes: JSON.stringify(record.providerTransactionHashes),
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+/** Inserts a chain-observed source transfer or returns its existing deposit. */
+export async function insertOrGetSource(
+  db: Db.Db,
+  record: Record & { sourceTransferIndex: number },
+): Promise<insertOrGetSource.Result> {
+  const inserted = await db.kysely
+    .insertInto('funding_deposits')
+    .values({
+      ...record,
+      providerRequestIds: JSON.stringify(record.providerRequestIds),
+      providerTransactionHashes: JSON.stringify(record.providerTransactionHashes),
+    })
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'sourceTransactionHash', 'sourceTransferIndex']).doNothing(),
+    )
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return { record: inserted, type: 'created' }
+  const existing = await db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', record.depositAddressId)
+    .where('sourceTransactionHash', '=', record.sourceTransactionHash)
+    .where('sourceTransferIndex', '=', record.sourceTransferIndex)
+    .executeTakeFirstOrThrow()
+  return { record: existing, type: 'existing' }
+}
+
+export declare namespace insertOrGetSource {
+  /** Result of idempotently persisting one verified source transfer. */
+  type Result = { record: Record; type: 'created' | 'existing' }
+}
+
+/** Serializes source attribution for one address and transaction. */
+export function withSourceTransaction<const result>(
+  db: Db.Db,
+  options: withSourceTransaction.Options<result>,
+): Promise<result> {
+  return db.transaction(async (tx) => {
+    const key = `${options.depositAddressId}:${options.sourceTransactionHash.toLowerCase()}`
+    await sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(tx.kysely)
+    return options.fn(tx)
+  })
+}
+
+export declare namespace withSourceTransaction {
+  /** Source identity and transaction-scoped work protected by its advisory lock. */
+  type Options<result> = {
+    /** Funding deposit address that received the transfer. */
+    depositAddressId: string
+    /** Database work serialized for the source transaction. */
+    fn: (db: Db.Db) => Promise<result>
+    /** Source transaction whose deposit attribution must not race. */
+    sourceTransactionHash: string
+  }
+}
+
+/** Gets deposits created from one provider-observed source transaction. */
+export function listByProviderObservation(
+  db: Db.Db,
+  options: listByProviderObservation.Options,
+): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('providerRequestId', '=', options.providerRequestId)
+    .where('sourceTransactionHash', '=', options.sourceTransactionHash)
+    .orderBy('providerTransferIndex', 'asc')
+    .execute()
+}
+
+export declare namespace listByProviderObservation {
+  /** Provider observation fields that identify one source transaction. */
+  type Options = {
+    /** Funding deposit address that received the transfer. */
+    depositAddressId: string
+    /** Provider request that reported the transfer. */
+    providerRequestId: string
+    /** Provider-observed source transaction reference. */
+    sourceTransactionHash: string
+  }
+}
+
+/** Attaches first-observation timestamps to every deposit from one provider request. */
+export function recordRequestObservation(
+  db: Db.Db,
+  options: recordRequestObservation.Options,
+): Promise<Record[]> {
+  return db.kysely
+    .updateTable('funding_deposits')
+    .set({
+      ...(options.pollObservedAt
+        ? {
+            pollObservedAt: sql<string>`LEAST(COALESCE(poll_observed_at, ${options.pollObservedAt}), ${options.pollObservedAt})`,
+          }
+        : {}),
+      ...(options.webhookReceivedAt
+        ? {
+            webhookReceivedAt: sql<string>`LEAST(COALESCE(webhook_received_at, ${options.webhookReceivedAt}), ${options.webhookReceivedAt})`,
+          }
+        : {}),
+    })
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('providerRequestId', '=', options.providerRequestId)
+    .returningAll()
+    .execute()
+}
+
+export declare namespace recordRequestObservation {
+  /** First observations associated with one provider request. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** When polling first observed the provider request. */
+    pollObservedAt?: string | undefined
+    /** Provider request identifier. */
+    providerRequestId: string
+    /** When Tempo first received an authenticated provider webhook. */
+    webhookReceivedAt?: string | undefined
+  }
+}
+
+/** Gets deposits associated with one address and source transaction. */
+export function listBySourceTransaction(
+  db: Db.Db,
+  options: listBySourceTransaction.Options,
+): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('sourceTransactionHash', '=', options.sourceTransactionHash)
+    .orderBy('sourceTransferIndex', 'asc')
+    .execute()
+}
+
+export declare namespace listBySourceTransaction {
+  /** Source transaction fields scoped to one deposit address. */
+  type Options = {
+    /** Funding deposit address that received the transfer. */
+    depositAddressId: string
+    /** Provider-observed source transaction reference. */
+    sourceTransactionHash: string
+  }
+}
+
+/** Returns whether an address has a nonterminal source transfer awaiting provider attribution. */
+export async function hasUnattributed(db: Db.Db, depositAddressId: string): Promise<boolean> {
+  return Boolean(
+    await db.kysely
+      .selectFrom('funding_deposits')
+      .select('id')
+      .where('depositAddressId', '=', depositAddressId)
+      .where('providerRequestId', 'is', null)
+      .where('status', 'not in', ['completed', 'refunded'])
+      .limit(1)
+      .executeTakeFirst(),
+  )
+}
+
+/** Gets a funding deposit without ownership scoping. */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+}
+
+/** Gets an owner-visible funding deposit. */
+export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('environment', '=', owner.environment)
+    .where('id', '=', id)
+    .where('orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  return query.executeTakeFirst()
+}
+
+/** Lists one owner-visible address's deposits newest-first. */
+export function listByAddress(
+  db: Db.Db,
+  owner: Owner,
+  addressId: string,
+  options: listByAddress.Options,
+): Promise<Record[]> {
+  const { cursor, limit } = options
+  let query = db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', addressId)
+    .where('environment', '=', owner.environment)
+    .where('orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('createdAt', '<', cursor.createdAt),
+        eb.and([eb('createdAt', '=', cursor.createdAt), eb('id', '<', cursor.id)]),
+      ]),
+    )
+  return query.orderBy('createdAt', 'desc').orderBy('id', 'desc').limit(limit).execute()
+}
+
+export declare namespace listByAddress {
+  /** Cursor fields for the last deposit returned by the previous page. */
+  type Cursor = {
+    /** Deposit creation time. */
+    createdAt: string
+    /** Deposit id, used as a deterministic tie-breaker. */
+    id: string
+  }
+
+  /** Paging options for one address's deposits. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: Cursor | undefined
+    /** Maximum rows to return. */
+    limit: number
+  }
+}
+
+/** Lists one recipient's owner-visible deposits newest-first. */
+export function listByRecipient(db: Db.Db, options: listByRecipient.Options): Promise<Record[]> {
+  const { cursor, limit, owner, recipient } = options
+  let query = db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('environment', '=', owner.environment)
+    .where('orgId', '=', owner.orgId)
+    .where(sql<boolean>`lower(snapshot->>'recipient') = ${recipient.toLowerCase()}`)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('createdAt', '<', cursor.createdAt),
+        eb.and([eb('createdAt', '=', cursor.createdAt), eb('id', '<', cursor.id)]),
+      ]),
+    )
+  return query.orderBy('createdAt', 'desc').orderBy('id', 'desc').limit(limit).execute()
+}
+
+export declare namespace listByRecipient {
+  /** Recipient filter, ownership, and paging options. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: listByAddress.Cursor | undefined
+    /** Maximum rows to return. */
+    limit: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+    /** Tempo account that receives completed deposits. */
+    recipient: string
+  }
+}
+
+/** Applies a version-guarded deposit update. */
+export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposits')
+    .set({
+      providerOutputAmount: options.providerOutputAmount,
+      providerRequestId: options.providerRequestId,
+      providerRequestIds: JSON.stringify(options.providerRequestIds),
+      providerState: options.providerState,
+      providerTransactionHashes: JSON.stringify(options.providerTransactionHashes),
+      providerTransferIndex: options.providerTransferIndex,
+      retryState: options.retryState,
+      settlementTransaction: options.settlementTransaction,
+      settlementTransactionHash: options.settlementTransactionHash,
+      snapshot: options.snapshot,
+      sourceTransferIndex: options.sourceTransferIndex,
+      status: options.status,
+      statusReason: options.statusReason,
+      subsidyAmount: options.subsidyAmount,
+      tempoGasPaid: options.tempoGasPaid,
+      updatedAt: options.updatedAt,
+      version: options.version,
+    })
+    .where('id', '=', options.id)
+    .where('version', '=', options.expectedVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Guarded deposit update fields. */
+  type Options = {
+    /** Stored version required for the update. */
+    expectedVersion: number
+    /** Funding deposit id (`fdp_…`). */
+    id: string
+    /** Provider output amount confirmed on Tempo. */
+    providerOutputAmount: Record['providerOutputAmount']
+    /** Provider request that first reported the deposit. */
+    providerRequestId: Record['providerRequestId']
+    /** Private provider request identifiers. */
+    providerRequestIds: Record['providerRequestIds']
+    /** Bounded private provider state. */
+    providerState: Record['providerState']
+    /** Provider-leg transaction references. */
+    providerTransactionHashes: Record['providerTransactionHashes']
+    /** Deposit position within the provider request. */
+    providerTransferIndex: Record['providerTransferIndex']
+    /** Bounded private retry state. */
+    retryState: Record['retryState']
+    /** Persisted settlement transaction bytes for exactly-once rebroadcast. */
+    settlementTransaction: Record['settlementTransaction']
+    /** Persisted settlement transaction hash. */
+    settlementTransactionHash: Record['settlementTransactionHash']
+    /** Replacement public snapshot. */
+    snapshot: Record['snapshot']
+    /** Verified transfer position in the source transaction, or null. */
+    sourceTransferIndex: Record['sourceTransferIndex']
+    /** Replacement lifecycle status. */
+    status: Record['status']
+    /** Replacement customer-safe reason. */
+    statusReason: Record['statusReason']
+    /** Destination token amount supplied by Tempo. */
+    subsidyAmount: Record['subsidyAmount']
+    /** Tempo gas paid for settlement, in base units. */
+    tempoGasPaid: Record['tempoGasPaid']
+    /** New material update time. */
+    updatedAt: string
+    /** New material version. */
+    version: number
+  }
+}

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

@@ -0,0 +1,182 @@
+import * as TestApp from '../../../test/App.js'
+import * as FundingIdempotency from './fundingIdempotency.js'
+
+const db = TestApp.database()
+
+const now = new Date('2026-01-01T00:00:00.000Z')
+const replayTtlMs = 86_400_000
+const ttlMs = 60_000
+
+beforeEach(() => vi.useFakeTimers({ now, toFake: ['Date'] }))
+afterEach(() => vi.useRealTimers())
+
+function input(overrides: Partial<FundingIdempotency.claim.Input> = {}) {
+  return {
+    apiKeyId: 'key_test',
+    keyHash: `hash_${Math.random().toString(36).slice(2)}`,
+    requestHash: 'req_aaaa',
+    ttlMs,
+    ...overrides,
+  }
+}
+
+describe('claim', () => {
+  test('claims, blocks equivalent concurrent requests, and flags mismatches', async () => {
+    const first = input()
+    expect(await FundingIdempotency.claim(db, first)).toEqual({
+      createdAt: now.toISOString(),
+      type: 'claimed',
+    })
+    expect(await FundingIdempotency.claim(db, first)).toEqual({ type: 'pending' })
+    expect(await FundingIdempotency.claim(db, { ...first, requestHash: 'req_bbbb' })).toEqual({
+      type: 'mismatch',
+    })
+  })
+
+  test('replays the stored response after completion', async () => {
+    const claimed = input()
+    const result = await FundingIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    const completedAt = new Date('2026-01-01T00:00:30.000Z')
+    vi.setSystemTime(completedAt)
+    await FundingIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"ftr_test"}',
+      transferId: 'ftr_test',
+    })
+    await expect(
+      db.kysely
+        .selectFrom('funding_idempotency_requests')
+        .select('expiresAt')
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ expiresAt: '2026-01-02T00:00:30.000Z' })
+    expect(await FundingIdempotency.claim(db, claimed)).toEqual({
+      response: '{"id":"ftr_test"}',
+      type: 'replay',
+    })
+    // A different request against the completed key still conflicts.
+    expect(await FundingIdempotency.claim(db, { ...claimed, requestHash: 'req_bbbb' })).toEqual({
+      type: 'mismatch',
+    })
+  })
+
+  test('completes non-transfer resources without a transfer id', async () => {
+    const claimed = input()
+    const result = await FundingIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    await FundingIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"fda_test"}',
+    })
+
+    await expect(
+      db.kysely
+        .selectFrom('funding_idempotency_requests')
+        .select('transferId')
+        .where('apiKeyId', '=', claimed.apiKeyId)
+        .where('keyHash', '=', claimed.keyHash)
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ transferId: null })
+  })
+
+  test('reclaims an expired row in place', async () => {
+    const claimed = input()
+    await FundingIdempotency.claim(db, claimed)
+    const afterExpiry = new Date('2026-01-01T00:01:00.001Z')
+    vi.setSystemTime(afterExpiry)
+    expect(await FundingIdempotency.claim(db, claimed)).toEqual({
+      createdAt: afterExpiry.toISOString(),
+      type: 'claimed',
+    })
+  })
+
+  test('release frees a pending claim for retry', async () => {
+    const claimed = input()
+    const result = await FundingIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    await FundingIdempotency.release(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+    })
+    expect(await FundingIdempotency.claim(db, claimed)).toEqual({
+      createdAt: now.toISOString(),
+      type: 'claimed',
+    })
+  })
+
+  test('stale completion and release cannot mutate a replacement claim', async () => {
+    const claimed = input()
+    const original = await FundingIdempotency.claim(db, claimed)
+    expect(original.type).toBe('claimed')
+    if (original.type !== 'claimed') return
+
+    const afterExpiry = new Date('2026-01-01T00:01:00.001Z')
+    vi.setSystemTime(afterExpiry)
+    const replacement = await FundingIdempotency.claim(db, claimed)
+    expect(replacement.type).toBe('claimed')
+    if (replacement.type !== 'claimed') return
+
+    const identity = {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: original.createdAt,
+      keyHash: claimed.keyHash,
+    }
+    expect(
+      await FundingIdempotency.complete(db, {
+        ...identity,
+        replayTtlMs,
+        response: '{"id":"ftr_stale"}',
+        transferId: 'ftr_stale',
+      }),
+    ).toBeUndefined()
+    await FundingIdempotency.release(db, identity)
+    expect(await FundingIdempotency.claim(db, claimed)).toEqual({
+      type: 'pending',
+    })
+  })
+})
+
+describe('checkpoint', () => {
+  test('resumes a provider result and completes it', async () => {
+    const claimed = input()
+    const result = await FundingIdempotency.claim(db, claimed)
+    expect(result.type).toBe('claimed')
+    if (result.type !== 'claimed') return
+    await FundingIdempotency.checkpoint(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"requestId":"relay_request_1"}',
+    })
+
+    expect(await FundingIdempotency.claim(db, claimed)).toEqual({
+      createdAt: now.toISOString(),
+      response: '{"requestId":"relay_request_1"}',
+      type: 'resume',
+    })
+    await FundingIdempotency.complete(db, {
+      apiKeyId: claimed.apiKeyId,
+      createdAt: result.createdAt,
+      keyHash: claimed.keyHash,
+      replayTtlMs,
+      response: '{"id":"fda_test"}',
+    })
+    expect(await FundingIdempotency.claim(db, claimed)).toEqual({
+      response: '{"id":"fda_test"}',
+      type: 'replay',
+    })
+  })
+})