@lifi/compose-spec/README.md

Public wire-format types and schemas for Compose flows

# @lifi/compose-spec

Wire-format types and validation schemas for LI.FI Compose flows.

## Install

```bash
npm install @lifi/compose-spec
```

`@lifi/compose-spec` is published independently and is also a peer dependency of [`@lifi/composer-sdk`](https://www.npmjs.com/package/@lifi/composer-sdk). The two packages are versioned in lockstep — always install matching versions.

## What's included

- **Flow schema types** — `Flow`, `Call`, `Continuation`, `Ref`, `BindValue`, and related types that define the structure of a Compose flow document
- **Resource types** — `Resource`, `Availability`, plus helpers like `erc20Token`, `foldResource`, `resourceKey`
- **Output types** — `Outputs`, `Output`, `ConsumedOutput`, `TerminalOutput`, `Amount`, `Estimate`, `Minimum`, `Delivery`, `EstimateBasis`, `MinimumBasis` — the per-port `outputs` record on a compile result
- **Manifest types** — `ComposeManifest`, `ManifestOperation`, `ManifestGuard`, `ManifestMaterialiser`, `ManifestPrecondition`
- **Port types** — `ResourcePort`, `HandlePort`, `OpInputPort`, `OpOutputPort`, and type guards
- **Ref utilities** — `ref` to build bind refs (`ref.input('amount')`, `ref.context.sender`, `ref('nodeId.port')`), plus `parseRef`, `foldRef`, `refKey` for working with flow references
- **Constructors** — `linear`, `copy`, `handle`, `native`, `erc20`, `resource`, `readResource`, `opHandle`, `resourceOutput`
- **Zod schemas** — Runtime validation for manifests, ports, guards, and operations
- **Effect schemas** — `FlowSchema`, `ResourceSchema`, `CallSchema`, etc. for flow document validation

## Usage

Import types for your Compose tooling:

```ts
import type { Flow, Call, Resource, ComposeManifest } from '@lifi/compose-spec';
```

Validate a manifest at runtime with Zod:

```ts
import { ComposeManifestZod } from '@lifi/compose-spec';

const result = ComposeManifestZod.safeParse(rawManifest);
if (!result.success) {
  console.error(result.error);
}
```

## When to use this package

Use `@lifi/compose-spec` directly if you're building tooling around Compose flows — validators, visualizers, alternative SDKs, or server-side processors.

For building and submitting flows, use [`@lifi/composer-sdk`](https://www.npmjs.com/package/@lifi/composer-sdk) instead.

## License

Apache-2.0