tapimo 0.7.1 → 0.8.0

package/src/db/tables/fundingDepositAddresses.ts

@@ -0,0 +1,404 @@
+import { sql, type JSONColumnType, type Selectable } from 'kysely'
+import * as pg from 'pg'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_deposit_addresses` table. */
+export type Table = Omit<db_Schema.FundingDepositAddress, 'providerRequestIds'> & {
+  /** Private provider request identifiers stored as JSON. */
+  providerRequestIds: JSONColumnType<readonly string[], string, string>
+}
+
+/** A stored funding deposit address. */
+export type Record = Selectable<Table>
+
+/** Ownership filter derived from the authenticated API key. */
+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
+}
+
+/** Identity fields that make one reusable address match a caller request. */
+export type Match = Owner & {
+  /** Customer destination token key. */
+  destinationTokenKey: string
+  /** Tempo account that receives completed deposits. */
+  recipient: string
+  /** Source-chain account that receives refunds. */
+  refundAddress: string
+  /** Source chain CAIP-2 id. */
+  sourceChainId: string
+  /** Source token key. */
+  sourceTokenKey: string
+  /** Whether Tempo guarantees normalized 1:1 delivery. */
+  subsidize: boolean
+}
+
+/** Inserts a provisioned funding deposit address. */
+export function insert(db: Db.Db, record: Record): Promise<Record> {
+  return db.kysely
+    .insertInto('funding_deposit_addresses')
+    .values({
+      ...record,
+      providerRequestIds: JSON.stringify(record.providerRequestIds),
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+/** Inserts an address or returns the concurrently-created matching resource. */
+export async function insertOrGet(db: Db.Db, options: insertOrGet.Options): Promise<Record> {
+  const record = await db.kysely
+    .insertInto('funding_deposit_addresses')
+    .values({
+      ...options.record,
+      providerRequestIds: JSON.stringify(options.record.providerRequestIds),
+    })
+    .onConflict((oc) =>
+      oc
+        .columns([
+          'orgId',
+          'environment',
+          'projectId',
+          'sourceChainId',
+          'sourceTokenKey',
+          'destinationTokenKey',
+          'recipient',
+          'refundAddress',
+          'subsidize',
+        ])
+        .doNothing(),
+    )
+    .returningAll()
+    .executeTakeFirst()
+    .catch((cause) => {
+      if (
+        cause instanceof pg.DatabaseError &&
+        cause.code === '23505' &&
+        cause.constraint === 'funding_deposit_addresses_provider_address_key'
+      )
+        throw new ConflictError()
+      throw cause
+    })
+  if (record) return record
+  const existing = await getMatching(db, options.match)
+  if (existing) return existing
+  throw new ConflictError()
+}
+
+export declare namespace insertOrGet {
+  /** Record and stable identity used by create-or-get. */
+  type Options = {
+    /** Stable customer-visible address identity. */
+    match: Match
+    /** Provisioned address record to insert. */
+    record: Record
+  }
+}
+
+/** Gets a funding deposit address without ownership scoping. */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+}
+
+/** Gets a funding deposit address by its provider-owned address. */
+export function getByProviderAddress(
+  db: Db.Db,
+  options: getByProviderAddress.Options,
+): Promise<Record | undefined> {
+  const address = /^0x[0-9a-fA-F]{40}$/.test(options.address)
+    ? options.address.toLowerCase()
+    : options.address
+  return db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('address', '=', address)
+    .where('providerId', '=', options.providerId)
+    .executeTakeFirst()
+}
+
+export declare namespace getByProviderAddress {
+  /** Provider address identity received from a reconciliation trigger. */
+  type Options = {
+    /** Provider-owned reusable deposit address. */
+    address: string
+    /** Funding provider id. */
+    providerId: string
+  }
+}
+
+/** Gets an owner-visible funding deposit address. */
+export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .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()
+}
+
+/** Gets the reusable address that matches one owner and route identity. */
+export function getMatching(db: Db.Db, match: Match): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('destinationTokenKey', '=', match.destinationTokenKey)
+    .where('environment', '=', match.environment)
+    .where('orgId', '=', match.orgId)
+    .where('recipient', '=', match.recipient)
+    .where('refundAddress', '=', match.refundAddress)
+    .where('sourceChainId', '=', match.sourceChainId)
+    .where('sourceTokenKey', '=', match.sourceTokenKey)
+    .where('subsidize', '=', match.subsidize)
+  query =
+    match.projectId === undefined
+      ? query.where('projectId', 'is', null)
+      : query.where('projectId', '=', match.projectId)
+  return query.executeTakeFirst()
+}
+
+/** Lists active provider addresses for one source-chain token. */
+export function listActiveSources(
+  db: Db.Db,
+  options: listActiveSources.Options,
+): Promise<readonly Record[]> {
+  return db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('providerId', '=', options.providerId)
+    .where('sourceChainId', '=', options.sourceChainId)
+    .where('sourceTokenKey', '=', options.sourceTokenKey)
+    .where('status', '=', 'active')
+    .orderBy('id', 'asc')
+    .execute()
+}
+
+export declare namespace listActiveSources {
+  /** Provider and source asset identifying one observer shard. */
+  type Options = {
+    /** Funding provider that owns the deposit addresses. */
+    providerId: string
+    /** Source chain CAIP-2 id. */
+    sourceChainId: string
+    /** Source token key. */
+    sourceTokenKey: string
+  }
+}
+
+/** Claims a bounded batch of active addresses due for provider reconciliation. */
+export function claimDue(db: Db.Db, options: claimDue.Options): Promise<readonly Record[]> {
+  return db.transaction(async (tx) => {
+    const due = await tx.kysely
+      .selectFrom('funding_deposit_addresses')
+      .select('id')
+      .where('nextPollAt', '<=', options.now)
+      .where('providerId', '=', options.providerId)
+      .where('status', '=', 'active')
+      .where((eb) =>
+        eb.or([eb('pollLeaseUntil', 'is', null), eb('pollLeaseUntil', '<=', options.now)]),
+      )
+      .orderBy('nextPollAt', 'asc')
+      .orderBy('id', 'asc')
+      .limit(options.limit)
+      .forUpdate()
+      .skipLocked()
+      .execute()
+    if (due.length === 0) return []
+    return tx.kysely
+      .updateTable('funding_deposit_addresses')
+      .set({
+        pollLeaseUntil: options.leaseUntil,
+        pollLeaseVersion: sql<number>`poll_lease_version + 1`,
+      })
+      .where(
+        'id',
+        'in',
+        due.map((record) => record.id),
+      )
+      .returningAll()
+      .execute()
+  })
+}
+
+export declare namespace claimDue {
+  /** Provider and lease bounds for one reconciliation claim. */
+  type Options = {
+    /** Exclusive upper bound on rows claimed in one tick. */
+    limit: number
+    /** Expiry time assigned to each claimed lease. */
+    leaseUntil: string
+    /** Current time used for due and expired-lease comparisons. */
+    now: string
+    /** Funding provider whose addresses should be claimed. */
+    providerId: string
+  }
+}
+
+/** Claims one active address unless another reconciliation owns its lease. */
+export function claim(db: Db.Db, options: claim.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      pollLeaseUntil: options.leaseUntil,
+      pollLeaseVersion: sql<number>`poll_lease_version + 1`,
+    })
+    .where('id', '=', options.id)
+    .where('status', '=', 'active')
+    .where((eb) =>
+      eb.or([eb('pollLeaseUntil', 'is', null), eb('pollLeaseUntil', '<=', options.now)]),
+    )
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace claim {
+  /** Identity and lease bounds for one reconciliation claim. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Expiry time assigned to the claimed lease. */
+    leaseUntil: string
+    /** Current time used for expired-lease comparison. */
+    now: string
+  }
+}
+
+/** Extends an active reconciliation lease without changing its fence. */
+export async function renewPoll(db: Db.Db, options: renewPoll.Options): Promise<boolean> {
+  return Boolean(
+    await db.kysely
+      .updateTable('funding_deposit_addresses')
+      .set({ pollLeaseUntil: options.leaseUntil })
+      .where('id', '=', options.id)
+      .where('pollLeaseUntil', 'is not', null)
+      .where('pollLeaseVersion', '=', options.pollLeaseVersion)
+      .where('status', '=', 'active')
+      .returning('id')
+      .executeTakeFirst(),
+  )
+}
+
+export declare namespace renewPoll {
+  /** Lease identity and renewed expiry guarded by the current fence. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Replacement reconciliation lease expiry. */
+    leaseUntil: string
+    /** Fencing token returned by the claim operation. */
+    pollLeaseVersion: number
+  }
+}
+
+/** Completes an owned reconciliation lease and schedules the address again. */
+export function completePoll(
+  db: Db.Db,
+  options: completePoll.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      lastPolledAt: options.lastPolledAt,
+      nextPollAt: options.nextPollAt,
+      pollFailureCount: 0,
+      pollLeaseUntil: null,
+      providerRequestIds: JSON.stringify(options.providerRequestIds),
+      providerState: options.providerState,
+    })
+    .where('id', '=', options.id)
+    .where('pollLeaseVersion', '=', options.pollLeaseVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace completePoll {
+  /** Successful reconciliation result guarded by the claimed lease version. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Time when provider reconciliation completed. */
+    lastPolledAt: string
+    /** Time when this address becomes due again. */
+    nextPollAt: string
+    /** Fencing token returned by {@link claimDue}. */
+    pollLeaseVersion: number
+    /** Provider request identifiers retained from address provisioning. */
+    providerRequestIds: readonly string[]
+    /** Bounded provider reconciliation state. */
+    providerState: Record['providerState']
+  }
+}
+
+/** Releases an owned reconciliation lease after failure and schedules a retry. */
+export function failPoll(db: Db.Db, options: failPoll.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      nextPollAt: options.nextPollAt,
+      pollFailureCount: sql<number>`poll_failure_count + 1`,
+      pollLeaseUntil: null,
+    })
+    .where('id', '=', options.id)
+    .where('pollLeaseVersion', '=', options.pollLeaseVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace failPoll {
+  /** Failed reconciliation result guarded by the claimed lease version. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Time when this address becomes eligible for retry. */
+    nextPollAt: string
+    /** Fencing token returned by {@link claimDue}. */
+    pollLeaseVersion: number
+  }
+}
+
+/** Applies a version-guarded deposit address status update. */
+export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      status: options.status,
+      updatedAt: options.updatedAt,
+      version: options.version,
+    })
+    .where('id', '=', options.id)
+    .where('version', '=', options.expectedVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Guarded address update fields. */
+  type Options = {
+    /** Stored version required for the update. */
+    expectedVersion: number
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Replacement lifecycle status. */
+    status: Record['status']
+    /** New material update time. */
+    updatedAt: string
+    /** New material version. */
+    version: number
+  }
+}
+
+/** Provider address conflicted with a different customer-visible identity. */
+export class ConflictError extends Error {
+  override name = 'FundingDepositAddresses.ConflictError'
+}

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

@@ -0,0 +1,106 @@
+import * as DepositAddress from '../../internal/funding/DepositAddress.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as FundingDepositRequestObservations from './fundingDepositRequestObservations.js'
+
+const db = TestApp.database()
+
+let addressCounter = 0
+function seedAddress() {
+  const index = addressCounter++
+  return DepositAddress.create(db, {
+    apiKeyId: 'key_request_observations',
+    deliveryStrategy: 'provider',
+    environment: 'production',
+    now: new Date(Date.UTC(2026, 0, 1, 0, 0, index)),
+    orgId: 'org_request_observations',
+    providerOutputToken: TestFunding.providerOutputToken(),
+    snapshot: TestFunding.depositAddressSnapshot({
+      provider: { id: `relay_observation_${index}`, name: 'Relay' },
+      recipient: `0x${index.toString(16).padStart(40, '0')}`,
+    }),
+  })
+}
+
+describe('get', () => {
+  test('returns no observation before a request is seen', async () => {
+    const address = await seedAddress()
+    expect(
+      await FundingDepositRequestObservations.get(db, {
+        depositAddressId: address.id,
+        providerRequestId: 'relay_unseen',
+      }),
+    ).toMatchInlineSnapshot(`undefined`)
+  })
+})
+
+describe('observePoll', () => {
+  test('retains the first poll timestamp for each request', async () => {
+    const address = await seedAddress()
+    await FundingDepositRequestObservations.observePoll(db, {
+      depositAddressId: address.id,
+      observedAt: '2026-01-01T00:00:10.000Z',
+      providerRequestIds: ['relay_poll', 'relay_poll'],
+    })
+    await FundingDepositRequestObservations.observePoll(db, {
+      depositAddressId: address.id,
+      observedAt: '2026-01-01T00:00:09.000Z',
+      providerRequestIds: ['relay_poll'],
+    })
+
+    expect(
+      await FundingDepositRequestObservations.get(db, {
+        depositAddressId: address.id,
+        providerRequestId: 'relay_poll',
+      }),
+    ).toMatchInlineSnapshot(
+      { depositAddressId: expect.any(String) },
+      `
+      {
+        "depositAddressId": Any<String>,
+        "pollObservedAt": "2026-01-01T00:00:09.000Z",
+        "providerRequestId": "relay_poll",
+        "webhookReceivedAt": null,
+      }
+    `,
+    )
+  })
+})
+
+describe('observeWebhook', () => {
+  test('retains both first-observation timestamps regardless of arrival order', async () => {
+    const address = await seedAddress()
+    await FundingDepositRequestObservations.observeWebhook(db, {
+      depositAddressId: address.id,
+      providerRequestId: 'relay_webhook',
+      receivedAt: '2026-01-01T00:00:08.000Z',
+    })
+    await FundingDepositRequestObservations.observePoll(db, {
+      depositAddressId: address.id,
+      observedAt: '2026-01-01T00:00:07.000Z',
+      providerRequestIds: ['relay_webhook'],
+    })
+    await FundingDepositRequestObservations.observeWebhook(db, {
+      depositAddressId: address.id,
+      providerRequestId: 'relay_webhook',
+      receivedAt: '2026-01-01T00:00:06.000Z',
+    })
+
+    expect(
+      await FundingDepositRequestObservations.get(db, {
+        depositAddressId: address.id,
+        providerRequestId: 'relay_webhook',
+      }),
+    ).toMatchInlineSnapshot(
+      { depositAddressId: expect.any(String) },
+      `
+      {
+        "depositAddressId": Any<String>,
+        "pollObservedAt": "2026-01-01T00:00:07.000Z",
+        "providerRequestId": "relay_webhook",
+        "webhookReceivedAt": "2026-01-01T00:00:06.000Z",
+      }
+    `,
+    )
+  })
+})

package/src/db/tables/fundingDepositRequestObservations.ts

@@ -0,0 +1,99 @@
+import { sql, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_deposit_request_observations` table. */
+export type Table = db_Schema.FundingDepositRequestObservation
+
+/** First Tempo observations of one provider request. */
+export type Record = Selectable<Table>
+
+/** Gets observation timestamps for one provider request. */
+export function get(db: Db.Db, options: get.Options): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_deposit_request_observations')
+    .selectAll()
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('providerRequestId', '=', options.providerRequestId)
+    .executeTakeFirst()
+}
+
+export declare namespace get {
+  /** Provider request identity scoped to one reusable address. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** Provider request identifier. */
+    providerRequestId: string
+  }
+}
+
+/** Records when polling first observed each provider request. */
+export async function observePoll(db: Db.Db, options: observePoll.Options): Promise<Record[]> {
+  const providerRequestIds = [...new Set(options.providerRequestIds)]
+  if (providerRequestIds.length === 0) return []
+  return db.kysely
+    .insertInto('funding_deposit_request_observations')
+    .values(
+      providerRequestIds.map((providerRequestId) => ({
+        depositAddressId: options.depositAddressId,
+        pollObservedAt: options.observedAt,
+        providerRequestId,
+        webhookReceivedAt: null,
+      })),
+    )
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'providerRequestId']).doUpdateSet({
+        pollObservedAt: sql<string>`LEAST(COALESCE(funding_deposit_request_observations.poll_observed_at, excluded.poll_observed_at), excluded.poll_observed_at)`,
+      }),
+    )
+    .returningAll()
+    .execute()
+}
+
+export declare namespace observePoll {
+  /** Provider requests observed in one successful poll response. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** When Tempo observed the provider requests. */
+    observedAt: string
+    /** Provider request identifiers returned by the poll. */
+    providerRequestIds: readonly string[]
+  }
+}
+
+/** Records when Tempo first received an authenticated webhook for a provider request. */
+export function observeWebhook(
+  db: Db.Db,
+  options: observeWebhook.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .insertInto('funding_deposit_request_observations')
+    .values({
+      depositAddressId: options.depositAddressId,
+      pollObservedAt: null,
+      providerRequestId: options.providerRequestId,
+      webhookReceivedAt: options.receivedAt,
+    })
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'providerRequestId']).doUpdateSet({
+        webhookReceivedAt: sql<string>`LEAST(COALESCE(funding_deposit_request_observations.webhook_received_at, excluded.webhook_received_at), excluded.webhook_received_at)`,
+      }),
+    )
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace observeWebhook {
+  /** Authenticated webhook observation for one provider request. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** Provider request identifier. */
+    providerRequestId: string
+    /** When Tempo received the webhook. */
+    receivedAt: string
+  }
+}