@loqate/compose/README.md

Loqate Compose SDK — high-level flows that compose base API clients into easy-to-use sessions.

# IN ALPHA - NOT CURRENTLY FOR RELEASE

<div align="left">
    <a href="https://opensource.org/licenses/MIT">
        <img src="https://img.shields.io/badge/License-MIT-blue.svg" style="width: 100px; height: 28px;" />
    </a>
</div>

# @loqate/compose

High‑level, _compose_ SDK for Loqate. It orchestrates common address flows (capture → select → verify) on top of lower‑level clients.

```ts
import { AddressSession } from "@loqate/compose";
import { avcParser } from "@loqate/compose/utils";
```

## Install

```bash
npm i @loqate/compose
# or
pnpm add @loqate/compose
```

> Node 18+ (or modern bundlers/browsers) recommended.

## Quick start

```ts
import { AddressSession } from "@loqate/compose";

const session = new AddressSession({
  baseUrl: "https://api.addressy.com",
  apiKey: process.env.LOQATE_API_KEY!,
});

await session.start();

const results = await session.suggest("10 downing st, london");
const chosen = await session.select(results[0].id);

const verified = await session.verify(chosen.address);

console.log(verified.avc); // e.g. "AVC=R"
```

### Utils

```ts
import { avcParser } from "@loqate/compose/utils";

const parsed = avcParser("AVC=R;DPV=Y;...");
// => structured object; tolerant to unknown tokens
```

## Design

- **AddressSession**: a lightweight stateful orchestrator exposing a friendly API.
- **Transport‑agnostic**: bring your own `fetch` if needed.
- **Tree‑shakeable**: `sideEffects: false`, ESM first with CJS fallback.
- **Typed**: full d.ts output.

You can inject real, generated clients later:

```ts
new AddressSession({ clients: { capture, verify } });
```

## License

MIT