@calimero-network/mero-js 1.1.0 → 1.2.1

package/dist/index.cjs

@@ -22,8 +22,15 @@ __export(index_exports, {
   AdminApiClient: () => AdminApiClient,
   AuthApiClient: () => AuthApiClient,
   HTTPError: () => HTTPError,
+  LocalStorageTokenStore: () => LocalStorageTokenStore,
+  MemoryTokenStore: () => MemoryTokenStore,
   MeroJs: () => MeroJs,
+  RpcClient: () => RpcClient,
+  RpcError: () => RpcError,
+  SseClient: () => SseClient,
   WebHttpClient: () => WebHttpClient,
+  WsClient: () => WsClient,
+  buildAuthLoginUrl: () => buildAuthLoginUrl,
   combineSignals: () => combineSignals,
   createAdminApiClient: () => createAdminApiClient,
   createAdminApiClientFromHttpClient: () => createAdminApiClientFromHttpClient,
@@ -40,6 +47,7 @@ __export(index_exports, {
   createRetryableMethod: () => createRetryableMethod,
   createTimeoutSignal: () => createTimeoutSignal,
   createUniversalHttpClient: () => createUniversalHttpClient,
+  parseAuthCallback: () => parseAuthCallback,
   withRetry: () => withRetry
 });
 module.exports = __toCommonJS(index_exports);
@@ -243,8 +251,7 @@ var WebHttpClient = class {
           bodyText
         );
         const userAborted = init?.signal?.aborted === true;
-        if (response.status === 401 && this.transport.refreshToken && response.headers.get("x-auth-error") === "token_expired" && retryCount < MAX_RETRY_ATTEMPTS && !isStreamBody && // Can't retry with stream bodies
-        !userAborted) {
+        if (response.status === 401 && this.transport.refreshToken && response.headers.get("x-auth-error") === "token_expired" && retryCount < MAX_RETRY_ATTEMPTS && !isStreamBody && !userAborted) {
           try {
             let refreshPromise = this.refreshTokenPromise;
             if (!refreshPromise) {
@@ -682,122 +689,117 @@ function createAuthApiClientFromHttpClient(httpClient, _config) {
 }
 
 // src/admin-api/admin-client.ts
+function unwrap(response) {
+  return response.data;
+}
 var AdminApiClient = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
-  // Health and Status Endpoints
+  // ---- Health and Status (public, no auth) ----
   async healthCheck() {
-    const response = await this.httpClient.get("/health");
-    if (!response.data) {
-      throw new Error("Health response data is null");
-    }
-    return response.data;
+    return unwrap(await this.httpClient.get("/admin-api/health"));
   }
   async isAuthed() {
-    return this.httpClient.get("/is-authed");
+    return this.httpClient.get("/admin-api/is-authed");
   }
-  // Application Management Endpoints
+  // ---- Application Management ----
   async installApplication(request) {
-    return this.httpClient.post(
-      "/install-application",
-      request
-    );
+    return unwrap(await this.httpClient.post("/admin-api/install-application", request));
   }
   async installDevApplication(request) {
-    return this.httpClient.post(
-      "/install-dev-application",
-      request
-    );
+    return unwrap(await this.httpClient.post("/admin-api/install-dev-application", request));
   }
   async uninstallApplication(appId) {
-    return this.httpClient.delete(
-      `/applications/${appId}`
-    );
+    return unwrap(await this.httpClient.delete(`/admin-api/applications/${appId}`));
   }
   async listApplications() {
-    return this.httpClient.get("/applications");
+    return unwrap(await this.httpClient.get("/admin-api/applications"));
   }
   async getApplication(appId) {
+    return unwrap(await this.httpClient.get(`/admin-api/applications/${appId}`));
+  }
+  // ---- Package Management ----
+  async getLatestPackageVersion(packageName) {
     return this.httpClient.get(
-      `/applications/${appId}`
+      `/admin-api/packages/${encodeURIComponent(packageName)}/latest`
     );
   }
-  // Context Management Endpoints
+  // ---- Context Management ----
   async createContext(request) {
-    return this.httpClient.post("/contexts", request);
+    return unwrap(await this.httpClient.post("/admin-api/contexts", request));
   }
   async deleteContext(contextId) {
-    return this.httpClient.delete(
-      `/contexts/${contextId}`
-    );
+    return unwrap(await this.httpClient.delete(`/admin-api/contexts/${contextId}`));
   }
   async getContexts() {
-    return this.httpClient.get("/contexts");
+    return unwrap(await this.httpClient.get("/admin-api/contexts"));
   }
   async getContext(contextId) {
-    return this.httpClient.get(`/contexts/${contextId}`);
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}`));
   }
-  // Blob Management Endpoints
-  async uploadBlob(request) {
-    return this.httpClient.post("/blobs", request);
+  async getContextsForApplication(applicationId) {
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/for-application/${applicationId}`));
   }
-  async deleteBlob(blobId) {
-    return this.httpClient.delete(`/blobs/${blobId}`);
+  // ---- Context Identity ----
+  async generateContextIdentity() {
+    return unwrap(await this.httpClient.post("/admin-api/identity/context", {}));
   }
-  async listBlobs() {
-    return this.httpClient.get("/blobs");
+  async getContextIdentities(contextId) {
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/identities`));
   }
-  async getBlob(blobId) {
-    return this.httpClient.get(`/blobs/${blobId}`);
+  async getContextIdentitiesOwned(contextId) {
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/identities-owned`));
   }
-  // Alias Management Endpoints
-  async createAlias(request) {
-    return this.httpClient.post("/alias", request);
+  // ---- Context Invite / Join ----
+  async inviteToContext(request) {
+    return unwrap(await this.httpClient.post("/admin-api/contexts/invite", request));
   }
-  async deleteAlias(aliasId) {
-    return this.httpClient.delete(`/alias/${aliasId}`);
+  async joinContext(request) {
+    return unwrap(await this.httpClient.post("/admin-api/contexts/join", request));
   }
-  async listAliases() {
-    return this.httpClient.get("/alias");
+  // ---- Blob Management ----
+  async uploadBlob(data) {
+    return unwrap(await this.httpClient.put("/admin-api/blobs", data));
   }
-  async getAlias(aliasId) {
-    return this.httpClient.get(`/alias/${aliasId}`);
+  async deleteBlob(blobId) {
+    return unwrap(await this.httpClient.delete(`/admin-api/blobs/${blobId}`));
   }
-  // Network Management Endpoints
-  async getNetworkPeers() {
-    return this.httpClient.get("/network/peers");
+  async listBlobs() {
+    return unwrap(await this.httpClient.get("/admin-api/blobs"));
   }
-  async getNetworkStats() {
-    return this.httpClient.get("/network/stats");
+  async getBlob(blobId) {
+    return unwrap(await this.httpClient.get(`/admin-api/blobs/${blobId}`));
   }
-  async getNetworkConfig() {
-    return this.httpClient.get("/network/config");
+  // ---- Alias Management ----
+  // Server uses type-specific alias routes: /admin-api/alias/{create,lookup,delete,list}/{context,application}
+  async createContextAlias(request) {
+    return this.httpClient.post("/admin-api/alias/create/context", request);
   }
-  async updateNetworkConfig(request) {
-    return this.httpClient.put(
-      "/network/config",
-      request
-    );
+  async createApplicationAlias(request) {
+    return this.httpClient.post("/admin-api/alias/create/application", request);
   }
-  async getPeersCount() {
-    return this.httpClient.get("/network/peers/count");
+  async lookupContextAlias(name) {
+    return this.httpClient.post(`/admin-api/alias/lookup/context/${encodeURIComponent(name)}`, {});
+  }
+  async lookupApplicationAlias(name) {
+    return this.httpClient.post(`/admin-api/alias/lookup/application/${encodeURIComponent(name)}`, {});
   }
-  // System Management Endpoints
-  async getSystemInfo() {
-    return this.httpClient.get("/system/info");
+  async deleteContextAlias(name) {
+    return this.httpClient.post(`/admin-api/alias/delete/context/${encodeURIComponent(name)}`, {});
   }
-  async getSystemLogs() {
-    return this.httpClient.get("/system/logs");
+  async deleteApplicationAlias(name) {
+    return this.httpClient.post(`/admin-api/alias/delete/application/${encodeURIComponent(name)}`, {});
   }
-  async getSystemMetrics() {
-    return this.httpClient.get("/system/metrics");
+  async listContextAliases() {
+    return unwrap(await this.httpClient.get("/admin-api/alias/list/context"));
   }
-  async restartSystem() {
-    return this.httpClient.post("/system/restart");
+  async listApplicationAliases() {
+    return unwrap(await this.httpClient.get("/admin-api/alias/list/application"));
   }
-  async shutdownSystem() {
-    return this.httpClient.post("/system/shutdown");
+  // ---- Network ----
+  async getPeersCount() {
+    return this.httpClient.get("/admin-api/peers");
   }
 };
 
@@ -855,15 +857,495 @@ function createAdminApiClientFromHttpClient(httpClient, _config) {
   return new AdminApiClient(httpClient);
 }
 
+// src/auth/index.ts
+function parseAuthCallback(url) {
+  try {
+    const hashIndex = url.indexOf("#");
+    if (hashIndex === -1) return null;
+    const hash = url.substring(hashIndex + 1);
+    const params = new URLSearchParams(hash);
+    const accessToken = params.get("access_token");
+    if (!accessToken) return null;
+    return {
+      accessToken,
+      refreshToken: params.get("refresh_token") ?? "",
+      applicationId: params.get("application_id") ?? "",
+      contextId: params.get("context_id") ?? "",
+      contextIdentity: params.get("context_identity") ?? "",
+      nodeUrl: params.get("node_url") ?? ""
+    };
+  } catch {
+    return null;
+  }
+}
+function buildAuthLoginUrl(nodeUrl, opts) {
+  const params = new URLSearchParams();
+  params.set("callback-url", opts.callbackUrl);
+  if (opts.permissions && opts.permissions.length > 0) {
+    params.set("permissions", opts.permissions.join(","));
+  }
+  params.set("mode", opts.mode);
+  if (opts.packageName) {
+    params.set("package-name", opts.packageName);
+    if (opts.packageVersion) {
+      params.set("package-version", opts.packageVersion);
+    }
+    if (opts.registryUrl) {
+      params.set("registry-url", opts.registryUrl);
+    }
+  }
+  const base = nodeUrl.replace(/\/+$/, "");
+  return `${base}/auth/login?${params.toString()}`;
+}
+
+// src/rpc/index.ts
+var RpcError = class extends Error {
+  constructor(code, message, data, type) {
+    super(message);
+    this.name = "RpcError";
+    this.code = code;
+    this.data = data;
+    this.type = type;
+  }
+};
+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 ?? {},
+        executorPublicKey: params.executorPublicKey
+      }
+    };
+    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;
+    }
+    return response.result;
+  }
+};
+
+// src/events/sse.ts
+var SseClient = class {
+  constructor(opts) {
+    this.sessionId = null;
+    this.abortController = null;
+    this.reconnectTimer = null;
+    this.subscribedContextIds = /* @__PURE__ */ new Set();
+    this.closed = false;
+    this.listeners = { connect: [], event: [], error: [] };
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.getAuthToken = opts.getAuthToken;
+    this.reconnectDelayMs = opts.reconnectDelayMs ?? 3e3;
+  }
+  on(event, handler) {
+    const key = event;
+    if (key in this.listeners) {
+      const arr = this.listeners[key];
+      if (!arr.includes(handler)) arr.push(handler);
+    }
+  }
+  off(event, handler) {
+    const key = event;
+    if (key in this.listeners) {
+      const arr = this.listeners[key];
+      const idx = arr.indexOf(handler);
+      if (idx !== -1) arr.splice(idx, 1);
+    }
+  }
+  emit(event, arg) {
+    const key = event;
+    if (key in this.listeners) {
+      for (const handler of this.listeners[key]) {
+        try {
+          handler(arg);
+        } catch {
+        }
+      }
+    }
+  }
+  async connect() {
+    if (this.abortController && !this.closed) {
+      return;
+    }
+    this.closed = false;
+    this.abortController = new AbortController();
+    try {
+      const token = await this.getAuthToken();
+      const response = await fetch(`${this.baseUrl}/sse`, {
+        headers: {
+          "Authorization": `Bearer ${token}`,
+          "Accept": "text/event-stream"
+        },
+        signal: this.abortController.signal
+      });
+      if (!response.ok) {
+        throw new Error(`SSE connection failed: ${response.status}`);
+      }
+      if (!response.body) {
+        throw new Error("SSE response has no body");
+      }
+      this.readStream(response.body).catch((err) => {
+        if (this.closed) return;
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.emit("error", error);
+        this.scheduleReconnect();
+      });
+    } catch (err) {
+      if (this.closed) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", error);
+      this.scheduleReconnect();
+    }
+  }
+  async readStream(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.startsWith("data:")) {
+            const jsonStr = line.slice(5).trim();
+            if (jsonStr) {
+              this.handleMessage(jsonStr);
+            }
+          }
+        }
+      }
+      buffer += decoder.decode();
+      if (buffer.startsWith("data:")) {
+        const jsonStr = buffer.slice(5).trim();
+        if (jsonStr) {
+          this.handleMessage(jsonStr);
+        }
+      }
+    } catch (err) {
+      if (this.closed) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", error);
+    }
+    if (!this.closed) {
+      this.scheduleReconnect();
+    }
+  }
+  handleMessage(jsonStr) {
+    try {
+      const msg = JSON.parse(jsonStr);
+      if (msg.type === "connect" && msg.session_id) {
+        this.sessionId = msg.session_id;
+        this.emit("connect", msg.session_id);
+        if (this.subscribedContextIds.size > 0) {
+          this.sendSubscription("subscribe", [...this.subscribedContextIds]);
+        }
+        return;
+      }
+      if (msg.result && msg.result.contextId) {
+        let eventData = msg.result.data;
+        if (Array.isArray(eventData)) {
+          try {
+            const bytes = new Uint8Array(eventData);
+            const text = new TextDecoder().decode(bytes);
+            eventData = JSON.parse(text);
+          } catch {
+          }
+        }
+        this.emit("event", {
+          contextId: msg.result.contextId,
+          data: eventData
+        });
+      }
+    } catch {
+    }
+  }
+  async subscribe(contextIds) {
+    const newIds = contextIds.filter((id) => !this.subscribedContextIds.has(id));
+    for (const id of contextIds) {
+      this.subscribedContextIds.add(id);
+    }
+    if (newIds.length > 0 && this.sessionId) {
+      await this.sendSubscription("subscribe", newIds);
+    }
+  }
+  async unsubscribe(contextIds) {
+    const hadIds = contextIds.filter((id) => this.subscribedContextIds.has(id));
+    for (const id of contextIds) {
+      this.subscribedContextIds.delete(id);
+    }
+    if (hadIds.length > 0 && this.sessionId) {
+      await this.sendSubscription("unsubscribe", hadIds);
+    }
+  }
+  async sendSubscription(method, contextIds) {
+    try {
+      const token = await this.getAuthToken();
+      const response = await fetch(`${this.baseUrl}/sse/subscription`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          id: this.sessionId,
+          method,
+          params: { contextIds }
+        })
+      });
+      if (!response.ok) {
+        this.emit("error", new Error(`SSE ${method} failed: ${response.status}`));
+      }
+    } catch (err) {
+      this.emit("error", err instanceof Error ? err : new Error(`SSE ${method} failed`));
+    }
+  }
+  forceReconnect() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.sessionId = null;
+    this.connect();
+  }
+  scheduleReconnect() {
+    if (this.closed) return;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.forceReconnect();
+    }, this.reconnectDelayMs);
+  }
+  close() {
+    this.closed = true;
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.sessionId = null;
+    this.subscribedContextIds.clear();
+  }
+};
+
+// src/events/ws.ts
+var _WsClient = class _WsClient {
+  constructor(opts) {
+    this.ws = null;
+    this.closed = false;
+    this.reconnectAttempt = 0;
+    this.reconnectTimer = null;
+    this.subscribedContextIds = /* @__PURE__ */ new Set();
+    this.listeners = { connect: [], event: [], error: [] };
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.getAuthToken = opts.getAuthToken;
+  }
+  on(event, handler) {
+    const key = event;
+    if (key in this.listeners) {
+      const arr = this.listeners[key];
+      if (!arr.includes(handler)) arr.push(handler);
+    }
+  }
+  off(event, handler) {
+    const key = event;
+    if (key in this.listeners) {
+      const arr = this.listeners[key];
+      const idx = arr.indexOf(handler);
+      if (idx !== -1) arr.splice(idx, 1);
+    }
+  }
+  emit(event, arg) {
+    const key = event;
+    if (key in this.listeners) {
+      for (const handler of this.listeners[key]) {
+        try {
+          handler(arg);
+        } catch {
+        }
+      }
+    }
+  }
+  async connect() {
+    if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
+      return;
+    }
+    this.closed = false;
+    try {
+      const token = await this.getAuthToken();
+      if (!token) {
+        throw new Error("No authentication token available for WebSocket connection");
+      }
+      const wsUrl = this.baseUrl.replace(/^http/, "ws");
+      this.ws = new WebSocket(`${wsUrl}/ws?token=${encodeURIComponent(token)}`);
+      this.ws.onopen = () => {
+        this.reconnectAttempt = 0;
+        this.emit("connect");
+        if (this.subscribedContextIds.size > 0) {
+          this.sendMessage({
+            id: null,
+            method: "subscribe",
+            params: { contextIds: [...this.subscribedContextIds] }
+          });
+        }
+      };
+      this.ws.onmessage = (event) => {
+        this.handleMessage(event.data);
+      };
+      this.ws.onerror = () => {
+        this.emit("error", new Error("WebSocket error"));
+      };
+      this.ws.onclose = () => {
+        if (!this.closed) {
+          this.scheduleReconnect();
+        }
+      };
+    } catch (err) {
+      if (this.closed) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", error);
+      this.scheduleReconnect();
+    }
+  }
+  handleMessage(raw) {
+    if (typeof raw !== "string") return;
+    try {
+      const msg = JSON.parse(raw);
+      if (msg.result && msg.result.contextId) {
+        let eventData = msg.result.data;
+        if (Array.isArray(eventData)) {
+          try {
+            const bytes = new Uint8Array(eventData);
+            const text = new TextDecoder().decode(bytes);
+            eventData = JSON.parse(text);
+          } catch {
+          }
+        }
+        this.emit("event", {
+          contextId: msg.result.contextId,
+          data: eventData
+        });
+      }
+    } catch {
+    }
+  }
+  subscribe(contextIds) {
+    for (const id of contextIds) {
+      this.subscribedContextIds.add(id);
+    }
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.sendMessage({
+        id: null,
+        method: "subscribe",
+        params: { contextIds }
+      });
+    }
+  }
+  unsubscribe(contextIds) {
+    for (const id of contextIds) {
+      this.subscribedContextIds.delete(id);
+    }
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.sendMessage({
+        id: null,
+        method: "unsubscribe",
+        params: { contextIds }
+      });
+    }
+  }
+  sendMessage(msg) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+  scheduleReconnect() {
+    if (this.closed) return;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+    const delay = Math.min(
+      1e3 * Math.pow(2, this.reconnectAttempt),
+      _WsClient.MAX_BACKOFF_MS
+    );
+    this.reconnectAttempt++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+  close() {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.close();
+      this.ws = null;
+    }
+    this.subscribedContextIds.clear();
+  }
+};
+_WsClient.MAX_BACKOFF_MS = 3e4;
+var WsClient = _WsClient;
+
 // src/mero-js.ts
