tapimo 0.11.0 → 0.12.0

package/src/apps/funding/routes/chains.test.ts

@@ -38,17 +38,221 @@ function create(options: TestApp.create.Options = {}) {
 }
 
 describe('funding OpenAPI', () => {
-  test('publishes get operation ids for funding inventory', async () => {
+  test('publishes generator-ready discovery contracts', async () => {
     const app = create({ auth: false })
     const spec = await (await app.request('/openapi.json')).json()
+    const operations = {
+      chains: spec.paths['/v1/funding/chains'].get,
+      providers: spec.paths['/v1/funding/providers'].get,
+      quotes: spec.paths['/v1/funding/quotes'].get,
+    }
+    const summarize = (operation: (typeof operations)[keyof typeof operations]) => ({
+      errors: Object.fromEntries(
+        [400, 401, 403, 429, 500, 502].map((status) => [
+          status,
+          operation.responses[status].$ref ??
+            operation.responses[status].content?.['application/json']?.schema,
+        ]),
+      ),
+      operationId: operation.operationId,
+      response: operation.responses[200].content['application/json'].schema,
+    })
 
     expect({
-      chains: spec.paths['/v1/funding/chains'].get.operationId,
-      providers: spec.paths['/v1/funding/providers'].get.operationId,
-    }).toEqual({
-      chains: 'getFundingChains',
-      providers: 'getFundingProviders',
-    })
+      components: [
+        'FundingChain',
+        'FundingChainInventory',
+        'FundingChainList',
+        'FundingProvider',
+        'FundingProviderList',
+        'FundingQuote',
+        'FundingQuoteDetails',
+        'FundingQuoteList',
+        'FundingQuoteQuality',
+        'FundingToken',
+      ].filter((name) => spec.components.schemas[name]),
+      formats: {
+        quoteExpiresAt: spec.components.schemas.FundingQuoteDetails.properties.expiresAt.format,
+        quoteSampledAt: spec.components.schemas.FundingQuoteDetails.properties.sampledAt.format,
+      },
+      models: {
+        chainInventoryToken: spec.components.schemas.FundingChainInventory.properties.tokens.items,
+        chainList: spec.components.schemas.FundingChainList.properties.data.items,
+        providerList: spec.components.schemas.FundingProviderList.properties.data.items,
+        quote: {
+          destinationChain: spec.components.schemas.FundingQuote.properties.destinationChain,
+          destinationToken: spec.components.schemas.FundingQuote.properties.destinationToken,
+          provider: spec.components.schemas.FundingQuote.properties.provider,
+          quality: spec.components.schemas.FundingQuote.properties.quality,
+          quote: spec.components.schemas.FundingQuote.properties.quote,
+          sourceChain: spec.components.schemas.FundingQuote.properties.sourceChain,
+          sourceToken: spec.components.schemas.FundingQuote.properties.sourceToken,
+        },
+        quoteList: spec.components.schemas.FundingQuoteList.properties.data.items,
+      },
+      operations: {
+        chains: summarize(operations.chains),
+        providers: summarize(operations.providers),
+        quotes: summarize(operations.quotes),
+      },
+      sharedErrorCodes: {
+        authentication:
+          spec.components.schemas.AuthenticationError.properties.error.properties.code.enum,
+        forbidden: spec.components.schemas.ForbiddenError.properties.error.properties.code.enum,
+        malformedApiKey:
+          spec.components.schemas.ApiKeyMalformedError.properties.error.properties.code.enum,
+        malformedApiKeyOrInvalidQuery:
+          spec.components.schemas.ApiKeyMalformedOrQueryInvalidError.properties.error.properties
+            .code.enum,
+        upstream: spec.components.schemas.UpstreamError.properties.error.properties.code.enum,
+      },
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "FundingChain",
+          "FundingChainInventory",
+          "FundingChainList",
+          "FundingProvider",
+          "FundingProviderList",
+          "FundingQuote",
+          "FundingQuoteDetails",
+          "FundingQuoteList",
+          "FundingQuoteQuality",
+          "FundingToken",
+        ],
+        "formats": {
+          "quoteExpiresAt": "date-time",
+          "quoteSampledAt": "date-time",
+        },
+        "models": {
+          "chainInventoryToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+          "chainList": {
+            "$ref": "#/components/schemas/FundingChainInventory",
+          },
+          "providerList": {
+            "$ref": "#/components/schemas/FundingProvider",
+          },
+          "quote": {
+            "destinationChain": {
+              "$ref": "#/components/schemas/FundingChain",
+            },
+            "destinationToken": {
+              "$ref": "#/components/schemas/FundingToken",
+            },
+            "provider": {
+              "$ref": "#/components/schemas/FundingProvider",
+            },
+            "quality": {
+              "$ref": "#/components/schemas/FundingQuoteQuality",
+            },
+            "quote": {
+              "$ref": "#/components/schemas/FundingQuoteDetails",
+            },
+            "sourceChain": {
+              "$ref": "#/components/schemas/FundingChain",
+            },
+            "sourceToken": {
+              "$ref": "#/components/schemas/FundingToken",
+            },
+          },
+          "quoteList": {
+            "$ref": "#/components/schemas/FundingQuote",
+          },
+        },
+        "operations": {
+          "chains": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+            },
+            "operationId": "getFundingChains",
+            "response": {
+              "$ref": "#/components/schemas/FundingChainList",
+            },
+          },
+          "providers": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+            },
+            "operationId": "getFundingProviders",
+            "response": {
+              "$ref": "#/components/schemas/FundingProviderList",
+            },
+          },
+          "quotes": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+            },
+            "operationId": "quoteFunding",
+            "response": {
+              "$ref": "#/components/schemas/FundingQuoteList",
+            },
+          },
+        },
+        "sharedErrorCodes": {
+          "authentication": [
+            "api_key_invalid",
+            "api_key_missing",
+            "unauthorized",
+          ],
+          "forbidden": [
+            "api_key_forbidden",
+            "api_key_ip_forbidden",
+            "forbidden",
+          ],
+          "malformedApiKey": [
+            "api_key_malformed",
+          ],
+          "malformedApiKeyOrInvalidQuery": [
+            "api_key_malformed",
+            "query_invalid",
+          ],
+          "upstream": [
+            "upstream_error",
+          ],
+        },
+      }
+    `)
   })
 })
 

package/src/apps/funding/routes/chains.ts

@@ -20,23 +20,29 @@ export namespace schema {
   export const Token = FundingProvider.schema.TokenRef
 
   /** Chain inventory entry returned by the funding chains endpoint. */
-  export const ChainInventory = Schema.describe(
-    z.extend(Chain, {
-      tokens: z.array(Token).check(z.describe('Stablecoins known on this source chain.')),
-    }),
-    'One source chain and its known stablecoin inventory.',
+  export const ChainInventory = OpenApi.component(
+    Schema.describe(
+      z.extend(Chain, {
+        tokens: z.array(Token).check(z.describe('Stablecoins known on this source chain.')),
+      }),
+      'One source chain and its known stablecoin inventory.',
+    ),
+    'FundingChainInventory',
   )
 
   /** Schemas for the getFundingChains operation. */
   export namespace getFundingChains {
     /** Non-paginated source-chain inventory. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z
-          .array(ChainInventory)
-          .check(z.describe('Source chains and stablecoins supported by funding quotes.')),
-      }),
-      'A non-paginated list of source chains and stablecoin inventory.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z
+            .array(ChainInventory)
+            .check(z.describe('Source chains and stablecoins supported by funding quotes.')),
+        }),
+        'A non-paginated list of source chains and stablecoin inventory.',
+      ),
+      'FundingChainList',
     )
   }
 }
@@ -72,6 +78,7 @@ export function chains() {
       description: 'Lists supported source chains and tokens.',
       operationId: 'getFundingChains',
       responses: OpenApi.responses({
+        errors: { 400: { codes: [] } },
         success: {
           description: 'Supported source chains and stablecoins.',
           example: fundingChainsResponseExample,

package/src/apps/funding/routes/deposit-addresses.test.ts

@@ -60,6 +60,400 @@ function create(options: TestApp.create.Options = {}) {
   return TestApp.create({ ...options, db })
 }
 
+type ContractResponse = {
+  $ref?: string | undefined
+  content?: Record<string, { schema: unknown }> | undefined
+}
+
+test('publishes generator-ready funding deposit contracts', async () => {
+  const spec = await (await create({ auth: false }).request('/openapi.json')).json()
+  const depositAddressPath = Object.keys(spec.paths).find(
+    (path) => path.includes('/v1/funding/deposit-addresses/{') && !path.endsWith('/reconcile'),
+  )!
+  const depositPath = Object.keys(spec.paths).find((path) =>
+    path.includes('/v1/funding/deposits/{'),
+  )!
+  const reconcilePath = Object.keys(spec.paths).find((path) => path.endsWith('/reconcile'))!
+  const operations = {
+    createAddress: spec.paths['/v1/funding/deposit-addresses'].post,
+    getAddress: spec.paths[depositAddressPath].get,
+    getDeposit: spec.paths[depositPath].get,
+    listAddresses: spec.paths['/v1/funding/deposit-addresses'].get,
+    listDeposits: spec.paths['/v1/funding/deposits'].get,
+    reconcileAddress: spec.paths[reconcilePath].post,
+  }
+  const summarize = (operation: (typeof operations)[keyof typeof operations]) => ({
+    errors: Object.fromEntries(
+      (Object.entries(operation.responses) as [string, ContractResponse][])
+        .filter(([status]) => Number(status) >= 400)
+        .map(([status, response]) => [
+          status,
+          response.$ref ?? response.content?.['application/json']?.schema,
+        ]),
+    ),
+    operationId: operation.operationId,
+    request: operation.requestBody?.content['application/json'].schema,
+    response:
+      operation.responses[200]?.content?.['application/json']?.schema ??
+      operation.responses[202]?.content?.['application/json']?.schema,
+  })
+
+  expect({
+    components: [
+      'CreateFundingDepositAddressRequest',
+      'CreateFundingDepositAddressResponse',
+      'CreatedFundingDepositAddress',
+      'FundingDeposit',
+      'FundingDepositAddress',
+      'FundingDepositAddressList',
+      'FundingDepositList',
+      'FundingDepositStatusReason',
+    ].filter((name) => spec.components.schemas[name]),
+    formats: {
+      addressCreatedAt: spec.components.schemas.FundingDepositAddress.properties.createdAt.format,
+      addressUpdatedAt: spec.components.schemas.FundingDepositAddress.properties.updatedAt.format,
+      depositCreatedAt: spec.components.schemas.FundingDeposit.properties.createdAt.format,
+      depositUpdatedAt: spec.components.schemas.FundingDeposit.properties.updatedAt.format,
+    },
+    models: {
+      address: {
+        destinationChain: spec.components.schemas.FundingDepositAddress.properties.destinationChain,
+        destinationToken: spec.components.schemas.FundingDepositAddress.properties.destinationToken,
+        provider: spec.components.schemas.FundingDepositAddress.properties.provider,
+        sourceChain: spec.components.schemas.FundingDepositAddress.properties.sourceChain,
+        sourceToken: spec.components.schemas.FundingDepositAddress.properties.sourceToken,
+      },
+      addressList: spec.components.schemas.FundingDepositAddressList.properties.data.items,
+      createResponse: spec.components.schemas.CreateFundingDepositAddressResponse.anyOf,
+      createdAddress: {
+        feeToken:
+          spec.components.schemas.CreatedFundingDepositAddress.properties.fees.items.properties
+            .token,
+        quote: spec.components.schemas.CreatedFundingDepositAddress.properties.quote,
+      },
+      deposit: {
+        destinationChain: spec.components.schemas.FundingDeposit.properties.destinationChain,
+        destinationToken: spec.components.schemas.FundingDeposit.properties.destinationToken,
+        provider: spec.components.schemas.FundingDeposit.properties.provider,
+        sourceChain: spec.components.schemas.FundingDeposit.properties.sourceChain,
+        sourceToken: spec.components.schemas.FundingDeposit.properties.sourceToken,
+        statusReason: spec.components.schemas.FundingDeposit.properties.statusReason,
+      },
+      depositList: spec.components.schemas.FundingDepositList.properties.data.items,
+    },
+    operations: {
+      createAddress: summarize(operations.createAddress),
+      getAddress: summarize(operations.getAddress),
+      getDeposit: summarize(operations.getDeposit),
+      listAddresses: summarize(operations.listAddresses),
+      listDeposits: summarize(operations.listDeposits),
+      reconcileAddress: summarize(operations.reconcileAddress),
+    },
+    sharedErrorCodes: {
+      addressNotActive:
+        spec.components.schemas.FundingDepositAddressNotActiveError.properties.error.properties.code
+          .enum,
+      addressNotAvailable:
+        spec.components.schemas.DepositAddressNotAvailableError.properties.error.properties.code
+          .enum,
+      addressNotFound:
+        spec.components.schemas.FundingDepositAddressNotFoundError.properties.error.properties.code
+          .enum,
+      createInvalid:
+        spec.components.schemas.ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError.properties
+          .error.properties.code.enum,
+      depositNotFound:
+        spec.components.schemas.FundingDepositNotFoundError.properties.error.properties.code.enum,
+      idempotencyConflict:
+        spec.components.schemas.IdempotencyConflictOrIdempotencyInProgressError.properties.error
+          .properties.code.enum,
+      notImplemented:
+        spec.components.schemas.NotImplemented501Error.properties.error.properties.code.enum,
+      parametersInvalid:
+        spec.components.schemas.ApiKeyMalformedOrParamInvalidError.properties.error.properties.code
+          .enum,
+      queryInvalid:
+        spec.components.schemas.ApiKeyMalformedOrQueryInvalidError.properties.error.properties.code
+          .enum,
+    },
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "CreateFundingDepositAddressRequest",
+        "CreateFundingDepositAddressResponse",
+        "CreatedFundingDepositAddress",
+        "FundingDeposit",
+        "FundingDepositAddress",
+        "FundingDepositAddressList",
+        "FundingDepositList",
+        "FundingDepositStatusReason",
+      ],
+      "formats": {
+        "addressCreatedAt": "date-time",
+        "addressUpdatedAt": "date-time",
+        "depositCreatedAt": "date-time",
+        "depositUpdatedAt": "date-time",
+      },
+      "models": {
+        "address": {
+          "destinationChain": {
+            "$ref": "#/components/schemas/FundingChain",
+          },
+          "destinationToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+          "provider": {
+            "$ref": "#/components/schemas/FundingProvider",
+          },
+          "sourceChain": {
+            "$ref": "#/components/schemas/FundingChain",
+          },
+          "sourceToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+        },
+        "addressList": {
+          "$ref": "#/components/schemas/FundingDepositAddress",
+        },
+        "createResponse": [
+          {
+            "$ref": "#/components/schemas/CreatedFundingDepositAddress",
+          },
+          {
+            "$ref": "#/components/schemas/FundingDepositAddress",
+          },
+        ],
+        "createdAddress": {
+          "feeToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+          "quote": {
+            "$ref": "#/components/schemas/FundingQuoteDetails",
+          },
+        },
+        "deposit": {
+          "destinationChain": {
+            "$ref": "#/components/schemas/FundingChain",
+          },
+          "destinationToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+          "provider": {
+            "$ref": "#/components/schemas/FundingProvider",
+          },
+          "sourceChain": {
+            "$ref": "#/components/schemas/FundingChain",
+          },
+          "sourceToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+          "statusReason": {
+            "$ref": "#/components/schemas/FundingDepositStatusReason",
+          },
+        },
+        "depositList": {
+          "$ref": "#/components/schemas/FundingDeposit",
+        },
+      },
+      "operations": {
+        "createAddress": {
+          "errors": {
+            "400": {
+              "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+            },
+            "401": {
+              "$ref": "#/components/schemas/AuthenticationError",
+            },
+            "403": {
+              "$ref": "#/components/schemas/ForbiddenError",
+            },
+            "404": {
+              "$ref": "#/components/schemas/DepositAddressNotAvailableError",
+            },
+            "409": {
+              "$ref": "#/components/schemas/IdempotencyConflictOrIdempotencyInProgressError",
+            },
+            "429": "#/components/responses/RateLimited",
+            "500": "#/components/responses/InternalError",
+            "502": {
+              "$ref": "#/components/schemas/UpstreamError",
+            },
+          },
+          "operationId": "createFundingDepositAddress",
+          "request": {
+            "$ref": "#/components/schemas/CreateFundingDepositAddressRequest",
+          },
+          "response": {
+            "$ref": "#/components/schemas/CreateFundingDepositAddressResponse",
+          },
+        },
+        "getAddress": {
+          "errors": {
+            "400": {
+              "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+            },
+            "401": {
+              "$ref": "#/components/schemas/AuthenticationError",
+            },
+            "403": {
+              "$ref": "#/components/schemas/ForbiddenError",
+            },
+            "404": {
+              "$ref": "#/components/schemas/FundingDepositAddressNotFoundError",
+            },
+            "429": "#/components/responses/RateLimited",
+            "500": "#/components/responses/InternalError",
+            "502": {
+              "$ref": "#/components/schemas/UpstreamError",
+            },
+          },
+          "operationId": "getFundingDepositAddress",
+          "request": undefined,
+          "response": {
+            "$ref": "#/components/schemas/FundingDepositAddress",
+          },
+        },
+        "getDeposit": {
+          "errors": {
+            "400": {
+              "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+            },
+            "401": {
+              "$ref": "#/components/schemas/AuthenticationError",
+            },
+            "403": {
+              "$ref": "#/components/schemas/ForbiddenError",
+            },
+            "404": {
+              "$ref": "#/components/schemas/FundingDepositNotFoundError",
+            },
+            "429": "#/components/responses/RateLimited",
+            "500": "#/components/responses/InternalError",
+            "502": {
+              "$ref": "#/components/schemas/UpstreamError",
+            },
+          },
+          "operationId": "getFundingDeposit",
+          "request": undefined,
+          "response": {
+            "$ref": "#/components/schemas/FundingDeposit",
+          },
+        },
+        "listAddresses": {
+          "errors": {
+            "400": {
+              "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidError",
+            },
+            "401": {
+              "$ref": "#/components/schemas/AuthenticationError",
+            },
+            "403": {
+              "$ref": "#/components/schemas/ForbiddenError",
+            },
+            "429": "#/components/responses/RateLimited",
+            "500": "#/components/responses/InternalError",
+            "502": {
+              "$ref": "#/components/schemas/UpstreamError",
+            },
+          },
+          "operationId": "listFundingDepositAddresses",
+          "request": undefined,
+          "response": {
+            "$ref": "#/components/schemas/FundingDepositAddressList",
+          },
+        },
+        "listDeposits": {
+          "errors": {
+            "400": {
+              "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidError",
+            },
+            "401": {
+              "$ref": "#/components/schemas/AuthenticationError",
+            },
+            "403": {
+              "$ref": "#/components/schemas/ForbiddenError",
+            },
+            "429": "#/components/responses/RateLimited",
+            "500": "#/components/responses/InternalError",
+            "502": {
+              "$ref": "#/components/schemas/UpstreamError",
+            },
+          },
+          "operationId": "listFundingDeposits",
+          "request": undefined,
+          "response": {
+            "$ref": "#/components/schemas/FundingDepositList",
+          },
+        },
+        "reconcileAddress": {
+          "errors": {
+            "400": {
+              "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+            },
+            "401": {
+              "$ref": "#/components/schemas/AuthenticationError",
+            },
+            "403": {
+              "$ref": "#/components/schemas/ForbiddenError",
+            },
+            "404": {
+              "$ref": "#/components/schemas/FundingDepositAddressNotFoundError",
+            },
+            "409": {
+              "$ref": "#/components/schemas/FundingDepositAddressNotActiveError",
+            },
+            "429": "#/components/responses/RateLimited",
+            "500": "#/components/responses/InternalError",
+            "501": {
+              "$ref": "#/components/schemas/NotImplemented501Error",
+            },
+            "502": {
+              "$ref": "#/components/schemas/UpstreamError",
+            },
+          },
+          "operationId": "reconcileFundingDepositAddress",
+          "request": undefined,
+          "response": undefined,
+        },
+      },
+      "sharedErrorCodes": {
+        "addressNotActive": [
+          "funding_deposit_address_not_active",
+        ],
+        "addressNotAvailable": [
+          "deposit_address_not_available",
+        ],
+        "addressNotFound": [
+          "funding_deposit_address_not_found",
+        ],
+        "createInvalid": [
+          "api_key_malformed",
+          "body_invalid",
+          "idempotency_key_required",
+        ],
+        "depositNotFound": [
+          "funding_deposit_not_found",
+        ],
+        "idempotencyConflict": [
+          "idempotency_conflict",
+          "idempotency_in_progress",
+        ],
+        "notImplemented": [
+          "not_implemented",
+        ],
+        "parametersInvalid": [
+          "api_key_malformed",
+          "param_invalid",
+        ],
+        "queryInvalid": [
+          "api_key_malformed",
+          "query_invalid",
+        ],
+      },
+    }
+  `)
+})
+
 describe('POST /funding/deposit-addresses', () => {
   test('requires funding:write and an idempotency key', async () => {
     const app = transfersApp({ providers: [depositAddressProvider()] })