@lifi/composer-sdk 0.2.0-staging.4 → 0.2.0

package/README.md

@@ -119,6 +119,7 @@ if (result.status === 'success') {
 - `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.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).
 
 **Helpers**
 - `resources.erc20(address, chainId)` / `resources.native(chainId)` — resource constructors
@@ -127,6 +128,7 @@ if (result.status === 'success') {
 - `preconditions.*` — precondition factories (erc20Balance, nativeBalance, erc20Allowance)
 - `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)
 
 ## Simulation policy and partial results
 
@@ -181,6 +183,85 @@ 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.
+
+```ts
+import { createComposeSdk } from '@lifi/composer-sdk';
+
+const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+
+const result = await sdk.client.simulate({
+  chainId: 1,
+  from: '0x1111111111111111111111111111111111111111',
+  to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+  data: '0xa9059cbb...', // pre-encoded transfer calldata
+  value: 0n, // bigint accepted; serialised to "0"
+  requirements: [
+    {
+      type: 'Erc20Balance',
+      wallet: '0x1111111111111111111111111111111111111111',
+      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      balance: 1_000_000n, // bigint accepted
+    },
+  ],
+  trackedBalances: [
+    {
+      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      owner: '0x1111111111111111111111111111111111111111',
+    },
+    {
+      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      owner: '0x2222222222222222222222222222222222222222',
+    },
+  ],
+});
+
+switch (result.status) {
+  case 'ok':
+    // Successful simulation.
+    console.log(result.gasUsed, result.deltas);
+    break;
+  case 'revert':
+    // The simulation ran but the transaction reverted on-chain — NOT an error.
+    console.log(result.revertReason, result.decodeResult);
+    break;
+  case 'error':
+    // The request was well-formed but the simulation could not be set up/run.
+    console.log(result.message);
+    break;
+}
+```
+
+`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`.
+
+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:
+
+```ts
+import { buildSimulateRequest } from '@lifi/composer-sdk';
+
+const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });
+const req = buildSimulateRequest({
+  result: compiled,
+  chainId: 1,
+  signer: '0x1111111111111111111111111111111111111111',
+  trackedBalances: [
+    {
+      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      owner: '0x1111111111111111111111111111111111111111',
+    },
+  ],
+});
+const sim = await sdk.client.simulate(req);
+```
+
+Two caveats from the endpoint: `gasUsed` is the inner-call execution gas only (it excludes the 21000 base tx cost and calldata gas), and EOA-only behaviour (e.g. `msg.sender == tx.origin` checks) is not faithfully simulated because the call runs through injected VM bytecode rather than a real EOA. See [`docs/references/simulate-endpoint.md`](../../../docs/references/simulate-endpoint.md) for the full contract.
+
+Two runnable examples cover both paths: [`src/examples/simulateRawTransaction.ts`](src/examples/simulateRawTransaction.ts) builds a raw `SimulateRequest` directly, and [`src/examples/simulateCompiledSwap.ts`](src/examples/simulateCompiledSwap.ts) shows the end-to-end compile → `buildSimulateRequest` → `simulate` arc.
+
 ## Error handling
 
 All SDK errors are thrown as `ComposeError` with a `code` property:

package/dist/authoring/handles.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/authoring/handles.ts"],"sourcesContent":["import type { Resource } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * A handle referencing a flow input declared in the flow's input schema.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface InputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'input';\n  readonly inputName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input handle for a resource (token) input, carrying the resource\n * declaration alongside the reference.\n */\nexport interface ResourceInputHandle extends InputHandle<'resource'> {\n  readonly resource: Resource;\n}\n\n/**\n * A handle referencing an output port of a previously declared operation node.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface OutputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'output';\n  readonly nodeId: string;\n  readonly portName: string;\n  readonly __outputKind?: T;\n}\n\n/** Discriminated union of all handle types that can be bound to operation arguments. */\nexport type AnyHandle = InputHandle | OutputHandle;\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */\nexport const isInputHandle = (h: AnyHandle): h is InputHandle =>\n  h._tag === 'input';\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */\nexport const isOutputHandle = (h: AnyHandle): h is OutputHandle =>\n  h._tag === 'output';\n\n/**\n * Converts a handle to a JSON `$ref` pointer used in the flow document.\n * Input handles become `\"input.<name>\"`; output handles become `\"<nodeId>.<port>\"`.\n */\nexport const handleToRef = (h: AnyHandle): { $ref: string } => {\n  if (h._tag === 'input') {\n    if (!h.inputName) throw new Error('InputHandle has empty inputName');\n    return { $ref: `input.${h.inputName}` };\n  }\n  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');\n  if (!h.portName) throw new Error('OutputHandle has empty portName');\n  return { $ref: `${h.nodeId}.${h.portName}` };\n};\n\n/**\n * For a bind slot expecting type T, also accept `'resource'`-tagged\n * handles when T is `'uint256'` (resources are uint256 amounts).\n */\ntype ResourceAssignable<T extends OutputKind> = T extends 'uint256'\n  ? T | 'resource'\n  : T;\n\n/**\n * The set of values accepted by a typed bind slot.\n * - `OutputHandle<T>` / `InputHandle<T>` (same type)\n * - For `'uint256'` slots, also `'resource'`-tagged handles\n * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)\n *\n * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`\n * to create a typed ref when you need to reference a raw path.\n */\nexport type Bindable<T extends OutputKind> =\n  | OutputHandle<ResourceAssignable<T>>\n  | InputHandle<ResourceAssignable<T>>\n  | TypedRef<ResourceAssignable<T>>;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuCO,MAAM,gBAAgB,CAAC,MAC5B,EAAE,SAAS;AAGN,MAAM,iBAAiB,CAAC,MAC7B,EAAE,SAAS;AAMN,MAAM,cAAc,CAAC,MAAmC;AAC7D,MAAI,EAAE,SAAS,SAAS;AACtB,QAAI,CAAC,EAAE,UAAW,OAAM,IAAI,MAAM,iCAAiC;AACnE,WAAO,EAAE,MAAM,SAAS,EAAE,SAAS,GAAG;AAAA,EACxC;AACA,MAAI,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,+BAA+B;AAC9D,MAAI,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iCAAiC;AAClE,SAAO,EAAE,MAAM,GAAG,EAAE,MAAM,IAAI,EAAE,QAAQ,GAAG;AAC7C;","names":[]}
+{"version":3,"sources":["../../src/authoring/handles.ts"],"sourcesContent":["import type { Resource, StaticSolType } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * A handle referencing a flow input declared in the flow's input schema.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface InputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'input';\n  readonly inputName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input handle for a resource (token) input, carrying the resource\n * declaration alongside the reference.\n */\nexport interface ResourceInputHandle extends InputHandle<'resource'> {\n  readonly resource: Resource;\n}\n\n/**\n * A handle referencing an output port of a previously declared operation node.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface OutputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'output';\n  readonly nodeId: string;\n  readonly portName: string;\n  readonly __outputKind?: T;\n}\n\n/** Discriminated union of all handle types that can be bound to operation arguments. */\nexport type AnyHandle = InputHandle | OutputHandle;\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */\nexport const isInputHandle = (h: AnyHandle): h is InputHandle =>\n  h._tag === 'input';\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */\nexport const isOutputHandle = (h: AnyHandle): h is OutputHandle =>\n  h._tag === 'output';\n\n/**\n * Converts a handle to a JSON `$ref` pointer used in the flow document.\n * Input handles become `\"input.<name>\"`; output handles become `\"<nodeId>.<port>\"`.\n */\nexport const handleToRef = (h: AnyHandle): { $ref: string } => {\n  if (h._tag === 'input') {\n    if (!h.inputName) throw new Error('InputHandle has empty inputName');\n    return { $ref: `input.${h.inputName}` };\n  }\n  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');\n  if (!h.portName) throw new Error('OutputHandle has empty portName');\n  return { $ref: `${h.nodeId}.${h.portName}` };\n};\n\n/**\n * For a bind slot expecting type T, widen the set of accepted handle types:\n * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle\n *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256\n *   amount). At the IR1 boundary every value is a type-erased word, so any\n *   static-32-byte handle is a sound bind for a `bytes32` payload port.\n * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged\n *   handles (resources are uint256 amounts).\n * - every other type keeps exact-SolType matching.\n */\ntype SlotAssignable<T extends OutputKind> = T extends 'bytes32'\n  ? StaticSolType | 'resource'\n  : T extends 'uint256'\n    ? T | 'resource'\n    : T;\n\n/**\n * The set of values accepted by a typed bind slot.\n * - `OutputHandle<T>` / `InputHandle<T>` (same type)\n * - For `'uint256'` slots, also `'resource'`-tagged handles\n * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)\n * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)\n *\n * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`\n * to create a typed ref when you need to reference a raw path.\n */\nexport type Bindable<T extends OutputKind> =\n  | OutputHandle<SlotAssignable<T>>\n  | InputHandle<SlotAssignable<T>>\n  | TypedRef<SlotAssignable<T>>;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuCO,MAAM,gBAAgB,CAAC,MAC5B,EAAE,SAAS;AAGN,MAAM,iBAAiB,CAAC,MAC7B,EAAE,SAAS;AAMN,MAAM,cAAc,CAAC,MAAmC;AAC7D,MAAI,EAAE,SAAS,SAAS;AACtB,QAAI,CAAC,EAAE,UAAW,OAAM,IAAI,MAAM,iCAAiC;AACnE,WAAO,EAAE,MAAM,SAAS,EAAE,SAAS,GAAG;AAAA,EACxC;AACA,MAAI,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,+BAA+B;AAC9D,MAAI,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iCAAiC;AAClE,SAAO,EAAE,MAAM,GAAG,EAAE,MAAM,IAAI,EAAE,QAAQ,GAAG;AAC7C;","names":[]}

package/dist/authoring/handles.d.cts

@@ -1,4 +1,4 @@
-import { Resource } from '@lifi/compose-spec';
+import { StaticSolType, Resource } from '@lifi/compose-spec';
 import { OutputKind, TypedRef } from '../types.cjs';
 
 /**
@@ -43,19 +43,26 @@ declare const handleToRef: (h: AnyHandle) => {
     $ref: string;
 };
 /**
- * For a bind slot expecting type T, also accept `'resource'`-tagged
- * handles when T is `'uint256'` (resources are uint256 amounts).
+ * For a bind slot expecting type T, widen the set of accepted handle types:
+ * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle
+ *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256
+ *   amount). At the IR1 boundary every value is a type-erased word, so any
+ *   static-32-byte handle is a sound bind for a `bytes32` payload port.
+ * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged
+ *   handles (resources are uint256 amounts).
+ * - every other type keeps exact-SolType matching.
  */
-type ResourceAssignable<T extends OutputKind> = T extends 'uint256' ? T | 'resource' : T;
+type SlotAssignable<T extends OutputKind> = T extends 'bytes32' ? StaticSolType | 'resource' : T extends 'uint256' ? T | 'resource' : T;
 /**
  * The set of values accepted by a typed bind slot.
  * - `OutputHandle<T>` / `InputHandle<T>` (same type)
  * - For `'uint256'` slots, also `'resource'`-tagged handles
- * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)
+ * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)
+ * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)
  *
  * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
  * to create a typed ref when you need to reference a raw path.
  */
-type Bindable<T extends OutputKind> = OutputHandle<ResourceAssignable<T>> | InputHandle<ResourceAssignable<T>> | TypedRef<ResourceAssignable<T>>;
+type Bindable<T extends OutputKind> = OutputHandle<SlotAssignable<T>> | InputHandle<SlotAssignable<T>> | TypedRef<SlotAssignable<T>>;
 
 export { type AnyHandle, type Bindable, type InputHandle, type OutputHandle, type ResourceInputHandle, handleToRef, isInputHandle, isOutputHandle };

package/dist/authoring/handles.d.ts

@@ -1,4 +1,4 @@
-import { Resource } from '@lifi/compose-spec';
+import { StaticSolType, Resource } from '@lifi/compose-spec';
 import { OutputKind, TypedRef } from '../types.js';
 
 /**
@@ -43,19 +43,26 @@ declare const handleToRef: (h: AnyHandle) => {
     $ref: string;
 };
 /**
- * For a bind slot expecting type T, also accept `'resource'`-tagged
- * handles when T is `'uint256'` (resources are uint256 amounts).
+ * For a bind slot expecting type T, widen the set of accepted handle types:
+ * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle
+ *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256
+ *   amount). At the IR1 boundary every value is a type-erased word, so any
+ *   static-32-byte handle is a sound bind for a `bytes32` payload port.
+ * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged
+ *   handles (resources are uint256 amounts).
+ * - every other type keeps exact-SolType matching.
  */
-type ResourceAssignable<T extends OutputKind> = T extends 'uint256' ? T | 'resource' : T;
+type SlotAssignable<T extends OutputKind> = T extends 'bytes32' ? StaticSolType | 'resource' : T extends 'uint256' ? T | 'resource' : T;
 /**
  * The set of values accepted by a typed bind slot.
  * - `OutputHandle<T>` / `InputHandle<T>` (same type)
  * - For `'uint256'` slots, also `'resource'`-tagged handles
- * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)
+ * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)
+ * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)
  *
  * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
  * to create a typed ref when you need to reference a raw path.
  */
-type Bindable<T extends OutputKind> = OutputHandle<ResourceAssignable<T>> | InputHandle<ResourceAssignable<T>> | TypedRef<ResourceAssignable<T>>;
+type Bindable<T extends OutputKind> = OutputHandle<SlotAssignable<T>> | InputHandle<SlotAssignable<T>> | TypedRef<SlotAssignable<T>>;
 
 export { type AnyHandle, type Bindable, type InputHandle, type OutputHandle, type ResourceInputHandle, handleToRef, isInputHandle, isOutputHandle };

package/dist/authoring/handles.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/authoring/handles.ts"],"sourcesContent":["import type { Resource } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * A handle referencing a flow input declared in the flow's input schema.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface InputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'input';\n  readonly inputName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input handle for a resource (token) input, carrying the resource\n * declaration alongside the reference.\n */\nexport interface ResourceInputHandle extends InputHandle<'resource'> {\n  readonly resource: Resource;\n}\n\n/**\n * A handle referencing an output port of a previously declared operation node.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface OutputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'output';\n  readonly nodeId: string;\n  readonly portName: string;\n  readonly __outputKind?: T;\n}\n\n/** Discriminated union of all handle types that can be bound to operation arguments. */\nexport type AnyHandle = InputHandle | OutputHandle;\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */\nexport const isInputHandle = (h: AnyHandle): h is InputHandle =>\n  h._tag === 'input';\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */\nexport const isOutputHandle = (h: AnyHandle): h is OutputHandle =>\n  h._tag === 'output';\n\n/**\n * Converts a handle to a JSON `$ref` pointer used in the flow document.\n * Input handles become `\"input.<name>\"`; output handles become `\"<nodeId>.<port>\"`.\n */\nexport const handleToRef = (h: AnyHandle): { $ref: string } => {\n  if (h._tag === 'input') {\n    if (!h.inputName) throw new Error('InputHandle has empty inputName');\n    return { $ref: `input.${h.inputName}` };\n  }\n  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');\n  if (!h.portName) throw new Error('OutputHandle has empty portName');\n  return { $ref: `${h.nodeId}.${h.portName}` };\n};\n\n/**\n * For a bind slot expecting type T, also accept `'resource'`-tagged\n * handles when T is `'uint256'` (resources are uint256 amounts).\n */\ntype ResourceAssignable<T extends OutputKind> = T extends 'uint256'\n  ? T | 'resource'\n  : T;\n\n/**\n * The set of values accepted by a typed bind slot.\n * - `OutputHandle<T>` / `InputHandle<T>` (same type)\n * - For `'uint256'` slots, also `'resource'`-tagged handles\n * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)\n *\n * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`\n * to create a typed ref when you need to reference a raw path.\n */\nexport type Bindable<T extends OutputKind> =\n  | OutputHandle<ResourceAssignable<T>>\n  | InputHandle<ResourceAssignable<T>>\n  | TypedRef<ResourceAssignable<T>>;\n"],"mappings":"AAuCO,MAAM,gBAAgB,CAAC,MAC5B,EAAE,SAAS;AAGN,MAAM,iBAAiB,CAAC,MAC7B,EAAE,SAAS;AAMN,MAAM,cAAc,CAAC,MAAmC;AAC7D,MAAI,EAAE,SAAS,SAAS;AACtB,QAAI,CAAC,EAAE,UAAW,OAAM,IAAI,MAAM,iCAAiC;AACnE,WAAO,EAAE,MAAM,SAAS,EAAE,SAAS,GAAG;AAAA,EACxC;AACA,MAAI,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,+BAA+B;AAC9D,MAAI,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iCAAiC;AAClE,SAAO,EAAE,MAAM,GAAG,EAAE,MAAM,IAAI,EAAE,QAAQ,GAAG;AAC7C;","names":[]}
+{"version":3,"sources":["../../src/authoring/handles.ts"],"sourcesContent":["import type { Resource, StaticSolType } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * A handle referencing a flow input declared in the flow's input schema.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface InputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'input';\n  readonly inputName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input handle for a resource (token) input, carrying the resource\n * declaration alongside the reference.\n */\nexport interface ResourceInputHandle extends InputHandle<'resource'> {\n  readonly resource: Resource;\n}\n\n/**\n * A handle referencing an output port of a previously declared operation node.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface OutputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'output';\n  readonly nodeId: string;\n  readonly portName: string;\n  readonly __outputKind?: T;\n}\n\n/** Discriminated union of all handle types that can be bound to operation arguments. */\nexport type AnyHandle = InputHandle | OutputHandle;\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */\nexport const isInputHandle = (h: AnyHandle): h is InputHandle =>\n  h._tag === 'input';\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */\nexport const isOutputHandle = (h: AnyHandle): h is OutputHandle =>\n  h._tag === 'output';\n\n/**\n * Converts a handle to a JSON `$ref` pointer used in the flow document.\n * Input handles become `\"input.<name>\"`; output handles become `\"<nodeId>.<port>\"`.\n */\nexport const handleToRef = (h: AnyHandle): { $ref: string } => {\n  if (h._tag === 'input') {\n    if (!h.inputName) throw new Error('InputHandle has empty inputName');\n    return { $ref: `input.${h.inputName}` };\n  }\n  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');\n  if (!h.portName) throw new Error('OutputHandle has empty portName');\n  return { $ref: `${h.nodeId}.${h.portName}` };\n};\n\n/**\n * For a bind slot expecting type T, widen the set of accepted handle types:\n * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle\n *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256\n *   amount). At the IR1 boundary every value is a type-erased word, so any\n *   static-32-byte handle is a sound bind for a `bytes32` payload port.\n * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged\n *   handles (resources are uint256 amounts).\n * - every other type keeps exact-SolType matching.\n */\ntype SlotAssignable<T extends OutputKind> = T extends 'bytes32'\n  ? StaticSolType | 'resource'\n  : T extends 'uint256'\n    ? T | 'resource'\n    : T;\n\n/**\n * The set of values accepted by a typed bind slot.\n * - `OutputHandle<T>` / `InputHandle<T>` (same type)\n * - For `'uint256'` slots, also `'resource'`-tagged handles\n * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)\n * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)\n *\n * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`\n * to create a typed ref when you need to reference a raw path.\n */\nexport type Bindable<T extends OutputKind> =\n  | OutputHandle<SlotAssignable<T>>\n  | InputHandle<SlotAssignable<T>>\n  | TypedRef<SlotAssignable<T>>;\n"],"mappings":"AAuCO,MAAM,gBAAgB,CAAC,MAC5B,EAAE,SAAS;AAGN,MAAM,iBAAiB,CAAC,MAC7B,EAAE,SAAS;AAMN,MAAM,cAAc,CAAC,MAAmC;AAC7D,MAAI,EAAE,SAAS,SAAS;AACtB,QAAI,CAAC,EAAE,UAAW,OAAM,IAAI,MAAM,iCAAiC;AACnE,WAAO,EAAE,MAAM,SAAS,EAAE,SAAS,GAAG;AAAA,EACxC;AACA,MAAI,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,+BAA+B;AAC9D,MAAI,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iCAAiC;AAClE,SAAO,EAAE,MAAM,GAAG,EAAE,MAAM,IAAI,EAAE,QAAQ,GAAG;AAC7C;","names":[]}

