tapimo 0.15.1 → 0.18.0

package/src/apps/routes/routes/quotes.test.ts

@@ -4,6 +4,7 @@ import * as RoutesCatalog from '../../../internal/routes/Catalog.js'
 import * as RoutesProvider from '../../../internal/routes/Provider.js'
 
 import * as Across from '../../../internal/routes/providers/across.js'
+import * as PropAmm from '../../../internal/routes/providers/propAmm.js'
 
 import * as Relay from '../../../internal/routes/providers/relay.js'
 
@@ -118,6 +119,52 @@ function create(options: TestApp.create.Options = {}) {
 }
 
 describe('GET /routes/quotes', () => {
+  test('documents and returns route_unavailable for an unknown source token', async () => {
+    const app = create({ auth: false, providers: [PropAmm.propAmm()] })
+    const spec = await (await app.request('/openapi.json')).json()
+    const parameter = spec.paths['/v1/routes/quotes'].get.parameters.find(
+      (parameter: { name: string }) => parameter.name === 'sourceToken',
+    )
+    expect(parameter.description).toBe(
+      'Source token symbol, address, or token key, scoped to `sourceChain`. Non-EVM addresses are case-sensitive. Unknown tokens return HTTP 400 with `route_unavailable`.',
+    )
+    const response = await app.request(
+      '/v1/routes/quotes?sourceChain=tempo&sourceToken=unknown-token&destinationToken=usdy&sourceAmount=1000000',
+    )
+    expect(response.status).toBe(400)
+    expect((await TestApp.json(response, Schema.ErrorResponse)).error).toMatchInlineSnapshot(`
+      {
+        "code": "route_unavailable",
+        "details": [
+          {
+            "message": "No quote is available for the selected route. Try another token pair or chain, or retry later.",
+          },
+        ],
+        "message": "No route is available for this request. Review the details and retry.",
+      }
+    `)
+  })
+
+  test('explains missing PropAMM identities in the public response', async () => {
+    const app = create({ auth: false, providers: [PropAmm.propAmm()] })
+    const response = await app.request(
+      '/v1/routes/quotes?sourceChain=tempo&sourceToken=usdce&destinationToken=usdy&sourceAmount=1000000',
+    )
+    expect(response.status).toBe(400)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect((await TestApp.json(response, Schema.ErrorResponse)).error).toMatchInlineSnapshot(`
+      {
+        "code": "route_unavailable",
+        "details": [
+          {
+            "message": "Sender and recipient addresses are required. Provide both addresses and retry.",
+          },
+        ],
+        "message": "No route is available for this request. Review the details and retry.",
+      }
+    `)
+  })
+
   test('publishes alphabetically ordered quote example fields', async () => {
     const app = create({ auth: false })
     const spec = await (await app.request('/openapi.json')).json()
@@ -137,6 +184,11 @@ describe('GET /routes/quotes', () => {
     const response = await app.request(quoteUrl(), { headers: TestApp.auth.headers })
     expect(response.status).toBe(200)
     expect(response.headers.get('cache-control')).toBe('no-store')
+    expect({
+      limit: response.headers.get('ratelimit-limit'),
+      remaining: response.headers.get('ratelimit-remaining'),
+      scope: response.headers.get('ratelimit-scope'),
+    }).toEqual({ limit: '40', remaining: '39', scope: 'data:read' })
     const body = await TestApp.json(response, Routes.schema.quoteRoutes.Response)
 
     expect(body.data).toHaveLength(1)
@@ -444,7 +496,7 @@ describe('GET /routes/quotes', () => {
     })
   })
 
-  test('returns an empty list when no provider is available', async () => {
+  test('returns an actionable error when no route is available', async () => {
     const entries: Log.Entry[] = []
     const response = await create({ logger: (entry) => void entries.push(entry) }).request(
       quoteUrl(),
@@ -452,9 +504,19 @@ describe('GET /routes/quotes', () => {
         headers: TestApp.auth.headers,
       },
     )
-    expect(response.status).toBe(200)
-    const body = await TestApp.json(response, Routes.schema.quoteRoutes.Response)
-    expect(body.data).toEqual([])
+    expect(response.status).toBe(400)
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(body.error).toMatchInlineSnapshot(`
+      {
+        "code": "route_unavailable",
+        "details": [
+          {
+            "message": "No quote is available for the selected route. Try another token pair or chain, or retry later.",
+          },
+        ],
+        "message": "No route is available for this request. Review the details and retry.",
+      }
+    `)
     expect(entries[0]?.routesQuoteResult).toEqual({
       candidateCount: 0,
       outcome: 'unsupported',
@@ -462,7 +524,7 @@ describe('GET /routes/quotes', () => {
     })
   })
 
-  test('returns an empty list when the provider reports no quote', async () => {
+  test('returns an actionable error when the provider reports no quote', async () => {
     const entries: Log.Entry[] = []
     const app = create({
       logger: (entry) => {
@@ -476,9 +538,20 @@ describe('GET /routes/quotes', () => {
       ],
     })
     const response = await app.request(quoteUrl(), { headers: TestApp.auth.headers })
-    expect(response.status).toBe(200)
-    const body = await TestApp.json(response, Routes.schema.quoteRoutes.Response)
-    expect(body.data).toEqual([])
+    expect(response.status).toBe(400)
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(body.error).toMatchInlineSnapshot(`
+      {
+        "code": "route_unavailable",
+        "details": [
+          {
+            "message": "No quote is available for the selected route. Try another token pair or chain, or retry later.",
+          },
+        ],
+        "message": "No route is available for this request. Review the details and retry.",
+      }
+    `)
+    expect(entries[0]?.errorCode).toBe('route_unavailable')
     expect(entries[0]?.routesProviderAttempts).toEqual([
       {
         durationMs: expect.any(Number),

package/src/apps/routes/routes/quotes.ts

@@ -9,6 +9,11 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Value from '../../../internal/Value.js'
+import * as Access from '../Access.js'
+
+// Bound each caller independently from the shared provider quota enforced by the Relay adapter.
+const quoteRateLimit = { limit: 40, period: 'minute' } as const
+const quoteRateLimitBucket = 'routes-quotes'
 
 /** Zod schemas owned by route quote resources. */
 export namespace schema {
@@ -104,17 +109,30 @@ const routesQuoteResponseExample = {
 export function quotes() {
   return new Hono<App.Environment>().get(
     '/v1/routes/quotes',
-    Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+    Auth.policy({
+      apiKey: {
+        bucket: quoteRateLimitBucket,
+        rateLimit: quoteRateLimit,
+        scopes: ['data:read'],
+      },
+      mpp: { bucket: quoteRateLimitBucket, rateLimit: quoteRateLimit },
+      public: true,
+    }),
     OpenApi.validate('query', schema.quoteRoutes.Query, {
       code: 'query_invalid',
       message: 'Invalid query parameters',
     }),
     OpenApi.describeRoute({
-      description: 'Returns live quotes for transferring stablecoins between supported chains.',
+      description:
+        'Returns live stablecoin transfer quotes, or an actionable error when none are available.',
       operationId: 'quoteRoutes',
       responses: OpenApi.responses({
         errors: {
-          400: { codes: ['query_invalid'] },
+          400: { codes: ['query_invalid', 'route_unavailable'] },
+          403: {
+            codes: ['routes_suspended'],
+            description: 'Fresh instructions are suspended for this API-key organization.',
+          },
           502: {
             codes: ['upstream_error'],
             description:
@@ -122,7 +140,7 @@ export function quotes() {
           },
         },
         success: {
-          description: 'Live route quotes. An empty list means no provider returned a quote.',
+          description: 'Successful live route quotes.',
           example: routesQuoteResponseExample,
           schema: schema.quoteRoutes.Response,
         },
@@ -140,34 +158,61 @@ export function quotes() {
 
       const query = c.req.valid('query')
       const attempts: RoutesProvider.ProviderAttempt[] = []
+      const unavailable = new Set<z.output<typeof RoutesProvider.schema.UnavailableReason>>()
       const providers = c.get('providers').filter(RoutesProvider.is)
       try {
         c.header('Cache-Control', 'no-store')
-        const catalog = await RoutesCatalog.snapshot(c).catch((cause) => {
-          c.set('routesQuoteResult', {
-            candidateCount: 0,
-            outcome: 'failed',
-            quotes: [],
-          })
-          throw cause
-        })
-        const data = await RoutesProvider.getQuotes({
-          cache: { bypass: cacheBypass(c.req.raw) },
-          catalog,
-          destinationChain: query.destinationChain ?? 'tempo',
-          destinationToken: query.destinationToken,
-          onAttempt: (attempt) => attempts.push(attempt),
-          onResult: (result) => c.set('routesQuoteResult', result),
-          provider: query.provider,
-          providers,
-          quotaKey: providerQuotaKey(c),
-          sourceAmount: query.sourceAmount,
-          sourceAmountUnits: query.sourceAmountUnits,
-          sourceChain: query.sourceChain,
-          sourceToken: query.sourceToken,
-        })
+        const [catalog, policyContext] = await Promise.all([
+          RoutesCatalog.snapshot(c).catch((cause) => {
+            c.set('routesQuoteResult', {
+              candidateCount: 0,
+              outcome: 'failed',
+              quotes: [],
+            })
+            throw cause
+          }),
+          Access.loadPolicy(c),
+        ])
+        const permitted = policyContext
+          ? Access.filterCatalog(catalog, policyContext, false)
+          : catalog
+        const candidates = RoutesProvider.getQuoteCandidates({ ...query, catalog, providers })
+        const hasCandidates = candidates.some((candidate) =>
+          permitted.routes.some((entry) => entry.route === candidate.route),
+        )
+        if (!hasCandidates)
+          c.set('routesQuoteResult', { candidateCount: 0, outcome: 'unsupported', quotes: [] })
+        const data = hasCandidates
+          ? await RoutesProvider.getQuotes({
+              cache: { bypass: cacheBypass(c.req.raw) },
+              catalog: permitted,
+              destinationChain: query.destinationChain ?? 'tempo',
+              destinationToken: query.destinationToken,
+              onAttempt: (attempt) => attempts.push(attempt),
+              onResult: (result) => c.set('routesQuoteResult', result),
+              onUnavailable: (reason) => unavailable.add(reason),
+              provider: query.provider,
+              providers,
+              quotaKey: providerQuotaKey(c),
+              recipient: query.recipient,
+              sender: query.sender,
+              sourceAmount: query.sourceAmount,
+              sourceAmountUnits: query.sourceAmountUnits,
+              sourceChain: query.sourceChain,
+              sourceToken: query.sourceToken,
+            })
+          : []
         if (attempts.length > 0)
           c.set('routesProviderAttempts', attempts.map(RoutesProvider.formatAttempt))
+        if (data.length === 0) {
+          if (unavailable.size === 0) unavailable.add('route_unavailable')
+          return Response.error(c, {
+            code: 'route_unavailable',
+            details: [...unavailable].map((reason) => unavailableDetails[reason]),
+            message: 'No route is available for this request. Review the details and retry.',
+            status: 400,
+          })
+        }
         return c.json(
           Response.validated(schema.quoteRoutes.Response, {
             data,
@@ -175,6 +220,7 @@ export function quotes() {
           200,
         )
       } catch (cause) {
+        if (cause instanceof Access.PolicyError) return Access.policyError(c, cause)
         const message = requestErrorMessage(cause)
         if (message) return Response.error(c, { code: 'query_invalid', message, status: 400 })
         if (cause instanceof RoutesProvider.ProviderQuoteError) {
@@ -194,6 +240,42 @@ export function quotes() {
   )
 }
 
+const unavailableDetails = {
+  identity_required: {
+    message: 'Sender and recipient addresses are required. Provide both addresses and retry.',
+  },
+  insufficient_liquidity: {
+    message: 'There is not enough liquidity for this amount. Try a smaller amount or retry later.',
+    path: ['sourceAmount'],
+  },
+  invalid_identity: {
+    message:
+      'A sender or recipient address is invalid. Check both addresses for the selected chains and retry.',
+  },
+  price_unavailable: {
+    message: 'A current price is unavailable. Retry later to request a fresh quote.',
+  },
+  recipient_not_allowed: {
+    message:
+      'The recipient is not authorized for this route. Use an approved recipient address or request access before retrying.',
+    path: ['recipient'],
+  },
+  recipient_unsupported: {
+    message:
+      'This route cannot deliver to the requested recipient. Choose another recipient address and retry.',
+    path: ['recipient'],
+  },
+  route_unavailable: {
+    message:
+      'No quote is available for the selected route. Try another token pair or chain, or retry later.',
+  },
+  sender_not_allowed: {
+    message:
+      'The sender is not authorized for this route. Use an approved sender address or request access before retrying.',
+    path: ['sender'],
+  },
+} satisfies Record<z.output<typeof RoutesProvider.schema.UnavailableReason>, Response.error.Detail>
+
 function providerQuotaKey(c: Context<App.Environment>) {
   const principal = Auth.getPrincipal(c)
   if (!principal) return 'public:anonymous'