@lifi/composer-sdk 0.4.1 → 0.5.1

package/src/client.ts

@@ -8,8 +8,18 @@ import type {
   SimulateRequest,
   SimulateResult,
 } from '@lifi/compose-spec';
+import {
+  checkCompatibility,
+  COMPOSE_VERSION_HEADER,
+  COMPOSER_SDK_VERSION_HEADER,
+  parseVersion,
+} from '@lifi/compose-spec';
 
-import type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
+import type {
+  ChainSummary,
+  GetZapPacksOptions,
+  ZapPackOverview,
+} from './discovery.js';
 import { ComposeError, errorFromHttpResponse } from './errors.js';
 import {
   parseCompilePartialEnvelope,
@@ -19,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.
@@ -55,6 +67,28 @@ export interface ComposeClient {
    * @throws {@link ComposeError} on network, validation, or server errors.
    */
   readonly getManifest: () => Promise<ComposeManifest>;
+  /**
+   * Fetches the chains the Compose API supports, ascending by `chainId`.
+   *
+   * A chain is listed once the server confirms the VM contract is deployed on
+   * it — the same condition {@link compile}, {@link route} and
+   * {@link simulate} validate against. A chain absent from this list is
+   * rejected outright by those endpoints.
+   *
+   * The converse does not hold: a listed chain can still have no routing edge
+   * for a given token pair, which {@link route} reports as `no_route_error`.
+   * Use {@link getZapPacks} to enumerate the pairs that do route.
+   *
+   * Each entry carries a display `name` alongside its `chainId`. The name is a
+   * deployment-maintained label — render it, but key on `chainId`.
+   *
+   * The list tracks the server's chain registry, which refreshes periodically.
+   * Results are not cached by the SDK; callers should cache as appropriate.
+   *
+   * @returns The supported chains, ascending by `chainId`.
+   * @throws {@link ComposeError} on network or server errors.
+   */
+  readonly getChains: () => Promise<readonly ChainSummary[]>;
   /**
    * Submits a compile request and returns the result.
    *
@@ -75,9 +109,9 @@ export interface ComposeClient {
    * `POST /compose/route`.
    *
    * A convenience path that skips flow authoring: the server builds a one-node
-   * `lifi.zap` flow with a `directDeposit` input from the `fromToken` /
-   * `toToken` pair and runs it through the same pipeline as {@link compile}.
-   * The response is therefore the same discriminated result — HTTP 206 under
+   * zap flow with a `directDeposit` input from the `fromToken` / `toToken`
+   * pair and runs it through the same pipeline as {@link compile}. The
+   * response is therefore the same discriminated result — HTTP 206 under
    * `simulationPolicy: 'allow-revert'` yields `status: 'partial'` rather than
    * throwing, exactly as it does for {@link compile}.
    *
@@ -88,6 +122,13 @@ export interface ComposeClient {
    * author richer flows later, so the single-step limit is the current state of
    * the server, not the shape of this contract.
    *
+   * Only synchronous edges are considered unless the request sets
+   * `allowAsyncRoutes: true`, so by default every produced resource comes back
+   * `availability: 'now'` and a pair reachable only after settlement is a
+   * `no_route_error`. Opting in adds the `lifi.zapAsync` fallback, which still
+   * loses to a synchronous edge when the pair has one; read
+   * `producedResources[*].availability` to see which representation you got.
+   *
    * Use {@link compile} for what the server does not author for you: several
    * chained operations, splits, explicit preconditions, or per-op guards.
    *
@@ -143,12 +184,80 @@ 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> =>
   typeof v === 'object' && v !== null;
 
+// Non-negative decimal integer string, as the server sends token amounts.
+const INTEGER_STRING = /^\d+$/;
+
+const decodeAmount = (
+  value: unknown,
+  key: string,
+  field: 'amountOut' | 'amountOutMin',
+  url: string,
+): bigint => {
+  if (typeof value !== 'string' || !INTEGER_STRING.test(value)) {
+    throw new ComposeError(
+      'UNKNOWN_ERROR',
+      `Malformed compose response: producedResources.${key}.simulated.${field} is ${
+        value === undefined ? 'absent' : 'not an integer string'
+      }`,
+      { url },
+    );
+  }
+  return BigInt(value);
+};
+
+// `simulated.amountOut` / `.amountOutMin` are declared `bigint` on
+// `SimulatedAmounts` (the domain truth: `compose-core` produces real bigints)
+// but arrive as decimal strings on the wire (the backend stringifies them).
+// Decode at this seam so a consumer reading the declared type gets the value
+// the type promises. A resource without `simulated` is left untouched; a
+// `simulated` claiming a missing or non-numeric amount is a contract violation
+// and surfaces as a `ComposeError` rather than `NaN` / `BigInt(undefined)`.
+const decodeSimulatedAmounts = (data: unknown, url: string): void => {
+  if (!isNonNullObject(data)) return;
+  const resources = data.producedResources;
+  if (!isNonNullObject(resources)) return;
+  for (const key of Object.keys(resources)) {
+    const resource = resources[key];
+    if (!isNonNullObject(resource)) continue;
+    const simulated = resource.simulated;
+    if (simulated === undefined) continue;
+    if (!isNonNullObject(simulated)) {
+      throw new ComposeError(
+        'UNKNOWN_ERROR',
+        `Malformed compose response: producedResources.${key}.simulated is not an object`,
+        { url },
+      );
+    }
+    simulated.amountOut = decodeAmount(
+      simulated.amountOut,
+      key,
+      'amountOut',
+      url,
+    );
+    if (simulated.amountOutMin !== undefined) {
+      simulated.amountOutMin = decodeAmount(
+        simulated.amountOutMin,
+        key,
+        'amountOutMin',
+        url,
+      );
+    }
+  }
+};
+
 const parseBody = async <T>(res: Response, url: string): Promise<T> => {
   const body = await res.json().catch((_) => null);
   if (!isNonNullObject(body) || !('data' in body)) {
@@ -164,6 +273,7 @@ const parseCompileSuccessBody = async (
   url: string,
 ): Promise<ComposeCompileResult> => {
   const data = await parseBody<ComposeCompileSuccessData>(res, url);
+  decodeSimulatedAmounts(data, url);
   return { ...data, status: 'success' as const };
 };
 
@@ -184,6 +294,7 @@ const parsePartialBody = async (
   // shape as a hand-authored type, so we narrow it here rather than re-declaring
   // that type as a schema. `error` is fully validated — no cast needed.
   const data = envelope.data as unknown as ComposeCompilePartialData;
+  decodeSimulatedAmounts(data, url);
   return { ...data, status: 'partial' as const, error: envelope.error };
 };
 
@@ -214,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);
   }
@@ -240,6 +421,20 @@ const postCompile = async (
   return await parseCompileSuccessBody(res, url);
 };
 
+// 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>(
+  transport: ComposeTransport,
+  url: string,
+): Promise<T> => {
+  const res = await send(transport, url, { method: 'GET' });
+  if (!res.ok) {
+    const body = await res.text();
+    throw errorFromHttpResponse(res.status, body, url);
+  }
+  return await parseBody<T>(res, url);
+};
+
 /**
  * Creates a low-level Compose API client.
  *
@@ -267,29 +462,16 @@ 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 };
 
-  const getManifest = async (): Promise<ComposeManifest> => {
-    const url = `${base}/compose/manifest`;
-    let res: Response;
-    try {
-      res = await fetchFn(url, {
-        method: 'GET',
-        headers: { ...baseHeaders },
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
-    }
-    if (!res.ok) {
-      const body = await res.text();
-      throw errorFromHttpResponse(res.status, body, url);
-    }
-    return await parseBody<ComposeManifest>(res, url);
-  };
+  const getManifest = async (): Promise<ComposeManifest> =>
+    getJson<ComposeManifest>(transport, `${base}/compose/manifest`);
+
+  const getChains = async (): Promise<readonly ChainSummary[]> =>
+    getJson<readonly ChainSummary[]>(transport, `${base}/chains`);
 
   const compile = async (
     request: ComposeCompileRequest,
@@ -312,39 +494,17 @@ export const createComposeClient = (
       params.set('protocols', list);
     }
     const qs = params.toString();
-    const url = `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`;
-    let res: Response;
-    try {
-      res = await fetchFn(url, {
-        method: 'GET',
-        headers: { ...baseHeaders },
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
-    }
-    if (!res.ok) {
-      const body = await res.text();
-      throw errorFromHttpResponse(res.status, body, url);
-    }
-    return await parseBody<readonly ZapPackOverview[]>(res, url);
+    return getJson<readonly ZapPackOverview[]>(
+      transport,
+      `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`,
+    );
   };
 
   const simulate = async (
     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
@@ -358,5 +518,5 @@ export const createComposeClient = (
     throw errorFromHttpResponse(res.status, body, url);
   };
 
-  return { getManifest, compile, route, getZapPacks, simulate };
+  return { getManifest, getChains, compile, route, getZapPacks, simulate };
 };

package/src/discovery.ts

@@ -1,5 +1,5 @@
 /**
- * Types for the Compose discovery API (`GET /compose/zap-packs`).
+ * Types for the Compose discovery API (`GET /compose/zap-packs`, `GET /chains`).
  *
  * These are SDK-facing presentation types — not part of the core compile
  * contract in compose-spec. The backend response is the source of truth;
@@ -11,6 +11,23 @@
  * `"enter-position"`, `"exit-position"`, `"wrap"`, `"unwrap"`, `"mint"`, `"burn"`.
  */
 
+/**
+ * A chain the Compose deployment supports.
+ */
+export interface ChainSummary {
+  /** EVM chain ID. The stable identifier — key on this. */
+  readonly chainId: number;
+  /**
+   * Human-readable label, suitable for display in a chain selector.
+   *
+   * Maintained by the deployment rather than derived from canonical chain
+   * branding, so it can differ from a chain's marketed name and can change
+   * without notice. Never treat it as an identifier, and never match on it.
+   * A chain the deployment has no configured label for reports `Chain <id>`.
+   */
+  readonly name: string;
+}
+
 /**
  * A single routing edge representing a supported token-to-token path
  * through a DeFi protocol.

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,
     },
   );
 };