@lifi/composer-sdk 0.0.1-alpha

package/dist/authoring/FlowBuilderCore.d.ts

@@ -0,0 +1,114 @@
+import { Resource, SolType, Ref, AppliedGuard, Flow } from '@lifi/compose-spec';
+import { TypedRef, InputSchema, InputDecl, TypedGuard, OutputKind } from '../types.js';
+import { InputHandle, OutputHandle, ResourceInputHandle } from './handles.js';
+
+/**
+ * Arguments for calling an operation node in a flow.
+ */
+interface CallArgs {
+    /** Maps parameter names to input/output handles or raw `$ref` pointers. */
+    readonly bind: Record<string, AnyBindable>;
+    /** Optional operation-specific configuration. */
+    readonly config?: object;
+    /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */
+    readonly guards?: readonly TypedGuard[];
+}
+/**
+ * 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.
+ *
+ * Use `raw.ref<T>()` to create a typed ref from a raw path string.
+ */
+type AnyBindable = InputHandle | OutputHandle | TypedRef;
+/**
+ * Provides references to runtime context values available inside a flow.
+ * Access via `builder.context`.
+ */
+interface ContextAccessor {
+    /** A `$ref` pointing to the transaction sender (signer) address. */
+    readonly sender: TypedRef<'address'>;
+    /** A `$ref` pointing to the on-chain execution (proxy) address. */
+    readonly executionAddress: TypedRef<'address'>;
+}
+type InputHandleOf<D extends InputDecl> = D extends Resource ? ResourceInputHandle : D extends SolType ? InputHandle<D> : InputHandle;
+/**
+ * A mapped type that converts an input schema into typed handles.
+ * Resource inputs produce {@link ResourceInputHandle}; scalar inputs produce {@link InputHandle}.
+ *
+ * @typeParam T - The flow's input schema.
+ */
+type InputHandles<T extends InputSchema> = {
+    readonly [K in keyof T]: InputHandleOf<T[K]>;
+};
+/**
+ * Options for creating a new flow builder.
+ *
+ * @typeParam T - The flow's input schema.
+ */
+interface FlowOptions<T extends InputSchema> {
+    /** Optional human-readable name for the flow. Defaults to a random UUID. */
+    readonly name?: string;
+    /** Input declarations mapping names to resource or scalar types. */
+    readonly inputs: T;
+}
+/**
+ * A Flow document branded with its input schema for type-safe request building.
+ *
+ * The `__inputs` field is a phantom type — it exists only at compile time for
+ * TypeScript inference and is never present at runtime.
+ */
+type TypedFlow<T extends InputSchema = InputSchema> = Flow & {
+    readonly __inputs?: T;
+};
+/**
+ * Core flow builder interface providing low-level access to flow construction.
+ *
+ * For most use cases, prefer the {@link FlowBuilder} type returned by `sdk.flow()`
+ * which adds generated operation methods and a `compile` method.
+ *
+ * @typeParam T - The flow's input schema.
+ */
+interface FlowBuilderCore<T extends InputSchema = InputSchema> {
+    /** Runtime context references (sender address, execution address). */
+    readonly context: ContextAccessor;
+    /** Typed handles for each declared flow input, used to bind inputs to operations. */
+    readonly inputs: InputHandles<T>;
+    /**
+     * Appends an untyped operation node to the flow. This is an escape hatch
+     * for operations not yet covered by the generated methods.
+     *
+     * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed
+     * operations.
+     *
+     * @param id - Unique node identifier within the flow.
+     * @param op - The operation name (e.g. `"custom.vaultQuery"`).
+     * @param args - Bind map, config, and optional guards for the node.
+     * @throws Error if a node with the same `id` already exists in the flow.
+     */
+    readonly untypedOp: (id: string, op: string, args: {
+        readonly bind: Record<string, Ref>;
+        readonly config: Record<string, unknown>;
+        readonly guards?: readonly AppliedGuard[];
+    }) => void;
+    /** Serialises the builder state into a {@link TypedFlow} document. */
+    readonly build: () => TypedFlow<T>;
+}
+/** Maps output port names to their output kind for compile-time and runtime validation. */
+type OutputSpec = Record<string, OutputKind>;
+/** Internal interface exposed to bindGeneratedOps — not part of the public API. */
+interface FlowBuilderInternal<T extends InputSchema = InputSchema> extends FlowBuilderCore<T> {
+    readonly call: <O extends OutputSpec>(nodeId: string, op: string, args: CallArgs, outputs: O) => {
+        readonly [K in keyof O & string]: OutputHandle<O[K]>;
+    };
+}
+/**
+ * Creates a new flow builder targeting the given chain.
+ *
+ * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).
+ * @param options - Flow configuration including input declarations.
+ * @returns A {@link FlowBuilderInternal} instance.
+ * @internal
+ */
+declare const createFlowBuilderCore: <T extends InputSchema>(chainId: number, options: FlowOptions<T>) => FlowBuilderInternal<T>;
+
+export { type AnyBindable, type CallArgs, type ContextAccessor, type FlowBuilderCore, type FlowBuilderInternal, type FlowOptions, type InputHandles, type OutputSpec, type TypedFlow, createFlowBuilderCore };