+function expiresAtFromJwt(token, fallbackMs) {
+  try {
+    const parts = token.split(".");
+    if (parts.length === 3) {
+      let b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+      while (b64.length % 4) b64 += "=";
+      const payload = JSON.parse(atob(b64));
+      if (typeof payload.exp === "number") {
+        return payload.exp * 1e3;
+      }
+    }
+  } catch {
+  }
+  return fallbackMs;
+}
 var MeroJs = class {
   constructor(config) {
     this.tokenData = null;
     this.refreshPromise = null;
+    this.rpcClient = null;
+    this.sseClient = null;
+    this.wsClient = null;
+    this.wsWarned = false;
     this.config = {
       timeoutMs: 1e4,
       ...config
     };
+    this.tokenStore = config.tokenStore ?? null;
+    if (this.tokenStore) {
+      this.tokenData = this.tokenStore.getTokens();
+    }
     const isTauri = typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
     this.httpClient = createBrowserHttpClient({
       baseUrl: this.config.baseUrl,
@@ -871,6 +1353,16 @@ var MeroJs = class {
         const token = await this.getValidToken();
         return token?.access_token || "";
       },
+      refreshToken: async () => {
+        const refreshed = await this.performTokenRefresh();
+        return refreshed.access_token;
+      },
+      onTokenRefresh: async (newToken) => {
+        if (this.tokenData) {
+          this.tokenData.access_token = newToken;
+          this.tokenStore?.setTokens(this.tokenData);
+        }
+      },
       timeoutMs: this.config.timeoutMs,
       credentials: this.config.requestCredentials ?? (isTauri ? "omit" : void 0)
     });
@@ -903,6 +1395,50 @@ var MeroJs = class {
   get admin() {
     return this.adminClient;
   }
+  /**
+   * Get the RPC client (lazy initialized)
+   */
+  get rpc() {
+    if (!this.rpcClient) {
+      this.rpcClient = new RpcClient({ httpClient: this.httpClient });
+    }
+    return this.rpcClient;
+  }
+  /**
+   * Get the SSE event client (lazy initialized)
+   */
+  get events() {
+    if (!this.sseClient) {
+      this.sseClient = new SseClient({
+        baseUrl: this.config.baseUrl,
+        getAuthToken: async () => {
+          const token = await this.getValidToken();
+          return token?.access_token || "";
+        }
+      });
+    }
+    return this.sseClient;
+  }
+  /**
+   * Get the WebSocket event client (lazy initialized).
+   * @experimental Use `events` (SSE) for production. WsClient is experimental.
+   */
+  get ws() {
+    if (!this.wsWarned) {
+      this.wsWarned = true;
+      console.warn("[mero-js] WsClient is experimental. Use mero.events (SSE) for production.");
+    }
+    if (!this.wsClient) {
+      this.wsClient = new WsClient({
+        baseUrl: this.config.baseUrl,
+        getAuthToken: async () => {
+          const token = await this.getValidToken();
+          return token?.access_token || "";
+        }
+      });
+    }
+    return this.wsClient;
+  }
   /**
    * Authenticate with the provided credentials
    * This will create the root key on first use
@@ -925,12 +1461,13 @@ var MeroJs = class {
         }
       };
       const response = await this.authClient.generateTokens(requestBody);
+      const accessToken = response.data.access_token;
       this.tokenData = {
-        access_token: response.data.access_token,
+        access_token: accessToken,
         refresh_token: response.data.refresh_token,
-        expires_at: Date.now() + 24 * 60 * 60 * 1e3
-        // Default to 24 hours
+        expires_at: expiresAtFromJwt(accessToken, Date.now() + 36e5)
       };
+      this.tokenStore?.setTokens(this.tokenData);
       return this.tokenData;
     } catch (error) {
       throw new Error(
@@ -939,16 +1476,12 @@ var MeroJs = class {
     }
   }
   /**
-   * Get a valid token, refreshing if necessary
+   * Get a valid token. Returns the current token as-is.
+   * The server rejects refresh attempts while the access token is still valid,
+   * so we never proactively refresh. Instead, the WebHttpClient handles 401
+   * responses reactively via the refreshToken transport hook.
    */
   async getValidToken() {
-    if (!this.tokenData) {
-      return null;
-    }
-    const bufferTime = 5 * 60 * 1e3;
-    if (Date.now() >= this.tokenData.expires_at - bufferTime) {
-      return await this.refreshToken();
-    }
     return this.tokenData;
   }
   /**
@@ -981,15 +1514,15 @@ var MeroJs = class {
         access_token: this.tokenData.access_token,
         refresh_token: this.tokenData.refresh_token
       });
+      const accessToken = response.data.access_token;
       this.tokenData = {
-        access_token: response.data.access_token,
+        access_token: accessToken,
         refresh_token: response.data.refresh_token,
-        expires_at: Date.now() + 24 * 60 * 60 * 1e3
-        // Default to 24 hours
+        expires_at: expiresAtFromJwt(accessToken, Date.now() + 36e5)
       };
+      this.tokenStore?.setTokens(this.tokenData);
       return this.tokenData;
     } catch (error) {
-      this.clearToken();
       throw new Error(
         `Token refresh failed: ${error instanceof Error ? error.message : "Unknown error"}`
       );
@@ -1000,6 +1533,7 @@ var MeroJs = class {
    */
   clearToken() {
     this.tokenData = null;
+    this.tokenStore?.clear();
   }
   /**
    * Check if the SDK is authenticated
@@ -1007,14 +1541,97 @@ var MeroJs = class {
   isAuthenticated() {
     return this.tokenData !== null;
   }
+  /**
+   * Set token data directly (e.g., from auth callback).
+   * If `expires_at` is missing or 0, attempts to parse the JWT exp claim,
+   * falling back to 1 hour from now.
+   */
+  setTokenData(data) {
+    const expiresAt = data.expires_at || expiresAtFromJwt(data.access_token, Date.now() + 36e5);
+    this.tokenData = { ...data, expires_at: expiresAt };
+    this.tokenStore?.setTokens(this.tokenData);
+  }
   /**
    * Get the current token data (for debugging)
    */
   getTokenData() {
     return this.tokenData;
   }
+  /**
+   * Close all event connections and clean up resources
+   */
+  close() {
+    this.sseClient?.close();
+    this.wsClient?.close();
+  }
+  /**
+   * Parse an auth callback URL hash fragment (static utility)
+   */
+  static parseAuthCallback(url) {
+    return parseAuthCallback(url);
+  }
+  /**
+   * Build an auth login URL (static utility)
+   */
+  static buildAuthLoginUrl(nodeUrl, opts) {
+    return buildAuthLoginUrl(nodeUrl, opts);
+  }
 };
 function createMeroJs(config) {
   return new MeroJs(config);
 }
+
+// src/token-store/index.ts
+var MemoryTokenStore = class {
+  constructor() {
+    this.tokens = null;
+  }
+  getTokens() {
+    return this.tokens;
+  }
+  setTokens(data) {
+    this.tokens = data;
+  }
+  clear() {
+    this.tokens = null;
+  }
+};
+var STORAGE_KEY = "mero-tokens";
+var LocalStorageTokenStore = class {
+  constructor(key = STORAGE_KEY) {
+    this.key = key;
+  }
+  getTokens() {
+    try {
+      if (typeof localStorage === "undefined") return null;
+      const raw = localStorage.getItem(this.key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (parsed && parsed.access_token && parsed.refresh_token) {
+        return {
+          access_token: parsed.access_token,
+          refresh_token: parsed.refresh_token,
+          expires_at: typeof parsed.expires_at === "number" ? parsed.expires_at : Date.now() + 36e5
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  setTokens(data) {
+    try {
+      if (typeof localStorage === "undefined") return;
+      localStorage.setItem(this.key, JSON.stringify(data));
+    } catch {
+    }
+  }
+  clear() {
+    try {
+      if (typeof localStorage === "undefined") return;
+      localStorage.removeItem(this.key);
+    } catch {
+    }
+  }
+};
 //# sourceMappingURL=index.cjs.map