@calimero-network/mero-js 1.1.0 → 2.0.0-beta.1

package/dist/mero-js.d.ts

@@ -1,8 +1,15 @@
-import type { AuthApiClient } from './auth-api';
-import type { AdminApiClient } from './admin-api';
+import { RpcClient } from './api/rpc';
+import { WebSocketClient } from './api/ws';
+import { SseClient } from './api/sse';
+import type { AuthApiClient } from './api/auth';
+import type { AdminApiClient } from './api/admin';
+import type { WebSocketClientOptions } from './api/ws';
+import type { SseClientOptions } from './api/sse';
 export interface MeroJsConfig {
     /** Base URL for the Calimero node */
     baseUrl: string;
+    /** Auth service base URL (for proxied mode). If not specified, uses baseUrl (embedded mode) */
+    authBaseUrl?: string;
     /** Initial credentials for authentication */
     credentials?: {
         username: string;
@@ -12,6 +19,63 @@ export interface MeroJsConfig {
     timeoutMs?: number;
     /** Request credentials mode for fetch (omit, same-origin, include) */
     requestCredentials?: RequestCredentials;
+    /**
+     * Optional token storage for persistence across sessions.
+     * If not provided, tokens are stored in-memory only.
+     *
+     * @example Browser localStorage
+     * ```typescript
+     * const mero = new MeroJs({
+     *   baseUrl: 'http://localhost:3000',
+     *   tokenStorage: {
+     *     async get() {
+     *       const data = localStorage.getItem('mero-token');
+     *       return data ? JSON.parse(data) : null;
+     *     },
+     *     async set(token) {
+     *       localStorage.setItem('mero-token', JSON.stringify(token));
+     *     },
+     *     async clear() {
+     *       localStorage.removeItem('mero-token');
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * @example React Native AsyncStorage
+     * ```typescript
+     * import AsyncStorage from '@react-native-async-storage/async-storage';
+     *
+     * const mero = new MeroJs({
+     *   baseUrl: 'http://localhost:3000',
+     *   tokenStorage: {
+     *     async get() {
+     *       const data = await AsyncStorage.getItem('mero-token');
+     *       return data ? JSON.parse(data) : null;
+     *     },
+     *     async set(token) {
+     *       await AsyncStorage.setItem('mero-token', JSON.stringify(token));
+     *     },
+     *     async clear() {
+     *       await AsyncStorage.removeItem('mero-token');
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    tokenStorage?: TokenStorage;
+}
+/**
+ * Interface for custom token storage implementations.
+ * Allows persistence of tokens across sessions in any environment.
+ */
+export interface TokenStorage {
+    /** Get the stored token data */
+    get(): Promise<TokenData | null>;
+    /** Store the token data */
+    set(token: TokenData): Promise<void>;
+    /** Clear the stored token data */
+    clear(): Promise<void>;
 }
 export interface TokenData {
     access_token: string;
@@ -26,9 +90,26 @@ export declare class MeroJs {
     private httpClient;
     private authClient;
     private adminClient;
+    private rpcClient;
     private tokenData;
     private refreshPromise;
+    private tokenStorage;
     constructor(config: MeroJsConfig);
+    /**
+     * Initialize the SDK by loading tokens from storage (if provided).
+     * Call this after construction if using tokenStorage.
+     *
+     * @example
+     * ```typescript
+     * const mero = new MeroJs({ baseUrl: '...', tokenStorage: myStorage });
+     * await mero.init(); // Load stored tokens
+     *
+     * if (!mero.isAuthenticated()) {
+     *   await mero.authenticate({ username: '...', password: '...' });
+     * }
+     * ```
+     */
+    init(): Promise<void>;
     /**
      * Get the Auth API client
      */
@@ -37,6 +118,37 @@ export declare class MeroJs {
      * Get the Admin API client
      */
     get admin(): AdminApiClient;
+    /**
+     * Get the RPC client for executing queries and mutations
+     *
+     * @example
+     * ```typescript
+     * // Execute a query
+     * const result = await meroJs.rpc.query(
+     *   'context-id',
+     *   'get',
+     *   { key: 'myKey' },
+     *   'ed25519:executor-public-key'
+     * );
+     *
+     * // Execute a mutation
+     * await meroJs.rpc.mutate(
+     *   'context-id',
+     *   'set',
+     *   { key: 'myKey', value: 'myValue' },
+     *   'ed25519:executor-public-key'
+     * );
+     *
+     * // Or use the generic execute method
+     * const result = await meroJs.rpc.execute({
+     *   contextId: 'context-id',
+     *   method: 'set',
+     *   args: { key: 'myKey', value: 'myValue' },
+     *   executorPublicKey: 'ed25519:...',
+     * });
+     * ```
+     */
+    get rpc(): RpcClient;
     /**
      * Authenticate with the provided credentials
      * This will create the root key on first use
@@ -46,21 +158,37 @@ export declare class MeroJs {
         password: string;
     }): Promise<TokenData>;
     /**
-     * Get a valid token, refreshing if necessary
+     * Get a valid token, refreshing if necessary.
+     * This is called automatically by the HTTP client.
+     *
+     * Note: The HTTP client also handles 401 errors with automatic refresh,
+     * so this preemptive check is an optimization to avoid unnecessary 401s.
      */
     private getValidToken;
     /**
-     * Refresh the access token using the refresh token
+     * Refresh the access token using the refresh token.
+     * Called automatically when token is about to expire or on 401.
+     *
+     * @deprecated Use performTokenRefresh instead - this is kept for compatibility
      */
     private refreshToken;
     /**
-     * Perform the actual token refresh
+     * Perform the actual token refresh.
+     * This is used by both preemptive refresh and HTTP client's 401 handler.
+     *
+     * Uses a shared promise to prevent multiple simultaneous refresh attempts,
+     * even when called from multiple sources (preemptive check, HTTP 401 handler, etc.)
      */
     private performTokenRefresh;
     /**
-     * Clear the current token
+     * Internal: Actually perform the refresh request.
+     * Called only from performTokenRefresh() which manages the deduplication.
      */
-    clearToken(): void;
+    private doTokenRefresh;
+    /**
+     * Clear the current token from memory and storage
+     */
+    clearToken(): Promise<void>;
     /**
      * Check if the SDK is authenticated
      */
@@ -69,6 +197,69 @@ export declare class MeroJs {
      * Get the current token data (for debugging)
      */
     getTokenData(): TokenData | null;
+    /**
+     * Manually set the token data.
+     * Use this when handling authentication externally (e.g., OAuth flows).
+     *
+     * @param tokenData - The token data to set, or null to clear
+     * @example
+     * ```typescript
+     * // After receiving tokens from external auth flow
+     * await meroJs.setToken({
+     *   access_token: 'eyJ...',
+     *   refresh_token: 'eyJ...',
+     *   expires_at: Date.now() + 3600000,
+     * });
+     * ```
+     */
+    setToken(tokenData: TokenData | null): Promise<void>;
+    /**
+     * Create a WebSocket client for real-time event subscriptions
+     *
+     * @param options - Optional WebSocket client options to override defaults
+     * @returns A new WebSocketClient instance
+     *
+     * @example
+     * ```typescript
+     * const ws = meroJs.createWebSocket();
+     * await ws.connect();
+     *
+     * ws.onEvent((event) => {
+     *   console.log('Received event:', event);
+     * });
+     *
+     * await ws.subscribe(['context-id-1', 'context-id-2']);
+     *
+     * // Later...
+     * ws.disconnect();
+     * ```
+     */
+    createWebSocket(options?: Partial<Omit<WebSocketClientOptions, 'baseUrl' | 'getAuthToken'>>): WebSocketClient;
+    /**
+     * Create an SSE client for server-sent event streaming
+     *
+     * @param options - Optional SSE client options to override defaults
+     * @returns A new SseClient instance
+     *
+     * @example
+     * ```typescript
+     * const sse = meroJs.createSse();
+     * const sessionId = await sse.connect();
+     *
+     * sse.onEvent((event) => {
+     *   console.log('Received event:', event);
+     * });
+     *
+     * await sse.subscribe(['context-id-1', 'context-id-2']);
+     *
+     * // Get session info
+     * const session = await sse.getSession();
+     *
+     * // Later...
+     * sse.disconnect();
+     * ```
+     */
+    createSse(options?: Partial<Omit<SseClientOptions, 'baseUrl' | 'httpClient' | 'getAuthToken'>>): SseClient;
 }
 /**
  * Create a new MeroJs SDK instance

package/dist/mero-js.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mero-js.d.ts","sourceRoot":"","sources":["../src/mero-js.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,cAAc,CAAmC;gBAE7C,MAAM,EAAE,YAAY;IAyChC;;OAEG;IACH,IAAI,IAAI,IAAI,aAAa,CAExB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,cAAc,CAE1B;IAED;;;OAGG;IACG,YAAY,CAAC,WAAW,CAAC,EAAE;QAC/B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,SAAS,CAAC;IAmCtB;;OAEG;YACW,aAAa;IAc3B;;OAEG;YACW,YAAY;IAoB1B;;OAEG;YACW,mBAAmB;IA2BjC;;OAEG;IACI,UAAU,IAAI,IAAI;IAIzB;;OAEG;IACI,eAAe,IAAI,OAAO;IAIjC;;OAEG;IACI,YAAY,IAAI,SAAS,GAAG,IAAI;CAGxC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEzD"}
+{"version":3,"file":"mero-js.d.ts","sourceRoot":"","sources":["../src/mero-js.ts"],"names":[],"mappings":"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"}