@lifi/composer-sdk 0.5.0 → 0.5.1

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@lifi/composer-sdk` — TypeScript SDK for building and compiling\n * Compose flows into executable EVM calldata.\n *\n * Start by creating an SDK instance with {@link createComposeSdk}, then use\n * {@link ComposeSdk.flow} to build flows and compile them.\n *\n * @packageDocumentation\n */\n\nexport type {\n  AbiTypeToOutputKind,\n  Address,\n  InputDecl,\n  InputSchema,\n  InputSpecOf,\n  IntegerString,\n  IntegerStringInput,\n  OutputKind,\n  TypedGuard,\n  TypedRef,\n  TypedLiteral,\n} from './types.js';\n\nexport type {\n  ChainSummary,\n  GetZapPacksOptions,\n  ZapPackEdge,\n  ZapPackOverview,\n} from './discovery.js';\nexport type {\n  ComposeError,\n  ComposeErrorCode,\n  ComposePreparationOps,\n} from './errors.js';\nexport type {\n  AppliedGuard,\n  ApprovalEntry,\n  Call,\n  ComposeCompilePartialData,\n  ComposeAction,\n  ComposeFill,\n  ComposeFee,\n  ComposeUserProgramSimulation,\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeCompileSuccessData,\n  ComposeErrorKind,\n  ComposeRouteRequest,\n  ComposeTransactionRequest,\n  FailedPreparedOp,\n  Flow,\n  InputSpec,\n  MaterialiserConfigOf,\n  MaterialiserInput,\n  Precondition,\n  PreconditionConfigOf,\n  PriceImpact,\n  ProducedResource,\n  Ref,\n  Resource,\n  RouteAmount,\n  RouteAmountAll,\n  RouteAmountExact,\n  SimulatedAmounts,\n  SimulationPolicy,\n  SimulationRevert,\n  SolType,\n  SweepTo,\n  SimulateRequest,\n  SimulateResult,\n  SimulateOkResult,\n  SimulateRevertResult,\n  SimulateRevertDecodeResult,\n  SimulateSetupErrorResult,\n  SimulateBalanceEntry,\n  TrackedBalance,\n  SlotFinderRequirement,\n  Erc20BalanceRequirement,\n  NativeBalanceRequirement,\n  Erc20AllowanceRequirement,\n  ContinuationIntent,\n  ContinuationOutcome,\n  Check,\n  CheckComparator,\n  Phase1ArtifactWire,\n  ContinuationPlanWire,\n} from '@lifi/compose-spec';\nexport {\n  SIMULATE_MAX_TRACKED_BALANCES,\n  SIMULATE_MAX_REQUIREMENTS,\n} from '@lifi/compose-spec';\nexport { isComposeError, isComposePreparationError } from './errors.js';\n\nexport type {\n  Bindable,\n  RefBindable,\n  AnyRefBindable,\n  InputHandle,\n  ResourceInputHandle,\n  OutputHandle,\n  AnyHandle,\n} from './authoring/handles.js';\nexport { isInputHandle, isOutputHandle } from './authoring/handles.js';\nexport { ref } from './authoring/raw.js';\n\nexport type { AnyBindable } from './authoring/FlowBuilderCore.js';\nexport type { TypedFlow, FlowOptions } from './authoring/FlowBuilderCore.js';\n\nexport type { ComposeRunInput } from './run/inputs.js';\nexport { materialiser } from './run/inputs.js';\n\nexport { buildSimulateRequest } from './run/simulate.js';\nexport type { BuildSimulateRequestInput } from './run/simulate.js';\n\nexport { createComposeSdk } from './sdk.js';\nexport type { ComposeSdk, ComposeSdkOptions, FlowBuilder } from './sdk.js';\n\nimport * as guardsMod from './generated/guards.generated.js';\nimport * as materialisersMod from './generated/materialisers.generated.js';\nimport * as preconditionsMod from './generated/preconditions.generated.js';\nimport * as rawMod from './raw.js';\nimport * as resourcesMod from './resources.js';\nimport * as routeAmountMod from './routeAmount.js';\n\n/**\n * Guard factories for protecting operation outputs (e.g. slippage tolerance).\n * Pass guards to an operation's `guards` array.\n *\n * @example\n * ```ts\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.token },\n *   config: { resourceOut: resources.native(1) },\n *   guards: [guards.slippage({ port: 'amountOut', bps: 300 })],\n * });\n * ```\n */\nexport const guards: typeof guardsMod = guardsMod;\n/**\n * Materialiser factories that tell the runtime how to resolve token input\n * amounts on-chain (e.g. read a wallet balance, accept a direct deposit).\n *\n * @example\n * ```ts\n * await builder.compile({\n *   inputs: { token: materialisers.balanceOf({}) },\n *   signer: '0x...',\n * });\n * ```\n */\nexport const materialisers: typeof materialisersMod = materialisersMod;\n/**\n * Precondition factories for asserting on-chain state before a flow executes\n * (e.g. minimum token balances, ERC-20 allowances).\n *\n * @example\n * ```ts\n * await builder.compile({\n *   inputs: { token: materialisers.balanceOf({}) },\n *   preconditions: [\n *     preconditions.erc20Balance({ wallet: '0x...', token: '0x...', balance: 1000n }),\n *   ],\n *   signer: '0x...',\n * });\n * ```\n */\nexport const preconditions: typeof preconditionsMod = preconditionsMod;\n/**\n * Resource declaration helpers for defining token inputs in a flow schema.\n * Use {@link resources.erc20} for ERC-20 tokens and {@link resources.native}\n * for the chain's native coin (ETH, MATIC, etc.).\n *\n * @example\n * ```ts\n * const builder = sdk.flow(1, {\n *   inputs: {\n *     usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1),\n *     eth: resources.native(1),\n *   },\n * });\n * ```\n */\nexport const resources: typeof resourcesMod = resourcesMod;\n/**\n * Amount constructors for {@link ComposeSdk.route}. Use\n * {@link routeAmount.exact} to spend a fixed amount of the `fromToken`, and\n * {@link routeAmount.all} to spend the signer's whole balance.\n *\n * @example\n * ```ts\n * // USDC into the Aave v3 aEthUSDC position — one routing-catalog edge.\n * const result = await sdk.route({\n *   chainId: 1,\n *   fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n *   toToken: '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c',\n *   amount: routeAmount.exact(1_000_000n),\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport const routeAmount: typeof routeAmountMod = routeAmountMod;\nexport * from './generated/config.generated.js';\n\n/**\n * Low-level escape hatch for constructing flow nodes, guards, and materialiser\n * inputs without the typed builder API. Prefer the generated operation methods\n * on {@link FlowBuilder} and the typed `guards`/`materialisers` namespaces\n * for most use cases.\n */\nexport const raw: typeof rawMod = rawMod;\n"],"mappings":"AAwFA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,gBAAgB,iCAAiC;AAW1D,SAAS,eAAe,sBAAsB;AAC9C,SAAS,WAAW;AAMpB,SAAS,oBAAoB;AAE7B,SAAS,4BAA4B;AAGrC,SAAS,wBAAwB;AAGjC,YAAY,eAAe;AAC3B,YAAY,sBAAsB;AAClC,YAAY,sBAAsB;AAClC,YAAY,YAAY;AACxB,YAAY,kBAAkB;AAC9B,YAAY,oBAAoB;AAezB,MAAM,SAA2B;AAajC,MAAM,gBAAyC;AAgB/C,MAAM,gBAAyC;AAgB/C,MAAM,YAAiC;AAkBvC,MAAM,cAAqC;AAClD,cAAc;AAQP,MAAM,MAAqB;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@lifi/composer-sdk` — TypeScript SDK for building and compiling\n * Compose flows into executable EVM calldata.\n *\n * Start by creating an SDK instance with {@link createComposeSdk}, then use\n * {@link ComposeSdk.flow} to build flows and compile them.\n *\n * @packageDocumentation\n */\n\nexport type {\n  AbiTypeToOutputKind,\n  Address,\n  InputDecl,\n  InputSchema,\n  InputSpecOf,\n  IntegerString,\n  IntegerStringInput,\n  OutputKind,\n  TypedGuard,\n  TypedRef,\n  TypedLiteral,\n} from './types.js';\n\nexport type {\n  ChainSummary,\n  GetZapPacksOptions,\n  ZapPackEdge,\n  ZapPackOverview,\n} from './discovery.js';\nexport type {\n  ComposeError,\n  ComposeErrorCode,\n  ComposeSdkOutdated,\n  ComposeServerOutdated,\n  ComposePreparationOps,\n} from './errors.js';\nexport type {\n  AppliedGuard,\n  ApprovalEntry,\n  Call,\n  ComposeCompilePartialData,\n  ComposeAction,\n  ComposeFill,\n  ComposeFee,\n  ComposeUserProgramSimulation,\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeCompileSuccessData,\n  ComposeErrorKind,\n  ComposeRouteRequest,\n  ComposeTransactionRequest,\n  FailedPreparedOp,\n  Flow,\n  InputSpec,\n  MaterialiserConfigOf,\n  MaterialiserInput,\n  Precondition,\n  PreconditionConfigOf,\n  PriceImpact,\n  ProducedResource,\n  Ref,\n  Resource,\n  RouteAmount,\n  RouteAmountAll,\n  RouteAmountExact,\n  SimulatedAmounts,\n  SimulationPolicy,\n  SimulationRevert,\n  SolType,\n  SweepTo,\n  SimulateRequest,\n  SimulateResult,\n  SimulateOkResult,\n  SimulateRevertResult,\n  SimulateRevertDecodeResult,\n  SimulateSetupErrorResult,\n  SimulateBalanceEntry,\n  TrackedBalance,\n  SlotFinderRequirement,\n  Erc20BalanceRequirement,\n  NativeBalanceRequirement,\n  Erc20AllowanceRequirement,\n  ContinuationIntent,\n  ContinuationOutcome,\n  Check,\n  CheckComparator,\n  Phase1ArtifactWire,\n  ContinuationPlanWire,\n} from '@lifi/compose-spec';\nexport {\n  SIMULATE_MAX_TRACKED_BALANCES,\n  SIMULATE_MAX_REQUIREMENTS,\n} from '@lifi/compose-spec';\nexport {\n  isComposeError,\n  isComposePreparationError,\n  isComposeSdkOutdatedError,\n  isComposeServerOutdatedError,\n} from './errors.js';\n\nexport type {\n  Bindable,\n  RefBindable,\n  AnyRefBindable,\n  InputHandle,\n  ResourceInputHandle,\n  OutputHandle,\n  AnyHandle,\n} from './authoring/handles.js';\nexport { isInputHandle, isOutputHandle } from './authoring/handles.js';\nexport { ref } from './authoring/raw.js';\n\nexport type { AnyBindable } from './authoring/FlowBuilderCore.js';\nexport type { TypedFlow, FlowOptions } from './authoring/FlowBuilderCore.js';\n\nexport type { ComposeRunInput } from './run/inputs.js';\nexport { materialiser } from './run/inputs.js';\n\nexport { buildSimulateRequest } from './run/simulate.js';\nexport type { BuildSimulateRequestInput } from './run/simulate.js';\n\nexport { createComposeSdk } from './sdk.js';\nexport type { ComposeSdk, ComposeSdkOptions, FlowBuilder } from './sdk.js';\n\nimport * as guardsMod from './generated/guards.generated.js';\nimport * as materialisersMod from './generated/materialisers.generated.js';\nimport * as preconditionsMod from './generated/preconditions.generated.js';\nimport * as rawMod from './raw.js';\nimport * as resourcesMod from './resources.js';\nimport * as routeAmountMod from './routeAmount.js';\n\n/**\n * Guard factories for protecting operation outputs (e.g. slippage tolerance).\n * Pass guards to an operation's `guards` array.\n *\n * @example\n * ```ts\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.token },\n *   config: { resourceOut: resources.native(1) },\n *   guards: [guards.slippage({ port: 'amountOut', bps: 300 })],\n * });\n * ```\n */\nexport const guards: typeof guardsMod = guardsMod;\n/**\n * Materialiser factories that tell the runtime how to resolve token input\n * amounts on-chain (e.g. read a wallet balance, accept a direct deposit).\n *\n * @example\n * ```ts\n * await builder.compile({\n *   inputs: { token: materialisers.balanceOf({}) },\n *   signer: '0x...',\n * });\n * ```\n */\nexport const materialisers: typeof materialisersMod = materialisersMod;\n/**\n * Precondition factories for asserting on-chain state before a flow executes\n * (e.g. minimum token balances, ERC-20 allowances).\n *\n * @example\n * ```ts\n * await builder.compile({\n *   inputs: { token: materialisers.balanceOf({}) },\n *   preconditions: [\n *     preconditions.erc20Balance({ wallet: '0x...', token: '0x...', balance: 1000n }),\n *   ],\n *   signer: '0x...',\n * });\n * ```\n */\nexport const preconditions: typeof preconditionsMod = preconditionsMod;\n/**\n * Resource declaration helpers for defining token inputs in a flow schema.\n * Use {@link resources.erc20} for ERC-20 tokens and {@link resources.native}\n * for the chain's native coin (ETH, MATIC, etc.).\n *\n * @example\n * ```ts\n * const builder = sdk.flow(1, {\n *   inputs: {\n *     usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1),\n *     eth: resources.native(1),\n *   },\n * });\n * ```\n */\nexport const resources: typeof resourcesMod = resourcesMod;\n/**\n * Amount constructors for {@link ComposeSdk.route}. Use\n * {@link routeAmount.exact} to spend a fixed amount of the `fromToken`, and\n * {@link routeAmount.all} to spend the signer's whole balance.\n *\n * @example\n * ```ts\n * // USDC into the Aave v3 aEthUSDC position — one routing-catalog edge.\n * const result = await sdk.route({\n *   chainId: 1,\n *   fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n *   toToken: '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c',\n *   amount: routeAmount.exact(1_000_000n),\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport const routeAmount: typeof routeAmountMod = routeAmountMod;\nexport * from './generated/config.generated.js';\n\n/**\n * Low-level escape hatch for constructing flow nodes, guards, and materialiser\n * inputs without the typed builder API. Prefer the generated operation methods\n * on {@link FlowBuilder} and the typed `guards`/`materialisers` namespaces\n * for most use cases.\n */\nexport const raw: typeof rawMod = rawMod;\n"],"mappings":"AA0FA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAWP,SAAS,eAAe,sBAAsB;AAC9C,SAAS,WAAW;AAMpB,SAAS,oBAAoB;AAE7B,SAAS,4BAA4B;AAGrC,SAAS,wBAAwB;AAGjC,YAAY,eAAe;AAC3B,YAAY,sBAAsB;AAClC,YAAY,sBAAsB;AAClC,YAAY,YAAY;AACxB,YAAY,kBAAkB;AAC9B,YAAY,oBAAoB;AAezB,MAAM,SAA2B;AAajC,MAAM,gBAAyC;AAgB/C,MAAM,gBAAyC;AAgB/C,MAAM,YAAiC;AAkBvC,MAAM,cAAqC;AAClD,cAAc;AAQP,MAAM,MAAqB;","names":[]}

package/dist/responseSchemas.cjs

@@ -101,6 +101,9 @@ const serverErrorBodySchema = import_zod.default.object({
     kind: import_zod.default.string().optional(),
     message: import_zod.default.string().optional(),
     path: import_zod.default.string().optional(),
+    sdkVersion: import_zod.default.string().optional(),
+    serverVersion: import_zod.default.string().optional(),
+    minimumSdkVersion: import_zod.default.string().optional(),
     details: import_zod.default.custom().optional(),
     failedOps: import_zod.default.array(failedPreparedOpSchema).readonly().optional(),
     succeededOps: import_zod.default.array(import_zod.default.string()).readonly().optional()

package/dist/responseSchemas.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object but kept untyped — compose-spec owns its full shape\n * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows\n * it. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: Record<string, unknown>;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":["z"]}
+{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object but kept untyped — compose-spec owns its full shape\n * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows\n * it. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: Record<string, unknown>;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly sdkVersion?: string;\n    readonly serverVersion?: string;\n    readonly minimumSdkVersion?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      sdkVersion: z.string().optional(),\n      serverVersion: z.string().optional(),\n      minimumSdkVersion: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":["z"]}

package/dist/responseSchemas.d.cts

@@ -39,6 +39,9 @@ interface ServerErrorBody {
         readonly kind?: string;
         readonly message?: string;
         readonly path?: string;
+        readonly sdkVersion?: string;
+        readonly serverVersion?: string;
+        readonly minimumSdkVersion?: string;
         readonly details?: SimulationRevert;
         readonly failedOps?: readonly ServerFailedPreparedOp[];
         readonly succeededOps?: readonly string[];

package/dist/responseSchemas.d.ts

@@ -39,6 +39,9 @@ interface ServerErrorBody {
         readonly kind?: string;
         readonly message?: string;
         readonly path?: string;
+        readonly sdkVersion?: string;
+        readonly serverVersion?: string;
+        readonly minimumSdkVersion?: string;
         readonly details?: SimulationRevert;
         readonly failedOps?: readonly ServerFailedPreparedOp[];
         readonly succeededOps?: readonly string[];

package/dist/responseSchemas.js

@@ -66,6 +66,9 @@ const serverErrorBodySchema = z.object({
     kind: z.string().optional(),
     message: z.string().optional(),
     path: z.string().optional(),
+    sdkVersion: z.string().optional(),
+    serverVersion: z.string().optional(),
+    minimumSdkVersion: z.string().optional(),
     details: z.custom().optional(),
     failedOps: z.array(failedPreparedOpSchema).readonly().optional(),
     succeededOps: z.array(z.string()).readonly().optional()

package/dist/responseSchemas.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object but kept untyped — compose-spec owns its full shape\n * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows\n * it. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: Record<string, unknown>;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object but kept untyped — compose-spec owns its full shape\n * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows\n * it. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: Record<string, unknown>;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly sdkVersion?: string;\n    readonly serverVersion?: string;\n    readonly minimumSdkVersion?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      sdkVersion: z.string().optional(),\n      serverVersion: z.string().optional(),\n      minimumSdkVersion: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -46,7 +46,7 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.5.0"
+    "@lifi/compose-spec": "0.5.1"
   },
   "dependencies": {
     "abitype": "^1.2.3",

package/src/client.ts

@@ -8,6 +8,12 @@ import type {
   SimulateRequest,
   SimulateResult,
 } from '@lifi/compose-spec';
+import {
+  checkCompatibility,
+  COMPOSE_VERSION_HEADER,
+  COMPOSER_SDK_VERSION_HEADER,
+  parseVersion,
+} from '@lifi/compose-spec';
 
 import type {
   ChainSummary,
@@ -23,12 +29,14 @@ import {
 // __SDK_VERSION__ is a compile-time constant injected by tsup (via `define` in tsup.config.ts)
 // and by vitest (via `define` in vitest.config.ts). Both read the version from package.json
 // at build/test time and replace this identifier with the literal string value.
-// It is sent as the `x-lifi-composer-sdk` request header so the server can identify the caller.
+// It is sent as the `COMPOSER_SDK_VERSION_HEADER` request header so the server can identify the caller.
 // Falls back to 'dev' when running via tsx without tsup substitution (e.g. the example harness).
 declare const __SDK_VERSION__: string;
 
 const SDK_VERSION: string =
   typeof __SDK_VERSION__ !== 'undefined' ? __SDK_VERSION__ : 'dev';
+// `undefined` for the `dev` sentinel, which disables the response version check.
+const SDK_VERSION_TRIPLE = parseVersion(SDK_VERSION);
 
 /**
  * Configuration for creating a low-level Compose API client.
@@ -176,7 +184,14 @@ export interface ComposeClient {
   readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 
-const bigintReplacer = (_key: string, value: unknown): unknown =>
+/**
+ * `JSON.stringify` replacer that renders `bigint` amounts as decimal strings.
+ *
+ * The compose wire carries token amounts as decimal strings, and `bigint` has
+ * no JSON representation, so every payload this client sends goes through it.
+ * Exported so the example harness prints a request exactly as it is sent.
+ */
+export const bigintReplacer = (_key: string, value: unknown): unknown =>
   typeof value === 'bigint' ? value.toString() : value;
 
 const isNonNullObject = (v: unknown): v is Record<string, unknown> =>
@@ -310,22 +325,92 @@ type ComposeTransport = {
   readonly baseHeaders: Record<string, string>;
 };
 
-const postCompile = async (
+// A patch bump is additive and a minor bump is breaking, so a 200 from a
+// backend behind this SDK cannot be trusted: the newer flow this SDK authored
+// may have compiled under the server's older semantics without raising an
+// error. This covers the deploy window where the SDK is published to npm ahead
+// of the backend rollout. Only the compile-family POSTs are checked; discovery
+// GETs stay reachable from a mismatched SDK, as on the server. An absent header
+// (a pre-gate backend, a header-stripping proxy) is accepted, mirroring the
+// server's pass-through of a compile that carries no version header.
+const assertServerVersion = (res: Response, url: string): void => {
+  const serverVersion = res.headers.get(COMPOSE_VERSION_HEADER);
+  if (serverVersion === null || SDK_VERSION_TRIPLE === undefined) return;
+  const serverTriple = parseVersion(serverVersion);
+  if (serverTriple === undefined) return;
+
+  const compatibility = checkCompatibility(SDK_VERSION_TRIPLE, serverTriple);
+  if (compatibility === 'compatible') return;
+
+  const versions = { sdkVersion: SDK_VERSION, serverVersion };
+  if (compatibility === 'sdk_outdated') {
+    throw new ComposeError(
+      'VALIDATION_ERROR',
+      `composer-sdk ${SDK_VERSION} is older than the compose contract served at ${url} (${serverVersion}); upgrade @lifi/composer-sdk and @lifi/compose-spec`,
+      {
+        status: res.status,
+        url,
+        kind: 'sdk_outdated',
+        sdkOutdated: {
+          ...versions,
+          minimumSdkVersion: `${serverTriple.major}.${serverTriple.minor}.0`,
+        },
+      },
+    );
+  }
+  throw new ComposeError(
+    'VALIDATION_ERROR',
+    `composer-sdk ${SDK_VERSION} targets a newer compose contract than the server at ${url} serves (${serverVersion}); pin @lifi/composer-sdk and @lifi/compose-spec to ${serverVersion} or wait for the server rollout`,
+    {
+      status: res.status,
+      url,
+      kind: 'server_outdated',
+      serverOutdated: versions,
+    },
+  );
+};
+
+type SendInit =
+  | { readonly method: 'GET' }
+  | { readonly method: 'POST'; readonly body: unknown };
+
+// GETs on this API carry no body; POSTs carry a JSON one with `bigint` amounts
+// rendered as decimal strings.
+const requestInit = (
+  baseHeaders: Record<string, string>,
+  init: SendInit,
+): RequestInit =>
+  init.method === 'GET'
+    ? { method: 'GET', headers: { ...baseHeaders } }
+    : {
+        method: 'POST',
+        headers: { ...baseHeaders, 'Content-Type': 'application/json' },
+        body: JSON.stringify(init.body, bigintReplacer),
+      };
+
+// One fetch path for every route: maps transport failures to `NETWORK_ERROR`.
+// The response version check is not here — only the compile-family POSTs gate
+// on it (see `postCompile`); discovery GETs and `/simulate` are ungated.
+const send = async (
   { fetchFn, baseHeaders }: ComposeTransport,
   url: string,
-  request: ComposeCompileRequest | ComposeRouteRequest,
-): Promise<ComposeCompileResult> => {
-  let res: Response;
+  init: SendInit,
+): Promise<Response> => {
   try {
-    res = await fetchFn(url, {
-      method: 'POST',
-      headers: { ...baseHeaders, 'Content-Type': 'application/json' },
-      body: JSON.stringify(request, bigintReplacer),
-    });
+    return await fetchFn(url, requestInit(baseHeaders, init));
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new ComposeError('NETWORK_ERROR', message, { cause: err });
   }
+};
+
+const postCompile = async (
+  transport: ComposeTransport,
+  url: string,
+  request: ComposeCompileRequest | ComposeRouteRequest,
+): Promise<ComposeCompileResult> => {
+  const res = await send(transport, url, { method: 'POST', body: request });
+  assertServerVersion(res, url);
   if (res.status === 206) {
     return await parsePartialBody(res, url);
   }
@@ -339,19 +424,10 @@ const postCompile = async (
 // Every enveloped GET on this API behaves identically: no body, no query
 // semantics of its own, `{ data }` on success, an error envelope otherwise.
 const getJson = async <T>(
-  { fetchFn, baseHeaders }: ComposeTransport,
+  transport: ComposeTransport,
   url: string,
 ): Promise<T> => {
-  let res: Response;
-  try {
-    res = await fetchFn(url, {
-      method: 'GET',
-      headers: { ...baseHeaders },
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new ComposeError('NETWORK_ERROR', message, { cause: err });
-  }
+  const res = await send(transport, url, { method: 'GET' });
   if (!res.ok) {
     const body = await res.text();
     throw errorFromHttpResponse(res.status, body, url);
@@ -386,7 +462,7 @@ export const createComposeClient = (
 
   const baseHeaders: Record<string, string> = {
     Accept: 'application/json',
-    'x-lifi-composer-sdk': SDK_VERSION,
+    [COMPOSER_SDK_VERSION_HEADER]: SDK_VERSION,
     'x-lifi-api-key': trimmedApiKey,
   };
   const transport: ComposeTransport = { fetchFn, baseHeaders };
@@ -428,17 +504,7 @@ export const createComposeClient = (
     request: SimulateRequest,
   ): Promise<SimulateResult> => {
     const url = `${base}/simulate`;
-    let res: Response;
-    try {
-      res = await fetchFn(url, {
-        method: 'POST',
-        headers: { ...baseHeaders, 'Content-Type': 'application/json' },
-        body: JSON.stringify(request, bigintReplacer),
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
-    }
+    const res = await send(transport, url, { method: 'POST', body: request });
     // Only 200 (carries `ok`/`revert`) and 422 (carries the `error` member of
     // the union) have a discriminated body. 422 is deliberately intercepted
     // here (not thrown as VALIDATION_ERROR) so callers get one exhaustive

package/src/errors.ts

@@ -1,9 +1,11 @@
 import type {
   ComposeErrorKind,
+  ComposeRouteErrorKind,
   FailedPreparedOp,
   GenericComposeErrorKind,
   SimulationRevert,
 } from '@lifi/compose-spec';
+import z from 'zod';
 
 import {
   parseServerErrorBody,
@@ -32,6 +34,24 @@ export type ComposeErrorCode =
   | 'NOT_FOUND'
   | 'UNKNOWN_ERROR';
 
+/** Version details returned when the backend rejects an outdated SDK. */
+export interface ComposeSdkOutdated {
+  readonly sdkVersion: string;
+  readonly serverVersion: string;
+  readonly minimumSdkVersion: string;
+}
+
+/**
+ * Version details attached when the SDK is ahead of the backend it reached.
+ * Raised by the backend's version gate, or by the SDK itself when the
+ * `x-lifi-composer-version` response header names an older contract than the
+ * one this SDK was built against.
+ */
+export interface ComposeServerOutdated {
+  readonly sdkVersion: string;
+  readonly serverVersion: string;
+}
+
 /**
  * Error class for all failures originating from the Compose SDK or API.
  *
@@ -58,7 +78,7 @@ export class ComposeError extends Error {
   /** The request URL that produced the error. */
   readonly url?: string;
   /** Server-provided error kind for finer-grained classification. */
-  readonly kind?: ComposeErrorKind;
+  readonly kind?: ComposeErrorKind | ComposeRouteErrorKind;
   /** JSON-pointer path to the field that caused a validation error. */
   readonly path?: string;
   /**
@@ -78,6 +98,10 @@ export class ComposeError extends Error {
    * `preparation_error` errors alongside {@link ComposeError.failedOps}.
    */
   readonly succeededOps?: readonly string[];
+  /** Version details attached only to `sdk_outdated` errors. */
+  readonly sdkOutdated?: ComposeSdkOutdated;
+  /** Version details attached only to `server_outdated` errors. */
+  readonly serverOutdated?: ComposeServerOutdated;
 
   constructor(
     code: ComposeErrorCode,
@@ -86,11 +110,13 @@ export class ComposeError extends Error {
       status?: number;
       url?: string;
       cause?: unknown;
-      kind?: ComposeErrorKind;
+      kind?: ComposeErrorKind | ComposeRouteErrorKind;
       path?: string;
       details?: SimulationRevert;
       failedOps?: readonly FailedPreparedOp[];
       succeededOps?: readonly string[];
+      sdkOutdated?: ComposeSdkOutdated;
+      serverOutdated?: ComposeServerOutdated;
     },
   ) {
     super(message, { cause: options?.cause });
@@ -102,6 +128,8 @@ export class ComposeError extends Error {
     this.details = options?.details;
     this.failedOps = options?.failedOps;
     this.succeededOps = options?.succeededOps;
+    this.sdkOutdated = options?.sdkOutdated;
+    this.serverOutdated = options?.serverOutdated;
   }
 }
 
@@ -153,6 +181,69 @@ export const isComposePreparationError = (
   Array.isArray(e.failedOps) &&
   Array.isArray(e.succeededOps);
 
+// `isComposeError` accepts a structurally-similar error by name, so an error
+// raised by a *second* copy of this package in the dependency tree reaches the
+// guard below without its `sdkOutdated` field being type-guaranteed. Parse it.
+const sdkOutdatedSchema = z.object({
+  sdkVersion: z.string(),
+  serverVersion: z.string(),
+  minimumSdkVersion: z.string(),
+});
+
+/**
+ * Narrows an outdated-SDK rejection to its required version details.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await builder.compile(run);
+ * } catch (e) {
+ *   if (isComposeSdkOutdatedError(e)) {
+ *     console.error(`Upgrade to at least ${e.sdkOutdated.minimumSdkVersion}`);
+ *     return;
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const isComposeSdkOutdatedError = (
+  e: unknown,
+): e is ComposeError & { readonly sdkOutdated: ComposeSdkOutdated } =>
+  isComposeError(e) &&
+  e.kind === 'sdk_outdated' &&
+  sdkOutdatedSchema.safeParse(e.sdkOutdated).success;
+
+const serverOutdatedSchema = z.object({
+  sdkVersion: z.string(),
+  serverVersion: z.string(),
+});
+
+/**
+ * Narrows a server-behind-SDK rejection to its required version details.
+ *
+ * This is the deploy-window error: the SDK on npm is ahead of the backend that
+ * answered. Pin the SDK to the server's `major.minor`, or wait for the rollout.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await builder.compile(run);
+ * } catch (e) {
+ *   if (isComposeServerOutdatedError(e)) {
+ *     console.error(`Server serves ${e.serverOutdated.serverVersion}`);
+ *     return;
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const isComposeServerOutdatedError = (
+  e: unknown,
+): e is ComposeError & { readonly serverOutdated: ComposeServerOutdated } =>
+  isComposeError(e) &&
+  e.kind === 'server_outdated' &&
+  serverOutdatedSchema.safeParse(e.serverOutdated).success;
+
 const STATUS_TO_CODE: ReadonlyMap<number, ComposeErrorCode> = new Map<
   number,
   ComposeErrorCode
@@ -175,6 +266,24 @@ const tryParseErrorBody = (body: string): ServerErrorBody | null => {
   return parseServerErrorBody(json);
 };
 
+/**
+ * Extracts the version triple an `sdk_outdated` or `server_outdated` envelope
+ * carries. The slots reuse the same schemas the type guards narrow with. Zod
+ * strips keys the schema does not declare, so the parsed value is exactly the
+ * triple; a partial payload fails the parse and yields `undefined` rather than
+ * a half-populated object.
+ */
+const readVersionSlots = (serverError: ServerErrorBody['error']) => ({
+  sdkOutdated:
+    serverError?.kind === 'sdk_outdated'
+      ? sdkOutdatedSchema.safeParse(serverError).data
+      : undefined,
+  serverOutdated:
+    serverError?.kind === 'server_outdated'
+      ? serverOutdatedSchema.safeParse(serverError).data
+      : undefined,
+});
+
 /**
  * Constructs a {@link ComposeError} from an HTTP error response, extracting
  * structured error details from the response body when available.
@@ -191,6 +300,7 @@ export const errorFromHttpResponse = (
 ): ComposeError => {
   const parsed = tryParseErrorBody(body);
   const serverError = parsed?.error;
+  const { sdkOutdated, serverOutdated } = readVersionSlots(serverError);
 
   return new ComposeError(
     STATUS_TO_CODE.get(status) ??
@@ -199,7 +309,8 @@ export const errorFromHttpResponse = (
     {
       status,
       url,
-      kind: serverError?.kind as ComposeErrorKind | undefined,
+      kind: serverError?.kind as
+        ComposeErrorKind | ComposeRouteErrorKind | undefined,
       path: serverError?.path,
       details: serverError?.details,
       // The wire schema types `kind` as a bare string; the server only ever
@@ -209,6 +320,8 @@ export const errorFromHttpResponse = (
         kind: op.kind as GenericComposeErrorKind,
       })),
       succeededOps: serverError?.succeededOps,
+      sdkOutdated,
+      serverOutdated,
     },
   );
 };

package/src/examples/run.ts

@@ -43,6 +43,7 @@ import type {
   ComposeRouteRequest,
 } from '@lifi/compose-spec';
 
+import { bigintReplacer } from '../client.js';
 import { type ComposeSdk, createComposeSdk } from '../sdk.js';
 
 import { buildAaveRepay } from './aaveRepay.js';
@@ -76,6 +77,9 @@ import { buildSwapWithOutputValidation } from './swapWithOutputValidation.js';
 import { buildPartialTransfer, buildTransferTokens } from './transferTokens.js';
 import { buildUntypedOpWithTypedRef } from './untypedOpWithTypedRef.js';
 
+const stringifyJson = (value: unknown) =>
+  JSON.stringify(value, bigintReplacer, 2);
+
 const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   'aave-repay': () =>
     buildAaveRepay({
@@ -233,14 +237,7 @@ const run = async () => {
   const request = routeBuilder ? routeBuilder() : builder!();
 
   console.log('--- Request ---');
-  console.log(
-    JSON.stringify(
-      request,
-      (_key, value: unknown) =>
-        typeof value === 'bigint' ? value.toString() : value,
-      2,
-    ),
-  );
+  console.log(stringifyJson(request));
 
   console.log(`\n--- Compiling against ${BASE_URL} ---`);
   const result = routeBuilder
@@ -248,7 +245,7 @@ const run = async () => {
     : await sdk.client.compile(request as ComposeCompileRequest);
 
   console.log('\n--- Result ---');
-  console.log(JSON.stringify(result, null, 2));
+  console.log(stringifyJson(result));
 };
 
 run().catch((err: unknown) => {

package/src/index.ts

@@ -31,6 +31,8 @@ export type {
 export type {
   ComposeError,
   ComposeErrorCode,
+  ComposeSdkOutdated,
+  ComposeServerOutdated,
   ComposePreparationOps,
 } from './errors.js';
 export type {
@@ -90,7 +92,12 @@ export {
   SIMULATE_MAX_TRACKED_BALANCES,
   SIMULATE_MAX_REQUIREMENTS,
 } from '@lifi/compose-spec';
-export { isComposeError, isComposePreparationError } from './errors.js';
+export {
+  isComposeError,
+  isComposePreparationError,
+  isComposeSdkOutdatedError,
+  isComposeServerOutdatedError,
+} from './errors.js';
 
 export type {
   Bindable,