@calimero-network/mero-js 26.11.0 → 27.0.0

package/dist/events/ws.js

@@ -1,212 +0,0 @@
-/**
- * @experimental WebSocket event client. The SSE client (`SseClient`) is the
- * recommended transport for production — use `MeroJs.events` instead of `MeroJs.ws`.
- */
-export class WsClient {
-    constructor(opts) {
-        this.ws = null;
-        this.closed = false;
-        this.reconnectAttempt = 0;
-        this.reconnectTimer = null;
-        this.subscribedContextIds = new Set();
-        this.subscribedGroupIds = 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) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const arr = this.listeners[key];
-            if (!arr.includes(handler))
-                arr.push(handler);
-        }
-    }
-    off(event, handler) {
-        const key = event;
-        if (key in this.listeners) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            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 {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    handler(arg);
-                }
-                catch {
-                    // Swallow handler errors
-                }
-            }
-        }
-    }
-    async connect() {
-        if (this.ws && (this.ws.readyState === 0 /* CONNECTING */ || this.ws.readyState === 1 /* OPEN */)) {
-            return;
-        }
-        this.closed = false;
-        try {
-            const token = await this.getAuthToken();
-            if (!token) {
-                throw new Error('No authentication token available for WebSocket connection');
-            }
-            // Browser WebSocket API can't set headers, use query param
-            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');
-                this.resubscribeAfterReconnect();
-            };
-            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)
-                return;
-            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 {
-                    // Keep raw data
-                }
-            }
-            if (msg.result.contextId) {
-                this.emit('event', {
-                    contextId: msg.result.contextId,
-                    // Forward the event tag (sibling of `data` in core's flattened
-                    // payload) so consumers can discriminate, matching `SseClient`.
-                    type: msg.result.type,
-                    data: eventData,
-                });
-                return;
-            }
-            // Group-keyed event message (untagged NodeEvent's membership and
-            // migration variants; the `type` tag tells them apart).
-            if (msg.result.groupId) {
-                this.emit('event', {
-                    groupId: msg.result.groupId,
-                    type: msg.result.type,
-                    data: eventData,
-                });
-            }
-        }
-        catch {
-            // Invalid JSON, ignore
-        }
-    }
-    subscribe(idsOrOpts) {
-        const opts = Array.isArray(idsOrOpts) ? { contextIds: idsOrOpts } : idsOrOpts;
-        for (const id of opts.contextIds ?? []) {
-            this.subscribedContextIds.add(id);
-        }
-        for (const id of opts.groupIds ?? []) {
-            this.subscribedGroupIds.add(id);
-        }
-        if (this.ws && this.ws.readyState === 1 /* OPEN */) {
-            this.sendMessage({
-                id: null,
-                method: 'subscribe',
-                params: this.buildSubscriptionParams(opts.contextIds ?? [], opts.groupIds ?? []),
-            });
-        }
-    }
-    unsubscribe(idsOrOpts) {
-        const opts = Array.isArray(idsOrOpts) ? { contextIds: idsOrOpts } : idsOrOpts;
-        for (const id of opts.contextIds ?? []) {
-            this.subscribedContextIds.delete(id);
-        }
-        for (const id of opts.groupIds ?? []) {
-            this.subscribedGroupIds.delete(id);
-        }
-        if (this.ws && this.ws.readyState === 1 /* OPEN */) {
-            this.sendMessage({
-                id: null,
-                method: 'unsubscribe',
-                params: this.buildSubscriptionParams(opts.contextIds ?? [], opts.groupIds ?? []),
-            });
-        }
-    }
-    resubscribeAfterReconnect() {
-        if (this.subscribedContextIds.size === 0 && this.subscribedGroupIds.size === 0)
-            return;
-        this.sendMessage({
-            id: null,
-            method: 'subscribe',
-            params: this.buildSubscriptionParams([...this.subscribedContextIds], [...this.subscribedGroupIds]),
-        });
-    }
-    buildSubscriptionParams(contextIds, groupIds) {
-        const params = {};
-        if (contextIds.length > 0)
-            params.contextIds = contextIds;
-        if (groupIds.length > 0)
-            params.groupIds = groupIds;
-        return params;
-    }
-    sendMessage(msg) {
-        if (this.ws && this.ws.readyState === 1 /* OPEN */) {
-            this.ws.send(JSON.stringify(msg));
-        }
-    }
-    scheduleReconnect() {
-        if (this.closed)
-            return;
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-        }
-        const delay = Math.min(1000 * 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();
-        this.subscribedGroupIds.clear();
-    }
-}
-WsClient.MAX_BACKOFF_MS = 30000;

