tapimo 0.3.0 → 0.4.0

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

@@ -187,6 +187,12 @@ export namespace schema {
           z.describe('Explainable route score from 0 to 100, when enough signals are available.'),
           z.meta({ examples: [91] }),
         ),
+      sourceDetail: z
+        .nullable(z.string())
+        .check(
+          z.describe('Provider-specific source or endpoint detail for the quality signal.'),
+          z.meta({ examples: ['providerEndpoint'] }),
+        ),
       tier: z
         .enum(['liquid', 'thin', 'unknown', 'unavailable', 'error'])
         .check(
@@ -194,7 +200,72 @@ export namespace schema {
           z.meta({ examples: ['unknown'] }),
         ),
     }),
-    'Machine-readable liquidity, fee, and freshness signals for a route candidate.',
+    'Machine-readable liquidity, fee, and source signals for a route candidate.',
+  )
+
+  /** Provider-derived quote data for a route candidate. */
+  export const RouteQuote = Schema.describe(
+    z.object({
+      expiresAt: z
+        .nullable(z.iso.datetime())
+        .check(
+          z.describe('Provider quote expiry timestamp.'),
+          z.meta({ examples: ['2026-01-01T00:00:30Z'] }),
+        ),
+      inputAmount: Schema.DecimalString.check(
+        z.describe('Source amount sent to the provider in base units.'),
+        z.meta({ examples: ['1000000'] }),
+      ),
+      limits: z
+        .nullable(
+          z.object({
+            instantSourceAmount: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Provider-reported instant source amount capacity.'),
+                z.meta({ examples: ['12453940000'] }),
+              ),
+            maxSourceAmount: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Provider-reported maximum source amount.'),
+                z.meta({ examples: ['1114274433200'] }),
+              ),
+            minSourceAmount: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Provider-reported minimum source amount.'),
+                z.meta({ examples: ['500063'] }),
+              ),
+          }),
+        )
+        .check(z.describe('Provider limits expressed in source base units.')),
+      minimumOutputAmount: z
+        .nullable(Schema.DecimalString)
+        .check(
+          z.describe('Slippage-adjusted minimum destination amount in base units.'),
+          z.meta({ examples: ['988000'] }),
+        ),
+      outputAmount: z
+        .nullable(Schema.DecimalString)
+        .check(
+          z.describe('Expected destination amount in base units.'),
+          z.meta({ examples: ['989102'] }),
+        ),
+      outputAmountFormatted: z
+        .nullable(z.string())
+        .check(
+          z.describe('Expected destination amount rendered with destination token decimals.'),
+          z.meta({ examples: ['0.989102'] }),
+        ),
+      sampledAt: z.iso
+        .datetime()
+        .check(
+          z.describe('Timestamp for the live quote or route probe.'),
+          z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
+        ),
+    }),
+    'Provider-derived quote, limit, and freshness data for a route candidate.',
   )
 
   /** Static or live funding route candidate. */