package/dist/client.cjs

@@ -22,7 +22,8 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 var import_errors = require("./errors.js");
-const SDK_VERSION = true ? "0.2.0-staging.4" : "dev";
+var import_responseSchemas = require("./responseSchemas.js");
+const SDK_VERSION = true ? "0.2.0" : "dev";
 const bigintReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 const isNonNullObject = (v) => typeof v === "object" && v !== null;
 const parseBody = async (res, url) => {
@@ -40,16 +41,28 @@ const parseCompileSuccessBody = async (res, url) => {
 };
 const parsePartialBody = async (res, url) => {
   const body = await res.json().catch((_) => null);
-  if (!isNonNullObject(body) || !("data" in body) || !isNonNullObject(body.data) || !("error" in body) || !isNonNullObject(body.error)) {
+  const envelope = (0, import_responseSchemas.parseCompilePartialEnvelope)(body);
+  if (envelope === null) {
     throw new import_errors.ComposeError(
       "UNKNOWN_ERROR",
       "Unexpected partial response format",
       { url }
     );
   }
-  const data = body.data;
-  const error = body.error;
-  return { ...data, status: "partial", error };
+  const data = envelope.data;
+  return { ...data, status: "partial", error: envelope.error };
+};
+const parseSimulateBody = async (res, url) => {
+  const body = await res.json().catch((_) => null);
+  const result = (0, import_responseSchemas.parseSimulateResult)(body);
+  if (result === null) {
+    throw new import_errors.ComposeError(
+      "UNKNOWN_ERROR",
+      "Unexpected simulate response format",
+      { url }
+    );
+  }
+  return result;
 };
 const createComposeClient = (options) => {
   if (!options.baseUrl || !/^https?:\/\//i.test(options.baseUrl)) {
@@ -131,7 +144,26 @@ const createComposeClient = (options) => {
     }
     return await parseBody(res, url);
   };
-  return { getManifest, compile, getZapPacks };
+  const simulate = async (request) => {
+    const url = `${base}/simulate`;
+    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 === 200 || res.status === 422) {
+      return await parseSimulateBody(res, url);
+    }
+    const body = await res.text();
+    throw (0, import_errors.errorFromHttpResponse)(res.status, body, url);
+  };
+  return { getManifest, compile, 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} from '@lifi/compose-spec';\n\nimport type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';\nimport { ComposeError, errorFromHttpResponse } from './errors.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  /** Optional LI.FI API key. When set, sent as the `x-lifi-api-key` header on every request. */\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\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  if (\n    !isNonNullObject(body) ||\n    !('data' in body) ||\n    !isNonNullObject(body.data) ||\n    !('error' in body) ||\n    !isNonNullObject(body.error)\n  ) {\n    throw new ComposeError(\n      'UNKNOWN_ERROR',\n      'Unexpected partial response format',\n      { url },\n    );\n  }\n  const data = body.data as unknown as ComposeCompilePartialData;\n  const error = body.error as unknown as { kind: string; message: string };\n  return { ...data, status: 'partial' as const, error };\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 fetchFn = options.fetch ?? globalThis.fetch;\n  const base = options.baseUrl.replace(/\\/$/, '');\n\n  const trimmedApiKey = options.apiKey?.trim() || undefined;\n\n  const baseHeaders: Record<string, string> = {\n    Accept: 'application/json',\n    'x-lifi-composer-sdk': SDK_VERSION,\n    ...(trimmedApiKey ? { '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  return { getManifest, compile, getZapPacks };\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  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  /** Optional LI.FI API key. When set, sent as the `x-lifi-api-key` header on every request. */\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 fetchFn = options.fetch ?? globalThis.fetch;\n  const base = options.baseUrl.replace(/\\/$/, '');\n\n  const trimmedApiKey = options.apiKey?.trim() || undefined;\n\n  const baseHeaders: Record<string, string> = {\n    Accept: 'application/json',\n    'x-lifi-composer-sdk': SDK_VERSION,\n    ...(trimmedApiKey ? { '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"]}

package/dist/client.d.cts

@@ -1,4 +1,4 @@
-import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult } from '@lifi/compose-spec';
+import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
 import { GetZapPacksOptions, ZapPackOverview } from './discovery.cjs';
 
 /**
@@ -55,6 +55,30 @@ interface ComposeClient {
      *   routing catalog is not yet initialized).
      */
     readonly getZapPacks: (options?: GetZapPacksOptions) => Promise<readonly ZapPackOverview[]>;
+    /**
+     * Simulates a raw, pre-encoded transaction against `POST /simulate` and
+     * reports how the watched balances change and how much inner-call gas it
+     * burns.
+     *
+     * The result is a discriminated union on `status`:
+     * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.
+     * - `'revert'` — the simulation ran but the transaction reverted on-chain. A
+     *   revert is a *successful simulation*, not a transport error, so it is
+     *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}
+     *   returns `status: 'partial'` on a simulated revert.
+     * - `'error'` — the request was well-formed but the simulation could not be
+     *   set up or run (HTTP 422); `message` is intentionally generic.
+     *
+     * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)
+     * are serialised to decimal strings automatically.
+     *
+     * @param request - The raw transaction plus funding `requirements` and the
+     *   `trackedBalances` to watch.
+     * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+     * @throws {@link ComposeError} on network failures, HTTP 400 (malformed
+     *   input), 401/403 (auth), 404, 429, and 5xx.
+     */
+    readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 /**
  * Creates a low-level Compose API client.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult } from '@lifi/compose-spec';
+import { ComposeManifest, ComposeCompileRequest, ComposeCompileResult, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
 import { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
 
 /**
@@ -55,6 +55,30 @@ interface ComposeClient {
      *   routing catalog is not yet initialized).
      */
     readonly getZapPacks: (options?: GetZapPacksOptions) => Promise<readonly ZapPackOverview[]>;
+    /**
+     * Simulates a raw, pre-encoded transaction against `POST /simulate` and
+     * reports how the watched balances change and how much inner-call gas it
+     * burns.
+     *
+     * The result is a discriminated union on `status`:
+     * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.
+     * - `'revert'` — the simulation ran but the transaction reverted on-chain. A
+     *   revert is a *successful simulation*, not a transport error, so it is
+     *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}
+     *   returns `status: 'partial'` on a simulated revert.
+     * - `'error'` — the request was well-formed but the simulation could not be
+     *   set up or run (HTTP 422); `message` is intentionally generic.
+     *
+     * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)
+     * are serialised to decimal strings automatically.
+     *
+     * @param request - The raw transaction plus funding `requirements` and the
+     *   `trackedBalances` to watch.
+     * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+     * @throws {@link ComposeError} on network failures, HTTP 400 (malformed
+     *   input), 401/403 (auth), 404, 429, and 5xx.
+     */
+    readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 /**
  * Creates a low-level Compose API client.

package/dist/client.js

@@ -1,5 +1,9 @@
 import { ComposeError, errorFromHttpResponse } from "./errors.js";
-const SDK_VERSION = true ? "0.2.0-staging.4" : "dev";
+import {
+  parseCompilePartialEnvelope,
+  parseSimulateResult
+} from "./responseSchemas.js";
+const SDK_VERSION = true ? "0.2.0" : "dev";
 const bigintReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 const isNonNullObject = (v) => typeof v === "object" && v !== null;
 const parseBody = async (res, url) => {
@@ -17,16 +21,28 @@ const parseCompileSuccessBody = async (res, url) => {
 };
 const parsePartialBody = async (res, url) => {
   const body = await res.json().catch((_) => null);
-  if (!isNonNullObject(body) || !("data" in body) || !isNonNullObject(body.data) || !("error" in body) || !isNonNullObject(body.error)) {
+  const envelope = parseCompilePartialEnvelope(body);
+  if (envelope === null) {
     throw new ComposeError(
       "UNKNOWN_ERROR",
       "Unexpected partial response format",
       { url }
     );
   }
-  const data = body.data;
-  const error = body.error;
-  return { ...data, status: "partial", error };
+  const data = envelope.data;
+  return { ...data, status: "partial", error: envelope.error };
+};
+const parseSimulateBody = async (res, url) => {
+  const body = await res.json().catch((_) => null);
+  const result = parseSimulateResult(body);
+  if (result === null) {
+    throw new ComposeError(
+      "UNKNOWN_ERROR",
+      "Unexpected simulate response format",
+      { url }
+    );
+  }
+  return result;
 };
 const createComposeClient = (options) => {
   if (!options.baseUrl || !/^https?:\/\//i.test(options.baseUrl)) {
@@ -108,7 +124,26 @@ const createComposeClient = (options) => {
     }
     return await parseBody(res, url);
   };
-  return { getManifest, compile, getZapPacks };
+  const simulate = async (request) => {
+    const url = `${base}/simulate`;
+    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 === 200 || res.status === 422) {
+      return await parseSimulateBody(res, url);
+    }
+    const body = await res.text();
+    throw errorFromHttpResponse(res.status, body, url);
+  };
+  return { getManifest, compile, getZapPacks, simulate };
 };
 export {
   createComposeClient

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type {\n  ComposeCompilePartialData,\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeCompileSuccessData,\n  ComposeManifest,\n} from '@lifi/compose-spec';\n\nimport type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';\nimport { ComposeError, errorFromHttpResponse } from './errors.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  /** Optional LI.FI API key. When set, sent as the `x-lifi-api-key` header on every request. */\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\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  if (\n    !isNonNullObject(body) ||\n    !('data' in body) ||\n    !isNonNullObject(body.data) ||\n    !('error' in body) ||\n    !isNonNullObject(body.error)\n  ) {\n    throw new ComposeError(\n      'UNKNOWN_ERROR',\n      'Unexpected partial response format',\n      { url },\n    );\n  }\n  const data = body.data as unknown as ComposeCompilePartialData;\n  const error = body.error as unknown as { kind: string; message: string };\n  return { ...data, status: 'partial' as const, error };\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 fetchFn = options.fetch ?? globalThis.fetch;\n  const base = options.baseUrl.replace(/\\/$/, '');\n\n  const trimmedApiKey = options.apiKey?.trim() || undefined;\n\n  const baseHeaders: Record<string, string> = {\n    Accept: 'application/json',\n    'x-lifi-composer-sdk': SDK_VERSION,\n    ...(trimmedApiKey ? { '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  return { getManifest, compile, getZapPacks };\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  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  /** Optional LI.FI API key. When set, sent as the `x-lifi-api-key` header on every request. */\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 fetchFn = options.fetch ?? globalThis.fetch;\n  const base = options.baseUrl.replace(/\\/$/, '');\n\n  const trimmedApiKey = options.apiKey?.trim() || undefined;\n\n  const baseHeaders: Record<string, string> = {\n    Accept: 'application/json',\n    'x-lifi-composer-sdk': SDK_VERSION,\n    ...(trimmedApiKey ? { '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"]}

package/dist/errors.cjs

@@ -23,6 +23,7 @@ __export(errors_exports, {
   isComposeError: () => isComposeError
 });
 module.exports = __toCommonJS(errors_exports);
+var import_responseSchemas = require("./responseSchemas.js");
 class ComposeError extends Error {
   name = "ComposeError";
   /** Machine-readable error category. */
@@ -61,11 +62,13 @@ const STATUS_TO_CODE = /* @__PURE__ */ new Map([
   [429, "RATE_LIMITED"]
 ]);
 const tryParseErrorBody = (body) => {
+  let json;
   try {
-    return JSON.parse(body);
+    json = JSON.parse(body);
   } catch {
     return null;
   }
+  return (0, import_responseSchemas.parseServerErrorBody)(json);
 };
 const errorFromHttpResponse = (status, body, url) => {
   const parsed = tryParseErrorBody(body);