package/dist/authoring/FlowBuilderCore.js

@@ -0,0 +1,91 @@
+import { handleToRef } from "./handles.js";
+import { ref } from "./raw.js";
+const toRef = (bindable) => {
+  if ("_tag" in bindable) return handleToRef(bindable);
+  return bindable;
+};
+const isResource = (decl) => typeof decl === "object" && decl !== null && "kind" in decl;
+const createFlowBuilderCore = (chainId, options) => {
+  const id = options.name ?? crypto.randomUUID();
+  const flowInputs = [];
+  const nodes = [];
+  const nodeIds = /* @__PURE__ */ new Set();
+  const inputHandles = {};
+  for (const [name, decl] of Object.entries(options.inputs)) {
+    if (isResource(decl)) {
+      if (decl.chainId !== chainId) {
+        throw new Error(
+          `Input "${name}" has chainId ${decl.chainId} but flow targets chain ${chainId}`
+        );
+      }
+      flowInputs.push({ name, resource: decl });
+      inputHandles[name] = { _tag: "input", inputName: name, resource: decl };
+    } else {
+      flowInputs.push({ name, type: decl });
+      inputHandles[name] = { _tag: "input", inputName: name };
+    }
+  }
+  const call = (nodeId, op, args, outputs) => {
+    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
+    nodeIds.add(nodeId);
+    const bind = {};
+    for (const [key, val] of Object.entries(args.bind)) {
+      bind[key] = toRef(val);
+    }
+    const node = {
+      id: nodeId,
+      op,
+      bind,
+      config: args.config ?? {},
+      ...args.guards && args.guards.length > 0 && { guards: args.guards }
+    };
+    nodes.push(node);
+    return new Proxy({}, {
+      get: (_target, prop) => {
+        if (typeof prop !== "string" || prop === "then") return void 0;
+        if (!(prop in outputs)) {
+          throw new Error(
+            `Op "${op}" has no output port "${prop}". Valid ports: ${Object.keys(
+              outputs
+            ).join(", ")}`
+          );
+        }
+        return { _tag: "output", nodeId, portName: prop };
+      }
+    });
+  };
+  const untypedOp = (nodeId, op, args) => {
+    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
+    nodeIds.add(nodeId);
+    const node = {
+      id: nodeId,
+      op,
+      bind: args.bind,
+      config: args.config,
+      ...args.guards && args.guards.length > 0 && { guards: args.guards }
+    };
+    nodes.push(node);
+  };
+  const build = () => ({
+    version: 1,
+    id,
+    chainId,
+    inputs: [...flowInputs],
+    nodes: [...nodes]
+  });
+  const context = {
+    sender: ref("context.sender"),
+    executionAddress: ref("context.executionAddress")
+  };
+  return {
+    context,
+    inputs: inputHandles,
+    call,
+    untypedOp,
+    build
+  };
+};
+export {
+  createFlowBuilderCore
+};
+//# sourceMappingURL=FlowBuilderCore.js.map

