UNPKG

@lifi/composer-sdk

Version:

Public Composer SDK for building and submitting flows

160 lines • 6.75 kB
import { InputSchema } from "./types.js"; import { FlowBuilderCore, FlowOptions, TypedFlow } from "./authoring/FlowBuilderCore.js"; import { ChainSummary } from "./discovery.js"; import { ComposeClient } from "./client.js"; import { GeneratedOps } from "./generated/operations.generated.js"; import { ComposeRunInput } from "./run/inputs.js"; import { ComposeCompileRequest, ComposeCompileResult, ComposeRouteRequest, SimulateRequest, SimulateResult } from "@lifi/compose-spec"; //#region src/sdk.d.ts /** * 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. */ export 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. */ export 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...', * }); * ``` */ export 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>; /** * Fetches the chains this Compose deployment supports, ascending by * `chainId`. Thin pass-through to {@link ComposeClient.getChains}; see it * for what "supported" means and for the caching caveat. * * Each entry pairs the `chainId` with a display `name`, so one call both * gates a chain selector and labels it. Key on `chainId`; `name` is a * deployment-maintained label that can change. * * Use it to fail fast before building a flow for a chain the server would * reject. * * @returns The supported chains, ascending by `chainId`. * @throws {@link ComposeError} on network or server errors. * * @example * ```ts * const chains = await sdk.getSupportedChains(); * if (!chains.some((c) => c.chainId === 8453)) { * throw new Error('Base is not supported'); * } * for (const { chainId, name } of chains) { * console.log(`${name} (${chainId})`); * } * ``` */ readonly getSupportedChains: () => Promise<readonly ChainSummary[]>; /** * 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 into a submit-ready transaction. Thin * pass-through to {@link ComposeClient.route}; see it for the short chain of * catalog edges the server plans, 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' }); * ``` */ export declare const createComposeSdk: (options: ComposeSdkOptions) => ComposeSdk; //#endregion export type { ComposeRunInput }; //# sourceMappingURL=sdk.d.ts.map