tapimo 0.7.0 → 0.7.2

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

@@ -1,6 +1,7 @@
 import { type Db, Webhooks as Core } from 'tapimo'
 import * as z from 'zod/mini'
 
+import * as Cursor from '../../../internal/Cursor.js'
 import * as Tidx from '../../../internal/Tidx.js'
 import * as Viem from '../../../internal/Viem.js'
 import * as TestApp from '../../../../test/App.js'
@@ -163,12 +164,7 @@ describe('access matrix', () => {
     const zone = 421_700_001
     const app = TestApp.client({
       auth: { keys: [writer] },
-      zones: [
-        {
-          chainId: zone,
-          forwardRpcUrl: 'https://zone.rpc.test',
-        },
-      ],
+      zones: [TestApp.zone({ chainId: zone, rpcUrl: 'https://zone.rpc.test' })],
     })
     const response = await app.v1.webhooks.$post(
       { json: { ...validBody, chainId: zone } },
@@ -226,7 +222,11 @@ describe('access matrix', () => {
 
 describe('CRUD lifecycle', () => {
   test('creates, reads, lists, updates, and deletes a subscription', async () => {
-    const app = client()
+    const db = TestApp.database()
+    const app = TestApp.client({
+      auth: { keys: [writer, reader, other] },
+      db,
+    })
 
     // Create returns the one-time signing secret.
     const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
@@ -239,6 +239,9 @@ describe('CRUD lifecycle', () => {
     // API-key-owned subscriptions never expire.
     expect(createdBody.expiresAt).toMatchInlineSnapshot(`undefined`)
     expect(createdBody).not.toHaveProperty('owner')
+    expect(Cursor.decode((await Core.getCursor(db, createdBody.id))!, ['int'])).toEqual([
+      expect.any(Number),
+    ])
 
     // Reads never expose the secret.
     const read = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get(
@@ -1320,15 +1323,17 @@ describe('envelope schema', () => {
 describe('MPP access (disabled for now — API-key-only)', () => {
   test('rejects an MPP payer with 401, offering no payment challenge', async () => {
     const app = TestApp.create({
-      auth: { keys: [] },
-      mpp: {
-        secretKey: 'secret_test_key_0123456789abcdef',
-        session: {
-          chainId: Tempo.chain.id,
-          currency: Tempo.currency,
-          decimals: 6,
-          getClient: () => Tempo.client,
-          recipient: Tempo.accounts[2].address,
+      auth: {
+        keys: [],
+        mpp: {
+          secretKey: 'secret_test_key_0123456789abcdef',
+          session: {
+            chainId: Tempo.chain.id,
+            currency: Tempo.currency,
+            decimals: 6,
+            getClient: () => Tempo.client,
+            recipient: Tempo.accounts[2].address,
+          },
         },
       },
     })
@@ -1352,11 +1357,11 @@ describe('MPP access (disabled for now — API-key-only)', () => {
 // redirected to the disposable local chain, which lacks that history, so the
 // whole block is testnet-only.
 describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
-  /** Decodes the opaque `(block, index)` keyset cursor the poller stores. */
-  function decodeCursor(token: string | null): [number, number] | null {
+  /** Decodes an opaque creation checkpoint or `(block, index)` poller cursor. */
+  function decodeCursor(token: string | null): number[] | null {
     if (!token) return null
     const json = atob(token.replaceAll('-', '+').replaceAll('_', '/'))
-    return JSON.parse(json) as [number, number]
+    return JSON.parse(json) as number[]
   }
 
   /** Encodes a `(block, index)` keyset cursor in the poller's opaque format. */
@@ -1373,7 +1378,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
   // the real keyset/`toBlock` SQL and decode path end to end — no fabricated rows.
   const realTidx = Tidx.getClient({
     chainId: 42431,
-    tidx: { baseUrl: 'https://tidx.tempo.xyz', basicAuth: process.env.TIDX_BASIC_AUTH },
+    tidx: { auth: process.env.TIDX_AUTH, baseUrl: 'https://tidx.tempo.xyz' },
   })
   // The monitoring scanners (`log:emitted`/`block:created`/`transaction:included`)
   // read the same immutable historical window over real RPC (chain 42431 →
@@ -1390,6 +1395,9 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
   // rows, both in block 1,000,002 (`log_idx` 0 then 1): a TIP-20 transfer
   // followed by its fee payment. Filtering on it makes the scan deterministic.
   const windowSender = '0xe7687128b0a808c2831ff94d4f7b2fb35c65af38'
+  // This token has 226 transfers across blocks 1,000,000 through 1,000,003.
+  const volumeHead = 1_000_005
+  const volumeToken = '0x20c0000000000000000000000000000000000001'
 
   async function createTransferSubscription(db: Db.Db) {
     return Core.createSubscription(db, {
@@ -1401,6 +1409,16 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     })
   }
 
+  async function createVolumeSubscription(db: Db.Db, ownerId = 'org_test') {
+    return Core.createSubscription(db, {
+      chainId: 42431,
+      destination: { type: 'url', url: `https://hooks.example.com/${ownerId}` },
+      eventType: 'token:transfer',
+      filters: { token: volumeToken },
+      owner: { orgId: ownerId, type: 'api_key' },
+    })
+  }
+
   test('dispatches a signed envelope per row and advances the cursor', async () => {
     const db = TestApp.database()
     const subscription = await createTransferSubscription(db)
@@ -1519,6 +1537,104 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     `)
   })
 
+  test('drains two bounded transfer pages per tick without gaps', async () => {
+    const db = TestApp.database()
+    const subscription = await createVolumeSubscription(db)
+    await Core.setCursor(db, subscription.id, windowCursor)
+
+    const positions: string[] = []
+    const tick = () =>
+      Webhooks.poll({
+        chainId: 42431,
+        client,
+        db,
+        dispatch: async ({ envelope }) => {
+          const data = envelope.data as { blockNumber: number; logIndex: number }
+          positions.push(`${data.blockNumber}:${data.logIndex}`)
+          return { ok: true }
+        },
+        eventTypes: ['token:transfer'],
+        headBlockNumber: volumeHead,
+        tidx: realTidx,
+      })
+
+    expect((await tick()).dispatched).toBe(200)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([1_000_003, 144])
+    expect((await tick()).dispatched).toBe(26)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([1_000_003, 223])
+    expect(positions).toHaveLength(226)
+    expect(new Set(positions).size).toBe(226)
+    expect(positions[99]).toBe('1000002:9')
+    expect(positions[100]).toBe('1000002:10')
+  })
+
+  test('commits the first page before a continuation delivery fails', async () => {
+    const db = TestApp.database()
+    const subscription = await createVolumeSubscription(db)
+    await Core.setCursor(db, subscription.id, windowCursor)
+
+    let calls = 0
+    const first = await Webhooks.poll({
+      chainId: 42431,
+      client,
+      db,
+      dispatch: async () => (++calls === 101 ? { error: 'unreachable', ok: false } : { ok: true }),
+      eventTypes: ['token:transfer'],
+      headBlockNumber: volumeHead,
+      tidx: realTidx,
+    })
+
+    expect(first.dispatched).toBe(100)
+    expect(first.failed).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([1_000_002, 9])
+
+    let resumed: readonly [number, number] | undefined
+    await Webhooks.poll({
+      batchSize: 1,
+      chainId: 42431,
+      client,
+      db,
+      dispatch: async ({ envelope }) => {
+        const data = envelope.data as { blockNumber: number; logIndex: number }
+        resumed = [data.blockNumber, data.logIndex]
+        return { ok: true }
+      },
+      eventTypes: ['token:transfer'],
+      headBlockNumber: volumeHead,
+      tidx: realTidx,
+    })
+    expect(resumed).toEqual([1_000_002, 10])
+  })
+
+  test('round-robins continuation pages across subscriptions', async () => {
+    const db = TestApp.database()
+    const a = await createVolumeSubscription(db, 'org_a')
+    const b = await createVolumeSubscription(db, 'org_b')
+    await Core.setCursor(db, a.id, windowCursor)
+    await Core.setCursor(db, b.id, windowCursor)
+    const [first, second] = [a.id, b.id].sort()
+
+    const order: string[] = []
+    await Webhooks.poll({
+      chainId: 42431,
+      client,
+      db,
+      dispatch: async ({ subscription }) => {
+        order.push(subscription.id)
+        return { ok: true }
+      },
+      eventTypes: ['token:transfer'],
+      headBlockNumber: volumeHead,
+      tidx: realTidx,
+    })
+
+    expect(order).toHaveLength(400)
+    expect(new Set(order.slice(0, 100))).toEqual(new Set([first]))
+    expect(new Set(order.slice(100, 200))).toEqual(new Set([second]))
+    expect(new Set(order.slice(200, 300))).toEqual(new Set([first]))
+    expect(new Set(order.slice(300, 400))).toEqual(new Set([second]))
+  })
+
   test('anchors a first-seen subscription at the confirmed head without backfilling', async () => {
     const db = TestApp.database()
     const subscription = await createTransferSubscription(db)
@@ -1550,6 +1666,82 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     `)
   })
 
+  test('dispatches creation-head replacements once confirmed', async () => {
+    const db = TestApp.database()
+    const creationHead = windowTo
+    const subscription = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        destination: { type: 'url', url: 'https://hooks.example.com/x' },
+        eventType: 'token:transfer',
+        filters: { sender: windowSender },
+        owner: { orgId: 'org_test', type: 'api_key' },
+      },
+      { startBlockNumber: creationHead },
+    )
+
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      confirmations: 3,
+      dispatch: async () => ({ ok: true }),
+      eventTypes: ['token:transfer'],
+      headBlockNumber: creationHead + 3,
+      client,
+      db,
+      tidx: realTidx,
+    })
+
+    expect(result.dispatched).toBe(2)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowTo, 1])
+  })
+
+  test('keeps confirmed creation anchors while sources catch up', async () => {
+    const db = TestApp.database()
+    const startBlockNumber = windowTo + 100
+    const transfer = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        destination: { type: 'url', url: 'https://hooks.example.com/transfer' },
+        eventType: 'token:transfer',
+        filters: { sender: windowSender },
+        owner: { orgId: 'org_transfer', type: 'api_key' },
+      },
+      { startBlockNumber },
+    )
+    const block = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        destination: { type: 'url', url: 'https://hooks.example.com/block' },
+        eventType: 'block:created',
+        filters: {},
+        owner: { orgId: 'org_block', type: 'api_key' },
+      },
+      { startBlockNumber },
+    )
+
+    await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async () => ({ ok: true }),
+      eventTypes: ['token:transfer', 'block:created'],
+      headBlockNumber: windowHead,
+      client,
+      db,
+      tidx: realTidx,
+    })
+
+    expect(decodeCursor(await Core.getCursor(db, transfer.id))).toEqual([
+      startBlockNumber - 2,
+      endOfBlockIndex,
+    ])
+    expect(decodeCursor(await Core.getCursor(db, block.id))).toEqual([
+      startBlockNumber - 2,
+      endOfBlockIndex,
+    ])
+  })
+
   test('advances to the end of the confirmed window on an empty scan', async () => {
     const db = TestApp.database()
     const subscription = await createTransferSubscription(db)
@@ -1687,27 +1879,67 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     `)
   })
 
-  test('block:created scans new blocks and resolves transaction counts', async () => {
+  test('log:emitted limits a tick and resumes within the block', async () => {
     const db = TestApp.database()
     const subscription = await Core.createSubscription(db, {
       chainId: 42431,
-      eventType: 'block:created',
-      // Pin to a single block so the heartbeat feed is deterministic.
-      filters: { number: { eq: `0x${windowTo.toString(16)}` } },
-      owner: { orgId: 'org_test', type: 'api_key' },
       destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      eventType: 'log:emitted',
+      filters: { args: { from: windowSender }, signature: transferSignature },
+      owner: { orgId: 'org_test', type: 'api_key' },
     })
     await Core.setCursor(db, subscription.id, windowCursor)
 
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const tick = () =>
+      Webhooks.poll({
+        batchSize: 1,
+        chainId: 42431,
+        client,
+        db,
+        dispatch: async (input) => {
+          dispatched.push(input)
+          return { ok: true }
+        },
+        eventTypes: ['log:emitted'],
+        headBlockNumber: windowHead,
+        tidx: realTidx,
+      })
+
+    expect((await tick()).dispatched).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowTo, 0])
+    expect((await tick()).dispatched).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowTo, 1])
+    expect(
+      dispatched.map(({ envelope }) => (envelope.data as { logIndex: number }).logIndex),
+    ).toEqual([0, 1])
+  })
+
+  test('block:created scans new blocks and resolves transaction counts', async () => {
+    const db = TestApp.database()
+    const subscription = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        eventType: 'block:created',
+        // Pin to the creation-head height, which may be replaced before confirmation.
+        filters: { number: { eq: `0x${windowTo.toString(16)}` } },
+        owner: { orgId: 'org_test', type: 'api_key' },
+        destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      },
+      { startBlockNumber: windowTo },
+    )
+
     const dispatched: Webhooks.poll.Dispatchable[] = []
     const result = await Webhooks.poll({
       chainId: 42431,
+      confirmations: 3,
       dispatch: async (input) => {
         dispatched.push(input)
         return { ok: true }
       },
       eventTypes: ['block:created'],
-      headBlockNumber: windowHead,
+      headBlockNumber: windowTo + 3,
       client,
       db,
       tidx: realTidx,
@@ -1736,28 +1968,126 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     `)
   })
 
-  test('transaction:included filters on txs columns and inner calls', async () => {
+  test('block:created limits a tick and resumes at the next block', async () => {
     const db = TestApp.database()
     const subscription = await Core.createSubscription(db, {
       chainId: 42431,
-      eventType: 'transaction:included',
-      // `from` + an `input` selector (ERC20 `transfer` = 0xa9059cbb) pins the
-      // scan to the deterministic window tx.
-      filters: { from: windowSender, input: { selector: '0xa9059cbb' } },
-      owner: { orgId: 'org_test', type: 'api_key' },
       destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      eventType: 'block:created',
+      filters: {},
+      owner: { orgId: 'org_test', type: 'api_key' },
     })
     await Core.setCursor(db, subscription.id, windowCursor)
 
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const tick = () =>
+      Webhooks.poll({
+        batchSize: 1,
+        chainId: 42431,
+        client,
+        db,
+        dispatch: async (input) => {
+          dispatched.push(input)
+          return { ok: true }
+        },
+        eventTypes: ['block:created'],
+        headBlockNumber: windowHead,
+        tidx: realTidx,
+      })
+
+    expect((await tick()).dispatched).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowFrom, 0])
+    expect((await tick()).dispatched).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowFrom + 1, 0])
+    expect(dispatched.map(({ envelope }) => (envelope.data as { number: number }).number)).toEqual([
+      windowFrom,
+      windowFrom + 1,
+    ])
+  })
+
+  test('block:created continues other subscriptions when a block header cannot be read', async () => {
+    const db = TestApp.database()
+    const missingBlock = 4_000_000_000
+    const cursor = encodeCursor([missingBlock - 1, endOfBlockIndex])
+    const unavailable = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        destination: { type: 'url', url: 'https://hooks.example.com/unavailable' },
+        eventType: 'block:created',
+        filters: { number: { eq: `0x${missingBlock.toString(16)}` } },
+        owner: { orgId: 'org_test', type: 'api_key' },
+      },
+      { now: () => new Date('2026-01-01T00:00:00.000Z') },
+    )
+    const healthy = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        destination: { type: 'url', url: 'https://hooks.example.com/healthy' },
+        eventType: 'block:created',
+        filters: { number: { eq: `0x${windowTo.toString(16)}` } },
+        owner: { orgId: 'org_test', type: 'api_key' },
+      },
+      { now: () => new Date('2026-01-01T00:00:01.000Z') },
+    )
+    await Core.setCursor(db, unavailable.id, cursor)
+    await Core.setCursor(db, healthy.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+
+    await expect(
+      Webhooks.poll({
+        chainId: 42431,
+        dispatch: async (input) => {
+          dispatched.push(input)
+          return { ok: true }
+        },
+        eventTypes: ['block:created'],
+        headBlockNumber: missingBlock + 2,
+        client,
+        db,
+        maxBlocks: 3,
+        tidx: realTidx,
+      }),
+    ).rejects.toThrow()
+
+    expect(await Core.getCursor(db, unavailable.id)).toBe(cursor)
+    expect(decodeCursor(await Core.getCursor(db, healthy.id))).toMatchInlineSnapshot(`
+      [
+        1000002,
+        2147483647,
+      ]
+    `)
+    expect(dispatched.map(({ subscription }) => subscription.id)).toEqual([healthy.id])
+  })
+
+  test('transaction:included filters on txs columns and inner calls', async () => {
+    const db = TestApp.database()
+    const subscription = await Core.createSubscription(
+      db,
+      {
+        chainId: 42431,
+        eventType: 'transaction:included',
+        // `from` + an `input` selector (ERC20 `transfer` = 0xa9059cbb) pins the
+        // scan to the deterministic creation-head transaction.
+        filters: { from: windowSender, input: { selector: '0xa9059cbb' } },
+        owner: { orgId: 'org_test', type: 'api_key' },
+        destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      },
+      { startBlockNumber: windowTo },
+    )
+
     const dispatched: Webhooks.poll.Dispatchable[] = []
     const result = await Webhooks.poll({
       chainId: 42431,
+      confirmations: 3,
       dispatch: async (input) => {
         dispatched.push(input)
         return { ok: true }
       },
       eventTypes: ['transaction:included'],
-      headBlockNumber: windowHead,
+      headBlockNumber: windowTo + 3,
       client,
       db,
       tidx: realTidx,
@@ -1776,6 +2106,75 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
       expect(typeof tx.feeToken?.name).toBe('string')
       expect(typeof tx.feeToken?.symbol).toBe('string')
     } else expect(tx?.feeToken).toBeUndefined()
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([
+      windowTo,
+      endOfBlockIndex,
+    ])
+  })
+
+  test('transaction:included limits a tick and resumes within the block', async () => {
+    const db = TestApp.database()
+    const subscription = await Core.createSubscription(db, {
+      chainId: 42431,
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      eventType: 'transaction:included',
+      filters: {},
+      owner: { orgId: 'org_test', type: 'api_key' },
+    })
+    await Core.setCursor(db, subscription.id, encodeCursor([windowTo - 1, endOfBlockIndex]))
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const tick = () =>
+      Webhooks.poll({
+        batchSize: 1,
+        chainId: 42431,
+        client,
+        db,
+        dispatch: async (input) => {
+          dispatched.push(input)
+          return { ok: true }
+        },
+        eventTypes: ['transaction:included'],
+        headBlockNumber: windowHead,
+        tidx: realTidx,
+      })
+
+    expect((await tick()).dispatched).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowTo, 0])
+    expect((await tick()).dispatched).toBe(1)
+    expect(decodeCursor(await Core.getCursor(db, subscription.id))).toEqual([windowTo, 1])
+    expect(
+      new Set(dispatched.map(({ envelope }) => (envelope.data as { hash: string }).hash)).size,
+    ).toBe(2)
+  })
+
+  test('transaction:included preserves the cursor when a confirmed block is unavailable', async () => {
+    const db = TestApp.database()
+    const missingBlock = 4_000_000_000
+    const cursor = encodeCursor([missingBlock - 1, endOfBlockIndex])
+    const subscription = await Core.createSubscription(db, {
+      chainId: 42431,
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      eventType: 'transaction:included',
+      filters: { blockNumber: { eq: `0x${missingBlock.toString(16)}` } },
+      owner: { orgId: 'org_test', type: 'api_key' },
+    })
+    await Core.setCursor(db, subscription.id, cursor)
+
+    await expect(
+      Webhooks.poll({
+        chainId: 42431,
+        eventTypes: ['transaction:included'],
+        headBlockNumber: missingBlock + 2,
+        client,
+        db,
+        tidx: realTidx,
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`
+      [Webhooks.BlockUnavailableError: Block 4000000000 is unavailable.]
+    `)
+
+    expect(await Core.getCursor(db, subscription.id)).toBe(cursor)
   })
 
   test('transaction:included matches exact empty calldata through the poller', async () => {