tapimo 0.5.2 → 0.6.0

package/src/internal/MetricSink.test.ts

@@ -0,0 +1,160 @@
+import * as Metrics from '../Metrics.js'
+import type * as Log from './Log.js'
+import * as MetricSink from './MetricSink.js'
+
+type MetricEvent = {
+  name: string
+  tags: Metrics.Tags | undefined
+  type: 'count' | 'gauge' | 'histogram'
+  value: number
+}
+
+describe('requests', () => {
+  test('records bounded funding provider attempts without caller data', () => {
+    const events: MetricEvent[] = []
+    let flushes = 0
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {
+        flushes += 1
+      },
+      gauge(name, value, tags) {
+        events.push({ name, tags, type: 'gauge', value })
+      },
+      histogram(name, value, tags) {
+        events.push({ name, tags, type: 'histogram', value })
+      },
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 100,
+      fundingProviderAttempts: [
+        {
+          durationMs: 10,
+          id: 'relay',
+          operation: 'quote/v2',
+          outcome: 'available',
+        },
+        {
+          durationMs: 20,
+          id: 'rhino',
+          operation: 'quote/bridge-swap/public',
+          outcome: 'thin',
+        },
+        {
+          durationMs: 30,
+          id: 'squid',
+          operation: 'v2/route',
+          outcome: 'unavailable',
+        },
+        {
+          durationMs: 40,
+          failure: 'timeout',
+          id: 'across',
+          operation: 'swap/approval',
+          outcome: 'failed',
+        },
+      ],
+      level: 'info',
+      method: 'GET',
+      path: '/v1/funding/quotes',
+      principal: {
+        id: 'key_private',
+        orgId: 'org_private',
+        projectId: 'project_private',
+        type: 'api_key',
+      },
+      query: 'sourceAmount=secret',
+      requestId: 'request_private',
+      route: '/v1/funding/quotes',
+      status: 200,
+    } satisfies Log.Entry)
+
+    const funding = events.filter((event) => event.name.startsWith('funding_quote_provider_'))
+    expect(funding).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "outcome": "available",
+            "provider": "relay",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "outcome": "available",
+            "provider": "relay",
+          },
+          "type": "histogram",
+          "value": 10,
+        },
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "outcome": "thin",
+            "provider": "rhino",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "outcome": "thin",
+            "provider": "rhino",
+          },
+          "type": "histogram",
+          "value": 20,
+        },
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "outcome": "unavailable",
+            "provider": "squid",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "outcome": "unavailable",
+            "provider": "squid",
+          },
+          "type": "histogram",
+          "value": 30,
+        },
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "failure": "timeout",
+            "outcome": "failed",
+            "provider": "across",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "failure": "timeout",
+            "outcome": "failed",
+            "provider": "across",
+          },
+          "type": "histogram",
+          "value": 40,
+        },
+      ]
+    `)
+    expect(JSON.stringify(funding)).not.toMatch(
+      /key_private|org_private|project_private|request_private|secret/,
+    )
+    expect(flushes).toBe(1)
+  })
+})

package/src/internal/MetricSink.ts

@@ -95,6 +95,16 @@ export function requests(backend: Metrics): RequestSink {
     for (const [operation, duration] of Object.entries(entry.timings ?? {}))
       backend.histogram('upstream_duration_ms', duration, { ...tags, operation })
 
+    for (const attempt of entry.fundingProviderAttempts ?? []) {
+      const tags_attempt = {
+        ...(attempt.failure === undefined ? {} : { failure: attempt.failure }),
+        outcome: attempt.outcome,
+        provider: attempt.id,
+      }
+      backend.count('funding_quote_provider_attempt_count', 1, tags_attempt)
+      backend.histogram('funding_quote_provider_duration_ms', attempt.durationMs, tags_attempt)
+    }
+
     backend.flush()
   }
 }

package/src/internal/OpenApi.ts

@@ -64,6 +64,7 @@ export const errorCodes = {
     'address_invalid',
     'token_invalid',
     'symbol_invalid',
+    'quote_amount_out_of_range',
     'pair_invalid',
     'pair_id_invalid',
     'transaction_invalid',
@@ -71,6 +72,7 @@ export const errorCodes = {
     'block_invalid',
     'chain_id_invalid',
     'chain_id_unsupported',
+    'destination_transition_invalid',
     'url_invalid',
     'api_key_malformed',
   ],
@@ -85,6 +87,7 @@ export const errorCodes = {
     'receipt_not_found',
     'order_not_found',
     'pair_not_found',
+    'quote_not_available',
     'verified_token_not_found',
     'webhook_not_found',
     'delivery_not_found',

package/src/internal/Schema.ts

@@ -290,6 +290,35 @@ export const DecimalString = z
     z.meta({ examples: ['1000000'] }),
   )
 
+/** A self-contained token quantity in base units and human-readable form. */
+export const TokenAmount = describe(
+  z.object({
+    baseUnits: DecimalString.check(z.describe("The quantity in the token's smallest unit.")),
+    currency: z
+      .string()
+      .check(
+        z.describe('The monetary denomination of this quantity.'),
+        z.meta({ examples: ['USD'] }),
+      ),
+    decimals: z
+      .number()
+      .check(
+        z.int(),
+        z.nonnegative(),
+        z.describe('Decimal places used to convert `baseUnits` into `formatted`.'),
+        z.meta({ examples: [6] }),
+      ),
+    formatted: z
+      .string()
+      .check(
+        z.regex(/^\d+(\.\d+)?$/),
+        z.describe('The quantity rendered in whole token units.'),
+        z.meta({ examples: ['1'] }),
+      ),
+  }),
+  'A token quantity with its denomination and decimal representation.',
+)
+
 /**
  * Minimum page size accepted across list endpoints. Floored at 5 because the
  * indexer rejects signature-decoded `Transfer` queries with `LIMIT < 5`
@@ -306,6 +335,22 @@ export const Limit = z
     z.meta({ examples: [10] }),
   )
 
+/** Valuation denomination query parameter shared across valuation-bearing endpoints. */
+export const Denomination = z
+  .optional(
+    z.pipe(
+      z.string().check(z.regex(/^[a-zA-Z]{3}$/)),
+      z.transform((value) => value.toUpperCase()),
+    ),
+  )
+  .check(
+    z.describe(
+      'Currency to denominate values in (case-insensitive, e.g. `AUD`). ' +
+        'Must be priced by the configured FX oracle. Defaults to `USD`.',
+    ),
+    z.meta({ examples: ['AUD'] }),
+  )
+
 /** Opaque keyset-pagination cursor query parameter shared across list endpoints. */
 export const Cursor = z
   .optional(z.string())
@@ -464,17 +509,17 @@ export function timestampBound(noun: string, bound: 'from' | 'to') {
 
 /**
  * Builds the schema for a comma-separated opt-in query parameter (e.g.
- * `?include=token,feeToken`), parsed into a validated array of the given enum's
+ * `?include=token,totalCount`), parsed into a validated array of the given enum's
  * members. Absent or empty values yield `[]`. Centralizes the splitting,
  * trimming, and OpenAPI array-enum metadata that every list endpoint otherwise
  * repeats.
  *
- * A repeated parameter (`?include=token&include=feeToken`) arrives from the
+ * A repeated parameter (`?include=token&include=totalCount`) arrives from the
  * validator as a `string[]`, so the input accepts both forms and each entry is
- * still comma-split — the two styles compose freely.
+ * still comma-split, so the two styles compose freely.
  *
- * Pass the endpoint's `Include` enum — kept local so its members drive both the
- * parsed type and the docs — plus the param description.
+ * Pass the endpoint's local `Include` enum so its members drive the parsed type
+ * and documentation, plus the parameter description.
  */
 export function includeQuery<const T extends Readonly<Record<string, string>>>(
   member: z.ZodMiniEnum<T>,

package/src/internal/Value.test.ts

@@ -0,0 +1,20 @@
+import * as Value from './Value.js'
+
+describe('tokenAmount', () => {
+  test('renders a self-contained token quantity', () => {
+    expect(
+      Value.tokenAmount({
+        baseUnits: '1234567',
+        currency: 'USD',
+        decimals: 6,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "baseUnits": "1234567",
+        "currency": "USD",
+        "decimals": 6,
+        "formatted": "1.234567",
+      }
+    `)
+  })
+})

