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

Public Composer SDK for building and submitting flows

import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, 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;
    /** Optional LI.FI API key. When set, sent as the `x-lifi-api-key` header on every request. */
    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>;
    /**
     * 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 };