@lifi/composer-sdk 0.0.1-alpha

package/src/index.ts

@@ -0,0 +1,149 @@
+/**
+ * `@lifi/composer-sdk` — TypeScript SDK for building and compiling
+ * Compose flows into executable EVM calldata.
+ *
+ * Start by creating an SDK instance with {@link createComposeSdk}, then use
+ * {@link ComposeSdk.flow} to build flows and compile them.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  AbiTypeToOutputKind,
+  Address,
+  InputDecl,
+  InputSchema,
+  InputSpecOf,
+  IntegerString,
+  IntegerStringInput,
+  OutputKind,
+  TypedGuard,
+  TypedRef,
+} from './types.js';
+
+export type {
+  GetZapPacksOptions,
+  ZapPackEdge,
+  ZapPackOverview,
+} from './discovery.js';
+export type { ComposeError, ComposeErrorCode } from './errors.js';
+export type {
+  AppliedGuard,
+  ApprovalEntry,
+  Call,
+  ComposeCompilePartialData,
+  ComposeCompileRequest,
+  ComposeCompileResult,
+  ComposeCompileSuccessData,
+  ComposeContinuation,
+  ComposeErrorKind,
+  ComposeTransactionRequest,
+  Flow,
+  InputSpec,
+  MaterialiserConfigOf,
+  MaterialiserInput,
+  Precondition,
+  PreconditionConfigOf,
+  PriceImpact,
+  Ref,
+  Resource,
+  SimulationPolicy,
+  SimulationRevert,
+  SolType,
+  SweepTo,
+} from '@lifi/compose-spec';
+export { isComposeError } from './errors.js';
+
+export type {
+  Bindable,
+  InputHandle,
+  ResourceInputHandle,
+  OutputHandle,
+  AnyHandle,
+} from './authoring/handles.js';
+export { isInputHandle, isOutputHandle } from './authoring/handles.js';
+export { ref } from './authoring/raw.js';
+
+export type { AnyBindable } from './authoring/FlowBuilderCore.js';
+export type { TypedFlow, FlowOptions } from './authoring/FlowBuilderCore.js';
+
+export type { ComposeRunInput } from './run/inputs.js';
+export { materialiser } from './run/inputs.js';
+
+export { createComposeSdk } from './sdk.js';
+export type { ComposeSdk, ComposeSdkOptions, FlowBuilder } from './sdk.js';
+
+import * as guardsMod from './generated/guards.generated.js';
+import * as materialisersMod from './generated/materialisers.generated.js';
+import * as preconditionsMod from './generated/preconditions.generated.js';
+import * as rawMod from './raw.js';
+import * as resourcesMod from './resources.js';
+
+/**
+ * Guard factories for protecting operation outputs (e.g. slippage tolerance).
+ * Pass guards to an operation's `guards` array.
+ *
+ * @example
+ * ```ts
+ * builder.lifi.swap('swap1', {
+ *   bind: { amountIn: builder.inputs.token },
+ *   config: { resourceOut: resources.native(1) },
+ *   guards: [guards.slippage({ port: 'amountOut', bps: 300 })],
+ * });
+ * ```
+ */
+export const guards: typeof guardsMod = guardsMod;
+/**
+ * Materialiser factories that tell the runtime how to resolve token input
+ * amounts on-chain (e.g. read a wallet balance, accept a direct deposit).
+ *
+ * @example
+ * ```ts
+ * await builder.compile({
+ *   inputs: { token: materialisers.balanceOf({}) },
+ *   signer: '0x...',
+ * });
+ * ```
+ */
+export const materialisers: typeof materialisersMod = materialisersMod;
+/**
+ * Precondition factories for asserting on-chain state before a flow executes
+ * (e.g. minimum token balances, ERC-20 allowances).
+ *
+ * @example
+ * ```ts
+ * await builder.compile({
+ *   inputs: { token: materialisers.balanceOf({}) },
+ *   preconditions: [
+ *     preconditions.erc20Balance({ wallet: '0x...', token: '0x...', balance: 1000n }),
+ *   ],
+ *   signer: '0x...',
+ * });
+ * ```
+ */
+export const preconditions: typeof preconditionsMod = preconditionsMod;
+/**
+ * Resource declaration helpers for defining token inputs in a flow schema.
+ * Use {@link resources.erc20} for ERC-20 tokens and {@link resources.native}
+ * for the chain's native coin (ETH, MATIC, etc.).
+ *
+ * @example
+ * ```ts
+ * const builder = sdk.flow(1, {
+ *   inputs: {
+ *     usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1),
+ *     eth: resources.native(1),
+ *   },
+ * });
+ * ```
+ */
+export const resources: typeof resourcesMod = resourcesMod;
+export * from './generated/config.generated.js';
+
+/**
+ * Low-level escape hatch for constructing flow nodes, guards, and materialiser
+ * inputs without the typed builder API. Prefer the generated operation methods
+ * on {@link FlowBuilder} and the typed `guards`/`materialisers` namespaces
+ * for most use cases.
+ */
+export const raw: typeof rawMod = rawMod;

