@lifi/composer-sdk 0.0.1-alpha

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright LI.FI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,220 @@
+# @lifi/composer-sdk
+
+TypeScript SDK for building and submitting LI.FI Compose flows.
+
+## Install
+
+`@lifi/compose-spec` is a peer dependency and must be installed alongside the SDK at the same version (they are versioned in lockstep).
+
+```bash
+npm install @lifi/composer-sdk @lifi/compose-spec
+```
+
+## Quick start
+
+Swap WETH to USDC, then zap the USDC into an Aave lending position — all in a single transaction.
+
+```ts
+import {
+  createComposeSdk,
+  resources,
+  guards,
+  materialisers,
+} from '@lifi/composer-sdk';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c'; // Aave aEthUSDC
+const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
+
+// Create the SDK pointed at the Compose API.
+const sdk = createComposeSdk({
+  baseUrl: 'https://compose.li.fi',
+  apiKey: process.env.LIFI_API_KEY, // optional
+});
+
+// Build a two-step flow on Ethereum mainnet.
+const builder = sdk.flow(1, {
+  name: 'swap-and-zap-weth-to-aave',
+  inputs: {
+    amountIn: resources.erc20(WETH, 1),
+  },
+});
+
+// Step 1: Swap WETH → USDC via LI.FI.
+const swapOutputs = builder.lifi.swap('swap', {
+  bind: { amountIn: builder.inputs.amountIn },
+  config: {
+    resourceOut: resources.erc20(USDC, 1),
+    slippage: 0.03,
+  },
+});
+
+// Step 2: Zap the swapped USDC into Aave.
+// The swap's amountOut handle threads directly into the zap's amountIn.
+builder.lifi.zap('zap', {
+  bind: { amountIn: swapOutputs.amountOut },
+  config: {
+    resourceOut: resources.erc20(A_ETH_USDC, 1),
+  },
+  guards: [guards.slippage({ port: 'amountOut', bps: 100 })],
+});
+
+const flow = builder.build();
+
+// Compile the flow into transaction calldata.
+const request = sdk.request(flow, {
+  signer: OWNER,
+  inputs: {
+    amountIn: materialisers.directDeposit({
+      amount: '1000000000000000000',
+    }),
+  },
+  sweepTo: builder.context.sender,
+});
+
+const result = await sdk.client.compile(request);
+
+if (result.status === 'success') {
+  // Full success — transactionRequest includes gasLimit.
+  console.log(result.transactionRequest);
+} else {
+  // result.status === 'partial' — simulation reverted.
+  // Transaction is still available but without gasLimit.
+  console.log(result.simulationRevert);
+}
+```
+
+## Core concepts
+
+**Flows and operations** — A flow is a sequence of on-chain operations. You declare inputs, chain operations together, and the backend compiles everything into a single transaction. Operations are namespaced (e.g., `builder.lifi.swap`, `builder.core.split`).
+
+**Resources** — `resources.erc20(address, chainId)` and `resources.native(chainId)` describe the tokens flowing through your operations. They carry chain and address metadata used for routing and validation.
+
+**Handles** — Operations produce typed output handles (e.g. `OutputHandle<'resource'>`, `OutputHandle<'uint256'>`) that you bind to downstream inputs. The type system enforces compatibility at compile time — a resource handle can flow into a `uint256` slot (since resources are amounts), but an `address` handle cannot.
+
+**Runtime inputs (materialisers)** — Materialisers resolve input values at execution time rather than at build time. `directDeposit` is exact by default when you provide an amount; pass `allowNonExact: true` to permit capped ERC-20 deposits or deposit-all behavior. `balanceOf` reads the wallet's current balance; `call` measures a balance delta after an arbitrary contract call.
+
+**Preconditions** — Expected on-chain state at execution time: `erc20Balance` and `nativeBalance` assert wallet holdings, `erc20Allowance` asserts token approvals.
+
+**Guards** — Protect against slippage and other runtime conditions. Applied per-operation via the `guards` field.
+
+## API surface
+
+**SDK factory**
+- `createComposeSdk({ baseUrl, fetch?, apiKey? })` — creates the SDK instance
+
+**Flow building**
+- `sdk.flow(chainId, options)` — creates a `FlowBuilder`
+- `builder.<namespace>.<operation>(id, { bind, config })` — adds an operation, returns typed `OutputHandle<T>` per port
+- `builder.untypedOp(id, op, args)` — escape hatch for operations not in the manifest (returns `void`; use `raw.ref<T>()` to reference its outputs)
+- `builder.build()` — produces a `Flow` document
+- `sdk.request(flow, { signer, inputs, preconditions, sweepTo, ... })` — builds a compile request
+
+**HTTP client**
+- `sdk.client.compile(request)` — sends the flow to the backend and returns a `ComposeCompileResult` (discriminated union: `status: 'success'` or `status: 'partial'`)
+- `sdk.client.getManifest()` — fetches the operation manifest
+
+**Helpers**
+- `resources.erc20(address, chainId)` / `resources.native(chainId)` — resource constructors
+- `guards.*` — guard factories (e.g., slippage)
+- `materialisers.*` — materialiser factories (directDeposit, balanceOf, call)
+- `preconditions.*` — precondition factories (erc20Balance, nativeBalance, erc20Allowance)
+- `raw.ref<T>(path)` — create a typed `$ref` pointer for use in bind slots (escape hatch for `untypedOp` outputs)
+- `raw.guard(kind, config?)` / `raw.materialiser(kind, config?)` — low-level factories for guards and materialisers
+
+## Simulation policy and partial results
+
+By default, the Compose backend simulates the compiled transaction and returns an error (HTTP 422) if simulation detects a revert. You can opt into receiving a **partial result** instead by passing `simulationPolicy: 'allow-revert'`:
+
+```ts
+const result = await builder.compile({
+  signer: OWNER,
+  inputs: { amountIn: materialisers.balanceOf({ owner: OWNER }) },
+  simulationPolicy: 'allow-revert',
+});
+
+if (result.status === 'success') {
+  // Simulation succeeded. transactionRequest includes gasLimit.
+  const tx = result.transactionRequest;
+  console.log(tx.gasLimit); // string
+} else {
+  // result.status === 'partial'
+  // Simulation reverted, but a transaction is still available (without gasLimit).
+  console.log(result.error.kind);    // 'simulation_revert'
+  console.log(result.error.message); // human-readable revert description
+
+  // Revert diagnostics
+  const revert = result.simulationRevert;
+  console.log(revert.code);          // e.g. 3
+  console.log(revert.rawErrorBytes); // raw ABI-encoded error
+
+  // Decoded error candidates (when available)
+  if (revert.decodeResult?.errorCandidates) {
+    for (const c of revert.decodeResult.errorCandidates) {
+      console.log(c.decodedErrorSignature, c.decodedParams);
+    }
+  }
+
+  // The transactionRequest is still usable — the caller must estimate gas themselves.
+  const tx = result.transactionRequest;
+  console.log(tx.to, tx.data, tx.value);
+}
+```
+
+The `simulationPolicy` field accepts two values:
+- `'strict'` (default) — revert causes a thrown `ComposeError` with code `VALIDATION_ERROR`
+- `'allow-revert'` — revert returns a partial result with `status: 'partial'`
+
+You can also pass `checkOnChainAllowances: true` to have the server filter the returned `approvals` array against current on-chain allowances, omitting approvals that are already sufficient:
+
+```ts
+const result = await builder.compile({
+  signer: OWNER,
+  inputs: { amountIn: materialisers.balanceOf({ owner: OWNER }) },
+  checkOnChainAllowances: true,
+});
+```
+
+## Error handling
+
+All SDK errors are thrown as `ComposeError` with a `code` property:
+
+```ts
+import { isComposeError } from '@lifi/composer-sdk';
+
+try {
+  const result = await sdk.client.compile(request);
+} catch (err) {
+  if (isComposeError(err)) {
+    console.error(err.code, err.message);
+    // Codes: VALIDATION_ERROR, SERVER_ERROR, RATE_LIMITED, NETWORK_ERROR, ...
+  }
+}
+```
+
+## Examples
+
+The `src/examples/` directory contains complete working examples:
+
+- **lifiSwap** — Single token swap (WETH to USDC)
+- **lifiZap** — Swap into a DeFi position
+- **swapAndZap** — Multi-step: swap then deposit
+- **splitAndZap** — Split a resource and zap each portion into a different vault
+- **splitWithArithmetic** — Split then verify with add/subtract/assertEqual assertions
+- **dustSweep** — Split and partially use tokens, sweep leftover dust back to sender
+- **depositFromProxy** — Read tokens already on the proxy via `balanceOf`, with a precondition guard
+- **approveAndDeposit** — Approve a vault, deposit, and graduate shares via `asResource`
+- **consolidateToUsdc** — Consolidate multiple tokens into USDC
+- **consolidateToEth** — Consolidate multiple tokens into ETH
+- **swapToRecipient** — Swap and send to a different address
+- **swapWithBalanceCheck** — Swap with balance precondition
+- **swapWithOutputValidation** — Swap with computed slippage bounds using bpsDown/bpsUp/assertInRange
+- **rawCallWithArithmetic** — Query a contract with pre-encoded calldata, then scale with multiply/divide
+- **readContractState** — Compare peek (compile-time), staticCall (execution-time), and balanceOf (resource)
+- **swapWithAllowRevert** — Swap with `simulationPolicy: 'allow-revert'` and handle the `ComposeCompileResult` discriminated union
+- **untypedOpWithTypedRef** — Insert an untyped operation node via `untypedOp`, then bridge its output into typed operations using `raw.ref<T>()`
+
+## License
+
+Apache-2.0

