tapimo 0.11.0 → 0.13.0

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

@@ -4,6 +4,7 @@ import { type Address, ContractFunctionExecutionError } from 'viem'
 import { Abis } from 'viem/tempo'
 import * as z from 'zod/mini'
 
+import * as Assets from '../../../Assets.js'
 import type * as App from '../../../App.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
@@ -20,6 +21,26 @@ import * as Value from '../../../internal/Value.js'
 import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 import * as Transactions from './transactions.js'
 
+/** Mainnet chain id used by the coherent token OpenAPI example. */
+export const tokenExampleChainId = 4217
+
+/** Coherent mainnet token metadata used by generated OpenAPI examples. */
+export const tokenExample = {
+  address: '0x20c000000000000000000000b9537d11c60e8b50',
+  currency: 'USD',
+  decimals: 6,
+  id: '0x20c000000000000000000000b9537d11c60e8b50',
+  logoUri: Assets.url({
+    chainId: tokenExampleChainId,
+    origin: 'https://api.tempo.xyz',
+    path: 'icons/0x20c000000000000000000000b9537d11c60e8b50',
+  }),
+  name: 'Bridged USDC (Stargate)',
+  symbol: 'USDC.e',
+  totalSupply: '10850791186630',
+  verified: true,
+} as const
+
 const tokenCreatedSignature =
   'event TokenCreated(address indexed token, string name, string symbol, string currency, address quoteToken, address admin, bytes32 salt)'
 