package/dist/http-client/api-response.d.ts

@@ -1,15 +0,0 @@
-export type ErrorResponse = {
-    code?: number;
-    message: string;
-};
-export type ResponseData<D = unknown> = {
-    data: D;
-    error: null;
-} | {
-    data: null;
-    error: ErrorResponse;
-};
-export type ApiResponse<D = unknown> = Promise<ResponseData<D>>;
-export interface SuccessResponse {
-    success: boolean;
-}

package/dist/http-client/api-response.js

@@ -1 +0,0 @@
-export {};

package/dist/http-client/http-factory.d.ts

@@ -1,71 +0,0 @@
-import { Transport, HttpClient } from './http-types.js';
-export declare function createHttpClient(transport: Transport): HttpClient;
-export declare function createBrowserHttpClient(options: {
-    baseUrl: string;
-    fetch?: typeof fetch;
-    getAuthToken?: () => Promise<string | undefined>;
-    getProof?: Transport['getProof'];
-    onTokenRefresh?: (newToken: string) => Promise<void>;
-    /**
-     * Callback to refresh the access token when a 401 error with 'token_expired' is detected.
-     * Should return the new access token, or throw an error if refresh fails.
-     * If provided, the client will automatically retry the request after a successful refresh.
-     */
-    refreshToken?: () => Promise<string>;
-    /**
-     * Callback invoked when the server reports a revoked token family
-     * (`x-auth-error: token_reuse` / `token_revoked`). Terminal — the request is
-     * never retried; clear stored tokens and force a re-login.
-     */
-    onAuthRevoked?: () => Promise<void> | void;
-    defaultHeaders?: Record<string, string>;
-    timeoutMs?: number;
-    credentials?: RequestCredentials;
-    defaultAbortSignal?: AbortSignal;
-}): HttpClient;
-export declare function createNodeHttpClient(options: {
-    baseUrl: string;
-    fetch?: typeof fetch;
-    getAuthToken?: () => Promise<string | undefined>;
-    getProof?: Transport['getProof'];
-    onTokenRefresh?: (newToken: string) => Promise<void>;
-    /**
-     * Callback to refresh the access token when a 401 error with 'token_expired' is detected.
-     * Should return the new access token, or throw an error if refresh fails.
-     * If provided, the client will automatically retry the request after a successful refresh.
-     */
-    refreshToken?: () => Promise<string>;
-    /**
-     * Callback invoked when the server reports a revoked token family
-     * (`x-auth-error: token_reuse` / `token_revoked`). Terminal — the request is
-     * never retried; clear stored tokens and force a re-login.
-     */
-    onAuthRevoked?: () => Promise<void> | void;
-    defaultHeaders?: Record<string, string>;
-    timeoutMs?: number;
-    credentials?: RequestCredentials;
-    defaultAbortSignal?: AbortSignal;
-}): HttpClient;
-export declare function createUniversalHttpClient(options: {
-    baseUrl: string;
-    fetch?: typeof fetch;
-    getAuthToken?: () => Promise<string | undefined>;
-    getProof?: Transport['getProof'];
-    onTokenRefresh?: (newToken: string) => Promise<void>;
-    /**
-     * Callback to refresh the access token when a 401 error with 'token_expired' is detected.
-     * Should return the new access token, or throw an error if refresh fails.
-     * If provided, the client will automatically retry the request after a successful refresh.
-     */
-    refreshToken?: () => Promise<string>;
-    /**
-     * Callback invoked when the server reports a revoked token family
-     * (`x-auth-error: token_reuse` / `token_revoked`). Terminal — the request is
-     * never retried; clear stored tokens and force a re-login.
-     */
-    onAuthRevoked?: () => Promise<void> | void;
-    defaultHeaders?: Record<string, string>;
-    timeoutMs?: number;
-    credentials?: RequestCredentials;
-    defaultAbortSignal?: AbortSignal;
-}): HttpClient;

package/dist/http-client/http-factory.js