package/src/raw.ts

@@ -0,0 +1,10 @@
+/**
+ * Low-level escape hatch for constructing flow nodes and guards without the
+ * typed builder API. Use these when working with operation kinds not covered
+ * by the generated methods, or when you need full control over the JSON shape.
+ *
+ * For most use cases, prefer the generated operation methods on {@link FlowBuilder}
+ * (e.g. `builder.lifi.swap(...)`) and the typed guard/materialiser helpers.
+ */
+export { rawGuard as guard, ref } from './authoring/raw.js';
+export { materialiser } from './run/inputs.js';

package/src/resources.ts

@@ -0,0 +1,61 @@
+import type { Address } from './types.js';
+
+// These resource types are SDK-local declarations that mirror the shape of
+// `Resource` from `@lifi/compose-spec`. They exist so the SDK can be used
+// without directly depending on `@lifi/compose-spec` at the call site.
+// The types are structurally compatible, so they are assignable to each other.
+
+/** A resource declaration representing the chain's native token (e.g. ETH, MATIC). */
+export interface NativeResource {
+  readonly kind: 'native';
+  readonly chainId: number;
+}
+
+/** A resource declaration representing an ERC-20 token at a specific address. */
+export interface Erc20Resource {
+  readonly kind: 'erc20';
+  readonly token: Address;
+  readonly chainId: number;
+}
+
+/** A token resource — either the chain's native token or an ERC-20. */
+export type Resource = NativeResource | Erc20Resource;
+
+/**
+ * Creates a native token resource declaration.
+ *
+ * @param chainId - The EVM chain ID the native token belongs to.
+ * @returns A {@link NativeResource} for use in flow input schemas.
+ *
+ * @example
+ * ```ts
+ * const builder = sdk.flow(1, {
+ *   inputs: { eth: native(1) },
+ * });
+ * ```
+ */
+export const native = (chainId: number): NativeResource => ({
+  kind: 'native',
+  chainId,
+});
+
+/**
+ * Creates an ERC-20 token resource declaration.
+ *
+ * @param token - The `0x`-prefixed contract address of the ERC-20 token.
+ * @param chainId - The EVM chain ID the token is deployed on.
+ * @returns An {@link Erc20Resource} for use in flow input schemas.
+ *
+ * @example
+ * ```ts
+ * const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+ * const builder = sdk.flow(1, {
+ *   inputs: { usdc: erc20(USDC, 1) },
+ * });
+ * ```
+ */
+export const erc20 = (token: Address, chainId: number): Erc20Resource => ({
+  kind: 'erc20',
+  token,
+  chainId,
+});

package/src/run/inputs.ts

