@calimero-network/mero-js 29.15.0 → 29.16.0

package/README.md

@@ -125,6 +125,41 @@ The pieces it is built from are exported too: the sealed transport
 the client for mero-tee's private agent gate (`attestAgent`, `provisionAgent`,
 `releaseAgent`).
 
+## The runtime and the route layer
+
+The client is two layers. The **runtime** (`@calimero-network/mero-js/runtime`,
+`src/runtime/`) is everything that is not a route: the node's attestation, the
+sealed channel, the credential and the session's refresh on a `401`, moving on
+`421 WRONG_NODE`, D70 retries and failover, the `412 CONFIRM_REQUIRED` passkey
+step-up, error mapping and server-sent events. Its whole surface toward routes is
+one interface:
+
+```ts
+interface Transport {
+  request(method: HttpMethod, path: string, options?: RequestOptions): Promise<Response>; // 2xx, body unread
+  json<T>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+  events(path: string, options?: { query?; signal? }): AsyncGenerator<CloudEvent>;
+}
+// RequestOptions: { query?, body? (JSON) | bytes? + contentType?, passkey? (answers a 412),
+//                   userVerification?, retry?: true | 'once' (D70), signal?, promptSignal? }
+```
+
+A refusal is thrown as its typed `CalimeroError`. `NodeTransport` implements it;
+`routePath('apps/{app}/blobs/{id}', { app, id })` fills a path with encoded
+segments. The **route layer**, `CalimeroClient`, is the hand-written methods on
+top; `client.transport` is its runtime, so a route layer of your own (one
+generated from the node's OpenAPI document, say) shares the client's session:
+
+```ts
+import { routePath } from '@calimero-network/mero-js/runtime';
+
+const app = await client.transport.json('GET', routePath('apps/{app}', { app: appId }));
+await client.transport.json('DELETE', routePath('orgs/{org}', { org }), { body: {}, passkey });
+```
+
+The `/runtime` entry re-exports the package's own bundle, so its error classes are
+the ones `CalimeroClient` throws (`instanceof` holds across both imports).
+
 ## Development
 
 ```bash

package/dist/cloud-v2/client.d.ts

@@ -9,17 +9,13 @@
  * const { result } = await cloud.call(appId, 'set', { key: 'a', value: '1' });
  * ```
  */
+import { DEFAULT_RETRY, NodeTransport, retryDelayMs, type CalimeroSession, type CloudEvent, type CloudRetryOptions } from '../runtime/transport.js';
 import { type AttestationDoc, type CloudPolicy } from './attestation.js';
 import { type PasskeyProvider } from './passkey.js';
 import { type AppsReport, type ConsentRequest, type ConsentResult, type ConsentStarted, type OpenConsentOptions, type OpsAppsReport, type OpsOrgsReport, type PageOptions, type PendingApprovals, type PublisherBindingInfo, type PublisherProof, type ReleaseRules } from './approvals.js';
 export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmPromptBlocked, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, PasskeyUnknownHere, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, RuntimeTooOld, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export type { Committed, SignUpRefusal } from './errors.js';
-export interface CalimeroSession {
-    accountId: string;
-    sessionToken: string;
-    expiresAt: number;
-    refreshToken: string;
-}
+export type { CalimeroSession, CloudEvent };
 export interface CallResult {
     index: number;
     result: unknown;
@@ -32,11 +28,6 @@ export interface ViewResult {
     index: number;
     result: unknown;
 }
-export interface CloudEvent {
-    id: string;
-    kind: string;
-    data: unknown;
-}
 /** What installing a package release answers. */
 export interface PackageInstalled {
     package: string;
@@ -703,31 +694,8 @@ export interface SignUpPolicy {
     /** Whether a sign-up without an invite is refused. */
     inviteRequired: boolean;
 }
-/**
- * How a call or a view is sent again while the node is unavailable (D70): with
- * the same key, after a backoff that starts at `baseDelayMs` and doubles up to
- * `maxDelayMs`, no jitter, at most `retries` times. The defaults are the Rust
- * client's: 6 retries, 200 ms doubling, at most 2 s (about 9 s in all, past a
- * leader election).
- */
-export interface CloudRetryOptions {
-    /** Retries after the first attempt. Default 6. */
-    retries?: number;
-    /** The first backoff; each retry doubles it. Default 200 ms. */
-    baseDelayMs?: number;
-    /** The longest backoff. Default 2 s. */
-    maxDelayMs?: number;
-}
-export declare const DEFAULT_RETRY: {
-    readonly retries: 6;
-    readonly baseDelayMs: 200;
-    readonly maxDelayMs: 2000;
-};
-/** The backoff before retry `retry` (0 for the first): `baseDelayMs` doubling, at most `maxDelayMs`. */
-export declare function retryDelayMs(retry: number, options: {
-    baseDelayMs: number;
-    maxDelayMs: number;
-}): number;
+export { DEFAULT_RETRY, retryDelayMs };
+export type { CloudRetryOptions };
 export interface CalimeroClientOptions {
     /** One node of the cluster: the one the client talks to first. */
     baseUrl: string;
@@ -763,24 +731,15 @@ export interface CalimeroConnectOptions {
     random?: () => number;
 }
 export declare class CalimeroClient {
-    /** Every node this client may use, `baseUrl` first (or as the directory last ordered them). */
-    private nodeUrls;
-    /** The one in use: an index into {@link nodeUrls}. */
-    private at;
-    /** A sealed fetch per node, each attesting its own node on first use. */
-    private readonly channels;
-    private readonly policy;
-    /** The unsealed fetch, for the one route served in the clear (`/attestation`). */
-    private readonly raw;
-    private auth;
-    private current;
-    /** The refresh under way, which every request that needs one shares. */
-    private refreshing;
-    private readonly retry;
-    /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
-    private readonly networkFailures;
-    /** The directory the node list came from, for a client made by {@link connect}. */
-    private source;
+    /**
+     * The runtime every route of this client is sent through
+     * (`@calimero-network/mero-js/runtime`): the attested, sealed channel to each
+     * node, the credential and its refresh, the `412 CONFIRM_REQUIRED` step-up,
+     * D70 retries and error mapping. A route layer of its own (one generated from
+     * the node's OpenAPI document, say) sends through it and shares this
+     * client's session.
+     */
+    readonly transport: NodeTransport;
     /**
      * A client for the Calimero Cloud cluster named `cluster`: its node list read
      * from the public node directory, those in `zone` first, each group in
@@ -792,87 +751,18 @@ export declare class CalimeroClient {
      * first request once the directory's `refreshAfterSeconds` has passed.
      */
     static connect(options: CalimeroConnectOptions): Promise<CalimeroClient>;
-    constructor(options: CalimeroClientOptions);
+    /** A client of the nodes `options` names, or one sending through an existing `transport`. */
+    constructor(options: CalimeroClientOptions | NodeTransport);
     /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved the client on. */
     get nodeUrl(): string;
     /** Every node this client may use, in the order it moves through them. */
     get nodes(): string[];
-    /** The sealed channel to `url`, attested under the client's policy before its first request. */
-    private channel;
-    /**
-     * Move on from node `from` (the one that answered `421 WRONG_NODE`) to the
-     * next one. False when there is no other. A request that saw the same node
-     * refuse after another request moved on already does not move again.
-     */
-    private moveOn;
-    /**
-     * Fail over from node `from`, where a request's retries ran out, to the next
-     * node it has not `tried`. False when it has tried them all. A request whose
-     * node another request moved away from already goes to that node, if untried.
-     */
-    private failOver;
-    /**
-     * Read the node list again from the directory, in the background, for a
-     * client made by {@link connect}: the node in use stays first, then the
-     * directory's order; a node no longer listed is dropped. A failed read is
-     * ignored. One read at a time.
-     */
-    private reread;
     /** Authenticate every request with an API key. */
     useApiKey(key: string): void;
     useSession(session: CalimeroSession): void;
     get session(): CalimeroSession | undefined;
-    /**
-     * Send one request to the node in use, with the credential held now, and
-     * answer the response, whatever its status. {@link send} judges it.
-     */
-    private request;
-    /**
-     * {@link request}, answering what a lost issuing node or a node on the
-     * wrong release does to a session: a successful response, or the refusal as a
-     * typed error ({@link errorFrom}).
-     *
-     * - `401 UNAUTHENTICATED` to a request that carried a session: the node that
-     *   signed the session may be gone, replaced, or out of reach of the node
-     *   asked, which any node of the cluster answers with a refresh. The client
-     *   refreshes once, shared by every request that needs it at the same time
-     *   ({@link refresh}), and repeats the request once. A refresh that is
-     *   refused surfaces as {@link LoginRequired}.
-     * - `421 WRONG_NODE`: this node's release may not serve the account. The
-     *   client moves to the next node it knows and repeats the request once; with
-     *   none, the {@link WrongNode} reaches the caller.
-     *
-     * Repeating is safe even for a request that is not idempotent: the node
-     * answers `401` and `421` when it judges the credential, before it reads what
-     * the request asks, so the first attempt ran nothing. The exceptions are the
-     * ceremonies that mint a session ({@link ceremony}), never repeated here.
-     */
-    private send;
-    /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
-    private mayRefresh;
-    /**
-     * A fresh session in place of the one `token` belonged to: by the refresh
-     * another request already made, or by one this request starts.
-     */
-    private renew;
+    /** A JSON request, or a raw one when `raw` is given (as `contentType`, the transport's default when absent). */
     private json;
-    /**
-     * {@link json} for a call or a view (D70): while the node answers 503 or
-     * cannot be reached, the same request, with the same idempotency key, is sent
-     * again after {@link retryDelayMs} (or the pause the node asked for, if
-     * longer), at most `retries` times. Every other answer is final.
-     *
-     * When a node's retries run out, the request fails over to the next node the
-     * client knows and its retries start again there, with the same key: the
-     * key is kept in the app's replicated log, so the cluster answers it once
-     * whichever node it reaches. Each node is tried once per request. The last
-     * failure surfaces as {@link UnavailableError}: the node's 503, or reason
-     * `network` for a connection that failed, whose `committed` is `'unknown'`.
-     *
-     * `once` sends the request exactly once, to the node in use (the confirmed
-     * attempt of {@link callConfirmed}, whose challenge is single-use).
-     */
-    private retried;
     post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
     get<T = Record<string, unknown>>(path: string): Promise<T>;
     put<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
@@ -917,7 +807,6 @@ export declare class CalimeroClient {
      * same token again (which would revoke the session).
      */
     refresh(): Promise<CalimeroSession>;
-    private exchangeRefresh;
     /**
      * End this session. The client is signed out whether or not the node
      * answers: the revoke (`POST /auth/logout`) is attempted, and its failure
@@ -1177,6 +1066,10 @@ export declare class CalimeroClient {
      * confirmed retry carries `confirm` beside it.
      */
     deleteConfirmed<T>(path: string, passkey: PasskeyProvider, body?: Record<string, unknown>): Promise<T>;
+    /**
+     * `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey` when one
+     * is given; `signal` aborts only the passkey prompt.
+     */
     private confirmed;
     /**
      * Create an app instance from a bundle hash, or from a package release
@@ -1219,8 +1112,6 @@ export declare class CalimeroClient {
     }): Promise<ViewResult>;
     /** Committed events from index `from`, then live, until `signal` aborts. */
     events(app: string, from?: number, signal?: AbortSignal): AsyncGenerator<CloudEvent>;
-    /** A server-sent event stream on `path`, sealed like every other answer. */
-    private stream;
     /**
      * Publish this device's presence in `app`: `state` (at most 4 KiB) or `null`
      * to retract it. The newest `seq` wins; send the same `seq` and state again