tapimo 0.12.0 → 0.14.0

package/src/internal/funding/Transfer.ts

@@ -2,11 +2,15 @@ import * as z from 'zod/mini'
 
 import type * as Db from '../../db/Db.js'
 import * as FundingTransferEvents from '../../db/tables/fundingTransferEvents.js'
+import * as FundingTransferTransactions from '../../db/tables/fundingTransferTransactions.js'
 import * as FundingTransfers from '../../db/tables/fundingTransfers.js'
 import * as Id from '../Id.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
+import type * as Webhooks from '../Webhooks.js'
 import * as Action from './Action.js'
 import * as Provider from './Provider.js'
+import * as TransferWebhook from './TransferWebhook.js'
 
 /** Public funding transfer statuses, in the order documented by the API. */
 export const statuses = [
@@ -60,7 +64,7 @@ const transitions: Record<Status, readonly Status[]> = {
   'awaiting-source': ['action-required', 'expired', 'processing'],
   completed: [],
   expired: [],
-  processing: ['action-required', 'completed', 'refunding'],
+  processing: ['action-required', 'awaiting-source', 'completed', 'refunding'],
   refunded: [],
   refunding: ['action-required', 'refunded'],
 }
@@ -91,22 +95,25 @@ export namespace schema {
     )
 
   /** Customer-safe explanation of a status that needs context. */
-  export const StatusReason = z
-    .object({
-      code: z
-        .enum(statusReasonCodes)
-        .check(
-          z.describe('Stable machine-readable reason code.'),
-          z.meta({ examples: ['destination_amount_below_minimum'] }),
+  export const StatusReason = OpenApi.component(
+    z
+      .object({
+        code: z
+          .enum(statusReasonCodes)
+          .check(
+            z.describe('Stable machine-readable reason code.'),
+            z.meta({ examples: ['destination_amount_below_minimum'] }),
+          ),
+        message: z.string().check(
+          z.describe('Human-readable explanation of the reason.'),
+          z.meta({
+            examples: ['The verified destination amount did not satisfy the quoted minimum.'],
+          }),
         ),
-      message: z.string().check(
-        z.describe('Human-readable explanation of the reason.'),
-        z.meta({
-          examples: ['The verified destination amount did not satisfy the quoted minimum.'],
-        }),
-      ),
-    })
-    .check(z.describe('Why the transfer is in its current status, when context is needed.'))
+      })
+      .check(z.describe('Why the transfer is in its current status, when context is needed.')),
+    'FundingTransferStatusReason',
+  )
 
   /** Funding method selected at creation. */
   export const Method = z
@@ -122,39 +129,45 @@ export namespace schema {
     )
 
   /** One fee applied to the transfer. */
-  export const Fee = z
-    .object({
-      amount: Schema.TokenAmount,
-      side: z
-        .enum(['destination', 'source'])
-        .check(
-          z.describe('Which side of the transfer the fee is taken from.'),
-          z.meta({ examples: ['destination'] }),
-        ),
-      token: Provider.schema.TokenRef,
-      type: z
-        .enum(['provider'])
-        .check(z.describe('What the fee pays for.'), z.meta({ examples: ['provider'] })),
-    })
-    .check(z.describe('One fee applied to the transfer.'))
+  export const Fee = OpenApi.component(
+    z
+      .object({
+        amount: Schema.TokenAmount,
+        side: z
+          .enum(['destination', 'source'])
+          .check(
+            z.describe('Which side of the transfer the fee is taken from.'),
+            z.meta({ examples: ['destination'] }),
+          ),
+        token: Provider.schema.TokenRef,
+        type: z
+          .enum(['provider'])
+          .check(z.describe('What the fee pays for.'), z.meta({ examples: ['provider'] })),
+      })
+      .check(z.describe('One fee applied to the transfer.')),
+    'FundingTransferFee',
+  )
 
   /** Freshness and validity window of the selected quote. */
-  export const Quote = z
-    .object({
-      expiresAt: z
-        .string()
-        .check(
-          z.describe('When the quoted terms stop being executable (ISO 8601).'),
-          z.meta({ examples: ['2026-07-30T04:01:00.000Z'] }),
-        ),
-      sampledAt: z
-        .string()
-        .check(
-          z.describe('When the provider produced the quote (ISO 8601).'),
-          z.meta({ examples: ['2026-07-30T04:00:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('Freshness and validity window of the selected quote.'))
+  export const Quote = OpenApi.component(
+    z
+      .object({
+        expiresAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the quoted terms stop being executable (ISO 8601).'),
+            z.meta({ examples: ['2026-07-30T04:01:00.000Z'] }),
+          ),
+        sampledAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the provider produced the quote (ISO 8601).'),
+            z.meta({ examples: ['2026-07-30T04:00:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('Freshness and validity window of the selected quote.')),
+    'FundingTransferQuote',
+  )
 
   const hashesCheck = (description: string) => [
     z.describe(description),
@@ -219,8 +232,8 @@ export namespace schema {
     .check(z.describe('Quote terms and reconciled public fields of a funding transfer.'))
 
   const fundingTransferFields = {
-    createdAt: z
-      .string()
+    createdAt: z.iso
+      .datetime()
       .check(
         z.describe('When the transfer was created (ISO 8601).'),
         z.meta({ examples: ['2026-07-30T04:00:00.000Z'] }),
@@ -253,8 +266,8 @@ export namespace schema {
     sourceTransactionHashes: snapshotFields.sourceTransactionHashes,
     status: Status,
     statusReason: z.optional(StatusReason),
-    updatedAt: z
-      .string()
+    updatedAt: z.iso
+      .datetime()
       .check(
         z.describe('When the transfer last materially changed (ISO 8601).'),
         z.meta({ examples: ['2026-07-30T04:00:20.000Z'] }),
@@ -270,73 +283,86 @@ export namespace schema {
   }
 
   /** A funding transfer as returned by reads. Reads never include `action`. */
-  export const FundingTransfer = z
-    .object(fundingTransferFields)
-    .check(z.describe('One durable funding transfer.'))
+  export const FundingTransfer = OpenApi.component(
+    z.object(fundingTransferFields).check(z.describe('One durable funding transfer.')),
+    'FundingTransfer',
+  )
 
   /** A created funding transfer: the read shape plus the executable action. */
-  export const CreatedFundingTransfer = z
-    .object({ action: Action.schema.Action, ...fundingTransferFields })
-    .check(z.describe('The created funding transfer, including its one-time executable action.'))
+  export const CreatedFundingTransfer = OpenApi.component(
+    z
+      .object({ action: Action.schema.Action, ...fundingTransferFields })
+      .check(z.describe('The created funding transfer, including its one-time executable action.')),
+    'CreatedFundingTransfer',
+  )
 
   /** Request body accepted by funding transfer creation. */
-  export const CreateRequest = z
-    .strictObject({
-      amount: z
-        .string()
-        .check(
-          z.regex(/^[1-9]\d*$/),
-          z.describe('Amount in base units of the token the mode fixes.'),
-          z.meta({ examples: ['1000000'] }),
-        ),
-      destinationToken: z
-        .string()
-        .check(
-          z.minLength(1),
-          z.describe('Tempo destination token symbol, contract address, or token key.'),
-          z.meta({ examples: ['pathusd'] }),
-        ),
-      mode: Mode,
-      recipient: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]{40}$/),
-          z.describe('Final beneficiary of the transfer.'),
-          z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
-        ),
-      sender: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]{40}$/),
-          z.describe('Source-chain account that signs the funding action.'),
-          z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
-        ),
-      slippageBps: z.optional(
-        z
-          .number()
+  export const CreateRequest = OpenApi.component(
+    z
+      .strictObject({
+        amount: z
+          .string()
           .check(
-            z.int(),
-            z.gte(0),
-            z.lte(10_000),
-            z.describe('Maximum acceptable slippage in basis points.'),
-            z.meta({ examples: [50] }),
+            z.regex(/^[1-9]\d*$/),
+            z.describe('Amount in base units of the token the mode fixes.'),
+            z.meta({ examples: ['1000000'] }),
           ),
-      ),
-      sourceChain: z
-        .string()
-        .check(
-          z.describe('Source chain CAIP-2 id, slug, or alias.'),
-          z.meta({ examples: ['base', 'eip155:8453'] }),
-        ),
-      sourceToken: z
-        .string()
-        .check(
-          z.minLength(1),
-          z.describe('Source token symbol, contract address, or token key.'),
-          z.meta({ examples: ['usdc'] }),
+        destinationToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Tempo destination token symbol, contract address, or token key.'),
+            z.meta({ examples: ['pathusd'] }),
+          ),
+        mode: Mode,
+        provider: z
+          .optional(z.string().check(z.minLength(1)))
+          .check(
+            z.describe('Funding provider ID. Omit to select the best available provider.'),
+            z.meta({ examples: ['relay'] }),
+          ),
+        recipient: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Final beneficiary of the transfer.'),
+            z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+          ),
+        sender: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Source-chain account that signs the funding action.'),
+            z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
+          ),
+        slippageBps: z.optional(
+          z
+            .number()
+            .check(
+              z.int(),
+              z.gte(0),
+              z.lte(10_000),
+              z.describe('Maximum acceptable slippage in basis points.'),
+              z.meta({ examples: [50] }),
+            ),
         ),
-    })
-    .check(z.describe('Funding transfer creation request.'))
+        sourceChain: z
+          .string()
+          .check(
+            z.describe('Source chain CAIP-2 id, slug, or alias.'),
+            z.meta({ examples: ['base', 'eip155:8453'] }),
+          ),
+        sourceToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source token symbol, contract address, or token key.'),
+            z.meta({ examples: ['usdc'] }),
+          ),
+      })
+      .check(z.describe('Funding transfer creation request.')),
+    'CreateFundingTransferRequest',
+  )
 }
 
 /** Stored public snapshot of a funding transfer (see {@link schema.Snapshot}). */
@@ -360,12 +386,22 @@ export const transactionRoles = ['destination', 'refund', 'source'] as const
 /** Role of a verified transaction reference on a transfer. */
 export type TransactionRole = (typeof transactionRoles)[number]
 
+/** Bounded private provider state retained for transfer reconciliation. */
+export type ProviderState = Record<string, unknown>
+
+type Staged = {
+  /** Funding transfer record committed with the webhook obligations. */
+  record: FundingTransfers.Record
+  /** Webhook queue references committed with the transfer. */
+  references: Webhooks.QueueReference[]
+}
+
 /**
  * Creates a durable funding transfer: the row plus its version-1 event commit
  * in one transaction, so every stored version has an immutable public record.
  */
 export async function create(db: Db.Db, input: create.Input): Promise<FundingTransfers.Record> {
-  return db.transaction((tx) => createIn(tx, input))
+  return db.transaction(async (tx) => (await createIn(tx, input)).record)
 }
 
 /**
@@ -373,7 +409,7 @@ export async function create(db: Db.Db, input: create.Input): Promise<FundingTra
  * transaction, for writes that must commit atomically with sibling state
  * (idempotency completion).
  */
-export async function createIn(tx: Db.Db, input: create.Input): Promise<FundingTransfers.Record> {
+export async function createIn(tx: Db.Db, input: create.Input): Promise<createIn.Result> {
   const now = new Date()
   const snapshot = parseSnapshot(input.snapshot)
   const record: FundingTransfers.Record = {
@@ -395,14 +431,22 @@ export async function createIn(tx: Db.Db, input: create.Input): Promise<FundingT
     version: 1,
   }
   const created = await FundingTransfers.insert(tx, record)
-  await FundingTransferEvents.insert(tx, {
+  const event = await FundingTransferEvents.insert(tx, {
     createdAt: record.createdAt,
     snapshot: toPublic(created),
     status: created.status,
     transferId: created.id,
     version: created.version,
   })
-  return created
+  const { references } = await TransferWebhook.stage(tx, {
+    changes: [{ event, record: created }],
+  })
+  return { record: created, references }
+}
+
+export declare namespace createIn {
+  /** Created transfer and webhook queue references committed with it. */
+  type Result = Staged
 }
 
 export declare namespace create {
@@ -419,12 +463,193 @@ export declare namespace create {
     /** Attributed project id, when the creating key is project-attributed. */
     projectId?: string | undefined
     /** Private provider correlation retained for reconciliation. */
-    providerState?: Provider.prepareTransfer.Correlation | undefined
+    providerState?: ProviderState | undefined
     /** The public snapshot captured from the selected quote. */
     snapshot: Snapshot
   }
 }
 
+/** Atomically assigns one verified source transaction and starts reconciliation. */
+export async function registerSourceTransaction(
+  db: Db.Db,
+  options: registerSourceTransaction.Options,
+): Promise<registerSourceTransaction.Result> {
+  return db.transaction(async (tx) => {
+    const current = await FundingTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+
+    const existing = await FundingTransferTransactions.getSource(tx, {
+      chainId: options.chainId,
+      transactionRef: options.transactionHash,
+    })
+    if (existing) {
+      if (existing.transferId !== current.id) return { current, type: 'conflict' }
+      if (current.status !== 'processing' && current.status !== 'completed')
+        return { current, type: 'invalid' }
+      return { record: current, type: 'replayed' }
+    }
+    if (current.status !== 'awaiting-source') return { current, type: 'invalid' }
+
+    const claimed = await FundingTransferTransactions.claimSource(tx, {
+      chainId: options.chainId,
+      createdAt: new Date().toISOString(),
+      role: 'source',
+      transactionRef: options.transactionHash,
+      transferId: options.id,
+    })
+    if (claimed.type === 'conflict') return { current, type: 'conflict' }
+    if (claimed.type === 'replayed') return { record: current, type: 'replayed' }
+
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: { ...current.providerState, ...options.providerState },
+      snapshot: {
+        ...current.snapshot,
+        sourceTransactionHashes: [claimed.record.transactionRef],
+      },
+      status: 'processing',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'registered' }
+  })
+}
+
+export declare namespace registerSourceTransaction {
+  /** Verified source evidence and private provider correlation. */
+  type Options = {
+    /** Source chain CAIP-2 id. */
+    chainId: string
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Private state added for destination reconciliation. */
+    providerState: ProviderState
+    /** Verified source transaction hash. */
+    transactionHash: string
+  }
+
+  /** Source transaction registration outcome. */
+  type Result =
+    | { current: FundingTransfers.Record; type: 'conflict' }
+    | { current: FundingTransfers.Record; type: 'invalid' }
+    | (Staged & { type: 'registered' })
+    | { record: FundingTransfers.Record; type: 'replayed' }
+    | { type: 'not_found' }
+}
+
+/** Atomically removes invalidated source evidence and accepts a replacement. */
+export async function reopenSourceTransaction(
+  db: Db.Db,
+  options: reopenSourceTransaction.Options,
+): Promise<reopenSourceTransaction.Result> {
+  return db.transaction(async (tx) => {
+    const current = await FundingTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.status !== 'processing') return { current, type: 'invalid' }
+
+    const removed = await FundingTransferTransactions.removeSource(tx, {
+      chainId: options.chainId,
+      transactionHash: options.transactionHash,
+      transferId: current.id,
+    })
+    if (!removed) return { current, type: 'invalid' }
+    const { sourceTransactionHashes: _sourceTransactionHashes, ...snapshot } = current.snapshot
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: options.providerState,
+      snapshot,
+      status: 'awaiting-source',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'reopened' }
+  })
+}
+
+export declare namespace reopenSourceTransaction {
+  /** Source evidence to remove after it disappears from the canonical chain. */
+  type Options = {
+    /** Source chain CAIP-2 id. */
+    chainId: string
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Private provider state retained while awaiting replacement evidence. */
+    providerState: ProviderState
+    /** Invalidated source transaction hash. */
+    transactionHash: string
+  }
+
+  /** Source transaction reopening outcome. */
+  type Result =
+    | { current: FundingTransfers.Record; type: 'invalid' }
+    | (Staged & { type: 'reopened' })
+    | { type: 'not_found' }
+}
+
+/** Atomically records a verified destination transaction and completes a transfer. */
+export async function complete(db: Db.Db, options: complete.Options): Promise<complete.Result> {
+  return db.transaction(async (tx) => {
+    const current = await FundingTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.status === 'completed') {
+      const transactions = await FundingTransferTransactions.listByTransfer(tx, current.id)
+      const existing = transactions.some(
+        (transaction) =>
+          transaction.chainId === options.chainId &&
+          transaction.role === 'destination' &&
+          transaction.transactionRef === options.transactionHash.toLowerCase(),
+      )
+      return existing ? { record: current, type: 'replayed' } : { current, type: 'invalid' }
+    }
+    if (current.status !== 'processing') return { current, type: 'invalid' }
+
+    const transaction = await FundingTransferTransactions.insert(tx, {
+      chainId: options.chainId,
+      createdAt: new Date().toISOString(),
+      role: 'destination',
+      transactionRef: options.transactionHash,
+      transferId: options.id,
+    })
+    if (!transaction) throw new AtomicTransitionError()
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      snapshot: {
+        ...current.snapshot,
+        destinationAmount: options.destinationAmount,
+        destinationTransactionHashes: [transaction.transactionRef],
+      },
+      status: 'completed',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'completed' }
+  })
+}
+
+export declare namespace complete {
+  /** Verified destination evidence for one processing transfer. */
+  type Options = {
+    /** Destination chain CAIP-2 id. */
+    chainId: string
+    /** Exact verified destination amount. */
+    destinationAmount: NonNullable<Snapshot['destinationAmount']>
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Verified destination transaction hash. */
+    transactionHash: string
+  }
+
+  /** Transfer completion outcome. */
+  type Result =
+    | { current: FundingTransfers.Record; type: 'invalid' }
+    | (Staged & { type: 'completed' })
+    | { record: FundingTransfers.Record; type: 'replayed' }
+    | { type: 'not_found' }
+}
+
 /**
  * Applies a version-guarded material change: a status transition, a snapshot
  * update, or both. The row update and its immutable event commit in one
@@ -434,39 +659,48 @@ export declare namespace create {
 export async function transition(
   db: Db.Db,
   options: transition.Options,
+): Promise<transition.Result> {
+  return db.transaction((tx) => transitionIn(tx, options))
+}
+
+async function transitionIn(
+  tx: Db.Db,
+  options: transition.Options & { current?: FundingTransfers.Record | undefined },
 ): Promise<transition.Result> {
   const now = new Date()
-  return db.transaction(async (tx) => {
-    const current = await FundingTransfers.get(tx, options.id)
-    if (!current) return { type: 'not_found' }
-    if (current.version !== options.expectedVersion) return { current, type: 'stale' }
-    const status = options.status ?? current.status
-    if (status !== current.status && !canTransition(current.status, status))
-      return { current, type: 'invalid' }
-
-    const updated = await FundingTransfers.update(tx, {
-      expectedVersion: options.expectedVersion,
-      id: options.id,
-      snapshot: options.snapshot === undefined ? current.snapshot : parseSnapshot(options.snapshot),
-      status,
-      statusReason:
-        options.statusReason ?? (status === current.status ? current.statusReason : null),
-      updatedAt: now.toISOString(),
-      version: current.version + 1,
-    })
-    if (!updated) {
-      const latest = await FundingTransfers.get(tx, options.id)
-      return latest ? { current: latest, type: 'stale' } : { type: 'not_found' }
-    }
-    await FundingTransferEvents.insert(tx, {
-      createdAt: updated.updatedAt,
-      snapshot: toPublic(updated),
-      status: updated.status,
-      transferId: updated.id,
-      version: updated.version,
-    })
-    return { record: updated, type: 'applied' }
+  const current = options.current ?? (await FundingTransfers.get(tx, options.id))
+  if (!current) return { type: 'not_found' }
+  if (current.version !== options.expectedVersion) return { current, type: 'stale' }
+  const status = options.status ?? current.status
+  if (status !== current.status && !canTransition(current.status, status))
+    return { current, type: 'invalid' }
+
+  const updated = await FundingTransfers.update(tx, {
+    expectedVersion: options.expectedVersion,
+    id: options.id,
+    providerState:
+      options.providerState === undefined ? current.providerState : options.providerState,
+    snapshot: options.snapshot === undefined ? current.snapshot : parseSnapshot(options.snapshot),
+    status,
+    statusReason: options.statusReason ?? (status === current.status ? current.statusReason : null),
+    updatedAt: now.toISOString(),
+    version: current.version + 1,
+  })
+  if (!updated) {
+    const latest = await FundingTransfers.get(tx, options.id)
+    return latest ? { current: latest, type: 'stale' } : { type: 'not_found' }
+  }
+  const event = await FundingTransferEvents.insert(tx, {
+    createdAt: updated.updatedAt,
+    snapshot: toPublic(updated),
+    status: updated.status,
+    transferId: updated.id,
+    version: updated.version,
+  })
+  const { references } = await TransferWebhook.stage(tx, {
+    changes: [{ event, record: updated }],
   })
+  return { record: updated, references, type: 'applied' }
 }
 
 export declare namespace transition {
@@ -476,6 +710,8 @@ export declare namespace transition {
     expectedVersion: number
     /** Transfer id (`ftr_…`). */
     id: string
+    /** Replacement private provider state; omitted keeps the stored value. */
+    providerState?: ProviderState | null | undefined
     /** Replacement public snapshot; omitted keeps the stored snapshot. */
     snapshot?: Snapshot | undefined
     /** New status; omitted keeps the current status (snapshot-only change). */
@@ -486,7 +722,7 @@ export declare namespace transition {
 
   /** Outcome of a guarded transition. */
   type Result =
-    | { record: FundingTransfers.Record; type: 'applied' }
+    | (Staged & { type: 'applied' })
     | { current: FundingTransfers.Record; type: 'invalid' }
     | { current: FundingTransfers.Record; type: 'stale' }
     | { type: 'not_found' }
@@ -520,3 +756,7 @@ function parseSnapshot(snapshot: Snapshot): Snapshot {
     },
   }
 }
+
+class AtomicTransitionError extends Error {
+  override name = 'Funding.Transfer.AtomicTransitionError'
+}