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

package/dist/mero-js.d.ts

@@ -1,15 +1,13 @@
-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';
+import type { AuthApiClient } from './auth-api';
+import type { AdminApiClient } from './admin-api';
+import type { TokenStore } from './token-store';
+import type { AuthCallbackResult, AuthLoginOptions } from './auth';
+import { RpcClient } from './rpc';
+import { SseClient } from './events/sse';
+import { WsClient } from './events/ws';
 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;
@@ -19,63 +17,8 @@ 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>;
+    /** Optional token store for persistence */
+    tokenStore?: TokenStore;
 }
 export interface TokenData {
     access_token: string;
@@ -90,26 +33,14 @@ export declare class MeroJs {
     private httpClient;
     private authClient;
     private adminClient;
-    private rpcClient;
     private tokenData;
     private refreshPromise;
-    private tokenStorage;
+    private tokenStore;
+    private rpcClient;
+    private sseClient;
+    private wsClient;
+    private wsWarned;
     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
      */
@@ -119,36 +50,18 @@ export declare class MeroJs {
      */
     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 the RPC client (lazy initialized)
      */
     get rpc(): RpcClient;
+    /**
+     * Get the SSE event client (lazy initialized)
+     */
+    get events(): SseClient;
+    /**
+     * Get the WebSocket event client (lazy initialized).
+     * @experimental Use `events` (SSE) for production. WsClient is experimental.
+     */
+    get ws(): WsClient;
     /**
      * Authenticate with the provided credentials
      * This will create the root key on first use
@@ -158,108 +71,50 @@ export declare class MeroJs {
         password: string;
     }): Promise<TokenData>;
     /**
-     * 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.
+     * 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.
      */
     private getValidToken;
     /**
-     * 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
+     * Refresh the access token using the refresh token
      */
     private refreshToken;
     /**
-     * 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.)
+     * Perform the actual token refresh
      */
     private performTokenRefresh;
     /**
-     * Internal: Actually perform the refresh request.
-     * Called only from performTokenRefresh() which manages the deduplication.
+     * Clear the current token
      */
-    private doTokenRefresh;
-    /**
-     * Clear the current token from memory and storage
-     */
-    clearToken(): Promise<void>;
+    clearToken(): void;
     /**
      * Check if the SDK is authenticated
      */
     isAuthenticated(): boolean;
+    /**
+     * 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: TokenData): void;
     /**
      * 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,
-     * });
-     * ```
+     * Close all event connections and clean up resources
      */
-    setToken(tokenData: TokenData | null): Promise<void>;
+    close(): 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();
-     * ```
+     * Parse an auth callback URL hash fragment (static utility)
      */
-    createWebSocket(options?: Partial<Omit<WebSocketClientOptions, 'baseUrl' | 'getAuthToken'>>): WebSocketClient;
+    static parseAuthCallback(url: string): AuthCallbackResult | null;
     /**
-     * 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();
-     * ```
+     * Build an auth login URL (static utility)
      */
-    createSse(options?: Partial<Omit<SseClientOptions, 'baseUrl' | 'httpClient' | 'getAuthToken'>>): SseClient;
+    static buildAuthLoginUrl(nodeUrl: string, opts: AuthLoginOptions): string;
 }
 /**
  * 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,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,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;IACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,GAAG,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACjC,2BAA2B;IAC3B,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,kCAAkC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;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,CAAY;IAC7B,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,cAAc,CAAmC;IACzD,OAAO,CAAC,YAAY,CAA6B;gBAErC,MAAM,EAAE,YAAY;IAoEhC;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;OAEG;IACH,IAAI,IAAI,IAAI,aAAa,CAExB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,cAAc,CAE1B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,IAAI,GAAG,IAAI,SAAS,CAEnB;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;IAqEtB;;;;;;OAMG;YACW,aAAa;IAsB3B;;;;;OAKG;YACW,YAAY;IAI1B;;;;;;OAMG;YACW,mBAAmB;IAmBjC;;;OAGG;YACW,cAAc;IAkG5B;;OAEG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxC;;OAEG;IACI,eAAe,IAAI,OAAO;IAIjC;;OAEG;IACI,YAAY,IAAI,SAAS,GAAG,IAAI;IAIvC;;;;;;;;;;;;;;OAcG;IACU,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjE;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,eAAe,CACpB,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,sBAAsB,EAAE,SAAS,GAAG,cAAc,CAAC,CAAC,GAC1E,eAAe;IAQlB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,SAAS,CACd,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,YAAY,GAAG,cAAc,CAAC,CAAC,GACnF,SAAS;CAQb;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":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,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;IACxC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAqBD;;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;IACzD,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,YAAY;IAwDhC;;OAEG;IACH,IAAI,IAAI,IAAI,aAAa,CAExB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,cAAc,CAE1B;IAED;;OAEG;IACH,IAAI,GAAG,IAAI,SAAS,CAKnB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,SAAS,CAWtB;IAED;;;OAGG;IACH,IAAI,EAAE,IAAI,QAAQ,CAejB;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;IAsCtB;;;;;OAKG;YACW,aAAa;IAI3B;;OAEG;YACW,YAAY;IAoB1B;;OAEG;YACW,mBAAmB;IA+BjC;;OAEG;IACI,UAAU,IAAI,IAAI;IAKzB;;OAEG;IACI,eAAe,IAAI,OAAO;IAIjC;;;;OAIG;IACI,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAM1C;;OAEG;IACI,YAAY,IAAI,SAAS,GAAG,IAAI;IAIvC;;OAEG;IACI,KAAK,IAAI,IAAI;IAKpB;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAIhE;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM;CAG1E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEzD"}