package/dist/authoring/FlowBuilderCore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/authoring/FlowBuilderCore.ts"],"sourcesContent":["import type {\n  AppliedGuard,\n  Call,\n  Flow,\n  FlowInput,\n  Ref,\n  Resource,\n  SolType,\n} from '@lifi/compose-spec';\n\nimport type {\n  InputDecl,\n  InputSchema,\n  OutputKind,\n  TypedGuard,\n  TypedRef,\n} from '../types.js';\n\nimport type {\n  InputHandle,\n  OutputHandle,\n  ResourceInputHandle,\n} from './handles.js';\nimport { handleToRef } from './handles.js';\nimport { ref } from './raw.js';\n\n/**\n * Arguments for calling an operation node in a flow.\n */\nexport interface CallArgs {\n  /** Maps parameter names to input/output handles or raw `$ref` pointers. */\n  readonly bind: Record<string, AnyBindable>;\n  /** Optional operation-specific configuration. */\n  readonly config?: object;\n  /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */\n  readonly guards?: readonly TypedGuard[];\n}\n\n/**\n * Any value that can be bound to an operation parameter: an input handle,\n * an output handle from a previous operation, or a typed `$ref` pointer.\n *\n * Use `raw.ref<T>()` to create a typed ref from a raw path string.\n */\nexport type AnyBindable = InputHandle | OutputHandle | TypedRef;\n\nconst toRef = (bindable: AnyBindable): Ref => {\n  if ('_tag' in bindable) return handleToRef(bindable);\n  return bindable;\n};\n\n/**\n * Provides references to runtime context values available inside a flow.\n * Access via `builder.context`.\n */\nexport interface ContextAccessor {\n  /** A `$ref` pointing to the transaction sender (signer) address. */\n  readonly sender: TypedRef<'address'>;\n  /** A `$ref` pointing to the on-chain execution (proxy) address. */\n  readonly executionAddress: TypedRef<'address'>;\n}\n\ntype InputHandleOf<D extends InputDecl> = D extends Resource\n  ? ResourceInputHandle\n  : D extends SolType\n    ? InputHandle<D>\n    : InputHandle;\n\n/**\n * A mapped type that converts an input schema into typed handles.\n * Resource inputs produce {@link ResourceInputHandle}; scalar inputs produce {@link InputHandle}.\n *\n * @typeParam T - The flow's input schema.\n */\nexport type InputHandles<T extends InputSchema> = {\n  readonly [K in keyof T]: InputHandleOf<T[K]>;\n};\n\n/**\n * Options for creating a new flow builder.\n *\n * @typeParam T - The flow's input schema.\n */\nexport interface FlowOptions<T extends InputSchema> {\n  /** Optional human-readable name for the flow. Defaults to a random UUID. */\n  readonly name?: string;\n  /** Input declarations mapping names to resource or scalar types. */\n  readonly inputs: T;\n}\n\n/**\n * A Flow document branded with its input schema for type-safe request building.\n *\n * The `__inputs` field is a phantom type — it exists only at compile time for\n * TypeScript inference and is never present at runtime.\n */\nexport type TypedFlow<T extends InputSchema = InputSchema> = Flow & {\n  readonly __inputs?: T;\n};\n\n/**\n * Core flow builder interface providing low-level access to flow construction.\n *\n * For most use cases, prefer the {@link FlowBuilder} type returned by `sdk.flow()`\n * which adds generated operation methods and a `compile` method.\n *\n * @typeParam T - The flow's input schema.\n */\nexport interface FlowBuilderCore<T extends InputSchema = InputSchema> {\n  /** Runtime context references (sender address, execution address). */\n  readonly context: ContextAccessor;\n  /** Typed handles for each declared flow input, used to bind inputs to operations. */\n  readonly inputs: InputHandles<T>;\n  /**\n   * Appends an untyped operation node to the flow. This is an escape hatch\n   * for operations not yet covered by the generated methods.\n   *\n   * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed\n   * operations.\n   *\n   * @param id - Unique node identifier within the flow.\n   * @param op - The operation name (e.g. `\"custom.vaultQuery\"`).\n   * @param args - Bind map, config, and optional guards for the node.\n   * @throws Error if a node with the same `id` already exists in the flow.\n   */\n  readonly untypedOp: (\n    id: string,\n    op: string,\n    args: {\n      readonly bind: Record<string, Ref>;\n      readonly config: Record<string, unknown>;\n      readonly guards?: readonly AppliedGuard[];\n    },\n  ) => void;\n  /** Serialises the builder state into a {@link TypedFlow} document. */\n  readonly build: () => TypedFlow<T>;\n}\n\n/** Maps output port names to their output kind for compile-time and runtime validation. */\nexport type OutputSpec = Record<string, OutputKind>;\n\n/** Internal interface exposed to bindGeneratedOps — not part of the public API. */\nexport interface FlowBuilderInternal<\n  T extends InputSchema = InputSchema,\n> extends FlowBuilderCore<T> {\n  readonly call: <O extends OutputSpec>(\n    nodeId: string,\n    op: string,\n    args: CallArgs,\n    outputs: O,\n  ) => { readonly [K in keyof O & string]: OutputHandle<O[K]> };\n}\n\nconst isResource = (decl: InputDecl): decl is Resource =>\n  typeof decl === 'object' && decl !== null && 'kind' in decl;\n\n/**\n * Creates a new flow builder targeting the given chain.\n *\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 FlowBuilderInternal} instance.\n * @internal\n */\nexport const createFlowBuilderCore = <T extends InputSchema>(\n  chainId: number,\n  options: FlowOptions<T>,\n): FlowBuilderInternal<T> => {\n  const id = options.name ?? crypto.randomUUID();\n  const flowInputs: FlowInput[] = [];\n  const nodes: Call[] = [];\n  const nodeIds = new Set<string>();\n\n  const inputHandles = {} as Record<string, InputHandle | ResourceInputHandle>;\n  for (const [name, decl] of Object.entries(options.inputs)) {\n    if (isResource(decl)) {\n      if (decl.chainId !== chainId) {\n        throw new Error(\n          `Input \"${name}\" has chainId ${decl.chainId} but flow targets chain ${chainId}`,\n        );\n      }\n      flowInputs.push({ name, resource: decl });\n      inputHandles[name] = { _tag: 'input', inputName: name, resource: decl };\n    } else {\n      flowInputs.push({ name, type: decl });\n      inputHandles[name] = { _tag: 'input', inputName: name };\n    }\n  }\n\n  const call = <O extends OutputSpec>(\n    nodeId: string,\n    op: string,\n    args: CallArgs,\n    outputs: O,\n  ): { readonly [K in keyof O & string]: OutputHandle<O[K]> } => {\n    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: \"${nodeId}\"`);\n    nodeIds.add(nodeId);\n\n    const bind: Record<string, Ref> = {};\n    for (const [key, val] of Object.entries(args.bind)) {\n      bind[key] = toRef(val);\n    }\n\n    const node: Call = {\n      id: nodeId,\n      op,\n      bind,\n      config: (args.config ?? {}) as Record<string, unknown>,\n      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),\n    };\n    nodes.push(node);\n\n    type Result = { readonly [K in keyof O & string]: OutputHandle<O[K]> };\n    return new Proxy({} as Result, {\n      get: (_target, prop): OutputHandle | undefined => {\n        if (typeof prop !== 'string' || prop === 'then') return undefined;\n        if (!(prop in outputs)) {\n          throw new Error(\n            `Op \"${op}\" has no output port \"${prop}\". Valid ports: ${Object.keys(\n              outputs,\n            ).join(', ')}`,\n          );\n        }\n        return { _tag: 'output', nodeId, portName: prop };\n      },\n    });\n  };\n\n  const untypedOp = (\n    nodeId: string,\n    op: string,\n    args: {\n      readonly bind: Record<string, Ref>;\n      readonly config: Record<string, unknown>;\n      readonly guards?: readonly AppliedGuard[];\n    },\n  ): void => {\n    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: \"${nodeId}\"`);\n    nodeIds.add(nodeId);\n    const node: Call = {\n      id: nodeId,\n      op,\n      bind: args.bind,\n      config: args.config,\n      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),\n    };\n    nodes.push(node);\n  };\n\n  const build = (): TypedFlow<T> => ({\n    version: 1,\n    id,\n    chainId,\n    inputs: [...flowInputs],\n    nodes: [...nodes],\n  });\n\n  const context: ContextAccessor = {\n    sender: ref<'address'>('context.sender'),\n    executionAddress: ref<'address'>('context.executionAddress'),\n  };\n\n  return {\n    context,\n    inputs: inputHandles as InputHandles<T>,\n    call,\n    untypedOp,\n    build,\n  };\n};\n"],"mappings":"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","names":[]}

