tapimo 0.7.1 → 0.7.2

package/src/db/tables/fundingTransferTransactions.ts

@@ -0,0 +1,37 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_transfer_transactions` table. */
+export type Table = db_Schema.FundingTransferTransaction
+/** One verified transaction reference on a transfer. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts a transaction reference, lowercasing EVM hashes while preserving
+ * other references. Repeats return `undefined`; conflicting source ownership throws.
+ */
+export function insert(db: Db.Db, record: Record): Promise<Record | undefined> {
+  return db.kysely
+    .insertInto('funding_transfer_transactions')
+    .values({
+      ...record,
+      transactionRef: record.chainId.startsWith('eip155:')
+        ? record.transactionRef.toLowerCase()
+        : record.transactionRef,
+    })
+    .onConflict((oc) => oc.columns(['transferId', 'role', 'transactionRef']).doNothing())
+    .returningAll()
+    .executeTakeFirst()
+}
+
+/** Lists a transfer's transaction references, oldest first. */
+export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('funding_transfer_transactions')
+    .selectAll()
+    .where('transferId', '=', transferId)
+    .orderBy('createdAt', 'asc')
+    .execute()
+}

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

@@ -0,0 +1,89 @@
+import * as Transfer from '../../internal/funding/Transfer.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as FundingTransfers from './fundingTransfers.js'
+
+const db = TestApp.database()
+
+const owner = { environment: 'production', orgId: 'org_list' } as const
+
+let counter = 0
+function seed(input: Partial<Transfer.create.Input> = {}) {
+  // Distinct create times keep ids strictly ordered for paging assertions.
+  return Transfer.create(db, {
+    apiKeyId: 'key_test',
+    environment: 'production',
+    id: Transfer.generateId(new Date(Date.UTC(2026, 0, 1, 0, 0, counter++))),
+    orgId: owner.orgId,
+    snapshot: TestFunding.transferSnapshot(),
+    ...input,
+  })
+}
+
+describe('list', () => {
+  test('pages newest-first by id with owner isolation', async () => {
+    const first = await seed()
+    const second = await seed({ projectId: 'prj_a' })
+    const third = await seed()
+    await seed({ orgId: 'org_other' })
+    await seed({ environment: 'sandbox' })
+
+    const page = await FundingTransfers.list(db, owner, { limit: 3 })
+    expect(page.map((row) => row.id)).toEqual([third.id, second.id, first.id])
+
+    const rest = await FundingTransfers.list(db, owner, { cursor: third.id, limit: 3 })
+    expect(rest.map((row) => row.id)).toEqual([second.id, first.id])
+  })
+
+  test('narrows project-attributed owners to their project', async () => {
+    const rows = await FundingTransfers.list(db, { ...owner, projectId: 'prj_a' }, { limit: 10 })
+    expect(rows.every((row) => row.projectId === 'prj_a')).toBe(true)
+    expect(rows.length).toBeGreaterThan(0)
+  })
+
+  test('filters by status', async () => {
+    const record = await seed()
+    await Transfer.transition(db, { expectedVersion: 1, id: record.id, status: 'expired' })
+    const rows = await FundingTransfers.list(db, owner, { limit: 10, status: 'expired' })
+    expect(rows.map((row) => row.id)).toEqual([record.id])
+  })
+})
+
+describe('count', () => {
+  test('shares the list filter and stops at the cap', async () => {
+    const total = await FundingTransfers.count(db, owner, { cap: 100 })
+    expect(total).toBeGreaterThanOrEqual(3)
+    expect(await FundingTransfers.count(db, owner, { cap: 2 })).toBe(3)
+    expect(await FundingTransfers.count(db, { ...owner, orgId: 'org_none' }, { cap: 100 })).toBe(0)
+  })
+})
+
+describe('getOwned', () => {
+  test('returns owned rows and hides foreign ones', async () => {
+    const record = await seed()
+    expect((await FundingTransfers.getOwned(db, owner, record.id))?.id).toBe(record.id)
+    expect(
+      await FundingTransfers.getOwned(db, { ...owner, orgId: 'org_other' }, record.id),
+    ).toBeUndefined()
+    expect(
+      await FundingTransfers.getOwned(db, { ...owner, projectId: 'prj_a' }, record.id),
+    ).toBeUndefined()
+  })
+})
+
+describe('update', () => {
+  test('applies only against the expected version', async () => {
+    const record = await seed()
+    const options = {
+      expectedVersion: 1,
+      id: record.id,
+      snapshot: record.snapshot,
+      status: 'processing',
+      statusReason: null,
+      updatedAt: '2026-01-01T00:10:00.000Z',
+      version: 2,
+    } as const
+    expect((await FundingTransfers.update(db, options))?.version).toBe(2)
+    expect(await FundingTransfers.update(db, options)).toBeUndefined()
+  })
+})

package/src/db/tables/fundingTransfers.ts

@@ -0,0 +1,153 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_transfers` table. */
+export type Table = db_Schema.FundingTransfer
+/** A stored funding transfer. */
+export type Record = Selectable<Table>
+
+/**
+ * Ownership filter derived from the API-key principal, never from the
+ * request. A `projectId` narrows reads to that project; organization-attributed
+ * keys omit it and see every project in their organization and environment.
+ */
+export type Owner = {
+  /** Key environment. */
+  environment: Record['environment']
+  /** Owning organization id (`org_…`). */
+  orgId: string
+  /** Attributed project id, for project-attributed keys. */
+  projectId?: string | undefined
+}
+
+/** Inserts a transfer row. Callers commit the matching event in the same transaction. */
+export function insert(db: Db.Db, record: Record): Promise<Record> {
+  return db.kysely
+    .insertInto('funding_transfers')
+    .values(record)
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+/** Gets a transfer by id without ownership scoping (domain and reconciler use). */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('id', '=', id)
+    .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
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('id', '=', id)
+    .where('orgId', '=', owner.orgId)
+    .where('environment', '=', owner.environment)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  return query.executeTakeFirst()
+}
+
+/**
+ * Lists an owner's transfers newest-first. Ids embed a timestamp, so lexical
+ * key order is chronological and the cursor is the last returned id.
+ */
+export function list(db: Db.Db, owner: Owner, options: list.Options): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('orgId', '=', owner.orgId)
+    .where('environment', '=', owner.environment)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (options.status !== undefined) query = query.where('status', '=', options.status)
+  if (options.cursor !== undefined) query = query.where('id', '<', options.cursor)
+  return query.orderBy('id', 'desc').limit(options.limit).execute()
+}
+
+export declare namespace list {
+  /** Paging and filter options. */
+  type Options = {
+    /** Exclusive lower bound: the last id of the previous page. */
+    cursor?: string | undefined
+    /** Maximum rows to return (fetch one extra to detect a further page). */
+    limit: number
+    /** Restricts to one lifecycle status. */
+    status?: Record['status'] | undefined
+  }
+}
+
+/**
+ * Counts an owner's transfers through a capped subquery sharing the list
+ * filter, so the count cannot scan unboundedly. A result above `cap` means
+ * the true count was truncated.
+ */
+export async function count(db: Db.Db, owner: Owner, options: count.Options): Promise<number> {
+  const row = await db.kysely
+    .selectFrom((eb) => {
+      let query = eb
+        .selectFrom('funding_transfers')
+        .select('id')
+        .where('orgId', '=', owner.orgId)
+        .where('environment', '=', owner.environment)
+      if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+      if (options.status !== undefined) query = query.where('status', '=', options.status)
+      return query.limit(options.cap + 1).as('page')
+    })
+    .select(({ fn }) => fn.countAll<string>().as('count'))
+    .executeTakeFirstOrThrow()
+  return Number(row.count)
+}
+
+export declare namespace count {
+  /** Count options sharing the list filter. */
+  type Options = {
+    /** Row ceiling; a result above it signals a truncated count. */
+    cap: number
+    /** Restricts to one lifecycle status. */
+    status?: Record['status'] | undefined
+  }
+}
+
+/**
+ * Applies a version-guarded update; `undefined` when the row moved past
+ * `expectedVersion` (or vanished) so the caller retries against fresh state.
+ */
+export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_transfers')
+    .set({
+      snapshot: options.snapshot,
+      status: options.status,
+      statusReason: options.statusReason,
+      updatedAt: options.updatedAt,
+      version: options.version,
+    })
+    .where('id', '=', options.id)
+    .where('version', '=', options.expectedVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Guarded update fields. */
+  type Options = {
+    /** The version the update was computed against. */
+    expectedVersion: number
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Replacement public snapshot. */
+    snapshot: Record['snapshot']
+    /** New lifecycle status. */
+    status: Record['status']
+    /** Customer-safe reason, or null to clear. */
+    statusReason: Record['statusReason']
+    /** Mutation timestamp (ISO 8601). */
+    updatedAt: string
+    /** The incremented version. */
+    version: number
+  }
+}

