tapimo 0.15.1 → 0.18.0

package/src/apps/data/routes/transactions.ts

@@ -13,6 +13,7 @@ import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Store from '../../../internal/Store.js'
 import * as Tidx from '../../../internal/Tidx.js'
+import * as Timeout from '../../../internal/Timeout.js'
 import * as Timing from '../../../internal/Timing.js'
 import * as Ttl from '../../../internal/Ttl.js'
 import * as Value from '../../../internal/Value.js'
@@ -1072,8 +1073,8 @@ export function getTransactions(c: Context<App.Environment>, options: getTransac
 
   return Timing.time(c, 'transactions', () =>
     Store.memoize(
-      async () => {
-        const page = await scanTransactions({ tidx }, options)
+      async (signal) => {
+        const page = await scanTransactions({ signal, tidx }, options)
         return {
           data: page.items.map((item) => item.data),
           nextCursor: page.nextCursor,
@@ -1115,7 +1116,7 @@ export async function scanTransactions(
     toBlock,
     toTimestamp,
   } = options
-  const { tidx } = deps
+  const { signal: flight, tidx } = deps
   const sortDirection = order === 'asc' ? 'ASC' : 'DESC'
   // Keyset pagination: anchor the page below the previous row's `(block, idx)`
   // position instead of a numeric offset, so rows arriving at the head can't
@@ -1177,35 +1178,43 @@ export async function scanTransactions(
     feePayer !== undefined ||
     feeToken !== undefined
   const fetchRows = async (where: readonly string[]) => {
+    // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
+    // to `string`.
+    const query = (block: string) =>
+      `
+        SELECT ${transactionColumns}
+        FROM txs
+        ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+        ORDER BY ${block} ${sortDirection}, idx ${sortDirection}
+        LIMIT ${queryLimit}${skip}
+      ` as string
+    if (!filtered)
+      return await tidx.fetch({
+        chainId,
+        query: query('block_num'),
+        ...(flight ? { signal: flight } : {}),
+      })
+    // TIDX reports statement kills as 408 timeouts, which the client retries until
+    // the deadline; half the deadline bounds the walk so the fenced retry still runs.
+    const timeout = AbortSignal.timeout(Timeout.duration / 2)
     try {
       return await tidx.fetch({
         chainId,
-        // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
-        // to `string`.
-        query: `
-          SELECT ${transactionColumns}
-          FROM txs
-          ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
-          ORDER BY block_num ${sortDirection}, idx ${sortDirection}
-          LIMIT ${queryLimit}${skip}
-        ` as string,
+        query: query('block_num'),
+        signal: flight ? AbortSignal.any([flight, timeout]) : timeout,
       })
     } catch (error) {
+      // An expired flight means the memoized caller already gave up.
+      if (flight?.aborted) throw error
       // Planner mis-selectivity turns these top-N scans into a block-ordered
       // walk that times out when matches sit far from the scan boundary;
       // `block_num + 0` blocks that walk, forcing the filter index plus a sort.
-      if (!filtered || !Tidx.isDeterministicError(error)) throw error
+      if (!timeout.aborted && !Tidx.isQueryTimeout(error) && !Tidx.isDeterministicError(error))
+        throw error
       return await tidx.fetch({
         chainId,
-        // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
-        // to `string`.
-        query: `
-          SELECT ${transactionColumns}
-          FROM txs
-          ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
-          ORDER BY block_num + 0 ${sortDirection}, idx ${sortDirection}
-          LIMIT ${queryLimit}${skip}
-        ` as string,
+        query: query('block_num + 0'),
+        ...(flight ? { signal: flight } : {}),
       })
     }
   }
@@ -1395,6 +1404,8 @@ export declare namespace countTransactions {
 export declare namespace scanTransactions {
   /** Dependencies for {@link scanTransactions}. */
   type Deps = {
+    /** Optional deadline signal bounding every TIDX read in the scan. */
+    signal?: AbortSignal | undefined
     /** TIDX query client for the target chain. */
     tidx: Tidx.Client
   }

package/src/apps/data/routes/webhooks.test.ts

@@ -307,10 +307,19 @@ describe('CRUD lifecycle', () => {
       },
       as(webhookWriter),
     )
-    const body = (await response.json()) as { error?: { code?: string } }
+    expect(response.status).toMatchInlineSnapshot(`403`)
+    if (response.status !== 403) throw new Error('Expected a forbidden response')
+    const { requestId, ...body } = await response.json()
 
-    expect(response.status).toBe(403)
-    expect(body.error?.code).toBe('api_key_forbidden')
+    expect(requestId).toBeDefined()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "api_key_forbidden",
+          "message": "API key is missing required permissions: routes:read. Use an API key with these scopes.",
+        },
+      }
+    `)
   })
 
   test('captures route transfer ownership scope without reading the RPC head', async () => {

package/src/apps/data/routes/webhooks.ts

@@ -1670,7 +1670,8 @@ export function webhooks(options: webhooks.Options = {}) {
             )
               return Response.error(c, {
                 code: 'api_key_forbidden',
-                message: 'API key missing required scope',
+                message:
+                  'API key is missing required permissions: routes:read. Use an API key with these scopes.',
                 status: 403,
               })
           }

package/src/apps/management/App.ts

@@ -7,6 +7,7 @@ import * as Metadata from '../metadata.js'
 
 import { apiKeys } from './routes/api-keys.js'
 import { billing } from './routes/billing.js'
+import { cli } from './routes/cli.js'
 import { faucet } from './routes/faucet.js'
 import { invitations } from './routes/invitations.js'
 import { inviteLinks } from './routes/invite-links.js'
@@ -75,6 +76,7 @@ export function management(options: management.Options = {}) {
     })
     .route('/', apiKeys({ enabled: options.apiKeys !== false }))
     .route('/', billing())
+    .route('/', cli({ consoleUrl: options.consoleUrl }))
     .route('/', faucet())
     .route('/', invitations())
     .route('/', inviteLinks())
@@ -96,6 +98,8 @@ export declare namespace management {
     apiKeys?: boolean | undefined
     /** Stripe billing capability; omit to disable billing routes (501) and keep production sponsorship closed. */
     billing?: Billing | undefined
+    /** Console origin hosting the CLI sign-in approval page. @default 'https://console.tempo.xyz' */
+    consoleUrl?: string | undefined
     /** Legacy group-level transactional email sender. Prefer `App.create({ email })`. */
     email?: Email.Sender | undefined
     /** Webhook capability shared with the data group and host poller; omit or pass false to disable management. */

package/src/apps/management/Billing.test.ts

@@ -1,5 +1,5 @@
 import { nanoid } from 'nanoid'
-import type Stripe from 'stripe'
+import Stripe from 'stripe'
 
 import * as Runtime from '../../../test/runtime.js'
 import * as ApiKeys from '../../ApiKeys.js'
@@ -33,16 +33,23 @@ const input = {
 /** Inserts and finalizes one billable row; `seed` derives a unique sign payload. */
 async function finalized(
   db: Db.Db,
-  options: { feeAmount: string; orgId?: string; seed: string },
+  options: {
+    chainId?: number
+    feeAmount: string
+    finalizedAt?: string
+    orgId?: string
+    seed: string
+  },
 ): Promise<SponsoredTransactions.Record> {
   const row = await SponsoredTransactions.upsert(db, {
     ...input,
+    ...(options.chainId === undefined ? {} : { chainId: options.chainId }),
     ...(options.orgId ? { orgId: options.orgId } : {}),
     signPayload: `0x${options.seed.repeat(32)}`,
   })
   await SponsoredTransactions.finalize(db, row.id, {
     feeAmount: options.feeAmount,
-    finalizedAt: new Date().toISOString(),
+    finalizedAt: options.finalizedAt ?? new Date().toISOString(),
   })
   return row
 }
@@ -178,6 +185,7 @@ type StubSubscription = {
  * item/subscription creation are captured for assertions.
  */
 function stubStripe(options: {
+  createdAt?: number | undefined
   meterEvent?: ((params: { identifier: string }) => void) | undefined
   subscriptions?: readonly StubSubscription[] | undefined
   subscriptionsList?: (() => Promise<void>) | undefined
@@ -239,7 +247,7 @@ function stubStripe(options: {
     subscriptionItems: {
       create: async (params: { price: string; subscription: string }) => {
         itemsCreated.push(params)
-        return { created: Math.floor(Date.now() / 1_000) }
+        return { created: options.createdAt ?? Math.floor(Date.now() / 1_000) }
       },
     },
     subscriptions: {
@@ -248,7 +256,7 @@ function stubStripe(options: {
         return {
           items: {
             data: params.items.map(({ price }) => ({
-              created: Math.floor(Date.now() / 1_000),
+              created: options.createdAt ?? Math.floor(Date.now() / 1_000),
               price: { id: price },
             })),
           },
@@ -315,6 +323,89 @@ describe('status', () => {
 })
 
 describe('createReporter', () => {
+  test('retries an explicitly rejected Stripe event after its configuration is corrected', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const row = await finalized(db, { feeAmount: '100000', seed: '42' })
+    let reject = true
+    const { meterEvents, stripe } = stubStripe({
+      meterEvent: () => {
+        if (reject)
+          throw new Stripe.errors.StripeInvalidRequestError({
+            message: 'Meter configuration is invalid.',
+            statusCode: 400,
+            type: 'invalid_request_error',
+          })
+      },
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    const reporter = Billing.createReporter({ db, stripe })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect((await SponsoredTransactions.get(db, row.id))?.meterEventFirstAttemptedAt).toBeNull()
+
+    reject = false
+    expect(await reporter.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(meterEvents.map(({ identifier }) => identifier)).toStrictEqual([row.id])
+    await db.close()
+  })
+
+  test('stops an uncertain Stripe resend after its identifier window', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const row = await finalized(db, { feeAmount: '100000', seed: '41' })
+    await SponsoredTransactions.beginMeterEvent(
+      db,
+      row.id,
+      new Date(Date.now() - 24 * 60 * 60 * 1_000).toISOString(),
+    )
+
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
+      failed: 1,
+      reported: 0,
+      skipped: 0,
+    })
+    expect(meterEvents).toHaveLength(0)
+    expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).toBeNull()
+    await db.close()
+  })
+
+  test('rotates unavailable sponsorships behind healthy rows', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const unavailable = await finalized(db, {
+      feeAmount: '100000',
+      finalizedAt: '2026-01-01T00:00:00.000Z',
+      orgId: 'org_missing',
+      seed: '39',
+    })
+    const healthy = await finalized(db, {
+      chainId: 421700099,
+      feeAmount: '250000',
+      finalizedAt: '2026-01-02T00:00:00.000Z',
+      seed: '40',
+    })
+
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    const reporter = Billing.createReporter({ batchSize: 1, db, stripe })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(await reporter.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(meterEvents.map(({ identifier }) => identifier)).toStrictEqual([healthy.id])
+    expect(
+      (await SponsoredTransactions.get(db, unavailable.id))?.meterEventFirstAttemptedAt,
+    ).toBeNull()
+    expect((await SponsoredTransactions.get(db, unavailable.id))?.meterReportedAt).toBeNull()
+    await db.close()
+  })
+
   test('behavior: a poisoned row never stalls the queue', async () => {
     const db = create()
     await db.migrate()
@@ -387,6 +478,7 @@ describe('createReporter', () => {
       skipped: 0,
     })
     expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).not.toBeNull()
+    expect((await SponsoredTransactions.get(db, row.id))?.meterEventFirstAttemptedAt).not.toBeNull()
     expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
       failed: 0,
       reported: 0,
@@ -395,24 +487,35 @@ describe('createReporter', () => {
     await db.close()
   })
 
-  test('behavior: canceled customers skip without meter events', async () => {
-    const db = create()
-    await db.migrate()
-    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
-    await StripeCustomers.setStatus(db, 'org_1', 'canceled')
-    const row = await finalized(db, { feeAmount: '100000', seed: '03' })
-
-    const { meterEvents, stripe } = stubStripe({ subscriptions: [{ status: 'active' }] })
-    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
-      failed: 0,
-      reported: 0,
-      skipped: 1,
-    })
-    expect(meterEvents).toHaveLength(0)
-    // Skipped rows still mark: nobody remains to invoice, ever.
-    expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).not.toBeNull()
-    await db.close()
-  })
+  test.each(['canceled', 'missing'] as const)(
+    'behavior: retains sponsorship liability for %s customers',
+    async (status) => {
+      const db = create()
+      await db.migrate()
+      if (status === 'canceled') {
+        await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+        await StripeCustomers.setStatus(db, 'org_1', 'canceled')
+      }
+      const row = await finalized(db, { feeAmount: '100000', seed: '03' })
+
+      // No provider call is needed until a billing identity is available.
+      const stripe = new Stripe('sk_test_unavailable_customer', { maxNetworkRetries: 0 })
+      const reporter = Billing.createReporter({ db, stripe })
+      expect(await reporter.tick()).toStrictEqual({
+        failed: 1,
+        reported: 0,
+        skipped: 0,
+      })
+      expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).toBeNull()
+      expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+      expect(
+        (await SponsoredTransactions.listUnreported(db, { chainIds: [Viem.chainId.mainnet] })).map(
+          ({ id }) => id,
+        ),
+      ).toEqual([row.id])
+      await db.close()
+    },
+  )
 
   test('behavior: ensures the metered subscription once and stamps its backlog at now', async () => {
     const db = create()
@@ -779,7 +882,8 @@ describe('createRequestUsageReporter', () => {
 
     // Tick 1: fresh customer, initial seal of 5. The just-created item bills at
     // now (no backdate).
-    const first = stubStripe({ subscriptions: [] })
+    const createdAt = Math.floor(now() / 1_000)
+    const first = stubStripe({ createdAt, subscriptions: [] })
     const reporter1 = Billing.createRequestUsageReporter({
       db,
       now,
@@ -788,9 +892,9 @@ describe('createRequestUsageReporter', () => {
     })
     expect(await reporter1.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
     expect(first.meterEvents).toEqual([
-      { event_name: 'api_request_count', identifier: expect.any(String), payload: expect.objectContaining({ value: '5' }) }, // prettier-ignore
+      { event_name: 'api_request_count', identifier: expect.any(String), payload: expect.objectContaining({ value: '5' }), timestamp: createdAt }, // prettier-ignore
     ])
-    expect(first.meterEvents[0]!.timestamp).toBeUndefined()
+    expect(first.meterEvents[0]!.timestamp).toBe(createdAt)
     expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(5) // prettier-ignore
 
     // Tick 2: count grows to 8; only the delta of 3 bills, backdated (item exists).
@@ -824,6 +928,30 @@ describe('createRequestUsageReporter', () => {
     await db.close()
   })
 
+  test('behavior: clamps initial backlog to an item provisioned by another reporter', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+    const createdAt = Math.floor(Date.parse('2026-01-01T18:00:00.000Z') / 1_000)
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [
+        { createdAt, items: ['feePayerSpend', 'routeSubsidy', 'apiRequests'], status: 'active' },
+      ],
+    })
+
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [{ bucketStart, count: 5, orgId: 'org_1' }],
+        stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(meterEvents[0]?.timestamp).toBe(createdAt)
+    await db.close()
+  })
+
   test('behavior: overlapping ticks cannot claim the same observed watermark twice', async () => {
     const db = create()
     await db.migrate()
@@ -941,6 +1069,7 @@ describe('createRequestUsageReporter', () => {
       bucketStart,
       deltaCount: 6,
       environment: 'production',
+      eventTimestamp: bucketStart,
       identifier: 'rq_production_deadbeef0001_0_0',
       orgId: 'org_1',
       sequence: 0,
@@ -969,11 +1098,12 @@ describe('createRequestUsageReporter', () => {
     await db.migrate()
     await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
     await StripeCustomers.setStatus(db, 'org_1', 'active')
+    const createdAt = Math.floor(Date.parse('2026-01-01T18:00:00.000Z') / 1_000)
     const { stripe } = stubStripe({
       meterEvent() {
         throw new Error('Stripe unavailable')
       },
-      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+      subscriptions: [{ createdAt, items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
     })
     const reporter = Billing.createRequestUsageReporter({
       db,
@@ -990,6 +1120,102 @@ describe('createRequestUsageReporter', () => {
         oldestPendingAgeSeconds: expect.any(Number),
       },
     ])
+
+    const pending = (await RequestUsage.listPending(db, 'production'))[0]!
+    await db.kysely
+      .updateTable('request_usage_meter_events')
+      .set({ eventTimestamp: pending.firstAttemptedAt })
+      .where('identifier', '=', pending.identifier)
+      .execute()
+    const retryAt = new Date(pending.firstAttemptedAt).getTime() + 23 * 60 * 60 * 1_000
+    const failedRetry = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now: () => retryAt,
+        readCounts: async () => [],
+        stripe: failedRetry.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(failedRetry.meterEvents).toHaveLength(0)
+    expect(await RequestUsage.listPending(db, 'production')).toHaveLength(1)
+    expect(await reporter.pending()).toMatchObject([{ count: 1, environment: 'production' }])
+
+    const retry = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now: () => retryAt + 24 * 60 * 60 * 1_000,
+        readCounts: async () => [],
+        stripe: retry.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(retry.meterEvents).toHaveLength(0)
+    await db.close()
+  })
+
+  test('behavior: stops retrying a legacy event after identifier uniqueness expires', async () => {
+    const db = create()
+    await db.migrate()
+    await RequestUsage.insertPending(db, {
+      bucketStart,
+      deltaCount: 6,
+      environment: 'production',
+      eventTimestamp: new Date().toISOString(),
+      identifier: 'rq_production_deadbeef0003_0_0',
+      orgId: 'org_1',
+      sequence: 0,
+      stripeCustomerId: 'cus_1',
+    })
+    await db.kysely
+      .updateTable('request_usage_meter_events')
+      .set({ eventTimestamp: null })
+      .where('identifier', '=', 'rq_production_deadbeef0003_0_0')
+      .execute()
+    const pending = (await RequestUsage.listPending(db, 'production'))[0]!
+    expect(pending).not.toHaveProperty('eventTimestamp')
+    const stripe = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now: () => new Date(pending.firstAttemptedAt).getTime() + 23 * 60 * 60 * 1_000,
+        readCounts: async () => [],
+        stripe: stripe.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(stripe.meterEvents).toHaveLength(0)
+    expect(await RequestUsage.listPending(db, 'production')).toHaveLength(1)
+    await db.close()
+  })
+
+  test('behavior: settles a retry when Stripe confirms the identifier already exists', async () => {
+    const db = create()
+    await db.migrate()
+    await RequestUsage.insertPending(db, {
+      bucketStart,
+      deltaCount: 6,
+      environment: 'production',
+      eventTimestamp: bucketStart,
+      identifier: 'rq_production_deadbeef0002_0_0',
+      orgId: 'org_1',
+      sequence: 0,
+      stripeCustomerId: 'cus_1',
+    })
+    const { stripe } = stubStripe({
+      meterEvent({ identifier }) {
+        throw new Error(`An event already exists with identifier ${identifier}.`)
+      },
+      subscriptions: [],
+    })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [],
+        stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(6) // prettier-ignore
     await db.close()
   })
 })