@@ -53,7 +74,9 @@ export namespace schema {
     /** Path parameters for token metadata requests. */
     export const Params = z
       .object({
-        token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+        token: Schema.tokenAddress(tokenExample.address).check(
+          z.describe('The TIP-20 token contract address on Tempo.'),
+        ),
       })
       .check(z.describe('Path parameters for looking up one token’s metadata.'))
 
@@ -84,139 +107,140 @@ export namespace schema {
       .check(z.describe('Query parameters for looking up one token’s metadata.'))
 
     /** TIP-20 token metadata returned by token endpoints. */
-    export const Response = Schema.describe(
-      z.object({
-        address: Schema.TokenAddress.check(
-          z.describe('The TIP-20 token contract address on Tempo.'),
-        ),
-        admin: z
-          .optional(Schema.Address)
-          .check(
-            z.describe(
-              'Token admin from the onchain `TokenCreated` event, present when requested ' +
-                'via `include=admin` and indexed data is available.',
-            ),
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          address: Schema.tokenAddress(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.',
+          admin: z
+            .optional(Schema.Address)
+            .check(
+              z.describe(
+                'Token admin from the onchain `TokenCreated` event, present when requested ' +
+                  'via `include=admin` and indexed data is available.',
+              ),
             ),
-            z.meta({ examples: ['USD'] }),
-          ),
-        createdAt: z
-          .optional(z.iso.datetime())
-          .check(
-            z.describe(
-              'Token creation timestamp, present when requested via `include=createdAt` ' +
-                'and indexed data is available.',
+          currency: z
+            .string()
+            .check(
+              z.describe(
+                'The currency label for this token, such as `USD` for USD-denominated stablecoins.',
+              ),
+              z.meta({ examples: [tokenExample.currency] }),
             ),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-          ),
-        decimals: z
-          .number()
-          .check(
-            z.int(),
-            z.nonnegative(),
-            z.describe(
-              'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
+          createdAt: z
+            .optional(z.iso.datetime())
+            .check(
+              z.describe(
+                'Token creation timestamp, present when requested via `include=createdAt` ' +
+                  'and indexed data is available.',
+              ),
+              z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
             ),
-            z.meta({ examples: [6] }),
-          ),
-        holderCount: z
-          .optional(z.number().check(z.int(), z.nonnegative()))
-          .check(
-            z.describe(
-              'The number of accounts that currently hold a positive balance of this token, when indexed holder data is available.',
+          decimals: z
+            .number()
+            .check(
+              z.int(),
+              z.nonnegative(),
+              z.describe(
+                'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
+              ),
+              z.meta({ examples: [tokenExample.decimals] }),
             ),
-            z.meta({ examples: [1234] }),
-          ),
-        id: z
-          .string()
-          .check(
-            z.describe('A stable resource ID for this token, equal to its contract address.'),
-            z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
-          ),
-        logoUri: z.optional(z.string()).check(
-          z.describe('A URL for the token’s logo image, when one is available.'),
-          z.meta({
-            examples: [
-              'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
-            ],
-          }),
-        ),
-        name: z
-          .string()
-          .check(
-            z.describe('The token’s human-readable name.'),
-            z.meta({ examples: ['USD Coin'] }),
-          ),
-        quoteToken: z
-          .optional(Schema.Address)
-          .check(
-            z.describe(
-              'Quote token from the onchain `TokenCreated` event, present when requested ' +
-                'via `include=quoteToken` and indexed data is available.',
+          holderCount: z
+            .optional(z.number().check(z.int(), z.nonnegative()))
+            .check(
+              z.describe(
+                'The number of accounts that currently hold a positive balance of this token, when indexed holder data is available.',
+              ),
+              z.meta({ examples: [1234] }),
             ),
-          ),
-        symbol: z
-          .string()
-          .check(
-            z.describe('The short ticker symbol wallets and apps show for this token.'),
-            z.meta({ examples: ['USDC'] }),
-          ),
-        totalSupply: z
-          .optional(z.string().check(z.regex(/^\d+$/)))
-          .check(
-            z.describe(
-              'The token’s total supply as a decimal string in the smallest unit, so large values keep full precision.',
+          id: z
+            .string()
+            .check(
+              z.describe('A stable resource ID for this token, equal to its contract address.'),
+              z.meta({ examples: [tokenExample.id] }),
             ),
-            z.meta({ examples: ['1000000000000'] }),
+          logoUri: z.optional(z.string()).check(
+            z.describe('A URL for the token’s logo image, when one is available.'),
+            z.meta({
+              examples: [tokenExample.logoUri],
+            }),
           ),
-        transferStats: z
-          .optional(
-            z.object({
-              count: z
-                .number()
-                .check(
-                  z.int(),
-                  z.nonnegative(),
-                  z.describe('The total number of `Transfer` events emitted by this token.'),
-                  z.meta({ examples: [12345] }),
-                ),
-              firstAt: z
-                .nullable(z.iso.datetime())
-                .check(
-                  z.describe(
-                    'The time of this token’s first `Transfer` event, or `null` if no transfers exist.',
+          name: z
+            .string()
+            .check(
+              z.describe('The token’s human-readable name.'),
+              z.meta({ examples: [tokenExample.name] }),
+            ),
+          quoteToken: z
+            .optional(Schema.Address)
+            .check(
+              z.describe(
+                'Quote token from the onchain `TokenCreated` event, present when requested ' +
+                  'via `include=quoteToken` and indexed data is available.',
+              ),
+            ),
+          symbol: z
+            .string()
+            .check(
+              z.describe('The short ticker symbol wallets and apps show for this token.'),
+              z.meta({ examples: [tokenExample.symbol] }),
+            ),
+          totalSupply: z
+            .optional(z.string().check(z.regex(/^\d+$/)))
+            .check(
+              z.describe(
+                'The token’s total supply as a decimal string in the smallest unit, so large values keep full precision.',
+              ),
+              z.meta({ examples: [tokenExample.totalSupply] }),
+            ),
+          transferStats: z
+            .optional(
+              z.object({
+                count: z
+                  .number()
+                  .check(
+                    z.int(),
+                    z.nonnegative(),
+                    z.describe('The total number of `Transfer` events emitted by this token.'),
+                    z.meta({ examples: [12345] }),
                   ),
-                  z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-                ),
-              lastAt: z
-                .nullable(z.iso.datetime())
-                .check(
-                  z.describe(
-                    'The time of this token’s most recent `Transfer` event, or `null` if no transfers exist.',
+                firstAt: z
+                  .nullable(z.iso.datetime())
+                  .check(
+                    z.describe(
+                      'The time of this token’s first `Transfer` event, or `null` if no transfers exist.',
+                    ),
+                    z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
                   ),
-                  z.meta({ examples: ['2024-06-01T12:00:00Z'] }),
-                ),
-            }),
-          )
-          .check(
-            z.describe(
-              'Lifetime `Transfer` event statistics, present when requested via ' +
-                '`include=transferStats` and indexed data is available.',
+                lastAt: z
+                  .nullable(z.iso.datetime())
+                  .check(
+                    z.describe(
+                      'The time of this token’s most recent `Transfer` event, or `null` if no transfers exist.',
+                    ),
+                    z.meta({ examples: ['2024-06-01T12:00:00Z'] }),
+                  ),
+              }),
+            )
+            .check(
+              z.describe(
+                'Lifetime `Transfer` event statistics, present when requested via ' +
+                  '`include=transferStats` and indexed data is available.',
+              ),
             ),
-          ),
-        verified: z
-          .boolean()
-          .check(
-            z.describe('Whether this token is in Tempo’s curated verified token list.'),
-            z.meta({ examples: [true] }),
-          ),
-      }),
-      'Token metadata for a TIP-20 token, including name, symbol, decimals, supply, and optional indexed details.',
+          verified: z
+            .boolean()
+            .check(
+              z.describe('Whether this token is in Tempo’s curated verified token list.'),
+              z.meta({ examples: [tokenExample.verified] }),
+            ),
+        }),
+        'Token metadata for a TIP-20 token, including name, symbol, decimals, supply, and optional indexed details.',
+      ),
+      'Token',
     )
   }
 
@@ -226,24 +250,30 @@ export namespace schema {
    * temporal facts (`totalSupply`, `holderCount`, `createdAt`) belong on the
    * token detail endpoint, not in feed rows.
    */
-  export const Token = Schema.describe(
-    z.pick(getToken.Response, {
-      address: true,
-      currency: true,
-      decimals: true,
-      id: true,
-      logoUri: true,
-      name: true,
-      symbol: true,
-      verified: true,
-    }),
-    'A compact TIP-20 token reference with identity and display fields only.',
+  export const Token = OpenApi.component(
+    Schema.describe(
+      z.pick(getToken.Response, {
+        address: true,
+        currency: true,
+        decimals: true,
+        id: true,
+        logoUri: true,
+        name: true,
+        symbol: true,
+        verified: true,
+      }),
+      'A compact TIP-20 token reference with identity and display fields only.',
+    ),
+    'TokenReference',
   )
 
   /** RPC token metadata embedded in resources, with optional curated fields. */
-  export const TokenReference = Schema.describe(
-    z.partial(z.omit(Token, { id: true }), { logoUri: true, verified: true }),
-    'A compact TIP-20 token reference with RPC metadata and optional enrichments.',
+  export const TokenReference = OpenApi.component(
+    Schema.describe(
+      z.partial(z.omit(Token, { id: true }), { logoUri: true, verified: true }),
+      'A compact TIP-20 token reference with RPC metadata and optional enrichments.',
+    ),
+    'RpcTokenReference',
   )
 
   /** Schemas for the getTokenBySymbol operation. */
@@ -352,12 +382,15 @@ export namespace schema {
       .check(...Schema.pageChecks(), z.describe('Query parameters for listing TIP-20 tokens.'))
 
     /** Page of TIP-20 tokens. */
-    export const Response = z
-      .object({
-        data: z.array(getToken.Response).check(z.describe('The tokens in this page.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of TIP-20 tokens on Tempo.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(getToken.Response).check(z.describe('The tokens in this page.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of TIP-20 tokens on Tempo.')),
+      'TokenList',
+    )
   }
 
   /** Schemas for the getTokenHolders operation. */
@@ -396,64 +429,73 @@ export namespace schema {
       .check(...Schema.pageChecks(), z.describe('Query parameters for listing a token’s holders.'))
 
     /** A single TIP-20 token holder. */
-    export const Holder = z
-      .object({
-        address: Schema.Address.check(z.describe('The account address that holds this token.')),
-        balance: z
-          .string()
-          .check(
-            z.regex(/^\d+$/),
-            z.describe(
-              'A non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token.',
+    export const Holder = OpenApi.component(
+      z
+        .object({
+          address: Schema.Address.check(z.describe('The account address that holds this token.')),
+          balance: z
+            .string()
+            .check(
+              z.regex(/^\d+$/),
+              z.describe(
+                'A non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token.',
+              ),
+              z.meta({ examples: ['1000000'] }),
             ),
-            z.meta({ examples: ['1000000'] }),
-          ),
-        id: z
-          .string()
-          .check(
-            z.describe('A stable resource ID for this holder, equal to the holder address.'),
-            z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
-          ),
-      })
-      .check(z.describe('One account holding a positive balance of this TIP-20 token.'))
+          id: z
+            .string()
+            .check(
+              z.describe('A stable resource ID for this holder, equal to the holder address.'),
+              z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
+            ),
+        })
+        .check(z.describe('One account holding a positive balance of this TIP-20 token.')),
+      'TokenHolder',
+    )
 
     /** Resources embedded on demand via `include`. */
-    export const Meta = z
-      .object({
-        totalCountCapped: z
-          .optional(Schema.TotalCountCapped)
-          .check(
-            z.describe(
-              'Whether `totalCount` reached the API count cap; holder counts are exact here.',
+    export const Meta = OpenApi.component(
+      z
+        .object({
+          totalCountCapped: z
+            .optional(Schema.TotalCountCapped)
+            .check(
+              z.describe(
+                'Whether `totalCount` reached the API count cap; holder counts are exact here.',
+              ),
             ),
-          ),
-        token: z
-          .optional(Token)
-          .check(
-            z.describe('A compact token reference, returned when you request `include=token`.'),
-          ),
-        totalCount: z
-          .optional(Schema.TotalCount)
-          .check(
-            z.describe(
-              'The total number of token holders, returned when you request `include=totalCount`.',
+          token: z
+            .optional(Token)
+            .check(
+              z.describe('A compact token reference, returned when you request `include=token`.'),
             ),
-          ),
-      })
-      .check(z.describe('Extra resources included because you requested them with `include`.'))
+          totalCount: z
+            .optional(Schema.TotalCount)
+            .check(
+              z.describe(
+                'The total number of token holders, returned when you request `include=totalCount`.',
+              ),
+            ),
+        })
+        .check(z.describe('Extra resources included because you requested them with `include`.')),
+      'TokenHolderListMeta',
+    )
 
     /** Page of TIP-20 token holders, ordered by balance descending. */
-    export const Response = z
-      .object({
-        data: z
-          .array(Holder)
-          .check(
-            z.describe('The holders in this page, ordered by balance from highest to lowest.'),
-          ),
-        meta: z.optional(Meta).check(z.describe('Extra resources you requested with `include`.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of accounts holding this TIP-20 token.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Holder)
+            .check(
+              z.describe('The holders in this page, ordered by balance from highest to lowest.'),
+            ),
+          meta: z.optional(Meta).check(z.describe('Extra resources you requested with `include`.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of accounts holding this TIP-20 token.')),
+      'TokenHolderList',
+    )
   }
 
   /** Schemas for the getTokenTransactions operation. */
@@ -510,29 +552,32 @@ export namespace schema {
       )
 
     /** Resources embedded on demand via `include`. */
-    export const Meta = z
-      .object({
-        totalCountCapped: z
-          .optional(Schema.TotalCountCapped)
-          .check(
-            z.describe(
-              'Whether `totalCount` reached the API count cap; when `true`, treat the count as a lower bound.',
+    export const Meta = OpenApi.component(
+      z
+        .object({
+          totalCountCapped: z
+            .optional(Schema.TotalCountCapped)
+            .check(
+              z.describe(
+                'Whether `totalCount` reached the API count cap; when `true`, treat the count as a lower bound.',
+              ),
             ),
-          ),
-        token: z
-          .optional(Token)
-          .check(
-            z.describe('A compact token reference, returned when you request `include=token`.'),
-          ),
-        totalCount: z
-          .optional(Schema.TotalCount)
-          .check(
-            z.describe(
-              'The capped total number of matching transactions, returned when you request `include=totalCount`.',
+          token: z
+            .optional(Token)
+            .check(
+              z.describe('A compact token reference, returned when you request `include=token`.'),
             ),
-          ),
-      })
-      .check(z.describe('Extra resources included because you requested them with `include`.'))
+          totalCount: z
+            .optional(Schema.TotalCount)
+            .check(
+              z.describe(
+                'The capped total number of matching transactions, returned when you request `include=totalCount`.',
+              ),
+            ),
+        })
+        .check(z.describe('Extra resources included because you requested them with `include`.')),
+      'TokenTransactionListMeta',
+    )
 
     /**
      * Page of transactions touching the token contract. Each row is the
@@ -543,15 +588,18 @@ export namespace schema {
      * already imports `Tokens.schema` at module init; a direct reference
      * here would close the import cycle and crash during evaluation.
      */
-    export const Response = z
-      .object({
-        data: z
-          .array(z.lazy(() => Transactions.schema.getTransaction.Response))
-          .check(z.describe('The transactions in this page.')),
-        meta: z.optional(Meta).check(z.describe('Extra resources you requested with `include`.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of transactions that interact with this token contract.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(z.lazy(() => Transactions.schema.getTransaction.Response))
+            .check(z.describe('The transactions in this page.')),
+          meta: z.optional(Meta).check(z.describe('Extra resources you requested with `include`.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of transactions that interact with this token contract.')),
+      'TokenTransactionList',
+    )
   }
 }
 
@@ -570,6 +618,9 @@ export function tokens() {
           'Lists TIP-20 tokens on Tempo. TIP-20 is Tempo’s payments-focused token standard and a superset of ERC-20.',
         operationId: 'getTokens',
         responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
+          },
           success: { description: 'A page of TIP-20 tokens.', schema: schema.getTokens.Response },
         }),
         summary: 'List tokens',
@@ -624,7 +675,7 @@ export function tokens() {
             200,
           )
         } catch (cause) {
-          return Response.upstream(c, cause)
+          return Response.upstream(c, cause, { page: query.page })
         }
       },
     )
@@ -645,6 +696,14 @@ export function tokens() {
         operationId: 'getTokenBySymbol',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'query_invalid',
+                'symbol_invalid',
+              ],
+            },
             404: {
               description: 'No token was found for this address or symbol.',
               codes: ['token_not_found'],
@@ -653,6 +712,7 @@ export function tokens() {
           },
           success: {
             description: 'Metadata for one TIP-20 token.',
+            example: tokenExample,
             schema: schema.getToken.Response,
           },
         }),
@@ -717,6 +777,9 @@ export function tokens() {
         operationId: 'getToken',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid', 'token_invalid'],
+            },
             404: {
               description: 'No token was found for this address or symbol.',
               codes: ['token_not_found'],
@@ -725,6 +788,7 @@ export function tokens() {
           },
           success: {
             description: 'Metadata for one TIP-20 token.',
+            example: tokenExample,
             schema: schema.getToken.Response,
           },
         }),
@@ -776,8 +840,15 @@ export function tokens() {
             description: 'The token logo image.',
             headers: OpenApi.successHeaders,
           },
-          400: OpenApi.standardError(400, 'The request parameters were invalid.'),
+          400: OpenApi.standardError(400, 'The request parameters were invalid.', [
+            'api_key_malformed',
+            'chain_id_invalid',
+            'chain_id_unsupported',
+            'query_invalid',
+            'token_invalid',
+          ]),
           401: OpenApi.standardError(401, 'The API key is missing or invalid.'),
+          403: OpenApi.standardError(403, 'The API key cannot access this resource.'),
           404: OpenApi.standardError(404, 'No logo image was found for this token.', [
             'token_logo_not_found',
           ]),
@@ -861,7 +932,12 @@ export function tokens() {
           'Lists the accounts that hold a TIP-20 token, ordered from largest to smallest balance.',
         operationId: 'getTokenHolders',
         responses: OpenApi.responses({
-          errors: { 502: 'The upstream indexer could not serve this request.' },
+          errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid', 'token_invalid'],
+            },
+            502: 'The upstream indexer could not serve this request.',
+          },
           success: {
             description: 'A page of token holders.',
             schema: schema.getTokenHolders.Response,
@@ -932,7 +1008,7 @@ export function tokens() {
             200,
           )
         } catch (cause) {
-          return Response.upstream(c, cause)
+          return Response.upstream(c, cause, { page: query.page })
         }
       },
     )
@@ -951,7 +1027,12 @@ export function tokens() {
         description: 'Lists transactions that interacted with this token contract.',
         operationId: 'getTokenTransactions',
         responses: OpenApi.responses({
-          errors: { 502: 'The upstream indexer could not serve this request.' },
+          errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid', 'token_invalid'],
+            },
+            502: 'The upstream indexer could not serve this request.',
+          },
           success: {
             description: 'A page of transactions involving this token contract.',
             schema: schema.getTokenTransactions.Response,
@@ -1051,7 +1132,7 @@ export function tokens() {
             200,
           )
         } catch (cause) {
-          return Response.upstream(c, cause)
+          return Response.upstream(c, cause, { page: query.page })
         }
       },
     )