@calimero-network/mero-js 13.0.0 → 13.1.0

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export type { MigrateMyEntriesSummary } from './rpc/index.js';
 export type { ExecuteParams } from './rpc/index.js';
 export { SseClient, WsClient } from './events/index.js';
 export type { SseEventData, WsEventData, AppVersionChangedEvent, GroupMembershipEventData, GroupMigrationEventData, MigrationStartedData, MigrationProgressData, CascadeProgressData, MigrationCompletedData, } from './events/index.js';
+export { EphemeralClient, jsonCodec } from './ephemeral/index.js';
+export type { Codec, EphemeralEntry } from './ephemeral/index.js';
 export * from './cloud/index.js';
 export * from './capabilities.js';
 export { DEFAULT_LOCAL_NODE_PORTS, localNodeUrl, nodeEndpoint, probeNodeHealth, discoverLocalNodes, } from './nodeDiscovery.js';

package/dist/index.js

@@ -16,6 +16,8 @@ export { MemoryTokenStore, LocalStorageTokenStore } from './token-store/index.js
 export { RpcClient, RpcError } from './rpc/index.js';
 // Events (SSE / WebSocket)
 export { SseClient, WsClient } from './events/index.js';
+// Ephemeral presence (cursors / typing / online)
+export { EphemeralClient, jsonCodec } from './ephemeral/index.js';
 // Cloud client (enable-HA, disable-HA)
 export * from './cloud/index.js';
 // Member capability bitmask constants & helpers

package/dist/index.mjs

@@ -1472,35 +1472,33 @@ var RpcError = class extends Error {
     this.type = type;
   }
 };
+async function jsonRpcCall(httpClient, method, params) {
+  const response = await httpClient.post("/jsonrpc", {
+    jsonrpc: "2.0",
+    id: 1,
+    method,
+    params
+  });
+  if (response.error) {
+    const err = response.error;
+    throw new RpcError(err.code ?? -1, err.message ?? err.type ?? "RPC error", err.data, err.type);
+  }
+  return response.result;
+}
 var RpcClient = class {
   constructor(opts) {
     this.httpClient = opts.httpClient;
   }
   async execute(params) {
-    const body = {
-      jsonrpc: "2.0",
-      id: 1,
-      method: "execute",
-      params: {
-        contextId: params.contextId,
-        method: params.method,
-        argsJson: params.argsJson ?? {}
-      }
-    };
-    const response = await this.httpClient.post(
-      "/jsonrpc",
-      body
-    );
-    if (response.error) {
-      const err = response.error;
-      const code = err.code ?? -1;
-      const message = err.message ?? err.type ?? "RPC error";
-      throw new RpcError(code, message, err.data, err.type);
-    }
-    if (response.result && "output" in response.result) {
-      return response.result.output;
+    const result = await jsonRpcCall(this.httpClient, "execute", {
+      contextId: params.contextId,
+      method: params.method,
+      argsJson: params.argsJson ?? {}
+    });
+    if (result && "output" in result) {
+      return result.output;
     }
-    return response.result;
+    return result;
   }
   /**
    * One-tap owner-driven convert: re-signs the caller's identity-gated entries
@@ -1991,6 +1989,72 @@ var _WsClient = class _WsClient {
 _WsClient.MAX_BACKOFF_MS = 3e4;
 var WsClient = _WsClient;
 
+// src/ephemeral/codec.ts
+function jsonCodec() {
+  return {
+    encode(value) {
+      return Array.from(new TextEncoder().encode(JSON.stringify(value)));
+    },
+    decode(bytes) {
+      return JSON.parse(new TextDecoder().decode(new Uint8Array(bytes)));
+    }
+  };
+}
+
+// src/ephemeral/index.ts
+var EphemeralClient = class {
+  constructor(opts) {
+    this.httpClient = opts.httpClient;
+    this.sse = opts.sse;
+  }
+  /**
+   * Publish your own presence slice, replacing it wholesale.
+   *
+   * Rejects with an `RpcError` (not a bare `Error`), so a typed failure such as
+   * an oversized slice keeps its `type` and `data` — e.g. `SliceTooLarge` with
+   * the offending size — and is `instanceof RpcError` like every other RPC in
+   * this SDK.
+   */
+  async set(contextId, state, codec = jsonCodec()) {
+    await jsonRpcCall(this.httpClient, "set_ephemeral", {
+      contextId,
+      state: codec.encode(state)
+    });
+  }
+  /**
+   * Observe presence changes for a context.
+   *
+   * This adds NO transport — it is a typed filter over the existing SSE event
+   * stream, which already carries `{ contextId, type, data }`. On subscribing,
+   * the node replays that context's current presence to this connection as
+   * ordinary `Ephemeral` events before any live deltas; a replayed entry
+   * carries `ageMs`, a live delta does not (never synthesized as `0` — absent
+   * and zero mean different things). Returns an unsubscribe function.
+   */
+  subscribe(contextId, handler, codec = jsonCodec()) {
+    const listener = (event) => {
+      const e = event;
+      if (e.type !== "Ephemeral" || e.contextId !== contextId) return;
+      const data = e.data;
+      if (!data?.author) return;
+      const removed = Boolean(data.removed);
+      const entry = {
+        author: data.author,
+        state: removed || data.state === void 0 ? void 0 : codec.decode(data.state),
+        removed
+      };
+      if (data.ageMs !== void 0) entry.ageMs = data.ageMs;
+      handler(entry);
+    };
+    this.sse.on("event", listener);
+    void this.sse.connect().catch(() => void 0);
+    void this.sse.subscribe([contextId]).catch(() => void 0);
+    return () => {
+      this.sse.off("event", listener);
+    };
+  }
+};
+
 // src/mero-js.ts
 var REFRESH_LOCK_NAME = "mero-js:token-refresh";
 function getLockManager() {
@@ -2109,6 +2173,21 @@ var MeroJs = class {
     }
     return this.sseClient;
   }
+  /**
+   * Get the ephemeral-presence client (lazy initialized).
+   *
+   * Shares this instance's SSE client, so `subscribe` reuses the one event
+   * stream rather than opening a second connection.
+   */
+  get ephemeral() {
+    if (!this.ephemeralClient) {
+      this.ephemeralClient = new EphemeralClient({
+        httpClient: this.httpClient,
+        sse: this.events
+      });
+    }
+    return this.ephemeralClient;
+  }
   /**
    * Get the WebSocket event client (lazy initialized).
    * @experimental Use `events` (SSE) for production. WsClient is experimental.
@@ -2462,6 +2541,7 @@ export {
   CAPABILITIES,
   CloudClient,
   DEFAULT_LOCAL_NODE_PORTS,
+  EphemeralClient,
   HTTPError,
   LocalStorageTokenStore,
   MemoryTokenStore,
@@ -2491,6 +2571,7 @@ export {
   createUniversalHttpClient,
   discoverLocalNodes,
   hasCap,
+  jsonCodec,
   localNodeUrl,
   nodeEndpoint,
   parseAuthCallback,