@lifi/composer-sdk 0.2.0-staging.5 → 0.3.0

package/dist/responseSchemas.cjs

@@ -0,0 +1,110 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var responseSchemas_exports = {};
+__export(responseSchemas_exports, {
+  parseCompilePartialEnvelope: () => parseCompilePartialEnvelope,
+  parseServerErrorBody: () => parseServerErrorBody,
+  parseSimulateResult: () => parseSimulateResult
+});
+module.exports = __toCommonJS(responseSchemas_exports);
+var import_zod = __toESM(require("zod"), 1);
+const balanceEntrySchema = import_zod.default.object({
+  token: import_zod.default.string(),
+  owner: import_zod.default.string(),
+  amount: import_zod.default.string()
+});
+const simulateOkSchema = import_zod.default.object({
+  status: import_zod.default.literal("ok"),
+  block: import_zod.default.number(),
+  timestamp: import_zod.default.number(),
+  balancesBefore: import_zod.default.array(balanceEntrySchema),
+  balancesAfter: import_zod.default.array(balanceEntrySchema),
+  deltas: import_zod.default.array(balanceEntrySchema),
+  gasUsed: import_zod.default.string()
+});
+const simulateRevertDecodeResultSchema = import_zod.default.object({
+  errorCandidates: import_zod.default.array(
+    import_zod.default.object({
+      decodedErrorSignature: import_zod.default.string(),
+      decodedParams: import_zod.default.array(import_zod.default.string())
+    })
+  ).optional(),
+  error: import_zod.default.string().optional()
+});
+const simulateRevertSchema = import_zod.default.object({
+  status: import_zod.default.literal("revert"),
+  block: import_zod.default.number(),
+  timestamp: import_zod.default.number(),
+  revertReason: import_zod.default.string().optional(),
+  code: import_zod.default.number().optional(),
+  rawErrorBytes: import_zod.default.string().optional(),
+  decodeResult: simulateRevertDecodeResultSchema.optional()
+});
+const simulateSetupErrorSchema = import_zod.default.object({
+  status: import_zod.default.literal("error"),
+  message: import_zod.default.string()
+});
+const simulateResultSchema = import_zod.default.discriminatedUnion("status", [
+  simulateOkSchema,
+  simulateRevertSchema,
+  simulateSetupErrorSchema
+]);
+const parseSimulateResult = (body) => {
+  const parsed = simulateResultSchema.safeParse(body);
+  if (!parsed.success) return null;
+  const result = parsed.data;
+  return result;
+};
+const compilePartialEnvelopeSchema = import_zod.default.object({
+  data: import_zod.default.record(import_zod.default.string(), import_zod.default.unknown()),
+  error: import_zod.default.object({ kind: import_zod.default.string(), message: import_zod.default.string() })
+});
+const parseCompilePartialEnvelope = (body) => {
+  const parsed = compilePartialEnvelopeSchema.safeParse(body);
+  return parsed.success ? parsed.data : null;
+};
+const serverErrorBodySchema = import_zod.default.object({
+  error: import_zod.default.object({
+    kind: import_zod.default.string().optional(),
+    message: import_zod.default.string().optional(),
+    path: import_zod.default.string().optional(),
+    details: import_zod.default.custom().optional()
+  }).optional()
+});
+const parseServerErrorBody = (json) => {
+  const parsed = serverErrorBodySchema.safeParse(json);
+  return parsed.success ? parsed.data : null;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseCompilePartialEnvelope,
+  parseServerErrorBody,
+  parseSimulateResult
+});
+//# sourceMappingURL=responseSchemas.cjs.map

package/dist/responseSchemas.cjs.map

@@ -0,0 +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/** 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  };\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`.\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    })\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,iBAAc;AAkBd,MAAM,qBAAqB,WAAAA,QAAE,OAAO;AAAA,EAClC,OAAO,WAAAA,QAAE,OAAO;AAAA,EAChB,OAAO,WAAAA,QAAE,OAAO;AAAA,EAChB,QAAQ,WAAAA,QAAE,OAAO;AACnB,CAAC;AAED,MAAM,mBAAmB,WAAAA,QAAE,OAAO;AAAA,EAChC,QAAQ,WAAAA,QAAE,QAAQ,IAAI;AAAA,EACtB,OAAO,WAAAA,QAAE,OAAO;AAAA,EAChB,WAAW,WAAAA,QAAE,OAAO;AAAA,EACpB,gBAAgB,WAAAA,QAAE,MAAM,kBAAkB;AAAA,EAC1C,eAAe,WAAAA,QAAE,MAAM,kBAAkB;AAAA,EACzC,QAAQ,WAAAA,QAAE,MAAM,kBAAkB;AAAA,EAClC,SAAS,WAAAA,QAAE,OAAO;AACpB,CAAC;AAED,MAAM,mCAAmC,WAAAA,QAAE,OAAO;AAAA,EAChD,iBAAiB,WAAAA,QACd;AAAA,IACC,WAAAA,QAAE,OAAO;AAAA,MACP,uBAAuB,WAAAA,QAAE,OAAO;AAAA,MAChC,eAAe,WAAAA,QAAE,MAAM,WAAAA,QAAE,OAAO,CAAC;AAAA,IACnC,CAAC;AAAA,EACH,EACC,SAAS;AAAA,EACZ,OAAO,WAAAA,QAAE,OAAO,EAAE,SAAS;AAC7B,CAAC;AAED,MAAM,uBAAuB,WAAAA,QAAE,OAAO;AAAA,EACpC,QAAQ,WAAAA,QAAE,QAAQ,QAAQ;AAAA,EAC1B,OAAO,WAAAA,QAAE,OAAO;AAAA,EAChB,WAAW,WAAAA,QAAE,OAAO;AAAA,EACpB,cAAc,WAAAA,QAAE,OAAO,EAAE,SAAS;AAAA,EAClC,MAAM,WAAAA,QAAE,OAAO,EAAE,SAAS;AAAA,EAC1B,eAAe,WAAAA,QAAE,OAAO,EAAE,SAAS;AAAA,EACnC,cAAc,iCAAiC,SAAS;AAC1D,CAAC;AAED,MAAM,2BAA2B,WAAAA,QAAE,OAAO;AAAA,EACxC,QAAQ,WAAAA,QAAE,QAAQ,OAAO;AAAA,EACzB,SAAS,WAAAA,QAAE,OAAO;AACpB,CAAC;AAED,MAAM,uBAAuB,WAAAA,QAAE,mBAAmB,UAAU;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAYM,MAAM,sBAAsB,CAAC,SAAyC;AAC3E,QAAM,SAAS,qBAAqB,UAAU,IAAI;AAClD,MAAI,CAAC,OAAO,QAAS,QAAO;AAM5B,QAAM,SAAyB,OAAO;AACtC,SAAO;AACT;AAaA,MAAM,+BAA+B,WAAAA,QAAE,OAAO;AAAA,EAC5C,MAAM,WAAAA,QAAE,OAAO,WAAAA,QAAE,OAAO,GAAG,WAAAA,QAAE,QAAQ,CAAC;AAAA,EACtC,OAAO,WAAAA,QAAE,OAAO,EAAE,MAAM,WAAAA,QAAE,OAAO,GAAG,SAAS,WAAAA,QAAE,OAAO,EAAE,CAAC;AAC3D,CAAC;AAGM,MAAM,8BAA8B,CACzC,SACkC;AAClC,QAAM,SAAS,6BAA6B,UAAU,IAAI;AAC1D,SAAO,OAAO,UAAU,OAAO,OAAO;AACxC;AAeA,MAAM,wBAAwB,WAAAA,QAAE,OAAO;AAAA,EACrC,OAAO,WAAAA,QACJ,OAAO;AAAA,IACN,MAAM,WAAAA,QAAE,OAAO,EAAE,SAAS;AAAA,IAC1B,SAAS,WAAAA,QAAE,OAAO,EAAE,SAAS;AAAA,IAC7B,MAAM,WAAAA,QAAE,OAAO,EAAE,SAAS;AAAA,IAC1B,SAAS,WAAAA,QAAE,OAAyB,EAAE,SAAS;AAAA,EACjD,CAAC,EACA,SAAS;AACd,CAAC;AAGM,MAAM,uBAAuB,CAAC,SAA0C;AAC7E,QAAM,SAAS,sBAAsB,UAAU,IAAI;AACnD,SAAO,OAAO,UAAU,OAAO,OAAO;AACxC;","names":["z"]}

package/dist/responseSchemas.d.cts

@@ -0,0 +1,36 @@
+import { SimulationRevert, SimulateResult } from '@lifi/compose-spec';
+
+/**
+ * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`
+ * when the body does not match the `ok`/`revert`/`error` union, letting the
+ * caller raise a transport-level error.
+ */
+declare const parseSimulateResult: (body: unknown) => SimulateResult | null;
+/**
+ * The validated members of an HTTP 206 partial compile envelope. `data` is
+ * verified to be an object but kept untyped — compose-spec owns its full shape
+ * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows
+ * it. `error` is fully validated.
+ */
+interface CompilePartialEnvelope {
+    readonly data: Record<string, unknown>;
+    readonly error: {
+        readonly kind: string;
+        readonly message: string;
+    };
+}
+/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */
+declare const parseCompilePartialEnvelope: (body: unknown) => CompilePartialEnvelope | null;
+/** Error envelope returned on non-2xx responses. */
+interface ServerErrorBody {
+    readonly error?: {
+        readonly kind?: string;
+        readonly message?: string;
+        readonly path?: string;
+        readonly details?: SimulationRevert;
+    };
+}
+/** Validates an already-parsed error envelope; `null` when it does not match. */
+declare const parseServerErrorBody: (json: unknown) => ServerErrorBody | null;
+
+export { type CompilePartialEnvelope, type ServerErrorBody, parseCompilePartialEnvelope, parseServerErrorBody, parseSimulateResult };

package/dist/responseSchemas.d.ts

@@ -0,0 +1,36 @@
+import { SimulationRevert, SimulateResult } from '@lifi/compose-spec';
+
+/**
+ * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`
+ * when the body does not match the `ok`/`revert`/`error` union, letting the
+ * caller raise a transport-level error.
+ */
+declare const parseSimulateResult: (body: unknown) => SimulateResult | null;
+/**
+ * The validated members of an HTTP 206 partial compile envelope. `data` is
+ * verified to be an object but kept untyped — compose-spec owns its full shape
+ * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows
+ * it. `error` is fully validated.
+ */
+interface CompilePartialEnvelope {
+    readonly data: Record<string, unknown>;
+    readonly error: {
+        readonly kind: string;
+        readonly message: string;
+    };
+}
+/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */
+declare const parseCompilePartialEnvelope: (body: unknown) => CompilePartialEnvelope | null;
+/** Error envelope returned on non-2xx responses. */
+interface ServerErrorBody {
+    readonly error?: {
+        readonly kind?: string;
+        readonly message?: string;
+        readonly path?: string;
+        readonly details?: SimulationRevert;
+    };
+}
+/** Validates an already-parsed error envelope; `null` when it does not match. */
+declare const parseServerErrorBody: (json: unknown) => ServerErrorBody | null;
+
+export { type CompilePartialEnvelope, type ServerErrorBody, parseCompilePartialEnvelope, parseServerErrorBody, parseSimulateResult };

package/dist/responseSchemas.js

