npm package: @lucid-dreams/client
Description: @lucid/client — API + A2A Hub Client
Latest version: 0.2.24

@lucid/client — API + A2A Hub Client

Overview
- Typed helpers and schemas for the server API.
- Thin A2A hub client to interoperate with registered agents by `agentRef`.

A2A Hub Client
- Import: `import { A2AHubClient } from '@lucid/client'`.
- Construct with your API base URL and optional headers or API key.

Using x402-fetch for payments
- Install: `x402-fetch`
- Example:
  import { createSigner, wrapFetchWithPayment } from 'x402-fetch';
  const signer = await createSigner('base-sepolia', process.env.PRIVATE_KEY!);
  const paidFetch = wrapFetchWithPayment(fetch, signer);
  const client = new A2AHubClient('http://localhost:8787', { fetch: paidFetch });
  // Headers added by x402-fetch are forwarded by the hub to target agents

Paid client helper
- Import: `import { createPaidA2AHubClient } from '@lucid/client'`.
- Example:
  const client = await createPaidA2AHubClient({
    hubUrl: 'http://localhost:8787',
    privateKey: process.env.PRIVATE_KEY!,
    network: process.env.PAYMENT_NETWORK || process.env.NETWORK || 'base-sepolia',
  });
  // Same API as A2AHubClient
  await client.sendMessage({ agentRef: 'echo-agent', skillId: 'echo', input: { text: 'hi' } });

Examples
- Get agent card:
  const client = new A2AHubClient('http://localhost:8787', { apiKey: process.env.API_KEY });
  const card = await client.getCard('echo-agent');

- Send a non-streaming task:
  const task = await client.sendMessage({ agentRef: 'echo-agent', skillId: 'echo', input: { text: 'hello' } });
  // task.kind === 'task'; task.status.state in ['completed','failed','unknown']

- Stream a task:
  const ac = new AbortController();
  try {
    for await (const evt of client.sendMessageStream({ agentRef: 'echo-agent', skillId: 'echo', input: { text: 'stream me' }, signal: ac.signal })) {
      if (evt.kind === 'task') console.log('task opened', evt.id);
      else if (evt.kind === 'status-update') console.log('status', evt.status.state, evt.status.message?.parts?.[0]?.text);
    }
  } finally {
    ac.abort();
  }

Notes
- `skillId` is optional if the agent only advertises a single entrypoint.
- Streaming yields a `task` first, then `status-update` events until a final update (`final: true`).
- Errors in the stream are thrown by the iterator; wrap in try/catch.
- Payments (x402): pass your `x-402-*` headers via the client constructor, e.g. `new A2AHubClient(url, { headers: { 'x-402-token': '...', 'x-402-signature': '...' } })`. The hub forwards these to the target agent.

Node paid demo
- A runnable script is included at `apps/examples/a2a/paid-demo.ts` that:
  - Fetches an agent card via the hub
  - Sends an A2A RPC task (non-stream)
  - Invokes and streams via direct hub endpoints with x402 payments (headers auto-managed by x402-fetch)

Run (Bun):

```
HUB_URL=http://localhost:8787 \
AGENT_REF=echo-agent \
SKILL_ID=echo \
NETWORK=base-sepolia \
PRIVATE_KEY=0x... \
bun run apps/examples/a2a/paid-demo.ts
```

Notes:
- For paid flows, ensure the target agent is configured with x402 (payee address, network, facilitator).
- The demo prints `x-payment-response` when present; 402 challenges are handled by x402-fetch when using the direct endpoints.