@@ -0,0 +1,117 @@
+import type {
+  ComposeRun,
+  InputSpec,
+  MaterialiserInput,
+  Precondition,
+  SimulationPolicy,
+  SweepTo,
+} from '@lifi/compose-spec';
+
+import type { Address, InputSchema, InputSpecOf } from '../types.js';
+
+/**
+ * Runtime inputs for compiling a flow. Passed to `builder.compile()` or `sdk.request()`.
+ *
+ * @typeParam T - The flow's input schema, used to type-check `inputs` and `assumptions`.
+ */
+export interface ComposeRunInput<T extends InputSchema = InputSchema> {
+  /**
+   * Concrete values for each declared flow input. Resource inputs accept a
+   * materialiser or a literal integer amount; scalar inputs accept the matching type.
+   */
+  readonly inputs: { readonly [K in keyof T]: InputSpecOf<T[K]> };
+  /** Optional preconditions that must hold before the flow executes (e.g. minimum balances). */
+  readonly preconditions?: readonly Precondition[];
+  /** The `0x`-prefixed address of the transaction signer. */
+  readonly signer: Address;
+  /**
+   * Optional assumed token amounts for resource inputs, keyed by input name.
+   * When a materialiser resolves amounts at execution time rather than upfront,
+   * assumptions let the compiler plan routes using estimated values. The keys
+   * must match the input names declared in the flow schema.
+   */
+  readonly assumptions?: { readonly [K in keyof T]?: bigint };
+  /** Optional integrator referrer identifier. */
+  readonly referrer?: string;
+  /** Maximum acceptable price impact in basis points (e.g. `300` = 3%). */
+  readonly maxPriceImpactBps?: number;
+  /**
+   * Destination for sweeping all proxy-held terminal resources after execution.
+   * Pass a literal `0x`-prefixed address or `{ $ref: "context.sender" }` to
+   * send remaining tokens to the signer.
+   */
+  readonly sweepTo?: SweepTo;
+  /**
+   * Controls behavior when simulation detects a revert.
+   * `'strict'` (default) returns an error; `'allow-revert'` returns a partial
+   * result with the transaction and revert diagnostics.
+   */
+  readonly simulationPolicy?: SimulationPolicy;
+  /**
+   * When `true`, the server checks on-chain ERC-20 allowances and omits
+   * approvals that are already sufficient. Defaults to `false`.
+   */
+  readonly checkOnChainAllowances?: boolean;
+}
+
+/**
+ * Creates an untyped materialiser input spec. This is a low-level escape hatch
+ * for materialiser kinds not yet covered by the generated helpers.
+ *
+ * Prefer the typed helpers in the `materialisers` namespace (e.g.
+ * `materialisers.balanceOf()`, `materialisers.directDeposit()`) which provide
+ * compile-time config validation.
+ *
+ * @param kind - The materialiser type (e.g. `"balanceOf"`, `"directDeposit"`).
+ * @param config - Optional materialiser-specific configuration.
+ * @returns A {@link MaterialiserInput} for use in {@link ComposeRunInput.inputs}.
+ *
+ * @example
+ * ```ts
+ * const run = {
+ *   inputs: { token: materialiser('customKind', { myParam: '0x...' }) },
+ *   signer: '0x...',
+ * };
+ * ```
+ */
+export const materialiser = (
+  kind: string,
+  config: Record<string, unknown> = {},
+): MaterialiserInput => ({
+  kind,
+  ...config,
+});
+
+/**
+ * Assembles a {@link ComposeRun} object from individual parameters.
+ * Used internally by the SDK; prefer {@link ComposeRunInput} for external use.
+ *
+ * @internal
+ */
+export const buildRun = (run: {
+  inputs: Record<string, InputSpec>;
+  preconditions?: readonly Precondition[];
+  signer: string;
+  assumptions?: Record<string, bigint>;
+  referrer?: string;
+  maxPriceImpactBps?: number;
+  sweepTo?: SweepTo;
+  simulationPolicy?: SimulationPolicy;
+  checkOnChainAllowances?: boolean;
+}): ComposeRun => ({
+  inputs: run.inputs,
+  ...(run.preconditions?.length && { preconditions: run.preconditions }),
+  signer: run.signer,
+  ...(run.assumptions && { assumptions: run.assumptions }),
+  ...(run.referrer != null && { referrer: run.referrer }),
+  ...(run.maxPriceImpactBps != null && {
+    maxPriceImpactBps: run.maxPriceImpactBps,
+  }),
+  ...(run.sweepTo != null && { sweepTo: run.sweepTo }),
+  ...(run.simulationPolicy != null && {
+    simulationPolicy: run.simulationPolicy,
+  }),
+  ...(run.checkOnChainAllowances != null && {
+    checkOnChainAllowances: run.checkOnChainAllowances,
+  }),
+});

package/src/sdk.ts

@@ -0,0 +1,173 @@
+import type {
+  ComposeCompileRequest,
+  ComposeCompileResult,
+  InputSpec,
+} from '@lifi/compose-spec';
+
+import {
+  createFlowBuilderCore,
+  type FlowBuilderCore,
+  type FlowOptions,
+  type TypedFlow,
+} from './authoring/FlowBuilderCore.js';
+import { type ComposeClient, createComposeClient } from './client.js';
+import {
+  bindGeneratedOps,
+  type GeneratedOps,
+} from './generated/operations.generated.js';
+import { buildRun, type ComposeRunInput } from './run/inputs.js';
+import type { InputSchema } from './types.js';
+
+export type { ComposeRunInput };
+
+/**
+ * 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;
+  /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */
+  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' });
+ *
+ * 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>;
+  /**
+   * 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;
+}
+
+/**
+ * Creates a new Compose SDK instance.
+ *
+ * @param options - SDK configuration including the API base URL and optional fetch implementation.
+ * @returns A {@link ComposeSdk} instance.
+ *
+ * @example
+ * ```ts
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * ```
+ */
+export const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {
+  const composeClient = createComposeClient(options);
+
+  const request = <T extends InputSchema>(
+    flowDoc: TypedFlow<T>,
+    run: ComposeRunInput<T>,
+  ): ComposeCompileRequest => ({
+    flow: flowDoc,
+    run: buildRun({
+      inputs: run.inputs as Record<string, InputSpec>,
+      preconditions: run.preconditions,
+      signer: run.signer,
+      assumptions: run.assumptions as Record<string, bigint> | undefined,
+      referrer: run.referrer,
+      maxPriceImpactBps: run.maxPriceImpactBps,
+      sweepTo: run.sweepTo,
+      simulationPolicy: run.simulationPolicy,
+      checkOnChainAllowances: run.checkOnChainAllowances,
+    }),
+  });
+
+  const flow = <T extends InputSchema>(
+    chainId: number,
+    opts: FlowOptions<T>,
+  ): FlowBuilder<T> => {
+    const core = createFlowBuilderCore(chainId, opts);
+    const builder = Object.assign(core, bindGeneratedOps(core));
+
+    const compile = async (
+      run: ComposeRunInput<T>,
+    ): Promise<ComposeCompileResult> => {
+      const flowDoc = builder.build();
+      const req = request(flowDoc, run);
+      return composeClient.compile(req);
+    };
+
+    return Object.assign(builder, { compile });
+  };
+
+  return { client: composeClient, flow, request };
+};