@@ -0,0 +1,74 @@
+import z from "zod";
+const balanceEntrySchema = z.object({
+  token: z.string(),
+  owner: z.string(),
+  amount: z.string()
+});
+const simulateOkSchema = z.object({
+  status: z.literal("ok"),
+  block: z.number(),
+  timestamp: z.number(),
+  balancesBefore: z.array(balanceEntrySchema),
+  balancesAfter: z.array(balanceEntrySchema),
+  deltas: z.array(balanceEntrySchema),
+  gasUsed: z.string()
+});
+const simulateRevertDecodeResultSchema = z.object({
+  errorCandidates: z.array(
+    z.object({
+      decodedErrorSignature: z.string(),
+      decodedParams: z.array(z.string())
+    })
+  ).optional(),
+  error: z.string().optional()
+});
+const simulateRevertSchema = z.object({
+  status: z.literal("revert"),
+  block: z.number(),
+  timestamp: z.number(),
+  revertReason: z.string().optional(),
+  code: z.number().optional(),
+  rawErrorBytes: z.string().optional(),
+  decodeResult: simulateRevertDecodeResultSchema.optional()
+});
+const simulateSetupErrorSchema = z.object({
+  status: z.literal("error"),
+  message: z.string()
+});
+const simulateResultSchema = z.discriminatedUnion("status", [
+  simulateOkSchema,
+  simulateRevertSchema,
+  simulateSetupErrorSchema
+]);
+const parseSimulateResult = (body) => {
+  const parsed = simulateResultSchema.safeParse(body);
+  if (!parsed.success) return null;
+  const result = parsed.data;
+  return result;
+};
+const compilePartialEnvelopeSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+  error: z.object({ kind: z.string(), message: z.string() })
+});
+const parseCompilePartialEnvelope = (body) => {
+  const parsed = compilePartialEnvelopeSchema.safeParse(body);
+  return parsed.success ? parsed.data : null;
+};
+const serverErrorBodySchema = z.object({
+  error: z.object({
+    kind: z.string().optional(),
+    message: z.string().optional(),
+    path: z.string().optional(),
+    details: z.custom().optional()
+  }).optional()
+});
+const parseServerErrorBody = (json) => {
+  const parsed = serverErrorBodySchema.safeParse(json);
+  return parsed.success ? parsed.data : null;
+};
+export {
+  parseCompilePartialEnvelope,
+  parseServerErrorBody,
+  parseSimulateResult
+};
+//# sourceMappingURL=responseSchemas.js.map

package/dist/responseSchemas.js.map

