@lifi/composer-sdk 0.0.1-alpha

package/src/client.ts

@@ -0,0 +1,230 @@
+import type {
+  ComposeCompilePartialData,
+  ComposeCompileRequest,
+  ComposeCompileResult,
+  ComposeCompileSuccessData,
+  ComposeManifest,
+} from '@lifi/compose-spec';
+
+import type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
+import { ComposeError, errorFromHttpResponse } from './errors.js';
+
+// __SDK_VERSION__ is a compile-time constant injected by tsup (via `define` in tsup.config.ts)
+// and by vitest (via `define` in vitest.config.ts). Both read the version from package.json
+// at build/test time and replace this identifier with the literal string value.
+// It is sent as the `x-lifi-composer-sdk` request header so the server can identify the caller.
+// Falls back to 'dev' when running via tsx without tsup substitution (e.g. the example harness).
+declare const __SDK_VERSION__: string;
+
+const SDK_VERSION: string =
+  typeof __SDK_VERSION__ !== 'undefined' ? __SDK_VERSION__ : 'dev';
+
+/**
+ * Configuration for creating a low-level Compose API client.
+ */
+export 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.
+ */
+export 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[]>;
+}
+
+const bigintReplacer = (_key: string, value: unknown): unknown =>
+  typeof value === 'bigint' ? value.toString() : value;
+
+const isNonNullObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null;
+
+const parseBody = async <T>(res: Response, url: string): Promise<T> => {
+  const body = await res.json().catch((_) => null);
+  if (!isNonNullObject(body) || !('data' in body)) {
+    throw new ComposeError('UNKNOWN_ERROR', 'Unexpected response format', {
+      url,
+    });
+  }
+  return body.data as T;
+};
+
+const parseCompileSuccessBody = async (
+  res: Response,
+  url: string,
+): Promise<ComposeCompileResult> => {
+  const data = await parseBody<ComposeCompileSuccessData>(res, url);
+  return { ...data, status: 'success' as const };
+};
+
+const parsePartialBody = async (
+  res: Response,
+  url: string,
+): Promise<ComposeCompileResult> => {
+  const body = await res.json().catch((_) => null);
+  if (
+    !isNonNullObject(body) ||
+    !('data' in body) ||
+    !isNonNullObject(body.data) ||
+    !('error' in body) ||
+    !isNonNullObject(body.error)
+  ) {
+    throw new ComposeError(
+      'UNKNOWN_ERROR',
+      'Unexpected partial response format',
+      { url },
+    );
+  }
+  const data = body.data as unknown as ComposeCompilePartialData;
+  const error = body.error as unknown as { kind: string; message: string };
+  return { ...data, status: 'partial' as const, error };
+};
+
+/**
+ * Creates a low-level Compose API client.
+ *
+ * @param options - Client configuration including the API base URL.
+ * @returns A {@link ComposeClient} instance.
+ */
+export const createComposeClient = (
+  options: ComposeClientOptions,
+): ComposeClient => {
+  if (!options.baseUrl || !/^https?:\/\//i.test(options.baseUrl)) {
+    throw new ComposeError(
+      'VALIDATION_ERROR',
+      `Invalid baseUrl: expected an HTTP(S) URL, got "${options.baseUrl}"`,
+    );
+  }
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const base = options.baseUrl.replace(/\/$/, '');
+
+  const trimmedApiKey = options.apiKey?.trim() || undefined;
+
+  const baseHeaders: Record<string, string> = {
+    Accept: 'application/json',
+    'x-lifi-composer-sdk': SDK_VERSION,
+    ...(trimmedApiKey ? { 'x-lifi-api-key': trimmedApiKey } : {}),
+  };
+
+  const getManifest = async (): Promise<ComposeManifest> => {
+    const url = `${base}/compose/manifest`;
+    let res: Response;
+    try {
+      res = await fetchFn(url, {
+        method: 'GET',
+        headers: { ...baseHeaders },
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
+    }
+    if (!res.ok) {
+      const body = await res.text();
+      throw errorFromHttpResponse(res.status, body, url);
+    }
+    return await parseBody<ComposeManifest>(res, url);
+  };
+
+  const compile = async (
+    request: ComposeCompileRequest,
+  ): Promise<ComposeCompileResult> => {
+    const url = `${base}/compose`;
+    let res: Response;
+    try {
+      res = await fetchFn(url, {
+        method: 'POST',
+        headers: { ...baseHeaders, 'Content-Type': 'application/json' },
+        body: JSON.stringify(request, bigintReplacer),
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
+    }
+    if (res.status === 206) {
+      return await parsePartialBody(res, url);
+    }
+    if (!res.ok) {
+      const body = await res.text();
+      throw errorFromHttpResponse(res.status, body, url);
+    }
+    return await parseCompileSuccessBody(res, url);
+  };
+
+  const getZapPacks = async (
+    options?: GetZapPacksOptions,
+  ): Promise<readonly ZapPackOverview[]> => {
+    const params = new URLSearchParams();
+    if (options?.protocols != null) {
+      // Backend expects a single comma-separated value, not repeated keys.
+      const raw = options.protocols;
+      const list = typeof raw === 'string' ? raw : raw.join(',');
+      params.set('protocols', list);
+    }
+    const qs = params.toString();
+    const url = `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`;
+    let res: Response;
+    try {
+      res = await fetchFn(url, {
+        method: 'GET',
+        headers: { ...baseHeaders },
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
+    }
+    if (!res.ok) {
+      const body = await res.text();
+      throw errorFromHttpResponse(res.status, body, url);
+    }
+    return await parseBody<readonly ZapPackOverview[]>(res, url);
+  };
+
+  return { getManifest, compile, getZapPacks };
+};

package/src/discovery.ts

@@ -0,0 +1,51 @@
+/**
+ * Types for the Compose discovery API (`GET /compose/zap-packs`).
+ *
+ * These are SDK-facing presentation types — not part of the core compile
+ * contract in compose-spec. The backend response is the source of truth;
+ * the SDK provides typed access.
+ *
+ * The `type` field on edges is a plain `string` rather than a strict union
+ * so the SDK remains forward-compatible when the backend introduces new
+ * edge types. Known values at time of writing:
+ * `"enter-position"`, `"exit-position"`, `"wrap"`, `"unwrap"`, `"mint"`, `"burn"`.
+ */
+
+/**
+ * A single routing edge representing a supported token-to-token path
+ * through a DeFi protocol.
+ */
+export interface ZapPackEdge {
+  /** Edge type (e.g. `"enter-position"`, `"exit-position"`, `"wrap"`). */
+  readonly type: string;
+  /** Input token. */
+  readonly in: { readonly address: string; readonly chainId: number };
+  /** Output token. */
+  readonly out: { readonly address: string; readonly chainId: number };
+  /** Minimum input amount accepted (stringified integer), if constrained. */
+  readonly inAmountMin?: string;
+  /** Maximum input amount accepted (stringified integer), if constrained. */
+  readonly inAmountMax?: string;
+}
+
+/**
+ * All routing edges for a single protocol.
+ */
+export interface ZapPackOverview {
+  /** Protocol identifier (e.g. `"aave"`, `"morpho"`). */
+  readonly protocol: string;
+  /** Available routing edges for this protocol. */
+  readonly edges: readonly ZapPackEdge[];
+}
+
+/**
+ * Options for {@link ComposeClient.getZapPacks}.
+ */
+export interface GetZapPacksOptions {
+  /**
+   * Filter to specific protocols. Pass a single string or an array.
+   * Only edges belonging to the listed protocols are returned.
+   * Omit to fetch all available protocols.
+   */
+  readonly protocols?: string | readonly string[];
+}

package/src/errors.ts

@@ -0,0 +1,150 @@
+import type { ComposeErrorKind, SimulationRevert } from '@lifi/compose-spec';
+
+/**
+ * Machine-readable error codes returned by the SDK.
+ *
+ * - `NETWORK_ERROR` — The HTTP request failed (DNS, timeout, connection refused).
+ * - `VALIDATION_ERROR` — The server rejected the request (HTTP 400/422).
+ * - `UNAUTHENTICATED` — The request lacks valid authentication credentials (HTTP 401).
+ * - `FORBIDDEN` — The server understood the request but refuses to authorise it (HTTP 403).
+ * - `SERVER_ERROR` — The server returned a 5xx status.
+ * - `RATE_LIMITED` — The server returned HTTP 429.
+ * - `NOT_FOUND` — The requested resource does not exist (HTTP 404).
+ * - `UNKNOWN_ERROR` — An unexpected error that doesn't fit other categories.
+ */
+export type ComposeErrorCode =
+  | 'NETWORK_ERROR'
+  | 'VALIDATION_ERROR'
+  | 'UNAUTHENTICATED'
+  | 'FORBIDDEN'
+  | 'SERVER_ERROR'
+  | 'RATE_LIMITED'
+  | 'NOT_FOUND'
+  | 'UNKNOWN_ERROR';
+
+/**
+ * Error class for all failures originating from the Compose SDK or API.
+ *
+ * Includes structured metadata beyond the error message to support
+ * programmatic error handling.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await builder.compile(run);
+ * } catch (e) {
+ *   if (isComposeError(e) && e.code === 'VALIDATION_ERROR') {
+ *     console.error('Invalid request:', e.message, e.path);
+ *   }
+ * }
+ * ```
+ */
+export class ComposeError extends Error {
+  override readonly name = 'ComposeError';
+  /** Machine-readable error category. */
+  readonly code: ComposeErrorCode;
+  /** HTTP status code, when the error originated from an HTTP response. */
+  readonly status?: number;
+  /** The request URL that produced the error. */
+  readonly url?: string;
+  /** Server-provided error kind for finer-grained classification. */
+  readonly kind?: ComposeErrorKind;
+  /** JSON-pointer path to the field that caused a validation error. */
+  readonly path?: string;
+  /**
+   * Simulation revert diagnostics attached to `simulation_revert` errors.
+   * Contains the raw error bytes and decoded error candidates when the
+   * backend can parse the revert reason.
+   */
+  readonly details?: SimulationRevert;
+
+  constructor(
+    code: ComposeErrorCode,
+    message: string,
+    options?: {
+      status?: number;
+      url?: string;
+      cause?: unknown;
+      kind?: ComposeErrorKind;
+      path?: string;
+      details?: SimulationRevert;
+    },
+  ) {
+    super(message, { cause: options?.cause });
+    this.code = code;
+    this.status = options?.status;
+    this.url = options?.url;
+    this.kind = options?.kind;
+    this.path = options?.path;
+    this.details = options?.details;
+  }
+}
+
+/**
+ * Type guard that narrows an unknown error to {@link ComposeError}.
+ * @param e - The value to check.
+ * @returns `true` if `e` is an instance of `ComposeError`.
+ */
+export const isComposeError = (e: unknown): e is ComposeError =>
+  e instanceof ComposeError ||
+  (e instanceof Error && e.name === 'ComposeError' && 'code' in e);
+
+const STATUS_TO_CODE: ReadonlyMap<number, ComposeErrorCode> = new Map<
+  number,
+  ComposeErrorCode
+>([
+  [400, 'VALIDATION_ERROR'],
+  [401, 'UNAUTHENTICATED'],
+  [403, 'FORBIDDEN'],
+  [404, 'NOT_FOUND'],
+  [422, 'VALIDATION_ERROR'],
+  [429, 'RATE_LIMITED'],
+]);
+
+interface ServerErrorBody {
+  readonly error?: {
+    readonly kind?: string;
+    readonly message?: string;
+    readonly path?: string;
+    readonly details?: SimulationRevert;
+  };
+}
+
+const tryParseErrorBody = (body: string): ServerErrorBody | null => {
+  try {
+    return JSON.parse(body) as ServerErrorBody;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Constructs a {@link ComposeError} from an HTTP error response, extracting
+ * structured error details from the response body when available.
+ *
+ * @param status - The HTTP status code.
+ * @param body - The raw response body text.
+ * @param url - The request URL that produced the error.
+ * @returns A `ComposeError` with the appropriate error code and metadata.
+ */
+export const errorFromHttpResponse = (
+  status: number,
+  body: string,
+  url: string,
+): ComposeError => {
+  const parsed = tryParseErrorBody(body);
+  const serverError = parsed?.error;
+
+  return new ComposeError(
+    STATUS_TO_CODE.get(status) ??
+      (status >= 500 ? 'SERVER_ERROR' : 'UNKNOWN_ERROR'),
+    (serverError?.message ?? body) || `HTTP ${status}`,
+    {
+      status,
+      url,
+      kind: serverError?.kind as ComposeErrorKind | undefined,
+      path: serverError?.path,
+      details: serverError?.details,
+    },
+  );
+};

package/src/examples/approveAndDeposit.ts

@@ -0,0 +1,84 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+import type { Address } from '../types.js';
+
+import { BASE_URL } from './config.js';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+// Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
+const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
+
+export interface ApproveAndDepositInput {
+  readonly owner: Address;
+  readonly amount: `${bigint}`;
+}
+
+/**
+ * Approve a vault to spend USDC, deposit into it, and track the resulting
+ * shares as a resource.
+ *
+ * Demonstrates:
+ * - core.approve to grant ERC20 allowance to the vault
+ * - core.call to invoke the vault's deposit function
+ * - core.asResource to graduate the raw return value to a tracked resource
+ */
+export const buildApproveAndDeposit = ({
+  owner,
+  amount,
+}: ApproveAndDepositInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'approve-and-deposit',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+    },
+  });
+
+  // Approve the vault to spend our USDC.
+  builder.core.approve('approve-vault', {
+    bind: { amount: builder.inputs.amountIn },
+    config: { spender: VAULT },
+  });
+
+  // Call vault.deposit(uint256 assets, address receiver) returns (uint256).
+  // The input resource (USDC) is consumed by the call.
+  // The `returns (uint256)` clause gives typed access to `.result` (shares minted).
+  const depositResult = builder.core.call('deposit', {
+    resource: builder.inputs.amountIn,
+    bind: {
+      assets: builder.inputs.amountIn,
+      receiver: builder.context.executionAddress,
+    },
+    config: {
+      target: VAULT,
+      functionSignature:
+        'function deposit(uint256 assets, address receiver) returns (uint256)',
+    },
+  });
+
+  // Graduate the raw shares handle to a tracked resource so downstream
+  // nodes can use it with slippage tracking and linearity checks.
+  builder.core.asResource('shares', {
+    bind: { handle: depositResult.result },
+    config: {
+      resource: resources.erc20(VAULT, 1),
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};