package/src/types.ts

@@ -0,0 +1,101 @@
+import type { Ref } from '@lifi/compose-spec';
+import {
+  InputSpec,
+  MaterialiserInput,
+  Resource,
+  SolType,
+} from '@lifi/compose-spec';
+
+/**
+ * A string that represents a non-negative integer (e.g. "1000000000").
+ * Uses a template literal type so that only numeric-looking strings
+ * are assignable at compile time.
+ */
+export type IntegerString = `${bigint}`;
+
+/**
+ * Accepted input for integer-string config fields.
+ * Callers may pass either a numeric string ("1000000000") or a native bigint
+ * (1000000000n). Bigint values are stringified automatically during JSON
+ * serialization via the SDK's `bigintReplacer`.
+ */
+export type IntegerStringInput = IntegerString | bigint;
+
+/**
+ * A `0x`-prefixed hex string representing an Ethereum address.
+ * Template literal type catches obviously wrong values at compile time.
+ */
+export type Address = `0x${string}`;
+
+/** The universe of output port kinds: Solidity scalar types plus `'resource'`. */
+export type OutputKind = SolType | 'resource';
+
+/**
+ * Maps an ABI parameter type string (from abitype's `ParseAbiItem`) to the
+ * closest `OutputKind`. When the ABI type is one of the supported `SolType`
+ * scalars, the mapping is exact; for all other Solidity types (e.g. tuples,
+ * fixed-point decimals) it falls back to `SolType` — accepting any scalar
+ * handle but not `'resource'` handles.
+ *
+ * The fallback excludes `'resource'` because every Solidity type is a scalar;
+ * resource handles carry token-amount semantics that should only flow into
+ * slots explicitly declared as resources.
+ *
+ * Extending `SolType` with new members automatically widens the exact-match
+ * branch — no changes needed here.
+ */
+export type AbiTypeToOutputKind<T extends string> = T extends SolType
+  ? T
+  : SolType;
+
+/**
+ * A typed `$ref` pointer carrying a phantom type parameter.
+ * Extends `Ref` so it is accepted anywhere a plain `Ref` is.
+ * The `__outputKind` field is never set at runtime — it exists only
+ * for TypeScript's structural type checker to distinguish typed refs.
+ */
+export interface TypedRef<T extends OutputKind = OutputKind> extends Ref {
+  readonly __outputKind?: T;
+}
+
+/**
+ * An input declaration in a flow schema.
+ * `Resource` values become resource inputs (token amounts);
+ * `SolType` strings become handle inputs (scalars like addresses).
+ */
+export type InputDecl = Resource | SolType;
+
+/**
+ * A record mapping input names to their declarations.
+ * Used as the type parameter for generic flow builders and requests.
+ */
+export type InputSchema = Record<string, InputDecl>;
+
+/**
+ * Maps an input declaration to the allowed runtime value type.
+ * Resource inputs accept materialisers or literal amounts.
+ * Handle inputs accept the scalar type matching their SolType.
+ */
+export type InputSpecOf<D> = D extends Resource
+  ? MaterialiserInput | IntegerStringInput
+  : D extends 'address'
+    ? Address
+    : D extends 'bool'
+      ? boolean
+      : D extends `${'u' | ''}int${string}`
+        ? IntegerStringInput
+        : D extends `bytes${string}`
+          ? `0x${string}`
+          : D extends 'string'
+            ? string
+            : InputSpec;
+
+/**
+ * A guard applied to an operation, with the `port` field constrained
+ * to a specific set of output port names.
+ */
+export interface TypedGuard<Port extends string = string> {
+  readonly kind: string;
+  readonly port: Port;
+  readonly [key: string]: unknown;
+}