meridian-sdk 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# meridian-sdk
+
+TypeScript SDK for [Meridian](../README.md) — Effect-based, fully typed, msgpack wire protocol.
+
+## Install
+
+```bash
+bun add meridian-sdk effect msgpackr
+# or
+npm install meridian-sdk effect msgpackr
+```
+
+## Quick start
+
+```ts
+import { Effect, Schema } from "effect";
+import { MeridianClient } from "meridian-sdk";
+
+// MeridianClient.create() parses + validates the token — returns Effect
+const client = await Effect.runPromise(
+  MeridianClient.create({
+    url: "http://localhost:3000",
+    namespace: "my-room",
+    token: process.env.MERIDIAN_TOKEN!,
+  })
+);
+
+// GCounter
+const views = client.gcounter("gc:views");
+views.increment(1);
+views.onChange(v => console.log("views:", v));
+
+// LWW Register with runtime schema validation
+const Profile = Schema.Struct({ name: Schema.String, avatar: Schema.String });
+const profile = client.lwwregister("lw:profile", Profile);
+profile.set({ name: "Chahine", avatar: "https://..." });
+profile.onChange(v => console.log("profile:", v)); // v: { name, avatar } | null
+
+// Presence
+const Cursor = Schema.Struct({ x: Schema.Number, y: Schema.Number });
+const room = client.presence("pr:room", Cursor);
+room.heartbeat({ x: 100, y: 200 }, 30_000);
+room.onChange(entries => console.log("online:", entries));
+
+// Close WebSocket when done
+client.close();
+```
+
+## Error handling
+
+All errors are `Data.TaggedError` — matchable with `Effect.catchTag`:
+
+```ts
+import { Effect } from "effect";
+import { MeridianClient, TokenExpiredError, HttpError, NetworkError } from "meridian-sdk";
+
+await Effect.runPromise(
+  MeridianClient.create(config).pipe(
+    Effect.catchTag("TokenExpiredError", (e) =>
+      Effect.die(`Token expired at ${new Date(e.expiredAt).toISOString()}`)
+    ),
+    Effect.flatMap(client =>
+      client.http.getCrdt("my-room", "gc:views").pipe(
+        Effect.catchTag("HttpError", e => Effect.succeed(`HTTP ${e.status}`)),
+        Effect.catchTag("NetworkError", e => Effect.succeed(`Network: ${e.message}`)),
+      )
+    ),
+  )
+);
+```
+
+## API
+
+### `MeridianClient.create(config)` → `Effect<MeridianClient, TokenParseError | TokenExpiredError>`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `string` | Server base URL (`http://` or `ws://`) |
+| `namespace` | `string` | Namespace to connect to |
+| `token` | `string` | Meridian token |
+| `autoConnect` | `boolean?` | Open WebSocket immediately (default: `true`) |
+
+### CRDT handles
+
+| Method | Returns | Schema? |
+|--------|---------|---------|
+| `client.gcounter(id)` | `GCounterHandle` | — |
+| `client.pncounter(id)` | `PNCounterHandle` | — |
+| `client.orset(id, schema?)` | `ORSetHandle<T>` | Optional |
+| `client.lwwregister(id, schema?)` | `LwwRegisterHandle<T>` | Optional |
+| `client.presence(id, schema?)` | `PresenceHandle<T>` | Optional |
+
+Without a schema, `T = unknown`. With a schema, incoming deltas are validated at runtime via `Schema.decodeUnknownSync`.
+
+### HTTP client (`client.http`)
+
+All methods return `Effect<T, HttpError | NetworkError>`:
+
+```ts
+client.http.getCrdt(ns, id)           // → Effect<CrdtGetResponse, ...>
+client.http.postOp(ns, id, op)        // → Effect<CrdtOpResponse, ...>
+client.http.syncCrdt(ns, id, sinceVc) // → Effect<CrdtGetResponse, ...>
+client.http.issueToken(ns, opts)      // → Effect<TokenIssueResponse, ...>
+```
+
+## Wire protocol
+
+- **Transport**: HTTP + WebSocket
+- **Serialization**: MessagePack (msgpackr)
+- **Auth**: Bearer token in `Authorization` header or `?token=` query param
+
+## Development
+
+```bash
+bun install
+bun test          # run tests
+bun run typecheck # tsc --noEmit
+bun run build     # compile to dist/
+```