@@ -0,0 +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/** 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  };\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`.\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    })\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":"AACA,OAAO,OAAO;AAkBd,MAAM,qBAAqB,EAAE,OAAO;AAAA,EAClC,OAAO,EAAE,OAAO;AAAA,EAChB,OAAO,EAAE,OAAO;AAAA,EAChB,QAAQ,EAAE,OAAO;AACnB,CAAC;AAED,MAAM,mBAAmB,EAAE,OAAO;AAAA,EAChC,QAAQ,EAAE,QAAQ,IAAI;AAAA,EACtB,OAAO,EAAE,OAAO;AAAA,EAChB,WAAW,EAAE,OAAO;AAAA,EACpB,gBAAgB,EAAE,MAAM,kBAAkB;AAAA,EAC1C,eAAe,EAAE,MAAM,kBAAkB;AAAA,EACzC,QAAQ,EAAE,MAAM,kBAAkB;AAAA,EAClC,SAAS,EAAE,OAAO;AACpB,CAAC;AAED,MAAM,mCAAmC,EAAE,OAAO;AAAA,EAChD,iBAAiB,EACd;AAAA,IACC,EAAE,OAAO;AAAA,MACP,uBAAuB,EAAE,OAAO;AAAA,MAChC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC;AAAA,IACnC,CAAC;AAAA,EACH,EACC,SAAS;AAAA,EACZ,OAAO,EAAE,OAAO,EAAE,SAAS;AAC7B,CAAC;AAED,MAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,QAAQ,EAAE,QAAQ,QAAQ;AAAA,EAC1B,OAAO,EAAE,OAAO;AAAA,EAChB,WAAW,EAAE,OAAO;AAAA,EACpB,cAAc,EAAE,OAAO,EAAE,SAAS;AAAA,EAClC,MAAM,EAAE,OAAO,EAAE,SAAS;AAAA,EAC1B,eAAe,EAAE,OAAO,EAAE,SAAS;AAAA,EACnC,cAAc,iCAAiC,SAAS;AAC1D,CAAC;AAED,MAAM,2BAA2B,EAAE,OAAO;AAAA,EACxC,QAAQ,EAAE,QAAQ,OAAO;AAAA,EACzB,SAAS,EAAE,OAAO;AACpB,CAAC;AAED,MAAM,uBAAuB,EAAE,mBAAmB,UAAU;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAYM,MAAM,sBAAsB,CAAC,SAAyC;AAC3E,QAAM,SAAS,qBAAqB,UAAU,IAAI;AAClD,MAAI,CAAC,OAAO,QAAS,QAAO;AAM5B,QAAM,SAAyB,OAAO;AACtC,SAAO;AACT;AAaA,MAAM,+BAA+B,EAAE,OAAO;AAAA,EAC5C,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC;AAAA,EACtC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,OAAO,EAAE,CAAC;AAC3D,CAAC;AAGM,MAAM,8BAA8B,CACzC,SACkC;AAClC,QAAM,SAAS,6BAA6B,UAAU,IAAI;AAC1D,SAAO,OAAO,UAAU,OAAO,OAAO;AACxC;AAeA,MAAM,wBAAwB,EAAE,OAAO;AAAA,EACrC,OAAO,EACJ,OAAO;AAAA,IACN,MAAM,EAAE,OAAO,EAAE,SAAS;AAAA,IAC1B,SAAS,EAAE,OAAO,EAAE,SAAS;AAAA,IAC7B,MAAM,EAAE,OAAO,EAAE,SAAS;AAAA,IAC1B,SAAS,EAAE,OAAyB,EAAE,SAAS;AAAA,EACjD,CAAC,EACA,SAAS;AACd,CAAC;AAGM,MAAM,uBAAuB,CAAC,SAA0C;AAC7E,QAAM,SAAS,sBAAsB,UAAU,IAAI;AACnD,SAAO,OAAO,UAAU,OAAO,OAAO;AACxC;","names":[]}

package/dist/run/simulate.cjs

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var simulate_exports = {};
+__export(simulate_exports, {
+  buildSimulateRequest: () => buildSimulateRequest
+});
+module.exports = __toCommonJS(simulate_exports);
+const buildSimulateRequest = (input) => {
+  const { result, chainId, signer, trackedBalances, requirements, block } = input;
+  return {
+    chainId,
+    from: signer,
+    to: result.transactionRequest.to,
+    data: result.transactionRequest.data,
+    value: input.value ?? result.transactionRequest.value,
+    block,
+    requirements,
+    trackedBalances
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildSimulateRequest
+});
+//# sourceMappingURL=simulate.cjs.map

package/dist/run/simulate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/run/simulate.ts"],"sourcesContent":["import type {\n  ComposeCompileResult,\n  SimulateRequest,\n  SlotFinderRequirement,\n  TrackedBalance,\n} from '@lifi/compose-spec';\n\n/**\n * Input for {@link buildSimulateRequest}: a compile result plus the fields a\n * simulation needs that a compiled flow does not carry.\n */\nexport interface BuildSimulateRequestInput {\n  /**\n   * A result from `builder.compile(...)` / `client.compile(...)`. Both\n   * `success` and `partial` results carry a `transactionRequest`, so either is\n   * valid input — the helper does not discriminate on `status`.\n   */\n  readonly result: ComposeCompileResult;\n  /** EVM chain id. A compile result does not carry the target chain. */\n  readonly chainId: number;\n  /**\n   * The transaction sender (`from`). A compile result does not carry the\n   * signer, so it must be supplied here.\n   */\n  readonly signer: string;\n  /**\n   * Balances to watch across the simulation. These cannot be inferred from a\n   * flow and must be supplied by the caller.\n   */\n  readonly trackedBalances: readonly TrackedBalance[];\n  /** Optional funding instructions applied before simulation. */\n  readonly requirements?: readonly SlotFinderRequirement[];\n  /** Optional block to pin the simulation to. Omitted ⇒ chain head. */\n  readonly block?: number;\n  /**\n   * Optional native value override. Defaults to the compiled\n   * `transactionRequest.value` when omitted.\n   */\n  readonly value?: bigint | string;\n}\n\n/**\n * Assembles a {@link SimulateRequest} from a compile result and the\n * caller-supplied chain, signer, and tracked balances. Pure: performs no\n * network I/O, does not mutate its input, and returns a fresh object.\n *\n * Bridges the common case — simulate the transaction you just compiled —\n * without coupling raw-transaction simulation to the flow builder. The\n * `value` defaults to the compiled transaction's value unless overridden.\n *\n * @example\n * ```ts\n * const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });\n * const req = buildSimulateRequest({\n *   result: compiled,\n *   chainId: 1,\n *   signer: '0x1111111111111111111111111111111111111111',\n *   trackedBalances: [{ token: '0xA0b8...', owner: '0x1111...' }],\n * });\n * const sim = await sdk.client.simulate(req);\n * ```\n */\nexport const buildSimulateRequest = (\n  input: BuildSimulateRequestInput,\n): SimulateRequest => {\n  const { result, chainId, signer, trackedBalances, requirements, block } =\n    input;\n  return {\n    chainId,\n    from: signer,\n    to: result.transactionRequest.to,\n    data: result.transactionRequest.data,\n    value: input.value ?? result.transactionRequest.value,\n    block,\n    requirements,\n    trackedBalances,\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA8DO,MAAM,uBAAuB,CAClC,UACoB;AACpB,QAAM,EAAE,QAAQ,SAAS,QAAQ,iBAAiB,cAAc,MAAM,IACpE;AACF,SAAO;AAAA,IACL;AAAA,IACA,MAAM;AAAA,IACN,IAAI,OAAO,mBAAmB;AAAA,IAC9B,MAAM,OAAO,mBAAmB;AAAA,IAChC,OAAO,MAAM,SAAS,OAAO,mBAAmB;AAAA,IAChD;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/run/simulate.d.cts

@@ -0,0 +1,59 @@
+import { ComposeCompileResult, TrackedBalance, SlotFinderRequirement, SimulateRequest } from '@lifi/compose-spec';
+
+/**
+ * Input for {@link buildSimulateRequest}: a compile result plus the fields a
+ * simulation needs that a compiled flow does not carry.
+ */
+interface BuildSimulateRequestInput {
+    /**
+     * A result from `builder.compile(...)` / `client.compile(...)`. Both
+     * `success` and `partial` results carry a `transactionRequest`, so either is
+     * valid input — the helper does not discriminate on `status`.
+     */
+    readonly result: ComposeCompileResult;
+    /** EVM chain id. A compile result does not carry the target chain. */
+    readonly chainId: number;
+    /**
+     * The transaction sender (`from`). A compile result does not carry the
+     * signer, so it must be supplied here.
+     */
+    readonly signer: string;
+    /**
+     * Balances to watch across the simulation. These cannot be inferred from a
+     * flow and must be supplied by the caller.
+     */
+    readonly trackedBalances: readonly TrackedBalance[];
+    /** Optional funding instructions applied before simulation. */
+    readonly requirements?: readonly SlotFinderRequirement[];
+    /** Optional block to pin the simulation to. Omitted ⇒ chain head. */
+    readonly block?: number;
+    /**
+     * Optional native value override. Defaults to the compiled
+     * `transactionRequest.value` when omitted.
+     */
+    readonly value?: bigint | string;
+}
+/**
+ * Assembles a {@link SimulateRequest} from a compile result and the
+ * caller-supplied chain, signer, and tracked balances. Pure: performs no
+ * network I/O, does not mutate its input, and returns a fresh object.
+ *
+ * Bridges the common case — simulate the transaction you just compiled —
+ * without coupling raw-transaction simulation to the flow builder. The
+ * `value` defaults to the compiled transaction's value unless overridden.
+ *
+ * @example
+ * ```ts
+ * const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });
+ * const req = buildSimulateRequest({
+ *   result: compiled,
+ *   chainId: 1,
+ *   signer: '0x1111111111111111111111111111111111111111',
+ *   trackedBalances: [{ token: '0xA0b8...', owner: '0x1111...' }],
+ * });
+ * const sim = await sdk.client.simulate(req);
+ * ```
+ */
+declare const buildSimulateRequest: (input: BuildSimulateRequestInput) => SimulateRequest;
+
+export { type BuildSimulateRequestInput, buildSimulateRequest };

package/dist/run/simulate.d.ts

@@ -0,0 +1,59 @@
+import { ComposeCompileResult, TrackedBalance, SlotFinderRequirement, SimulateRequest } from '@lifi/compose-spec';
+
+/**
+ * Input for {@link buildSimulateRequest}: a compile result plus the fields a
+ * simulation needs that a compiled flow does not carry.
+ */
+interface BuildSimulateRequestInput {
+    /**
+     * A result from `builder.compile(...)` / `client.compile(...)`. Both
+     * `success` and `partial` results carry a `transactionRequest`, so either is
+     * valid input — the helper does not discriminate on `status`.
+     */
+    readonly result: ComposeCompileResult;
+    /** EVM chain id. A compile result does not carry the target chain. */
+    readonly chainId: number;
+    /**
+     * The transaction sender (`from`). A compile result does not carry the
+     * signer, so it must be supplied here.
+     */
+    readonly signer: string;
+    /**
+     * Balances to watch across the simulation. These cannot be inferred from a
+     * flow and must be supplied by the caller.
+     */
+    readonly trackedBalances: readonly TrackedBalance[];
+    /** Optional funding instructions applied before simulation. */
+    readonly requirements?: readonly SlotFinderRequirement[];
+    /** Optional block to pin the simulation to. Omitted ⇒ chain head. */
+    readonly block?: number;
+    /**
+     * Optional native value override. Defaults to the compiled
+     * `transactionRequest.value` when omitted.
+     */
+    readonly value?: bigint | string;
+}
+/**
+ * Assembles a {@link SimulateRequest} from a compile result and the
+ * caller-supplied chain, signer, and tracked balances. Pure: performs no
+ * network I/O, does not mutate its input, and returns a fresh object.
+ *
+ * Bridges the common case — simulate the transaction you just compiled —
+ * without coupling raw-transaction simulation to the flow builder. The
+ * `value` defaults to the compiled transaction's value unless overridden.
+ *
+ * @example
+ * ```ts
+ * const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });
+ * const req = buildSimulateRequest({
+ *   result: compiled,
+ *   chainId: 1,
+ *   signer: '0x1111111111111111111111111111111111111111',
+ *   trackedBalances: [{ token: '0xA0b8...', owner: '0x1111...' }],
+ * });
+ * const sim = await sdk.client.simulate(req);
+ * ```
+ */
+declare const buildSimulateRequest: (input: BuildSimulateRequestInput) => SimulateRequest;
+
+export { type BuildSimulateRequestInput, buildSimulateRequest };

package/dist/run/simulate.js

@@ -0,0 +1,17 @@
+const buildSimulateRequest = (input) => {
+  const { result, chainId, signer, trackedBalances, requirements, block } = input;
+  return {
+    chainId,
+    from: signer,
+    to: result.transactionRequest.to,
+    data: result.transactionRequest.data,
+    value: input.value ?? result.transactionRequest.value,
+    block,
+    requirements,
+    trackedBalances
+  };
+};
+export {
+  buildSimulateRequest
+};
+//# sourceMappingURL=simulate.js.map

package/dist/run/simulate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/run/simulate.ts"],"sourcesContent":["import type {\n  ComposeCompileResult,\n  SimulateRequest,\n  SlotFinderRequirement,\n  TrackedBalance,\n} from '@lifi/compose-spec';\n\n/**\n * Input for {@link buildSimulateRequest}: a compile result plus the fields a\n * simulation needs that a compiled flow does not carry.\n */\nexport interface BuildSimulateRequestInput {\n  /**\n   * A result from `builder.compile(...)` / `client.compile(...)`. Both\n   * `success` and `partial` results carry a `transactionRequest`, so either is\n   * valid input — the helper does not discriminate on `status`.\n   */\n  readonly result: ComposeCompileResult;\n  /** EVM chain id. A compile result does not carry the target chain. */\n  readonly chainId: number;\n  /**\n   * The transaction sender (`from`). A compile result does not carry the\n   * signer, so it must be supplied here.\n   */\n  readonly signer: string;\n  /**\n   * Balances to watch across the simulation. These cannot be inferred from a\n   * flow and must be supplied by the caller.\n   */\n  readonly trackedBalances: readonly TrackedBalance[];\n  /** Optional funding instructions applied before simulation. */\n  readonly requirements?: readonly SlotFinderRequirement[];\n  /** Optional block to pin the simulation to. Omitted ⇒ chain head. */\n  readonly block?: number;\n  /**\n   * Optional native value override. Defaults to the compiled\n   * `transactionRequest.value` when omitted.\n   */\n  readonly value?: bigint | string;\n}\n\n/**\n * Assembles a {@link SimulateRequest} from a compile result and the\n * caller-supplied chain, signer, and tracked balances. Pure: performs no\n * network I/O, does not mutate its input, and returns a fresh object.\n *\n * Bridges the common case — simulate the transaction you just compiled —\n * without coupling raw-transaction simulation to the flow builder. The\n * `value` defaults to the compiled transaction's value unless overridden.\n *\n * @example\n * ```ts\n * const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });\n * const req = buildSimulateRequest({\n *   result: compiled,\n *   chainId: 1,\n *   signer: '0x1111111111111111111111111111111111111111',\n *   trackedBalances: [{ token: '0xA0b8...', owner: '0x1111...' }],\n * });\n * const sim = await sdk.client.simulate(req);\n * ```\n */\nexport const buildSimulateRequest = (\n  input: BuildSimulateRequestInput,\n): SimulateRequest => {\n  const { result, chainId, signer, trackedBalances, requirements, block } =\n    input;\n  return {\n    chainId,\n    from: signer,\n    to: result.transactionRequest.to,\n    data: result.transactionRequest.data,\n    value: input.value ?? result.transactionRequest.value,\n    block,\n    requirements,\n    trackedBalances,\n  };\n};\n"],"mappings":"AA8DO,MAAM,uBAAuB,CAClC,UACoB;AACpB,QAAM,EAAE,QAAQ,SAAS,QAAQ,iBAAiB,cAAc,MAAM,IACpE;AACF,SAAO;AAAA,IACL;AAAA,IACA,MAAM;AAAA,IACN,IAAI,OAAO,mBAAmB;AAAA,IAC9B,MAAM,OAAO,mBAAmB;AAAA,IAChC,OAAO,MAAM,SAAS,OAAO,mBAAmB;AAAA,IAChD;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/sdk.cjs

@@ -52,7 +52,12 @@ const createComposeSdk = (options) => {
     };
     return Object.assign(builder, { compile });
   };
-  return { client: composeClient, flow, request };
+  return {
+    client: composeClient,
+    flow,
+    request,
+    simulate: composeClient.simulate
+  };
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/sdk.cjs.map

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

package/dist/sdk.d.cts

@@ -1,4 +1,4 @@
-import { ComposeCompileResult, ComposeCompileRequest } from '@lifi/compose-spec';
+import { ComposeCompileResult, ComposeCompileRequest, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
 import { FlowOptions, FlowBuilderCore, TypedFlow } from './authoring/FlowBuilderCore.cjs';
 import { ComposeClient } from './client.cjs';
 import { GeneratedOps } from './generated/operations.generated.cjs';
@@ -46,8 +46,8 @@ interface ComposeSdkOptions {
     readonly baseUrl: string;
     /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */
     readonly fetch?: typeof globalThis.fetch;
-    /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */
-    readonly apiKey?: string;
+    /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */
+    readonly apiKey: string;
 }
 /**
  * The top-level Compose SDK interface.
@@ -59,7 +59,7 @@ interface ComposeSdkOptions {
  * ```ts
  * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';
  *
- * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
  *
  * const builder = sdk.flow(1, {
  *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },
@@ -95,16 +95,28 @@ interface ComposeSdk {
      * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.
      */
     readonly request: <T extends InputSchema>(flow: TypedFlow<T>, run: ComposeRunInput<T>) => ComposeCompileRequest;
+    /**
+     * Simulates a raw, pre-encoded transaction. Thin pass-through to
+     * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`
+     * result discrimination and error behaviour. Pair with `buildSimulateRequest`
+     * to assemble the request from a compile result.
+     *
+     * @param request - The raw transaction plus funding `requirements` and
+     *   `trackedBalances`.
+     * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+     * @throws {@link ComposeError} on network, validation, or server errors.
+     */
+    readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 /**
  * Creates a new Compose SDK instance.
  *
- * @param options - SDK configuration including the API base URL and optional fetch implementation.
+ * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.
  * @returns A {@link ComposeSdk} instance.
  *
  * @example
  * ```ts
- * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
  * ```
  */
 declare const createComposeSdk: (options: ComposeSdkOptions) => ComposeSdk;