tapimo 0.7.0 → 0.7.2

package/src/internal/MetricSink.test.ts

@@ -10,6 +10,165 @@ type MetricEvent = {
 }
 
 describe('requests', () => {
+  test('records optional funding transfer count failures on successful pages', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 10,
+      fundingTransferCountFailed: true,
+      level: 'info',
+      method: 'GET',
+      path: '/v1/funding/transfers',
+      requestId: 'request_private',
+      route: '/v1/funding/transfers',
+      status: 200,
+    })
+
+    expect(events.find((event) => event.name === 'funding_transfer_count_failure_count'))
+      .toMatchInlineSnapshot(`
+      {
+        "name": "funding_transfer_count_failure_count",
+        "tags": {
+          "cache": "miss",
+          "method": "GET",
+          "principal_environment": "none",
+          "principal_type": "unknown",
+          "route": "/v1/funding/transfers",
+        },
+        "type": "count",
+        "value": 1,
+      }
+    `)
+  })
+
+  test('records bounded operational failure signals', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 10,
+      errorCode: 'upstream_error',
+      level: 'error',
+      method: 'POST',
+      path: '/rpc/sponsor',
+      providerFailures: [
+        {
+          chainId: 4217,
+          failure: 'http',
+          id: 'tidx',
+          operation: 'query',
+          status: 502,
+        },
+      ],
+      requestId: 'request_private',
+      route: '/rpc/sponsor',
+      rpc: { code: -32603, dataCode: 'internal_error', errors: 2, serverErrors: 2 },
+      sponsorship: {
+        chainId: 4217,
+        internalErrors: 2,
+        method: 'eth_sendRawTransaction',
+        outcome: 'rejected',
+        payloadHash: `0x${'aa'.repeat(32)}`,
+        rejections: 2,
+      },
+      status: 502,
+    })
+
+    expect(events.filter((event) => event.name !== 'http_response_count')).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "http_server_error_count",
+          "tags": {
+            "cache": "miss",
+            "error_code": "upstream_error",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/sponsor",
+            "status": 502,
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "rpc_response_error_count",
+          "tags": {
+            "cache": "miss",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/sponsor",
+            "rpc_error_code": "-32603",
+          },
+          "type": "count",
+          "value": 2,
+        },
+        {
+          "name": "rpc_response_server_error_count",
+          "tags": {
+            "cache": "miss",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/sponsor",
+            "rpc_error_code": "-32603",
+          },
+          "type": "count",
+          "value": 2,
+        },
+        {
+          "name": "upstream_failure_count",
+          "tags": {
+            "cache": "miss",
+            "chain_id": "4217",
+            "failure": "http",
+            "method": "POST",
+            "operation": "query",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "provider": "tidx",
+            "route": "/rpc/sponsor",
+            "status": "502",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "sponsorship_internal_error_count",
+          "tags": {
+            "cache": "miss",
+            "chain_id": "4217",
+            "method": "eth_sendRawTransaction",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/sponsor",
+          },
+          "type": "count",
+          "value": 2,
+        },
+      ]
+    `)
+    expect(JSON.stringify(events)).not.toContain('request_private')
+    expect(JSON.stringify(events)).not.toContain('aa'.repeat(32))
+  })
+
   test('records JSON-RPC errors with bounded code tags', () => {
     const events: MetricEvent[] = []
     const metrics = Metrics.from({
@@ -90,26 +249,26 @@ describe('requests', () => {
         {
           durationMs: 10,
           id: 'relay',
-          operation: 'quote/v2',
+          operation: 'getQuote',
           outcome: 'available',
         },
         {
           durationMs: 20,
           id: 'rhino',
-          operation: 'quote/bridge-swap/public',
+          operation: 'getQuote',
           outcome: 'thin',
         },
         {
           durationMs: 30,
           id: 'squid',
-          operation: 'v2/route',
+          operation: 'getQuote',
           outcome: 'unavailable',
         },
         {
           durationMs: 40,
           failure: 'timeout',
           id: 'across',
-          operation: 'swap/approval',
+          operation: 'prepareTransfer',
           outcome: 'failed',
         },
       ],
@@ -134,6 +293,7 @@ describe('requests', () => {
         {
           "name": "funding_quote_provider_attempt_count",
           "tags": {
+            "operation": "getQuote",
             "outcome": "available",
             "provider": "relay",
           },
@@ -143,6 +303,7 @@ describe('requests', () => {
         {
           "name": "funding_quote_provider_duration_ms",
           "tags": {
+            "operation": "getQuote",
             "outcome": "available",
             "provider": "relay",
           },
@@ -152,6 +313,7 @@ describe('requests', () => {
         {
           "name": "funding_quote_provider_attempt_count",
           "tags": {
+            "operation": "getQuote",
             "outcome": "thin",
             "provider": "rhino",
           },
@@ -161,6 +323,7 @@ describe('requests', () => {
         {
           "name": "funding_quote_provider_duration_ms",
           "tags": {
+            "operation": "getQuote",
             "outcome": "thin",
             "provider": "rhino",
           },
@@ -170,6 +333,7 @@ describe('requests', () => {
         {
           "name": "funding_quote_provider_attempt_count",
           "tags": {
+            "operation": "getQuote",
             "outcome": "unavailable",
             "provider": "squid",
           },
@@ -179,6 +343,7 @@ describe('requests', () => {
         {
           "name": "funding_quote_provider_duration_ms",
           "tags": {
+            "operation": "getQuote",
             "outcome": "unavailable",
             "provider": "squid",
           },
@@ -189,6 +354,7 @@ describe('requests', () => {
           "name": "funding_quote_provider_attempt_count",
           "tags": {
             "failure": "timeout",
+            "operation": "prepareTransfer",
             "outcome": "failed",
             "provider": "across",
           },
@@ -199,6 +365,7 @@ describe('requests', () => {
           "name": "funding_quote_provider_duration_ms",
           "tags": {
             "failure": "timeout",
+            "operation": "prepareTransfer",
             "outcome": "failed",
             "provider": "across",
           },
@@ -212,4 +379,77 @@ describe('requests', () => {
     )
     expect(flushes).toBe(1)
   })
+
+  test('records MPP relay outcomes without credential data', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge() {},
+      histogram(name, value, tags) {
+        events.push({ name, tags, type: 'histogram', value })
+      },
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 42,
+      level: 'info',
+      method: 'POST',
+      mpp: {
+        chainId: 4217,
+        errorCode: 'invalid_payment',
+        feePayer: true,
+        idempotency: 'claimed',
+        operation: 'broadcast',
+        outcome: 'failure',
+      },
+      path: '/v1/mpp/broadcast',
+      requestId: 'request_private',
+      route: '/v1/mpp/broadcast',
+      status: 200,
+    } satisfies Log.Entry)
+
+    const mpp = events.filter((event) => event.name.startsWith('mpp_relay_'))
+    expect(mpp).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "mpp_relay_operation_count",
+          "tags": {
+            "chain_id": "4217",
+            "error_code": "invalid_payment",
+            "fee_payer": true,
+            "operation": "broadcast",
+            "outcome": "failure",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "mpp_relay_operation_duration_ms",
+          "tags": {
+            "chain_id": "4217",
+            "error_code": "invalid_payment",
+            "fee_payer": true,
+            "operation": "broadcast",
+            "outcome": "failure",
+          },
+          "type": "histogram",
+          "value": 42,
+        },
+        {
+          "name": "mpp_relay_idempotency_claim_count",
+          "tags": {
+            "chain_id": "4217",
+            "outcome": "claimed",
+          },
+          "type": "count",
+          "value": 1,
+        },
+      ]
+    `)
+    expect(JSON.stringify(mpp)).not.toMatch(/request_private|credential|payload|signature/)
+  })
 })

