tapimo 0.10.2 → 0.12.0

package/src/internal/funding/Deposit.ts

@@ -4,6 +4,7 @@ import type * as Db from '../../db/Db.js'
 import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
 import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
 import * as Id from '../Id.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import * as Provider from './Provider.js'
 
@@ -115,22 +116,25 @@ export namespace schema {
     )
 
   /** Customer-safe explanation of a deposit status. */
-  export const StatusReason = z
-    .object({
-      code: z
-        .enum(statusReasonCodes)
-        .check(
-          z.describe('Stable machine-readable reason code.'),
-          z.meta({ examples: ['delivery_liquidity_unavailable'] }),
-        ),
-      message: z
-        .string()
-        .check(
-          z.describe('Human-readable explanation of the current status.'),
-          z.meta({ examples: ['The required destination amount is not currently available.'] }),
-        ),
-    })
-    .check(z.describe('Why a deposit needs attention or recovery.'))
+  export const StatusReason = OpenApi.component(
+    z
+      .object({
+        code: z
+          .enum(statusReasonCodes)
+          .check(
+            z.describe('Stable machine-readable reason code.'),
+            z.meta({ examples: ['delivery_liquidity_unavailable'] }),
+          ),
+        message: z
+          .string()
+          .check(
+            z.describe('Human-readable explanation of the current status.'),
+            z.meta({ examples: ['The required destination amount is not currently available.'] }),
+          ),
+      })
+      .check(z.describe('Why a deposit needs attention or recovery.')),
+    'FundingDepositStatusReason',
+  )
 
   /** Public fields persisted as the deposit snapshot. */
   export const Snapshot = z
@@ -189,54 +193,57 @@ export namespace schema {
     )
 
   /** One detected funding deposit. */
-  export const FundingDeposit = z
-    .object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the deposit was first detected (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
-        ),
-      depositAddressId: Snapshot.shape.depositAddressId,
-      detectionTrigger: z.optional(DetectionTrigger),
-      destinationAmount: Snapshot.shape.destinationAmount,
-      destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
-      destinationChain: Snapshot.shape.destinationChain,
-      destinationToken: Snapshot.shape.destinationToken,
-      destinationTransactionHashes: Snapshot.shape.destinationTransactionHashes,
-      id: z
-        .string()
-        .check(
-          z.regex(/^fdp_[A-Za-z0-9_-]+$/),
-          z.describe('Funding deposit id (`fdp_…`).'),
-          z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-      provider: Snapshot.shape.provider,
-      recipient: Snapshot.shape.recipient,
-      refundAddress: Snapshot.shape.refundAddress,
-      refundAmount: Snapshot.shape.refundAmount,
-      refundTransactionHashes: Snapshot.shape.refundTransactionHashes,
-      sender: Snapshot.shape.sender,
-      sourceAmount: Snapshot.shape.sourceAmount,
-      sourceChain: Snapshot.shape.sourceChain,
-      sourceToken: Snapshot.shape.sourceToken,
-      sourceTransactionHashes: Snapshot.shape.sourceTransactionHashes,
-      sourceTransferIndex: z
-        .optional(z.number().check(z.int(), z.minimum(0)))
-        .check(
-          z.describe('Verified transfer position within the source transaction.'),
-          z.meta({ examples: [0] }),
-        ),
-      status: Status,
-      statusReason: z.optional(StatusReason),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the deposit last materially changed (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:02:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('One detected deposit and its delivery status.'))
+  export const FundingDeposit = OpenApi.component(
+    z
+      .object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit was first detected (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
+          ),
+        depositAddressId: Snapshot.shape.depositAddressId,
+        detectionTrigger: z.optional(DetectionTrigger),
+        destinationAmount: Snapshot.shape.destinationAmount,
+        destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
+        destinationChain: Snapshot.shape.destinationChain,
+        destinationToken: Snapshot.shape.destinationToken,
+        destinationTransactionHashes: Snapshot.shape.destinationTransactionHashes,
+        id: z
+          .string()
+          .check(
+            z.regex(/^fdp_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit id (`fdp_…`).'),
+            z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+        provider: Snapshot.shape.provider,
+        recipient: Snapshot.shape.recipient,
+        refundAddress: Snapshot.shape.refundAddress,
+        refundAmount: Snapshot.shape.refundAmount,
+        refundTransactionHashes: Snapshot.shape.refundTransactionHashes,
+        sender: Snapshot.shape.sender,
+        sourceAmount: Snapshot.shape.sourceAmount,
+        sourceChain: Snapshot.shape.sourceChain,
+        sourceToken: Snapshot.shape.sourceToken,
+        sourceTransactionHashes: Snapshot.shape.sourceTransactionHashes,
+        sourceTransferIndex: z
+          .optional(z.number().check(z.int(), z.minimum(0)))
+          .check(
+            z.describe('Verified transfer position within the source transaction.'),
+            z.meta({ examples: [0] }),
+          ),
+        status: Status,
+        statusReason: z.optional(StatusReason),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit last materially changed (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:02:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('One detected deposit and its delivery status.')),
+    'FundingDeposit',
+  )
 }
 
 /** Stored public snapshot of a funding deposit. */

package/src/internal/funding/DepositAddress.ts

@@ -3,6 +3,7 @@ import * as z from 'zod/mini'
 import type * as Db from '../../db/Db.js'
 import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
 import * as Id from '../Id.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Provider from './Provider.js'
 import * as Transfer from './Transfer.js'
 
@@ -83,51 +84,57 @@ export namespace schema {
     .check(z.describe('Public route and ownership-independent fields of a deposit address.'))
 
   /** One reusable funding deposit address. */
-  export const FundingDepositAddress = z
-    .object({
-      address: Snapshot.shape.address,
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the deposit address was created (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
-        ),
-      destinationChain: Snapshot.shape.destinationChain,
-      destinationToken: Snapshot.shape.destinationToken,
-      id: z
-        .string()
-        .check(
-          z.regex(/^fda_[A-Za-z0-9_-]+$/),
-          z.describe('Funding deposit address id (`fda_…`).'),
-          z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-      provider: Snapshot.shape.provider,
-      recipient: Snapshot.shape.recipient,
-      refundAddress: Snapshot.shape.refundAddress,
-      sourceChain: Snapshot.shape.sourceChain,
-      sourceToken: Snapshot.shape.sourceToken,
-      status: Status,
-      subsidize: Snapshot.shape.subsidize,
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the deposit address last materially changed (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('One reusable address for funding a Tempo account.'))
+  export const FundingDepositAddress = OpenApi.component(
+    z
+      .object({
+        address: Snapshot.shape.address,
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit address was created (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
+          ),
+        destinationChain: Snapshot.shape.destinationChain,
+        destinationToken: Snapshot.shape.destinationToken,
+        id: z
+          .string()
+          .check(
+            z.regex(/^fda_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit address id (`fda_…`).'),
+            z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+        provider: Snapshot.shape.provider,
+        recipient: Snapshot.shape.recipient,
+        refundAddress: Snapshot.shape.refundAddress,
+        sourceChain: Snapshot.shape.sourceChain,
+        sourceToken: Snapshot.shape.sourceToken,
+        status: Status,
+        subsidize: Snapshot.shape.subsidize,
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit address last materially changed (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('One reusable address for funding a Tempo account.')),
+    'FundingDepositAddress',
+  )
 
   /** A reusable funding deposit address with terms sampled during creation. */
-  export const CreatedFundingDepositAddress = z
-    .object({
-      ...FundingDepositAddress.shape,
-      destinationAmount: Provider.schema.FundingQuote.shape.destinationAmount,
-      destinationAmountMin: Provider.schema.FundingQuote.shape.destinationAmountMin,
-      fees: z.array(Transfer.schema.Fee).check(z.describe('Fees applied to the quoted deposit.')),
-      quote: Provider.schema.QuoteDetails,
-      sourceAmount: Provider.schema.FundingQuote.shape.sourceAmount,
-    })
-    .check(z.describe('A reusable funding deposit address with current quoted delivery terms.'))
+  export const CreatedFundingDepositAddress = OpenApi.component(
+    z
+      .object({
+        ...FundingDepositAddress.shape,
+        destinationAmount: Provider.schema.FundingQuote.shape.destinationAmount,
+        destinationAmountMin: Provider.schema.FundingQuote.shape.destinationAmountMin,
+        fees: z.array(Transfer.schema.Fee).check(z.describe('Fees applied to the quoted deposit.')),
+        quote: Provider.schema.QuoteDetails,
+        sourceAmount: Provider.schema.FundingQuote.shape.sourceAmount,
+      })
+      .check(z.describe('A reusable funding deposit address with current quoted delivery terms.')),
+    'CreatedFundingDepositAddress',
+  )
 }
 
 /** Stored public snapshot of a funding deposit address. */

package/src/internal/funding/DepositWebhook.test.ts

@@ -0,0 +1,131 @@
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as WebhookQueueEvents from '../../db/tables/webhookQueueEvents.js'
+import * as Webhooks from '../Webhooks.js'
+import * as Deposit from './Deposit.js'
+import * as FundingDepositAddress from './DepositAddress.js'
+import * as DepositWebhook from './DepositWebhook.js'
+
+const db = TestApp.database()
+
+describe('stage', () => {
+  test('matches owner, environment, project, and filters with stable event ids', async () => {
+    const orgId = 'org_funding_deposit_webhook'
+    const projectId = 'prj_funding_deposit_webhook'
+    const address = await FundingDepositAddress.create(db, {
+      apiKeyId: 'key_funding_deposit_webhook',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-08-12T00:00:00.000Z'),
+      orgId,
+      projectId,
+      providerOutputToken: TestFunding.providerOutputToken(),
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
+        recipient: `0x${'ab'.repeat(20)}`,
+      }),
+    })
+    const deposit = await Deposit.create(db, {
+      now: new Date('2026-08-12T00:01:00.000Z'),
+      providerRequestId: 'relay_deposit_webhook',
+      snapshot: TestFunding.depositSnapshot(address.id),
+      sourceTransactionHash: `0x${'aa'.repeat(32)}`,
+      sourceTransferIndex: 0,
+    })
+    const completed = await Deposit.transition(db, {
+      expectedVersion: deposit.version,
+      id: deposit.id,
+      status: 'completed',
+    })
+    if (completed.type !== 'applied') throw new Error('Expected deposit transition to apply.')
+
+    const filters = {
+      depositAddressId: address.id,
+      recipient: address.recipient.toLowerCase(),
+      status: 'completed',
+    }
+    const org = await subscription({ filters, orgId })
+    const project = await subscription({ filters, orgId, projectId })
+    await subscription({ orgId, projectId: 'prj_funding_deposit_sibling' })
+    await subscription({ environment: 'sandbox', orgId })
+    await subscription({ filters: { status: 'refunded' }, orgId })
+
+    const first = await DepositWebhook.stage(db, { records: [completed.record] })
+    const second = await DepositWebhook.stage(db, { records: [completed.record] })
+    expect({ created: first.created, repeated: second.created }).toEqual({
+      created: 2,
+      repeated: 0,
+    })
+    expect(first.references.map((reference) => reference.subscriptionId)).toEqual([
+      org.id,
+      project.id,
+    ])
+    const event = await WebhookQueueEvents.get(db, first.references[0]!)
+    expect(event?.envelope).toMatchObject({
+      chainId: 4217,
+      data: { id: completed.record.id, status: 'completed' },
+      id: first.references[0]!.eventId,
+      subscriptionId: org.id,
+      type: 'funding:deposit.updated',
+    })
+  })
+})
+
+describe('transition', () => {
+  test('commits the deposit version with its webhook obligation', async () => {
+    const orgId = 'org_funding_deposit_transition'
+    const address = await FundingDepositAddress.create(db, {
+      apiKeyId: 'key_funding_deposit_transition',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-08-12T01:00:00.000Z'),
+      orgId,
+      providerOutputToken: TestFunding.providerOutputToken(),
+      snapshot: TestFunding.depositAddressSnapshot(),
+    })
+    const deposit = await Deposit.create(db, {
+      now: new Date('2026-08-12T01:01:00.000Z'),
+      providerRequestId: 'relay_deposit_transition',
+      snapshot: TestFunding.depositSnapshot(address.id),
+      sourceTransactionHash: `0x${'bb'.repeat(32)}`,
+      sourceTransferIndex: 0,
+    })
+    await subscription({ filters: {}, orgId })
+
+    const transitioned = await DepositWebhook.transition(db, {
+      expectedVersion: deposit.version,
+      id: deposit.id,
+      status: 'bridging',
+    })
+    if (transitioned.result.type !== 'applied') throw new Error('Expected applied transition.')
+
+    expect(transitioned.references).toHaveLength(1)
+    expect(await WebhookQueueEvents.get(db, transitioned.references[0]!)).toMatchObject({
+      envelope: {
+        data: { id: deposit.id, status: 'bridging' },
+        id: transitioned.references[0]!.eventId,
+      },
+    })
+  })
+})
+
+function subscription(options: subscription.Options) {
+  return Webhooks.createSubscription(db, {
+    chainId: 4217,
+    destination: { type: 'url', url: 'https://example.com/webhooks/tempo' },
+    environment: options.environment ?? 'production',
+    eventType: 'funding:deposit.updated',
+    filters: options.filters ?? { recipient: `0x${'ab'.repeat(20)}`, status: 'completed' },
+    owner: { orgId: options.orgId, type: 'api_key' },
+    ...(options.projectId === undefined ? {} : { projectId: options.projectId }),
+  })
+}
+
+declare namespace subscription {
+  type Options = {
+    environment?: 'production' | 'sandbox' | undefined
+    filters?: Record<string, unknown> | undefined
+    orgId: string
+    projectId?: string | undefined
+  }
+}

package/src/internal/funding/DepositWebhook.ts

@@ -0,0 +1,101 @@
+import type * as Db from '../../db/Db.js'
+import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as WebhookSubscriptions from '../../db/tables/webhookSubscriptions.js'
+import * as Webhooks from '../Webhooks.js'
+import * as Deposit from './Deposit.js'
+
+/** Applies a deposit transition and stages every matching webhook obligation atomically. */
+export async function transition(
+  db: Db.Db,
+  options: Deposit.transition.Options,
+): Promise<transition.Result> {
+  return db.transaction(async (tx) => {
+    const result = await Deposit.transition(tx, options)
+    if (result.type !== 'applied') return { references: [], result }
+    const staged = await stage(tx, { records: [result.record] })
+    return { references: staged.references, result }
+  })
+}
+
+export declare namespace transition {
+  /** Transition result plus compact references for atomically staged obligations. */
+  type Result = {
+    /** Queue references staged with the applied transition. */
+    references: Webhooks.QueueReference[]
+    /** Version-guarded deposit transition outcome. */
+    result: Deposit.transition.Result
+  }
+}
+
+/** Stages durable webhook obligations for committed funding deposit versions. */
+export async function stage(
+  db: Db.Db,
+  options: stage.Options,
+): Promise<Webhooks.ensureQueueEvents.Result> {
+  const dispatchables: Webhooks.ensureQueueEvents.Dispatchable[] = []
+  const now = new Date().toISOString()
+  for (const record of unique(options.records)) {
+    const chainId = destinationChainId(record)
+    if (chainId === undefined) continue
+    const subscriptions = await WebhookSubscriptions.listActiveForFundingDeposit(db, {
+      chainId,
+      environment: record.environment,
+      now,
+      orgId: record.orgId,
+      ...(record.projectId === null ? {} : { projectId: record.projectId }),
+    })
+    const data = Deposit.toPublic(record)
+    for (const subscription of subscriptions) {
+      if (!matches(subscription.filters, data)) continue
+      dispatchables.push({
+        envelope: Webhooks.buildKeyedEnvelope({
+          createdAt: new Date(record.updatedAt),
+          data,
+          key: `${record.id}:${record.version}`,
+          subscription,
+        }),
+        subscription,
+      })
+    }
+  }
+  return Webhooks.ensureQueueEvents(db, dispatchables)
+}
+
+export declare namespace stage {
+  /** Committed deposit changes eligible for customer webhook delivery. */
+  type Options = {
+    /** Latest committed funding deposit records. */
+    records: readonly FundingDeposits.Record[]
+  }
+}
+
+function destinationChainId(record: FundingDeposits.Record): number | undefined {
+  const match = /^eip155:(\d+)$/.exec(record.snapshot.destinationChain.id)
+  if (!match) return undefined
+  const chainId = Number(match[1])
+  return Number.isSafeInteger(chainId) && chainId > 0 ? chainId : undefined
+}
+
+function matches(filters: Record<string, unknown>, deposit: Deposit.Public): boolean {
+  if (
+    typeof filters['depositAddressId'] === 'string' &&
+    filters['depositAddressId'] !== deposit.depositAddressId
+  )
+    return false
+  if (
+    typeof filters['recipient'] === 'string' &&
+    filters['recipient'].toLowerCase() !== deposit.recipient.toLowerCase()
+  )
+    return false
+  if (typeof filters['status'] === 'string' && filters['status'] !== deposit.status) return false
+  return true
+}
+
+function unique(records: readonly FundingDeposits.Record[]): FundingDeposits.Record[] {
+  const byId = new Map<string, FundingDeposits.Record>()
+  for (const record of records) {
+    const current = byId.get(record.id)
+    if (!current || current.version < record.version) byId.set(record.id, record)
+  }
+  return [...byId.values()]
+}