@@ -1,68 +0,0 @@
-import { WebHttpClient } from './web-client.js';
-// Factory function to create HTTP client with sensible defaults
-export function createHttpClient(transport) {
-    return new WebHttpClient(transport);
-}
-// Factory function for browser environments
-export function createBrowserHttpClient(options) {
-    const transport = {
-        // globalThis.fetch must be called as a method on globalThis, not through a
-        // variable, or browsers throw "Illegal invocation".
-        fetch: (url, init) => options.fetch ? options.fetch(url, init) : globalThis.fetch(url, init),
-        baseUrl: options.baseUrl,
-        getAuthToken: options.getAuthToken,
-        getProof: options.getProof,
-        onTokenRefresh: options.onTokenRefresh,
-        refreshToken: options.refreshToken,
-        onAuthRevoked: options.onAuthRevoked,
-        defaultHeaders: options.defaultHeaders,
-        timeoutMs: options.timeoutMs,
-        credentials: options.credentials,
-        defaultAbortSignal: options.defaultAbortSignal,
-    };
-    return createHttpClient(transport);
-}
-// Factory function for Node.js environments
-export function createNodeHttpClient(options) {
-    // Use provided fetch or try to use global fetch (Node 18+)
-    const fetchImpl = options.fetch ?? globalThis.fetch;
-    if (!fetchImpl) {
-        throw new Error('No fetch implementation available. Please provide a fetch implementation ' +
-            '(e.g., undici.fetch) or use Node.js 18+ which has native fetch support.');
-    }
-    // Check if we're using the default globalThis.fetch to preserve context
-    // When fetchImpl is globalThis.fetch, we must call it directly, not through a variable
-    // Custom fetch implementations (like undici.fetch) can be called through the variable
-    const isDefaultFetch = fetchImpl === globalThis.fetch;
-    const transport = {
-        // Wrap fetch in arrow function to prevent "Illegal invocation" error
-        // For globalThis.fetch, call it directly to preserve 'this' context
-        // For custom implementations, calling through the variable is safe
-        fetch: isDefaultFetch
-            ? (url, init) => globalThis.fetch(url, init)
-            : (url, init) => fetchImpl(url, init),
-        baseUrl: options.baseUrl,
-        getAuthToken: options.getAuthToken,
-        getProof: options.getProof,
-        onTokenRefresh: options.onTokenRefresh,
-        refreshToken: options.refreshToken,
-        onAuthRevoked: options.onAuthRevoked,
-        defaultHeaders: options.defaultHeaders,
-        timeoutMs: options.timeoutMs,
-        credentials: options.credentials,
-        defaultAbortSignal: options.defaultAbortSignal,
-    };
-    return createHttpClient(transport);
-}
-// Universal factory that works in both environments
-export function createUniversalHttpClient(options) {
-    // Try to detect environment and use appropriate factory
-    if (typeof window !== 'undefined') {
-        // Browser environment
-        return createBrowserHttpClient(options);
-    }
-    else {
-        // Node.js environment
-        return createNodeHttpClient(options);
-    }
-}

package/dist/http-client/http-types.d.ts