package/dist/authoring/handles.cjs

@@ -0,0 +1,43 @@
+"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 handles_exports = {};
+__export(handles_exports, {
+  handleToRef: () => handleToRef,
+  isInputHandle: () => isInputHandle,
+  isOutputHandle: () => isOutputHandle
+});
+module.exports = __toCommonJS(handles_exports);
+const isInputHandle = (h) => h._tag === "input";
+const isOutputHandle = (h) => h._tag === "output";
+const handleToRef = (h) => {
+  if (h._tag === "input") {
+    if (!h.inputName) throw new Error("InputHandle has empty inputName");
+    return { $ref: `input.${h.inputName}` };
+  }
+  if (!h.nodeId) throw new Error("OutputHandle has empty nodeId");
+  if (!h.portName) throw new Error("OutputHandle has empty portName");
+  return { $ref: `${h.nodeId}.${h.portName}` };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleToRef,
+  isInputHandle,
+  isOutputHandle
+});
+//# sourceMappingURL=handles.cjs.map

package/dist/authoring/handles.cjs.map

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

package/dist/authoring/handles.d.cts

@@ -0,0 +1,61 @@
+import { Resource } from '@lifi/compose-spec';
+import { OutputKind, TypedRef } from '../types.cjs';
+
+/**
+ * A handle referencing a flow input declared in the flow's input schema.
+ * The phantom `__outputKind` field carries the type parameter through
+ * TypeScript's structural type system without affecting runtime shape.
+ */
+interface InputHandle<T extends OutputKind = OutputKind> {
+    readonly _tag: 'input';
+    readonly inputName: string;
+    readonly __outputKind?: T;
+}
+/**
+ * An input handle for a resource (token) input, carrying the resource
+ * declaration alongside the reference.
+ */
+interface ResourceInputHandle extends InputHandle<'resource'> {
+    readonly resource: Resource;
+}
+/**
+ * A handle referencing an output port of a previously declared operation node.
+ * The phantom `__outputKind` field carries the type parameter through
+ * TypeScript's structural type system without affecting runtime shape.
+ */
+interface OutputHandle<T extends OutputKind = OutputKind> {
+    readonly _tag: 'output';
+    readonly nodeId: string;
+    readonly portName: string;
+    readonly __outputKind?: T;
+}
+/** Discriminated union of all handle types that can be bound to operation arguments. */
+type AnyHandle = InputHandle | OutputHandle;
+/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */
+declare const isInputHandle: (h: AnyHandle) => h is InputHandle;
+/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */
+declare const isOutputHandle: (h: AnyHandle) => h is OutputHandle;
+/**
+ * Converts a handle to a JSON `$ref` pointer used in the flow document.
+ * Input handles become `"input.<name>"`; output handles become `"<nodeId>.<port>"`.
+ */
+declare const handleToRef: (h: AnyHandle) => {
+    $ref: string;
+};
+/**
+ * For a bind slot expecting type T, also accept `'resource'`-tagged
+ * handles when T is `'uint256'` (resources are uint256 amounts).
+ */
+type ResourceAssignable<T extends OutputKind> = T extends 'uint256' ? T | 'resource' : T;
+/**
+ * The set of values accepted by a typed bind slot.
+ * - `OutputHandle<T>` / `InputHandle<T>` (same type)
+ * - For `'uint256'` slots, also `'resource'`-tagged handles
+ * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)
+ *
+ * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
+ * to create a typed ref when you need to reference a raw path.
+ */
+type Bindable<T extends OutputKind> = OutputHandle<ResourceAssignable<T>> | InputHandle<ResourceAssignable<T>> | TypedRef<ResourceAssignable<T>>;
+
+export { type AnyHandle, type Bindable, type InputHandle, type OutputHandle, type ResourceInputHandle, handleToRef, isInputHandle, isOutputHandle };

