@lifi/composer-sdk/dist/sdk.d.cts

Public Composer SDK for building and submitting flows

import { ComposeCompileResult, ComposeCompileRequest, ComposeRouteRequest, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
import { FlowOptions, FlowBuilderCore, TypedFlow } from './authoring/FlowBuilderCore.cjs';
import { ComposeClient } from './client.cjs';
import { GeneratedOps } from './generated/operations.generated.cjs';
import { ComposeRunInput } from './run/inputs.cjs';
import { InputSchema } from './types.cjs';
import './authoring/handles.cjs';
import './discovery.cjs';
import './authoring/signatureArgs.cjs';
import 'abitype';
import './generated/config.generated.cjs';

/**
 * A flow builder augmented with generated operation methods and a `compile` method
 * that submits the flow to the Compose backend for compilation.
 *
 * Created via {@link ComposeSdk.flow}.
 *
 * @typeParam T - The input schema describing the flow's required inputs.
 */
type FlowBuilder<T extends InputSchema = InputSchema> = FlowBuilderCore<T> & GeneratedOps & {
    /**
     * Builds the flow document from the current builder state and submits it
     * to the Compose API for compilation.
     *
     * @param run - Runtime inputs, preconditions, and signer address.
     * @returns The compiled transaction calldata and metadata.
     * @throws {@link ComposeError} on network, validation, or server errors.
     *
     * @example
     * ```ts
     * const result = await builder.compile({
     *   inputs: { token: materialisers.balanceOf({}) },
     *   signer: '0xYourAddress...',
     * });
     * console.log(result.calldata);
     * ```
     */
    readonly compile: (run: ComposeRunInput<T>) => Promise<ComposeCompileResult>;
};
/**
 * Configuration for creating a Compose SDK instance.
 */
interface ComposeSdkOptions {
    /** Base URL of the Compose API (e.g. `"https://li.quest"`). */
    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;
}
/**
 * The top-level Compose SDK interface.
 *
 * Provides methods to build flows, compile them into executable calldata, and
 * interact with the Compose API directly.
 *
 * @example
 * ```ts
 * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';
 *
 * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
 *
 * const builder = sdk.flow(1, {
 *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },
 * });
 *
 * builder.lifi.swap('swap1', {
 *   bind: { amountIn: builder.inputs.usdc },
 *   config: { resourceOut: resources.native(1) },
 * });
 *
 * const result = await builder.compile({
 *   inputs: { usdc: materialisers.balanceOf({}) },
 *   signer: '0xYourAddress...',
 * });
 * ```
 */
interface ComposeSdk {
    /** Low-level HTTP client for the Compose API. */
    readonly client: ComposeClient;
    /**
     * Creates a new flow builder targeting the given chain.
     * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).
     * @param options - Flow configuration including input declarations.
     * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.
     * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.
     */
    readonly flow: <T extends InputSchema>(chainId: number, options: FlowOptions<T>) => FlowBuilder<T>;
    /**
     * Builds a raw compile request without sending it. Useful for inspecting the
     * request payload or submitting it through a custom transport.
     * @param flow - A built flow document (from `builder.build()`).
     * @param run - Runtime inputs, preconditions, and signer address.
     * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.
     */
    readonly request: <T extends InputSchema>(flow: TypedFlow<T>, run: ComposeRunInput<T>) => ComposeCompileRequest;
    /**
     * Compiles a token pair on one chain — as of today a single zap step over
     * one routing-catalog edge. Thin pass-through to
     * {@link ComposeClient.route}; see it for the current single-step limit,
     * when to prefer `flow(...).compile(...)`, the `success` / `partial`
     * discrimination, and error behaviour. Build the `amount` with
     * `routeAmount.exact(...)` / `routeAmount.all(...)`.
     *
     * @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.
     */
    readonly route: (request: ComposeRouteRequest) => Promise<ComposeCompileResult>;
    /**
     * Simulates a raw, pre-encoded transaction. Thin pass-through to
     * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`
     * result discrimination and error behaviour. Pair with `buildSimulateRequest`
     * to assemble the request from a compile result.
     *
     * @param request - The raw transaction plus funding `requirements` and
     *   `trackedBalances`.
     * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
     * @throws {@link ComposeError} on network, validation, or server errors.
     */
    readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
}
/**
 * Creates a new Compose SDK instance.
 *
 * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.
 * @returns A {@link ComposeSdk} instance.
 *
 * @example
 * ```ts
 * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
 * ```
 */
declare const createComposeSdk: (options: ComposeSdkOptions) => ComposeSdk;

export { ComposeRunInput, type ComposeSdk, type ComposeSdkOptions, type FlowBuilder, createComposeSdk };