@@ -1,87 +0,0 @@
-export type FetchLike = (input: RequestInfo, init?: RequestInit) => Promise<Response>;
-export interface Transport {
-    fetch: FetchLike;
-    baseUrl: string;
-    defaultHeaders?: Record<string, string>;
-    getAuthToken?: () => Promise<string | undefined>;
-    /**
-     * Per-request authorization, for a credential that commits to the request.
-     *
-     * `getAuthToken` returns one value reused across requests; a request proof
-     * signs the method, the path and the body, so it can only be produced where
-     * those are known. This is called with exactly that, and whatever it returns
-     * is merged into the headers.
-     *
-     * It runs AFTER `getAuthToken`, so a transport holding both sends both and
-     * lets the node decide — which it does by answering a request carrying a token
-     * by that token, and consulting a proof only when there is none.
-     */
-    authorizeRequest?: (request: {
-        method: string;
-        /** The path and query the node will see, as `signedPath` reads them. */
-        path: string;
-        body?: string | Uint8Array;
-    }) => Promise<Record<string, string>>;
-    /**
-     * Sign each request instead of, or alongside, presenting a session.
-     *
-     * Called per call with the method, the path the node will see, and the exact
-     * body — a proof commits to all three, so unlike `getAuthToken` it cannot be
-     * resolved once and reused. Returning `undefined` sends no proof header,
-     * which is how a client that only sometimes has a key stays usable.
-     *
-     * `createProofSigner` builds one of these from a credential and a key.
-     */
-    getProof?: (request: {
-        method: string;
-        path: string;
-        body?: unknown;
-    }) => Promise<string | undefined>;
-    onTokenRefresh?: (newToken: string) => Promise<void>;
-    /**
-     * Callback to refresh the access token when a 401 error with 'token_expired' is detected.
-     * Should return the new access token, or throw an error if refresh fails.
-     * If provided, the client will automatically retry the request after a successful refresh.
-     */
-    refreshToken?: () => Promise<string>;
-    /**
-     * Callback invoked when the server reports that the token family is gone
-     * (`x-auth-error: token_reuse` on 401, or `token_revoked`). Refresh tokens are
-     * single-use, so this is terminal: the stored tokens must be dropped and the
-     * user re-authenticated. The client never retries such a request.
-     */
-    onAuthRevoked?: () => Promise<void> | void;
-    timeoutMs?: number;
-    credentials?: RequestCredentials;
-    defaultAbortSignal?: AbortSignal;
-}
-export type ResponseParser = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'response';
-export interface RequestOptions extends RequestInit {
-    parse?: ResponseParser;
-    timeoutMs?: number;
-}
-export interface HttpClient {
-    get<T>(path: string, init?: RequestOptions): Promise<T>;
-    post<T>(path: string, body?: unknown, init?: RequestOptions): Promise<T>;
-    put<T>(path: string, body?: unknown, init?: RequestOptions): Promise<T>;
-    delete<T>(path: string, init?: RequestOptions): Promise<T>;
-    patch<T>(path: string, body?: unknown, init?: RequestOptions): Promise<T>;
-    head(path: string, init?: RequestOptions): Promise<{
-        headers: Record<string, string>;
-        status: number;
-    }>;
-    request<T>(path: string, init?: RequestOptions): Promise<T>;
-}
-export interface Header {
-    [key: string]: string;
-}
-export interface ProgressCallback {
-    (progress: number): void;
-}
-export interface HeadResponse {
-    headers: Record<string, string>;
-    status: number;
-}
-export interface LegacyRequestOptions {
-    responseType?: 'arraybuffer' | 'blob' | 'json';
-}

package/dist/http-client/http-types.js

@@ -1 +0,0 @@
-export {};

package/dist/http-client/index.d.ts

@@ -1,7 +0,0 @@
-export * from './http-types.js';
-export * from './api-response.js';
-export { WebHttpClient, HTTPError, AuthRevokedError, RequestAuthError } from './web-client.js';
-export { createHttpClient, createBrowserHttpClient, createNodeHttpClient, createUniversalHttpClient, } from './http-factory.js';
-export { withRetry, createRetryableMethod } from './retry.js';
-export type { RetryOptions } from './retry.js';
-export { combineSignals, createTimeoutSignal } from './signal-utils.js';

package/dist/http-client/index.js

@@ -1,11 +0,0 @@
-// HTTP client types and interfaces
-export * from './http-types.js';
-export * from './api-response.js';
-// Web Standards HTTP client implementation
-export { WebHttpClient, HTTPError, AuthRevokedError, RequestAuthError } from './web-client.js';
-// Factory functions for easy client creation
-export { createHttpClient, createBrowserHttpClient, createNodeHttpClient, createUniversalHttpClient, } from './http-factory.js';
-// Retry functionality
-export { withRetry, createRetryableMethod } from './retry.js';
-// Signal utilities
-export { combineSignals, createTimeoutSignal } from './signal-utils.js';

package/dist/http-client/path-segment.d.ts

@@ -1 +0,0 @@
-export declare function pathSegment(id: string): string;

package/dist/http-client/path-segment.js

@@ -1,8 +0,0 @@
-// encodeURIComponent leaves "." and ".." intact and URL parsers collapse them,
-// so those (and the empty id, which names the collection route) are refused.
-export function pathSegment(id) {
-    if (id === '' || id === '.' || id === '..') {
-        throw new TypeError(`invalid request path segment: ${JSON.stringify(id)}`);
-    }
-    return encodeURIComponent(id);
-}

package/dist/http-client/retry.d.ts

@@ -1,5 +0,0 @@
-export interface RetryOptions {
-    attempts?: number;
-}
-export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
-export declare function createRetryableMethod<T extends unknown[], R>(method: (...args: T) => Promise<R>, retryOptions?: RetryOptions): (...args: T) => Promise<R>;

package/dist/http-client/retry.js

