tapimo 0.11.0 → 0.13.0

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

@@ -60,6 +60,422 @@ function create(options: TestApp.create.Options = {}) {
   return TestApp.create({ ...options, db })
 }
 
+type ContractResponse = {
+  $ref?: string | undefined
+  content?: Record<string, { schema: unknown }> | undefined
+}
+
+type JsonSchema = {
+  $ref?: string | undefined
+  properties?: Record<string, JsonSchema> | undefined
+}
+
+type ComponentSpec = {
+  components: { schemas: Record<string, JsonSchema> }
+}
+
+function dereference(spec: ComponentSpec, schema: JsonSchema): JsonSchema {
+  if (!schema.$ref) return schema
+  const name = schema.$ref.split('/').at(-1)!
+  return spec.components.schemas[name]!
+}
+
+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: dereference(
+          spec,
+          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",
+            },
+            "504": "#/components/responses/RequestTimeout",
+          },
+          "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",
+            },
+            "504": "#/components/responses/RequestTimeout",
+          },
+          "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",
+            },
+            "504": "#/components/responses/RequestTimeout",
+          },
+          "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",
+            },
+            "504": "#/components/responses/RequestTimeout",
+          },
+          "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",
+            },
+            "504": "#/components/responses/RequestTimeout",
+          },
+          "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",
+            },
+            "504": "#/components/responses/RequestTimeout",
+          },
+          "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()] })

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