package/src/db/tables/organizations.ts

@@ -186,6 +186,22 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('organizations').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads organizations by id for operational attribution displays.
+ *
+ * @param db - The database.
+ * @param ids - Organization ids to read.
+ * @returns Matching organization records.
+ */
+export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('organizations')
+    .selectAll()
+    .where('id', 'in', [...ids])
+    .execute()
+}
+
 /**
  * Reads an organization with current member and project counts.
  *

package/src/db/tables/projects.ts

@@ -65,6 +65,22 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('projects').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads projects by id for operational attribution displays.
+ *
+ * @param db - The database.
+ * @param ids - Project ids to read.
+ * @returns Matching project records.
+ */
+export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('projects')
+    .selectAll()
+    .where('id', 'in', [...ids])
+    .execute()
+}
+
 /**
  * Lists an organization's projects, newest first.
  *

package/src/db/tables/requestUsage.ts

@@ -43,6 +43,12 @@ export type Bucket = db_Schema.RequestUsageBucket
 /** A stored request-count meter event. */
 export type MeterEvent = db_Schema.RequestUsageMeterEvent
 
+/** Aggregate state for pending meter events in one billing environment. */
+export type PendingStatus = {
+  count: number
+  oldestAttemptedAt: string | undefined
+}
+
 /** Identifies one hourly bucket for an org in an environment. */
 export type BucketKey = {
   /** UTC hour start (ISO 8601). */
@@ -91,6 +97,23 @@ export async function listPending(db: Db.Db, environment: Environment): Promise<
   return rows.map(toMeterEvent)
 }
 
