# @syncropel/sdk

TypeScript SDK for the [Syncropel](https://syncropel.com) protocol — emit content-addressed records, query threads, validate grammar, fail open on transport errors.

```typescript
import { Client, Identity, Ref } from "@syncropel/sdk";

const client = new Client({
  endpoint: "http://localhost:9100",
  identity: Identity.static("did:example:my-app"),
});

const result = await client.emit({
  act: "PUT",
  kind: "music.catalog.track",
  body: { title: "Glow", artists: ["Zonke"] },
  refs: [Ref.musicTrack({ isrc: "USJI19810404" })],
  thread: "music.library",
});

console.log(result.success, result.recordId);
```

One call validates the grammar, builds the record envelope, retries on transient errors, and resolves cleanly on transport failures so a flaky network never crashes your handler.

---

## Features

- **Async client** — `emit`, `query`, `queryThread`, `subscribe`, `intend`, `fulfill`, plus reserved-kind helpers
- **Grammar enforcement** — `body.kind` validated before any network call
- **Canonical references** — 11 community ref constructors (`@music.track`, `@code.file`, `@social.person`, …) for cross-publisher correlation
- **Fail-open transport** — every emit resolves to a result; transport errors never reject the promise
- **Identity-aware** — every record signed with the configured DID
- **Zero runtime dependencies** — uses the platform `fetch`
- **Universal runtime** — Node 18+, Deno, Bun, Cloudflare Workers, modern browsers
- **In-memory `MockKernel`** for tests at `@syncropel/sdk/testing` — no server needed

---

## Install

```bash
npm install @syncropel/sdk
```

| Runtime | Minimum |
|---|---|
| Node.js | 18 (built-in `fetch` + `AbortController`) |
| Deno | 1.30+ |
| Bun | 1.0+ |
| Cloudflare Workers | anywhere `fetch` is available |
| Modern browsers | anywhere `fetch` is available |

Ships compiled JavaScript + TypeScript declarations. ESM only.

---

## Quickstart

Spin up a local Syncropel server, then emit your first record:

```typescript
// hello.ts
import { Client, Identity, Ref } from "@syncropel/sdk";

const client = new Client({
  endpoint: "http://localhost:9100",
  identity: Identity.static("did:example:me"),
});

const result = await client.emit({
  act: "PUT",
  kind: "music.catalog.track",
  body: { title: "Glow" },
  refs: [Ref.musicTrack({ isrc: "USJI19810404" })],
  thread: "music.library",
});
console.log("emitted:", result.recordId);

const records = await client.queryThread({ thread: "music.library" });
console.log(`thread has ${records.length} record(s)`);
```

```bash
npx tsx hello.ts
```

See [syncropel.com](https://syncropel.com) for installing the Syncropel server (`spl`) and a full hosted-vs-local guide.

---

## Concepts in 60 seconds

- **Record** — the immutable, content-addressed unit. 8 fields; the SDK builds the envelope for you.
- **Kind** — `body.kind` names what the record is about, e.g. `music.catalog.track`. Follows a strict grammar: `scope.category.entity[.version]`.
- **Thread** — a logical conversation / workflow. Records share a thread when they're part of the same activity.
- **Actor** — who emitted the record, expressed as a [DID](https://www.w3.org/TR/did-core/).
- **Ref** — a canonical pointer to a real-world entity (a song, a file, a person…) so records about the same thing correlate across apps.

---

## API reference

### `Client`

| Method | Purpose |
|---|---|
| `emit({ act, kind, body, thread, refs?, parents?, dataType?, clock? })` | Primary emit. Returns `Promise<EmitResult>`. Grammar errors throw; transport errors resolve to `success: false`. |
| `intend({ goal, thread?, parents?, kind?, body?, clock? })` | Open a thread. Emits `INTEND`. Generates a random thread id if none supplied; returns it on `result.thread`. |
| `fulfill({ thread, summary, fulfills?, kind?, body?, parents?, clock? })` | Close a thread. Emits `KNOW` with `body.summary` + optional `body.fulfills` (id or list of ids). |
| `emitCorrection({ corrects, revisedFields, reason, thread, ... })` | Reserved-kind helper for `core.correction` — supersede earlier records with revised values. |
| `emitErasure({ erases, reason, thread, ... })` | Reserved-kind helper for `core.erasure` — mark records as erased (e.g. for compliance). |
| `emitAlias({ oldKind, newKind, reason, thread, ... })` | Reserved-kind helper for `core.alias` — declare that one kind supersedes another. |
| `emitScopeTransfer({ scope, fromPublisher, toPublisher, reason, thread, ... })` | Reserved-kind helper for `core.scope_transfer` — record ownership of a scope changing publisher. |
| `emitScopeClaim({ scope, governancePolicy, thread, ... })` | Reserved-kind helper for `core.scope_claim` — claim a scope with a governance policy. |
| `queryThread({ thread, limit?, since? })` | All records in a thread. Fail-open. |
| `query({ kind?, actor?, thread?, since?, limit?, where? })` | Filtered query. At least one of `kind` / `actor` / `thread` required. |
| `subscribe(thread, callback, options?)` | Live record subscription via SSE. Returns a `Subscription` handle (`close()`, `cursor`, `closed`). Auto-reconnects with exponential backoff + jitter; resumes from last cursor. See `examples/subscribe.ts`. |
| `health()` | Server health probe. Fail-open. |

Constructor options: `endpoint` (string), `identity` (required), `timeoutMs` (default `30000`), `maxRetries` (default `2`), `backoffMs` (default `250`), `onEmit` (observability hook), `apiKey` (sets `x-api-key` header), `fetch` (custom transport — useful for tests, proxies, observability wrappers).

### Namespaces

Beyond the flat emit/query methods, the client groups the rest of the surface into namespaces:

| Namespace | Purpose |
|---|---|
| `client.records` | `.create(emitOpts)` (emit alias), `.get(id)`, `.richQuery({ filter, sort?, limit? })` — server-side filtered query. |
| `client.threads` | `.list()`, `.records(id)`, `.state(id)`, `.project(id, format)`, `.watch(id, opts?)` — live `AsyncIterable` stream. |
| `client.folds` | `.resolve<V>(name, cacheKey?)`, `.watermark(name, cacheKey)` — read any kernel fold through one typed method. |
| `client.data` | The data plane — files, blobs, materials (see below). |
| `client.aitl` | `.pending()`, `.decide(id, { decision, reason? })` — actor-in-the-loop proposals. |
| `client.namespaces` | `.list()`, `.create({ id, description?, policy? })`. |
| `client.federation` | `.peers()`, `.pair(peer)`, `.sync(thread, peer?)`, `.discoverPeers()`, `.mergeResults()`. |
| `client.invites` | issue / list / preview / redeem / revoke / audit invitations. |
| `client.expr` | `.eval({ expression, context, record? })` — evaluate a CEL expression. |
| `client.graph` | `.query({ start, edges?, depth?, filter? })` — graph queries over the substrate. |

### `client.data` — the data plane

Files, blobs, and materials. Unlike the record reads (which fail open), the data plane **surfaces errors** as `SyncropelDataError` — a dropped write never looks like a success.

| Method | Purpose |
|---|---|
| `write({ path, data, contentType?, expectedHash? })` | One-call three-step write (init → chunked upload → commit). Returns `{ contentHash, sizeBytes }`. `expectedHash`: omit = overwrite, a hash = compare-and-swap, `null` = create-only. |
| `read(path)` / `readText(path)` | Fetch a path's bytes / UTF-8 text. |
| `readUrl(path)` | Resolve a path to a short-lived blob URL. |
| `list(path, { cursor?, limit? })` | Directory listing. |
| `stat(path)` | Node metadata: size, hash, content type, pin state, provenance. |
| `mkdir(path)` / `mv(from, to)` / `rm(path, { recursive? })` | Tree mutations. |
| `publish(path, { storageClass? })` | Promote a file to a durable, content-addressed artifact. |
| `materials({ q?, limit? })` / `node(path)` | Typed, byte-free views over files (pickers, previews). |
| `usage()` / `capabilities()` / `provenance({ … })` | Quota, self-describing limits, the "made by" feed. |

```typescript
// Create, then safely edit with compare-and-swap.
const { contentHash } = await client.data.write({
  path: "/files/notes.md",
  data: "# hello",
  contentType: "text/markdown",
});
try {
  await client.data.write({ path: "/files/notes.md", data: "# edited", expectedHash: contentHash });
} catch (e) {
  if (e instanceof SyncropelDataError && e.isConflict) {
    // someone else wrote first — reload e.currentHash and retry
  }
}
const text = await client.data.readText("/files/notes.md");
```

### `Identity`

| Form | Status |
|---|---|
| `Identity.static(did)` | Available |
| `Identity.key(pathOrBytes)` | Planned — throws if called today |
| `Identity.federated(...)` | Planned — throws if called today |

### `Ref` — canonical reference constructors

| Constructor | Canonical | Schemes |
|---|---|---|
| `Ref.musicTrack({ isrc? / spotifyId? / appleId? })` | `@music.track` | `isrc:`, `spotify:`, `apple:` |
| `Ref.codeFile({ repo? / gitUrl?, path })` | `@code.file` | `repo:`, `git:` |
| `Ref.opsIncident({ pagerduty? / linear? / url? })` | `@ops.incident` | `pd:`, `linear:`, `url:` |
| `Ref.calEvent({ uid })` | `@cal.event` | `uid:` |
| `Ref.socialPerson({ did? / email? / handle?+name? })` | `@social.person` | `did:`, `email:`, `handle:` |
| `Ref.mediaPhoto({ sha256? / url? })` | `@media.photo` | `sha256:`, `url:` |
| `Ref.mediaVideo({ youtube? / vimeo? / sha256? })` | `@media.video` | `youtube:`, `vimeo:`, `sha256:` |
| `Ref.docText({ doi? / url? / platformId? })` | `@doc.text` | `doi:`, `url:`, `platform:` |
| `Ref.finTransaction({ stripe? / plaid? / iso20022? })` | `@fin.transaction` | `stripe:`, `plaid:`, `iso20022:` |
| `Ref.researchPaper({ doi? / arxiv? / s2? })` | `@research.paper` | `doi:`, `arxiv:`, `s2:` |
| `Ref.coreThread({ id })` | `@core.thread` | `id:` |

Pass a list as `refs:` to `emit()`; the SDK merges them into `body._refs`. Two records anywhere in the network sharing the same canonical ref are joinable.

### `EmitResult`

```typescript
interface EmitResult {
  success: boolean;
  recordId?: string;
  clock?: number;
  error?: string;
  retried: number;
  kind: string;
  act: string;
  thread: string;
}
```

### `SyncropelKindError`

Thrown synchronously from `validateKind()` and every `emit*` method when `body.kind` violates the grammar. Subclasses `Error`; `instanceof` works across bundlers.

---

## Fail-open contract

`emit()` **never rejects its promise** on network errors, 4xx, 5xx, or timeouts. Every call resolves to an `EmitResult` and your code inspects `.success`:

```typescript
const result = await client.emit({ act: "PUT", kind: "music.catalog.track", body: {}, thread: "t" });
if (!result.success) {
  // Transient failure — log and keep going.
  console.warn(`emit failed: ${result.error} (retried ${result.retried})`);
}
```

A flaky network can't bring down your handler. You decide whether to drop the failure, retry, or escalate.

**Grammar errors are different.** `SyncropelKindError` always throws — it indicates programmer error (an invalid `body.kind`), and no retry will fix it. Failing loud at development time is correct.

### Observability hook

```typescript
const client = new Client({
  endpoint: "...",
  identity: Identity.static("..."),
  onEmit: (result) => {
    metrics.increment("syncropel.emit", { tags: { success: result.success } });
  },
});
```

Fires on every success and failure. Hook exceptions are swallowed with a `console.warn` — a broken metrics pipeline can't break your emit path.

---

## Grammar reference

Every record's `body.kind` follows the `scope.category.entity[.version]` grammar. The SDK validates at emit time:

| Kind | Valid? |
|---|---|
| `music.catalog.track` | ✓ — publisher scope, 3 segments |
| `music.catalog.track.v2` | ✓ — versioned |
| `@music.track` | ✓ — community canonical (2-segment allowed for `@<community>` and `core` scopes) |
| `core.alias` | ✓ — reserved core primitive |
| `dj.track_imported` | ✗ — 2-segment publisher scope forbidden |
| `Music.Catalog.Track` | ✗ — uppercase forbidden |
| `music.catalog.track.v2.foo` | ✗ — 5 segments |

When a canonical ref exists for your domain, use it:

```typescript
refs: [Ref.musicTrack({ isrc: "USJI19810404" })]
```

This makes your record correlatable with every other music record across publishers. Without refs, nothing breaks — you lose cross-app correlation.

---

## Testing your adapter

The SDK ships a canonical mock at `@syncropel/sdk/testing` — exercise your adapter end-to-end without running a server:

```typescript
import { Client, Identity, Ref } from "@syncropel/sdk";
import { MockKernel } from "@syncropel/sdk/testing";

test("my adapter imports tracks", async () => {
  const kernel = new MockKernel();
  const client = new Client({
    endpoint: "http://mock",
    identity: Identity.static("did:test:me"),
    fetch: kernel.fetch,
  });

  await myAdapter.importLibrary(client, tracks);

  const emitted = kernel.recordsByKind("music.catalog.track");
  assert.equal(emitted.length, tracks.length);
  for (const r of emitted) {
    const refs = (r.body as any)._refs as Array<{ kind: string }>;
    assert.equal(refs[0].kind, "@music.track");
  }
});
```

Record IDs produced by `MockKernel` use the same SHA-256-of-canonical-JSON rule as the real server, so `result.recordId` matches what you'd see in production. The mock also enforces `DuplicateClock` on `(thread, actor, clock)`.

Failure injection for fail-open coverage: `kernel.failNextPostCall(n)` and `kernel.failNextGetCall(n)`.

---

## Type-generation pipeline (v0.4.0+)

The SDK ships a **manifest-derived type module** at `src/types-generated.ts` —
20 typed interfaces produced from the kernel's published JSON schemas
(`/v1/capabilities`). These are the contract surface;
hand-written types in `src/types.ts` and `src/client.ts` reference them.

**To regenerate after a kernel manifest change:**

```bash
# 1. Regenerate the manifest snapshot from the kernel.
cargo run --bin export-manifest -p spl > sdks/manifest.json

# 2. Regenerate the SDK types from the new manifest.
cd sdks/typescript
npm run gen:types

# 3. Commit both manifest.json and src/types-generated.ts together.
git add ../manifest.json src/types-generated.ts
```

**Drift detection:** `npm run build` runs `npm run check:types` first. If
the regenerated output differs from the committed `types-generated.ts`,
the build fails with a diff — preventing accidental drift between the
SDK and the kernel manifest.

**Manifest version pin:** `package.json` declares which manifest version
the SDK targets (`"syncropel": { "manifest_version": "2" }`). Mismatch
with the daemon's served manifest version is exposed via the
`MANIFEST_VERSION` constant — useful when a deployment runs an older
daemon than the SDK expects.

---

## Versioning + stability

Independent semver. Patch releases ship freely; minor versions can change public behaviour with a [CHANGELOG](./CHANGELOG.md) note.

| SDK version | Highlights |
|---|---|
| **0.4.x** | **Current.** Type-generation pipeline + method expansion (`client.threads`, `client.aitl`, `client.federation`, `client.namespaces`, `client.expr`, `client.graph`, `client.records` namespaces; `do/know/learn/capabilities` flat methods; `namespace` constructor option). |
| 0.3.x | Subscribe / SSE record streaming with reconnect + resume. |
| 0.2.x | Adds `query`, `search`, and `infer` to the 0.1 surface. |
| 0.1.x | Foundation: async `Client`, grammar enforcement, canonical refs, reserved-kind helpers, `MockKernel`, fail-open transport. |

---

## License

[Apache-2.0](./LICENSE).
