tapimo 0.11.0 → 0.13.0

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

@@ -69,14 +69,16 @@ export namespace schema {
   /** A transfer token reference with RPC metadata. Inlined to avoid the `transfers`/`tokens` module cycle. */
   export const SourceToken = z
     .object({
-      address: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+      address: Schema.tokenAddress(Tokens.tokenExample.address).check(
+        z.describe('The TIP-20 token contract address on Tempo.'),
+      ),
       currency: z
         .string()
         .check(
           z.describe(
             'The currency label for this token, such as `USD` for USD-denominated stablecoins.',
           ),
-          z.meta({ examples: ['USD'] }),
+          z.meta({ examples: [Tokens.tokenExample.currency] }),
         ),
       decimals: z
         .number()
@@ -85,24 +87,25 @@ export namespace schema {
           z.describe(
             'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
           ),
-          z.meta({ examples: [6] }),
+          z.meta({ examples: [Tokens.tokenExample.decimals] }),
         ),
       logoUri: z.optional(z.string()).check(
         z.describe('A URL for the token’s logo image, returned with `include=token.logoUri`.'),
         z.meta({
-          examples: [
-            'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
-          ],
+          examples: [Tokens.tokenExample.logoUri],
         }),
       ),
       name: z
         .string()
-        .check(z.describe('The token’s human-readable name.'), z.meta({ examples: ['USD Coin'] })),
+        .check(
+          z.describe('The token’s human-readable name.'),
+          z.meta({ examples: [Tokens.tokenExample.name] }),
+        ),
       symbol: z
         .string()
         .check(
           z.describe('The short ticker symbol wallets and apps show for this token.'),
-          z.meta({ examples: ['USDC'] }),
+          z.meta({ examples: [Tokens.tokenExample.symbol] }),
         ),
       verified: z
         .optional(z.boolean())
@@ -119,17 +122,23 @@ export namespace schema {
       ),
     )
 
-  /** A token amount carrying its nominal value in the requested denomination. */
-  const ValuedAmount = z.extend(Schema.TokenAmount, {
-    valuation: z
-      .optional(z.nullable(Valuation.schema.Value))
-      .check(
-        z.describe(
-          'The amount’s nominal value in the requested `valuation.currency`. `null` when the token is ' +
-            'unverified, its display currency has no rate, or rates were unavailable.',
+  const transferToken = OpenApi.component(SourceToken, 'TokenTransferToken')
+
+  const ValuedAmount = Schema.describe(
+    z.extend(Schema.TokenAmount, {
+      valuation: z
+        .optional(z.nullable(Valuation.schema.Value))
+        .check(
+          z.describe(
+            'The amount’s nominal value in the requested `valuation.currency`. `null` when the token is ' +
+              'unverified, its display currency has no rate, or rates were unavailable.',
+          ),
         ),
-      ),
-  })
+    }),
+    'A token amount carrying its nominal value in the requested denomination.',
+  )
+
+  const valuedTokenAmount = OpenApi.component(ValuedAmount, 'ValuedTokenAmount')
 
   /**
    * Filter predicates shared verbatim by the `GET /transfers` list query
@@ -240,14 +249,14 @@ export namespace schema {
             z.meta({ examples: [23456789] }),
           ),
         destinationAmount: z
-          .optional(ValuedAmount)
+          .optional(valuedTokenAmount)
           .check(
             z.describe(
               'Amount delivered to the recipient for a cross-token transfer. Omitted with `destinationToken` for a same-token transfer.',
             ),
           ),
         destinationToken: z
-          .optional(schema.SourceToken)
+          .optional(transferToken)
           .check(
             z.describe(
               'The token delivered to the recipient when it differs from `sourceToken`. Omitted for same-token transfers and returned only with `include=crossToken`.',
@@ -281,8 +290,8 @@ export namespace schema {
           z.describe('The account address that received the tokens.'),
         ),
         sender: Schema.Address.check(z.describe('The account address that sent the tokens.')),
-        sourceAmount: ValuedAmount.check(z.describe('Amount associated with `sourceToken`.')),
-        sourceToken: schema.SourceToken.check(z.describe('The token that moved.')),
+        sourceAmount: valuedTokenAmount,
+        sourceToken: transferToken.check(z.describe('The token that moved.')),
         timestamp: z.iso
           .datetime()
           .check(
@@ -307,6 +316,8 @@ export namespace schema {
         ),
       )
 
+    const transfer = OpenApi.component(Transfer, 'TokenTransfer')
+
     /** Page-level resources: opt-in counts plus valuation rate provenance. */
     export const Meta = z
       .object({
@@ -323,19 +334,26 @@ export namespace schema {
       })
       .check(z.describe('Page-level resources attached to this response.'))
 
+    const meta = OpenApi.component(Meta, 'TokenTransferListMeta')
+
     /** Page of TIP-20 token transfers across the chain, ordered by block then log index. */
-    export const Response = z
-      .object({
-        data: z.array(Transfer).check(z.describe('The transfers in this page.')),
-        // Response-wide `meta` carries the opt-in capped total count
-        // (`include=totalCount`) and valuation rate provenance; per-row embeds
-        // (`memo`, `token`) attach to each `data` item, not here.
-        meta: z
-          .optional(Meta)
-          .check(z.describe('Page-level resources: opt-in counts and valuation rate provenance.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of TIP-20 token transfer events across the chain.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(transfer).check(z.describe('The transfers in this page.')),
+          // Response-wide `meta` carries the opt-in capped total count
+          // (`include=totalCount`) and valuation rate provenance; per-row embeds
+          // (`memo`, `token`) attach to each `data` item, not here.
+          meta: z
+            .optional(meta)
+            .check(
+              z.describe('Page-level resources: opt-in counts and valuation rate provenance.'),
+            ),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of TIP-20 token transfer events across the chain.')),
+      'TokenTransferList',
+    )
   }
 }
 
@@ -361,7 +379,10 @@ export function transfers(options: transfers.Options = {}) {
       description: 'List token transfer events across Tempo.',
       operationId: 'getTransfers',
       responses: OpenApi.responses({
-        errors: { 502: 'The indexer or Tempo RPC could not serve this request.' },
+        errors: {
+          400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
+          502: 'The indexer or Tempo RPC could not serve this request.',
+        },
         success: {
           description: 'A page of token transfer events.',
           schema: schema.getTransfers.Response,
@@ -659,7 +680,7 @@ export function transfers(options: transfers.Options = {}) {
       } catch (cause) {
         if (cause instanceof Valuation.UnsupportedDenominationError)
           return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
-        return Response.upstream(c, cause)
+        return Response.upstream(c, cause, { page: options.page })
       }
     },
   )

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

@@ -23,47 +23,55 @@ const tokenReadChunkSize = 20
 /** Zod schemas owned by the valuation handlers. */
 export namespace schema {
   /** A holding's nominal value in the requested denomination. */
-  export const Value = z
-    .object({
-      amount: z
-        .string()
-        .check(
-          z.regex(/^\d+(\.\d+)?$/),
-          z.describe('The holding’s nominal value, as a decimal string in `currency`.'),
-          z.meta({ examples: ['1.50'] }),
-        ),
-      currency: z
-        .string()
-        .check(
-          z.describe('The denomination currency of this value.'),
-          z.meta({ examples: ['USD'] }),
-        ),
-    })
-    .check(z.describe('The holding’s nominal value in the requested denomination.'))
+  export const Value = OpenApi.component(
+    z
+      .object({
+        amount: z
+          .string()
+          .check(
+            z.regex(/^\d+(\.\d+)?$/),
+            z.describe('The holding’s nominal value, as a decimal string in `currency`.'),
+            z.meta({ examples: ['1.50'] }),
+          ),
+        currency: z
+          .string()
+          .check(
+            z.describe('The denomination currency of this value.'),
+            z.meta({ examples: ['USD'] }),
+          ),
+      })
+      .check(z.describe('The holding’s nominal value in the requested denomination.')),
+    'ValuationValue',
+  )
 
   /** Rate provenance for a converted valuation. */
-  export const Pricing = z
-    .object({
-      asOf: z.iso
-        .datetime()
-        .check(
-          z.describe('Publication date of the rate set as an ISO 8601 timestamp.'),
-          z.meta({ examples: ['2026-07-20T00:00:00.000Z'] }),
-        ),
-      basis: z
-        .literal('nominal')
-        .check(
-          z.describe('Valuation basis: one token unit counts as one unit of its display currency.'),
-          z.meta({ examples: ['nominal'] }),
-        ),
-      source: z
-        .string()
-        .check(
-          z.describe('FX rate oracle that supplied the conversion rates.'),
-          z.meta({ examples: ['ecb'] }),
-        ),
-    })
-    .check(z.describe('Rate provenance for a converted valuation.'))
+  export const Pricing = OpenApi.component(
+    z
+      .object({
+        asOf: z.iso
+          .datetime()
+          .check(
+            z.describe('Publication date of the rate set as an ISO 8601 timestamp.'),
+            z.meta({ examples: ['2026-07-20T00:00:00.000Z'] }),
+          ),
+        basis: z
+          .literal('nominal')
+          .check(
+            z.describe(
+              'Valuation basis: one token unit counts as one unit of its display currency.',
+            ),
+            z.meta({ examples: ['nominal'] }),
+          ),
+        source: z
+          .string()
+          .check(
+            z.describe('FX rate oracle that supplied the conversion rates.'),
+            z.meta({ examples: ['ecb'] }),
+          ),
+      })
+      .check(z.describe('Rate provenance for a converted valuation.')),
+    'ValuationPricing',
+  )
 
   /** Schemas for the getAddressValuation operation. */
   export namespace getAddressValuation {
@@ -89,47 +97,50 @@ export namespace schema {
       .check(z.describe('Query parameters for valuing an account’s verified holdings.'))
 
     /** The nominal valuation of an account's verified holdings. */
-    export const Response = z
-      .object({
-        address: Schema.Address.check(z.describe('The account address this valuation covers.')),
-        amount: z
-          .string()
-          .check(
-            z.regex(/^\d+(\.\d+)?$/),
-            z.describe(
-              'The total value of the account’s verified holdings, as a decimal string in `currency`.',
+    export const Response = OpenApi.component(
+      z
+        .object({
+          address: Schema.Address.check(z.describe('The account address this valuation covers.')),
+          amount: z
+            .string()
+            .check(
+              z.regex(/^\d+(\.\d+)?$/),
+              z.describe(
+                'The total value of the account’s verified holdings, as a decimal string in `currency`.',
+              ),
+              z.meta({ examples: ['160.50'] }),
             ),
-            z.meta({ examples: ['160.50'] }),
-          ),
-        currency: z
-          .string()
-          .check(
-            z.describe('The denomination currency of `amount`.'),
-            z.meta({ examples: ['USD'] }),
-          ),
-        id: z
-          .string()
-          .check(
-            z.describe('A stable resource ID for this valuation, equal to the account address.'),
-            z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
-          ),
-        pricing: z
-          .nullable(Pricing)
-          .check(
-            z.describe(
-              'Rate provenance, or `null` when every valued holding was already denominated in `currency`.',
+          currency: z
+            .string()
+            .check(
+              z.describe('The denomination currency of `amount`.'),
+              z.meta({ examples: ['USD'] }),
             ),
-          ),
-        unpriced: z
-          .array(z.string())
-          .check(
-            z.describe(
-              'Display currencies excluded from `amount` because the FX oracle has no rate for them.',
+          id: z
+            .string()
+            .check(
+              z.describe('A stable resource ID for this valuation, equal to the account address.'),
+              z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
             ),
-            z.meta({ examples: [['BTC']] }),
-          ),
-      })
-      .check(z.describe('The nominal valuation of an account’s verified token holdings.'))
+          pricing: z
+            .nullable(Pricing)
+            .check(
+              z.describe(
+                'Rate provenance, or `null` when every valued holding was already denominated in `currency`.',
+              ),
+            ),
+          unpriced: z
+            .array(z.string())
+            .check(
+              z.describe(
+                'Display currencies excluded from `amount` because the FX oracle has no rate for them.',
+              ),
+              z.meta({ examples: [['BTC']] }),
+            ),
+        })
+        .check(z.describe('The nominal valuation of an account’s verified token holdings.')),
+      'AddressValuation',
+    )
   }
 }
 
@@ -155,7 +166,12 @@ export function addresses(options: addresses.Options = {}) {
         'Values every verified TIP-20 token an account holds as one unit of its display currency, converts each currency into the requested denomination using the configured FX rates, and returns the total.',
       operationId: 'getAddressValuation',
       responses: OpenApi.responses({
-        errors: { 502: 'Could not read balances or exchange rates from an upstream service.' },
+        errors: {
+          400: {
+            codes: ['address_invalid', 'chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+          },
+          502: 'Could not read balances or exchange rates from an upstream service.',
+        },
         success: {
           description: 'The valuation of this account’s verified holdings.',
           schema: schema.getAddressValuation.Response,

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

@@ -544,7 +544,9 @@ export namespace schema {
         .check(
           z.int(),
           z.nonnegative(),
-          z.describe('Number of delivery failures in a row for this subscription.'),
+          z.describe(
+            'Number of delivery failures in a row for this subscription, capped at the auto-disable threshold.',
+          ),
           z.meta({ examples: [0] }),
         ),
       filters: Filters.check(
@@ -560,7 +562,9 @@ export namespace schema {
       lastDeliveryAt: z
         .optional(z.iso.datetime())
         .check(
-          z.describe('When Tempo last delivered an event successfully, as an ISO 8601 timestamp.'),
+          z.describe(
+            'When Tempo last delivered an event successfully, as an ISO 8601 timestamp. Refreshed at most once per minute during sustained delivery.',
+          ),
           z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
         ),
       status: Status.check(z.meta({ examples: ['active'] })),

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

@@ -33,7 +33,19 @@ const withdrawalProcessedData = AbiParameters.from(['address', 'uint128', 'bool'
 const recipient = Schema.Address.parse('0xbe058e1c4df8a4366a387bf595b284246a93039e')
 const token = Schema.Address.parse('0x20c0000000000000000000000000000000000000')
 
+type OpenApiErrorSchema = {
+  $ref?: string
+  properties?: {
+    error?: {
+      properties?: {
+        code?: { enum?: readonly string[] }
+      }
+    }
+  }
+}
+
 type OpenApiDocument = {
+  components?: { schemas?: Record<string, OpenApiErrorSchema> }
   paths: {
     '/v1/zones/withdrawals/{senderTag}'?: {
       get?: {
@@ -63,15 +75,7 @@ type OpenApiDocument = {
           400?: {
             content?: {
               'application/json'?: {
-                schema?: {
-                  properties?: {
-                    error?: {
-                      properties?: {
-                        code?: { enum?: readonly string[] }
-                      }
-                    }
-                  }
-                }
+                schema?: OpenApiErrorSchema
               }
             }
           }
@@ -331,7 +335,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
     expect(response.status).toBe(403)
     expect(body.error.code).toBe('api_key_forbidden')
     expect(body.error.message).toBe(
-      `Chain id ${runtime.zone.chainId} is a zone. Use an API key granting \`zone:${runtime.zone.chainId}:read\` or \`zone:${runtime.zone.chainId}:write\`.`,
+      `Chain ID ${runtime.zone.chainId} is a Zone. Use an API key granting \`zone:${runtime.zone.chainId}:read\` or \`zone:${runtime.zone.chainId}:write\`.`,
     )
   })
 
@@ -419,7 +423,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
         },
         {
           "examples": [
-            1424310001,
+            1424310003,
           ],
           "name": "chainId",
           "required": true,
@@ -428,11 +432,13 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
     `)
 
     const response = operation.responses?.[200]?.content?.['application/json']
+    const errorSchema = operation.responses?.[400]?.content?.['application/json']?.schema
+    const errorSchemaName = errorSchema?.$ref?.split('/').at(-1)
+    const errorSchema_resolved = errorSchemaName
+      ? document.components?.schemas?.[errorSchemaName]
+      : errorSchema
     expect(Object.keys(response?.examples ?? {}).sort()).toEqual(['empty', 'processed'])
-    expect(
-      operation.responses?.[400]?.content?.['application/json']?.schema?.properties?.error
-        ?.properties?.code?.enum,
-    ).toEqual([
+    expect(errorSchema_resolved?.properties?.error?.properties?.code?.enum).toEqual([
       'api_key_malformed',
       'chain_id_invalid',
       'chain_id_unsupported',

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

@@ -43,7 +43,7 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainId.check(
           z.describe('The chain id of the Zone where the withdrawal originated.'),
-          z.meta({ examples: [1_424_310_001] }),
+          z.meta({ examples: [1_424_310_003] }),
         ),
       })
       .check(z.describe('Query parameters used to select the originating Zone.'))