+/**
+ * Reads the number and age anchor of meter events still awaiting Stripe.
+ *
+ * @param db - The database.
+ * @param environment - The billing environment to inspect.
+ * @returns The pending-event count and oldest first attempt.
+ */
+export async function getPendingStatus(db: Db.Db, environment: Environment): Promise<PendingStatus> {
+  const row = await db.kysely
+    .selectFrom('request_usage_meter_events')
+    .select((eb) => [eb.fn.countAll().as('count'), eb.fn.min('firstAttemptedAt').as('oldest')])
+    .where('environment', '=', environment)
+    .where('state', '=', 'pending')
+    .executeTakeFirstOrThrow()
+  return { count: Number(row.count), oldestAttemptedAt: row.oldest ?? undefined }
+}
+
 /**
  * Inserts a frozen `pending` meter event, claiming a delta. Idempotent on the
  * deterministic `identifier`: a re-seal after a crash resolves to the existing

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

@@ -62,6 +62,17 @@ describe('upsert', () => {
     await db.close()
   })
 
+  test('behavior: records organization-level sponsorship without a project', async () => {
+    const db = create()
+    await db.migrate()
+    const { projectId: _, ...organization } = input
+    const record = await SponsoredTransactions.upsert(db, organization)
+
+    expect(record.orgId).toMatchInlineSnapshot(`"org_1"`)
+    expect(record.projectId).toBeNull()
+    await db.close()
+  })
+
   test('behavior: preserves an explicit fee token', async () => {
     const db = create()
     await db.migrate()

package/src/db/tables/sponsoredTransactions.ts

@@ -40,7 +40,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     id: Id.generate('stx'),
     meterReportedAt: null,
     orgId: input.orgId,
-    projectId: input.projectId,
+    projectId: input.projectId ?? null,
     signPayload: input.signPayload,
     status: 'pending',
     transaction: input.transaction,
@@ -95,8 +95,8 @@ export declare namespace upsert {
     feeToken?: string | undefined
     /** Organization id (`org_…`) the spend attributes to. */
     orgId: string
-    /** Project id (`prj_…`) the spend attributes to. */
-    projectId: string
+    /** Project id (`prj_…`) the spend attributes to; omit for organization-level spend. */
+    projectId?: string | undefined
     /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
     signPayload: string
     /** Serialized sponsored transaction, kept for observability beyond log retention. */

package/src/db/tables/users.ts

@@ -21,6 +21,22 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('users').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads users by id for operational identity displays.
+ *
+ * @param db - The database.
+ * @param ids - User ids to read.
+ * @returns Matching user records.
+ */
+export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('users')
+    .selectAll()
+    .where('id', 'in', [...ids])
+    .execute()
+}
+
 /**
  * Reads a user by wallet address (compared lowercase).
  *

package/src/db/tables/verifiedTokens.ts

@@ -1,21 +1,24 @@
-import type { Selectable } from 'kysely'
+import type { ColumnType } from 'kysely'
 import type { Hex } from 'ox'
 
 import type * as VerifiedTokens from '../../internal/VerifiedTokens.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 
-/** Columns of the `verified_tokens` table, derived from `Schema.VerifiedToken`. */
-export type Table = db_Schema.VerifiedToken
+/** A bigint chain id, read as a string from pg and written as a number. */
+type ChainId = ColumnType<string, number, number>
 
-/** Columns of the `verified_token_lists` table, derived from `Schema.VerifiedTokenList`. */
-export type ListTable = db_Schema.VerifiedTokenList
+/** Columns of the `verified_tokens` table. */
+export type Table = Omit<db_Schema.VerifiedToken, 'chainId'> & { chainId: ChainId }
+
+/** Columns of the `verified_token_lists` table. */
+export type ListTable = Omit<db_Schema.VerifiedTokenList, 'chainId'> & { chainId: ChainId }
 
 /** A stored verified-token row. */
-export type Row = Selectable<Table>
+export type Row = db_Schema.VerifiedToken
 
 /** A chain's list-level metadata. */
-export type Meta = Selectable<ListTable>
+export type Meta = db_Schema.VerifiedTokenList
 
 /**
  * Reads a chain's list metadata — the "head" the soft-refresh cache compares
@@ -25,12 +28,13 @@ export type Meta = Selectable<ListTable>
  * @param chainId - The chain id.
  * @returns The metadata, or `undefined` when the chain has no list yet.
  */
-export function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
-  return db.kysely
+export async function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
+  const row = await db.kysely
     .selectFrom('verified_token_lists')
     .selectAll()
-    .where('chainId', '=', chainId)
+    .where('chainId', '=', String(chainId))
     .executeTakeFirst()
+  return row ? { ...row, chainId: Number(row.chainId) } : undefined
 }
 
 /**
@@ -40,13 +44,14 @@ export function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
  * @param chainId - The chain id.
  * @returns The rows.
  */
