@lifi/composer-sdk 0.4.0-staging.1 → 0.4.1

package/dist/sdk.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  InputSpec,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport {\n  createFlowBuilderCore,\n  type FlowBuilderCore,\n  type FlowOptions,\n  type TypedFlow,\n} from './authoring/FlowBuilderCore.js';\nimport { type ComposeClient, createComposeClient } from './client.js';\nimport {\n  bindGeneratedOps,\n  type GeneratedOps,\n} from './generated/operations.generated.js';\nimport { buildRun, type ComposeRunInput } from './run/inputs.js';\nimport type { InputSchema } from './types.js';\n\nexport type { ComposeRunInput };\n\n/**\n * A flow builder augmented with generated operation methods and a `compile` method\n * that submits the flow to the Compose backend for compilation.\n *\n * Created via {@link ComposeSdk.flow}.\n *\n * @typeParam T - The input schema describing the flow's required inputs.\n */\nexport type FlowBuilder<T extends InputSchema = InputSchema> =\n  FlowBuilderCore<T> &\n    GeneratedOps & {\n      /**\n       * Builds the flow document from the current builder state and submits it\n       * to the Compose API for compilation.\n       *\n       * @param run - Runtime inputs, preconditions, and signer address.\n       * @returns The compiled transaction calldata and metadata.\n       * @throws {@link ComposeError} on network, validation, or server errors.\n       *\n       * @example\n       * ```ts\n       * const result = await builder.compile({\n       *   inputs: { token: materialisers.balanceOf({}) },\n       *   signer: '0xYourAddress...',\n       * });\n       * console.log(result.calldata);\n       * ```\n       */\n      readonly compile: (\n        run: ComposeRunInput<T>,\n      ) => Promise<ComposeCompileResult>;\n    };\n\n/**\n * Configuration for creating a Compose SDK instance.\n */\nexport interface ComposeSdkOptions {\n  /** Base URL of the Compose API (e.g. `\"https://li.quest\"`). */\n  readonly baseUrl: string;\n  /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */\n  readonly apiKey: string;\n}\n\n/**\n * The top-level Compose SDK interface.\n *\n * Provides methods to build flows, compile them into executable calldata, and\n * interact with the Compose API directly.\n *\n * @example\n * ```ts\n * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';\n *\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n *\n * const builder = sdk.flow(1, {\n *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },\n * });\n *\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.usdc },\n *   config: { resourceOut: resources.native(1) },\n * });\n *\n * const result = await builder.compile({\n *   inputs: { usdc: materialisers.balanceOf({}) },\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport interface ComposeSdk {\n  /** Low-level HTTP client for the Compose API. */\n  readonly client: ComposeClient;\n  /**\n   * Creates a new flow builder targeting the given chain.\n   * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n   * @param options - Flow configuration including input declarations.\n   * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.\n   * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.\n   */\n  readonly flow: <T extends InputSchema>(\n    chainId: number,\n    options: FlowOptions<T>,\n  ) => FlowBuilder<T>;\n  /**\n   * Builds a raw compile request without sending it. Useful for inspecting the\n   * request payload or submitting it through a custom transport.\n   * @param flow - A built flow document (from `builder.build()`).\n   * @param run - Runtime inputs, preconditions, and signer address.\n   * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.\n   */\n  readonly request: <T extends InputSchema>(\n    flow: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ) => ComposeCompileRequest;\n  /**\n   * Simulates a raw, pre-encoded transaction. Thin pass-through to\n   * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`\n   * result discrimination and error behaviour. Pair with `buildSimulateRequest`\n   * to assemble the request from a compile result.\n   *\n   * @param request - The raw transaction plus funding `requirements` and\n   *   `trackedBalances`.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n * ```\n */\nexport const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {\n  const composeClient = createComposeClient(options);\n\n  const request = <T extends InputSchema>(\n    flowDoc: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ): ComposeCompileRequest => ({\n    flow: flowDoc,\n    run: buildRun({\n      inputs: run.inputs as Record<string, InputSpec>,\n      preconditions: run.preconditions,\n      signer: run.signer,\n      assumptions: run.assumptions as Record<string, bigint> | undefined,\n      referrer: run.referrer,\n      integratorFeeBps: run.integratorFeeBps,\n      maxPriceImpactBps: run.maxPriceImpactBps,\n      sweepTo: run.sweepTo,\n      simulationPolicy: run.simulationPolicy,\n      checkOnChainAllowances: run.checkOnChainAllowances,\n    }),\n  });\n\n  const flow = <T extends InputSchema>(\n    chainId: number,\n    opts: FlowOptions<T>,\n  ): FlowBuilder<T> => {\n    const core = createFlowBuilderCore(chainId, opts);\n    const builder = Object.assign(core, bindGeneratedOps(core));\n\n    const compile = async (\n      run: ComposeRunInput<T>,\n    ): Promise<ComposeCompileResult> => {\n      const flowDoc = builder.build();\n      const req = request(flowDoc, run);\n      return composeClient.compile(req);\n    };\n\n    return Object.assign(builder, { compile });\n  };\n\n  return {\n    client: composeClient,\n    flow,\n    request,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":"AAQA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AA+HxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,eAAe,IAAI;AAAA,MACnB,QAAQ,IAAI;AAAA,MACZ,aAAa,IAAI;AAAA,MACjB,UAAU,IAAI;AAAA,MACd,kBAAkB,IAAI;AAAA,MACtB,mBAAmB,IAAI;AAAA,MACvB,SAAS,IAAI;AAAA,MACb,kBAAkB,IAAI;AAAA,MACtB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;AAE1D,UAAM,UAAU,OACd,QACkC;AAClC,YAAM,UAAU,QAAQ,MAAM;AAC9B,YAAM,MAAM,QAAQ,SAAS,GAAG;AAChC,aAAO,cAAc,QAAQ,GAAG;AAAA,IAClC;AAEA,WAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;AAAA,EAC3C;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,UAAU,cAAc;AAAA,EAC1B;AACF;","names":[]}
+{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeRouteRequest,\n  InputSpec,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport {\n  createFlowBuilderCore,\n  type FlowBuilderCore,\n  type FlowOptions,\n  type TypedFlow,\n} from './authoring/FlowBuilderCore.js';\nimport { type ComposeClient, createComposeClient } from './client.js';\nimport {\n  bindGeneratedOps,\n  type GeneratedOps,\n} from './generated/operations.generated.js';\nimport { buildRun, type ComposeRunInput } from './run/inputs.js';\nimport type { InputSchema } from './types.js';\n\nexport type { ComposeRunInput };\n\n/**\n * A flow builder augmented with generated operation methods and a `compile` method\n * that submits the flow to the Compose backend for compilation.\n *\n * Created via {@link ComposeSdk.flow}.\n *\n * @typeParam T - The input schema describing the flow's required inputs.\n */\nexport type FlowBuilder<T extends InputSchema = InputSchema> =\n  FlowBuilderCore<T> &\n    GeneratedOps & {\n      /**\n       * Builds the flow document from the current builder state and submits it\n       * to the Compose API for compilation.\n       *\n       * @param run - Runtime inputs, preconditions, and signer address.\n       * @returns The compiled transaction calldata and metadata.\n       * @throws {@link ComposeError} on network, validation, or server errors.\n       *\n       * @example\n       * ```ts\n       * const result = await builder.compile({\n       *   inputs: { token: materialisers.balanceOf({}) },\n       *   signer: '0xYourAddress...',\n       * });\n       * console.log(result.calldata);\n       * ```\n       */\n      readonly compile: (\n        run: ComposeRunInput<T>,\n      ) => Promise<ComposeCompileResult>;\n    };\n\n/**\n * Configuration for creating a Compose SDK instance.\n */\nexport interface ComposeSdkOptions {\n  /** Base URL of the Compose API (e.g. `\"https://li.quest\"`). */\n  readonly baseUrl: string;\n  /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */\n  readonly apiKey: string;\n}\n\n/**\n * The top-level Compose SDK interface.\n *\n * Provides methods to build flows, compile them into executable calldata, and\n * interact with the Compose API directly.\n *\n * @example\n * ```ts\n * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';\n *\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n *\n * const builder = sdk.flow(1, {\n *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },\n * });\n *\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.usdc },\n *   config: { resourceOut: resources.native(1) },\n * });\n *\n * const result = await builder.compile({\n *   inputs: { usdc: materialisers.balanceOf({}) },\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport interface ComposeSdk {\n  /** Low-level HTTP client for the Compose API. */\n  readonly client: ComposeClient;\n  /**\n   * Creates a new flow builder targeting the given chain.\n   * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n   * @param options - Flow configuration including input declarations.\n   * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.\n   * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.\n   */\n  readonly flow: <T extends InputSchema>(\n    chainId: number,\n    options: FlowOptions<T>,\n  ) => FlowBuilder<T>;\n  /**\n   * Builds a raw compile request without sending it. Useful for inspecting the\n   * request payload or submitting it through a custom transport.\n   * @param flow - A built flow document (from `builder.build()`).\n   * @param run - Runtime inputs, preconditions, and signer address.\n   * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.\n   */\n  readonly request: <T extends InputSchema>(\n    flow: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ) => ComposeCompileRequest;\n  /**\n   * Compiles a token pair on one chain — as of today a single zap step over\n   * one routing-catalog edge. Thin pass-through to\n   * {@link ComposeClient.route}; see it for the current single-step limit,\n   * when to prefer `flow(...).compile(...)`, the `success` / `partial`\n   * discrimination, and error behaviour. Build the `amount` with\n   * `routeAmount.exact(...)` / `routeAmount.all(...)`.\n   *\n   * @param request - The from/to token pair, amount, signer, and route options.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly route: (\n    request: ComposeRouteRequest,\n  ) => Promise<ComposeCompileResult>;\n  /**\n   * Simulates a raw, pre-encoded transaction. Thin pass-through to\n   * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`\n   * result discrimination and error behaviour. Pair with `buildSimulateRequest`\n   * to assemble the request from a compile result.\n   *\n   * @param request - The raw transaction plus funding `requirements` and\n   *   `trackedBalances`.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n * ```\n */\nexport const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {\n  const composeClient = createComposeClient(options);\n\n  const request = <T extends InputSchema>(\n    flowDoc: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ): ComposeCompileRequest => ({\n    flow: flowDoc,\n    run: buildRun({\n      inputs: run.inputs as Record<string, InputSpec>,\n      preconditions: run.preconditions,\n      signer: run.signer,\n      assumptions: run.assumptions as Record<string, bigint> | undefined,\n      referrer: run.referrer,\n      integratorFeeBps: run.integratorFeeBps,\n      maxPriceImpactBps: run.maxPriceImpactBps,\n      sweepTo: run.sweepTo,\n      simulationPolicy: run.simulationPolicy,\n      checkOnChainAllowances: run.checkOnChainAllowances,\n    }),\n  });\n\n  const flow = <T extends InputSchema>(\n    chainId: number,\n    opts: FlowOptions<T>,\n  ): FlowBuilder<T> => {\n    const core = createFlowBuilderCore(chainId, opts);\n    const builder = Object.assign(core, bindGeneratedOps(core));\n\n    const compile = async (\n      run: ComposeRunInput<T>,\n    ): Promise<ComposeCompileResult> => {\n      const flowDoc = builder.build();\n      const req = request(flowDoc, run);\n      return composeClient.compile(req);\n    };\n\n    return Object.assign(builder, { compile });\n  };\n\n  return {\n    client: composeClient,\n    flow,\n    request,\n    route: composeClient.route,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":"AASA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AA8IxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,eAAe,IAAI;AAAA,MACnB,QAAQ,IAAI;AAAA,MACZ,aAAa,IAAI;AAAA,MACjB,UAAU,IAAI;AAAA,MACd,kBAAkB,IAAI;AAAA,MACtB,mBAAmB,IAAI;AAAA,MACvB,SAAS,IAAI;AAAA,MACb,kBAAkB,IAAI;AAAA,MACtB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;AAE1D,UAAM,UAAU,OACd,QACkC;AAClC,YAAM,UAAU,QAAQ,MAAM;AAC9B,YAAM,MAAM,QAAQ,SAAS,GAAG;AAChC,aAAO,cAAc,QAAQ,GAAG;AAAA,IAClC;AAEA,WAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;AAAA,EAC3C;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,OAAO,cAAc;AAAA,IACrB,UAAU,cAAc;AAAA,EAC1B;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.4.0-staging.1",
+  "version": "0.4.1",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -51,7 +51,7 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.4.0-staging.1"
+    "@lifi/compose-spec": "0.4.1"
   },
   "dependencies": {
     "abitype": "^1.2.3",
@@ -62,8 +62,8 @@
     "@eslint/compat": "^1.4.0",
     "@lifi/compose-spec": "workspace:^",
     "@types/node": "^25.6.0",
-    "@typescript-eslint/eslint-plugin": "^8.44.1",
-    "@typescript-eslint/parser": "^8.44.1",
+    "@typescript-eslint/eslint-plugin": "^8.68.0",
+    "@typescript-eslint/parser": "^8.68.0",
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-eslint-comments": "^3.2.0",
@@ -74,7 +74,7 @@
     "prettier": "^3.9.4",
     "tsup": "^8.5.1",
     "tsx": "^4.20.4",
-    "typescript": "^5.9.2",
+    "typescript": "^6.0.3",
     "vitest": "^3.2.4"
   },
   "files": [
@@ -85,6 +85,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.mock.ts",
     "!src/**/*.typecheck.ts",
-    "!dist/**/*.typecheck.*"
+    "!dist/**/*.typecheck.*",
+    "!src/examples/staged/**"
   ]
 }

package/src/authoring/raw.ts

@@ -35,8 +35,9 @@ import type { OutputKind, TypedRef } from '../types.js';
  * });
  * ```
  */
-export const ref = <T extends OutputKind>(path: string): TypedRef<T> =>
-  ({ $ref: path }) as TypedRef<T>;
+export const ref = <T extends OutputKind>(path: string): TypedRef<T> => ({
+  $ref: path,
+});
 
 /**
  * Creates a raw guard object for use in the `guards` array of an operation call.

package/src/client.ts

@@ -4,6 +4,7 @@ import type {
   ComposeCompileResult,
   ComposeCompileSuccessData,
   ComposeManifest,
+  ComposeRouteRequest,
   SimulateRequest,
   SimulateResult,
 } from '@lifi/compose-spec';
@@ -69,6 +70,38 @@ export interface ComposeClient {
   readonly compile: (
     request: ComposeCompileRequest,
   ) => Promise<ComposeCompileResult>;
+  /**
+   * Compiles a token pair into a submit-ready transaction via
+   * `POST /compose/route`.
+   *
+   * A convenience path that skips flow authoring: the server builds a one-node
+   * `lifi.zap` flow with a `directDeposit` input from the `fromToken` /
+   * `toToken` pair and runs it through the same pipeline as {@link compile}.
+   * The response is therefore the same discriminated result — HTTP 206 under
+   * `simulationPolicy: 'allow-revert'` yields `status: 'partial'` rather than
+   * throwing, exactly as it does for {@link compile}.
+   *
+   * As of today that flow is a single zap step: one edge of the backend's
+   * routing catalog (a position entry or exit, a wrap or unwrap, a mint or
+   * burn). Enumerate the pairs it covers with {@link getZapPacks}; a pair with
+   * no edge is rejected with `kind: 'no_route_error'`. The endpoint is meant to
+   * author richer flows later, so the single-step limit is the current state of
+   * the server, not the shape of this contract.
+   *
+   * Use {@link compile} for what the server does not author for you: several
+   * chained operations, splits, explicit preconditions, or per-op guards.
+   *
+   * `bigint` amounts in `amount` are serialised to decimal strings
+   * automatically.
+   *
+   * @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 —
+   *   including `NOT_FOUND` (HTTP 404) when no catalog edge covers the pair.
+   */
+  readonly route: (
+    request: ComposeRouteRequest,
+  ) => Promise<ComposeCompileResult>;
   /**
    * Fetches the available routing edges grouped by protocol.
    *
@@ -173,6 +206,39 @@ const parseSimulateBody = async (
   }
   return result;
 };
+// `POST /compose` and `POST /compose/route` differ only in path and request
+// shape: both return the enveloped success data on 200 and the partial
+// envelope on 206, so they share one transport.
+type ComposeTransport = {
+  readonly fetchFn: typeof fetch;
+  readonly baseHeaders: Record<string, string>;
+};
+
+const postCompile = async (
+  { fetchFn, baseHeaders }: ComposeTransport,
+  url: string,
+  request: ComposeCompileRequest | ComposeRouteRequest,
+): Promise<ComposeCompileResult> => {
+  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);
+};
 
 /**
  * Creates a low-level Compose API client.
@@ -204,6 +270,7 @@ export const createComposeClient = (
     'x-lifi-composer-sdk': SDK_VERSION,
     'x-lifi-api-key': trimmedApiKey,
   };
+  const transport: ComposeTransport = { fetchFn, baseHeaders };
 
   const getManifest = async (): Promise<ComposeManifest> => {
     const url = `${base}/compose/manifest`;
@@ -226,28 +293,13 @@ export const createComposeClient = (
 
   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);
-  };
+  ): Promise<ComposeCompileResult> =>
+    postCompile(transport, `${base}/compose`, request);
+
+  const route = async (
+    request: ComposeRouteRequest,
+  ): Promise<ComposeCompileResult> =>
+    postCompile(transport, `${base}/compose/route`, request);
 
   const getZapPacks = async (
     options?: GetZapPacksOptions,
@@ -306,5 +358,5 @@ export const createComposeClient = (
     throw errorFromHttpResponse(res.status, body, url);
   };
 
-  return { getManifest, compile, getZapPacks, simulate };
+  return { getManifest, compile, route, getZapPacks, simulate };
 };

package/src/discovery.ts

@@ -26,6 +26,19 @@ export interface ZapPackEdge {
   readonly inAmountMin?: string;
   /** Maximum input amount accepted (stringified integer), if constrained. */
   readonly inAmountMax?: string;
+  /**
+   * Recipient binding obligation. `"required"` means the zap must bind its
+   * `recipient` input. The output is externally owned, terminal, and unswept.
+   * The loose string type preserves forward compatibility with new values.
+   */
+  readonly recipient?: string;
+  /**
+   * Output availability. `"future"` means the output becomes available only
+   * after the initiating transaction settles; route via `lifi.zapAsync` with
+   * a bound recipient. Absent means the output is available synchronously.
+   * The loose string type preserves forward compatibility with new values.
+   */
+  readonly availability?: string;
 }
 
 /**

package/src/examples/lifiZap.ts

@@ -53,6 +53,10 @@ export const buildLifiZapExample = (): {
     inputs: {
       amountIn: materialisers.directDeposit({ amount: '1000000000' }),
     },
+    // This zap's edge keeps `amountOut` inside the execution VM, so sweeping
+    // leftovers back to the sender is safe. Omit `sweepTo` for an edge that
+    // delivers externally (`recipient: 'required'` in discovery): the output
+    // never enters the VM, so a sweep would find nothing to move.
     sweepTo: builder.context.sender,
   });
 

package/src/examples/lifiZapAsync.ts

@@ -0,0 +1,88 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+import type { Address } from '../types.js';
+
+import { API_KEY, BASE_URL } from './config.js';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+// Aave aEthUSDC receipt token on Ethereum mainnet
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+
+export interface LifiZapAsyncInput {
+  readonly owner: Address;
+  readonly recipient: Address;
+}
+
+/**
+ * Zap USDC into a DeFi position whose output settles asynchronously via LI.FI.
+ *
+ * Demonstrates:
+ * - `lifi.zapAsync`, the future-availability sibling of `lifi.zap`
+ * - Binding the required `recipient` input (the async op has no optional
+ *   recipient — the decl is non-optional, so `bind.recipient` is mandatory)
+ * - Omitting `sweepTo`: `availability: 'future'` governs custody, so the
+ *   output is delivered externally and never enters the execution VM — a
+ *   sweep would find nothing to move (custody, not amount reporting)
+ * - Amount reporting is unaffected by availability: when the async lowering
+ *   binds a terminal handle the output still reports `simulated.amountOut`,
+ *   the protocol's in-transaction expected value (an estimate; the delivered
+ *   amount arrives after settlement). `simulated.amountOutMin` appears only
+ *   when a minimum source exists — for a future output that means a floor the
+ *   edge lowering itself reported, never a user guard
+ * - No output guards: the reported value is the initiating-transaction
+ *   estimate, not the asynchronously delivered amount a guard could enforce,
+ *   so `amountOut` is excluded from the generated `TypedGuard` union
+ *   (`guards` typechecks as `TypedGuard<never>[]`) and the compiler rejects
+ *   any guard on it
+ */
+export const buildLifiZapAsyncExample = ({
+  owner,
+  recipient,
+}: LifiZapAsyncInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  // Declare the flow with a single USDC input and the recipient address input.
+  const builder = sdk.flow(1, {
+    name: 'zap-async-usdc-to-aave',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+      recipient: 'address',
+    },
+  });
+
+  // Zap USDC into an async Aave position via LI.FI.
+  // The future output is delivered to `recipient` once the initiating
+  // transaction settles; the recipient binding is required by the op.
+  builder.lifi.zapAsync('zap', {
+    bind: {
+      amountIn: builder.inputs.amountIn,
+      recipient: builder.inputs.recipient,
+    },
+    config: {
+      resourceOut: resources.erc20(A_ETH_USDC, 1),
+    },
+  });
+
+  const flow = builder.build();
+
+  // Build the compile request.
+  // directDeposit transfers a fixed amount of USDC into the VM; the recipient
+  // handle passes the delivery address as a plain string.
+  // No `sweepTo`: the async output is delivered externally to the recipient,
+  // never landing in the VM for a sweep to reach.
+  // NOTE: no production edge sets `availability: 'future'` yet, so this request
+  // resolves to a typed no_route today; it documents the intended shape.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000000' }),
+      recipient,
+    },
+  });
+
+  return { flow, request };
+};

package/src/examples/routeTokenPair.ts

@@ -0,0 +1,58 @@
+import type { ComposeRouteRequest } from '@lifi/compose-spec';
+
+import { routeAmount } from '../index.js';
+
+import { OWNER } from './config.js';
+
+const NATIVE_ETH = '0x0000000000000000000000000000000000000000';
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+
+/**
+ * Wrap 0.1 native ETH into WETH on Ethereum mainnet through
+ * `POST /compose/route`.
+ *
+ * Demonstrates:
+ * - The convenience path: a from/to token pair instead of an authored flow.
+ *   The pair resolves to the catalog's `wrap` edge, and the server authors the
+ *   zap step for it
+ * - `routeAmount.exact` for a fixed input amount (`bigint`, serialised on send)
+ * - The native sentinel address as `fromToken`
+ *
+ * Pure: returns a plain {@link ComposeRouteRequest}, performs no network I/O.
+ * Pass it to `sdk.route(...)` / `sdk.client.route(...)` to compile it.
+ */
+export const buildRouteExactExample = (): ComposeRouteRequest => ({
+  chainId: 1,
+  fromToken: NATIVE_ETH,
+  toToken: WETH,
+  amount: routeAmount.exact(100_000_000_000_000_000n), // 0.1 ETH
+  signer: OWNER,
+  slippageBps: 100,
+});
+
+/**
+ * Unwrap the signer's entire WETH balance back into native ETH on Ethereum
+ * mainnet — the catalog's `unwrap` edge.
+ *
+ * Demonstrates:
+ * - `routeAmount.all` for a balance resolved on-chain at execution time, where
+ *   the passed value is only the quoting stand-in
+ * - `sweepTo` naming the address that receives the output
+ * - `checkOnChainAllowances` so already-sufficient approvals are omitted from
+ *   the response
+ *
+ * Pure: returns a plain {@link ComposeRouteRequest}, performs no network I/O.
+ */
+export const buildRouteAllExample = (): ComposeRouteRequest => ({
+  chainId: 1,
+  fromToken: WETH,
+  toToken: NATIVE_ETH,
+  // Estimate of the balance on hand — the quote and the derived preconditions
+  // are computed against this, but the amount actually moved is the real
+  // balance at execution time.
+  amount: routeAmount.all(10n ** 18n), // ~1 WETH
+  signer: OWNER,
+  sweepTo: OWNER,
+  slippageBps: 50,
+  checkOnChainAllowances: true,
+});

package/src/examples/run.ts

@@ -20,6 +20,7 @@
  *   split-zap         — split USDC 60/40 and zap into Aave + Morpho vaults
  *   split-arithmetic  — split USDC 70/30 with arithmetic assertions
  *   zap               — zap USDC into Aave lending position
+ *   zap-async         — zap USDC into an async Aave position (future output)
  *   swap-zap          — swap WETH to USDC then zap into Aave
  *   swap-check        — swap WETH to USDC with balance check
  *   swap-recipient    — swap WETH + DAI to USDC and send to recipient
@@ -32,8 +33,13 @@
  *   transfer          — transfer full token balance to a recipient
  *   partial-transfer  — transfer a specific amount, keeping the remainder
  *   untyped-ref       — mix untypedOp with typed handles via raw.ref
+ *   route-exact       — wrap 0.1 native ETH into WETH via /compose/route
+ *   route-all         — unwrap the whole WETH balance to ETH via /compose/route
  */
-import type { ComposeCompileRequest } from '@lifi/compose-spec';
+import type {
+  ComposeCompileRequest,
+  ComposeRouteRequest,
+} from '@lifi/compose-spec';
 
 import { createComposeSdk } from '../sdk.js';
 
@@ -49,8 +55,13 @@ import { buildDepositFromProxy } from './depositFromProxy.js';
 import { buildDustSweepExample } from './dustSweep.js';
 import { buildLifiSwapExample } from './lifiSwap.js';
 import { buildLifiZapExample } from './lifiZap.js';
+import { buildLifiZapAsyncExample } from './lifiZapAsync.js';
 import { buildRawCallWithArithmetic } from './rawCallWithArithmetic.js';
 import { buildReadContractState } from './readContractState.js';
+import {
+  buildRouteAllExample,
+  buildRouteExactExample,
+} from './routeTokenPair.js';
 import { buildSplitAndZapExample } from './splitAndZap.js';
 import { buildSplitWithArithmetic } from './splitWithArithmetic.js';
 import { buildSwapAndZapExample } from './swapAndZap.js';
@@ -106,6 +117,8 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   'split-arithmetic': () =>
     buildSplitWithArithmetic({ owner: OWNER, amount: '1000000000' }).request,
   zap: () => buildLifiZapExample().request,
+  'zap-async': () =>
+    buildLifiZapAsyncExample({ owner: OWNER, recipient: RECIPIENT }).request,
   'swap-zap': () => buildSwapAndZapExample().request,
   'swap-check': () =>
     buildSwapWithBalanceCheck({ owner: OWNER, amount: '1000000000000000000' })
@@ -146,6 +159,13 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   'untyped-ref': () => buildUntypedOpWithTypedRef({ owner: OWNER }).request,
 };
 
+// `/compose/route` examples build a `ComposeRouteRequest` and go to
+// `sdk.route`, not `sdk.client.compile`, so they live in their own registry.
+const ROUTE_EXAMPLES: Record<string, () => ComposeRouteRequest> = {
+  'route-exact': buildRouteExactExample,
+  'route-all': buildRouteAllExample,
+};
+
 const run = async () => {
   const args = process.argv.slice(2);
   const useStaged = args.includes('--staged');
@@ -166,10 +186,13 @@ const run = async () => {
     examples = { ...EXAMPLES, ...stagedModule.STAGED_EXAMPLES };
   }
 
+  const routeBuilder = name ? ROUTE_EXAMPLES[name] : undefined;
   const builder = name ? examples[name] : undefined;
 
-  if (!builder) {
-    const valid = Object.keys(examples).join(', ');
+  if (!builder && !routeBuilder) {
+    const valid = [...Object.keys(examples), ...Object.keys(ROUTE_EXAMPLES)]
+      .sort()
+      .join(', ');
     console.error(
       `Error: ${
         name ? `unknown example "${name}"` : 'no example specified'
@@ -181,7 +204,7 @@ const run = async () => {
   }
   console.log(`Running example: ${name}`);
 
-  const request = builder();
+  const request = routeBuilder ? routeBuilder() : builder!();
   const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   console.log('--- Request ---');
@@ -195,7 +218,9 @@ const run = async () => {
   );
 
   console.log(`\n--- Compiling against ${BASE_URL} ---`);
-  const result = await sdk.client.compile(request);
+  const result = routeBuilder
+    ? await sdk.route(request as ComposeRouteRequest)
+    : await sdk.client.compile(request as ComposeCompileRequest);
 
   console.log('\n--- Result ---');
   console.log(JSON.stringify(result, null, 2));

package/src/generated/config.generated.ts

@@ -203,9 +203,14 @@ export interface CoreCallConfig {
           )[]
       )[]
   )[];