package/dist/auth/token.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Token parsing and expiry check (client-side only — no signature verification).
+ *
+ * Wire format: `base64url_no_pad(msgpack(TokenClaims)) + "." + base64url_no_pad(sig[64B])`
+ */
+import { Effect } from "effect";
+import { TokenParseError, TokenExpiredError } from "../errors.js";
+import { TokenClaims } from "../schema.js";
+/**
+ * Parse a Meridian token string and return the decoded claims.
+ * Returns Effect<TokenClaims, TokenParseError>.
+ * Does NOT verify the ed25519 signature — the server enforces that.
+ */
+export declare const parseToken: (token: string) => Effect.Effect<TokenClaims, TokenParseError>;
+/**
+ * Check token expiry. Returns Effect<TokenClaims, TokenExpiredError>.
+ * Clock-skew tolerance: ±5s.
+ */
+export declare const checkTokenExpiry: (claims: TokenClaims, nowMs?: number) => Effect.Effect<TokenClaims, TokenExpiredError>;
+/**
+ * Parse and check expiry in one step.
+ * Returns Effect<TokenClaims, TokenParseError | TokenExpiredError>.
+ */
+export declare const parseAndValidateToken: (token: string) => Effect.Effect<TokenClaims, TokenParseError | TokenExpiredError>;
+/** Returns milliseconds until the token expires (negative if already expired). */
+export declare const tokenTtlMs: (claims: TokenClaims, nowMs?: number) => number;
+//# sourceMappingURL=token.d.ts.map

package/dist/auth/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/auth/token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAM3C;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,CA+BjF,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,WAAW,EACnB,cAAkB,KACjB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,iBAAiB,CAM9C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,MAAM,KACZ,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,GAAG,iBAAiB,CACP,CAAC;AAE3D,kFAAkF;AAClF,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,EAAE,cAAkB,KAAG,MAC1C,CAAC"}

package/dist/auth/token.js