@@ -34,52 +34,55 @@ export namespace schema {
   /** Schemas for the createFundingDepositAddress operation. */
   export namespace createFundingDepositAddress {
     /** Funding deposit address creation request body. */
-    export const Body = z
-      .strictObject({
-        amount: FundingTransfer.schema.CreateRequest.shape.amount,
-        destinationToken: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe('Tempo destination token symbol, contract address, or token key.'),
-            z.meta({ examples: ['usdt0'] }),
-          ),
-        recipient: z
-          .string()
-          .check(
-            z.regex(/^0x[0-9a-fA-F]{40}$/),
-            z.describe('Tempo account that receives completed deposits.'),
-            z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
-          ),
-        refundAddress: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe('Source-chain account that receives refunds.'),
-            z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
-          ),
-        sourceChain: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe('Source chain CAIP-2 id, slug, or alias.'),
-            z.meta({ examples: ['tron', 'tron:0x2b6653dc'] }),
-          ),
-        sourceToken: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe('Source token symbol, contract address, or token key.'),
-            z.meta({ examples: ['usdt'] }),
-          ),
-        subsidize: z
-          .optional(z.boolean())
-          .check(
-            z.describe('Guarantees normalized 1:1 delivery through a Tempo-funded subsidy.'),
-            z.meta({ examples: [false] }),
-          ),
-      })
-      .check(z.describe('Reusable funding deposit address creation request.'))
+    export const Body = OpenApi.component(
+      z
+        .strictObject({
+          amount: FundingTransfer.schema.CreateRequest.shape.amount,
+          destinationToken: z
+            .string()
+            .check(
+              z.minLength(1),
+              z.describe('Tempo destination token symbol, contract address, or token key.'),
+              z.meta({ examples: ['usdt0'] }),
+            ),
+          recipient: z
+            .string()
+            .check(
+              z.regex(/^0x[0-9a-fA-F]{40}$/),
+              z.describe('Tempo account that receives completed deposits.'),
+              z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+            ),
+          refundAddress: z
+            .string()
+            .check(
+              z.minLength(1),
+              z.describe('Source-chain account that receives refunds.'),
+              z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
+            ),
+          sourceChain: z
+            .string()
+            .check(
+              z.minLength(1),
+              z.describe('Source chain CAIP-2 id, slug, or alias.'),
+              z.meta({ examples: ['tron', 'tron:0x2b6653dc'] }),
+            ),
+          sourceToken: z
+            .string()
+            .check(
+              z.minLength(1),
+              z.describe('Source token symbol, contract address, or token key.'),
+              z.meta({ examples: ['usdt'] }),
+            ),
+          subsidize: z
+            .optional(z.boolean())
+            .check(
+              z.describe('Guarantees normalized 1:1 delivery through a Tempo-funded subsidy.'),
+              z.meta({ examples: [false] }),
+            ),
+        })
+        .check(z.describe('Reusable funding deposit address creation request.')),
+      'CreateFundingDepositAddressRequest',
+    )
 
     /** Required headers for funding deposit address creation. */
     export const Headers = z.object({
@@ -95,16 +98,19 @@ export namespace schema {
     })
 
     /** The reusable address, with quoted terms only when the provider address was newly stored. */
-    export const Response = z
-      .union([
-        FundingDepositAddress.schema.CreatedFundingDepositAddress,
-        FundingDepositAddress.schema.FundingDepositAddress,
-      ])
-      .check(
-        z.describe(
-          'A reusable funding deposit address, including terms sampled for a newly stored provider address.',
+    export const Response = OpenApi.component(
+      z
+        .union([
+          FundingDepositAddress.schema.CreatedFundingDepositAddress,
+          FundingDepositAddress.schema.FundingDepositAddress,
+        ])
+        .check(
+          z.describe(
+            'A reusable funding deposit address, including terms sampled for a newly stored provider address.',
+          ),
         ),
-      )
+      'CreateFundingDepositAddressResponse',
+    )
   }
 
   /** Schemas for the getFundingDepositAddress operation. */
@@ -137,14 +143,17 @@ export namespace schema {
       .check(z.describe('Paging parameters for listing funding deposit addresses.'))
 
     /** One page of reusable funding deposit addresses. */
-    export const Response = z
-      .object({
-        data: z
-          .array(DepositAddress)
-          .check(z.describe('Funding deposit addresses on this page, newest first.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of reusable funding deposit addresses.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(DepositAddress)
+            .check(z.describe('Funding deposit addresses on this page, newest first.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of reusable funding deposit addresses.')),
+      'FundingDepositAddressList',
+    )
   }
 
   /** Schemas for the reconcileFundingDepositAddress operation. */
@@ -199,15 +208,18 @@ export namespace schema {
       .check(z.describe('Optional deposit filters and paging parameters.'))
 
     /** One page of detected deposits. */
-    export const Response = z
-      .object({
-        data: z.array(Deposit).check(z.describe('Detected deposits on this page, newest first.')),
-        meta: z
-          .optional(Schema.CountMeta)
-          .check(z.describe('Extra response metadata requested with `include`.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of visible funding deposits.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(Deposit).check(z.describe('Detected deposits on this page, newest first.')),
+          meta: z
+            .optional(Schema.CountMeta)
+            .check(z.describe('Extra response metadata requested with `include`.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of visible funding deposits.')),
+      'FundingDepositList',
+    )
   }
 
   /** Schemas for the getFundingDeposit operation. */
@@ -688,8 +700,6 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
             refundAddress,
             result,
           } = selected
-          const feeToken = (side: 'destination' | 'source') =>
-            side === 'source' ? selectedCandidate.sourceToken : selectedCandidate.destinationToken
           const created = await db.transaction(async (tx) => {
             const stored = await FundingDepositAddress.createOrGet(tx, {
               apiKeyId: principal.id,
@@ -729,16 +739,23 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
                 currency: selectedCandidate.destinationToken.currency,
                 decimals: selectedCandidate.destinationToken.decimals,
               }),
-              fees: result.fees.map((fee) => ({
-                amount: Value.tokenAmount({
-                  baseUnits: fee.amount,
-                  currency: feeToken(fee.side).currency,
-                  decimals: feeToken(fee.side).decimals,
-                }),
-                side: fee.side,
-                token: feeToken(fee.side),
-                type: 'provider',
-              })),
+              fees: result.fees.map((fee) => {
+                const token =
+                  fee.token ??
+                  (fee.side === 'source'
+                    ? selectedCandidate.sourceToken
+                    : selectedCandidate.destinationToken)
+                return {
+                  amount: Value.tokenAmount({
+                    baseUnits: fee.amount,
+                    currency: token.currency,
+                    decimals: token.decimals,
+                  }),
+                  side: fee.side,
+                  token,
+                  type: 'provider',
+                }
+              }),
               quote: {
                 ...(result.expiresAt === undefined ? {} : { expiresAt: result.expiresAt }),
                 sampledAt: result.sampledAt,

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

@@ -22,11 +22,14 @@ export namespace schema {
   /** Schemas for the getFundingProviders operation. */
   export namespace getFundingProviders {
     /** Non-paginated funding provider catalog. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Provider).check(z.describe("Providers in Tempo's funding quote catalog.")),
-      }),
-      'A non-paginated list of funding quote providers.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z.array(Provider).check(z.describe("Providers in Tempo's funding quote catalog.")),
+        }),
+        'A non-paginated list of funding quote providers.',
+      ),
+      'FundingProviderList',
     )
   }
 }
@@ -44,6 +47,7 @@ export function providers() {
       description: 'Lists available transfer providers.',
       operationId: 'getFundingProviders',
       responses: OpenApi.responses({
+        errors: { 400: { codes: [] } },
         success: {
           description: 'Funding quote providers supported by Tempo.',
           example: providersResponseExample,