Onramp endpoints

onramp.catalog(
  options?: {
    provider?: string       // provider hint, e.g. "banxa"; defaults to the tenant's preferred provider
    country?: string        // explicit ISO-3166-1 alpha-2; wins over clientCountry / GeoIP
    clientCountry?: string  // softer hint → X-Client-Country header
    fiat?: string           // scope payment-method limits/fees + crypto pairs to this fiat
    signal?: AbortSignal
  },
): Promise<OnrampCatalogResponse>

const catalog = await stridge.onramp.catalog({ country: "US" })

console.log(catalog.suggestedFiat)              // "USD" — preselect this
console.log(catalog.fiats.map((f) => f.code))   // ["USD", "EUR", …]
console.log(catalog.country.source)             // "query" — how the country resolved

const { fiats, suggested } = await stridge.onramp.fiats({ country: "US" })
const { crypto } = await stridge.onramp.crypto({ fiat: "USD" })
const { paymentMethods } = await stridge.onramp.paymentMethods({ fiat: "USD", crypto: "USDC" })
const { countries } = await stridge.onramp.countries()

onramp.quote(
  payload: {
    fiatCurrency: string       // e.g. "USD"
    fiatAmount: string         // positive decimal string, e.g. "100"
    country?: string           // resolved server-side when omitted
    paymentMethodId?: string   // scope fees/limits to a method
  },
  options?: { clientCountry?: string; signal?: AbortSignal },
): Promise<OnrampQuoteResponse>

const quote = await stridge.onramp.quote({ fiatCurrency: "USD", fiatAmount: "100" })

console.log(quote.assetName, quote.assetAmount) // "USDC", "99.7"
console.log(quote.rate)                          // "1.003" — fiat per 1 unit of crypto
console.log(quote.fees.total)                    // total fee on top of the crypto received

onramp.createSession(
  payload: {
    owner: string              // your end-user id; owner-scoped keys may only create under their own owner
    fiatCurrency: string       // e.g. "USD"
    fiatAmount: string         // positive decimal string
    destinationAsset: string   // asset the user receives, e.g. "USDC"
    destinationNetwork: string // network id from catalog crypto[].networkId
    destinationAddress: string // the user's wallet; must be allowed for the tenant, else 403
    country?: string
    paymentMethodId?: string
    redirectUrl?: string       // return URL after checkout; falls back to the tenant default
  },
  options?: {
    clientCountry?: string
    idempotencyKey?: string    // Idempotency-Key header — a retried create returns the same session
    signal?: AbortSignal
  },
): Promise<OnrampSessionResponse>

const session = await stridge.onramp.createSession(
  {
    owner: userId,
    fiatCurrency: "USD",
    fiatAmount: "100",
    destinationAsset: "USDC",
    destinationNetwork: "60",
    destinationAddress: walletAddress,
    redirectUrl: window.location.href,
  },
  { idempotencyKey: `onramp-${userId}-${Date.now()}` },
)

window.open(session.checkoutUrl, "_blank") // hand off to the hosted checkout

onramp.getSession(
  sessionId: string,
  options?: { ifNoneMatch?: string; signal?: AbortSignal },
): Promise<OnrampSessionResponse>

import { BackendError, isOnrampTerminalState } from "@stridge/sdk"

async function pollUntilTerminal(sessionId: string, etag?: string) {
  for (;;) {
    try {
      const session = await stridge.onramp.getSession(sessionId, { ifNoneMatch: etag })
      etag = session.etag
      if (isOnrampTerminalState(session.state)) return session
    } catch (err) {
      // A matching ETag surfaces as BackendError(304) — nothing changed, keep polling.
      if (!(err instanceof BackendError && err.statusCode === 304)) throw err
    }
    await new Promise((r) => setTimeout(r, 2_000))
  }
}

onramp.listOwnerSessions(
  owner: string,
  options?: {
    state?: string | string[]   // filter by state; an array joins to a comma list
    provider?: string
    destinationAsset?: string
    destinationNetwork?: string
    fiat?: string
    country?: string
    q?: string                   // free-text search
    from?: string                // created-at lower bound (RFC3339)
    to?: string                  // created-at upper bound (RFC3339)
    sort?: string
    order?: "asc" | "desc"
    limit?: number
    offset?: number
    includeTotals?: boolean      // include aggregate totals in the response
    signal?: AbortSignal
  },
): Promise<OnrampSessionListResponse>

const { sessions, pageInfo } = await stridge.onramp.listOwnerSessions(userId, {
  state: ["SESSION_COMPLETED", "SESSION_FAILED"],
  limit: 20,
})

interface OnrampSessionResponse {
  sessionId: string
  state: OnrampSessionState        // create always returns "SESSION_PENDING"
  checkoutUrl?: string             // provider-hosted page; present on create
  providerOrderId?: string
  externalOrderId: string
  flow: {
    fiat: { currency: string; amount: string }                 // what the user pays
    udaEntry: { address: string; networkId: string; asset: string }   // crypto the provider deposits, + the address
    destination: { address: string; networkId: string; asset: string; amount: string } // what the user receives, and where
  }
  expiresAt?: string
  etag: string                     // pass back as If-None-Match for cheap polling
}

import { OnrampSessionState, ONRAMP_TERMINAL_STATES, isOnrampTerminalState } from "@stridge/sdk"

onramp.setSessionState(
  sessionId: string,
  payload: { state: OnrampSessionState; failureCode?: string },
  options?: { signal?: AbortSignal },
): Promise<OnrampSessionResponse>

// Drive a pending session to success…
await stridge.onramp.setSessionState(session.sessionId, { state: "SESSION_COMPLETED" })

// …or to a specific failure:
await stridge.onramp.setSessionState(session.sessionId, {
  state: "SESSION_FAILED",
  failureCode: "payment_declined",
})

const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), 10_000)

try {
  const session = await stridge.onramp.getSession(sessionId, { signal: controller.signal })
  // …
} finally {
  clearTimeout(timer)
}