@lifi/composer-sdk/dist/client.d.ts

Public Composer SDK for building and submitting flows

import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, ComposeRouteRequest, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
import { GetZapPacksOptions, ZapPackOverview } from './discovery.js';

/**
 * Configuration for creating a low-level Compose API client.
 */
interface ComposeClientOptions {
    /** Base URL of the Compose API. */
    readonly baseUrl: string;
    /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */
    readonly fetch?: typeof globalThis.fetch;
    /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */
    readonly apiKey: string;
}
/**
 * Low-level HTTP client for the Compose API.
 *
 * Handles request serialization, SDK version headers, and error mapping.
 * Prefer using {@link ComposeSdk} for the full builder experience. Use this
 * directly when you need to decouple request building from submission — e.g.
 * build via `sdk.request()` then submit via `client.compile()` with custom
 * retry logic or request inspection.
 */
interface ComposeClient {
    /**
     * Fetches the server's operation manifest describing all supported operations,
     * guards, materialisers, and preconditions.
     * @returns The manifest document.
     * @throws {@link ComposeError} on network, validation, or server errors.
     */
    readonly getManifest: () => Promise<ComposeManifest>;
    /**
     * Submits a compile request and returns the result.
     *
     * When the caller passes `simulationPolicy: 'allow-revert'` and the transaction
     * reverts in simulation, the server responds with HTTP 206 and the SDK returns a
     * partial result (`status: 'partial'`) instead of throwing. The partial result
     * includes the transaction (without `gasLimit`) and revert diagnostics.
     *
     * @param request - The full compile request including flow and run inputs.
     * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.
     * @throws {@link ComposeError} on network, validation, or server errors.
     */
    readonly compile: (request: ComposeCompileRequest) => Promise<ComposeCompileResult>;
    /**
     * Compiles a token pair into a submit-ready transaction via
     * `POST /compose/route`.
     *
     * A convenience path that skips flow authoring: the server builds a one-node
     * `lifi.zap` flow with a `directDeposit` input from the `fromToken` /
     * `toToken` pair and runs it through the same pipeline as {@link compile}.
     * The response is therefore the same discriminated result — HTTP 206 under
     * `simulationPolicy: 'allow-revert'` yields `status: 'partial'` rather than
     * throwing, exactly as it does for {@link compile}.
     *
     * As of today that flow is a single zap step: one edge of the backend's
     * routing catalog (a position entry or exit, a wrap or unwrap, a mint or
     * burn). Enumerate the pairs it covers with {@link getZapPacks}; a pair with
     * no edge is rejected with `kind: 'no_route_error'`. The endpoint is meant to
     * author richer flows later, so the single-step limit is the current state of
     * the server, not the shape of this contract.
     *
     * Use {@link compile} for what the server does not author for you: several
     * chained operations, splits, explicit preconditions, or per-op guards.
     *
     * `bigint` amounts in `amount` are serialised to decimal strings
     * automatically.
     *
     * @param request - The from/to token pair, amount, signer, and route options.
     * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.
     * @throws {@link ComposeError} on network, validation, or server errors —
     *   including `NOT_FOUND` (HTTP 404) when no catalog edge covers the pair.
     */
    readonly route: (request: ComposeRouteRequest) => Promise<ComposeCompileResult>;
    /**
     * Fetches the available routing edges grouped by protocol.
     *
     * The edge catalog is dynamic — it reflects the current state of the
     * backend's routing snapshot (protocols, chains, token blacklists).
     * Results are not cached by the SDK; callers should cache as appropriate.
     *
     * @param options - Optional filter to restrict results to specific protocols.
     * @returns An array of {@link ZapPackOverview} objects, one per protocol.
     * @throws {@link ComposeError} on network or server errors (503 when the
     *   routing catalog is not yet initialized).
     */
    readonly getZapPacks: (options?: GetZapPacksOptions) => Promise<readonly ZapPackOverview[]>;
    /**
     * Simulates a raw, pre-encoded transaction against `POST /simulate` and
     * reports how the watched balances change and how much inner-call gas it
     * burns.
     *
     * The result is a discriminated union on `status`:
     * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.
     * - `'revert'` — the simulation ran but the transaction reverted on-chain. A
     *   revert is a *successful simulation*, not a transport error, so it is
     *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}
     *   returns `status: 'partial'` on a simulated revert.
     * - `'error'` — the request was well-formed but the simulation could not be
     *   set up or run (HTTP 422); `message` is intentionally generic.
     *
     * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)
     * are serialised to decimal strings automatically.
     *
     * @param request - The raw transaction plus funding `requirements` and the
     *   `trackedBalances` to watch.
     * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
     * @throws {@link ComposeError} on network failures, HTTP 400 (malformed
     *   input), 401/403 (auth), 404, 429, and 5xx.
     */
    readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
}
/**
 * Creates a low-level Compose API client.
 *
 * @param options - Client configuration including the API base URL.
 * @returns A {@link ComposeClient} instance.
 */
declare const createComposeClient: (options: ComposeClientOptions) => ComposeClient;

export { type ComposeClient, type ComposeClientOptions, createComposeClient };