@calimero-network/mero-js 13.0.0 → 13.2.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './auth-api/index.js';
 export * from './admin-api/index.js';
 export { parseAuthCallback, buildAuthLoginUrl } from './auth/index.js';
 export type { AuthCallbackResult, AuthLoginOptions } from './auth/index.js';
+export { toAccountHex, toAccountBase58, sameAccount, } from './account/index.js';
 export { MemoryTokenStore, LocalStorageTokenStore } from './token-store/index.js';
 export type { TokenStore } from './token-store/index.js';
 export { RpcClient, RpcError } from './rpc/index.js';
@@ -12,6 +13,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

@@ -10,12 +10,16 @@ export * from './auth-api/index.js';
 export * from './admin-api/index.js';
 // Auth utilities
 export { parseAuthCallback, buildAuthLoginUrl } from './auth/index.js';
+// Account id encoding (hex on the admin API, base58 in contract data)
+export { toAccountHex, toAccountBase58, sameAccount, } from './account/index.js';
 // Token store
 export { MemoryTokenStore, LocalStorageTokenStore } from './token-store/index.js';
 // RPC client
 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
@@ -1529,6 +1527,7 @@ function isGroupMigrationEvent(event) {
 }
 
 // src/events/sse.ts
+var TERMINAL_AUTH_ERRORS2 = /* @__PURE__ */ new Set(["token_reuse", "token_revoked"]);
 var SseClient = class {
   constructor(opts) {
     this.sessionId = null;
@@ -1606,7 +1605,8 @@ var SseClient = class {
     this.abortController = new AbortController();
     try {
       const token = await this.getAuthToken();
-      const response = await fetch(`${this.baseUrl}/sse`, {
+      const url = `${this.baseUrl}/sse`;
+      const response = await fetch(url, {
         headers: {
           "Authorization": `Bearer ${token}`,
           "Accept": "text/event-stream"
@@ -1614,7 +1614,25 @@ var SseClient = class {
         signal: this.abortController.signal
       });
       if (!response.ok) {
-        throw new Error(`SSE connection failed: ${response.status}`);
+        const authError = response.headers.get("x-auth-error");
+        const bodyText = await response.text().catch(() => void 0);
+        if (response.status === 401 && authError && TERMINAL_AUTH_ERRORS2.has(authError)) {
+          throw new AuthRevokedError(
+            authError,
+            response.status,
+            response.statusText,
+            url,
+            response.headers,
+            bodyText
+          );
+        }
+        throw new HTTPError(
+          response.status,
+          response.statusText,
+          url,
+          response.headers,
+          bodyText
+        );
       }
       if (!response.body) {
         throw new Error("SSE response has no body");
@@ -1991,6 +2009,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 +2193,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.
@@ -2299,6 +2398,93 @@ function createMeroJs(config) {
   return new MeroJs(config);
 }
 
+// src/account/index.ts
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var HEX_ACCOUNT = /^[0-9a-f]{64}$/i;
+function encodeBase58(bytes) {
+  if (bytes.length === 0) return "";
+  const digits = [0];
+  for (const byte of bytes) {
+    let carry = byte;
+    for (let i = 0; i < digits.length; i++) {
+      carry += digits[i] << 8;
+      digits[i] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "";
+  for (const byte of bytes) {
+    if (byte !== 0) break;
+    out += BASE58_ALPHABET[0];
+  }
+  for (let i = digits.length - 1; i >= 0; i--) {
+    out += BASE58_ALPHABET[digits[i]];
+  }
+  return out;
+}
+function decodeBase58(value) {
+  if (value.length === 0) return null;
+  const bytes = [0];
+  for (const char of value) {
+    const index = BASE58_ALPHABET.indexOf(char);
+    if (index < 0) return null;
+    let carry = index;
+    for (let i = 0; i < bytes.length; i++) {
+      carry += bytes[i] * 58;
+      bytes[i] = carry & 255;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  let leadingZeros = 0;
+  for (const char of value) {
+    if (char !== BASE58_ALPHABET[0]) break;
+    leadingZeros++;
+  }
+  return Uint8Array.from([
+    ...new Array(leadingZeros).fill(0),
+    ...bytes.reverse()
+  ]);
+}
+function toHex(bytes) {
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
+function fromHex(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function toAccountHex(id) {
+  const trimmed = (id ?? "").trim();
+  if (!trimmed) return "";
+  if (HEX_ACCOUNT.test(trimmed)) return trimmed.toLowerCase();
+  const decoded = decodeBase58(trimmed);
+  if (!decoded || decoded.length !== 32) return trimmed;
+  return toHex(decoded);
+}
+function toAccountBase58(id) {
+  const trimmed = (id ?? "").trim();
+  if (!trimmed) return "";
+  if (!HEX_ACCOUNT.test(trimmed)) return trimmed;
+  return encodeBase58(fromHex(trimmed));
+}
+function sameAccount(a, b) {
+  const left = toAccountHex(a);
+  const right = toAccountHex(b);
+  return HEX_ACCOUNT.test(left) && left === right;
+}
+
 // src/token-store/index.ts
 var MemoryTokenStore = class {
   constructor() {
@@ -2462,6 +2648,7 @@ export {
   CAPABILITIES,
   CloudClient,
   DEFAULT_LOCAL_NODE_PORTS,
+  EphemeralClient,
   HTTPError,
   LocalStorageTokenStore,
   MemoryTokenStore,
@@ -2491,10 +2678,14 @@ export {
   createUniversalHttpClient,
   discoverLocalNodes,
   hasCap,
+  jsonCodec,
   localNodeUrl,
   nodeEndpoint,
   parseAuthCallback,
   probeNodeHealth,
+  sameAccount,
+  toAccountBase58,
+  toAccountHex,
   withCap,
   withRetry,
   withoutCap