package/dist/authoring/handles.d.ts

@@ -0,0 +1,61 @@
+import { Resource } from '@lifi/compose-spec';
+import { OutputKind, TypedRef } from '../types.js';
+
+/**
+ * A handle referencing a flow input declared in the flow's input schema.
+ * The phantom `__outputKind` field carries the type parameter through
+ * TypeScript's structural type system without affecting runtime shape.
+ */
+interface InputHandle<T extends OutputKind = OutputKind> {
+    readonly _tag: 'input';
+    readonly inputName: string;
+    readonly __outputKind?: T;
+}
+/**
+ * An input handle for a resource (token) input, carrying the resource
+ * declaration alongside the reference.
+ */
+interface ResourceInputHandle extends InputHandle<'resource'> {
+    readonly resource: Resource;
+}
+/**
+ * A handle referencing an output port of a previously declared operation node.
+ * The phantom `__outputKind` field carries the type parameter through
+ * TypeScript's structural type system without affecting runtime shape.
+ */
+interface OutputHandle<T extends OutputKind = OutputKind> {
+    readonly _tag: 'output';
+    readonly nodeId: string;
+    readonly portName: string;
+    readonly __outputKind?: T;
+}
+/** Discriminated union of all handle types that can be bound to operation arguments. */
+type AnyHandle = InputHandle | OutputHandle;
+/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */
+declare const isInputHandle: (h: AnyHandle) => h is InputHandle;
+/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */
+declare const isOutputHandle: (h: AnyHandle) => h is OutputHandle;
+/**
+ * Converts a handle to a JSON `$ref` pointer used in the flow document.
+ * Input handles become `"input.<name>"`; output handles become `"<nodeId>.<port>"`.
+ */
+declare const handleToRef: (h: AnyHandle) => {
+    $ref: string;
+};
+/**
+ * For a bind slot expecting type T, also accept `'resource'`-tagged
+ * handles when T is `'uint256'` (resources are uint256 amounts).
+ */
+type ResourceAssignable<T extends OutputKind> = T extends 'uint256' ? T | 'resource' : T;
+/**
+ * The set of values accepted by a typed bind slot.
+ * - `OutputHandle<T>` / `InputHandle<T>` (same type)
+ * - For `'uint256'` slots, also `'resource'`-tagged handles
+ * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)
+ *
+ * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
+ * to create a typed ref when you need to reference a raw path.
+ */
+type Bindable<T extends OutputKind> = OutputHandle<ResourceAssignable<T>> | InputHandle<ResourceAssignable<T>> | TypedRef<ResourceAssignable<T>>;
+
+export { type AnyHandle, type Bindable, type InputHandle, type OutputHandle, type ResourceInputHandle, handleToRef, isInputHandle, isOutputHandle };