-export function list(db: Db.Db, chainId: number): Promise<Row[]> {
-  return db.kysely
+export async function list(db: Db.Db, chainId: number): Promise<Row[]> {
+  const rows = await db.kysely
     .selectFrom('verified_tokens')
     .selectAll()
-    .where('chainId', '=', chainId)
+    .where('chainId', '=', String(chainId))
     .orderBy('position')
     .execute()
+  return rows.map((row) => ({ ...row, chainId: Number(row.chainId) }))
 }
 
 /**
@@ -59,7 +64,7 @@ export function list(db: Db.Db, chainId: number): Promise<Row[]> {
  * @param input - The validated list and its new version metadata.
  */
 export async function publish(db: Db.Db, chainId: number, input: publish.Input): Promise<void> {
-  await db.kysely.deleteFrom('verified_tokens').where('chainId', '=', chainId).execute()
+  await db.kysely.deleteFrom('verified_tokens').where('chainId', '=', String(chainId)).execute()
   if (input.tokens.length > 0)
     await db.kysely
       .insertInto('verified_tokens')

package/src/db/tables/webhookSubscriptions.ts

@@ -46,8 +46,13 @@ export function toSubscription(row: Record): Webhooks.Subscription {
  *
  * @param db - The database.
  * @param subscription - The subscription to insert.
+ * @param options - Initial cursor options.
  */
-export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Promise<void> {
+export async function insert(
+  db: Db.Db,
+  subscription: Webhooks.Subscription,
+  options: insert.Options = {},
+): Promise<void> {
   await db.kysely
     .insertInto('webhook_subscriptions')
     .values({
@@ -63,7 +68,7 @@ export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Pr
       lastDeliveryAt: subscription.lastDeliveryAt ?? null,
       ownerId: ownerId(subscription.owner),
       ownerType: subscription.owner.type,
-      pollerCursor: null,
+      pollerCursor: options.pollerCursor ?? null,
       secret: subscription.secret,
       status: subscription.status,
       updatedAt: subscription.updatedAt,
@@ -71,6 +76,14 @@ export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Pr
     .execute()
 }
 
+export declare namespace insert {
+  /** Options for {@link insert}. */
+  type Options = {
+    /** Initial poller cursor committed with the subscription. */
+    pollerCursor?: string | undefined
+  }
+}
+
 /**
  * Inserts a subscription when its owner remains below the configured cap.
  * An owner-scoped transaction lock serializes the count and insert.
@@ -85,7 +98,11 @@ export async function insertWithinLimit(
     await sql`select pg_advisory_xact_lock(${subscriptionLimitLockClass}, hashtext(${owner}))`.execute(tx.kysely) // prettier-ignore
     const existing = await count(tx, subscription.owner, options.now)
     if (existing >= options.maxPerOwner) return false
-    await insert(tx, subscription)
+    await insert(
+      tx,
+      subscription,
+      options.pollerCursor === undefined ? {} : { pollerCursor: options.pollerCursor },
+    )
     return true
   })
 }
@@ -97,6 +114,8 @@ export declare namespace insertWithinLimit {
     maxPerOwner: number
     /** ISO timestamp used to exclude expired rows from the count. */
     now: string
+    /** Initial poller cursor committed with the subscription. */
+    pollerCursor?: string | undefined
   }
 }
 
@@ -312,6 +331,42 @@ export async function setCursor(db: Db.Db, id: string, cursor: string): Promise<
     .execute()
 }
 
+/**
+ * Writes a poller cursor only when the stored cursor still matches the caller's
+ * observed value.
+ *
+ * @param db - The database.
+ * @param options - Subscription, expected cursor, and next cursor.
+ * @returns Whether the cursor was updated.
+ */
+export async function compareAndSetCursor(
+  db: Db.Db,
+  options: compareAndSetCursor.Options,
+): Promise<boolean> {
+  let query = db.kysely
+    .updateTable('webhook_subscriptions')
+    .set({ pollerCursor: options.cursor })
+    .where('id', '=', options.subscriptionId)
+  query =
+    options.expectedCursor === null
+      ? query.where('pollerCursor', 'is', null)
+      : query.where('pollerCursor', '=', options.expectedCursor)
+  const result = await query.executeTakeFirst()
+  return result.numUpdatedRows > 0n
+}
+
+export declare namespace compareAndSetCursor {
+  /** Options for {@link compareAndSetCursor}. */
+  type Options = {
+    /** Next keyset cursor. */
+    cursor: string
+    /** Cursor observed before scanning, or null for an uninitialized subscription. */
+    expectedCursor: string | null
+    /** Subscription whose cursor advances. */
+    subscriptionId: string
+  }
+}
+
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
  * stamps `lastDeliveryAt`.

package/src/handlers/relay.test.ts

@@ -1,3 +1,5 @@
+/** @module-tag localnet */
+
 import type { RpcRequest } from 'ox'
 import { SignatureEnvelope, TxEnvelopeTempo } from 'ox/tempo'
 import { parseUnits, type Address, type BaseError } from 'viem'