@@ -202,6 +273,12 @@ export namespace schema {
     z.object({
       destinationChain: Chain.check(z.describe('Destination chain, always Tempo mainnet in V1.')),
       destinationToken: Token.check(z.describe('Tempo token expected from this route.')),
+      errorCode: z
+        .nullable(z.string())
+        .check(
+          z.describe('Stable route error code, when status is `error`.'),
+          z.meta({ examples: ['provider_timeout'] }),
+        ),
       id: z
         .string()
         .check(
@@ -210,6 +287,9 @@ export namespace schema {
         ),
       provider: ProviderRef,
       quality: Quality,
+      quote: z
+        .nullable(RouteQuote)
+        .check(z.describe('Provider-derived quote data, when a live route probe succeeds.')),
       sourceAmount: TokenAmount,
       sourceChain: Chain.check(z.describe('Chain where the caller currently holds funds.')),
       sourceToken: Token.check(z.describe('Token the caller currently holds.')),
@@ -278,6 +358,12 @@ export namespace schema {
             ),
             z.meta({ examples: ['USDC.e'] }),
           ),
+        include: z
+          .optional(z.string())
+          .check(
+            z.describe('Comma-separated response expansions. V1 accepts `quotes`.'),
+            z.meta({ examples: ['quotes'] }),
+          ),
         limit: Schema.Limit,
         provider: z
           .optional(z.string())
@@ -380,7 +466,7 @@ const fundingRouteResponseExamples = {
       '`GET /v1/funding/routes?sourceChain=base&sourceToken=USDC&sourceAmount=1000000&provider=across`',
     summary: 'Base USDC',
     value: {
-      data: FundingRoutes.listRoutes({
+      data: FundingRoutes.listStaticRoutes({
         limit: 10,
         provider: 'across',
         sourceAmount: '1000000',
@@ -395,7 +481,7 @@ const fundingRouteResponseExamples = {
       '`GET /v1/funding/routes?sourceChain=solana&sourceToken=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&sourceAmount=1000000&provider=bridge`',
     summary: 'Solana USDC',
     value: {
-      data: FundingRoutes.listRoutes({
+      data: FundingRoutes.listStaticRoutes({
         limit: 10,
         provider: 'bridge',
         sourceAmount: '1000000',
@@ -410,7 +496,7 @@ const fundingRouteResponseExamples = {
       '`GET /v1/funding/routes?sourceChain=tron&sourceToken=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t&sourceAmount=1000000&provider=bridge`',
     summary: 'Tron USDT',
     value: {
-      data: FundingRoutes.listRoutes({
+      data: FundingRoutes.listStaticRoutes({
         limit: 10,
         provider: 'bridge',
         sourceAmount: '1000000',
@@ -433,7 +519,7 @@ const providersResponseExample = {
 } satisfies z.output<typeof schema.listProviders.Response>
 
 /** Mounts funding route discovery and generic provider inventory endpoints. */
-export function funding() {
+export function funding(options: funding.Options = {}) {
   return new Hono<App.Environment>()
     .get(
       '/v1/funding/routes',
@@ -444,7 +530,7 @@ export function funding() {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists provider-specific route candidates for moving a source stablecoin amount into Tempo. This endpoint is discovery-only: it does not execute a bridge, reserve liquidity, guarantee settlement, or return live quotes. Static inventory candidates use `status: unknown` and `quality.liquiditySource: staticInventory`.',
+          'Lists provider-specific route candidates for moving a source stablecoin amount into Tempo. This endpoint is discovery-only: it does not execute a bridge, reserve liquidity, or guarantee settlement. Static inventory candidates use `status: unknown`; provider adapters may add best-effort live quote fields.',
         operationId: 'listFundingRoutes',
         responses: OpenApi.responses({
           errors: { 400: { codes: ['query_invalid'] } },
@@ -473,10 +559,15 @@ export function funding() {
 
         const query = c.req.valid('query')
         try {
+          const include = FundingRoutes.parseInclude(query.include)
           return c.json(
             Response.validated(schema.listFundingRoutes.Response, {
-              data: FundingRoutes.listRoutes({
+              data: await FundingRoutes.listRoutes({
+                adapters: options.adapters,
+                adapterTimeoutMs: options.adapterTimeoutMs,
+                cache: { bypass: cacheBypass(c.req.raw) },
                 destinationToken: query.destinationToken,
+                include,
                 limit: query.limit,
                 provider: query.provider,
                 sourceAmount: query.sourceAmount,
@@ -564,7 +655,10 @@ export function funding() {
         const query = c.req.valid('query')
         return c.json(
           Response.validated(schema.listProviders.Response, {
-            data: FundingRoutes.listProviders({ capability: query.capability }),
+            data: FundingRoutes.listProviders({
+              adapters: options.adapters,
+              capability: query.capability,
+            }),
           }),
           200,
         )
@@ -572,9 +666,20 @@ export function funding() {
     )
 }
 
+export declare namespace funding {
+  /** Options for funding route discovery. */
+  type Options = {
+    /** Provider adapters used to enrich static inventory with live data. */
+    adapters?: FundingRoutes.ProviderAdapters | undefined
+    /** Per-provider quote timeout in milliseconds. */
+    adapterTimeoutMs?: number | undefined
+  }
+}
+
 // Maps caller-input errors to a specific 400 message; anything else rethrows.
 function requestErrorMessage(cause: unknown) {
   if (cause instanceof FundingRoutes.InvalidAmountError) return 'Invalid `sourceAmount`.'
+  if (cause instanceof FundingRoutes.UnsupportedIncludeError) return 'Unsupported `include`.'
   if (cause instanceof FundingRoutes.UnsupportedDestinationTokenError)
     return 'Unsupported `destinationToken`.'
   if (cause instanceof FundingRoutes.UnsupportedProviderError) return 'Unsupported `provider`.'
@@ -582,3 +687,12 @@ function requestErrorMessage(cause: unknown) {
     return 'Unsupported `sourceChain`.'
   return undefined
 }
+
+function cacheBypass(request: Request) {
+  const directives = (
+    request.headers.get('Cache-Control') ??
+    request.headers.get('Pragma') ??
+    ''
+  ).toLowerCase()
+  return directives.includes('no-cache') || directives.includes('no-store')
+}

package/src/apps/docs/App.ts

@@ -10,7 +10,7 @@ import * as Metadata from '../metadata.js'
  *
  * ```ts
  * import { docs } from 'tapimo/docs'
- * App.create(options).route('/', data()).route('/', platform()).route('/', docs())
+ * App.create(options).route('/', data()).route('/', management()).route('/', docs())
  * ```
  *
  * The group registers no routes itself: it carries a reference factory (via

package/src/apps/index.ts

@@ -1,4 +1,4 @@
-export { data } from './data/index.js'
+export { data, FundingRouteProviders } from './data/index.js'
+export { management } from './management/index.js'
 export { mcp } from './mcp.js'
-export { platform } from './platform/index.js'
 export { relay } from './relay/index.js'

package/src/apps/{platform → management}/App.ts

@@ -22,7 +22,7 @@ import { usage } from './routes/usage.js'
 export type Email = {
   /** Console URL embedded in email links (e.g. sign-in URLs). Defaults to the hosted console; self-hosts point it at their own. */
   consoleUrl?: string | undefined
-  /** Sender address for platform emails (e.g. `noreply@tempo.xyz`). */
+  /** Sender address for management emails (e.g. `noreply@tempo.xyz`). */
   from: string
   /** Sends one message. */
   send: (message: Email.Message) => Promise<unknown>
@@ -69,32 +69,32 @@ export type Billing = {
 }
 
 /**
- * Request environment for platform routes: the shared app environment plus the
+ * Request environment for management routes: the shared app environment plus the
  * capabilities this group publishes on context (`billing`, `email`). Owned
- * here, not in core `App.Environment`, since these are platform concerns.
+ * here, not in core `App.Environment`, since these are management concerns.
  */
 export type Environment = {
   Variables: App.Environment['Variables'] & {
     /** Stripe billing capability; undefined when billing is unconfigured. */
     billing: Billing | undefined
-    /** Transactional email sender for platform emails; undefined when dispatch is disabled. */
+    /** Transactional email sender for management emails; undefined when dispatch is disabled. */
     email: Email | undefined
   }
 }
 
 /**
- * The tenant-platform route group: the current user, orgs, projects, members,
+ * The management route group: the current user, orgs, projects, members,
  * invitations, and API-key management. Every route reads its dependencies from
  * request context set by {@link App.create}.
  *
  * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
- * {@link App.create}, so platform routes gate on a session without owning it.
+ * {@link App.create}, so management routes gate on a session without owning it.
  *
  * ```ts
- * App.create(options).route('/', platform())
+ * App.create(options).route('/', management())
  * ```
  */
-export function platform(options: platform.Options = {}) {
+export function management(options: management.Options = {}) {
   const app = new Hono<Environment>()
     // Publish this group's capabilities for handlers; undefined disables each.
     .use('*', async (c, next) => {
@@ -114,21 +114,21 @@ export function platform(options: platform.Options = {}) {
   return Metadata.attach(app, openapi)
 }
 
-export declare namespace platform {
-  /** Options for the platform route group. */
+export declare namespace management {
+  /** Options for the management route group. */
   type Options = {
     /** Expose the API-key management routes in the OpenAPI document. @default true */
     apiKeys?: boolean | undefined
     /** Stripe billing capability; omit to disable billing routes (501) and keep production sponsorship closed. */
     billing?: Billing | undefined
-    /** Transactional email sender for platform emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
+    /** Transactional email sender for management emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
     email?: Email | undefined
   }
 }
 
 /**
- * The OpenAPI metadata this group owns: platform operation tags and the
- * `session` security scheme. Tagged onto the {@link platform} instance so
+ * The OpenAPI metadata this group owns: management operation tags and the
+ * `session` security scheme. Tagged onto the {@link management} instance so
  * `App.create` collects it.
  */
 const openapi = {
@@ -152,7 +152,7 @@ const openapi = {
   ],
   'x-tagGroups': [
     {
-      name: 'Platform API',
+      name: 'Management API',
       tags: [
         'API Keys',
         'Authentication',

package/src/apps/{platform → management}/index.ts

@@ -1,2 +1,2 @@
-export { platform } from './App.js'
+export { management } from './App.js'
 export * as Billing from './Billing.js'

package/src/apps/{platform → management}/routes/api-keys.ts

@@ -494,7 +494,7 @@ export declare namespace apiKeys {
   }
 }
 
-/** Projects a persisted record onto the platform key shape (no rate limits, no token). */
+/** Projects a persisted record onto the management key shape (no rate limits, no token). */
 function serializeKey(record: ApiKeys.Record) {
   return {
     createdAt: record.createdAt,

package/src/apps/{platform → management}/routes/invitations.ts

@@ -206,7 +206,7 @@ export namespace schema {
  * Mounts the invitations surface: org-scoped management
  * (`/orgs/:orgId/invitations`, admins and owners) plus the invitee's side
  * (`/invitations`, matched against the session's verified email). Invitation
- * emails dispatch through the sender the platform group publishes on context
+ * emails dispatch through the sender the management group publishes on context
  * (`c.get('email')`), best-effort.
  */
 export function invitations() {

package/src/apps/mcp.test.ts

@@ -114,7 +114,7 @@ test('scopes tools to the data domain', async () => {
   expect(tools).toContain('docs_search')
   // RPC is part of the data domain tag group.
   expect(tools.some((name) => name.startsWith('rpc'))).toBe(true)
-  // Out of domain: CoinGecko mirrors, session auth, platform, relay.
+  // Out of domain: CoinGecko mirrors, session auth, management, relay.
   expect(tools.some((name) => name.startsWith('gecko_'))).toBe(false)
   expect(tools.some((name) => name.startsWith('v1_auth_'))).toBe(false)
   expect(tools.some((name) => name.startsWith('v1_orgs'))).toBe(false)

package/src/apps/mcp.ts

@@ -201,7 +201,7 @@ const methods: readonly string[] = ['delete', 'get', 'head', 'options', 'patch',
 
 /**
  * Narrows the document to the data domain: operations tagged inside the
- * `Data API` tag group, minus excluded tags. Platform, relay, and session
+ * `Data API` tag group, minus excluded tags. Management, relay, and session
  * operations never surface as tools.
  */
 function scope(document: Document): Openapi.OpenAPISpec {

package/src/apps/relay/App.test.ts

@@ -16,7 +16,7 @@ import * as Fees from '../../internal/Fees.js'
 import * as Organizations from '../../db/tables/organizations.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
-import * as core_Billing from '../platform/Billing.js'
+import * as core_Billing from '../management/Billing.js'
 import * as RequestListener from '../../handlers/internal/requestListener.js'
 import * as Viem from '../../internal/Viem.js'
 import * as Sponsorships from './Sponsorships.js'

package/src/apps/relay/App.ts

@@ -8,7 +8,7 @@ import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
-import * as Billing from '../platform/Billing.js'
+import * as Billing from '../management/Billing.js'
 import * as Handler from '../../Handler.js'
 import * as Auth from '../../internal/Auth.js'
 import * as OpenApi from '../../internal/OpenApi.js'

package/src/internal/Auth.ts

@@ -882,7 +882,7 @@ export function install(options: install.Options) {
       }),
     )
     return Object.assign(
-      // The tag joins the `Platform API` group at `platform()`'s chosen slot;
+      // The tag joins the `Management API` group at `management()`'s chosen slot;
       // group listings filter to defined tags, so it drops out when unmounted.
       Metadata.attach(app.route('/v1/auth/siwe', handler), {
         tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],

package/src/internal/EdgeCache.ts

@@ -74,7 +74,7 @@ export function middleware<environment extends Env>(
   return async (c, next) => {
     const { store } = options
     // Pay the store lookup only when a matched handler is marked cacheable
-    // (mounted `Cache.response`); other GETs (authed platform routes, docs,
+    // (mounted `Cache.response`); other GETs (authed management routes, docs,
     // 404s) can never hit, so the read would be a wasted round trip.
     const eligible =
       store !== undefined &&

package/src/internal/FundingRoutes.test.ts

@@ -0,0 +1,213 @@
+import * as FundingRoutes from './FundingRoutes.js'
+
+const baseUsdcRequest = {
+  limit: 10,
+  provider: 'across',
+  sourceAmount: '1000000',
+  sourceAmountUnits: 'baseUnits',
+  sourceChain: 'base',
+  sourceToken: 'USDC',
+} as const
+
+describe('listRoutes', () => {
+  test('enriches static candidates with adapter quote probes', async () => {
+    let seen: FundingRoutes.QuoteProbeInput | undefined
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote(input, signal) {
+            seen = input
+            expect(signal.aborted).toBe(false)
+            expect(input.cache.bypass).toBe(false)
+            expect(input.destinationChain.id).toBe('eip155:4217')
+            expect(input.destinationToken.symbol).toBe('USDC.e')
+            expect(input.include).toEqual([])
+            expect(input.request.sourceChain).toBe('base')
+            return {
+              expiresAt: '2026-01-01T00:00:30Z',
+              limits: {
+                instantSourceAmount: '1000000000',
+                maxSourceAmount: '100000000000',
+                minSourceAmount: '500000',
+              },
+              minimumOutputAmount: '980000',
+              outputAmount: '990000',
+              outputAmountFormatted: '0.99',
+              quality: {
+                availableVolumeUsd: '1000.00',
+                estimatedSeconds: 4,
+                feeBps: 12,
+                historicalVolumeUsd24h: '100000.00',
+                instantVolumeUsd: '1000.00',
+                liquiditySource: 'providerQuote',
+                score: 91,
+                sourceDetail: 'providerEndpoint',
+                tier: 'liquid',
+              },
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'available',
+            }
+          },
+        },
+      },
+    })
+
+    expect(seen?.route.id).toBe('base-usdc-tempo-usdce-across')
+    expect(seen?.sourceAmount.amount).toBe('1000000')
+    expect(seen?.sourceChain.id).toBe('eip155:8453')
+    expect(seen?.sourceToken.symbol).toBe('USDC')
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({
+      errorCode: null,
+      id: 'base-usdc-tempo-usdce-across',
+      quality: {
+        availableVolumeUsd: '1000.00',
+        estimatedSeconds: 4,
+        feeBps: 12,
+        historicalVolumeUsd24h: '100000.00',
+        instantVolumeUsd: '1000.00',
+        liquiditySource: 'providerQuote',
+        score: 91,
+        sourceDetail: 'providerEndpoint',
+        tier: 'liquid',
+      },
+      quote: {
+        expiresAt: '2026-01-01T00:00:30Z',
+        inputAmount: '1000000',
+        limits: {
+          instantSourceAmount: '1000000000',
+          maxSourceAmount: '100000000000',
+          minSourceAmount: '500000',
+        },
+        minimumOutputAmount: '980000',
+        outputAmount: '990000',
+        outputAmountFormatted: '0.99',
+        sampledAt: '2026-01-01T00:00:00Z',
+      },
+      status: 'available',
+    })
+  })
+
+  test('leaves candidates static when their provider has no adapter', async () => {
+    let calls = 0
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote() {
+            calls += 1
+            throw new Error('unexpected call')
+          },
+        },
+      },
+    })
+
+    expect(calls).toBe(0)
+    expect(routes[0]).toMatchObject({
+      quality: {
+        liquiditySource: 'staticInventory',
+        sourceDetail: null,
+        tier: 'unknown',
+      },
+      quote: null,
+      status: 'unknown',
+    })
+  })
+
+  test('marks candidates as errors when an adapter throws', async () => {
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote() {
+            throw new Error('upstream unavailable')
+          },
+        },
+      },
+    })
+
+    expect(routes[0]).toMatchObject({
+      errorCode: 'provider_error',
+      quality: {
+        liquiditySource: 'providerError',
+        sourceDetail: null,
+        tier: 'error',
+      },
+      quote: null,
+      status: 'error',
+    })
+  })
+
+  test('aborts slow adapters and marks candidates as timed-out errors', async () => {
+    let aborted = false
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapterTimeoutMs: 1,
+      adapters: {
+        across: {
+          probeQuote(_input, signal) {
+            signal.addEventListener('abort', () => {
+              aborted = true
+            })
+            return new Promise<FundingRoutes.QuoteProbeResult>(() => {})
+          },
+        },
+      },
+    })
+
+    expect(aborted).toBe(true)
+    expect(routes[0]).toMatchObject({
+      errorCode: 'provider_timeout',
+      quality: {
+        liquiditySource: 'providerError',
+        sourceDetail: null,
+        tier: 'error',
+      },
+      quote: null,
+      status: 'error',
+    })
+  })
+
+  test('passes include and cache policy through to adapters', async () => {
+    let seen: FundingRoutes.QuoteProbeInput | undefined
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote(input) {
+            seen = input
+            return {
+              errorCode: 'provider_unavailable',
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'error',
+            }
+          },
+        },
+      },
+      cache: { bypass: true },
+      include: ['quotes'],
+    })
+
+    expect(seen?.cache.bypass).toBe(true)
+    expect(seen?.include).toEqual(['quotes'])
+    expect(seen?.request.include).toEqual(['quotes'])
+    expect(routes[0]).toMatchObject({
+      errorCode: 'provider_unavailable',
+      quote: null,
+      status: 'error',
+    })
+  })
+})
+
+describe('parseInclude', () => {
+  test('parses comma-separated include values', () => {
+    expect(FundingRoutes.parseInclude('quotes,quotes')).toEqual(['quotes'])
+  })
+
+  test('rejects unsupported include values', () => {
+    expect(() => FundingRoutes.parseInclude('quotes,debug')).toThrow(
+      FundingRoutes.UnsupportedIncludeError,
+    )
+  })
+})