-  approvals?: {
-    spender: Address;
-  }[];
+  approvals?: (
+    | {
+        spender: Address;
+      }
+    | {
+        from: 'sender';
+      }
+  )[];
 }
 
 export interface CoreStaticCallConfig {
@@ -684,6 +689,19 @@ export interface LifiZapConfig {
       };
 }
 
+export interface LifiZapAsyncConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+}
+
 export interface ParaswapBuyConfig {
   resourceOut:
     | {

package/src/generated/materialisers.generated.ts

@@ -10,7 +10,6 @@ import type {
   BalanceOfMaterialiserConfig as BalanceOfMaterialiserConfigSchema,
   CallMaterialiserConfig as CallMaterialiserConfigSchema,
   DirectDepositMaterialiserConfig as DirectDepositMaterialiserConfigSchema,
-  FlashloanMaterialiserConfig as FlashloanMaterialiserConfigSchema,
 } from './config.generated.js';
 
 export type BalanceOfMaterialiserConfig =
@@ -43,14 +42,3 @@ export const call = (config: CallMaterialiserConfig): MaterialiserInput => ({
   kind: 'call',
   ...config,
 });
-
-export type FlashloanMaterialiserConfig =
-  MaterialiserConfigOf<FlashloanMaterialiserConfigSchema>;
-
-/** Borrow tokens from a flashloan provider; amount becomes a register populated by the proxy at callback time — accepts: resource */
-export const flashloan = (
-  config: FlashloanMaterialiserConfig,
-): MaterialiserInput => ({
-  kind: 'flashloan',
-  ...config,
-});