package/src/internal/MetricSink.ts

@@ -84,12 +84,24 @@ export function requests(backend: Metrics): RequestSink {
       status: entry.status,
     })
     backend.histogram('http_response_duration_ms', entry.duration, tags)
+    if (entry.status >= 500)
+      backend.count('http_server_error_count', 1, {
+        ...tags,
+        ...(entry.errorCode === undefined ? {} : { error_code: entry.errorCode }),
+        status: entry.status,
+      })
 
-    if (entry.rpc)
+    if (entry.rpc) {
       backend.count('rpc_response_error_count', entry.rpc.errors, {
         ...tags,
         rpc_error_code: rpcErrorCode(entry.rpc.code),
       })
+      if ((entry.rpc.serverErrors ?? 0) > 0)
+        backend.count('rpc_response_server_error_count', entry.rpc.serverErrors ?? 0, {
+          ...tags,
+          rpc_error_code: rpcErrorCode(entry.rpc.code),
+        })
+    }
 
     if (entry.status === 429 || entry.errorCode === 'rate_limit_exceeded')
       backend.count('http_rate_limit_count', 1, {
@@ -104,6 +116,7 @@ export function requests(backend: Metrics): RequestSink {
     for (const attempt of entry.fundingProviderAttempts ?? []) {
       const tags_attempt = {
         ...(attempt.failure === undefined ? {} : { failure: attempt.failure }),
+        operation: attempt.operation,
         outcome: attempt.outcome,
         provider: attempt.id,
       }
@@ -111,6 +124,43 @@ export function requests(backend: Metrics): RequestSink {
       backend.histogram('funding_quote_provider_duration_ms', attempt.durationMs, tags_attempt)
     }
 
+    if (entry.fundingTransferCountFailed)
+      backend.count('funding_transfer_count_failure_count', 1, tags)
+
+    for (const failure of entry.providerFailures ?? (entry.provider ? [entry.provider] : []))
+      backend.count('upstream_failure_count', 1, {
+        ...tags,
+        chain_id: String(failure.chainId ?? 'unknown'),
+        failure: failure.failure,
+        operation: failure.operation,
+        provider: failure.id,
+        status: String(failure.status ?? 'unknown'),
+      })
+
+    if ((entry.sponsorship?.internalErrors ?? 0) > 0)
+      backend.count('sponsorship_internal_error_count', entry.sponsorship?.internalErrors ?? 0, {
+        ...tags,
+        chain_id: String(entry.sponsorship?.chainId ?? 'mixed'),
+        method: entry.sponsorship?.method ?? 'mixed',
+      })
+
+    if (entry.mpp) {
+      const tags_mpp = {
+        chain_id: String(entry.mpp.chainId),
+        ...(entry.mpp.errorCode === undefined ? {} : { error_code: entry.mpp.errorCode }),
+        fee_payer: entry.mpp.feePayer,
+        operation: entry.mpp.operation,
+        outcome: entry.mpp.outcome,
+      }
+      backend.count('mpp_relay_operation_count', 1, tags_mpp)
+      backend.histogram('mpp_relay_operation_duration_ms', entry.duration, tags_mpp)
+      if (entry.mpp.idempotency)
+        backend.count('mpp_relay_idempotency_claim_count', 1, {
+          chain_id: String(entry.mpp.chainId),
+          outcome: entry.mpp.idempotency,
+        })
+    }
+
     backend.flush()
   }
 }

package/src/internal/OpenApi.ts

@@ -64,6 +64,8 @@ export const errorCodes = {
     'address_invalid',
     'token_invalid',
     'symbol_invalid',
+    'swap_continuation_invalid',
+    'swap_provider_invalid',
     'quote_amount_out_of_range',
     'pair_invalid',
     'pair_id_invalid',
@@ -73,6 +75,7 @@ export const errorCodes = {
     'chain_id_invalid',
     'chain_id_unsupported',
     'destination_transition_invalid',
+    'sender_tag_invalid',
     'url_invalid',
     'api_key_malformed',
   ],

package/src/internal/Provider.test.ts

@@ -0,0 +1,17 @@
+import * as Provider from './Provider.js'
+
+describe('from', () => {
+  test.each(['exchange', 'funding'] as const)('preserves %s provider identity', (type) => {
+    expect(
+      Provider.from({
+        id: 'relay',
+        name: 'Relay',
+        type,
+      }),
+    ).toEqual({
+      id: 'relay',
+      name: 'Relay',
+      type,
+    })
+  })
+})

package/src/internal/Provider.ts

@@ -0,0 +1,17 @@
+/** A provider registered with the Tempo API app. */
+export type Provider<id extends string = string, type extends ProviderType = ProviderType> = {
+  /** Stable provider identifier. */
+  id: id
+  /** Human-readable provider name. */
+  name: string
+  /** Provider category used to select capability-specific implementations. */
+  type: type
+}
+
+/** Capability categories supported by registered providers. */
+export type ProviderType = 'exchange' | 'funding'
+
+/** Defines a provider while preserving its concrete identity and capabilities. */
+export function from<const provider extends Provider>(options: provider): provider {
+  return options
+}

package/src/internal/Schema.test.ts

@@ -32,3 +32,16 @@ describe('ChainIdQuery', () => {
     expect(Schema.ChainIdQuery.parse('42431')).toMatchInlineSnapshot(`42431`)
   })
 })
+
+describe('timestampBound', () => {
+  test('normalizes RFC 3339 offsets to UTC', () => {
+    const bound = Schema.timestampBound('swaps', 'from')
+
+    expect(bound.parse('2026-06-04T12:00:00+05:30')).toMatchInlineSnapshot(
+      `"2026-06-04T06:30:00.000Z"`,
+    )
+    expect(bound.parse('2026-06-04T12:00:00-05:00')).toMatchInlineSnapshot(
+      `"2026-06-04T17:00:00.000Z"`,
+    )
+  })
+})

package/src/internal/Schema.ts

@@ -25,25 +25,35 @@ const accountExample = '0xbe058e1c4df8a4366a387bf595b284246a93039e'
 // Pre-transform input for a 0x-prefixed 20-byte address. The OpenAPI example is
 // attached here (pre-transform) via `z.meta` so it surfaces on path/query
 // params; the lowercasing transform is applied after.
-const address = z.templateLiteral(['0x', z.string().check(z.regex(/^[0-9a-fA-F]{40}$/))])
+const addressInput = z.templateLiteral(['0x', z.string().check(z.regex(/^[0-9a-fA-F]{40}$/))])
 
 // TODO(ox/zod): replace with ox's `Address` zod schema once ox ships a `zod`
 // entrypoint, so the wire format stays in lockstep with ox/viem.
 /** Lowercase 0x-prefixed 20-byte account address. */
-export const Address = z
-  .pipe(
-    address.check(z.meta({ examples: [accountExample] })),
-    // `String.prototype.toLowerCase` widens its receiver from `Hex.Hex` to
-    // `string`. Cast the result back so the schema's inferred output keeps the
-    // hex-literal type — this is sound because lowercasing preserves both the
-    // `0x` prefix and the upstream regex constraint.
-    z.transform((value) => value.toLowerCase() as core_Hex.Hex),
-  )
-  .check(
-    z.describe(
-      'An account address — the `0x`-prefixed 20-byte identifier for a wallet or contract, returned in lowercase.',
-    ),
-  )
+export const Address = address(accountExample)
+
+/**
+ * Builds an `Address`-shaped schema with the given OpenAPI example. Use when a
+ * path or query parameter needs a more specific address example.
+ */
+export function address(example: core_Hex.Hex) {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(example))
+    throw new Error(`address example ${example} is not a 0x-prefixed 20-byte address`)
+  return z
+    .pipe(
+      addressInput.check(z.meta({ examples: [example] })),
+      // `String.prototype.toLowerCase` widens its receiver from `Hex.Hex` to
+      // `string`. Cast the result back so the schema's inferred output keeps the
+      // hex-literal type — this is sound because lowercasing preserves both the
+      // `0x` prefix and the upstream regex constraint.
+      z.transform((value) => value.toLowerCase() as core_Hex.Hex),
+    )
+    .check(
+      z.describe(
+        'An account address — the `0x`-prefixed 20-byte identifier for a wallet or contract, returned in lowercase.',
+      ),
+    )
+}
 
 /**
  * Lowercase 0x-prefixed 20-byte TIP-20 token contract address. The OpenAPI
@@ -70,7 +80,7 @@ export function tokenAddress(example: core_Hex.Hex) {
     )
   return z
     .pipe(
-      address.check(z.meta({ examples: [example] })),
+      addressInput.check(z.meta({ examples: [example] })),
       z.transform((value) => value.toLowerCase() as core_Hex.Hex),
     )
     .check(
@@ -335,7 +345,7 @@ export const Limit = z
     z.meta({ examples: [10] }),
   )
 
-/** Valuation denomination query parameter shared across valuation-bearing endpoints. */
+/** Valuation currency query parameter shared across valuation-bearing endpoints. */
 export const Denomination = z
   .optional(
     z.pipe(
@@ -495,16 +505,23 @@ export function blockNumberBound(noun: string, bound: 'from' | 'to') {
 
 /**
  * Optional inclusive ISO-8601 timestamp bound query parameter (`timestamp.from`
- * / `timestamp.to`). `noun` is the resource being listed (e.g. `transfers`).
+ * / `timestamp.to`), normalized to UTC. `noun` is the listed resource.
  */
 export function timestampBound(noun: string, bound: 'from' | 'to') {
   const direction = bound === 'from' ? 'at or after' : 'at or before'
-  return z.optional(z.iso.datetime({ offset: true })).check(
-    z.describe(`Only include ${noun} ${direction} this ISO 8601 timestamp.`),
-    z.meta({
-      examples: [bound === 'from' ? '2024-01-01T00:00:00Z' : '2024-12-31T23:59:59Z'],
-    }),
-  )
+  return z
+    .optional(
+      z.pipe(
+        z.iso.datetime({ offset: true }),
+        z.transform((value) => new Date(value).toISOString()),
+      ),
+    )
+    .check(
+      z.describe(`Only include ${noun} ${direction} this ISO 8601 timestamp.`),
+      z.meta({
+        examples: [bound === 'from' ? '2024-01-01T00:00:00Z' : '2024-12-31T23:59:59Z'],
+      }),
+    )
 }
 
 /**

package/src/internal/Store.test.ts

@@ -142,6 +142,31 @@ describe('update', () => {
   })
 })
 
+describe('change', () => {
+  test('applies typed set, no-op, and delete transitions', async () => {
+    const store = Store.memory()
+
+    const first = await Store.change(store, 'value', (current) => ({
+      op: 'set',
+      result: current,
+      value: 'first',
+    }))
+    const second = await Store.change(store, 'value', (current) => ({
+      op: 'noop',
+      result: current,
+    }))
+    await Store.change(store, 'value', () => ({ op: 'delete', result: undefined }))
+
+    expect({ first, second, value: await store.get('value') }).toMatchInlineSnapshot(`
+      {
+        "first": null,
+        "second": "first",
+        "value": null,
+      }
+    `)
+  })
+})
+
 describe('memory', () => {
   test('swaps atomically against the expected value', async () => {
     const store = Store.memory()

package/src/internal/Store.ts

@@ -212,6 +212,52 @@ export declare namespace update {
   }
 }
 
+/** Atomically applies a typed state transition without a get-and-put fallback. */
+export async function change<result>(
+  state: State,
+  key: string,
+  fn: (current: null | string) => Change<string, result>,
+  options: change.Options = {},
+): Promise<result> {
+  const { attempts = updateAttempts, ...put } = options
+  const swap = state.swap
+  if (!swap) throw new AtomicStateRequiredError()
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const current = await state.get(key)
+    const next = fn(current)
+    if (next.op === 'noop') return next.result
+    if (next.op === 'delete') {
+      if (!state.deleteIf) throw new AtomicDeleteRequiredError()
+      if (await state.deleteIf(key, current)) return next.result
+      continue
+    }
+    if (await swap(key, current, next.value, put)) return next.result
+  }
+  throw new UpdateContentionError(key, attempts)
+}
+
+export declare namespace change {
+  /** Options for one atomic state transition. */
+  type Options = update.Options
+}
+
+class AtomicStateRequiredError extends Error {
+  override name = 'Store.AtomicStateRequiredError'
+
+  constructor() {
+    super('Atomic state requires compare-and-swap support.')
+  }
+}
+
+class AtomicDeleteRequiredError extends Error {
+  override name = 'Store.AtomicDeleteRequiredError'
+
+  constructor() {
+    super('Atomic deletion requires compare-and-delete support.')
+  }
+}
+
 /** Creates an in-memory store with TTL support. */
 export function memory(options: memory.Options = {}): State {
   // Track value + optional expiration in one cell so `get` can lazily evict