package/dist/authoring/handles.js

@@ -0,0 +1,17 @@
+const isInputHandle = (h) => h._tag === "input";
+const isOutputHandle = (h) => h._tag === "output";
+const handleToRef = (h) => {
+  if (h._tag === "input") {
+    if (!h.inputName) throw new Error("InputHandle has empty inputName");
+    return { $ref: `input.${h.inputName}` };
+  }
+  if (!h.nodeId) throw new Error("OutputHandle has empty nodeId");
+  if (!h.portName) throw new Error("OutputHandle has empty portName");
+  return { $ref: `${h.nodeId}.${h.portName}` };
+};
+export {
+  handleToRef,
+  isInputHandle,
+  isOutputHandle
+};
+//# sourceMappingURL=handles.js.map

package/dist/authoring/handles.js.map

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

package/dist/authoring/raw.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 raw_exports = {};
+__export(raw_exports, {
+  rawGuard: () => rawGuard,
+  ref: () => ref
+});
+module.exports = __toCommonJS(raw_exports);
+const ref = (path) => ({ $ref: path });
+const rawGuard = (kind, config = {}) => {
+  if ("kind" in config) {
+    throw new Error(
+      `rawGuard: 'kind' must not appear in config (got "${String(
+        config.kind
+      )}"). Pass it as the first argument instead.`
+    );
+  }
+  return { ...config, kind };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  rawGuard,
+  ref
+});
+//# sourceMappingURL=raw.cjs.map

