@lifi/composer-sdk 0.4.1 → 0.5.1

package/dist/sdk.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeRouteRequest,\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   * Compiles a token pair on one chain — as of today a single zap step over\n   * one routing-catalog edge. Thin pass-through to\n   * {@link ComposeClient.route}; see it for the current single-step limit,\n   * when to prefer `flow(...).compile(...)`, the `success` / `partial`\n   * discrimination, and error behaviour. Build the `amount` with\n   * `routeAmount.exact(...)` / `routeAmount.all(...)`.\n   *\n   * @param request - The from/to token pair, amount, signer, and route options.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly route: (\n    request: ComposeRouteRequest,\n  ) => Promise<ComposeCompileResult>;\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    route: composeClient.route,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":"AASA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AA8IxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;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,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,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,OAAO,cAAc;AAAA,IACrB,UAAU,cAAc;AAAA,EAC1B;AACF;","names":[]}
+{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeRouteRequest,\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 type { ChainSummary } from './discovery.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   * Fetches the chains this Compose deployment supports, ascending by\n   * `chainId`. Thin pass-through to {@link ComposeClient.getChains}; see it\n   * for what \"supported\" means and for the caching caveat.\n   *\n   * Each entry pairs the `chainId` with a display `name`, so one call both\n   * gates a chain selector and labels it. Key on `chainId`; `name` is a\n   * deployment-maintained label that can change.\n   *\n   * Use it to fail fast before building a flow for a chain the server would\n   * reject.\n   *\n   * @returns The supported chains, ascending by `chainId`.\n   * @throws {@link ComposeError} on network or server errors.\n   *\n   * @example\n   * ```ts\n   * const chains = await sdk.getSupportedChains();\n   * if (!chains.some((c) => c.chainId === 8453)) {\n   *   throw new Error('Base is not supported');\n   * }\n   * for (const { chainId, name } of chains) {\n   *   console.log(`${name} (${chainId})`);\n   * }\n   * ```\n   */\n  readonly getSupportedChains: () => Promise<readonly ChainSummary[]>;\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   * Compiles a token pair on one chain — as of today a single zap step over\n   * one routing-catalog edge. Thin pass-through to\n   * {@link ComposeClient.route}; see it for the current single-step limit,\n   * when to prefer `flow(...).compile(...)`, the `success` / `partial`\n   * discrimination, and error behaviour. Build the `amount` with\n   * `routeAmount.exact(...)` / `routeAmount.all(...)`.\n   *\n   * @param request - The from/to token pair, amount, signer, and route options.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly route: (\n    request: ComposeRouteRequest,\n  ) => Promise<ComposeCompileResult>;\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      simulateUserProgram: run.simulateUserProgram,\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    getSupportedChains: composeClient.getChains,\n    request,\n    route: composeClient.route,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":"AASA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AAExD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AAyKxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;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,qBAAqB,IAAI;AAAA,MACzB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,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,oBAAoB,cAAc;AAAA,IAClC;AAAA,IACA,OAAO,cAAc;AAAA,IACrB,UAAU,cAAc;AAAA,EAC1B;AACF;","names":[]}

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { Ref } from '@lifi/compose-spec';\nimport {\n  InputSpec,\n  MaterialiserInput,\n  Resource,\n  SolType,\n} from '@lifi/compose-spec';\n\n/**\n * A string that represents a non-negative integer (e.g. \"1000000000\").\n * Uses a template literal type so that only numeric-looking strings\n * are assignable at compile time.\n */\nexport type IntegerString = `${bigint}`;\n\n/**\n * Accepted input for integer-string config fields.\n * Callers may pass either a numeric string (\"1000000000\") or a native bigint\n * (1000000000n). Bigint values are stringified automatically during JSON\n * serialization via the SDK's `bigintReplacer`.\n */\nexport type IntegerStringInput = IntegerString | bigint;\n\n/**\n * A `0x`-prefixed hex string representing an Ethereum address.\n * Template literal type catches obviously wrong values at compile time.\n */\nexport type Address = `0x${string}`;\n\n/** The universe of output port kinds: Solidity scalar types plus `'resource'`. */\nexport type OutputKind = SolType | 'resource';\n\n/**\n * Maps an ABI parameter type string (from abitype's `ParseAbiItem`) to the\n * closest `OutputKind`. When the ABI type is one of the supported `SolType`\n * scalars, the mapping is exact; for all other Solidity types (e.g. tuples,\n * fixed-point decimals) it falls back to `SolType` — accepting any scalar\n * handle but not `'resource'` handles.\n *\n * The fallback excludes `'resource'` because every Solidity type is a scalar;\n * resource handles carry token-amount semantics that should only flow into\n * slots explicitly declared as resources.\n *\n * Extending `SolType` with new members automatically widens the exact-match\n * branch — no changes needed here.\n */\nexport type AbiTypeToOutputKind<T extends string> = T extends SolType\n  ? T\n  : SolType;\n\n/**\n * A typed `$ref` pointer carrying a phantom type parameter.\n * Extends `Ref` so it is accepted anywhere a plain `Ref` is.\n * The `__outputKind` field is never set at runtime — it exists only\n * for TypeScript's structural type checker to distinguish typed refs.\n */\nexport interface TypedRef<T extends OutputKind = OutputKind> extends Ref {\n  readonly __outputKind?: T;\n}\n\n/**\n * An input declaration in a flow schema.\n * `Resource` values become resource inputs (token amounts);\n * `SolType` strings become handle inputs (scalars like addresses).\n */\nexport type InputDecl = Resource | SolType;\n\n/**\n * A record mapping input names to their declarations.\n * Used as the type parameter for generic flow builders and requests.\n */\nexport type InputSchema = Record<string, InputDecl>;\n\n/**\n * Maps an input declaration to the allowed runtime value type.\n * Resource inputs accept materialisers or literal amounts.\n * Handle inputs accept the scalar type matching their SolType.\n */\nexport type InputSpecOf<D> = D extends Resource\n  ? MaterialiserInput | IntegerStringInput\n  : D extends 'address'\n    ? Address\n    : D extends 'bool'\n      ? boolean\n      : D extends `${'u' | ''}int${string}`\n        ? IntegerStringInput\n        : D extends `bytes${string}`\n          ? `0x${string}`\n          : D extends 'string'\n            ? string\n            : InputSpec;\n\n/**\n * A guard applied to an operation, with the `port` field constrained\n * to a specific set of output port names.\n */\nexport interface TypedGuard<Port extends string = string> {\n  readonly kind: string;\n  readonly port: Port;\n  readonly [key: string]: unknown;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { LiteralBinding, Ref } from '@lifi/compose-spec';\nimport {\n  InputSpec,\n  MaterialiserInput,\n  Resource,\n  SolType,\n} from '@lifi/compose-spec';\n\n/**\n * A string that represents a non-negative integer (e.g. \"1000000000\").\n * Uses a template literal type so that only numeric-looking strings\n * are assignable at compile time.\n */\nexport type IntegerString = `${bigint}`;\n\n/**\n * Accepted input for integer-string config fields.\n * Callers may pass either a numeric string (\"1000000000\") or a native bigint\n * (1000000000n). Bigint values are stringified automatically during JSON\n * serialization via the SDK's `bigintReplacer`.\n */\nexport type IntegerStringInput = IntegerString | bigint;\n\n/**\n * A `0x`-prefixed hex string representing an Ethereum address.\n * Template literal type catches obviously wrong values at compile time.\n */\nexport type Address = `0x${string}`;\n\n/** The universe of output port kinds: Solidity scalar types plus `'resource'`. */\nexport type OutputKind = SolType | 'resource';\n\n/**\n * Maps an ABI parameter type string (from abitype's `ParseAbiItem`) to the\n * closest `OutputKind`. When the ABI type is one of the supported `SolType`\n * scalars, the mapping is exact; for all other Solidity types (e.g. tuples,\n * fixed-point decimals) it falls back to `SolType` — accepting any scalar\n * handle but not `'resource'` handles.\n *\n * The fallback excludes `'resource'` because every Solidity type is a scalar;\n * resource handles carry token-amount semantics that should only flow into\n * slots explicitly declared as resources.\n *\n * Extending `SolType` with new members automatically widens the exact-match\n * branch — no changes needed here.\n */\nexport type AbiTypeToOutputKind<T extends string> = T extends SolType\n  ? T\n  : SolType;\n\n/**\n * A typed `$ref` pointer carrying a phantom type parameter.\n * Extends `Ref` so it is accepted anywhere a plain `Ref` is.\n * The `__outputKind` field is never set at runtime — it exists only\n * for TypeScript's structural type checker to distinguish typed refs.\n */\nexport interface TypedRef<T extends OutputKind = OutputKind> extends Ref {\n  readonly __outputKind?: T;\n}\n\n/**\n * A literal bind value carrying a phantom type parameter.\n *\n * The wire format accepts a constant in a bind slot as\n * `{ kind: <solType>, value: <string> }`, alongside `$ref` pointers. Use it\n * for a value that must be baked into the flow document rather than supplied\n * at run time — the destination of a flow the backend stores and re-runs\n * later (a `continuation.settle` node's `continuationFlow`) has no run to\n * take an input from.\n *\n * @typeParam T - The Solidity type of the literal (e.g. `'address'`).\n */\nexport interface TypedLiteral<\n  T extends SolType = SolType,\n> extends LiteralBinding {\n  readonly kind: T;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input declaration in a flow schema.\n * `Resource` values become resource inputs (token amounts);\n * `SolType` strings become handle inputs (scalars like addresses).\n */\nexport type InputDecl = Resource | SolType;\n\n/**\n * A record mapping input names to their declarations.\n * Used as the type parameter for generic flow builders and requests.\n */\nexport type InputSchema = Record<string, InputDecl>;\n\n/**\n * Maps an input declaration to the allowed runtime value type.\n * Resource inputs accept materialisers or literal amounts.\n * Handle inputs accept the scalar type matching their SolType.\n */\nexport type InputSpecOf<D> = D extends Resource\n  ? MaterialiserInput | IntegerStringInput\n  : D extends 'address'\n    ? Address\n    : D extends 'bool'\n      ? boolean\n      : D extends `${'u' | ''}int${string}`\n        ? IntegerStringInput\n        : D extends `bytes${string}`\n          ? `0x${string}`\n          : D extends 'string'\n            ? string\n            : InputSpec;\n\n/**\n * A guard applied to an operation, with the `port` field constrained\n * to a specific set of output port names.\n */\nexport interface TypedGuard<Port extends string = string> {\n  readonly kind: string;\n  readonly port: Port;\n  readonly [key: string]: unknown;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types.d.cts

@@ -1,4 +1,4 @@
-import { SolType, Ref, Resource, MaterialiserInput, InputSpec } from '@lifi/compose-spec';
+import { SolType, Ref, LiteralBinding, Resource, MaterialiserInput, InputSpec } from '@lifi/compose-spec';
 
 /**
  * A string that represents a non-negative integer (e.g. "1000000000").
@@ -44,6 +44,22 @@ type AbiTypeToOutputKind<T extends string> = T extends SolType ? T : SolType;
 interface TypedRef<T extends OutputKind = OutputKind> extends Ref {
     readonly __outputKind?: T;
 }
+/**
+ * A literal bind value carrying a phantom type parameter.
+ *
+ * The wire format accepts a constant in a bind slot as
+ * `{ kind: <solType>, value: <string> }`, alongside `$ref` pointers. Use it
+ * for a value that must be baked into the flow document rather than supplied
+ * at run time — the destination of a flow the backend stores and re-runs
+ * later (a `continuation.settle` node's `continuationFlow`) has no run to
+ * take an input from.
+ *
+ * @typeParam T - The Solidity type of the literal (e.g. `'address'`).
+ */
+interface TypedLiteral<T extends SolType = SolType> extends LiteralBinding {
+    readonly kind: T;
+    readonly __outputKind?: T;
+}
 /**
  * An input declaration in a flow schema.
  * `Resource` values become resource inputs (token amounts);
@@ -71,4 +87,4 @@ interface TypedGuard<Port extends string = string> {
     readonly [key: string]: unknown;
 }
 
-export type { AbiTypeToOutputKind, Address, InputDecl, InputSchema, InputSpecOf, IntegerString, IntegerStringInput, OutputKind, TypedGuard, TypedRef };
+export type { AbiTypeToOutputKind, Address, InputDecl, InputSchema, InputSpecOf, IntegerString, IntegerStringInput, OutputKind, TypedGuard, TypedLiteral, TypedRef };

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { SolType, Ref, Resource, MaterialiserInput, InputSpec } from '@lifi/compose-spec';
+import { SolType, Ref, LiteralBinding, Resource, MaterialiserInput, InputSpec } from '@lifi/compose-spec';
 
 /**
  * A string that represents a non-negative integer (e.g. "1000000000").
@@ -44,6 +44,22 @@ type AbiTypeToOutputKind<T extends string> = T extends SolType ? T : SolType;
 interface TypedRef<T extends OutputKind = OutputKind> extends Ref {
     readonly __outputKind?: T;
 }
+/**
+ * A literal bind value carrying a phantom type parameter.
+ *
+ * The wire format accepts a constant in a bind slot as
+ * `{ kind: <solType>, value: <string> }`, alongside `$ref` pointers. Use it
+ * for a value that must be baked into the flow document rather than supplied
+ * at run time — the destination of a flow the backend stores and re-runs
+ * later (a `continuation.settle` node's `continuationFlow`) has no run to
+ * take an input from.
+ *
+ * @typeParam T - The Solidity type of the literal (e.g. `'address'`).
+ */
+interface TypedLiteral<T extends SolType = SolType> extends LiteralBinding {
+    readonly kind: T;
+    readonly __outputKind?: T;
+}
 /**
  * An input declaration in a flow schema.
  * `Resource` values become resource inputs (token amounts);
@@ -71,4 +87,4 @@ interface TypedGuard<Port extends string = string> {
     readonly [key: string]: unknown;
 }
 
-export type { AbiTypeToOutputKind, Address, InputDecl, InputSchema, InputSpecOf, IntegerString, IntegerStringInput, OutputKind, TypedGuard, TypedRef };
+export type { AbiTypeToOutputKind, Address, InputDecl, InputSchema, InputSpecOf, IntegerString, IntegerStringInput, OutputKind, TypedGuard, TypedLiteral, TypedRef };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -28,9 +28,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "prettier": {
-    "singleQuote": true
-  },
   "scripts": {
     "build": "tsc --noEmit && tsup",
     "clean": "rm -rf dist out",
@@ -40,18 +37,16 @@
     "test": "vitest run --config vitest.config.ts",
     "check:types": "tsc --noEmit",
     "check:sdk-drift": "vitest run --config vitest.drift.config.ts",
-    "fix": "run-s fix:lint fix:prettier",
+    "fix": "yarn fix:lint",
     "fix:lint": "eslint src --fix",
-    "fix:prettier": "prettier \"src/**/*.ts\" \"scripts/**/*.ts\" --write",
     "lint": "eslint src",
     "test:lint": "eslint src",
-    "test:prettier": "prettier \"src/**/*.ts\" \"scripts/**/*.ts\" --list-different",
     "verify:staged": "bash scripts/verify-staged.sh",
     "example": "tsx src/examples/run.ts",
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.4.1"
+    "@lifi/compose-spec": "0.5.1"
   },
   "dependencies": {
     "abitype": "^1.2.3",
@@ -70,8 +65,6 @@
     "eslint-plugin-import": "^2.22.0",
     "eslint-plugin-require-extensions": "^0.1.3",
     "json-schema-to-typescript": "^15.0.4",
-    "npm-run-all": "^4.1.5",
-    "prettier": "^3.9.4",
     "tsup": "^8.5.1",
     "tsx": "^4.20.4",
     "typescript": "^6.0.3",

package/src/authoring/FlowBuilderCore.ts

@@ -1,9 +1,9 @@
 import type {
   AppliedGuard,
+  BindValue,
   Call,
   Flow,
   FlowInput,
-  Ref,
   Resource,
   SolType,
 } from '@lifi/compose-spec';
@@ -13,6 +13,7 @@ import type {
   InputSchema,
   OutputKind,
   TypedGuard,
+  TypedLiteral,
   TypedRef,
 } from '../types.js';
 
@@ -21,7 +22,7 @@ import type {
   OutputHandle,
   ResourceInputHandle,
 } from './handles.js';
-import { handleToRef } from './handles.js';
+import { toBindValue } from './handles.js';
 import { ref } from './raw.js';
 
 /**
@@ -37,17 +38,14 @@ export interface CallArgs {
 }
 
 /**
- * Any value that can be bound to an operation parameter: an input handle,
- * an output handle from a previous operation, or a typed `$ref` pointer.
+ * Any value that can be bound to an operation parameter: an input handle, an
+ * output handle from a previous operation, a typed `$ref` pointer, or a typed
+ * literal.
  *
- * Use `raw.ref<T>()` to create a typed ref from a raw path string.
+ * Use `raw.ref<T>()` to create a typed ref from a raw path string, and
+ * `raw.literal<T>()` to bake in a constant.
  */
-export type AnyBindable = InputHandle | OutputHandle | TypedRef;
-
-const toRef = (bindable: AnyBindable): Ref => {
-  if ('_tag' in bindable) return handleToRef(bindable);
-  return bindable;
-};
+export type AnyBindable = InputHandle | OutputHandle | TypedRef | TypedLiteral;
 
 /**
  * Provides references to runtime context values available inside a flow.
@@ -127,7 +125,7 @@ export interface FlowBuilderCore<T extends InputSchema = InputSchema> {
     id: string,
     op: string,
     args: {
-      readonly bind: Record<string, Ref>;
+      readonly bind: Record<string, BindValue>;
       readonly config: Record<string, unknown>;
       readonly guards?: readonly AppliedGuard[];
     },
@@ -196,9 +194,9 @@ export const createFlowBuilderCore = <T extends InputSchema>(
     if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
     nodeIds.add(nodeId);
 
-    const bind: Record<string, Ref> = {};
+    const bind: Record<string, BindValue> = {};
     for (const [key, val] of Object.entries(args.bind)) {
-      bind[key] = toRef(val);
+      bind[key] = toBindValue(val);
     }
 
     const node: Call = {
@@ -230,7 +228,7 @@ export const createFlowBuilderCore = <T extends InputSchema>(
     nodeId: string,
     op: string,
     args: {
-      readonly bind: Record<string, Ref>;
+      readonly bind: Record<string, BindValue>;
       readonly config: Record<string, unknown>;
       readonly guards?: readonly AppliedGuard[];
     },

package/src/authoring/handles.ts

@@ -1,6 +1,11 @@
-import type { Resource, StaticSolType } from '@lifi/compose-spec';
+import type {
+  BindValue,
+  Resource,
+  SolType,
+  StaticSolType,
+} from '@lifi/compose-spec';
 
-import type { OutputKind, TypedRef } from '../types.js';
+import type { OutputKind, TypedLiteral, TypedRef } from '../types.js';
 
 /**
  * A handle referencing a flow input declared in the flow's input schema.
@@ -75,16 +80,47 @@ type SlotAssignable<T extends OutputKind> = T extends 'bytes32'
     : T;
 
 /**
- * The set of values accepted by a typed bind slot.
+ * The values accepted by a typed slot that must resolve to a `$ref`:
  * - `OutputHandle<T>` / `InputHandle<T>` (same type)
  * - For `'uint256'` slots, also `'resource'`-tagged handles
  * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)
  * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)
  *
- * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
+ * Plain `{ $ref: '...' }` objects are **not** accepted - use `raw.ref<T>()`
  * to create a typed ref when you need to reference a raw path.
  */
-export type Bindable<T extends OutputKind> =
+export type RefBindable<T extends OutputKind> =
   | OutputHandle<SlotAssignable<T>>
   | InputHandle<SlotAssignable<T>>
   | TypedRef<SlotAssignable<T>>;
+
+/**
+ * Any ref-resolving bindable, with no per-slot type constraint.
+ */
+export type AnyRefBindable = InputHandle | OutputHandle | TypedRef;
+
+/**
+ * The set of values accepted by a typed operation bind slot: everything
+ * {@link RefBindable} accepts, plus a {@link TypedLiteral} constant baked
+ * into the flow document. A `'resource'` slot rejects a literal: a token
+ * resource is not a scalar constant.
+ *
+ * Use `raw.literal<T>()` to create one.
+ */
+export type Bindable<T extends OutputKind> =
+  RefBindable<T> | LiteralBindable<SlotAssignable<T>>;
+
+// Distributes over the slot's assignable kinds and keeps the scalar ones: a
+// `'resource'` slot has no scalar arm, so its literal arm collapses to
+// `never` and a literal is rejected outright.
+type LiteralBindable<K extends OutputKind> = K extends SolType
+  ? TypedLiteral<K>
+  : never;
+
+/**
+ * Converts a bindable to the wire `bind` value it denotes: handles become
+ * `$ref` pointers, refs and literals pass through as-is.
+ */
+export const toBindValue = (
+  bindable: InputHandle | OutputHandle | TypedRef | TypedLiteral,
+): BindValue => ('_tag' in bindable ? handleToRef(bindable) : bindable);

package/src/authoring/raw.ts

@@ -1,6 +1,6 @@
-import type { AppliedGuard } from '@lifi/compose-spec';
+import type { AppliedGuard, SolType } from '@lifi/compose-spec';
 
-import type { OutputKind, TypedRef } from '../types.js';
+import type { OutputKind, TypedLiteral, TypedRef } from '../types.js';
 
 /**
  * Creates a typed `$ref` pointer for use in bind slots.
@@ -39,6 +39,40 @@ export const ref = <T extends OutputKind>(path: string): TypedRef<T> => ({
   $ref: path,
 });
 
+/**
+ * Creates a typed literal for use in bind slots: a constant baked into the
+ * flow document rather than supplied at run time.
+ *
+ * Prefer a declared flow input and `builder.inputs.<name>` — a value the
+ * caller supplies per run stays out of the document. Use a literal when the
+ * flow has no run of its own to take the value from: the `continuationFlow`
+ * of a `continuation.settle` node is stored by the settlement backend and
+ * re-run later against the deferred proceeds, so its delivery address has to
+ * be part of the committed document.
+ *
+ * @typeParam T - The Solidity type of the literal (e.g. `'address'`).
+ * @param kind - The literal's Solidity type.
+ * @param value - The literal value, as the wire format carries it: a string.
+ * @returns A {@link TypedLiteral} accepted by `Bindable<T>` slots matching `T`.
+ *
+ * @example
+ * ```ts
+ * import { raw } from '@lifi/composer-sdk';
+ *
+ * builder.core.transfer('deliver', {
+ *   bind: {
+ *     amount: zap.amountOut,
+ *     recipient: raw.literal('address', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'),
+ *   },
+ *   config: {},
+ * });
+ * ```
+ */
+export const literal = <T extends SolType>(
+  kind: T,
+  value: string,
+): TypedLiteral<T> => ({ kind, value });
+
 /**
  * Creates a raw guard object for use in the `guards` array of an operation call.
  *

package/src/authoring/signatureArgs.ts

@@ -3,32 +3,36 @@ import { type ParseAbiItem, parseAbiItem } from 'abitype';
 
 import type { AbiTypeToOutputKind, TypedGuard } from '../types.js';
 
-import type { AnyBindable, CallArgs } from './FlowBuilderCore.js';
-import type { Bindable, OutputHandle } from './handles.js';
+import type { CallArgs } from './FlowBuilderCore.js';
+import type { AnyRefBindable, OutputHandle, RefBindable } from './handles.js';
 import { handleToRef } from './handles.js';
 
 /**
  * Type-level extraction of named bind keys from a function signature string.
  * When `TSig` is a string literal matching a Solidity function signature,
  * resolves to a record whose keys are the parameter names and values are
- * `Bindable<kind>` where the kind is derived from each parameter's Solidity
+ * `RefBindable<kind>` where the kind is derived from each parameter's Solidity
  * type via `AbiTypeToOutputKind`. For recognised `SolType` parameters
  * (e.g. `uint256`, `address`, `uint128`) the bind slot is precisely typed;
  * for other Solidity types (e.g. tuples) the slot accepts any scalar handle.
- * Falls back to `Record<string, AnyBindable>` for non-literal strings.
+ * Falls back to `Record<string, AnyRefBindable>` for non-literal strings.
+ *
+ * These slots are lowered into `config.args`, which is positional calldata
+ * rather than a node `bind` record, so a literal is not accepted here: only
+ * values that resolve to a `$ref`.
  */
 export type SignatureBind<TSig extends string> = string extends TSig
-  ? Record<string, AnyBindable>
+  ? Record<string, AnyRefBindable>
   : ParseAbiItem<TSig> extends {
         type: 'function';
         inputs: infer I extends readonly { name: string; type: string }[];
       }
     ? {
-        readonly [P in I[number] as P['name']]: Bindable<
+        readonly [P in I[number] as P['name']]: RefBindable<
           AbiTypeToOutputKind<P['type']>
         >;
       }
-    : Record<string, AnyBindable>;
+    : Record<string, AnyRefBindable>;
 
 // ---------------------------------------------------------------------------
 // Return-type inference from function signatures
@@ -126,18 +130,18 @@ export const parseFunctionParams = (functionSignature: string): string[] => {
 };
 
 /**
- * Converts any `AnyBindable` to a `Ref` (`{ $ref: string }`).
+ * Converts a ref-resolving bindable to a `Ref` (`{ $ref: string }`).
  * Handles carry a `_tag` property and are converted via `handleToRef`;
  * `Ref` objects pass through as-is.
  */
-export const toBindRef = (bindable: AnyBindable): Ref => {
+export const toBindRef = (bindable: AnyRefBindable): Ref => {
   if ('_tag' in bindable) return handleToRef(bindable);
   return bindable;
 };
 
 export interface BuildCallWireFormatInput {
-  readonly resource?: AnyBindable;
-  readonly bind: Record<string, AnyBindable>;
+  readonly resource?: AnyRefBindable;
+  readonly bind: Record<string, AnyRefBindable>;
   readonly config: Record<string, unknown>;
   readonly guards?: readonly TypedGuard[];
 }
@@ -155,7 +159,7 @@ export interface CallWireResult {
  */
 const resolvePositionalArgs = (
   label: string,
-  bind: Record<string, AnyBindable>,
+  bind: Record<string, AnyRefBindable>,
   config: Record<string, unknown>,
 ): Ref[] => {
   const functionSignature = config.functionSignature;
@@ -222,7 +226,7 @@ export const buildCallWireFormat = (
 };
 
 export interface BuildStaticCallWireFormatInput {
-  readonly bind: Record<string, AnyBindable>;
+  readonly bind: Record<string, AnyRefBindable>;
   readonly config: Record<string, unknown>;
   readonly guards?: readonly TypedGuard[];
 }