hivecast-sdk/packages/sdk/README.md

# @open-matrix/sdk

Public Matrix actor SDK facade for package authors.

Prefer narrow package imports when a package only needs one layer:

```ts
import { MatrixActor } from '@open-matrix/core';
```

Use this umbrella package when a package intentionally needs the combined actor,
browser host, contracts, federation, and Omega kernel facade.

Import browser app build utilities directly from `@open-matrix/browser-kit` so
headless actor packages can import `@open-matrix/sdk` without loading
browser-only custom element code.

## HiveCast-Managed Transport

For HiveCast-backed actors, use a HiveCast API key to exchange for short-lived
actor-scoped NATS credentials:

```ts
import { exchangeHiveCastActorCredential } from '@open-matrix/sdk';

const credential = await exchangeHiveCastActorCredential({
  cloud: process.env.MATRIX_CLOUD!,
  space: process.env.MATRIX_SPACE!,
  apiKey: process.env.MATRIX_API_KEY!,
}, {
  mount: 'fresh.server.echo',
  accepts: { echo: { description: 'Echo a message', message: 'string' } },
});
```

The exchange returns NATS URLs plus a JWT/seed pair for the requested mount.
Server actors use `NatsTransport` with `credential.transport.natsUrl`; browser
actors use `createBrowserNatsTransport` with
`credential.transport.natsWsUrl`.

Runnable demos:

- `demos/fresh-server-actor`
- `demos/fresh-web-page`

Proof:

```bash
MATRIX_CLOUD=https://<your-hivecast-cloud> \
MATRIX_SPACE=<your-space-root> \
MATRIX_API_KEY=<your-hivecast-api-key> \
pnpm run prove:fresh-samples
```