@@ -0,0 +1,75 @@
+/**
+ * Token parsing and expiry check (client-side only — no signature verification).
+ *
+ * Wire format: `base64url_no_pad(msgpack(TokenClaims)) + "." + base64url_no_pad(sig[64B])`
+ */
+import { unpack } from "msgpackr";
+import { Effect, Schema } from "effect";
+import { TokenParseError, TokenExpiredError } from "../errors.js";
+import { TokenClaims } from "../schema.js";
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+/**
+ * Parse a Meridian token string and return the decoded claims.
+ * Returns Effect<TokenClaims, TokenParseError>.
+ * Does NOT verify the ed25519 signature — the server enforces that.
+ */
+export const parseToken = (token) => Effect.gen(function* () {
+    const dotIndex = token.indexOf(".");
+    if (dotIndex === -1) {
+        yield* Effect.fail(new TokenParseError({ message: "Invalid token format: missing '.'" }));
+        return undefined;
+    }
+    const payloadB64 = token.slice(0, dotIndex);
+    let bytes;
+    try {
+        bytes = base64urlDecode(payloadB64);
+    }
+    catch {
+        yield* Effect.fail(new TokenParseError({ message: "Invalid token format: base64url decode failed" }));
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = unpack(bytes);
+    }
+    catch {
+        yield* Effect.fail(new TokenParseError({ message: "Invalid token format: msgpack decode failed" }));
+        return undefined;
+    }
+    return yield* Schema.decodeUnknown(TokenClaims)(raw).pipe(Effect.mapError((e) => new TokenParseError({ message: `Invalid token format: ${e.message}` })));
+});
+/**
+ * Check token expiry. Returns Effect<TokenClaims, TokenExpiredError>.
+ * Clock-skew tolerance: ±5s.
+ */
+export const checkTokenExpiry = (claims, nowMs = Date.now()) => {
+    const SKEW_MS = 5_000;
+    if (nowMs >= claims.expires_at + SKEW_MS) {
+        return Effect.fail(new TokenExpiredError({ expiredAt: claims.expires_at }));
+    }
+    return Effect.succeed(claims);
+};
+/**
+ * Parse and check expiry in one step.
+ * Returns Effect<TokenClaims, TokenParseError | TokenExpiredError>.
+ */
+export const parseAndValidateToken = (token) => parseToken(token).pipe(Effect.flatMap(checkTokenExpiry));
+/** Returns milliseconds until the token expires (negative if already expired). */
+export const tokenTtlMs = (claims, nowMs = Date.now()) => claims.expires_at - nowMs;
+// ---------------------------------------------------------------------------
+// Base64url (no-padding) decoder — no external dep
+// ---------------------------------------------------------------------------
+function base64urlDecode(input) {
+    const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padLen = (4 - (padded.length % 4)) % 4;
+    const b64 = padded + "=".repeat(padLen);
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+//# sourceMappingURL=token.js.map

package/dist/auth/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/auth/token.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MeridianClient — top-level SDK entry point.
+ *
+ * Use `MeridianClient.create(config)` (returns Effect) to parse the token
+ * and validate it before connecting.
+ *
+ * ```ts
+ * const client = await Effect.runPromise(
+ *   MeridianClient.create({ url: "ws://localhost:3000", namespace: "room", token })
+ * );
+ * const counter = client.gcounter("gc:page-views");
+ * counter.increment();
+ * counter.onChange(v => console.log("views:", v));
+ * ```
+ */
+import { Effect, Schema } from "effect";
+import { HttpClient } from "./transport/http.js";
+import { GCounterHandle } from "./crdt/gcounter.js";
+import { PNCounterHandle } from "./crdt/pncounter.js";
+import { ORSetHandle } from "./crdt/orset.js";
+import { LwwRegisterHandle } from "./crdt/lwwregister.js";
+import { PresenceHandle } from "./crdt/presence.js";
+import type { TokenClaims } from "./schema.js";
+import type { TokenParseError, TokenExpiredError } from "./errors.js";
+export interface MeridianClientConfig {
+    /** Base URL of the Meridian server, e.g. "http://localhost:3000" */
+    url: string;
+    /** Namespace to connect to. */
+    namespace: string;
+    /** Meridian token for this namespace. */
+    token: string;
+    /** If true, open the WebSocket immediately. Default: true */
+    autoConnect?: boolean;
+}
+export declare class MeridianClient {
+    readonly namespace: string;
+    readonly clientId: number;
+    readonly claims: TokenClaims;
+    private readonly transport;
+    readonly http: HttpClient;
+    private readonly gcHandles;
+    private readonly pnHandles;
+    private readonly orHandles;
+    private readonly lwHandles;
+    private readonly prHandles;
+    private constructor();
+    /**
+     * Create a MeridianClient, parsing and validating the token.
+     * Returns Effect<MeridianClient, TokenParseError | TokenExpiredError>.
+     */
+    static create(config: MeridianClientConfig): Effect.Effect<MeridianClient, TokenParseError | TokenExpiredError>;
+    gcounter(crdtId: string): GCounterHandle;
+    pncounter(crdtId: string): PNCounterHandle;
+    orset<T>(crdtId: string, schema?: Schema.Schema<T>): ORSetHandle<T>;
+    lwwregister<T>(crdtId: string, schema?: Schema.Schema<T>): LwwRegisterHandle<T>;
+    presence<T>(crdtId: string, schema?: Schema.Schema<T>): PresenceHandle<T>;
+    close(): void;
+    private handleServerMsg;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASpD,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMtE,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAMD,qBAAa,cAAc;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAI1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;IAExE,OAAO;IAsBP;;;OAGG;IACH,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAQrE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc;IAUxC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAU1C,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAWnE,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC;IAW/E,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAazE,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,eAAe;CA6BxB"}

package/dist/client.js

@@ -0,0 +1,166 @@
+/**
+ * MeridianClient — top-level SDK entry point.
+ *
+ * Use `MeridianClient.create(config)` (returns Effect) to parse the token
+ * and validate it before connecting.
+ *
+ * ```ts
+ * const client = await Effect.runPromise(
+ *   MeridianClient.create({ url: "ws://localhost:3000", namespace: "room", token })
+ * );
+ * const counter = client.gcounter("gc:page-views");
+ * counter.increment();
+ * counter.onChange(v => console.log("views:", v));
+ * ```
+ */
+import { Effect, Schema } from "effect";
+import { WsTransport } from "./transport/websocket.js";
+import { HttpClient } from "./transport/http.js";
+import { GCounterHandle } from "./crdt/gcounter.js";
+import { PNCounterHandle } from "./crdt/pncounter.js";
+import { ORSetHandle } from "./crdt/orset.js";
+import { LwwRegisterHandle } from "./crdt/lwwregister.js";
+import { PresenceHandle } from "./crdt/presence.js";
+import { decodeGCounterDelta, decodePNCounterDelta, decodeORSetDelta, decodeLwwDelta, decodePresenceDelta, } from "./sync/delta.js";
+import { parseAndValidateToken } from "./auth/token.js";
+// ---------------------------------------------------------------------------
+// MeridianClient
+// ---------------------------------------------------------------------------
+export class MeridianClient {
+    namespace;
+    clientId;
+    claims;
+    transport;
+    http;
+    // Handle caches — keyed by crdt_id. Generic params erased at storage level;
+    // factories restore them via typed get+cast on retrieval.
+    gcHandles = new Map();
+    pnHandles = new Map();
+    orHandles = new Map();
+    lwHandles = new Map();
+    prHandles = new Map();
+    constructor(config, claims) {
+        this.namespace = config.namespace;
+        this.claims = claims;
+        this.clientId = claims.client_id;
+        const httpBase = config.url
+            .replace(/^wss:\/\//, "https://")
+            .replace(/^ws:\/\//, "http://");
+        this.http = new HttpClient({ baseUrl: httpBase, token: config.token });
+        const wsUrl = `${config.url.replace(/^http/, "ws")}/v1/namespaces/${config.namespace}/connect`;
+        this.transport = new WsTransport({
+            url: wsUrl,
+            token: config.token,
+            onMessage: (msg) => { this.handleServerMsg(msg); },
+        });
+        if (config.autoConnect !== false) {
+            this.transport.connect();
+        }
+    }
+    /**
+     * Create a MeridianClient, parsing and validating the token.
+     * Returns Effect<MeridianClient, TokenParseError | TokenExpiredError>.
+     */
+    static create(config) {
+        return parseAndValidateToken(config.token).pipe(Effect.map((claims) => new MeridianClient(config, claims)));
+    }
+    // ---- CRDT factory methods ----
+    gcounter(crdtId) {
+        let h = this.gcHandles.get(crdtId);
+        if (!h) {
+            h = new GCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
+            this.gcHandles.set(crdtId, h);
+            this.transport.subscribe(crdtId);
+        }
+        return h;
+    }
+    pncounter(crdtId) {
+        let h = this.pnHandles.get(crdtId);
+        if (!h) {
+            h = new PNCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
+            this.pnHandles.set(crdtId, h);
+            this.transport.subscribe(crdtId);
+        }
+        return h;
+    }
+    orset(crdtId, schema) {
+        let h = this.orHandles.get(crdtId);
+        if (!h) {
+            const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
+            h = schema ? new ORSetHandle({ ...base, schema }) : new ORSetHandle(base);
+            this.orHandles.set(crdtId, h);
+            this.transport.subscribe(crdtId);
+        }
+        return h;
+    }
+    lwwregister(crdtId, schema) {
+        let h = this.lwHandles.get(crdtId);
+        if (!h) {
+            const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
+            h = schema ? new LwwRegisterHandle({ ...base, schema }) : new LwwRegisterHandle(base);
+            this.lwHandles.set(crdtId, h);
+            this.transport.subscribe(crdtId);
+        }
+        return h;
+    }
+    presence(crdtId, schema) {
+        let h = this.prHandles.get(crdtId);
+        if (!h) {
+            const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
+            h = schema ? new PresenceHandle({ ...base, schema }) : new PresenceHandle(base);
+            this.prHandles.set(crdtId, h);
+            this.transport.subscribe(crdtId);
+        }
+        return h;
+    }
+    // ---- Lifecycle ----
+    close() {
+        this.transport.close();
+    }
+    // ---- Internal: route ServerMsg.Delta to the right handle ----
+    handleServerMsg(msg) {
+        if (!("Delta" in msg))
+            return;
+        const { crdt_id, delta_bytes } = msg.Delta;
+        const gcHandle = this.gcHandles.get(crdt_id);
+        if (gcHandle) {
+            try {
+                gcHandle.applyDelta(decodeGCounterDelta(delta_bytes));
+            }
+            catch { /* stale */ }
+            return;
+        }
+        const pnHandle = this.pnHandles.get(crdt_id);
+        if (pnHandle) {
+            try {
+                pnHandle.applyDelta(decodePNCounterDelta(delta_bytes));
+            }
+            catch { /* stale */ }
+            return;
+        }
+        const orHandle = this.orHandles.get(crdt_id);
+        if (orHandle) {
+            try {
+                orHandle.applyDelta(decodeORSetDelta(delta_bytes));
+            }
+            catch { /* stale */ }
+            return;
+        }
+        const lwHandle = this.lwHandles.get(crdt_id);
+        if (lwHandle) {
+            try {
+                lwHandle.applyDelta(decodeLwwDelta(delta_bytes));
+            }
+            catch { /* stale */ }
+            return;
+        }
+        const prHandle = this.prHandles.get(crdt_id);
+        if (prHandle) {
+            try {
+                prHandle.applyDelta(decodePresenceDelta(delta_bytes));
+            }
+            catch { /* stale */ }
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/codec.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Msgpack codec — wraps msgpackr with Meridian-specific conventions.
+ *
+ * The server uses rmp-serde with `to_vec_named` (named fields) so enum
+ * variants are encoded as `{ "VariantName": { ...fields } }` maps.
+ * msgpackr handles this transparently in JS land.
+ */
+import { Effect } from "effect";
+import { CodecError } from "./errors.js";
+import { ServerMsg } from "./schema.js";
+import type { ClientMsg, VectorClock } from "./schema.js";
+/** Encode any value to msgpack bytes. */
+export declare function encode(value: unknown): Uint8Array<ArrayBuffer>;
+/** Decode msgpack bytes to a plain JS value (unsafe — no schema validation). */
+export declare function decode(bytes: Uint8Array): unknown;
+/**
+ * Encode a ClientMsg to a binary WebSocket frame.
+ * The msgpack encoding matches rmp-serde's "named" enum format:
+ *   `{ Subscribe: { crdt_id: "foo" } }` → msgpack map with one key.
+ */
+export declare function encodeClientMsg(msg: ClientMsg): Uint8Array;
+/**
+ * Decode a binary WebSocket frame into a ServerMsg.
+ * Returns Effect<ServerMsg, CodecError>.
+ */
+export declare function decodeServerMsg(bytes: Uint8Array): Effect.Effect<ServerMsg, CodecError>;
+export declare function encodeVectorClock(vc: VectorClock): Uint8Array;
+export declare function decodeVectorClock(bytes: Uint8Array): Effect.Effect<VectorClock, CodecError>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM1D,yCAAyC;AACzC,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,CAE9D;AAED,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAEjD;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,UAAU,CAE1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAiBvF;AAMD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,UAAU,CAG7D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAkB3F"}

package/dist/codec.js

@@ -0,0 +1,72 @@
+/**
+ * Msgpack codec — wraps msgpackr with Meridian-specific conventions.
+ *
+ * The server uses rmp-serde with `to_vec_named` (named fields) so enum
+ * variants are encoded as `{ "VariantName": { ...fields } }` maps.
+ * msgpackr handles this transparently in JS land.
+ */
+import { pack, unpack } from "msgpackr";
+import { Effect, Schema } from "effect";
+import { CodecError } from "./errors.js";
+import { ServerMsg } from "./schema.js";
+// ---------------------------------------------------------------------------
+// Low-level encode / decode
+// ---------------------------------------------------------------------------
+/** Encode any value to msgpack bytes. */
+export function encode(value) {
+    return pack(value);
+}
+/** Decode msgpack bytes to a plain JS value (unsafe — no schema validation). */
+export function decode(bytes) {
+    return unpack(bytes);
+}
+// ---------------------------------------------------------------------------
+// Typed helpers for WebSocket frames
+// ---------------------------------------------------------------------------
+/**
+ * Encode a ClientMsg to a binary WebSocket frame.
+ * The msgpack encoding matches rmp-serde's "named" enum format:
+ *   `{ Subscribe: { crdt_id: "foo" } }` → msgpack map with one key.
+ */
+export function encodeClientMsg(msg) {
+    return encode(msg);
+}
+/**
+ * Decode a binary WebSocket frame into a ServerMsg.
+ * Returns Effect<ServerMsg, CodecError>.
+ */
+export function decodeServerMsg(bytes) {
+    let raw;
+    try {
+        raw = unpack(bytes);
+    }
+    catch {
+        return Effect.fail(new CodecError({ message: "msgpack decode failed", raw: bytes }));
+    }
+    // Schema.decodeUnknown accepts `unknown` input — correct for runtime decode boundaries
+    return Schema.decodeUnknown(ServerMsg)(raw).pipe(Effect.mapError((parseError) => new CodecError({
+        message: `ServerMsg schema validation failed: ${parseError.message}`,
+        raw: bytes,
+    })));
+}
+// ---------------------------------------------------------------------------
+// VectorClock <-> msgpack bytes
+// ---------------------------------------------------------------------------
+export function encodeVectorClock(vc) {
+    // Server expects { entries: { "client_id": version, ... } }
+    return encode({ entries: vc });
+}
+export function decodeVectorClock(bytes) {
+    let raw;
+    try {
+        raw = unpack(bytes);
+    }
+    catch {
+        return Effect.fail(new CodecError({ message: "VectorClock msgpack decode failed", raw: bytes }));
+    }
+    const entries = raw !== null && typeof raw === "object" && "entries" in raw
+        ? raw.entries
+        : {};
+    return Schema.decodeUnknown(Schema.Record({ key: Schema.String, value: Schema.Number }))(entries ?? {}).pipe(Effect.mapError((e) => new CodecError({ message: `VectorClock schema validation failed: ${e.message}`, raw: bytes })));
+}
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E,yCAAyC;AACzC,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,OAAO,IAAI,CAAC,KAAK,CAA4B,CAAC;AAChD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,MAAM,CAAC,KAAiB;IACtC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAc;IAC5C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,EAAE,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,uFAAuF;IACvF,OAAO,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAC9C,MAAM,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,EAAE,CAC7B,IAAI,UAAU,CAAC;QACb,OAAO,EAAE,uCAAuC,UAAU,CAAC,OAAO,EAAE;QACpE,GAAG,EAAE,KAAK;KACX,CAAC,CACH,CACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,MAAM,UAAU,iBAAiB,CAAC,EAAe;IAC/C,4DAA4D;IAC5D,OAAO,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,EAAE,OAAO,EAAE,mCAAmC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACnG,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAI,GAAG;QACzE,CAAC,CAAE,GAA4B,CAAC,OAAO;QACvC,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CACtF,OAAO,IAAI,EAAE,CACd,CAAC,IAAI,CACJ,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CACpB,IAAI,UAAU,CAAC,EAAE,OAAO,EAAE,yCAAyC,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAC9F,CACF,CAAC;AACJ,CAAC"}

package/dist/crdt/gcounter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * GCounter handle — increment-only counter.
+ *
+ * Local state is kept as a sparse map `{ client_id → count }`.
+ * `value()` returns the sum. Deltas are merged on incoming ServerMsg.Delta.
+ */
+import type { WsTransport } from "../transport/websocket.js";
+import type { GCounterDelta } from "../sync/delta.js";
+export interface GCounterState {
+    counts: Record<string, number>;
+}
+export declare class GCounterHandle {
+    private state;
+    private readonly clientId;
+    private readonly crdtId;
+    private readonly ns;
+    private readonly transport;
+    /** Emits on every state change. */
+    private readonly listeners;
+    constructor(opts: {
+        ns: string;
+        crdtId: string;
+        clientId: number;
+        transport: WsTransport;
+        initial?: GCounterState;
+    });
+    value(): number;
+    counts(): Readonly<Record<string, number>>;
+    /** Subscribe to value changes. Returns an unsubscribe function. */
+    onChange(listener: (value: number) => void): () => void;
+    /** Increment by `amount` (must be > 0). */
+    increment(amount?: number): void;
+    applyDelta(delta: GCounterDelta): void;
+    private emit;
+}
+//# sourceMappingURL=gcounter.d.ts.map

package/dist/crdt/gcounter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcounter.d.ts","sourceRoot":"","sources":["../../src/crdt/gcounter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;gBAEpD,IAAI,EAAE;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,WAAW,CAAC;QACvB,OAAO,CAAC,EAAE,aAAa,CAAC;KACzB;IAUD,KAAK,IAAI,MAAM;IAIf,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI1C,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,2CAA2C;IAC3C,SAAS,CAAC,MAAM,GAAE,MAAU,GAAG,IAAI;IAsBnC,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IActC,OAAO,CAAC,IAAI;CAMb"}