package/src/internal/Value.ts

@@ -1,4 +1,4 @@
-import { Hex } from 'ox'
+import { Hex, Value as core_Value } from 'ox'
 
 /** Coerce a TIDX numeric column (bigint / number / string) to a JS number. */
 export function toNumber(value: unknown) {
@@ -39,6 +39,29 @@ export function toIntegerString(value: unknown) {
   return undefined
 }
 
+/** Builds a token amount from its base-unit quantity and immutable token metadata. */
+export function tokenAmount(options: tokenAmount.Options) {
+  const baseUnits = options.baseUnits.toString()
+  return {
+    baseUnits,
+    currency: options.currency,
+    decimals: options.decimals,
+    formatted: core_Value.format(BigInt(baseUnits), options.decimals),
+  }
+}
+
+export declare namespace tokenAmount {
+  /** Inputs needed to render a self-contained token amount. */
+  type Options = {
+    /** Quantity in the token's smallest unit. */
+    baseUnits: bigint | string
+    /** Monetary denomination reported by the token. */
+    currency: string
+    /** Decimal places used by the token. */
+    decimals: number
+  }
+}
+
 /**
  * Coerce a TIDX numeric column (bigint / number / decimal string) to a minimal
  * `0x`-prefixed hex quantity (`0x0` for zero), matching the JSON-RPC wire

package/src/internal/VerifiedTokens.ts

@@ -535,7 +535,15 @@ export async function snapshot(c: Context<App.Environment>, chainId: ChainId): P
 
     // Soft-stale: serve immediately, refresh in the background. Never blocks.
     if (cell) {
-      void refresh(c, Db.get(c.get('dbCached')), chainId, cell)
+      const inflight = refresh(c, Db.get(c.get('dbCached')), chainId, cell)
+      // Workers cancel post-response I/O unless kept alive via `waitUntil`;
+      // without it the refresh dies mid-query and publishes never propagate.
+      // Node has no execution context, and fire-and-forget survives there.
+      try {
+        c.executionCtx.waitUntil(inflight)
+      } catch {
+        void inflight
+      }
       return cell.snapshot
     }
 

package/src/internal/Webhooks.test.ts

@@ -78,6 +78,45 @@ describe('createSubscription', () => {
     )
   })
 
+  test('counts paused subscriptions toward the live subscription cap', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput(), { maxPerOwner: 1 })
+    await Webhooks.updateSubscription(db, apiKeyOwner, created.id, { status: 'paused' })
+
+    await expect(
+      Webhooks.createSubscription(db, createInput(), { maxPerOwner: 1 }),
+    ).rejects.toBeInstanceOf(Webhooks.LimitExceededError)
+    await Webhooks.deleteSubscription(db, apiKeyOwner, created.id)
+    await expect(
+      Webhooks.createSubscription(db, createInput(), { maxPerOwner: 1 }),
+    ).resolves.toMatchObject({ status: 'active' })
+  })
+
+  test('enforces the per-owner cap across concurrent creates', async () => {
+    const getDb = TestApp.databaseFactory()
+    const results = await Promise.allSettled(
+      Array.from({ length: 8 }, () =>
+        Webhooks.createSubscription(getDb(), createInput(), { maxPerOwner: 3 }),
+      ),
+    )
+
+    expect(results.map((result) => result.status).sort()).toMatchInlineSnapshot(`
+      [
+        "fulfilled",
+        "fulfilled",
+        "fulfilled",
+        "rejected",
+        "rejected",
+        "rejected",
+        "rejected",
+        "rejected",
+      ]
+    `)
+    for (const result of results)
+      if (result.status === 'rejected') expect(result.reason).toBeInstanceOf(Webhooks.LimitExceededError) // prettier-ignore
+    expect(await Webhooks.listSubscriptions(getDb(), apiKeyOwner)).toHaveLength(3)
+  })
+
   test('rejects an undeliverable URL before persisting', async () => {
     const db = TestApp.database()
     await expect(
@@ -204,6 +243,27 @@ describe('updateSubscription', () => {
       `[Webhooks.InvalidUrlError: Webhook URL rejected (protocol): http://10.0.0.1]`,
     )
   })
+
+  test('requires recreation before activating URL signing for a provider destination', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(
+      db,
+      createInput({
+        destination: {
+          type: 'slack',
+          url: 'https://hooks.slack.com/services/T000/B000/xxxx',
+        },
+      }),
+    )
+
+    await expect(
+      Webhooks.updateSubscription(db, apiKeyOwner, created.id, {
+        destination: { type: 'url', url: 'https://hooks.example.com/v2' },
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Webhooks.InvalidDestinationTransitionError: Create a new webhook to change a provider-managed destination to an HTTPS endpoint.]`,
+    )
+  })
 })
 
 describe('listActive', () => {
@@ -548,6 +608,86 @@ describe('delivery log', () => {
     `)
   })
 
+  test('deliverCurrentAndRecord skips paused and deleted queued subscriptions', async () => {
+    const db = TestApp.database()
+    const paused = await Webhooks.createSubscription(db, createInput())
+    const removed = await Webhooks.createSubscription(db, createInput())
+    const pausedEnvelope = Webhooks.buildEnvelope({
+      blockNumber: 1,
+      data: { amount: '1' },
+      logIndex: 0,
+      subscription: paused,
+    })
+    const removedEnvelope = Webhooks.buildEnvelope({
+      blockNumber: 1,
+      data: { amount: '1' },
+      logIndex: 1,
+      subscription: removed,
+    })
+    await Webhooks.updateSubscription(db, apiKeyOwner, paused.id, { status: 'paused' })
+    await Webhooks.deleteSubscription(db, apiKeyOwner, removed.id)
+    let requests = 0
+    const fetch = (async () => {
+      requests++
+      return new Response(null, { status: 200 })
+    }) satisfies typeof globalThis.fetch
+
+    await expect(
+      Webhooks.deliverCurrentAndRecord(db, paused, pausedEnvelope, { fetch }),
+    ).resolves.toEqual({ status: 'skipped' })
+    await expect(
+      Webhooks.deliverCurrentAndRecord(db, removed, removedEnvelope, { fetch }),
+    ).resolves.toEqual({ status: 'skipped' })
+    expect(requests).toBe(0)
+  })
+
+  test('deliverCurrentAndRecord uses the current destination and secret', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput())
+    const envelope = Webhooks.buildEnvelope({
+      blockNumber: 1,
+      data: { amount: '1' },
+      logIndex: 0,
+      subscription: created,
+    })
+    const current = await Webhooks.updateSubscription(db, apiKeyOwner, created.id, {
+      destination: { type: 'url', url: 'https://hooks.example.com/current' },
+    })
+    const queued = { ...created, secret: `whsec_${'ff'.repeat(32)}` }
+    const captured: { body: string; signature: string | null; url: string } = {
+      body: '',
+      signature: null,
+      url: '',
+    }
+    const fetch = (async (input, init) => {
+      captured.body = typeof init?.body === 'string' ? init.body : ''
+      captured.signature = new Headers(init?.headers).get(Webhooks.signatureHeader)
+      captured.url = input instanceof Request ? input.url : input.toString()
+      return new Response(null, { status: 200 })
+    }) satisfies typeof globalThis.fetch
+
+    const delivery = await Webhooks.deliverCurrentAndRecord(db, queued, envelope, { fetch })
+
+    expect(delivery.status).toBe('delivered')
+    expect(captured.url).toBe('https://hooks.example.com/current')
+    expect(
+      Webhooks.verify({
+        body: captured.body,
+        secret: current!.secret,
+        signature: captured.signature ?? '',
+        tolerance: Number.POSITIVE_INFINITY,
+      }),
+    ).toBe(true)
+    expect(
+      Webhooks.verify({
+        body: captured.body,
+        secret: queued.secret,
+        signature: captured.signature ?? '',
+        tolerance: Number.POSITIVE_INFINITY,
+      }),
+    ).toBe(false)
+  })
+
   test('deleteSubscription removes the delivery log', async () => {
     const db = TestApp.database()
     const created = await Webhooks.createSubscription(db, createInput())

package/src/internal/Webhooks.ts

@@ -161,8 +161,8 @@ export type Delivery = {
 
 /**
  * Creates a subscription, validating its URL and (optionally) enforcing a
- * per-owner cap, then persists it. The cap check stays best-effort (count then
- * insert, non-transactional) — parity with the old store behavior.
+ * per-owner cap, then persists it. Capped writes serialize per owner so
+ * concurrent requests cannot exceed the limit.
  */
 export async function createSubscription(
   db: Db.Db,
@@ -174,11 +174,6 @@ export async function createSubscription(
   const now = (options.now ?? (() => new Date()))()
   const iso = now.toISOString()
 
-  if (options.maxPerOwner !== undefined) {
-    const existing = await WebhookSubscriptions.count(db, input.owner, iso)
-    if (existing >= options.maxPerOwner) throw new LimitExceededError(options.maxPerOwner)
-  }
-
   const subscription: Subscription = {
     chainId: input.chainId,
     ...(input.context === undefined ? {} : { context: input.context }),
@@ -197,14 +192,20 @@ export async function createSubscription(
       : { expiresAt: new Date(now.getTime() + input.ttl).toISOString() }),
   }
 
-  await WebhookSubscriptions.insert(db, subscription)
+  if (options.maxPerOwner !== undefined) {
+    const inserted = await WebhookSubscriptions.insertWithinLimit(db, subscription, {
+      maxPerOwner: options.maxPerOwner,
+      now: iso,
+    })
+    if (!inserted) throw new LimitExceededError(options.maxPerOwner)
+  } else await WebhookSubscriptions.insert(db, subscription)
   return subscription
 }
 
 export declare namespace createSubscription {
   /** Options for {@link createSubscription}. */
   type Options = {
-    /** Reject creation once the owner has this many subscriptions. */
+    /** Reject creation once the owner has this many live subscriptions. */
     maxPerOwner?: number | undefined
     /** Clock used for timestamps (injectable for tests). */
     now?: (() => Date) | undefined
@@ -268,6 +269,8 @@ export async function updateSubscription(
   const current = await getSubscription(db, owner, id)
   if (!current) return null
 
+  if (current.destination.type !== 'url' && patch.destination?.type === 'url')
+    throw new InvalidDestinationTransitionError()
   if (patch.destination !== undefined) WebhookDestination.assertDestination(patch.destination)
 
   const now = (options.now ?? (() => new Date()))()
@@ -550,6 +553,39 @@ export declare namespace deliverAndRecord {
   }
 }
 
+/**
+ * Re-resolves an enqueued subscription before delivery. Missing or inactive
+ * subscriptions are skipped; delivery uses the current destination and secret.
+ */
+export async function deliverCurrentAndRecord(
+  db: Db.Db,
+  queued: Subscription,
+  envelope: Envelope,
+  options: deliverAndRecord.Options = {},
+): Promise<deliverCurrentAndRecord.Result> {
+  const subscription = await getSubscription(db, queued.owner, queued.id)
+  if (!subscription || subscription.status !== 'active') return { status: 'skipped' }
+  return {
+    result: await deliverAndRecord(db, subscription, envelope, options),
+    status: 'delivered',
+  }
+}
+
+export declare namespace deliverCurrentAndRecord {
+  /** Authoritative delivery outcome, or a skipped stale queue message. */
+  type Result =
+    | {
+        /** Transport result from the current subscription state. */
+        result: WebhookDestination.Result
+        /** The current subscription was delivered. */
+        status: 'delivered'
+      }
+    | {
+        /** The queued subscription is absent or inactive. */
+        status: 'skipped'
+      }
+}
+
 /** Builds a delivery-log row from an attempt's envelope and classified result. */
 function buildDelivery(
   input: {
@@ -783,6 +819,14 @@ export class LimitExceededError extends Error {
   }
 }
 
+/** Thrown when an update would activate URL signing with an unrecoverable secret. */
+export class InvalidDestinationTransitionError extends Error {
+  constructor() {
+    super('Create a new webhook to change a provider-managed destination to an HTTPS endpoint.')
+    this.name = 'Webhooks.InvalidDestinationTransitionError'
+  }
+}
+
 /**
  * Thrown when a subscription's `filters` fail to validate against the schema for
  * its `eventType`. The detection path treats stored filters as **fail-closed**: