tapimo 0.13.0 → 0.15.0

package/src/db/tables/sponsoredTransactions.ts

@@ -1,9 +1,12 @@
-import type { ExpressionBuilder, Selectable } from 'kysely'
+import type { Selectable } from 'kysely'
 import { sql } from 'kysely'
+import { Value } from 'ox'
 
+import * as Fees from '../../internal/Fees.js'
 import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
+import * as SponsorshipAttributions from './sponsorshipAttributions.js'
 
 /** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
 export type Table = db_Schema.SponsoredTransaction
@@ -28,6 +31,7 @@ export const failedIntentRecoveryTtlMs = 86_400_000
 export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
   const record: Record = {
     apiKeyId: input.apiKeyId,
+    sponsorshipAttributionId: input.sponsorshipAttributionId ?? null,
     billable: input.billable,
     chainId: input.chainId,
     createdAt: new Date().toISOString(),
@@ -36,6 +40,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     feeAmount: null,
     feeMax: input.feeMax ?? null,
     feeToken: input.feeToken ?? null,
+    finalizationAttemptedAt: null,
     finalizedAt: null,
     id: Id.generate('stx'),
     meterReportedAt: null,
@@ -46,7 +51,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     transaction: input.transaction,
     transactionHash: input.transactionHash ?? null,
   }
-  return await db.kysely
+  const stored = await db.kysely
     .insertInto('sponsored_transactions')
     .values(record)
     .onConflict((oc) =>
@@ -69,11 +74,19 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
           finalizedAt: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN NULL ELSE ${eb.ref('sponsored_transactions.finalizedAt')} END`,
           status: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN 'pending' ELSE ${eb.ref('sponsored_transactions.status')} END`,
         }))
-        // A shared envelope cannot transfer billing attribution across tenants.
-        .where('sponsored_transactions.orgId', '=', input.orgId),
+        // A shared envelope cannot transfer billing attribution between owners.
+        .where('sponsored_transactions.orgId', '=', input.orgId)
+        .where(
+          sql<boolean>`sponsored_transactions.sponsorship_attribution_id IS NOT DISTINCT FROM ${record.sponsorshipAttributionId}`,
+        )
+        .where(
+          sql<boolean>`sponsored_transactions.project_id IS NOT DISTINCT FROM ${record.projectId}`,
+        ),
     )
     .returningAll()
-    .executeTakeFirstOrThrow()
+    .executeTakeFirst()
+  if (!stored) throw new AttributionConflictError()
+  return stored
 }
 
 export declare namespace upsert {
@@ -81,6 +94,8 @@ export declare namespace upsert {
   type Input = {
     /** API key id (`key_…`) that requested sponsorship. */
     apiKeyId: string
+    /** Canonical sponsorship attribution id snapshotted at sponsorship time. */
+    sponsorshipAttributionId?: string | undefined
     /** Whether the sponsorship accrues billable spend; false for sandbox. */
     billable: boolean
     /** Chain the sponsored transaction targets. */
@@ -121,19 +136,44 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
     .executeTakeFirst()
 }
 
-/**
- * Lists pending sponsorships, oldest first, for the finalization job.
- *
- * @param db - The database.
- * @param options - Paging options.
- * @returns The pending records.
- */
+/** Lists sponsored transactions newest-first for administrative inspection. */
+export function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  let query = db.kysely.selectFrom('sponsored_transactions').selectAll()
+  const cursor = options.cursor
+  if (cursor !== undefined)
+    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(options.limit).execute()
+}
+
+export declare namespace list {
+  /** Pagination options for sponsored transactions. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: Cursor | undefined
+    /** Maximum rows returned. */
+    limit: number
+  }
+
+  /** Cursor fields for the last transaction on the previous page. */
+  type Cursor = {
+    /** Sponsorship creation time. */
+    createdAt: string
+    /** Sponsored transaction id, used as a deterministic tie-breaker. */
+    id: string
+  }
+}
+
+/** Lists pending sponsorships, oldest first. */
 export function listPending(db: Db.Db, options: listPending.Options = {}): Promise<Record[]> {
   let query = db.kysely
     .selectFrom('sponsored_transactions')
     .selectAll()
     .where('status', '=', 'pending')
-    // `id` breaks same-millisecond `createdAt` ties for a deterministic scan.
     .orderBy('createdAt', 'asc')
     .orderBy('id', 'asc')
   if (options.limit !== undefined) query = query.limit(options.limit)
@@ -148,22 +188,57 @@ export declare namespace listPending {
   }
 }
 
+/** Claims the least-recently attempted pending sponsorships for one finalization pass. */
+export function claimPending(db: Db.Db, options: claimPending.Options): Promise<Record[]> {
+  return db.transaction(async (db) => {
+    const rows = await db.kysely
+      .selectFrom('sponsored_transactions')
+      .selectAll()
+      .where('status', '=', 'pending')
+      .orderBy(sql`finalization_attempted_at nulls first`)
+      .orderBy('createdAt', 'asc')
+      .orderBy('id', 'asc')
+      .limit(options.limit)
+      .forUpdate()
+      .skipLocked()
+      .execute()
+    if (rows.length === 0) return []
+    await db.kysely
+      .updateTable('sponsored_transactions')
+      .set({ finalizationAttemptedAt: options.attemptedAt })
+      .where(
+        'id',
+        'in',
+        rows.map((row) => row.id),
+      )
+      .execute()
+    return rows.map((row) => ({ ...row, finalizationAttemptedAt: options.attemptedAt }))
+  })
+}
+
+export declare namespace claimPending {
+  /** Claim timestamp and batch bound. */
+  type Options = {
+    /** Timestamp recorded before receipt lookups begin. */
+    attemptedAt: string
+    /** Maximum rows claimed by this pass. */
+    limit: number
+  }
+}
+
 /**
- * Lists hash-less fill intents, oldest first, for the reconciliation pass.
- * Failed intents are included only when the caller supplies a recovery floor.
+ * Lists active hash-less fill intents, oldest first, for reconciliation.
  *
  * @param db - The database.
  * @param options - Paging options.
- * @returns The pending intents.
+ * @returns The fill intents.
  */
 export function listIntents(db: Db.Db, options: listIntents.Options = {}): Promise<Record[]> {
   let query = db.kysely
     .selectFrom('sponsored_transactions')
     .selectAll()
-    .where(intentStatus(options.failedSince))
+    .where('status', '=', 'pending')
     .where('transactionHash', 'is', null)
-    // `pending` sorts after `failed`; descending keeps active intents first.
-    .orderBy('status', 'desc')
     .orderBy('createdAt', 'asc')
     .orderBy('id', 'asc')
   if (options.limit !== undefined) query = query.limit(options.limit)
@@ -172,9 +247,68 @@ export function listIntents(db: Db.Db, options: listIntents.Options = {}): Promi
 
 export declare namespace listIntents {
   /** Options for {@link listIntents}. */
-  type Options = listPending.Options & {
-    /** Include failed intents whose terminal timestamp is at or after this ISO timestamp. */
-    failedSince?: string | undefined
+  type Options = listPending.Options
+}
+
+/** Lists the oldest recoverable failed-intent timestamp for each chain. */
+export function listRecoveryWindows(
+  db: Db.Db,
+  options: listRecoveryWindows.Options,
+): Promise<listRecoveryWindows.Window[]> {
+  return db.kysely
+    .selectFrom('sponsored_transactions')
+    .select('chainId')
+    .select((eb) => eb.fn.min<string>('createdAt').as('createdAt'))
+    .where('finalizedAt', '>=', options.failedSince)
+    .where('status', '=', 'failed')
+    .where('transactionHash', 'is', null)
+    .groupBy('chainId')
+    .execute()
+}
+
+export declare namespace listRecoveryWindows {
+  /** Failed-intent recovery window options. */
+  type Options = {
+    /** Earliest terminal timestamp eligible for recovery. */
+    failedSince: string
+  }
+
+  /** One chain's failed-intent recovery window. */
+  type Window = {
+    /** Chain containing recoverable failed intents. */
+    chainId: number
+    /** Oldest eligible intent creation timestamp. */
+    createdAt: string
+  }
+}
+
+/** Lists pending and recoverable failed intents matching candidate sign payloads. */
+export function listRecoverableIntents(
+  db: Db.Db,
+  options: listRecoverableIntents.Options,
+): Promise<Record[]> {
+  if (options.signPayloads.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where('signPayload', 'in', [...options.signPayloads])
+    .where((eb) =>
+      eb.or([
+        eb('status', '=', 'pending'),
+        eb.and([eb('finalizedAt', '>=', options.failedSince), eb('status', '=', 'failed')]),
+      ]),
+    )
+    .where('transactionHash', 'is', null)
+    .execute()
+}
+
+export declare namespace listRecoverableIntents {
+  /** Reconciliation candidate lookup options. */
+  type Options = {
+    /** Earliest terminal timestamp eligible for recovery. */
+    failedSince: string
+    /** Candidate fee-payer sign payloads. */
+    signPayloads: readonly string[]
   }
 }
 
@@ -208,8 +342,17 @@ export async function assignTransactionHash(
         (record.finalizedAt === null || record.finalizedAt < failedSince)
       )
         return
-      if (record.status === 'failed' && record.billable && limit)
-        await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${record.orgId}))`.execute(tx.kysely) // prettier-ignore
+      const limited =
+        limit !== undefined &&
+        (limit.billable === undefined ? record.billable : record.billable === limit.billable)
+      if (record.status === 'failed' && limited) {
+        const scope = limit.sponsorshipAttributionId
+          ? `${record.orgId}:${limit.sponsorshipAttributionId}`
+          : limit.projectId
+            ? `${record.orgId}:${limit.projectId}`
+            : record.orgId
+        await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
+      }
       let query = tx.kysely
         .updateTable('sponsored_transactions')
         .set({
@@ -232,10 +375,15 @@ export async function assignTransactionHash(
         )
       const updated = await query.executeTakeFirst()
       if (updated.numUpdatedRows === 0n) return
-      if (record.status === 'failed' && record.billable && limit) {
+      if (record.status === 'failed' && limited) {
         const committed = await spend(tx, {
+          ...(limit.billable === undefined ? {} : { billable: limit.billable }),
+          ...(limit.sponsorshipAttributionId === undefined
+            ? {}
+            : { sponsorshipAttributionId: limit.sponsorshipAttributionId }),
           chainIds: limit.chainIds,
           orgId: record.orgId,
+          ...(limit.projectId === undefined ? {} : { projectId: limit.projectId }),
           since: limit.since,
         })
         if (committed > limit.max) throw new PeriodSpendLimitError()
@@ -319,12 +467,24 @@ export async function reserve(
   return db.transaction(async (tx) => {
     // `hashtext` maps the org id into the advisory-lock keyspace; the class
     // namespaces it against other advisory-lock users. Released at tx end.
-    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+    const scope = limit.sponsorshipAttributionId
+      ? `${input.orgId}:${limit.sponsorshipAttributionId}`
+      : limit.projectId
+        ? `${input.orgId}:${limit.projectId}`
+        : input.orgId
+    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
     const record = await upsert(tx, input)
-    if (record.billable) {
+    const limited =
+      limit.billable === undefined ? record.billable : record.billable === limit.billable
+    if (limited) {
       const committed = await spend(tx, {
+        ...(limit.billable === undefined ? {} : { billable: limit.billable }),
+        ...(limit.sponsorshipAttributionId === undefined
+          ? {}
+          : { sponsorshipAttributionId: limit.sponsorshipAttributionId }),
         chainIds: limit.chainIds,
         orgId: input.orgId,
+        ...(limit.projectId === undefined ? {} : { projectId: limit.projectId }),
         since: limit.since,
       })
       if (committed > limit.max) throw new PeriodSpendLimitError()
@@ -339,15 +499,179 @@ const billingLockClass = 1112294220
 export declare namespace reserve {
   /** The period spend limit enforced by {@link reserve}. */
   type Limit = {
+    /** Canonical attribution scope for independent limits. */
+    sponsorshipAttributionId?: string | undefined
+    /** Billing snapshot whose rows consume this limit; omit for customer-billable spend. */
+    billable?: boolean | undefined
     /** Chains whose spend counts (mainnet chain ids). */
     chainIds: readonly number[]
     /** Limit in fee-token base units. */
     max: bigint
+    /** Project scope for independent limits; omit for the organization-wide budget. */
+    projectId?: string | undefined
     /** Window start (ISO 8601). */
     since: string
   }
 }
 
+/**
+ * Applies the current promotion policy and records the sponsorship atomically.
+ * Exhausted promotions retain their window and fall back to customer billing.
+ */
+export function reservePromotion(
+  db: Db.Db,
+  input: reservePromotion.Input,
+  options: reservePromotion.Options,
+): Promise<reservePromotion.Result> {
+  return db.transaction(async (tx) => {
+    const scope = `${input.orgId}:${input.sponsorshipAttributionId}`
+    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
+    const existing = await tx.kysely
+      .selectFrom('sponsored_transactions')
+      .selectAll()
+      .where('signPayload', '=', input.signPayload)
+      .forUpdate()
+      .executeTakeFirst()
+    if (existing) {
+      if (
+        existing.orgId !== input.orgId ||
+        (existing.sponsorshipAttributionId !== null &&
+          existing.sponsorshipAttributionId !== input.sponsorshipAttributionId) ||
+        existing.projectId !== (input.projectId ?? null)
+      )
+        throw new AttributionConflictError()
+      // A pre-promotion row keeps its null attribution and billable snapshot
+      // when policy changes before an idempotent retry.
+      const stored = await upsert(
+        tx,
+        existing.sponsorshipAttributionId === null
+          ? { ...input, billable: existing.billable, sponsorshipAttributionId: undefined }
+          : input,
+      )
+      if (stored.billable && options.billingLimit) {
+        await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+        const billed = await spend(tx, {
+          chainIds: options.billingLimit.chainIds,
+          orgId: input.orgId,
+          since: options.billingLimit.since,
+        })
+        if (billed > options.billingLimit.max) throw new PeriodSpendLimitError()
+      }
+      if (!stored.billable && stored.sponsorshipAttributionId !== null) {
+        const attribution = await SponsorshipAttributions.get(tx, {
+          id: input.sponsorshipAttributionId,
+          orgId: input.orgId,
+        })
+        if (!attribution?.startsAt) throw new PromotionActivationError()
+        if (attribution.spendLimit !== null) {
+          const committed = await spend(tx, {
+            sponsorshipAttributionId: input.sponsorshipAttributionId,
+            billable: false,
+            chainIds: options.chainIds,
+            orgId: input.orgId,
+            since: attribution.startsAt,
+          })
+          if (committed > BigInt(attribution.spendLimit)) throw new PeriodSpendLimitError()
+        }
+      }
+      return { record: stored, status: stored.billable ? 'billed' : 'subsidized' }
+    }
+
+    const organization = await tx.kysely
+      .selectFrom('organizations')
+      .select(['sponsorshipSubsidyDurationDays', 'sponsorshipSubsidyProjectSpendLimit'])
+      .where('id', '=', input.orgId)
+      .forShare()
+      .executeTakeFirst()
+    if (!organization || organization.sponsorshipSubsidyDurationDays === null)
+      return { status: 'ineligible' }
+
+    const current = await SponsorshipAttributions.get(tx, {
+      id: input.sponsorshipAttributionId,
+      orgId: input.orgId,
+    })
+    if (current?.endsAt && Date.parse(options.at) >= Date.parse(current.endsAt))
+      return { status: 'ineligible' }
+
+    const endsAt = new Date(
+      Date.parse(options.at) + organization.sponsorshipSubsidyDurationDays * 86_400_000,
+    ).toISOString()
+    const attribution = await SponsorshipAttributions.activate(tx, {
+      id: input.sponsorshipAttributionId,
+      endsAt,
+      orgId: input.orgId,
+      spendLimit:
+        organization.sponsorshipSubsidyProjectSpendLimit === null
+          ? null
+          : Value.from(
+              organization.sponsorshipSubsidyProjectSpendLimit,
+              Fees.tokenDecimals,
+            ).toString(),
+      startsAt: options.at,
+    })
+    let record = await upsert(tx, input)
+    if (!attribution.startsAt) throw new PromotionActivationError()
+    if (attribution.spendLimit !== null) {
+      const committed = await spend(tx, {
+        sponsorshipAttributionId: input.sponsorshipAttributionId,
+        billable: false,
+        chainIds: options.chainIds,
+        orgId: input.orgId,
+        since: attribution.startsAt,
+      })
+      if (committed > BigInt(attribution.spendLimit)) {
+        record = await tx.kysely
+          .updateTable('sponsored_transactions')
+          .set({ billable: true })
+          .where('id', '=', record.id)
+          .returningAll()
+          .executeTakeFirstOrThrow()
+        if (options.billingLimit) {
+          await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+          const billed = await spend(tx, {
+            chainIds: options.billingLimit.chainIds,
+            orgId: input.orgId,
+            since: options.billingLimit.since,
+          })
+          if (billed > options.billingLimit.max) throw new PeriodSpendLimitError()
+        }
+      }
+    }
+    return { record, status: record.billable ? 'billed' : 'subsidized' }
+  })
+}
+
+export declare namespace reservePromotion {
+  /** Sponsored transaction with its canonical attribution snapshot. */
+  type Input = upsert.Input & {
+    /** Canonical sponsorship attribution id. */
+    sponsorshipAttributionId: string
+  }
+
+  /** Attribution promotion window and cap. */
+  type Options = {
+    /** Timestamp of the recorded sponsorship that may activate the window. */
+    at: string
+    /** Customer billing limit used when the attribution promotion is exhausted. */
+    billingLimit?: reserve.Limit | undefined
+    /** Mainnet chains whose promotional spend counts. */
+    chainIds: readonly number[]
+  }
+
+  /** Promotion reservation outcome. */
+  type Result =
+    | {
+        /** Stored sponsorship. */
+        record: Record
+        /** Whether Tempo or the customer pays for the stored sponsorship. */
+        status: 'billed' | 'subsidized'
+      }
+    | {
+        /** The current organization or attribution policy does not grant a promotion. */
+        status: 'ineligible'
+      }
+}
+
 /**
  * Billable spend committed since a cutoff, in fee-token base units: finalized
  * rows at their actual fee plus pending rows at their signed fee cap, so
@@ -358,8 +682,16 @@ export declare namespace reserve {
  * @returns The committed spend in base units.
  */
 export async function spend(db: Db.Db, options: spend.Options): Promise<bigint> {
-  const { chainIds, environment = 'production', orgId, since } = options
-  const query = db.kysely
+  const {
+    sponsorshipAttributionId,
+    billable,
+    chainIds,
+    environment = 'production',
+    orgId,
+    projectId,
+    since,
+  } = options
+  let query = db.kysely
     .selectFrom('sponsored_transactions')
     .select([
       sql<string>`coalesce(sum(case when status = 'finalized' then fee_amount::numeric else 0 end), 0)`.as('finalized'), // prettier-ignore
@@ -372,22 +704,35 @@ export async function spend(db: Db.Db, options: spend.Options): Promise<bigint>
     .where('status', 'in', ['finalized', 'pending'])
     .where('chainId', 'in', [...chainIds])
     .where('createdAt', '>=', since)
+  if (billable !== undefined) query = query.where('billable', '=', billable)
+  if (sponsorshipAttributionId !== undefined)
+    query = query.where('sponsorshipAttributionId', '=', sponsorshipAttributionId)
+  if (projectId !== undefined) query = query.where('projectId', '=', projectId)
   // Production mirrors the sponsorship gate — only billable rows count. Sandbox
   // rows are non-billable by construction, so the figure is display-only.
-  const row = await (environment === 'production' ? query.where('billable', '=', true) : query) //
-    .executeTakeFirstOrThrow()
+  const row = await (
+    environment === 'production' && billable === undefined
+      ? query.where('billable', '=', true)
+      : query
+  ).executeTakeFirstOrThrow()
   return BigInt(row.finalized) + BigInt(row.pending)
 }
 
 export declare namespace spend {
   /** Options for {@link spend}. */
   type Options = {
+    /** Canonical sponsorship attribution id whose spend counts. */
+    sponsorshipAttributionId?: string | undefined
+    /** Billing snapshot to count; omit for the existing production-billable behavior. */
+    billable?: boolean | undefined
     /** Chains whose spend counts (mainnet chain ids). */
     chainIds: readonly number[]
     /** Environment whose spend counts; production mirrors the billing gate, sandbox is display-only. Defaults to `production`. */
     environment?: Table['environment'] | undefined
     /** Organization id (`org_…`) the spend attributes to. */
     orgId: string
+    /** Project whose spend counts; omit for organization-wide spend. */
+    projectId?: string | undefined
     /** Window start (ISO 8601); rows created earlier are out of scope. */
     since: string
   }
@@ -516,18 +861,17 @@ export async function markReported(db: Db.Db, id: string, at: string): Promise<v
     .execute()
 }
 
-/** Intent status predicate; failed rows are recovery candidates only briefly. */
-function intentStatus(failedSince: string | undefined) {
-  return (eb: ExpressionBuilder<Db.Database, 'sponsored_transactions'>) => {
-    if (failedSince === undefined) return eb('status', '=', 'pending')
-    return eb.or([
-      eb('status', '=', 'pending'),
-      eb.and([eb('status', '=', 'failed'), eb('finalizedAt', '>=', failedSince)]),
-    ])
-  }
-}
-
 /** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
 export class PeriodSpendLimitError extends Error {
   override name = 'SponsoredTransactions.PeriodSpendLimitError'
 }
+
+/** Thrown when a promotional window cannot be activated consistently. */
+export class PromotionActivationError extends Error {
+  override name = 'SponsoredTransactions.PromotionActivationError'
+}
+
+/** Thrown when one signed envelope is presented with conflicting attribution. */
+export class AttributionConflictError extends Error {
+  override name = 'SponsoredTransactions.AttributionConflictError'
+}