package/dist/authoring/raw.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/authoring/raw.ts"],"sourcesContent":["import type { AppliedGuard } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * Creates a typed `$ref` pointer for use in bind slots.\n *\n * This is an **escape hatch** for referencing values that the typed builder\n * API doesn't cover — for example, outputs of an `untypedOp` node or custom\n * context paths. The caller is responsible for choosing the correct type\n * parameter; no runtime validation occurs.\n *\n * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`\n * whenever possible. Use `ref` only when you need to construct a `$ref` path\n * manually and want it accepted by a `Bindable<T>` slot.\n *\n * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).\n * @param path - The `$ref` path (e.g. `\"context.sender\"`, `\"myNode.result\"`).\n * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.\n *\n * @example\n * ```ts\n * import { raw } from '@lifi/composer-sdk';\n *\n * // Reference an untypedOp output in a typed operation:\n * builder.untypedOp('custom', 'some.op', {\n *   bind: { x: { $ref: 'input.token' } },\n *   config: {},\n * });\n * builder.core.add('sum', {\n *   bind: {\n *     a: raw.ref<'uint256'>('custom.result'),\n *     b: someTypedHandle,\n *   },\n * });\n * ```\n */\nexport const ref = <T extends OutputKind>(path: string): TypedRef<T> =>\n  ({ $ref: path }) as TypedRef<T>;\n\n/**\n * Creates a raw guard object for use in the `guards` array of an operation call.\n *\n * @param kind - The guard type (e.g. `\"slippage\"`).\n * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).\n * @returns An {@link AppliedGuard} object.\n */\nexport const rawGuard = (\n  kind: string,\n  config: Record<string, unknown> = {},\n): AppliedGuard => {\n  if ('kind' in config) {\n    throw new Error(\n      `rawGuard: 'kind' must not appear in config (got \"${String(\n        config.kind,\n      )}\"). Pass it as the first argument instead.`,\n    );\n  }\n  return { ...config, kind };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqCO,MAAM,MAAM,CAAuB,UACvC,EAAE,MAAM,KAAK;AAST,MAAM,WAAW,CACtB,MACA,SAAkC,CAAC,MAClB;AACjB,MAAI,UAAU,QAAQ;AACpB,UAAM,IAAI;AAAA,MACR,oDAAoD;AAAA,QAClD,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,KAAK;AAC3B;","names":[]}

package/dist/authoring/raw.d.cts

@@ -0,0 +1,47 @@
+import { AppliedGuard } from '@lifi/compose-spec';
+import { OutputKind, TypedRef } from '../types.cjs';
+
+/**
+ * Creates a typed `$ref` pointer for use in bind slots.
+ *
+ * This is an **escape hatch** for referencing values that the typed builder
+ * API doesn't cover — for example, outputs of an `untypedOp` node or custom
+ * context paths. The caller is responsible for choosing the correct type
+ * parameter; no runtime validation occurs.
+ *
+ * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`
+ * whenever possible. Use `ref` only when you need to construct a `$ref` path
+ * manually and want it accepted by a `Bindable<T>` slot.
+ *
+ * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).
+ * @param path - The `$ref` path (e.g. `"context.sender"`, `"myNode.result"`).
+ * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.
+ *
+ * @example
+ * ```ts
+ * import { raw } from '@lifi/composer-sdk';
+ *
+ * // Reference an untypedOp output in a typed operation:
+ * builder.untypedOp('custom', 'some.op', {
+ *   bind: { x: { $ref: 'input.token' } },
+ *   config: {},
+ * });
+ * builder.core.add('sum', {
+ *   bind: {
+ *     a: raw.ref<'uint256'>('custom.result'),
+ *     b: someTypedHandle,
+ *   },
+ * });
+ * ```
+ */
+declare const ref: <T extends OutputKind>(path: string) => TypedRef<T>;
+/**
+ * Creates a raw guard object for use in the `guards` array of an operation call.
+ *
+ * @param kind - The guard type (e.g. `"slippage"`).
+ * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).
+ * @returns An {@link AppliedGuard} object.
+ */
+declare const rawGuard: (kind: string, config?: Record<string, unknown>) => AppliedGuard;
+
+export { rawGuard, ref };

package/dist/authoring/raw.d.ts

