@lifi/composer-sdk 0.4.0 → 0.4.1

package/README.md

@@ -122,9 +122,11 @@ if (result.status === 'success') {
 ## API surface
 
 **SDK factory**
+
 - `createComposeSdk({ baseUrl, apiKey, fetch? })` — creates the SDK instance
 
 **Flow building**
+
 - `sdk.flow(chainId, options)` — creates a `FlowBuilder`
 - `builder.<namespace>.<operation>(id, { bind, config })` — adds an operation, returns typed `OutputHandle<T>` per port
 - `builder.untypedOp(id, op, args)` — escape hatch for operations not in the manifest (returns `void`; use `raw.ref<T>()` to reference its outputs)
@@ -132,12 +134,15 @@ if (result.status === 'success') {
 - `sdk.request(flow, { signer, inputs, preconditions, sweepTo, ... })` — builds a compile request
 
 **HTTP client**
+
 - `sdk.client.compile(request)` — sends the flow to the backend and returns a `ComposeCompileResult` (discriminated union: `status: 'success'` or `status: 'partial'`)
 - `sdk.client.getManifest()` — fetches the operation manifest
-- `sdk.client.getZapPacks(options?)` — fetches the available routing edges grouped by protocol, returning `ZapPackOverview[]`. The catalog is dynamic (reflects the backend's current routing snapshot) and is not cached by the SDK. Filter to specific protocols via `GetZapPacksOptions`; each entry's edges are typed as `ZapPackEdge`.
+- `sdk.client.getZapPacks(options?)` — fetches the available routing edges grouped by protocol, returning `ZapPackOverview[]`. The catalog is dynamic and is not cached by the SDK. Filter through `GetZapPacksOptions`. An edge with `recipient: 'required'` requires the zap's `recipient` binding, delivers the output externally, and produces an output that cannot be chained or swept. An edge with `availability: 'future'` produces an output that settles only after the initiating transaction; route it via `lifi.zapAsync` with a bound `recipient`. Availability governs custody only — a future output still reports `simulated.amountOut` (an in-transaction estimate; the delivered amount arrives after settlement), with `simulated.amountOutMin` present only when a minimum source exists.
 - `sdk.client.simulate(request)` / `sdk.simulate(request)` — simulates a raw, pre-encoded transaction and returns a `SimulateResult` (discriminated union: `status: 'ok' | 'revert' | 'error'`). See [Simulating a raw transaction](#simulating-a-raw-transaction).
+- `sdk.client.route(request)` / `sdk.route(request)` — compiles a single from/to token pair on one chain via `POST /compose/route`, returning the same `ComposeCompileResult` as `compile()`. See [Routing a token pair](#routing-a-token-pair).
 
 **Helpers**
+
 - `resources.erc20(address, chainId)` / `resources.native(chainId)` — resource constructors
 - `guards.*` — guard factories (e.g., slippage)
 - `materialisers.*` — materialiser factories (directDeposit, balanceOf, call)
@@ -145,6 +150,87 @@ if (result.status === 'success') {
 - `raw.ref<T>(path)` — create a typed `$ref` pointer for use in bind slots (escape hatch for `untypedOp` outputs)
 - `raw.guard(kind, config?)` / `raw.materialiser(kind, config?)` — low-level factories for guards and materialisers
 - `buildSimulateRequest({ result, chainId, signer, trackedBalances, requirements?, block?, value? })` — assembles a `SimulateRequest` from a compile result (pure, no I/O)
+- `routeAmount.exact(amount)` / `routeAmount.all(simAmount)` — amount constructors for `sdk.route(...)`
+
+## Routing a token pair
+
+Authoring a flow is the general path: you decide the operations and how they chain. `sdk.route(...)` is the shortcut for the case where the backend can decide for you — you hand it a from/to token pair, an amount, and a signer, and it returns the same submit-ready `ComposeCompileResult` that `compile()` returns.
+
+As of today the backend authors a single zap step for that pair: one edge of its routing catalog — entering or exiting a protocol position, a wrap or unwrap, a mint or burn. It is not a swap aggregator, so a pair with no catalog edge (WETH to USDC, for instance) comes back as `no_route_error`. The endpoint is meant to author more complex flows in future releases, so read the single-step limit as where the server is today rather than as the boundary of the API.
+
+```ts
+import { createComposeSdk, routeAmount } from '@lifi/composer-sdk';
+
+const sdk = createComposeSdk({
+  baseUrl: 'https://composer.li.quest',
+  apiKey: process.env.LIFI_API_KEY!,
+});
+
+const result = await sdk.route({
+  chainId: 1,
+  fromToken: '0x0000000000000000000000000000000000000000', // native ETH
+  toToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH — a `wrap` edge
+  amount: routeAmount.exact(100_000_000_000_000_000n), // 0.1 ETH
+  signer: '0xYourAddress...',
+  slippageBps: 100,
+});
+
+if (result.status === 'success') {
+  console.log(result.transactionRequest); // to, data, value, gasLimit
+}
+```
+
+### Discovering routable pairs
+
+The catalog is dynamic — protocols, chains, and token blacklists move — so discover pairs instead of hardcoding them:
+
+```ts
+const packs = await sdk.client.getZapPacks({ protocols: 'aave' });
+
+for (const pack of packs) {
+  for (const edge of pack.edges) {
+    console.log(pack.protocol, edge.type, edge.in.address, '->', edge.out.address);
+  }
+}
+```
+
+Every edge is one routable pair: `edge.in` and `edge.out` are the `fromToken` and `toToken` of a `route` call on `edge.in.chainId`, and `inAmountMin` / `inAmountMax` bound the amount when the protocol constrains it. Two edge fields change how you call `route`:
+
+- **`recipient: 'required'`** — the protocol mints to a named receiver, so set `sweepTo` when the output should not land with the signer.
+- **`availability: 'future'`** — the output only exists once the transaction settles. `route` cannot compile these; they need `lifi.zapAsync` on the authoring path.
+
+### Amounts
+
+The `amount` field is a discriminated union with two variants, built by `routeAmount`:
+
+- **`routeAmount.exact(amount)`** — spend exactly `amount` of `fromToken`, in its smallest unit. Use this when you know the figure.
+- **`routeAmount.all(simAmount)`** — spend the signer's whole `fromToken` balance, resolved on-chain at execution time. `simAmount` is only an estimate: the quote, the price impact, and the returned approvals are computed against it, but the amount actually moved is the real balance when the transaction lands. Pass your best estimate of the balance — a wildly wrong figure produces a poor quote. Not supported for a native `fromToken`: a gas coin arrives via `msg.value`, so there is no balance to sweep, and the server rejects the request.
+
+Both accept a `bigint` or a decimal string. `bigint` values are serialised for you.
+
+### Options
+
+`sdk.route(...)` shares its optional fields with the authoring path, and the server applies the same defaults. Omit a field to take the default; the SDK sends only what you set.
+
+- **`slippageBps`** — tolerance in basis points. Defaults to `100` (1%).
+- **`maxPriceImpactBps`** — reject the route if the priced impact exceeds this. No cap by default.
+- **`integratorFeeBps`** — your fee, in basis points, taken from the input amount before the route executes. Requires an integration-scoped `apiKey`; a non-zero value without one is rejected.
+- **`referrer`** — attribution string passed to the routing provider.
+- **`sweepTo`** — address that receives the output and any leftover dust. Accepts a literal address or `{ $ref: 'context.sender' }`. Defaults to the signer.
+- **`checkOnChainAllowances`** — when `true`, the server reads current allowances and omits approvals that are already sufficient. Defaults to `false`.
+- **`simulationPolicy`** — `'strict'` (default) or `'allow-revert'`, exactly as on the authoring path. See [Simulation policy and partial results](#simulation-policy-and-partial-results).
+- **`simulateUserProgram`** — when `true`, additionally simulates the final user-facing transaction after the structured simulation succeeds. Defaults to `false`.
+
+### When to author a flow instead
+
+`route` gives you one server-authored step. Reach for `sdk.flow(...)` when you need anything it does not express: several operations chained together, splitting one input across several destinations, guards on intermediate outputs, explicit preconditions, arithmetic, funding from proxy-held balances, or an asynchronous position (`availability: 'future'`) as the destination. Swapping WETH to USDC and then depositing the USDC into Aave is a flow; depositing USDC straight into Aave is a route.
+
+### Errors
+
+`route` maps failures the same way `compile` does — see [Error handling](#error-handling). Two are specific to this path:
+
+- **`NOT_FOUND`** with `kind: 'no_route_error'` — the backend has no routing edge for the pair on that chain. `sdk.client.getZapPacks()` reports which edges exist.
+- **`VALIDATION_ERROR`** — the pair is routable but the request is rejected, for example a price impact above `maxPriceImpactBps`, or a simulation revert under the default `'strict'` policy.
 
 ## Simulation policy and partial results
 
@@ -164,12 +250,12 @@ if (result.status === 'success') {
 } else {
   // result.status === 'partial'
   // Simulation reverted, but a transaction is still available (without gasLimit).
-  console.log(result.error.kind);    // 'simulation_revert'
+  console.log(result.error.kind); // 'simulation_revert'
   console.log(result.error.message); // human-readable revert description
 
   // Revert diagnostics
   const revert = result.simulationRevert;
-  console.log(revert.code);          // e.g. 3
+  console.log(revert.code); // e.g. 3
   console.log(revert.rawErrorBytes); // raw ABI-encoded error
 
   // Decoded error candidates (when available)
@@ -186,6 +272,7 @@ if (result.status === 'success') {
 ```
 
 The `simulationPolicy` field accepts two values:
+
 - `'strict'` (default) — revert causes a thrown `ComposeError` with code `VALIDATION_ERROR`
 - `'allow-revert'` — revert returns a partial result with `status: 'partial'`
 
@@ -201,7 +288,7 @@ const result = await builder.compile({
 
 ## Simulating a raw transaction
 
-`sdk.client.simulate(...)` (and the `sdk.simulate(...)` pass-through) answer a question the compile pipeline does not: *if I send this exact transaction, how do specific token balances change and how much gas does it burn?* It takes a raw, pre-encoded transaction (a `to`, hex `data`, optional native `value`), funds a sender, runs it in one `eth_call`, and reports the watched balances before/after, their signed deltas, and the inner-call gas.
+`sdk.client.simulate(...)` (and the `sdk.simulate(...)` pass-through) answer a question the compile pipeline does not: _if I send this exact transaction, how do specific token balances change and how much gas does it burn?_ It takes a raw, pre-encoded transaction (a `to`, hex `data`, optional native `value`), funds a sender, runs it in one `eth_call`, and reports the watched balances before/after, their signed deltas, and the inner-call gas.
 
 ```ts
 import { createComposeSdk } from '@lifi/composer-sdk';
@@ -255,7 +342,7 @@ switch (result.status) {
 
 `requirements` is the funding-instruction union (`Erc20Balance`, `NativeBalance`, `Erc20Allowance`); use the zero address as a `trackedBalances` `token` to watch native balance. Amount fields accept `bigint` (serialised to decimal strings) or strings. The caps `SIMULATE_MAX_TRACKED_BALANCES` and `SIMULATE_MAX_REQUIREMENTS` (both `40`) are exported for reference.
 
-Unlike `compile`, a `revert` is returned (not thrown): a revert is a *successful simulation* whose execution reverted. Only transport failures and HTTP 400/401/403/404/429/5xx throw `ComposeError`.
+Unlike `compile`, a `revert` is returned (not thrown): a revert is a _successful simulation_ whose execution reverted. Only transport failures and HTTP 400/401/403/404/429/5xx throw `ComposeError`.
 
 To simulate a transaction you just compiled, `buildSimulateRequest(...)` assembles the request without re-typing the transaction fields. `chainId` and `signer` are required (a compile result carries neither), and `trackedBalances`/`requirements` cannot be inferred from a flow:
 
@@ -325,6 +412,7 @@ The `src/examples/` directory contains complete working examples:
 
 - **lifiSwap** — Single token swap (WETH to USDC)
 - **lifiZap** — Swap into a DeFi position
+- **lifiZapAsync** — Zap into a position whose output settles after the initiating transaction (future availability)
 - **swapAndZap** — Multi-step: swap then deposit
 - **splitAndZap** — Split a resource and zap each portion into a different vault
 - **splitWithArithmetic** — Split then verify with add/subtract/assertEqual assertions
@@ -347,6 +435,7 @@ The `src/examples/` directory contains complete working examples:
 - **aaveClaimRewards** — Claim accrued Aave rewards and forward the claimed amount to a recipient
 - **aaveSetEMode** — Switch the proxy's Aave v3 eMode category
 - **untypedOpWithTypedRef** — Insert an untyped operation node via `untypedOp`, then bridge its output into typed operations using `raw.ref<T>()`
+- **routeTokenPair** — Compile a from/to token pair via `sdk.route(...)`, with both the `exact` and `all` amount variants
 
 ## Staging channel
 
@@ -370,6 +459,7 @@ const sdk = createComposeSdk({
 Calling a staged operation against a backend that does not have it enabled fails at runtime as a service-level error; the typed surface being present does not guarantee backend availability.
 
 The channel and the backend URL are independent:
+
 - The `staging` **channel** is durable — it is a permanent property of `main`, and which operations it carries rotates over time as ops graduate to `latest`.
 - The `baseUrl` is **per-environment and disposable** — it is a runtime argument, not a build-time property, so the same staging build can target whichever backend currently has the ops enabled.
 

package/dist/authoring/raw.cjs

@@ -22,7 +22,9 @@ __export(raw_exports, {
   ref: () => ref
 });
 module.exports = __toCommonJS(raw_exports);
-const ref = (path) => ({ $ref: path });
+const ref = (path) => ({
+  $ref: path
+});
 const rawGuard = (kind, config = {}) => {
   if ("kind" in config) {
     throw new Error(

package/dist/authoring/raw.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/authoring/raw.ts"],"sourcesContent":["import type { AppliedGuard } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * Creates a typed `$ref` pointer for use in bind slots.\n *\n * This is an **escape hatch** for referencing values that the typed builder\n * API doesn't cover — for example, outputs of an `untypedOp` node or custom\n * context paths. The caller is responsible for choosing the correct type\n * parameter; no runtime validation occurs.\n *\n * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`\n * whenever possible. Use `ref` only when you need to construct a `$ref` path\n * manually and want it accepted by a `Bindable<T>` slot.\n *\n * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).\n * @param path - The `$ref` path (e.g. `\"context.sender\"`, `\"myNode.result\"`).\n * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.\n *\n * @example\n * ```ts\n * import { raw } from '@lifi/composer-sdk';\n *\n * // Reference an untypedOp output in a typed operation:\n * builder.untypedOp('custom', 'some.op', {\n *   bind: { x: { $ref: 'input.token' } },\n *   config: {},\n * });\n * builder.core.add('sum', {\n *   bind: {\n *     a: raw.ref<'uint256'>('custom.result'),\n *     b: someTypedHandle,\n *   },\n * });\n * ```\n */\nexport const ref = <T extends OutputKind>(path: string): TypedRef<T> =>\n  ({ $ref: path }) as TypedRef<T>;\n\n/**\n * Creates a raw guard object for use in the `guards` array of an operation call.\n *\n * @param kind - The guard type (e.g. `\"slippage\"`).\n * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).\n * @returns An {@link AppliedGuard} object.\n */\nexport const rawGuard = (\n  kind: string,\n  config: Record<string, unknown> = {},\n): AppliedGuard => {\n  if ('kind' in config) {\n    throw new Error(\n      `rawGuard: 'kind' must not appear in config (got \"${String(\n        config.kind,\n      )}\"). Pass it as the first argument instead.`,\n    );\n  }\n  return { ...config, kind };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqCO,MAAM,MAAM,CAAuB,UACvC,EAAE,MAAM,KAAK;AAST,MAAM,WAAW,CACtB,MACA,SAAkC,CAAC,MAClB;AACjB,MAAI,UAAU,QAAQ;AACpB,UAAM,IAAI;AAAA,MACR,oDAAoD;AAAA,QAClD,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,KAAK;AAC3B;","names":[]}
+{"version":3,"sources":["../../src/authoring/raw.ts"],"sourcesContent":["import type { AppliedGuard } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * Creates a typed `$ref` pointer for use in bind slots.\n *\n * This is an **escape hatch** for referencing values that the typed builder\n * API doesn't cover — for example, outputs of an `untypedOp` node or custom\n * context paths. The caller is responsible for choosing the correct type\n * parameter; no runtime validation occurs.\n *\n * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`\n * whenever possible. Use `ref` only when you need to construct a `$ref` path\n * manually and want it accepted by a `Bindable<T>` slot.\n *\n * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).\n * @param path - The `$ref` path (e.g. `\"context.sender\"`, `\"myNode.result\"`).\n * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.\n *\n * @example\n * ```ts\n * import { raw } from '@lifi/composer-sdk';\n *\n * // Reference an untypedOp output in a typed operation:\n * builder.untypedOp('custom', 'some.op', {\n *   bind: { x: { $ref: 'input.token' } },\n *   config: {},\n * });\n * builder.core.add('sum', {\n *   bind: {\n *     a: raw.ref<'uint256'>('custom.result'),\n *     b: someTypedHandle,\n *   },\n * });\n * ```\n */\nexport const ref = <T extends OutputKind>(path: string): TypedRef<T> => ({\n  $ref: path,\n});\n\n/**\n * Creates a raw guard object for use in the `guards` array of an operation call.\n *\n * @param kind - The guard type (e.g. `\"slippage\"`).\n * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).\n * @returns An {@link AppliedGuard} object.\n */\nexport const rawGuard = (\n  kind: string,\n  config: Record<string, unknown> = {},\n): AppliedGuard => {\n  if ('kind' in config) {\n    throw new Error(\n      `rawGuard: 'kind' must not appear in config (got \"${String(\n        config.kind,\n      )}\"). Pass it as the first argument instead.`,\n    );\n  }\n  return { ...config, kind };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqCO,MAAM,MAAM,CAAuB,UAA+B;AAAA,EACvE,MAAM;AACR;AASO,MAAM,WAAW,CACtB,MACA,SAAkC,CAAC,MAClB;AACjB,MAAI,UAAU,QAAQ;AACpB,UAAM,IAAI;AAAA,MACR,oDAAoD;AAAA,QAClD,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,KAAK;AAC3B;","names":[]}

package/dist/authoring/raw.js

@@ -1,4 +1,6 @@
-const ref = (path) => ({ $ref: path });
+const ref = (path) => ({
+  $ref: path
+});
 const rawGuard = (kind, config = {}) => {
   if ("kind" in config) {
     throw new Error(

package/dist/authoring/raw.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/authoring/raw.ts"],"sourcesContent":["import type { AppliedGuard } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * Creates a typed `$ref` pointer for use in bind slots.\n *\n * This is an **escape hatch** for referencing values that the typed builder\n * API doesn't cover — for example, outputs of an `untypedOp` node or custom\n * context paths. The caller is responsible for choosing the correct type\n * parameter; no runtime validation occurs.\n *\n * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`\n * whenever possible. Use `ref` only when you need to construct a `$ref` path\n * manually and want it accepted by a `Bindable<T>` slot.\n *\n * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).\n * @param path - The `$ref` path (e.g. `\"context.sender\"`, `\"myNode.result\"`).\n * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.\n *\n * @example\n * ```ts\n * import { raw } from '@lifi/composer-sdk';\n *\n * // Reference an untypedOp output in a typed operation:\n * builder.untypedOp('custom', 'some.op', {\n *   bind: { x: { $ref: 'input.token' } },\n *   config: {},\n * });\n * builder.core.add('sum', {\n *   bind: {\n *     a: raw.ref<'uint256'>('custom.result'),\n *     b: someTypedHandle,\n *   },\n * });\n * ```\n */\nexport const ref = <T extends OutputKind>(path: string): TypedRef<T> =>\n  ({ $ref: path }) as TypedRef<T>;\n\n/**\n * Creates a raw guard object for use in the `guards` array of an operation call.\n *\n * @param kind - The guard type (e.g. `\"slippage\"`).\n * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).\n * @returns An {@link AppliedGuard} object.\n */\nexport const rawGuard = (\n  kind: string,\n  config: Record<string, unknown> = {},\n): AppliedGuard => {\n  if ('kind' in config) {\n    throw new Error(\n      `rawGuard: 'kind' must not appear in config (got \"${String(\n        config.kind,\n      )}\"). Pass it as the first argument instead.`,\n    );\n  }\n  return { ...config, kind };\n};\n"],"mappings":"AAqCO,MAAM,MAAM,CAAuB,UACvC,EAAE,MAAM,KAAK;AAST,MAAM,WAAW,CACtB,MACA,SAAkC,CAAC,MAClB;AACjB,MAAI,UAAU,QAAQ;AACpB,UAAM,IAAI;AAAA,MACR,oDAAoD;AAAA,QAClD,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,KAAK;AAC3B;","names":[]}
+{"version":3,"sources":["../../src/authoring/raw.ts"],"sourcesContent":["import type { AppliedGuard } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * Creates a typed `$ref` pointer for use in bind slots.\n *\n * This is an **escape hatch** for referencing values that the typed builder\n * API doesn't cover — for example, outputs of an `untypedOp` node or custom\n * context paths. The caller is responsible for choosing the correct type\n * parameter; no runtime validation occurs.\n *\n * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`\n * whenever possible. Use `ref` only when you need to construct a `$ref` path\n * manually and want it accepted by a `Bindable<T>` slot.\n *\n * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).\n * @param path - The `$ref` path (e.g. `\"context.sender\"`, `\"myNode.result\"`).\n * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.\n *\n * @example\n * ```ts\n * import { raw } from '@lifi/composer-sdk';\n *\n * // Reference an untypedOp output in a typed operation:\n * builder.untypedOp('custom', 'some.op', {\n *   bind: { x: { $ref: 'input.token' } },\n *   config: {},\n * });\n * builder.core.add('sum', {\n *   bind: {\n *     a: raw.ref<'uint256'>('custom.result'),\n *     b: someTypedHandle,\n *   },\n * });\n * ```\n */\nexport const ref = <T extends OutputKind>(path: string): TypedRef<T> => ({\n  $ref: path,\n});\n\n/**\n * Creates a raw guard object for use in the `guards` array of an operation call.\n *\n * @param kind - The guard type (e.g. `\"slippage\"`).\n * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).\n * @returns An {@link AppliedGuard} object.\n */\nexport const rawGuard = (\n  kind: string,\n  config: Record<string, unknown> = {},\n): AppliedGuard => {\n  if ('kind' in config) {\n    throw new Error(\n      `rawGuard: 'kind' must not appear in config (got \"${String(\n        config.kind,\n      )}\"). Pass it as the first argument instead.`,\n    );\n  }\n  return { ...config, kind };\n};\n"],"mappings":"AAqCO,MAAM,MAAM,CAAuB,UAA+B;AAAA,EACvE,MAAM;AACR;AASO,MAAM,WAAW,CACtB,MACA,SAAkC,CAAC,MAClB;AACjB,MAAI,UAAU,QAAQ;AACpB,UAAM,IAAI;AAAA,MACR,oDAAoD;AAAA,QAClD,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,KAAK;AAC3B;","names":[]}

package/dist/client.cjs

@@ -23,7 +23,7 @@ __export(client_exports, {
 module.exports = __toCommonJS(client_exports);
 var import_errors = require("./errors.js");
 var import_responseSchemas = require("./responseSchemas.js");
-const SDK_VERSION = true ? "0.4.0" : "dev";
+const SDK_VERSION = true ? "0.4.1" : "dev";
 const bigintReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 const isNonNullObject = (v) => typeof v === "object" && v !== null;
 const parseBody = async (res, url) => {
@@ -64,6 +64,27 @@ const parseSimulateBody = async (res, url) => {
   }
   return result;
 };
+const postCompile = async ({ fetchFn, baseHeaders }, url, request) => {
+  let res;
+  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 import_errors.ComposeError("NETWORK_ERROR", message, { cause: err });
+  }
+  if (res.status === 206) {
+    return await parsePartialBody(res, url);
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    throw (0, import_errors.errorFromHttpResponse)(res.status, body, url);
+  }
+  return await parseCompileSuccessBody(res, url);
+};
 const createComposeClient = (options) => {
   if (!options.baseUrl || !/^https?:\/\//i.test(options.baseUrl)) {
     throw new import_errors.ComposeError(
@@ -85,6 +106,7 @@ const createComposeClient = (options) => {
     "x-lifi-composer-sdk": SDK_VERSION,
     "x-lifi-api-key": trimmedApiKey
   };
+  const transport = { fetchFn, baseHeaders };
   const getManifest = async () => {
     const url = `${base}/compose/manifest`;
     let res;
@@ -103,28 +125,8 @@ const createComposeClient = (options) => {
     }
     return await parseBody(res, url);
   };
-  const compile = async (request) => {
-    const url = `${base}/compose`;
-    let res;
-    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 import_errors.ComposeError("NETWORK_ERROR", message, { cause: err });
-    }
-    if (res.status === 206) {
-      return await parsePartialBody(res, url);
-    }
-    if (!res.ok) {
-      const body = await res.text();
-      throw (0, import_errors.errorFromHttpResponse)(res.status, body, url);
-    }
-    return await parseCompileSuccessBody(res, url);
-  };
+  const compile = async (request) => postCompile(transport, `${base}/compose`, request);
+  const route = async (request) => postCompile(transport, `${base}/compose/route`, request);
   const getZapPacks = async (options2) => {
     const params = new URLSearchParams();
     if (options2?.protocols !== void 0) {
@@ -169,7 +171,7 @@ const createComposeClient = (options) => {
     const body = await res.text();
     throw (0, import_errors.errorFromHttpResponse)(res.status, body, url);
   };
-  return { getManifest, compile, getZapPacks, simulate };
+  return { getManifest, compile, route, getZapPacks, simulate };
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/client.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type {\n  ComposeCompilePartialData,\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeCompileSuccessData,\n  ComposeManifest,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';\nimport { ComposeError, errorFromHttpResponse } from './errors.js';\nimport {\n  parseCompilePartialEnvelope,\n  parseSimulateResult,\n} from './responseSchemas.js';\n\n// __SDK_VERSION__ is a compile-time constant injected by tsup (via `define` in tsup.config.ts)\n// and by vitest (via `define` in vitest.config.ts). Both read the version from package.json\n// at build/test time and replace this identifier with the literal string value.\n// It is sent as the `x-lifi-composer-sdk` request header so the server can identify the caller.\n// Falls back to 'dev' when running via tsx without tsup substitution (e.g. the example harness).\ndeclare const __SDK_VERSION__: string;\n\nconst SDK_VERSION: string =\n  typeof __SDK_VERSION__ !== 'undefined' ? __SDK_VERSION__ : 'dev';\n\n/**\n * Configuration for creating a low-level Compose API client.\n */\nexport interface ComposeClientOptions {\n  /** Base URL of the Compose API. */\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 * Low-level HTTP client for the Compose API.\n *\n * Handles request serialization, SDK version headers, and error mapping.\n * Prefer using {@link ComposeSdk} for the full builder experience. Use this\n * directly when you need to decouple request building from submission — e.g.\n * build via `sdk.request()` then submit via `client.compile()` with custom\n * retry logic or request inspection.\n */\nexport interface ComposeClient {\n  /**\n   * Fetches the server's operation manifest describing all supported operations,\n   * guards, materialisers, and preconditions.\n   * @returns The manifest document.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly getManifest: () => Promise<ComposeManifest>;\n  /**\n   * Submits a compile request and returns the result.\n   *\n   * When the caller passes `simulationPolicy: 'allow-revert'` and the transaction\n   * reverts in simulation, the server responds with HTTP 206 and the SDK returns a\n   * partial result (`status: 'partial'`) instead of throwing. The partial result\n   * includes the transaction (without `gasLimit`) and revert diagnostics.\n   *\n   * @param request - The full compile request including flow and run inputs.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly compile: (\n    request: ComposeCompileRequest,\n  ) => Promise<ComposeCompileResult>;\n  /**\n   * Fetches the available routing edges grouped by protocol.\n   *\n   * The edge catalog is dynamic — it reflects the current state of the\n   * backend's routing snapshot (protocols, chains, token blacklists).\n   * Results are not cached by the SDK; callers should cache as appropriate.\n   *\n   * @param options - Optional filter to restrict results to specific protocols.\n   * @returns An array of {@link ZapPackOverview} objects, one per protocol.\n   * @throws {@link ComposeError} on network or server errors (503 when the\n   *   routing catalog is not yet initialized).\n   */\n  readonly getZapPacks: (\n    options?: GetZapPacksOptions,\n  ) => Promise<readonly ZapPackOverview[]>;\n  /**\n   * Simulates a raw, pre-encoded transaction against `POST /simulate` and\n   * reports how the watched balances change and how much inner-call gas it\n   * burns.\n   *\n   * The result is a discriminated union on `status`:\n   * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.\n   * - `'revert'` — the simulation ran but the transaction reverted on-chain. A\n   *   revert is a *successful simulation*, not a transport error, so it is\n   *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}\n   *   returns `status: 'partial'` on a simulated revert.\n   * - `'error'` — the request was well-formed but the simulation could not be\n   *   set up or run (HTTP 422); `message` is intentionally generic.\n   *\n   * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)\n   * are serialised to decimal strings automatically.\n   *\n   * @param request - The raw transaction plus funding `requirements` and the\n   *   `trackedBalances` to watch.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network failures, HTTP 400 (malformed\n   *   input), 401/403 (auth), 404, 429, and 5xx.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\nconst bigintReplacer = (_key: string, value: unknown): unknown =>\n  typeof value === 'bigint' ? value.toString() : value;\n\nconst isNonNullObject = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null;\n\nconst parseBody = async <T>(res: Response, url: string): Promise<T> => {\n  const body = await res.json().catch((_) => null);\n  if (!isNonNullObject(body) || !('data' in body)) {\n    throw new ComposeError('UNKNOWN_ERROR', 'Unexpected response format', {\n      url,\n    });\n  }\n  return body.data as T;\n};\n\nconst parseCompileSuccessBody = async (\n  res: Response,\n  url: string,\n): Promise<ComposeCompileResult> => {\n  const data = await parseBody<ComposeCompileSuccessData>(res, url);\n  return { ...data, status: 'success' as const };\n};\n\nconst parsePartialBody = async (\n  res: Response,\n  url: string,\n): Promise<ComposeCompileResult> => {\n  const body = await res.json().catch((_) => null);\n  const envelope = parseCompilePartialEnvelope(body);\n  if (envelope === null) {\n    throw new ComposeError(\n      'UNKNOWN_ERROR',\n      'Unexpected partial response format',\n      { url },\n    );\n  }\n  // `data` is validated as an object by the schema; compose-spec owns its full\n  // shape as a hand-authored type, so we narrow it here rather than re-declaring\n  // that type as a schema. `error` is fully validated — no cast needed.\n  const data = envelope.data as unknown as ComposeCompilePartialData;\n  return { ...data, status: 'partial' as const, error: envelope.error };\n};\n\n// `/simulate` is un-enveloped: the discriminated body (`{ status, ... }`) is at\n// the top level, NOT wrapped in `{ data }` like `/compose`. So this reads the\n// body directly and validates it against the simulate union rather than reusing\n// `parseBody`.\nconst parseSimulateBody = async (\n  res: Response,\n  url: string,\n): Promise<SimulateResult> => {\n  const body = await res.json().catch((_) => null);\n  const result = parseSimulateResult(body);\n  if (result === null) {\n    throw new ComposeError(\n      'UNKNOWN_ERROR',\n      'Unexpected simulate response format',\n      { url },\n    );\n  }\n  return result;\n};\n\n/**\n * Creates a low-level Compose API client.\n *\n * @param options - Client configuration including the API base URL.\n * @returns A {@link ComposeClient} instance.\n */\nexport const createComposeClient = (\n  options: ComposeClientOptions,\n): ComposeClient => {\n  if (!options.baseUrl || !/^https?:\\/\\//i.test(options.baseUrl)) {\n    throw new ComposeError(\n      'VALIDATION_ERROR',\n      `Invalid baseUrl: expected an HTTP(S) URL, got \"${options.baseUrl}\"`,\n    );\n  }\n  const trimmedApiKey = options.apiKey?.trim() || undefined;\n  if (!trimmedApiKey) {\n    throw new ComposeError(\n      'VALIDATION_ERROR',\n      'apiKey is required: pass a LI.FI API key to createComposeSdk().',\n    );\n  }\n  const fetchFn = options.fetch ?? globalThis.fetch;\n  const base = options.baseUrl.replace(/\\/$/, '');\n\n  const baseHeaders: Record<string, string> = {\n    Accept: 'application/json',\n    'x-lifi-composer-sdk': SDK_VERSION,\n    'x-lifi-api-key': trimmedApiKey,\n  };\n\n  const getManifest = async (): Promise<ComposeManifest> => {\n    const url = `${base}/compose/manifest`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'GET',\n        headers: { ...baseHeaders },\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    if (!res.ok) {\n      const body = await res.text();\n      throw errorFromHttpResponse(res.status, body, url);\n    }\n    return await parseBody<ComposeManifest>(res, url);\n  };\n\n  const compile = async (\n    request: ComposeCompileRequest,\n  ): Promise<ComposeCompileResult> => {\n    const url = `${base}/compose`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'POST',\n        headers: { ...baseHeaders, 'Content-Type': 'application/json' },\n        body: JSON.stringify(request, bigintReplacer),\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    if (res.status === 206) {\n      return await parsePartialBody(res, url);\n    }\n    if (!res.ok) {\n      const body = await res.text();\n      throw errorFromHttpResponse(res.status, body, url);\n    }\n    return await parseCompileSuccessBody(res, url);\n  };\n\n  const getZapPacks = async (\n    options?: GetZapPacksOptions,\n  ): Promise<readonly ZapPackOverview[]> => {\n    const params = new URLSearchParams();\n    if (options?.protocols !== undefined) {\n      // Backend expects a single comma-separated value, not repeated keys.\n      const raw = options.protocols;\n      const list = typeof raw === 'string' ? raw : raw.join(',');\n      params.set('protocols', list);\n    }\n    const qs = params.toString();\n    const url = `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'GET',\n        headers: { ...baseHeaders },\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    if (!res.ok) {\n      const body = await res.text();\n      throw errorFromHttpResponse(res.status, body, url);\n    }\n    return await parseBody<readonly ZapPackOverview[]>(res, url);\n  };\n\n  const simulate = async (\n    request: SimulateRequest,\n  ): Promise<SimulateResult> => {\n    const url = `${base}/simulate`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'POST',\n        headers: { ...baseHeaders, 'Content-Type': 'application/json' },\n        body: JSON.stringify(request, bigintReplacer),\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    // Only 200 (carries `ok`/`revert`) and 422 (carries the `error` member of\n    // the union) have a discriminated body. 422 is deliberately intercepted\n    // here (not thrown as VALIDATION_ERROR) so callers get one exhaustive\n    // `switch (result.status)`. Every other status is a transport error and is\n    // thrown — including HTTP 400 (malformed input, no `status` body) and any\n    // unexpected 2xx.\n    if (res.status === 200 || res.status === 422) {\n      return await parseSimulateBody(res, url);\n    }\n    const body = await res.text();\n    throw errorFromHttpResponse(res.status, body, url);\n  };\n\n  return { getManifest, compile, getZapPacks, simulate };\n};\n"],"mappings":"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","names":["options"]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type {\n  ComposeCompilePartialData,\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeCompileSuccessData,\n  ComposeManifest,\n  ComposeRouteRequest,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';\nimport { ComposeError, errorFromHttpResponse } from './errors.js';\nimport {\n  parseCompilePartialEnvelope,\n  parseSimulateResult,\n} from './responseSchemas.js';\n\n// __SDK_VERSION__ is a compile-time constant injected by tsup (via `define` in tsup.config.ts)\n// and by vitest (via `define` in vitest.config.ts). Both read the version from package.json\n// at build/test time and replace this identifier with the literal string value.\n// It is sent as the `x-lifi-composer-sdk` request header so the server can identify the caller.\n// Falls back to 'dev' when running via tsx without tsup substitution (e.g. the example harness).\ndeclare const __SDK_VERSION__: string;\n\nconst SDK_VERSION: string =\n  typeof __SDK_VERSION__ !== 'undefined' ? __SDK_VERSION__ : 'dev';\n\n/**\n * Configuration for creating a low-level Compose API client.\n */\nexport interface ComposeClientOptions {\n  /** Base URL of the Compose API. */\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 * Low-level HTTP client for the Compose API.\n *\n * Handles request serialization, SDK version headers, and error mapping.\n * Prefer using {@link ComposeSdk} for the full builder experience. Use this\n * directly when you need to decouple request building from submission — e.g.\n * build via `sdk.request()` then submit via `client.compile()` with custom\n * retry logic or request inspection.\n */\nexport interface ComposeClient {\n  /**\n   * Fetches the server's operation manifest describing all supported operations,\n   * guards, materialisers, and preconditions.\n   * @returns The manifest document.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly getManifest: () => Promise<ComposeManifest>;\n  /**\n   * Submits a compile request and returns the result.\n   *\n   * When the caller passes `simulationPolicy: 'allow-revert'` and the transaction\n   * reverts in simulation, the server responds with HTTP 206 and the SDK returns a\n   * partial result (`status: 'partial'`) instead of throwing. The partial result\n   * includes the transaction (without `gasLimit`) and revert diagnostics.\n   *\n   * @param request - The full compile request including flow and run inputs.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly compile: (\n    request: ComposeCompileRequest,\n  ) => Promise<ComposeCompileResult>;\n  /**\n   * Compiles a token pair into a submit-ready transaction via\n   * `POST /compose/route`.\n   *\n   * A convenience path that skips flow authoring: the server builds a one-node\n   * `lifi.zap` flow with a `directDeposit` input from the `fromToken` /\n   * `toToken` pair and runs it through the same pipeline as {@link compile}.\n   * The response is therefore the same discriminated result — HTTP 206 under\n   * `simulationPolicy: 'allow-revert'` yields `status: 'partial'` rather than\n   * throwing, exactly as it does for {@link compile}.\n   *\n   * As of today that flow is a single zap step: one edge of the backend's\n   * routing catalog (a position entry or exit, a wrap or unwrap, a mint or\n   * burn). Enumerate the pairs it covers with {@link getZapPacks}; a pair with\n   * no edge is rejected with `kind: 'no_route_error'`. The endpoint is meant to\n   * author richer flows later, so the single-step limit is the current state of\n   * the server, not the shape of this contract.\n   *\n   * Use {@link compile} for what the server does not author for you: several\n   * chained operations, splits, explicit preconditions, or per-op guards.\n   *\n   * `bigint` amounts in `amount` are serialised to decimal strings\n   * automatically.\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   *   including `NOT_FOUND` (HTTP 404) when no catalog edge covers the pair.\n   */\n  readonly route: (\n    request: ComposeRouteRequest,\n  ) => Promise<ComposeCompileResult>;\n  /**\n   * Fetches the available routing edges grouped by protocol.\n   *\n   * The edge catalog is dynamic — it reflects the current state of the\n   * backend's routing snapshot (protocols, chains, token blacklists).\n   * Results are not cached by the SDK; callers should cache as appropriate.\n   *\n   * @param options - Optional filter to restrict results to specific protocols.\n   * @returns An array of {@link ZapPackOverview} objects, one per protocol.\n   * @throws {@link ComposeError} on network or server errors (503 when the\n   *   routing catalog is not yet initialized).\n   */\n  readonly getZapPacks: (\n    options?: GetZapPacksOptions,\n  ) => Promise<readonly ZapPackOverview[]>;\n  /**\n   * Simulates a raw, pre-encoded transaction against `POST /simulate` and\n   * reports how the watched balances change and how much inner-call gas it\n   * burns.\n   *\n   * The result is a discriminated union on `status`:\n   * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.\n   * - `'revert'` — the simulation ran but the transaction reverted on-chain. A\n   *   revert is a *successful simulation*, not a transport error, so it is\n   *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}\n   *   returns `status: 'partial'` on a simulated revert.\n   * - `'error'` — the request was well-formed but the simulation could not be\n   *   set up or run (HTTP 422); `message` is intentionally generic.\n   *\n   * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)\n   * are serialised to decimal strings automatically.\n   *\n   * @param request - The raw transaction plus funding `requirements` and the\n   *   `trackedBalances` to watch.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network failures, HTTP 400 (malformed\n   *   input), 401/403 (auth), 404, 429, and 5xx.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\nconst bigintReplacer = (_key: string, value: unknown): unknown =>\n  typeof value === 'bigint' ? value.toString() : value;\n\nconst isNonNullObject = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null;\n\nconst parseBody = async <T>(res: Response, url: string): Promise<T> => {\n  const body = await res.json().catch((_) => null);\n  if (!isNonNullObject(body) || !('data' in body)) {\n    throw new ComposeError('UNKNOWN_ERROR', 'Unexpected response format', {\n      url,\n    });\n  }\n  return body.data as T;\n};\n\nconst parseCompileSuccessBody = async (\n  res: Response,\n  url: string,\n): Promise<ComposeCompileResult> => {\n  const data = await parseBody<ComposeCompileSuccessData>(res, url);\n  return { ...data, status: 'success' as const };\n};\n\nconst parsePartialBody = async (\n  res: Response,\n  url: string,\n): Promise<ComposeCompileResult> => {\n  const body = await res.json().catch((_) => null);\n  const envelope = parseCompilePartialEnvelope(body);\n  if (envelope === null) {\n    throw new ComposeError(\n      'UNKNOWN_ERROR',\n      'Unexpected partial response format',\n      { url },\n    );\n  }\n  // `data` is validated as an object by the schema; compose-spec owns its full\n  // shape as a hand-authored type, so we narrow it here rather than re-declaring\n  // that type as a schema. `error` is fully validated — no cast needed.\n  const data = envelope.data as unknown as ComposeCompilePartialData;\n  return { ...data, status: 'partial' as const, error: envelope.error };\n};\n\n// `/simulate` is un-enveloped: the discriminated body (`{ status, ... }`) is at\n// the top level, NOT wrapped in `{ data }` like `/compose`. So this reads the\n// body directly and validates it against the simulate union rather than reusing\n// `parseBody`.\nconst parseSimulateBody = async (\n  res: Response,\n  url: string,\n): Promise<SimulateResult> => {\n  const body = await res.json().catch((_) => null);\n  const result = parseSimulateResult(body);\n  if (result === null) {\n    throw new ComposeError(\n      'UNKNOWN_ERROR',\n      'Unexpected simulate response format',\n      { url },\n    );\n  }\n  return result;\n};\n// `POST /compose` and `POST /compose/route` differ only in path and request\n// shape: both return the enveloped success data on 200 and the partial\n// envelope on 206, so they share one transport.\ntype ComposeTransport = {\n  readonly fetchFn: typeof fetch;\n  readonly baseHeaders: Record<string, string>;\n};\n\nconst postCompile = async (\n  { fetchFn, baseHeaders }: ComposeTransport,\n  url: string,\n  request: ComposeCompileRequest | ComposeRouteRequest,\n): Promise<ComposeCompileResult> => {\n  let res: Response;\n  try {\n    res = await fetchFn(url, {\n      method: 'POST',\n      headers: { ...baseHeaders, 'Content-Type': 'application/json' },\n      body: JSON.stringify(request, bigintReplacer),\n    });\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err);\n    throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n  }\n  if (res.status === 206) {\n    return await parsePartialBody(res, url);\n  }\n  if (!res.ok) {\n    const body = await res.text();\n    throw errorFromHttpResponse(res.status, body, url);\n  }\n  return await parseCompileSuccessBody(res, url);\n};\n\n/**\n * Creates a low-level Compose API client.\n *\n * @param options - Client configuration including the API base URL.\n * @returns A {@link ComposeClient} instance.\n */\nexport const createComposeClient = (\n  options: ComposeClientOptions,\n): ComposeClient => {\n  if (!options.baseUrl || !/^https?:\\/\\//i.test(options.baseUrl)) {\n    throw new ComposeError(\n      'VALIDATION_ERROR',\n      `Invalid baseUrl: expected an HTTP(S) URL, got \"${options.baseUrl}\"`,\n    );\n  }\n  const trimmedApiKey = options.apiKey?.trim() || undefined;\n  if (!trimmedApiKey) {\n    throw new ComposeError(\n      'VALIDATION_ERROR',\n      'apiKey is required: pass a LI.FI API key to createComposeSdk().',\n    );\n  }\n  const fetchFn = options.fetch ?? globalThis.fetch;\n  const base = options.baseUrl.replace(/\\/$/, '');\n\n  const baseHeaders: Record<string, string> = {\n    Accept: 'application/json',\n    'x-lifi-composer-sdk': SDK_VERSION,\n    'x-lifi-api-key': trimmedApiKey,\n  };\n  const transport: ComposeTransport = { fetchFn, baseHeaders };\n\n  const getManifest = async (): Promise<ComposeManifest> => {\n    const url = `${base}/compose/manifest`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'GET',\n        headers: { ...baseHeaders },\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    if (!res.ok) {\n      const body = await res.text();\n      throw errorFromHttpResponse(res.status, body, url);\n    }\n    return await parseBody<ComposeManifest>(res, url);\n  };\n\n  const compile = async (\n    request: ComposeCompileRequest,\n  ): Promise<ComposeCompileResult> =>\n    postCompile(transport, `${base}/compose`, request);\n\n  const route = async (\n    request: ComposeRouteRequest,\n  ): Promise<ComposeCompileResult> =>\n    postCompile(transport, `${base}/compose/route`, request);\n\n  const getZapPacks = async (\n    options?: GetZapPacksOptions,\n  ): Promise<readonly ZapPackOverview[]> => {\n    const params = new URLSearchParams();\n    if (options?.protocols !== undefined) {\n      // Backend expects a single comma-separated value, not repeated keys.\n      const raw = options.protocols;\n      const list = typeof raw === 'string' ? raw : raw.join(',');\n      params.set('protocols', list);\n    }\n    const qs = params.toString();\n    const url = `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'GET',\n        headers: { ...baseHeaders },\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    if (!res.ok) {\n      const body = await res.text();\n      throw errorFromHttpResponse(res.status, body, url);\n    }\n    return await parseBody<readonly ZapPackOverview[]>(res, url);\n  };\n\n  const simulate = async (\n    request: SimulateRequest,\n  ): Promise<SimulateResult> => {\n    const url = `${base}/simulate`;\n    let res: Response;\n    try {\n      res = await fetchFn(url, {\n        method: 'POST',\n        headers: { ...baseHeaders, 'Content-Type': 'application/json' },\n        body: JSON.stringify(request, bigintReplacer),\n      });\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      throw new ComposeError('NETWORK_ERROR', message, { cause: err });\n    }\n    // Only 200 (carries `ok`/`revert`) and 422 (carries the `error` member of\n    // the union) have a discriminated body. 422 is deliberately intercepted\n    // here (not thrown as VALIDATION_ERROR) so callers get one exhaustive\n    // `switch (result.status)`. Every other status is a transport error and is\n    // thrown — including HTTP 400 (malformed input, no `status` body) and any\n    // unexpected 2xx.\n    if (res.status === 200 || res.status === 422) {\n      return await parseSimulateBody(res, url);\n    }\n    const body = await res.text();\n    throw errorFromHttpResponse(res.status, body, url);\n  };\n\n  return { getManifest, compile, route, getZapPacks, simulate };\n};\n"],"mappings":"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","names":["options"]}

package/dist/client.d.cts

@@ -1,4 +1,4 @@
-import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
+import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, ComposeRouteRequest, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
 import { GetZapPacksOptions, ZapPackOverview } from './discovery.cjs';
 
 /**
@@ -42,6 +42,36 @@ interface ComposeClient {
      * @throws {@link ComposeError} on network, validation, or server errors.
      */
     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.
      *

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
+import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, ComposeRouteRequest, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
 import { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
 
 /**
@@ -42,6 +42,36 @@ interface ComposeClient {
      * @throws {@link ComposeError} on network, validation, or server errors.
      */
     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.
      *

package/dist/client.js

@@ -3,7 +3,7 @@ import {
   parseCompilePartialEnvelope,
   parseSimulateResult
 } from "./responseSchemas.js";
-const SDK_VERSION = true ? "0.4.0" : "dev";
+const SDK_VERSION = true ? "0.4.1" : "dev";
 const bigintReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 const isNonNullObject = (v) => typeof v === "object" && v !== null;
 const parseBody = async (res, url) => {
@@ -44,6 +44,27 @@ const parseSimulateBody = async (res, url) => {
   }
   return result;
 };
+const postCompile = async ({ fetchFn, baseHeaders }, url, request) => {
+  let res;
+  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 createComposeClient = (options) => {
   if (!options.baseUrl || !/^https?:\/\//i.test(options.baseUrl)) {
     throw new ComposeError(
@@ -65,6 +86,7 @@ const createComposeClient = (options) => {
     "x-lifi-composer-sdk": SDK_VERSION,
     "x-lifi-api-key": trimmedApiKey
   };
+  const transport = { fetchFn, baseHeaders };
   const getManifest = async () => {
     const url = `${base}/compose/manifest`;
     let res;
@@ -83,28 +105,8 @@ const createComposeClient = (options) => {
     }
     return await parseBody(res, url);
   };
-  const compile = async (request) => {
-    const url = `${base}/compose`;
-    let res;
-    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 compile = async (request) => postCompile(transport, `${base}/compose`, request);
+  const route = async (request) => postCompile(transport, `${base}/compose/route`, request);
   const getZapPacks = async (options2) => {
     const params = new URLSearchParams();
     if (options2?.protocols !== void 0) {
@@ -149,7 +151,7 @@ const createComposeClient = (options) => {
     const body = await res.text();
     throw errorFromHttpResponse(res.status, body, url);
   };
-  return { getManifest, compile, getZapPacks, simulate };
+  return { getManifest, compile, route, getZapPacks, simulate };
 };
 export {
   createComposeClient