import { type Context, Hono } from 'hono'
import { etag } from 'hono/etag'
import * as z from 'zod/mini'

import type * as App from '../../../App.js'
import * as Db from '../../../db/Db.js'
import * as FundingIdempotency from '../../../db/tables/fundingIdempotency.js'
import * as FundingTransfers from '../../../db/tables/fundingTransfers.js'
import * as Auth from '../../../internal/Auth.js'
import * as Cache from '../../../internal/Cache.js'
import * as FundingCatalog from '../../../internal/funding/Catalog.js'
import * as FundingProvider from '../../../internal/funding/Provider.js'
import * as FundingTransfer from '../../../internal/funding/Transfer.js'
import * as FundingTransferReconciliation from '../../../internal/funding/TransferReconciliation.js'
import * as Idempotency from '../../../internal/Idempotency.js'
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 type * as Webhooks from '../../../internal/Webhooks.js'
import * as Access from '../Access.js'
import * as ProviderAttempts from '../ProviderAttempts.js'

/** Zod schemas owned by funding transfer resources. */
export namespace schema {
  /** A durable funding transfer. Reads never include the executable `action`. */
  export const Transfer = FundingTransfer.schema.FundingTransfer
  /** Schemas for the listFundingTransfers operation. */
  export namespace listFundingTransfers {
    /** Query parameters for listing funding transfers. */
    export const Query = z
      .object({
        cursor: Schema.Cursor,
        include: Schema.totalCountInclude,
        limit: Schema.Limit,
        status: z.optional(FundingTransfer.schema.Status),
      })
      .check(z.describe('Query parameters for listing funding transfers.'))

    /** Paginated funding transfer list. */
    export const Response = OpenApi.component(
      z
        .object({
          data: z
            .array(Transfer)
            .check(z.describe('Funding transfers 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 funding transfers.')),
      'FundingTransferList',
    )
  }

  /** Schemas for the createFundingTransfer operation. */
  export namespace createFundingTransfer {
    /** Funding transfer creation request body. */
    export const Body = FundingTransfer.schema.CreateRequest

    /** Required headers for funding transfer creation. */
    export const Headers = z.object({
      'idempotency-key': z
        .string()
        .check(
          z.minLength(1),
          z.describe(
            'Opaque retry key scoped to the API key. Matching requests replay successful responses for 24 hours; changed input conflicts, in-flight requests block, and failed attempts release the key.',
          ),
          z.meta({ examples: ['funding_01k1c5j8q8p0be6j5v9m6d1e4r'] }),
        ),
    })

    /** The created transfer with its one-time executable action. */
    export const Response = FundingTransfer.schema.CreatedFundingTransfer
  }

  const destinationCreateFields = {
    amount: FundingTransfer.schema.CreateRequest.shape.amount,
    mode: FundingTransfer.schema.CreateRequest.shape.mode,
    recipient: FundingTransfer.schema.CreateRequest.shape.recipient,
    sender: FundingTransfer.schema.CreateRequest.shape.sender,
    slippageBps: FundingTransfer.schema.CreateRequest.shape.slippageBps,
    sourceChain: FundingTransfer.schema.CreateRequest.shape.sourceChain,
    sourceToken: FundingTransfer.schema.CreateRequest.shape.sourceToken,
  }

  /** Schemas for the createFundingTransferVault operation. */
  export namespace createFundingTransferVault {
    /** Funding transfer creation request for an Earn vault destination. */
    export const Body = OpenApi.component(
      z
        .strictObject({
          ...destinationCreateFields,
          vaultAddress: z
            .string()
            .check(
              z.regex(/^0x[0-9a-fA-F]{40}$/),
              z.describe('Tempo Earn vault contract address.'),
              z.meta({ examples: [`0x${'f4'.repeat(20)}`] }),
            ),
        })
        .check(z.describe('Vault funding transfer creation request.')),
      'CreateFundingTransferVaultRequest',
    )

    /** Required headers for vault funding transfer creation. */
    export const Headers = createFundingTransfer.Headers
  }

  /** Schemas for the createFundingTransferZone operation. */
  export namespace createFundingTransferZone {
    /** Funding transfer creation request for a Zone destination. */
    export const Body = OpenApi.component(
      z
        .strictObject({
          amount: destinationCreateFields.amount,
          destinationChain: z
            .string()
            .check(
              z.regex(/^eip155:\d+$/),
              z.describe('Configured Zone CAIP-2 id.'),
              z.meta({ examples: ['eip155:1424310003'] }),
            ),
          destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
          mode: destinationCreateFields.mode,
          recipient: destinationCreateFields.recipient,
          recipientFallback: z
            .string()
            .check(
              z.regex(/^0x[0-9a-fA-F]{40}$/),
              z.describe('Public Tempo recipient used if the Zone credit cannot complete.'),
              z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
            ),
          sender: destinationCreateFields.sender,
          slippageBps: destinationCreateFields.slippageBps,
          sourceChain: destinationCreateFields.sourceChain,
          sourceToken: destinationCreateFields.sourceToken,
        })
        .check(z.describe('Zone funding transfer creation request.')),
      'CreateFundingTransferZoneRequest',
    )

    /** Required headers for Zone funding transfer creation. */
    export const Headers = createFundingTransfer.Headers
  }

  /** Schemas for the getFundingTransfer operation. */
  export namespace getFundingTransfer {
    /** Path parameters for a funding transfer read. */
    export const Params = z
      .object({
        id: z
          .string()
          .check(
            z.describe('Funding transfer ID (`ftr_…`).'),
            z.meta({ examples: ['ftr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
          ),
      })
      .check(z.describe('Path parameters for a funding transfer request.'))

    /** The funding transfer resource, returned directly. */
    export const Response = Transfer
  }

  /** Schemas for the registerFundingTransferSourceTransaction operation. */
  export namespace registerFundingTransferSourceTransaction {
    /** Source transaction registration request body. */
    export const Body = OpenApi.component(
      z
        .strictObject({
          transactionHash: Schema.hash(`0x${'51'.repeat(32)}`),
        })
        .check(z.describe('Verified source transaction to associate with the transfer.')),
      'RegisterFundingTransferSourceTransactionRequest',
    )

    /** Path parameters for source transaction registration. */
    export const Params = getFundingTransfer.Params

    /** The transfer after source transaction registration. */
    export const Response = Transfer
  }
}

const baseChainExample = {
  addressFormat: 'hex',
  id: 'eip155:8453',
  kind: 'evm',
  name: 'Base',
} as const

const baseUsdcExample = {
  address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  currency: 'USD',
  decimals: 6,
  name: 'USD Coin',
  standard: 'ERC-20',
  symbol: 'USDC',
  tokenKey: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  verified: true,
} as const

const fundingTransferExample = {
  createdAt: '2026-01-01T00:00:00.000Z',
  destinationAmount: Value.tokenAmount({ baseUnits: '979295', currency: 'USD', decimals: 6 }),
  destinationAmountMin: Value.tokenAmount({ baseUnits: '939242', currency: 'USD', decimals: 6 }),
  destinationChain: {
    addressFormat: 'hex',
    id: 'eip155:4217',
    kind: 'evm',
    name: 'Tempo',
  },
  destinationToken: {
    address: '0x20c0000000000000000000000000000000000000',
    currency: 'USD',
    decimals: 6,
    name: 'PathUSD',
    standard: 'TIP-20',
    symbol: 'pathUSD',
    tokenKey: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
    verified: true,
  },
  fees: [
    {
      amount: Value.tokenAmount({ baseUnits: '20705', currency: 'USD', decimals: 6 }),
      side: 'source',
      token: baseUsdcExample,
      type: 'provider',
    },
  ],
  id: 'ftr_001767225600000_2ZPE2gvateYEQ0dQslgvkhjx',
  method: 'transaction',
  mode: 'exactSource',
  provider: { id: 'relay', name: 'Relay' },
  quote: {
    expiresAt: '2026-01-01T00:01:00.000Z',
    sampledAt: '2026-01-01T00:00:00.000Z',
  },
  recipient: `0x${'11'.repeat(20)}`,
  sender: `0x${'22'.repeat(20)}`,
  sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
  sourceChain: baseChainExample,
  sourceToken: baseUsdcExample,
  status: 'awaiting-source',
  updatedAt: '2026-01-01T00:00:00.000Z',
  version: 1,
} satisfies z.output<typeof schema.Transfer>

const registeredFundingTransferExample = {
  ...fundingTransferExample,
  sourceTransactionHashes: [`0x${'51'.repeat(32)}`],
  status: 'processing',
  updatedAt: '2026-01-01T00:00:20.000Z',
  version: 2,
} satisfies z.output<typeof schema.registerFundingTransferSourceTransaction.Response>

const listFundingTransfersResponseExample = {
  data: [fundingTransferExample],
  nextCursor: null,
} satisfies z.output<typeof schema.listFundingTransfers.Response>

const createdFundingTransferExample = {
  action: {
    calls: [
      {
        data: `0x095ea7b3000000000000000000000000${'44'.repeat(20)}00000000000000000000000000000000000000000000000000000000000f4240`,
        to: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
        value: '0x0',
      },
      {
        data: '0xe8017952',
        to: `0x${'44'.repeat(20)}`,
        value: '0x0',
      },
    ],
    type: 'evm:calls',
  },
  ...fundingTransferExample,
} satisfies z.output<typeof schema.createFundingTransfer.Response>

const unimplementedFundingTransferResponses = (() => {
  const responses = OpenApi.responses({
    errors: {
      400: { codes: ['body_invalid', 'idempotency_key_required'] },
      501: {
        codes: ['not_implemented'],
        description: 'This funding transfer destination is not implemented.',
      },
    },
    success: {
      description: 'Unused until this destination is implemented.',
      schema: z.never(),
    },
  })
  const { 200: success, 502: upstream, ...errors } = responses
  void success
  void upstream
  return errors
})()

// Replay the exact successful creation response for 24 hours.
const idempotencyReplayTtlMs = 86_400_000
// Pending claims only cover the bounded provider preparation window.
const idempotencyPendingTtlMs = 60_000
const fundingEtag = etag()
const bodyValidation = {
  code: 'body_invalid',
  message: 'Check the request body and try again.',
} as const
const paramValidation = {
  code: 'param_invalid',
  message: 'Check the path parameters and try again.',
} as const

/** Mounts durable funding transfer routes. */
export function transfers(options: transfers.Options = {}) {
  return new Hono<App.Environment>()
    .get(
      '/v1/funding/transfers',
      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
      OpenApi.validate('query', schema.listFundingTransfers.Query, {
        code: 'query_invalid',
        message: 'Check the query parameters and try again.',
      }),
      OpenApi.describeRoute({
        description: 'Lists transfers from newest to oldest.',
        operationId: 'listFundingTransfers',
        responses: OpenApi.responses({
          errors: {
            400: { codes: ['query_invalid'] },
          },
          success: {
            description: 'A page of funding transfers.',
            example: listFundingTransfersResponseExample,
            schema: schema.listFundingTransfers.Response,
          },
        }),
        summary: 'List transfers',
        tags: ['Funding Transfers'],
      }),
      fundingEtag,
      async (c) => {
        if (Auth.narrowAccess) return Auth.accessError(c)
        if (OpenApi.narrowValidation)
          return OpenApi.validationError(c, {
            code: 'query_invalid',
            message: 'Check the query parameters and try again.',
          })

        const owner = Access.owner(c)
        if (!owner) return Access.unauthorized(c)

        const db = Db.get(c.get('db'))
        const { cursor, include, limit, status } = c.req.valid('query')
        try {
          // `totalCount` is opt-in and capped (a capped subquery shares the
          // list filter); run it concurrently with the page list. Best-effort:
          // a failure omits `meta` rather than failing the page.
          const countPromise = include.includes('totalCount')
            ? FundingTransfers.count(db, owner, { cap: Schema.countCap, status }).catch(() => {
                c.set('fundingTransferCountFailed', true)
                return undefined
              })
            : undefined

          // Fetch one extra to detect a further page without a second round-trip.
          const rows = await FundingTransfers.list(db, owner, { cursor, limit: limit + 1, status })
          const hasMore = rows.length > limit
          const data = (hasMore ? rows.slice(0, limit) : rows).map(FundingTransfer.toPublic)
          const nextCursor = hasMore ? (data[data.length - 1]?.id ?? null) : null

          const count = countPromise ? await countPromise : undefined

          c.header('Cache-Control', Cache.policies.feed)
          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')

          return c.json(
            Response.validated(schema.listFundingTransfers.Response, {
              data,
              ...(count !== undefined
                ? {
                    meta: {
                      totalCountCapped: count > Schema.countCap,
                      totalCount: Math.min(count, Schema.countCap),
                    },
                  }
                : {}),
              nextCursor,
            }),
            200,
          )
        } catch (cause) {
          return Response.upstream(c, cause)
        }
      },
    )
    .get(
      '/v1/funding/transfers/:id{ftr_[A-Za-z0-9_-]+}',
      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
      OpenApi.validate('param', schema.getFundingTransfer.Params, {
        code: 'param_invalid',
        message: 'Check the path parameters and try again.',
      }),
      OpenApi.describeRoute({
        description: 'Returns a transfer by ID.',
        operationId: 'getFundingTransfer',
        responses: OpenApi.responses({
          errors: {
            400: { codes: ['param_invalid'] },
            404: {
              codes: ['funding_transfer_not_found'],
              description: 'No visible funding transfer exists for the identifier.',
            },
          },
          success: {
            description: 'The requested funding transfer.',
            example: fundingTransferExample,
            schema: schema.getFundingTransfer.Response,
          },
        }),
        summary: 'Get transfer',
        tags: ['Funding Transfers'],
      }),
      async (c) => {
        if (Auth.narrowAccess) return Auth.accessError(c)
        if (OpenApi.narrowValidation)
          return OpenApi.validationError(c, {
            code: 'param_invalid',
            message: 'Check the path parameters and try again.',
          })

        const owner = Access.owner(c)
        if (!owner) return Access.unauthorized(c)

        const db = Db.get(c.get('db'))
        const { id } = c.req.valid('param')
        try {
          // Ownership filters in SQL, so absent and foreign rows are the same 404.
          const record = await FundingTransfers.getOwned(db, owner, id)
          if (!record)
            return Response.error(c, {
              code: 'funding_transfer_not_found',
              message: 'Funding transfer not found',
              status: 404,
            })
          c.header('Cache-Control', Cache.policies.noStore)
          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')
          return c.json(
            Response.validated(
              schema.getFundingTransfer.Response,
              FundingTransfer.toPublic(record),
            ),
            200,
          )
        } catch (cause) {
          return Response.upstream(c, cause)
        }
      },
    )
    .post(
      '/v1/funding/transfers/:id{ftr_[A-Za-z0-9_-]+}/source-transactions',
      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
      OpenApi.validate(
        'param',
        schema.registerFundingTransferSourceTransaction.Params,
        paramValidation,
      ),
      OpenApi.validate(
        'json',
        schema.registerFundingTransferSourceTransaction.Body,
        bodyValidation,
      ),
      OpenApi.describeRoute({
        description: 'Registers and verifies a funding source transaction.',
        operationId: 'registerFundingTransferSourceTransaction',
        responses: OpenApi.responses({
          errors: {
            400: {
              codes: ['body_invalid', 'param_invalid', 'source_transaction_invalid'],
              description: 'The path, body, or submitted source transaction is invalid.',
            },
            404: {
              codes: ['funding_transfer_not_found'],
              description: 'No visible funding transfer exists for the identifier.',
            },
            409: {
              codes: [
                'funding_transfer_not_awaiting_source',
                'source_transaction_conflict',
                'source_transaction_pending',
              ],
              description: 'The transfer or source transaction cannot be registered yet.',
            },
            501: {
              codes: ['not_implemented'],
              description: 'Source transaction reconciliation is not configured.',
            },
            502: {
              codes: ['upstream_error'],
              description: 'Source verification or reconciliation dispatch failed.',
            },
          },
          success: {
            description: 'The transfer with its verified source transaction.',
            example: registeredFundingTransferExample,
            schema: schema.registerFundingTransferSourceTransaction.Response,
          },
        }),
        summary: 'Register source transaction',
        tags: ['Funding Transfers'],
      }),
      async (c) => {
        if (Auth.narrowAccess) return Auth.accessError(c)
        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)

        const owner = Access.owner(c)
        if (!owner) return Access.unauthorized(c)
        c.header('Cache-Control', Cache.policies.noStore)
        c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')

        const dispatch = options.dispatchTransferReconciliation
        if (!dispatch)
          return Response.error(c, {
            code: 'not_implemented',
            message: 'Source transaction reconciliation is not configured',
            status: 501,
          })

        const db = Db.get(c.get('db'))
        const { id } = c.req.valid('param')
        const { transactionHash } = c.req.valid('json')
        try {
          const record = await FundingTransfers.getOwned(db, owner, id)
          if (!record)
            return Response.error(c, {
              code: 'funding_transfer_not_found',
              message: 'Funding transfer not found',
              status: 404,
            })
          if (
            record.snapshot.sourceTransactionHashes?.some(
              (candidate) => candidate.toLowerCase() === transactionHash,
            )
          ) {
            if (record.status === 'processing')
              await dispatch({ transferId: record.id, type: 'funding:transfer:reconcile' })
            return c.json(
              Response.validated(
                schema.registerFundingTransferSourceTransaction.Response,
                FundingTransfer.toPublic(record),
              ),
              200,
            )
          }
          const provider = c
            .get('providers')
            .filter(FundingProvider.is)
            .find((candidate) => candidate.id === record.providerId)
          if (!provider || !FundingProvider.canVerifySourceTransaction(provider))
            return Response.error(c, {
              code: 'funding_transfer_not_awaiting_source',
              message: 'Funding transfer does not accept source transactions',
              status: 409,
            })
          if (record.status !== 'awaiting-source')
            return Response.error(c, {
              code: 'funding_transfer_not_awaiting_source',
              message: 'Funding transfer is not awaiting a source transaction',
              status: 409,
            })

          const catalog = await FundingCatalog.snapshot(c)
          const destinationChain = catalog.chainsByKey.get(record.snapshot.destinationChain.id)
          const sourceChain = catalog.chainsByKey.get(record.snapshot.sourceChain.id)
          const routeConfiguration = catalog.routesByProvider
            .get(record.providerId)
            ?.find(
              (candidate) =>
                candidate.route.source.chain.id === record.snapshot.sourceChain.id &&
                candidate.route.source.address.toLowerCase() ===
                  record.snapshot.sourceToken.address.toLowerCase() &&
                candidate.route.destination.chain.id === record.snapshot.destinationChain.id &&
                candidate.route.destination.address.toLowerCase() ===
                  record.snapshot.destinationToken.address.toLowerCase(),
            )?.configuration
          if (!destinationChain || !sourceChain)
            return Response.error(c, {
              code: 'funding_transfer_not_awaiting_source',
              message: 'Funding transfer route chains are no longer configured',
              status: 409,
            })

          const evidence = await provider.verifySourceTransaction(
            {
              destinationChain,
              providerState: record.providerState ?? undefined,
              routeConfiguration,
              sourceChain,
              transactionHash,
              transfer: record.snapshot,
            },
            c.req.raw.signal,
          )
          if (evidence.type === 'pending')
            return Response.error(c, {
              code: 'source_transaction_pending',
              message: 'Source transaction is not confirmed yet',
              status: 409,
            })
          if (evidence.type === 'invalid')
            return Response.error(c, {
              code: 'source_transaction_invalid',
              message: 'Source transaction does not match the funding transfer',
              status: 400,
            })

          const registered = await FundingTransfer.registerSourceTransaction(db, {
            chainId: record.snapshot.sourceChain.id,
            id: record.id,
            providerState: evidence.providerState ?? {},
            transactionHash,
          })
          if (registered.type === 'not_found')
            return Response.error(c, {
              code: 'funding_transfer_not_found',
              message: 'Funding transfer not found',
              status: 404,
            })
          if (registered.type === 'conflict')
            return Response.error(c, {
              code: 'source_transaction_conflict',
              message: 'Source transaction is already assigned to another funding transfer',
              status: 409,
            })
          if (registered.type === 'invalid')
            return Response.error(c, {
              code: 'funding_transfer_not_awaiting_source',
              message: 'Funding transfer is not awaiting a source transaction',
              status: 409,
            })

          await Promise.all([
            dispatch({ transferId: record.id, type: 'funding:transfer:reconcile' }),
            registered.type === 'registered' &&
            options.dispatchTransferUpdates &&
            registered.references.length > 0
              ? options.dispatchTransferUpdates(registered.references)
              : undefined,
          ])
          return c.json(
            Response.validated(
              schema.registerFundingTransferSourceTransaction.Response,
              FundingTransfer.toPublic(registered.record),
            ),
            200,
          )
        } catch (cause) {
          return Response.upstream(c, cause)
        }
      },
    )
    .post(
      '/v1/funding/transfers',
      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
      OpenApi.validate('header', schema.createFundingTransfer.Headers, {
        code: 'idempotency_key_required',
        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
      }),
      OpenApi.validate('json', schema.createFundingTransfer.Body, {
        code: 'body_invalid',
        message: 'Check the request body and try again.',
      }),
      OpenApi.describeRoute({
        description: 'Creates a transfer to a Tempo account.',
        operationId: 'createFundingTransfer',
        responses: OpenApi.responses({
          errors: {
            400: { codes: ['body_invalid', 'idempotency_key_required'] },
            404: {
              codes: ['quote_not_available'],
              description: 'No provider can prepare the requested route.',
            },
            409: {
              codes: ['idempotency_conflict', 'idempotency_in_progress'],
              description: 'The Idempotency-Key conflicts with an existing or in-flight request.',
            },
            502: {
              codes: ['upstream_error'],
              description: 'No provider succeeded and at least one failed unexpectedly.',
            },
          },
          success: {
            description: 'The created funding transfer with its one-time executable action.',
            example: createdFundingTransferExample,
            schema: schema.createFundingTransfer.Response,
          },
        }),
        summary: 'Create transfer',
        tags: ['Funding Transfers'],
      }),
      async (c) => {
        if (Auth.narrowAccess) return Auth.accessError(c)
        if (OpenApi.narrowValidation)
          return OpenApi.validationError(c, {
            code: 'body_invalid',
            message: 'Check the request body and try again.',
          })

        const principal = Auth.getPrincipal(c)
        const owner = Access.owner(c)
        if (!owner || principal?.type !== 'api_key') return Access.unauthorized(c)
        c.header('Cache-Control', 'no-store')

        const idempotencyKey = c.req.valid('header')['idempotency-key']

        const body = c.req.valid('json')
        const db = Db.get(c.get('db'))
        const identity = {
          apiKeyId: principal.id,
          keyHash: Idempotency.inputHash(idempotencyKey),
          requestHash: Idempotency.inputHash(body),
        }
        const claim = await FundingIdempotency.claim(db, {
          ...identity,
          ttlMs: idempotencyPendingTtlMs,
        })
        if (claim.type === 'mismatch')
          return Response.error(c, {
            code: 'idempotency_conflict',
            message: 'This Idempotency-Key was already used with different input.',
            status: 409,
          })
        if (claim.type === 'pending')
          return Response.error(c, {
            code: 'idempotency_in_progress',
            message: 'An equivalent funding transfer creation is still running.',
            status: 409,
          })
        if (claim.type === 'replay')
          return c.json(
            JSON.parse(claim.response) as z.output<typeof schema.createFundingTransfer.Response>,
            200,
          )

        const release = async () => {
          try {
            await FundingIdempotency.release(db, {
              apiKeyId: identity.apiKeyId,
              createdAt: claim.createdAt,
              keyHash: identity.keyHash,
            })
          } catch {
            // The pending claim expires on its own; the response stays authoritative.
          }
        }
        try {
          const attempts: FundingProvider.ProviderAttempt[] = []
          const catalog = await FundingCatalog.snapshot(c)
          const providers = c.get('providers').filter(FundingProvider.is)
          const selected = await FundingProvider.prepareTransfer({
            catalog,
            destinationChainId: c.get('chainId'),
            destinationToken: body.destinationToken,
            method: 'transaction',
            mode: body.mode,
            onAttempt: (attempt) => attempts.push(attempt),
            provider: body.provider,
            providers,
            recipient: body.recipient,
            sender: body.sender,
            slippageBps: body.slippageBps,
            sourceAmount: body.amount,
            sourceChain: body.sourceChain,
            sourceToken: body.sourceToken,
          })
          if (attempts.length > 0)
            c.set('fundingProviderAttempts', attempts.map(ProviderAttempts.format))
          if (!selected) {
            await release()
            return quoteNotAvailable(c)
          }

          const { candidate, result } = selected
          const snapshot: FundingTransfer.Snapshot = {
            destinationAmount: Value.tokenAmount({
              baseUnits: result.destinationAmount,
              currency: candidate.destinationToken.currency,
              decimals: candidate.destinationToken.decimals,
            }),
            destinationAmountMin: Value.tokenAmount({
              baseUnits: result.destinationAmountMin,
              currency: candidate.destinationToken.currency,
              decimals: candidate.destinationToken.decimals,
            }),
            destinationChain: candidate.destinationChain,
            destinationToken: candidate.destinationToken,
            fees: result.fees.map((fee) => {
              const token =
                fee.token ??
                (fee.side === 'source' ? candidate.sourceToken : candidate.destinationToken)
              return {
                amount: Value.tokenAmount({
                  baseUnits: fee.amount,
                  currency: token.currency,
                  decimals: token.decimals,
                }),
                side: fee.side,
                token,
                type: 'provider',
              }
            }),
            method: 'transaction',
            mode: body.mode,
            provider: candidate.provider,
            quote: { expiresAt: result.expiresAt, sampledAt: result.sampledAt },
            recipient: body.recipient,
            sender: body.sender,
            sourceAmount: Value.tokenAmount({
              baseUnits: candidate.sourceAmount.amount,
              currency: candidate.sourceToken.currency,
              decimals: candidate.sourceToken.decimals,
            }),
            sourceChain: candidate.sourceChain,
            sourceToken: candidate.sourceToken,
          }

          // The transfer row, its version-1 event, and the replay body commit
          // atomically so a crash cannot leave a claimed key without a replay.
          const created = await db.transaction(async (tx) => {
            const { record, references } = await FundingTransfer.createIn(tx, {
              apiKeyId: principal.id,
              environment: owner.environment,
              orgId: owner.orgId,
              projectId: owner.projectId,
              providerState:
                result.correlation || result.providerState
                  ? {
                      ...result.correlation,
                      ...result.providerState,
                    }
                  : undefined,
              snapshot,
            })
            const validated = Response.validated(
              schema.createFundingTransfer.Response,
              FundingTransfer.toCreated(record, result.action),
            )
            const completion = await FundingIdempotency.complete(tx, {
              apiKeyId: identity.apiKeyId,
              createdAt: claim.createdAt,
              keyHash: identity.keyHash,
              replayTtlMs: idempotencyReplayTtlMs,
              response: JSON.stringify(validated),
              transferId: record.id,
            })
            if (!completion)
              throw new IdempotencyLeaseLostError('Funding transfer creation lease was lost.')
            return { references, response: validated }
          })
          if (options.dispatchTransferUpdates && created.references.length > 0)
            try {
              await options.dispatchTransferUpdates(created.references)
            } catch (cause) {
              return Response.upstream(c, cause)
            }
          return c.json(created.response, 200)
        } catch (cause) {
          await release()
          if (cause instanceof FundingProvider.InvalidAmountError)
            return Response.error(c, { code: 'body_invalid', message: 'Invalid `amount`.', status: 400 }) // prettier-ignore
          if (cause instanceof FundingProvider.UnsupportedProviderError)
            return Response.error(c, { code: 'body_invalid', message: 'Unsupported `provider`.', status: 400 }) // prettier-ignore
          if (cause instanceof FundingProvider.UnsupportedSourceChainError)
            return quoteNotAvailable(c)
          if (cause instanceof FundingProvider.ProviderQuoteError) {
            if (cause.fundingProviderAttempts.length > 0)
              c.set('fundingProviderAttempts', cause.fundingProviderAttempts)
            if (cause.providerFailure) c.set('providerFailure', cause.providerFailure)
            if (cause.providerFailures) c.set('providerFailures', cause.providerFailures)
            return Response.error(c, {
              code: 'upstream_error',
              message: 'No funding provider could prepare the transfer.',
              status: 502,
            })
          }
          throw cause
        }
      },
    )
    .post(
      '/v1/funding/transfers/vault',
      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
      OpenApi.validate('header', schema.createFundingTransferVault.Headers, {
        code: 'idempotency_key_required',
        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
      }),
      OpenApi.validate('json', schema.createFundingTransferVault.Body, {
        code: 'body_invalid',
        message: 'Check the request body and try again.',
      }),
      OpenApi.describeRoute({
        description: 'Creates a transfer into a Tempo Earn vault.',
        operationId: 'createFundingTransferVault',
        responses: unimplementedFundingTransferResponses,
        summary: 'Create transfer into vault',
        tags: ['Funding Transfers'],
      }),
      (c) => {
        if (Auth.narrowAccess) return Auth.accessError(c)
        if (OpenApi.narrowValidation)
          return OpenApi.validationError(c, {
            code: 'body_invalid',
            message: 'Check the request body and try again.',
          })

        c.header('Cache-Control', 'no-store')
        return Response.error(c, {
          code: 'not_implemented',
          message: 'Vault funding transfers are not implemented.',
          status: 501,
        })
      },
    )
    .post(
      '/v1/funding/transfers/zone',
      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
      OpenApi.validate('header', schema.createFundingTransferZone.Headers, {
        code: 'idempotency_key_required',
        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
      }),
      OpenApi.validate('json', schema.createFundingTransferZone.Body, {
        code: 'body_invalid',
        message: 'Check the request body and try again.',
      }),
      OpenApi.describeRoute({
        description: 'Creates a transfer into a Tempo Zone.',
        operationId: 'createFundingTransferZone',
        responses: unimplementedFundingTransferResponses,
        summary: 'Create transfer into zone',
        tags: ['Funding Transfers'],
      }),
      (c) => {
        if (Auth.narrowAccess) return Auth.accessError(c)
        if (OpenApi.narrowValidation)
          return OpenApi.validationError(c, {
            code: 'body_invalid',
            message: 'Check the request body and try again.',
          })

        c.header('Cache-Control', 'no-store')
        return Response.error(c, {
          code: 'not_implemented',
          message: 'Zone funding transfers are not implemented.',
          status: 501,
        })
      },
    )
}

export declare namespace transfers {
  /** Funding transfer route dependencies. */
  type Options = {
    /** Enqueues one registered transfer for destination reconciliation. */
    dispatchTransferReconciliation?:
      | ((message: FundingTransferReconciliation.Message) => Promise<void>)
      | undefined
    /** Enqueues webhook updates staged with transfer mutations. */
    dispatchTransferUpdates?:
      | ((references: readonly Webhooks.QueueReference[]) => Promise<number>)
      | undefined
  }
}

function quoteNotAvailable(c: Context<App.Environment>) {
  return Response.error(c, {
    code: 'quote_not_available',
    message: 'No provider can prepare the requested funding route.',
    status: 404,
  })
}

class IdempotencyLeaseLostError extends Error {
  override name = 'Funding.IdempotencyLeaseLostError'
}