@@ -0,0 +1,47 @@
+import { AppliedGuard } from '@lifi/compose-spec';
+import { OutputKind, TypedRef } from '../types.js';
+
+/**
+ * Creates a typed `$ref` pointer for use in bind slots.
+ *
+ * This is an **escape hatch** for referencing values that the typed builder
+ * API doesn't cover — for example, outputs of an `untypedOp` node or custom
+ * context paths. The caller is responsible for choosing the correct type
+ * parameter; no runtime validation occurs.
+ *
+ * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`
+ * whenever possible. Use `ref` only when you need to construct a `$ref` path
+ * manually and want it accepted by a `Bindable<T>` slot.
+ *
+ * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).
+ * @param path - The `$ref` path (e.g. `"context.sender"`, `"myNode.result"`).
+ * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.
+ *
+ * @example
+ * ```ts
+ * import { raw } from '@lifi/composer-sdk';
+ *
+ * // Reference an untypedOp output in a typed operation:
+ * builder.untypedOp('custom', 'some.op', {
+ *   bind: { x: { $ref: 'input.token' } },
+ *   config: {},
+ * });
+ * builder.core.add('sum', {
+ *   bind: {
+ *     a: raw.ref<'uint256'>('custom.result'),
+ *     b: someTypedHandle,
+ *   },
+ * });
+ * ```
+ */
+declare const ref: <T extends OutputKind>(path: string) => TypedRef<T>;
+/**
+ * Creates a raw guard object for use in the `guards` array of an operation call.
+ *
+ * @param kind - The guard type (e.g. `"slippage"`).
+ * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).
+ * @returns An {@link AppliedGuard} object.
+ */
+declare const rawGuard: (kind: string, config?: Record<string, unknown>) => AppliedGuard;
+
+export { rawGuard, ref };

package/dist/authoring/raw.js

@@ -0,0 +1,16 @@
+const ref = (path) => ({ $ref: path });
+const rawGuard = (kind, config = {}) => {
+  if ("kind" in config) {
+    throw new Error(
+      `rawGuard: 'kind' must not appear in config (got "${String(
+        config.kind
+      )}"). Pass it as the first argument instead.`
+    );
+  }
+  return { ...config, kind };
+};
+export {
+  rawGuard,
+  ref
+};
+//# sourceMappingURL=raw.js.map

package/dist/authoring/raw.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/authoring/raw.ts"],"sourcesContent":["import type { AppliedGuard } from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedRef } from '../types.js';\n\n/**\n * Creates a typed `$ref` pointer for use in bind slots.\n *\n * This is an **escape hatch** for referencing values that the typed builder\n * API doesn't cover — for example, outputs of an `untypedOp` node or custom\n * context paths. The caller is responsible for choosing the correct type\n * parameter; no runtime validation occurs.\n *\n * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`\n * whenever possible. Use `ref` only when you need to construct a `$ref` path\n * manually and want it accepted by a `Bindable<T>` slot.\n *\n * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).\n * @param path - The `$ref` path (e.g. `\"context.sender\"`, `\"myNode.result\"`).\n * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.\n *\n * @example\n * ```ts\n * import { raw } from '@lifi/composer-sdk';\n *\n * // Reference an untypedOp output in a typed operation:\n * builder.untypedOp('custom', 'some.op', {\n *   bind: { x: { $ref: 'input.token' } },\n *   config: {},\n * });\n * builder.core.add('sum', {\n *   bind: {\n *     a: raw.ref<'uint256'>('custom.result'),\n *     b: someTypedHandle,\n *   },\n * });\n * ```\n */\nexport const ref = <T extends OutputKind>(path: string): TypedRef<T> =>\n  ({ $ref: path }) as TypedRef<T>;\n\n/**\n * Creates a raw guard object for use in the `guards` array of an operation call.\n *\n * @param kind - The guard type (e.g. `\"slippage\"`).\n * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).\n * @returns An {@link AppliedGuard} object.\n */\nexport const rawGuard = (\n  kind: string,\n  config: Record<string, unknown> = {},\n): AppliedGuard => {\n  if ('kind' in config) {\n    throw new Error(\n      `rawGuard: 'kind' must not appear in config (got \"${String(\n        config.kind,\n      )}\"). Pass it as the first argument instead.`,\n    );\n  }\n  return { ...config, kind };\n};\n"],"mappings":"AAqCO,MAAM,MAAM,CAAuB,UACvC,EAAE,MAAM,KAAK;AAST,MAAM,WAAW,CACtB,MACA,SAAkC,CAAC,MAClB;AACjB,MAAI,UAAU,QAAQ;AACpB,UAAM,IAAI;AAAA,MACR,oDAAoD;AAAA,QAClD,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,KAAK;AAC3B;","names":[]}