@calimero-network/mero-js 18.1.1 → 18.3.0

package/dist/mero-js.d.ts

@@ -6,6 +6,8 @@ import { RpcClient } from './rpc/index.js';
 import { SseClient } from './events/sse.js';
 import { WsClient } from './events/ws.js';
 import { EphemeralClient } from './ephemeral/index.js';
+import { CloudClient } from './cloud/cloud-client.js';
+import type { CloudClientConfig } from './cloud/cloud-client.js';
 export interface MeroJsConfig {
     /** Base URL for the Calimero node */
     baseUrl: string;
@@ -28,6 +30,20 @@ export interface MeroJsConfig {
      * never let a UI failure mask the auth error.
      */
     onAuthRevoked?: () => Promise<void> | void;
+    /**
+     * Calimero Cloud, reachable as `sdk.cloud`.
+     *
+     * A node connection and a cloud account are separate things a client can have
+     * either of, both of, or neither — a desktop app with a local node and a
+     * cloud subscription has both, and needs them from one object. So this is
+     * configuration on the existing SDK rather than a second SDK: pass the
+     * session token (or none, and sign in through `sdk.cloud`) and the node half
+     * is unaffected.
+     *
+     * For a caller with *no* node at all, `connectCloud` is the entry point
+     * instead — it returns a connection that can write without one.
+     */
+    cloud?: CloudClientConfig;
 }
 export interface TokenData {
     access_token: string;
@@ -50,6 +66,7 @@ export declare class MeroJs {
     private wsClient;
     private wsWarned;
     private ephemeralClient?;
+    private cloudClient?;
     constructor(config: MeroJsConfig);
     /**
      * Get the Auth API client
@@ -74,6 +91,17 @@ export declare class MeroJs {
      * stream rather than opening a second connection.
      */
     get ephemeral(): EphemeralClient;
+    /**
+     * Calimero Cloud (lazy initialized).
+     *
+     * Available whether or not `cloud` was configured — an app that signs in
+     * later gets an unauthenticated client it can call `signInWithGoogle` on,
+     * which is one fewer construction path than making the getter conditional.
+     * It is entirely independent of this instance's node credential: the cloud
+     * knows nothing about the node's tokens and the node knows nothing about the
+     * cloud session.
+     */
+    get cloud(): CloudClient;
     /**
      * Get the WebSocket event client (lazy initialized).
      * @experimental Use `events` (SSE) for production. WsClient is experimental.

package/dist/mero-js.js

@@ -6,6 +6,7 @@ import { RpcClient } from './rpc/index.js';
 import { SseClient } from './events/sse.js';
 import { WsClient } from './events/ws.js';
 import { EphemeralClient } from './ephemeral/index.js';
+import { CloudClient } from './cloud/cloud-client.js';
 /** Name of the Web Lock that serializes token refresh across tabs / webviews. */
 const REFRESH_LOCK_NAME = 'mero-js:token-refresh';
 /** Returns `navigator.locks` when the runtime supports the Web Locks API. */
@@ -157,6 +158,22 @@ export class MeroJs {
         }
         return this.ephemeralClient;
     }
+    /**
+     * Calimero Cloud (lazy initialized).
+     *
+     * Available whether or not `cloud` was configured — an app that signs in
+     * later gets an unauthenticated client it can call `signInWithGoogle` on,
+     * which is one fewer construction path than making the getter conditional.
+     * It is entirely independent of this instance's node credential: the cloud
+     * knows nothing about the node's tokens and the node knows nothing about the
+     * cloud session.
+     */
+    get cloud() {
+        if (!this.cloudClient) {
+            this.cloudClient = new CloudClient(this.config.cloud ?? {});
+        }
+        return this.cloudClient;
+    }
     /**
      * Get the WebSocket event client (lazy initialized).
      * @experimental Use `events` (SSE) for production. WsClient is experimental.

package/dist/relay/index.d.ts

@@ -0,0 +1,4 @@
+export { RelayClient, IntentRefusedError } from './relay-client.js';
+export type { RelayClientConfig, RelayDescription, IntentResult } from './relay-client.js';
+export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';
+export type { NonceSource } from './nonce-source.js';

package/dist/relay/index.js

@@ -0,0 +1,2 @@
+export { RelayClient, IntentRefusedError } from './relay-client.js';
+export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';

package/dist/relay/nonce-source.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Where a warrant's nonce comes from.
+ *
+ * # Why this is a named concept and not a counter in the relay client
+ *
+ * A warrant's nonce is spent, once, per `(context, author device)` on every
+ * node that applies the delta. So the sequence a client emits is not a local
+ * detail — it is state the network remembers, and the client is the only party
+ * that can keep it.
+ *
+ * The receiving ledger is a **sliding window** 64 wide, not a high-water mark,
+ * which is what makes the two failure modes so different:
+ *
+ * - **Skipping** numbers is free. Gossip gives no ordering, so the window
+ *   exists precisely to accept whatever unseen nonce arrives.
+ * - **Restarting** the sequence is fatal. A tab that reloads and resumes at `1`
+ *   re-presents nonces the network has already spent, and every one of those
+ *   writes is refused as a replay — indistinguishable, to the user, from the
+ *   app silently not saving.
+ *
+ * That asymmetry is why persistence is the default here and an in-memory source
+ * is the one you have to ask for. It is also why a source may jump: reserving a
+ * block and losing the tail is the correct trade.
+ */
+/** Produces the next nonce for one author device. Must never go backwards. */
+export interface NonceSource {
+    next(): Promise<bigint>;
+}
+/**
+ * A counter in memory, starting at `start`.
+ *
+ * Correct only for a process whose lifetime is the whole sequence — a script, a
+ * server-side worker that owns its own device key, a test. In a browser tab it
+ * resets on reload and replays; use {@link createLocalStorageNonceSource}
+ * there.
+ */
+export declare function createMemoryNonceSource(start?: number | bigint): NonceSource;
+/**
+ * A counter persisted in `localStorage`, so a reload continues the sequence.
+ *
+ * Key it per author **device**, not per account: two devices of one account are
+ * independent replicas with independent sequences, and sharing a counter would
+ * have them refusing each other's warrants.
+ *
+ * **Reserve-then-hand-out.** The stored value is advanced *before* the nonce is
+ * returned, so a crash between the two loses a number rather than reusing one.
+ * Losing a number costs nothing (the window accepts gaps); reusing one costs a
+ * write.
+ *
+ * Concurrent tabs are the case this cannot fully solve, because `localStorage`
+ * has no atomic read-modify-write. Two tabs racing can hand out the same nonce,
+ * and the loser's write is refused as a replay rather than silently
+ * misattributed — a visible error, not corruption. An app that genuinely writes
+ * from several tabs at once should hold a Web Lock around `next()` or give each
+ * tab its own device.
+ */
+export declare function createLocalStorageNonceSource(key: string, storage?: {
+    getItem(k: string): string | null;
+    setItem(k: string, v: string): void;
+}): NonceSource;

package/dist/relay/nonce-source.js

@@ -0,0 +1,95 @@
+/**
+ * Where a warrant's nonce comes from.
+ *
+ * # Why this is a named concept and not a counter in the relay client
+ *
+ * A warrant's nonce is spent, once, per `(context, author device)` on every
+ * node that applies the delta. So the sequence a client emits is not a local
+ * detail — it is state the network remembers, and the client is the only party
+ * that can keep it.
+ *
+ * The receiving ledger is a **sliding window** 64 wide, not a high-water mark,
+ * which is what makes the two failure modes so different:
+ *
+ * - **Skipping** numbers is free. Gossip gives no ordering, so the window
+ *   exists precisely to accept whatever unseen nonce arrives.
+ * - **Restarting** the sequence is fatal. A tab that reloads and resumes at `1`
+ *   re-presents nonces the network has already spent, and every one of those
+ *   writes is refused as a replay — indistinguishable, to the user, from the
+ *   app silently not saving.
+ *
+ * That asymmetry is why persistence is the default here and an in-memory source
+ * is the one you have to ask for. It is also why a source may jump: reserving a
+ * block and losing the tail is the correct trade.
+ */
+/**
+ * A counter in memory, starting at `start`.
+ *
+ * Correct only for a process whose lifetime is the whole sequence — a script, a
+ * server-side worker that owns its own device key, a test. In a browser tab it
+ * resets on reload and replays; use {@link createLocalStorageNonceSource}
+ * there.
+ */
+export function createMemoryNonceSource(start = 1) {
+    let next = BigInt(start);
+    if (next < 1n) {
+        throw new Error('nonce sequence starts at 1');
+    }
+    return {
+        next() {
+            const value = next;
+            next += 1n;
+            return Promise.resolve(value);
+        },
+    };
+}
+/**
+ * A counter persisted in `localStorage`, so a reload continues the sequence.
+ *
+ * Key it per author **device**, not per account: two devices of one account are
+ * independent replicas with independent sequences, and sharing a counter would
+ * have them refusing each other's warrants.
+ *
+ * **Reserve-then-hand-out.** The stored value is advanced *before* the nonce is
+ * returned, so a crash between the two loses a number rather than reusing one.
+ * Losing a number costs nothing (the window accepts gaps); reusing one costs a
+ * write.
+ *
+ * Concurrent tabs are the case this cannot fully solve, because `localStorage`
+ * has no atomic read-modify-write. Two tabs racing can hand out the same nonce,
+ * and the loser's write is refused as a replay rather than silently
+ * misattributed — a visible error, not corruption. An app that genuinely writes
+ * from several tabs at once should hold a Web Lock around `next()` or give each
+ * tab its own device.
+ */
+export function createLocalStorageNonceSource(key, storage) {
+    const store = storage ?? globalThis.localStorage;
+    if (!store) {
+        throw new Error('no localStorage in this runtime: pass a storage implementation, or use createMemoryNonceSource for a process that owns its whole sequence');
+    }
+    return {
+        next() {
+            const raw = store.getItem(key);
+            // A missing, empty, or corrupted value means "no sequence recorded", and
+            // the safe reading of that is not 1 — a cleared storage on a device that
+            // has already written would replay. But the client cannot know, and 1 is
+            // the only defensible start, so it is what a fresh key gets. This is why
+            // the doc above tells apps to key per device: a device whose storage was
+            // cleared should be re-paired rather than resumed.
+            let current = 0n;
+            if (raw !== null && raw !== '') {
+                try {
+                    const parsed = BigInt(raw);
+                    if (parsed > 0n)
+                        current = parsed;
+                }
+                catch {
+                    current = 0n;
+                }
+            }
+            const value = current + 1n;
+            store.setItem(key, value.toString());
+            return Promise.resolve(value);
+        },
+    };
+}

package/dist/relay/relay-client.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Write to a context through a relay, holding nothing but a signing key.
+ *
+ * # What this replaces
+ *
+ * `sdk.rpc.execute` asks a node to run a method *as itself*: it needs a node,
+ * that node needs to be a member, and the caller needs a credential on it. For
+ * a browser tab, a phone, or an agent, none of those three is available — the
+ * runtime cannot compile WASM against materialized state, never received the
+ * scope key that seals the deltas, and has no account on anybody's node.
+ *
+ * This client is the other path. The caller signs a warrant locally, the relay
+ * runs the method as the *author's* principal, and the resulting delta is
+ * attributed to the author's account and device — their replica slot, their
+ * membership, their name in the app. The relay's key signs the envelope and
+ * nothing else.
+ *
+ * # The three preconditions, and why they are checked in this order
+ *
+ * `describe()` answers the first two in one call, before anything is signed:
+ * the relay's executor account (which the warrant must name) and whether it
+ * holds `CAN_AUTHOR_ON_BEHALF` on the owning group. The third — that the
+ * author's account is a member — only the group knows, and it surfaces as a
+ * refusal.
+ *
+ * Checking before signing is not politeness. A warrant consumes a nonce from a
+ * monotonic per-device sequence, and one minted against the wrong executor is
+ * unspendable: the number is gone and the write never happened.
+ */
+import type { NonceSource } from './nonce-source.js';
+/** Where and as whom to write, plus the key that consents. */
+export interface RelayClientConfig {
+    /**
+     * The relay's base URL — the node's origin, not a path.
+     *
+     * Discover it from {@link CloudClient.getNamespaceRelays} for a hosted
+     * namespace, or take it from the operator for a self-hosted one.
+     */
+    relayUrl: string;
+    /**
+     * The account the relay writes as, hex — a warrant's `executor`.
+     *
+     * An account rather than a key, so one of the relay's processes rotating its
+     * signing key does not void warrants already issued to it. Left unset, the
+     * first `execute` learns it from {@link RelayClient.describe}.
+     */
+    executorAccount?: string;
+    /** The author's account, hex — whose consent the warrant carries. */
+    authorAccount: string;
+    /**
+     * The author's `AccountProof<DeviceCert>`, hex-encoded borsh.
+     *
+     * Proves the key that signed the warrant is a device of the account it names.
+     * The author sends only its own half; the relay attaches its own.
+     */
+    authorProof: string;
+    /**
+     * The author device's ed25519 signing secret, hex (32 bytes).
+     *
+     * Never transmitted. It signs in this process and only the signature leaves,
+     * which is the whole reason a keyholder can author without a node.
+     */
+    deviceSecret: string;
+    /** Where nonces come from. See {@link NonceSource} — a reset replays. */
+    nonces: NonceSource;
+    /**
+     * Seconds a minted warrant stays valid. Defaults to 300.
+     *
+     * Checked by the relay against its own clock and deliberately never by peers,
+     * so this bounds how long *this* request may sit in flight — not how long the
+     * network will accept the delta.
+     */
+    ttlSeconds?: number;
+    /** Injected for tests and non-browser runtimes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** What a relay says about its ability to run intents in one context. */
+export interface RelayDescription {
+    /** The account a warrant must name as `executor`, hex. */
+    executorAccount: string;
+    /** Whether the relay holds `CAN_AUTHOR_ON_BEHALF` on the owning group. */
+    canAuthorOnBehalf: boolean;
+    /** The group whose admin grants that capability, hex. */
+    groupId: string;
+}
+/** Where an accepted intent landed. */
+export interface IntentResult<T = unknown> {
+    /** The context's scope root after the run — did this change anything? */
+    rootHash: string;
+    /** The method's own return value. */
+    returns: T | null;
+}
+/**
+ * Thrown when a relay refuses an intent, carrying which precondition failed.
+ *
+ * The distinction is the whole reason this type exists. A `403` from this
+ * endpoint means one of three unrelated things — no grant on the relay, the
+ * author is not a member, or the nonce was already spent — and they send a
+ * caller somewhere completely different: ask an admin, ask for an invitation,
+ * or just retry. Collapsing them into "forbidden" makes a retryable replay look
+ * like a permissions bug.
+ */
+export declare class IntentRefusedError extends Error {
+    /** The relay's own explanation, verbatim. */
+    readonly reason: string;
+    /** `true` when re-presenting the same intent under a *fresh* warrant may work. */
+    readonly retryable: boolean;
+    readonly status: number;
+    name: string;
+    constructor(
+    /** The relay's own explanation, verbatim. */
+    reason: string, 
+    /** `true` when re-presenting the same intent under a *fresh* warrant may work. */
+    retryable: boolean, status: number);
+}
+export declare class RelayClient {
+    private readonly baseUrl;
+    private executorAccount;
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(config: RelayClientConfig);
+    /**
+     * Ask the relay what it can do in `contextId`.
+     *
+     * Cheap and unauthenticated on a relay that serves delegated execution
+     * publicly, which is what makes it usable as a precondition check rather than
+     * as diagnostics after a failure.
+     */
+    describe(contextId: string): Promise<RelayDescription>;
+    /**
+     * Mint a warrant for `method(args)` and present it to the relay.
+     *
+     * One intent, once: the warrant authorizes exactly this method and these
+     * arguments in exactly this context, and its nonce is spent by the network on
+     * apply. Nothing accumulates and nothing is reusable.
+     */
+    execute<T = unknown>(contextId: string, method: string, argsJson?: unknown): Promise<IntentResult<T>>;
+    private json;
+}

package/dist/relay/relay-client.js

@@ -0,0 +1,157 @@
+/**
+ * Write to a context through a relay, holding nothing but a signing key.
+ *
+ * # What this replaces
+ *
+ * `sdk.rpc.execute` asks a node to run a method *as itself*: it needs a node,
+ * that node needs to be a member, and the caller needs a credential on it. For
+ * a browser tab, a phone, or an agent, none of those three is available — the
+ * runtime cannot compile WASM against materialized state, never received the
+ * scope key that seals the deltas, and has no account on anybody's node.
+ *
+ * This client is the other path. The caller signs a warrant locally, the relay
+ * runs the method as the *author's* principal, and the resulting delta is
+ * attributed to the author's account and device — their replica slot, their
+ * membership, their name in the app. The relay's key signs the envelope and
+ * nothing else.
+ *
+ * # The three preconditions, and why they are checked in this order
+ *
+ * `describe()` answers the first two in one call, before anything is signed:
+ * the relay's executor account (which the warrant must name) and whether it
+ * holds `CAN_AUTHOR_ON_BEHALF` on the owning group. The third — that the
+ * author's account is a member — only the group knows, and it surfaces as a
+ * refusal.
+ *
+ * Checking before signing is not politeness. A warrant consumes a nonce from a
+ * monotonic per-device sequence, and one minted against the wrong executor is
+ * unspendable: the number is gone and the write never happened.
+ */
+import { signWarrant } from '../warrant/warrant.js';
+import { HTTPError } from '../http-client/web-client.js';
+/** How long a freshly minted warrant stays presentable, in seconds. */
+const DEFAULT_TTL_SECONDS = 300;
+/**
+ * Thrown when a relay refuses an intent, carrying which precondition failed.
+ *
+ * The distinction is the whole reason this type exists. A `403` from this
+ * endpoint means one of three unrelated things — no grant on the relay, the
+ * author is not a member, or the nonce was already spent — and they send a
+ * caller somewhere completely different: ask an admin, ask for an invitation,
+ * or just retry. Collapsing them into "forbidden" makes a retryable replay look
+ * like a permissions bug.
+ */
+export class IntentRefusedError extends Error {
+    constructor(
+    /** The relay's own explanation, verbatim. */
+    reason, 
+    /** `true` when re-presenting the same intent under a *fresh* warrant may work. */
+    retryable, status) {
+        super(`relay refused the intent (HTTP ${status}): ${reason}`);
+        this.reason = reason;
+        this.retryable = retryable;
+        this.status = status;
+        this.name = 'IntentRefusedError';
+    }
+}
+export class RelayClient {
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = config.relayUrl.replace(/\/+$/, '');
+        this.executorAccount = config.executorAccount;
+        const injected = config.fetch;
+        this.fetchImpl = injected
+            ? (input, init) => injected(input, init)
+            : (input, init) => globalThis.fetch(input, init);
+        this.timeoutMs = config.timeoutMs ?? 10000;
+    }
+    /**
+     * Ask the relay what it can do in `contextId`.
+     *
+     * Cheap and unauthenticated on a relay that serves delegated execution
+     * publicly, which is what makes it usable as a precondition check rather than
+     * as diagnostics after a failure.
+     */
+    async describe(contextId) {
+        const body = await this.json('GET', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`);
+        // Learned, not merely returned: a client that called `describe` should not
+        // then have to pass the account back in to `execute`.
+        this.executorAccount = body.data.executorAccount;
+        return body.data;
+    }
+    /**
+     * Mint a warrant for `method(args)` and present it to the relay.
+     *
+     * One intent, once: the warrant authorizes exactly this method and these
+     * arguments in exactly this context, and its nonce is spent by the network on
+     * apply. Nothing accumulates and nothing is reusable.
+     */
+    async execute(contextId, method, argsJson = {}) {
+        const executor = this.executorAccount ?? (await this.describe(contextId)).executorAccount;
+        const nonce = await this.config.nonces.next();
+        const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        const warrant = await signWarrant({
+            context: contextId,
+            authorAccount: this.config.authorAccount,
+            executor,
+            method,
+            argsJson,
+            nonce,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
+            deviceSecret: this.config.deviceSecret,
+        });
+        const body = await this.json('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`, { method, argsJson, warrant, authorProof: this.config.authorProof });
+        return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
+    }
+    async json(method, path, body) {
+        const headers = { Accept: 'application/json' };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new HTTPError(0, err instanceof Error ? err.name : 'NetworkError', `${this.baseUrl}${path}`, new Headers(), err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            // 400 and 403 are both caller preconditions and core separates them
+            // deliberately: 400 means re-sending the same bytes cannot help, 403
+            // means the bytes are genuine but authority is missing. Only the spent
+            // nonce is worth retrying, and only under a fresh warrant.
+            if (response.status === 400 || response.status === 403) {
+                const reason = extractReason(text);
+                throw new IntentRefusedError(reason, /nonce/i.test(reason), response.status);
+            }
+            throw new HTTPError(response.status, response.statusText, `${this.baseUrl}${path}`, response.headers, text);
+        }
+        return (await response.json());
+    }
+}
+/** Pull the relay's explanation out of its error body, or fall back to the raw text. */
+function extractReason(bodyText) {
+    if (!bodyText)
+        return 'no reason given';
+    try {
+        const parsed = JSON.parse(bodyText);
+        for (const candidate of [parsed.error, parsed.message]) {
+            if (typeof candidate === 'string' && candidate)
+                return candidate;
+        }
+    }
+    catch {
+        // Not JSON — the text itself is the best available explanation.
+    }
+    return bodyText;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "18.1.1",
+  "version": "18.3.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {
@@ -50,6 +50,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:contract": "tsc --noEmit -p tsconfig.contract.json",
     "typecheck:consumer": "tsc --noEmit -p tsconfig.consumer.json",
+    "typecheck:e2e": "tsc --noEmit -p tsconfig.e2e.json",
     "test:contract": "vitest run --config vitest.config.ts src/__contract__",
     "tsc": "tsc -b",
     "clean": "pnpm rimraf dist",