tapimo 0.4.0 → 0.4.3

package/src/apps/data/FundingRouteProviders.ts

@@ -1,10 +1,48 @@
-import type * as FundingRoutes from '../../internal/FundingRoutes.js'
+import * as z from 'zod/mini'
+
+import * as FundingRoutes from '../../internal/FundingRoutes.js'
 
 type Fetch = typeof globalThis.fetch
 
+const defaultFetch: Fetch = (input, init) => globalThis.fetch(input, init)
+
 const defaultAcrossBaseUrl = 'https://app.across.to/api'
 const defaultRelayBaseUrl = 'https://api.relay.link'
 
+namespace schema {
+  const DecimalString = z.string().check(z.regex(/^\d+(\.\d+)?$/))
+  const IntegerString = z.string().check(z.regex(/^\d+$/))
+
+  const AcrossToken = z.object({
+    address: z.string(),
+    chainId: z.number().check(z.int(), z.nonnegative()),
+    decimals: z.number().check(z.int(), z.nonnegative()),
+    symbol: z.string(),
+  })
+
+  const AcrossFee = z.object({
+    amount: IntegerString,
+    amountUsd: DecimalString,
+    pct: IntegerString,
+    token: AcrossToken,
+  })
+
+  export const AcrossQuote = z.object({
+    amountType: z.literal('exactInput'),
+    expectedFillTime: z.number().check(z.int(), z.nonnegative()),
+    expectedOutputAmount: IntegerString,
+    fees: z.object({
+      total: AcrossFee,
+      totalMax: AcrossFee,
+    }),
+    inputAmount: IntegerString,
+    inputToken: AcrossToken,
+    minOutputAmount: IntegerString,
+    outputToken: AcrossToken,
+    quoteExpiryTimestamp: z.number().check(z.int(), z.nonnegative()),
+  })
+}
+
 /** Creates the live funding route adapters configured for this deployment. */
 export function createAdapters(options: createAdapters.Options = {}) {
   return {
@@ -16,17 +54,17 @@ export function createAdapters(options: createAdapters.Options = {}) {
 export declare namespace createAdapters {
   /** Provider adapter factory options. Omit a provider to keep its routes static. */
   type Options = {
-    /** Across quote adapter options. */
+    /** Across discovery adapter options. */
     across?: across.Options | false | undefined
     /** Relay quote adapter options. */
     relay?: relay.Options | false | undefined
   }
 }
 
-/** Creates an Across quote adapter backed by `/suggested-fees`. */
+/** Creates an Across discovery adapter backed by `/suggested-fees`. */
 export function across(options: across.Options): FundingRoutes.ProviderAdapter {
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultAcrossBaseUrl)
-  const fetcher = options.fetch ?? globalThis.fetch
+  const fetcher = options.fetch ?? defaultFetch
   const now = options.now ?? (() => new Date())
 
   return {
@@ -65,17 +103,141 @@ export function across(options: across.Options): FundingRoutes.ProviderAdapter {
   }
 }
 
-export declare namespace across {
-  /** Across quote adapter options. */
+/** Builds the authenticated Across `/swap/approval` request for an exact-input quote. */
+export function createAcrossQuoteRequest(options: createAcrossQuoteRequest.Options) {
+  assertAcrossIntegratorId(options.integratorId)
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultAcrossBaseUrl)
+  const sourceChainId = providerChainId(options.route.sourceChain, 'across')
+  const destinationChainId = eip155ChainId(options.route.destinationChain)
+  const url = new URL(`${baseUrl}/swap/approval`)
+  url.search = new URLSearchParams({
+    amount: options.route.sourceAmount.amount,
+    depositor: options.depositor,
+    destinationChainId,
+    inputToken: options.route.sourceToken.address,
+    integratorId: options.integratorId,
+    originChainId: sourceChainId,
+    outputToken: options.route.destinationToken.address,
+    skipOriginTxEstimation: 'true',
+    strictTradeType: 'true',
+    tradeType: 'exactInput',
+  }).toString()
+  if (options.recipient !== undefined) url.searchParams.set('recipient', options.recipient)
+  return { headers: { Authorization: `Bearer ${options.apiKey}` }, url }
+}
+
+export declare namespace createAcrossQuoteRequest {
+  /** Inputs required to construct an Across exact-input quote request. */
+  type Options = {
+    /** Across API key sent as a bearer token. */
+    apiKey: string
+    /** Optional Across API base URL. */
+    baseUrl?: string | undefined
+    /** Address that would submit the source transaction. */
+    depositor: string
+    /** Across integrator id sent as the required query parameter. */
+    integratorId: string
+    /** Optional destination recipient. */
+    recipient?: string | undefined
+    /** Curated route selected for the quote. */
+    route: FundingRoutes.RouteCandidate
+  }
+}
+
+/** Creates an explicit Across quote adapter backed by `/swap/approval`. */
+export function acrossQuote(options: acrossQuote.Options): FundingRoutes.ProviderQuote {
+  assertAcrossIntegratorId(options.integratorId)
+
+  return async ({ depositor, recipient, route }, signal) => {
+    const request = createAcrossQuoteRequest({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      depositor,
+      integratorId: options.integratorId,
+      recipient,
+      route,
+    })
+
+    try {
+      const body = await requestJson(request.url, {
+        fetcher: defaultFetch,
+        headers: request.headers,
+        signal,
+      })
+      return parseAcrossQuote({ body, now: new Date(), route })
+    } catch (cause) {
+      if (!(cause instanceof ProviderResponseError)) throw cause
+      throw mapAcrossQuoteError({ body: cause.body, status: cause.status })
+    }
+  }
+}
+
+export declare namespace acrossQuote {
+  /** Across Swap API adapter options. */
   type Options = {
     /** Across API key sent as a bearer token. */
     apiKey: string
+    /** Optional Across API base URL. */
+    baseUrl?: string | undefined
     /** Across integrator id sent as the required query parameter. */
     integratorId: string
+  }
+}
+
+/** Returns bounded Across quote failure details suitable for structured request logs. */
+export function acrossQuoteFailure(options: acrossQuoteFailure.Options): acrossQuoteFailure.Result {
+  const { cause } = options
+  const base = { id: 'across', operation: 'swap/approval' } as const
+  if (cause instanceof ProviderResponseError) {
+    const code = providerErrorCode(cause.body)
+    return {
+      ...(code === undefined ? {} : { code }),
+      failure: 'http' as const,
+      ...base,
+      status: cause.status,
+    }
+  }
+  if (cause instanceof ProviderPayloadError) return { failure: 'payload', ...base }
+  if (cause instanceof TypeError) return { failure: 'network', ...base }
+  if (cause instanceof Error) return { failure: 'unknown', ...base }
+  return undefined
+}
+
+export declare namespace acrossQuoteFailure {
+  /** Inputs used to classify an Across quote failure. */
+  type Options = {
+    /** Error thrown by the Across quote boundary. */
+    cause: unknown
+  }
+
+  /** Bounded diagnostic fields, or undefined when the thrown value is not an error. */
+  type Result =
+    | {
+        /** Stable provider error code, when one is safe to retain. */
+        code?: string | undefined
+        /** Failure boundary that rejected the provider request. */
+        failure: 'http' | 'network' | 'payload' | 'unknown'
+        /** Provider identifier. */
+        id: 'across'
+        /** Across operation identifier. */
+        operation: 'swap/approval'
+        /** Upstream HTTP status, when a response was received. */
+        status?: number | undefined
+      }
+    | undefined
+}
+
+export declare namespace across {
+  /** Across API adapter options. */
+  type Options = {
     /** Override for tests or non-production Across environments. */
     baseUrl?: string | undefined
     /** Fetch implementation override for tests. */
     fetch?: Fetch | undefined
+    /** Across API key sent as a bearer token. */
+    apiKey: string
+    /** Across integrator id sent as the required query parameter. */
+    integratorId: string
     /** Clock override for deterministic tests. */
     now?: (() => Date) | undefined
   }
@@ -84,7 +246,7 @@ export declare namespace across {
 /** Creates a Relay quote adapter backed by `/chains/liquidity` and `/quote/v2`. */
 export function relay(options: relay.Options): FundingRoutes.ProviderAdapter {
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultRelayBaseUrl)
-  const fetcher = options.fetch ?? globalThis.fetch
+  const fetcher = options.fetch ?? defaultFetch
   const now = options.now ?? (() => new Date())
 
   return {
@@ -152,6 +314,85 @@ export declare namespace relay {
   }
 }
 
+/** Maps an Across HTTP error into the stable funding-provider error contract. */
+export function mapAcrossQuoteError(options: mapAcrossQuoteError.Options) {
+  if (options.status === 429) return new FundingRoutes.ProviderRateLimitError()
+  const cause = new ProviderResponseError(options.status, options.body)
+  const unavailable = providerUnavailable(cause, [
+    'AMOUNT_TOO_HIGH',
+    'AMOUNT_TOO_LOW',
+    'INSUFFICIENT_LIQUIDITY',
+    'NO_QUOTES',
+    'NO_ROUTE',
+    'UNSUPPORTED_ROUTE',
+  ])
+  if (unavailable) return new FundingRoutes.ProviderQuoteUnavailableError()
+  return cause
+}
+
+export declare namespace mapAcrossQuoteError {
+  /** Across HTTP error response to classify. */
+  type Options = {
+    /** Parsed response body returned by Across. */
+    body: unknown
+    /** Across HTTP response status. */
+    status: number
+  }
+}
+
+/** Validates and normalizes an Across quote payload against its curated route. */
+export function parseAcrossQuote(
+  options: parseAcrossQuote.Options,
+): FundingRoutes.ProviderQuoteResult {
+  const parsed = schema.AcrossQuote.safeParse(options.body)
+  if (!parsed.success) throw new ProviderPayloadError()
+  const response = parsed.data
+  const total = response.fees.total
+  const totalMax = response.fees.totalMax
+  if (
+    response.inputAmount !== options.route.sourceAmount.amount ||
+    response.inputToken.address.toLowerCase() !== options.route.sourceToken.address.toLowerCase() ||
+    response.inputToken.chainId !== Number(eip155ChainId(options.route.sourceChain)) ||
+    response.inputToken.decimals !== options.route.sourceToken.decimals ||
+    response.outputToken.address.toLowerCase() !==
+      options.route.destinationToken.address.toLowerCase() ||
+    response.outputToken.chainId !== Number(eip155ChainId(options.route.destinationChain)) ||
+    response.outputToken.decimals !== options.route.destinationToken.decimals ||
+    BigInt(response.expectedOutputAmount) <= 0n ||
+    BigInt(response.minOutputAmount) <= 0n ||
+    BigInt(response.minOutputAmount) > BigInt(response.expectedOutputAmount) ||
+    response.quoteExpiryTimestamp * 1_000 <= options.now.getTime() ||
+    !matchesFeeToken(total.token, options.route) ||
+    !matchesFeeToken(totalMax.token, options.route) ||
+    BigInt(totalMax.amount) < BigInt(total.amount) ||
+    BigInt(totalMax.pct) < BigInt(total.pct)
+  )
+    throw new ProviderPayloadError()
+  return {
+    estimatedSeconds: response.expectedFillTime,
+    expiresAt: isoFromUnixSeconds(String(response.quoteExpiryTimestamp)),
+    fees: {
+      total: formatAcrossFee(response.fees.total),
+      totalMax: formatAcrossFee(response.fees.totalMax),
+    },
+    minimumOutputAmount: response.minOutputAmount,
+    outputAmount: response.expectedOutputAmount,
+    sampledAt: options.now.toISOString(),
+  }
+}
+
+export declare namespace parseAcrossQuote {
+  /** Inputs required to validate and normalize an Across quote payload. */
+  type Options = {
+    /** Untrusted JSON body returned by Across. */
+    body: unknown
+    /** Timestamp when Tempo sampled the response. */
+    now: Date
+    /** Curated route the response must match. */
+    route: FundingRoutes.RouteCandidate
+  }
+}
+
 function formatAcrossResult(
   route: FundingRoutes.RouteCandidate,
   body: unknown,
@@ -191,6 +432,22 @@ function formatAcrossResult(
   }
 }
 
+function formatAcrossFee(
+  fee: z.output<typeof schema.AcrossQuote>['fees']['total'],
+): FundingRoutes.ProviderQuoteFee {
+  return {
+    amount: fee.amount,
+    amountUsd: fee.amountUsd,
+    bps: scaledPctToBps(fee.pct),
+    token: {
+      address: fee.token.address,
+      chainId: `eip155:${fee.token.chainId}`,
+      decimals: fee.token.decimals,
+      symbol: fee.token.symbol,
+    },
+  }
+}
+
 function formatRelayResult(
   route: FundingRoutes.RouteCandidate,
   quote: unknown,
@@ -333,12 +590,17 @@ function relayHeaders(apiKey: string | undefined): Record<string, string> | unde
 function providerUnavailable(cause: unknown, codes: readonly string[]) {
   if (!(cause instanceof ProviderResponseError) || cause.status < 400 || cause.status >= 500)
     return undefined
-  const body = record(cause.body)
-  const code = stringValue(body['code']) ?? stringValue(body['errorCode'])
+  const code = providerErrorCode(cause.body)
   if (code && codes.includes(code)) return code
   return undefined
 }
 
+function providerErrorCode(input: unknown) {
+  const body = record(input)
+  const code = stringValue(body['code']) ?? stringValue(body['errorCode'])
+  return code && /^[A-Za-z0-9_.:-]{1,64}$/.test(code) ? code : undefined
+}
+
 class ProviderResponseError extends Error {
   override name = 'FundingRouteProviders.ProviderResponseError'
 
@@ -350,6 +612,14 @@ class ProviderResponseError extends Error {
   }
 }
 
+class ProviderPayloadError extends Error {
+  override name = 'FundingRouteProviders.ProviderPayloadError'
+}
+
+class ProviderConfigurationError extends Error {
+  override name = 'FundingRouteProviders.ProviderConfigurationError'
+}
+
 function providerChainId(
   routeChain: FundingRoutes.RouteCandidate['sourceChain'],
   provider: string,
@@ -371,6 +641,21 @@ class UnsupportedProviderRouteError extends Error {
   override name = 'FundingRouteProviders.UnsupportedProviderRouteError'
 }
 
+function assertAcrossIntegratorId(integratorId: string) {
+  if (!/^0x[\da-fA-F]{4}$/.test(integratorId)) throw new ProviderConfigurationError()
+}
+
+function matchesFeeToken(
+  token: z.output<typeof schema.AcrossQuote>['fees']['total']['token'],
+  route: FundingRoutes.RouteCandidate,
+) {
+  return (
+    token.address.toLowerCase() === route.sourceToken.address.toLowerCase() &&
+    token.chainId === Number(eip155ChainId(route.sourceChain)) &&
+    token.decimals === route.sourceToken.decimals
+  )
+}
+
 function normalizeBaseUrl(input: string) {
   return input.replace(/\/+$/, '')
 }

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

@@ -1,6 +1,8 @@
 import { Schema } from 'tapimo'
 
 import * as TestApp from '../../../../test/App.js'
+import type * as Log from '../../../internal/Log.js'
+import * as FundingRouteProviders from '../FundingRouteProviders.js'
 import * as Funding from './funding.js'
 
 describe('GET /funding/routes', () => {
@@ -233,6 +235,84 @@ describe('GET /funding/routes', () => {
   })
 })
 
+describe('POST /funding/routes/quote', () => {
+  test('rejects invalid depositor addresses', async () => {
+    const response = await TestApp.create().request('/v1/funding/routes/quote', {
+      body: JSON.stringify({
+        depositor: 'invalid',
+        provider: 'across',
+        sourceAmount: '1000000',
+        sourceChain: 'base',
+        sourceToken: 'USDC',
+      }),
+      headers: { ...TestApp.auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(400)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+  })
+
+  test('returns a stable error when Across quoting is not configured', async () => {
+    const response = await TestApp.create().request('/v1/funding/routes/quote', {
+      body: JSON.stringify(quoteRequest()),
+      headers: { ...TestApp.auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(501)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(await response.json()).toMatchObject({ error: { code: 'provider_unconfigured' } })
+  })
+
+  test('records bounded Across failure details in the request log', async () => {
+    const entries: Log.Entry[] = []
+    const response = await TestApp.create({
+      fundingRoutes: {
+        async acrossQuote() {
+          throw FundingRouteProviders.mapAcrossQuoteError({
+            body: { code: 'AUTH_FAILED', detail: 'not logged' },
+            status: 401,
+          })
+        },
+      },
+      logger: (entry) => void entries.push(entry),
+    }).request('/v1/funding/routes/quote', {
+      body: JSON.stringify(quoteRequest()),
+      headers: { ...TestApp.auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(502)
+    expect(entries[0]).toMatchObject({
+      errorCode: 'provider_error',
+      provider: {
+        code: 'AUTH_FAILED',
+        failure: 'http',
+        id: 'across',
+        operation: 'swap/approval',
+        status: 401,
+      },
+    })
+    expect(JSON.stringify(entries[0])).not.toContain('not logged')
+  })
+
+  test('publishes the normalized quote contract in OpenAPI', async () => {
+    const response = await TestApp.create().request('/openapi.json')
+    const document = (await response.json()) as {
+      paths: Record<string, { post?: { operationId?: string; responses?: object } }>
+    }
+    const operation = document.paths['/v1/funding/routes/quote']?.post
+
+    expect(operation).toMatchObject({
+      operationId: 'quoteFundingRoute',
+      responses: { 200: expect.any(Object), 400: expect.any(Object), 502: expect.any(Object) },
+    })
+    expect(JSON.stringify(operation)).not.toMatch(/approvalTxns|checks|swapTx/)
+  })
+})
+
 describe('GET /funding/chains', () => {
   test('lists source chain and stablecoin inventory', async () => {
     const response = await TestApp.client().v1.funding.chains.$get(undefined, TestApp.auth)
@@ -252,6 +332,16 @@ describe('GET /funding/chains', () => {
   })
 })
 
+function quoteRequest() {
+  return {
+    depositor: '0x1111111111111111111111111111111111111111',
+    provider: 'across',
+    sourceAmount: '1000000',
+    sourceChain: 'base',
+    sourceToken: 'USDC',
+  }
+}
+
 describe('GET /providers', () => {
   test('lists providers filtered by capability', async () => {
     const response = await TestApp.client().v1.providers.$get(
@@ -280,29 +370,6 @@ describe('GET /providers', () => {
     ])
   })
 
-  test('marks configured live provider adapters', async () => {
-    const app = TestApp.create({
-      fundingRoutes: {
-        adapters: {
-          across: {
-            async probeQuote() {
-              throw new Error('not used')
-            },
-          },
-        },
-      },
-    })
-
-    const response = await app.request('/v1/providers?capability=fundingRoutes', {
-      headers: TestApp.auth.headers,
-    })
-    expect(response.status).toBe(200)
-    const body = await TestApp.json(response, Funding.schema.listProviders.Response)
-
-    expect(body.data.find((provider) => provider.id === 'across')?.status).toBe('configured')
-    expect(body.data.find((provider) => provider.id === 'relay')?.status).toBe('inventoryOnly')
-  })
-
   test('rejects unsupported provider capabilities', async () => {
     const response = await TestApp.create().request('/v1/providers?capability=settlement', {
       headers: TestApp.auth.headers,