@@ -1,82 +0,0 @@
-// Default retry condition - retry on network errors and 5xx status codes
-function defaultRetryCondition(error, attempt) {
-    // Don't retry on the last attempt
-    if (attempt <= 0)
-        return false;
-    // Distinguish timeout vs. user abort:
-    // - Timeout: name === 'TimeoutError' (per spec/platforms)
-    // - User abort: name === 'AbortError'
-    const errorWithName = error;
-    const name = errorWithName?.name;
-    if (name === 'TimeoutError')
-        return true;
-    if (name === 'AbortError')
-        return false;
-    // HTTP 5xx and 429 (including HTTPError from web-client)
-    const errorWithStatus = error;
-    if ('status' in errorWithStatus &&
-        typeof errorWithStatus.status === 'number') {
-        const status = errorWithStatus.status;
-        return status >= 500 || status === 429;
-    }
-    // Network TypeError (DNS/reset) is reasonably retryable
-    if (name === 'TypeError')
-        return true;
-    return false;
-}
-// Calculate delay with exponential backoff and jitter
-function calculateDelay(attempt) {
-    const baseDelayMs = 250; // Base 250ms as per spec
-    const delay = baseDelayMs * Math.pow(2, attempt - 1);
-    // Add ±20% jitter to reduce stampedes
-    const jitter = (Math.random() - 0.5) * 0.4 * delay;
-    return Math.max(0, delay + jitter);
-}
-// Retry helper function with new signature
-export async function withRetry(fn, options = {}) {
-    const { attempts = 3 } = options;
-    let lastError;
-    for (let attempt = 1; attempt <= attempts; attempt++) {
-        try {
-            return await fn(attempt);
-        }
-        catch (error) {
-            lastError = error;
-            // Check if we should retry (this handles the last attempt check)
-            if (!defaultRetryCondition(lastError, attempts - attempt)) {
-                throw lastError;
-            }
-            // Calculate delay
-            let delayMs = calculateDelay(attempt);
-            // Check for Retry-After header if it's an HTTP error
-            const errorWithHeaders = lastError;
-            const hdrs = errorWithHeaders.headers;
-            const retryAfter = hdrs?.get?.('Retry-After');
-            if (retryAfter) {
-                // If it's a number, treat as seconds
-                const seconds = parseInt(retryAfter, 10);
-                if (!isNaN(seconds)) {
-                    delayMs = Math.max(delayMs, seconds * 1000);
-                }
-                else {
-                    // If it's a date, calculate the difference
-                    const date = new Date(retryAfter);
-                    if (!isNaN(date.getTime())) {
-                        const waitTime = Math.max(0, date.getTime() - Date.now());
-                        // Cap wait at 60s per attempt as per spec
-                        delayMs = Math.max(delayMs, Math.min(waitTime, 60000));
-                    }
-                }
-            }
-            // Wait before retrying
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
-        }
-    }
-    throw lastError || new Error('Retry failed without error');
-}
-// Helper to create a retry-enabled HTTP client method
-export function createRetryableMethod(method, retryOptions = {}) {
-    return async (...args) => {
-        return withRetry(() => method(...args), retryOptions);
-    };
-}

package/dist/http-client/signal-utils.d.ts

@@ -1,2 +0,0 @@
-export declare function combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined;
-export declare function createTimeoutSignal(timeoutMs: number): AbortSignal;

package/dist/http-client/signal-utils.js

@@ -1,41 +0,0 @@
-// Utility for combining multiple AbortSignals
-export function combineSignals(signals) {
-    const list = signals.filter(Boolean);
-    if (list.length === 0)
-        return undefined;
-    // Prefer native any(), but fall back if unavailable or it throws
-    const AbortSignalAny = AbortSignal;
-    if (typeof AbortSignalAny.any === 'function') {
-        try {
-            return AbortSignalAny.any(list);
-        }
-        catch {
-            // Fall through to manual implementation
-        }
-    }
-    const controller = new AbortController();
-    const onAbort = (evt) => {
-        controller.abort(evt.target.reason);
-        for (const s of list)
-            s.removeEventListener('abort', onAbort);
-    };
-    for (const s of list) {
-        if (s.aborted)
-            return AbortSignal.abort(s.reason);
-        s.addEventListener('abort', onAbort, { once: true });
-    }
-    return controller.signal;
-}
-// Helper to create a timeout signal
-export function createTimeoutSignal(timeoutMs) {
-    // Use AbortSignal.timeout if available (Node 18.17+, modern browsers)
-    if (typeof AbortSignal.timeout === 'function') {
-        return AbortSignal.timeout(timeoutMs);
-    }
-    // Fallback for older environments
-    const controller = new AbortController();
-    setTimeout(() => {
-        controller.abort(new DOMException('Timeout', 'TimeoutError'));
-    }, timeoutMs);
-    return controller.signal;
-}