mushroomdb-client 0.1.2

package/README.md

@@ -0,0 +1,281 @@
+# mushroomdb-client
+
+TypeScript client for the [mushroomdb](https://github.com/MatthewSherlin/mushroomdb) graph database.
+Wraps the HTTP and WebSocket API exposed by `mushroomdb serve`.
+
+> **Not yet published to npm.** Install from the repo path (see below).
+
+---
+
+## Installation (from repo)
+
+```sh
+npm install /path/to/graph-db/clients/typescript
+```
+
+Or add to `package.json`:
+
+```json
+{
+  "dependencies": {
+    "mushroomdb-client": "file:../path/to/graph-db/clients/typescript"
+  }
+}
+```
+
+Node 18+ required. Fetch is built-in. For WebSocket in Node < 21, install `ws`:
+
+```sh
+npm install ws
+```
+
+---
+
+## Quick start
+
+```ts
+import { MushroomClient } from 'mushroomdb-client';
+
+const client = new MushroomClient('http://127.0.0.1:8080');
+
+// Read query
+const result = await client.query(
+  'MATCH (p:Person) RETURN p.id AS id, p.name AS name LIMIT 10',
+);
+console.log(result.columns); // ['id', 'name']
+console.log(result.rows);    // [['person-01', 'Alice'], ...]
+
+// Parameterised read
+const row = await client.query(
+  'MATCH (p:Person {id: $pid}) RETURN p.name AS name',
+  { params: { pid: 'person-01' } },
+);
+
+// Write (CREATE, MERGE, SET, DELETE)
+await client.query("CREATE (n:Company {id: 'acme', name: 'Acme Corp'})");
+
+// Bulk ingest
+await client.ingest({
+  label: 'Product',
+  rows: [
+    { id: 'prod-1', name: 'Widget', price: 9.99 },
+    { id: 'prod-2', name: 'Gadget', price: 24.99 },
+  ],
+});
+
+// Stats
+const stats = await client.stats();
+console.log(stats.nodes_live, stats.edges);
+
+// Rule suggestions
+const report = await client.suggest();
+console.log(report.truncated, report.suggestions.length);
+
+// Graph algorithms
+const pr = await client.algo('pagerank');
+console.log(pr.scores.slice(0, 5)); // top-5 nodes by PageRank
+
+const wcc = await client.algo('wcc');
+console.log(wcc.components.length);
+
+const deg = await client.algo('degree', { direction: 'out' });
+console.log(deg.scores.slice(0, 5));
+```
+
+---
+
+## WebSocket subscriptions
+
+Subscribe to post-commit events over `GET /subscribe`.
+
+**No auto-reconnect in v1.** When the connection drops, no further events are
+delivered. Reconnect manually if required.
+
+**The `lagged` event** is passed to `onEvent` like any other event. It fires
+when the server's per-subscriber queue (65,536 events) overflows. On receiving
+it, re-read the affected graph state for lossless consumers.
+
+```ts
+import WS from 'ws'; // Node < 21: npm install ws
+import type { WsConstructor } from 'mushroomdb-client';
+
+const handle = await client.subscribe(
+  {
+    rules: ['skill_fit'],   // rule-fire events
+    writes: true,           // node/prop write events
+    wsConstructor: WS as unknown as WsConstructor, // Node < 21 only
+  },
+  (ev) => {
+    switch (ev.type) {
+      case 'edge_fired':
+        console.log(`Rule ${ev.rule}: ${ev.src_key} → ${ev.dst_key} (seq ${ev.commit_seq})`);
+        break;
+      case 'node_inserted':
+        console.log(`New node: ${ev.key} (label ${ev.label})`);
+        break;
+      case 'lagged':
+        console.warn(`Missed ${ev.missed} events — re-read state`);
+        break;
+    }
+  },
+);
+
+// ... do work ...
+
+// Always await close to avoid dangling handles.
+await handle.close();
+```
+
+---
+
+## API reference
+
+### `new MushroomClient(baseUrl: string, opts?: { token?: string })`
+
+Create a client. `baseUrl` is the HTTP base URL printed by `mushroomdb serve`,
+e.g. `"http://127.0.0.1:8080"`. When `opts.token` is set, every HTTP fetch
+sends `Authorization: Bearer <token>`.
+
+### `client.query(cypher, opts?) → Promise<QueryResult>`
+
+Run a Cypher query (read or write). The server detects write statements and
+acquires the write lock automatically. Returns `{ columns: string[], rows: CellValue[][] }`.
+
+`opts.params` — bound parameters; values must be JSON scalars
+(`string | number | boolean`).
+
+### `client.ingest(req) → Promise<IngestReport>`
+
+Bulk-ingest nodes and optional edges. `req.label`, `req.rows` are required.
+See `IngestOptions` and `IngestEdge` for advanced options.
+
+### `client.stats() → Promise<Stats>`
+
+Returns live node/edge counts and per-rule statistics.
+
+### `client.suggest() → Promise<SuggestReport>`
+
+Profile the database and return candidate linking rules. CPU-intensive;
+capped at 5 s server-side. The `truncated` flag is `true` when the budget
+fires early.
+
+### `client.explain(a, b) → Promise<Explanation[]>`
+
+Wires `GET /explain?a=&b=`. Returns rule-derived edges between two node keys.
+
+### `client.createRule(def) → Promise<void>`
+
+Wires `POST /rules` with a `RuleDef` JSON body.
+
+### `client.node(key) → Promise<NodeInfo | null>`
+
+Wires `GET /node/{key}`. Returns `null` for an unknown key (HTTP 404).
+
+### `client.neighborhood(key, opts?) → Promise<Neighborhood>`
+
+Wires `GET /node/{key}/neighborhood`. `opts.depth` defaults to the server's
+(1). Result columns are `key`, `label`, `depth`.
+
+### `client.algo(name, config?) → Promise<AlgoReport>`
+
+Run a graph algorithm:
+
+| name | config type | result type |
+|------|-------------|-------------|
+| `"pagerank"` | `PageRankConfig` | `PageRankReport` — `{ scores: [key, score][], converged }` |
+| `"wcc"` | `WccConfig` | `WccReport` — `{ components: [key, component_id][], truncated }` |
+| `"degree"` | `DegreeConfig` | `DegreeReport` — `{ scores: [key, degree][], truncated }` |
+
+All config fields are optional; server defaults apply.
+
+### `client.subscribe(opts, onEvent) → Promise<SubscribeHandle>`
+
+Open a WebSocket subscription. Returns a handle with `close(): Promise<void>`.
+
+---
+
+## Error handling
+
+All HTTP errors throw `MushroomError` with the server's error detail in
+`err.detail` (and `err.message`):
+
+```ts
+import { MushroomError } from 'mushroomdb-client';
+try {
+  await client.query('BAD CYPHER');
+} catch (err) {
+  if (err instanceof MushroomError) {
+    console.error('Query failed:', err.detail);
+  }
+}
+```
+
+---
+
+## Known server-side limitations
+
+These are limitations of the mushroomdb server's Cypher implementation that
+affect how you write queries through this client.
+
+### 1. `CREATE ... RETURN` is supported
+
+You can include a `RETURN` clause directly after `CREATE` or `MERGE` to get
+back the created or matched bindings in a single statement:
+
+```ts
+// Single-statement create + return:
+const result = await client.query(
+  "CREATE (n:Widget {id: 'w1', name: 'Sprocket'}) RETURN n.name AS nm"
+);
+// result.rows[0][0] === 'Sprocket'
+
+// MERGE + RETURN (returns the node whether created or matched):
+const r2 = await client.query(
+  "MERGE (n:Tag {id: 'rust'}) RETURN n"
+);
+```
+
+### 2. Every node requires a string `id` property
+
+When using `CREATE`, nodes must include an `id` field with a string value.
+This is the key the server uses to identify the node:
+
+```ts
+// WRONG — missing 'id'
+await client.query("CREATE (n:Widget {name: 'Sprocket'})");
+
+// CORRECT
+await client.query("CREATE (n:Widget {id: 'w1', name: 'Sprocket'})");
+```
+
+---
+
+## Node-only vs browser-compatible
+
+| Feature | Browser | Node 18+ |
+|---------|---------|----------|
+| `query`, `ingest`, `stats`, `suggest`, `algo`, `explain`, `createRule`, `node`, `neighborhood` | Yes (uses `fetch`) | Yes |
+| `subscribe` | Yes (uses global `WebSocket`) | Requires `wsConstructor` option + `ws` package |
+
+---
+
+## Running the tests
+
+```sh
+cd clients/typescript
+npm ci
+npm test
+```
+
+Tests spawn a real `mushroomdb` binary. The first run builds it with `cargo`
+(takes ~30 s on a cold cache). If the build fails, all tests are **skipped**
+with a clear message (not marked as failed).
+
+Set `CARGO=/path/to/cargo` to use a specific cargo binary (required in CI or
+on machines where cargo is not on `PATH`).
+
+---
+
+## License
+
+Apache-2.0. Copyright 2026 Matthew Sherlin.

package/dist/client.d.ts

@@ -0,0 +1,176 @@
+/**
+ * HTTP client for the mushroomdb server.
+ *
+ * Uses the browser-standard `fetch` API (built into Node 18+).
+ *
+ * ```ts
+ * import { MushroomClient } from 'mushroomdb-client';
+ *
+ * const client = new MushroomClient('http://127.0.0.1:8080');
+ * const result = await client.query('MATCH (n:Person) RETURN n.name LIMIT 10');
+ * console.log(result.columns, result.rows);
+ * ```
+ */
+import { MushroomError, type DegreeConfig, type DegreeReport, type Explanation, type IngestReport, type IngestRequest, type Neighborhood, type NodeInfo, type PageRankConfig, type PageRankReport, type QueryResult, type RuleDef, type Stats, type SuggestReport, type WccConfig, type WccReport } from "./types.js";
+import { type SubscribeHandle, type SubscribeOptions, type WsConstructor } from "./ws.js";
+export type { AlgoDir, AlgoReport, CellValue, DegreeConfig, DegreeReport, Explanation, IngestEdge, IngestOptions, IngestReport, IngestRequest, Neighborhood, NodeInfo, PageRankConfig, PageRankReport, PredicateKind, PredicateSummary, QueryResult, RuleDef, RulePredicate, RuleStats, RuleSuggestion, Stats, SuggestReport, WccConfig, WccReport, } from "./types.js";
+export { MushroomError };
+/** Optional constructor flags for {@link MushroomClient}. */
+export interface ClientOptions {
+    /**
+     * When set, sent as `Authorization: Bearer <token>` on every HTTP fetch.
+     * Cookie auth is a browser/explorer concern and is not implemented here.
+     */
+    token?: string;
+}
+/** Parameters for a Cypher query. Values must be JSON scalars. */
+export type QueryParams = Record<string, string | number | boolean>;
+/** Options accepted by {@link MushroomClient.query}. */
+export interface QueryOptions {
+    /** Bound parameters. Values must be JSON scalars (string | number | boolean). */
+    params?: QueryParams;
+}
+/**
+ * HTTP + WebSocket client for mushroomdb.
+ *
+ * All methods use the browser-standard `fetch` API and are therefore
+ * compatible with both Node.js 18+ and modern browsers.
+ *
+ * **Node-only**: The `subscribe` method requires a WebSocket implementation.
+ * In Node < 21, install the `ws` package and pass `wsConstructor` in the
+ * subscribe options. See {@link SubscribeOptions}.
+ */
+export declare class MushroomClient {
+    private readonly baseUrl;
+    private readonly wsBase;
+    private readonly token;
+    /**
+     * @param baseUrl  HTTP base URL of the mushroomdb server, e.g.
+     *                 `"http://127.0.0.1:8080"`. Trailing slash is stripped.
+     * @param opts     Optional `{ token }` — sent as `Authorization: Bearer`.
+     */
+    constructor(baseUrl: string, opts?: ClientOptions);
+    private url;
+    private wsUrl;
+    private authHeaders;
+    /**
+     * Execute a fetch and decode the JSON body.
+     * Throws {@link MushroomError} on non-2xx responses.
+     */
+    private fetchJson;
+    /**
+     * Run a Cypher query (read or write).
+     *
+     * The server auto-detects write statements (`CREATE`, `MERGE`, `SET`,
+     * `DELETE`) and acquires the appropriate lock. Both read and write queries
+     * go to `POST /query?format=json`.
+     *
+     * @param cypher Cypher query string.
+     * @param opts   Optional bound parameters (JSON scalar values only).
+     * @returns      Column names and a 2-D array of {@link CellValue} rows.
+     */
+    query(cypher: string, opts?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Ingest nodes (and optional edges) into the database.
+     *
+     * Wraps `POST /ingest`. The server acquires the write lock, applies the
+     * rows to the WAL, and runs all rules incrementally.
+     *
+     * @param req  Ingest payload — `label`, `rows`, optional `options` and `edges`.
+     * @returns    Server ingest report (opaque; check for absence of errors).
+     */
+    ingest(req: IngestRequest): Promise<IngestReport>;
+    /**
+     * Get database-wide statistics.
+     *
+     * Wraps `GET /stats`. Returns live node/edge counts and per-rule stats.
+     */
+    stats(): Promise<Stats>;
+    /**
+     * Profile the database and return rule suggestions.
+     *
+     * Wraps `GET /suggest`. CPU-intensive — runs in the server's blocking
+     * thread-pool with a 5-second global budget. The {@link SuggestReport}
+     * includes a `truncated` flag when the budget fires early.
+     *
+     * Suggestions are not auto-applied; call `POST /rules` to create a rule.
+     */
+    suggest(): Promise<SuggestReport>;
+    /**
+     * Run a graph algorithm.
+     *
+     * Wraps `POST /algo/{pagerank|wcc|degree}`.
+     *
+     * @param algo   Algorithm name.
+     * @param config Optional algorithm-specific configuration.
+     * @returns      Algorithm report — see {@link PageRankReport}, {@link WccReport},
+     *               {@link DegreeReport}.
+     *
+     * @example
+     * ```ts
+     * const pr = await client.algo('pagerank') as PageRankReport;
+     * console.log(pr.scores.slice(0, 5));
+     * ```
+     */
+    algo(algo: "pagerank", config?: PageRankConfig): Promise<PageRankReport>;
+    algo(algo: "wcc", config?: WccConfig): Promise<WccReport>;
+    algo(algo: "degree", config?: DegreeConfig): Promise<DegreeReport>;
+    /**
+     * Explain rule-derived edges between two node keys.
+     *
+     * Wraps `GET /explain?a=&b=`.
+     */
+    explain(a: string, b: string): Promise<Explanation[]>;
+    /**
+     * Create a derivation rule.
+     *
+     * Wraps `POST /rules`. The server acquires the write lock, validates the
+     * {@link RuleDef}, and backfills matching pairs.
+     */
+    createRule(def: RuleDef): Promise<void>;
+    /**
+     * Fetch a node by key.
+     *
+     * Wraps `GET /node/{key}`. Returns `null` when the server answers 404
+     * (unknown key). Other HTTP errors throw {@link MushroomError}.
+     */
+    node(key: string): Promise<NodeInfo | null>;
+    /**
+     * Depth-N neighborhood of a node.
+     *
+     * Wraps `GET /node/{key}/neighborhood`. Default depth is the server's
+     * (1). Columns are `key`, `label`, `depth`.
+     */
+    neighborhood(key: string, opts?: {
+        depth?: number;
+    }): Promise<Neighborhood>;
+    /**
+     * Subscribe to post-commit events over WebSocket (`GET /subscribe`).
+     *
+     * Returns a promise that resolves when the server acknowledges the
+     * subscription (`{"subscribed":true}`). After that, `onEvent` is called
+     * for each {@link DbEvent}, including {@link DbEvent.lagged} frames.
+     *
+     * **No auto-reconnect in v1.** When the connection drops, no further events
+     * are delivered. Reconnect manually if required.
+     *
+     * **Always await `handle.close()`** when done — an open WebSocket keeps the
+     * Node.js event loop alive and will cause test hangs.
+     *
+     * **Node.js < 21**: pass `wsConstructor` — see {@link SubscribeOptions}.
+     *
+     * @example
+     * ```ts
+     * import WS from 'ws';
+     * const handle = await client.subscribe(
+     *   { writes: true, wsConstructor: WS as WsConstructor },
+     *   (ev) => console.log(ev),
+     * );
+     * // ... do work ...
+     * await handle.close();
+     * ```
+     */
+    subscribe(opts: SubscribeOptions, onEvent: (event: import("./types.js").DbEvent) => void): Promise<SubscribeHandle>;
+}
+export type { SubscribeHandle, SubscribeOptions, WsConstructor };
+//# 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":"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"}

package/dist/client.js

@@ -0,0 +1,239 @@
+/**
+ * HTTP client for the mushroomdb server.
+ *
+ * Uses the browser-standard `fetch` API (built into Node 18+).
+ *
+ * ```ts
+ * import { MushroomClient } from 'mushroomdb-client';
+ *
+ * const client = new MushroomClient('http://127.0.0.1:8080');
+ * const result = await client.query('MATCH (n:Person) RETURN n.name LIMIT 10');
+ * console.log(result.columns, result.rows);
+ * ```
+ */
+import { MushroomError, } from "./types.js";
+import { subscribe as wsSubscribe, } from "./ws.js";
+export { MushroomError };
+/**
+ * HTTP + WebSocket client for mushroomdb.
+ *
+ * All methods use the browser-standard `fetch` API and are therefore
+ * compatible with both Node.js 18+ and modern browsers.
+ *
+ * **Node-only**: The `subscribe` method requires a WebSocket implementation.
+ * In Node < 21, install the `ws` package and pass `wsConstructor` in the
+ * subscribe options. See {@link SubscribeOptions}.
+ */
+export class MushroomClient {
+    baseUrl;
+    wsBase;
+    token;
+    /**
+     * @param baseUrl  HTTP base URL of the mushroomdb server, e.g.
+     *                 `"http://127.0.0.1:8080"`. Trailing slash is stripped.
+     * @param opts     Optional `{ token }` — sent as `Authorization: Bearer`.
+     */
+    constructor(baseUrl, opts) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.wsBase = this.baseUrl.replace(/^http/, "ws");
+        this.token = opts?.token;
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------------
+    url(path) {
+        return `${this.baseUrl}${path}`;
+    }
+    wsUrl(path) {
+        return `${this.wsBase}${path}`;
+    }
+    authHeaders() {
+        return this.token ? { Authorization: `Bearer ${this.token}` } : {};
+    }
+    /**
+     * Execute a fetch and decode the JSON body.
+     * Throws {@link MushroomError} on non-2xx responses.
+     */
+    async fetchJson(path, init) {
+        const resp = await fetch(this.url(path), {
+            ...init,
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                ...this.authHeaders(),
+                ...(init?.headers ?? {}),
+            },
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = await resp.json();
+        if (!resp.ok) {
+            const detail = typeof body?.error === "string" ? body.error : `HTTP ${resp.status}`;
+            throw new MushroomError(detail);
+        }
+        return body;
+    }
+    // -------------------------------------------------------------------------
+    // HTTP endpoints
+    // -------------------------------------------------------------------------
+    /**
+     * Run a Cypher query (read or write).
+     *
+     * The server auto-detects write statements (`CREATE`, `MERGE`, `SET`,
+     * `DELETE`) and acquires the appropriate lock. Both read and write queries
+     * go to `POST /query?format=json`.
+     *
+     * @param cypher Cypher query string.
+     * @param opts   Optional bound parameters (JSON scalar values only).
+     * @returns      Column names and a 2-D array of {@link CellValue} rows.
+     */
+    async query(cypher, opts) {
+        return this.fetchJson("/query?format=json", {
+            method: "POST",
+            body: JSON.stringify({
+                cypher,
+                ...(opts?.params ? { params: opts.params } : {}),
+            }),
+        });
+    }
+    /**
+     * Ingest nodes (and optional edges) into the database.
+     *
+     * Wraps `POST /ingest`. The server acquires the write lock, applies the
+     * rows to the WAL, and runs all rules incrementally.
+     *
+     * @param req  Ingest payload — `label`, `rows`, optional `options` and `edges`.
+     * @returns    Server ingest report (opaque; check for absence of errors).
+     */
+    async ingest(req) {
+        return this.fetchJson("/ingest", {
+            method: "POST",
+            body: JSON.stringify(req),
+        });
+    }
+    /**
+     * Get database-wide statistics.
+     *
+     * Wraps `GET /stats`. Returns live node/edge counts and per-rule stats.
+     */
+    async stats() {
+        return this.fetchJson("/stats");
+    }
+    /**
+     * Profile the database and return rule suggestions.
+     *
+     * Wraps `GET /suggest`. CPU-intensive — runs in the server's blocking
+     * thread-pool with a 5-second global budget. The {@link SuggestReport}
+     * includes a `truncated` flag when the budget fires early.
+     *
+     * Suggestions are not auto-applied; call `POST /rules` to create a rule.
+     */
+    async suggest() {
+        return this.fetchJson("/suggest");
+    }
+    async algo(algo, config) {
+        // The server structs carry #[serde(default)], so sending only the fields
+        // the caller explicitly set (or an empty body {}) is valid — the server
+        // fills in its own defaults for any missing fields.
+        return this.fetchJson(`/algo/${algo}`, {
+            method: "POST",
+            body: JSON.stringify(config ?? {}),
+        });
+    }
+    /**
+     * Explain rule-derived edges between two node keys.
+     *
+     * Wraps `GET /explain?a=&b=`.
+     */
+    async explain(a, b) {
+        const qs = new URLSearchParams({ a, b });
+        return this.fetchJson(`/explain?${qs.toString()}`);
+    }
+    /**
+     * Create a derivation rule.
+     *
+     * Wraps `POST /rules`. The server acquires the write lock, validates the
+     * {@link RuleDef}, and backfills matching pairs.
+     */
+    async createRule(def) {
+        await this.fetchJson("/rules", {
+            method: "POST",
+            body: JSON.stringify(def),
+        });
+    }
+    /**
+     * Fetch a node by key.
+     *
+     * Wraps `GET /node/{key}`. Returns `null` when the server answers 404
+     * (unknown key). Other HTTP errors throw {@link MushroomError}.
+     */
+    async node(key) {
+        const resp = await fetch(this.url(`/node/${encodeURIComponent(key)}`), {
+            headers: {
+                Accept: "application/json",
+                ...this.authHeaders(),
+            },
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = await resp.json();
+        if (resp.status === 404) {
+            return null;
+        }
+        if (!resp.ok) {
+            const detail = typeof body?.error === "string" ? body.error : `HTTP ${resp.status}`;
+            throw new MushroomError(detail);
+        }
+        return body;
+    }
+    /**
+     * Depth-N neighborhood of a node.
+     *
+     * Wraps `GET /node/{key}/neighborhood`. Default depth is the server's
+     * (1). Columns are `key`, `label`, `depth`.
+     */
+    async neighborhood(key, opts) {
+        const qs = new URLSearchParams();
+        if (opts?.depth !== undefined) {
+            qs.set("depth", String(opts.depth));
+        }
+        const query = qs.toString();
+        const path = `/node/${encodeURIComponent(key)}/neighborhood${query ? `?${query}` : ""}`;
+        return this.fetchJson(path);
+    }
+    // -------------------------------------------------------------------------
+    // WebSocket
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to post-commit events over WebSocket (`GET /subscribe`).
+     *
+     * Returns a promise that resolves when the server acknowledges the
+     * subscription (`{"subscribed":true}`). After that, `onEvent` is called
+     * for each {@link DbEvent}, including {@link DbEvent.lagged} frames.
+     *
+     * **No auto-reconnect in v1.** When the connection drops, no further events
+     * are delivered. Reconnect manually if required.
+     *
+     * **Always await `handle.close()`** when done — an open WebSocket keeps the
+     * Node.js event loop alive and will cause test hangs.
+     *
+     * **Node.js < 21**: pass `wsConstructor` — see {@link SubscribeOptions}.
+     *
+     * @example
+     * ```ts
+     * import WS from 'ws';
+     * const handle = await client.subscribe(
+     *   { writes: true, wsConstructor: WS as WsConstructor },
+     *   (ev) => console.log(ev),
+     * );
+     * // ... do work ...
+     * await handle.close();
+     * ```
+     */
+    subscribe(opts, onEvent) {
+        let url = this.wsUrl("/subscribe");
+        if (this.token) {
+            url += `?token=${encodeURIComponent(this.token)}`;
+        }
+        return wsSubscribe(url, opts, onEvent);
+    }
+}
+//# sourceMappingURL=client.js.map