package/dist/authoring/FlowBuilderCore.cjs

@@ -0,0 +1,115 @@
+"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 FlowBuilderCore_exports = {};
+__export(FlowBuilderCore_exports, {
+  createFlowBuilderCore: () => createFlowBuilderCore
+});
+module.exports = __toCommonJS(FlowBuilderCore_exports);
+var import_handles = require("./handles.js");
+var import_raw = require("./raw.js");
+const toRef = (bindable) => {
+  if ("_tag" in bindable) return (0, import_handles.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: (0, import_raw.ref)("context.sender"),
+    executionAddress: (0, import_raw.ref)("context.executionAddress")
+  };
+  return {
+    context,
+    inputs: inputHandles,
+    call,
+    untypedOp,
+    build
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFlowBuilderCore
+});
+//# sourceMappingURL=FlowBuilderCore.cjs.map

package/dist/authoring/FlowBuilderCore.cjs.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/FlowBuilderCore.d.cts

@@ -0,0 +1,114 @@
+import { Resource, SolType, Ref, AppliedGuard, Flow } from '@lifi/compose-spec';
+import { TypedRef, InputSchema, InputDecl, TypedGuard, OutputKind } from '../types.cjs';
+import { InputHandle, OutputHandle, ResourceInputHandle } from './handles.cjs';
+
+/**
+ * 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 };