@calimero-network/mero-js 26.4.1 → 26.5.0

package/dist/account/index.d.ts

@@ -4,8 +4,8 @@ export { resolveRoot } from './account.js';
 export type { RootSource } from './account.js';
 export { resolveRootPair } from './account.js';
 export type { ResolvedRoot } from './account.js';
-export type { DelegatedCredential, DelegatedSession as DelegatedAccountSession, RelayMap, RelayNodeKeyAttempt } from './session.js';
-export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, } from './session.js';
+export type { DelegatedCredential, DelegatedSession as DelegatedAccountSession, RelayMap, RelayNodeKeyAttempt, RelayListingFailure } from './session.js';
+export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, RelaysUnavailableError, } from './session.js';
 export { resolveRelayFromInvitation, normaliseAccount } from './relay-from-invitation.js';
 export type { RelayResolutionStep, RelayResolutionFailure, ResolvedInvitationRelay, ResolveRelayResult, ResolveRelayFromInvitationInput, } from './relay-from-invitation.js';
 export { joinWithNode } from './join-with-node.js';

package/dist/account/index.js

@@ -2,7 +2,7 @@
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, createAccountRootSigner, accountRootSignerFromPhrase, signAccountLink, signAccountLogin, } from './account.js';
 export { resolveRoot } from './account.js';
 export { resolveRootPair } from './account.js';
-export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, } from './session.js';
+export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, RelaysUnavailableError, } from './session.js';
 export { resolveRelayFromInvitation, normaliseAccount } from './relay-from-invitation.js';
 export { joinWithNode } from './join-with-node.js';
 export { bootstrapFromInvitation } from './bootstrap-from-invitation.js';

package/dist/account/session.d.ts

@@ -209,6 +209,36 @@ export declare function relayForContext(account: string, contextId: string): str
 export declare function carryExecutorAccount(prev: DelegatedSession | null, next: DelegatedSession): DelegatedSession;
 /** Every relay this account is known to use: the session's, and each in the map. */
 export declare function knownRelays(s: DelegatedSession): string[];
+/**
+ * Thrown by {@link listDelegatedContexts} and {@link listDelegatedNamespaces}
+ * when the account knows relays and **none** of them answered.
+ *
+ * One relay down is skipped, as before: the others still answer for what they
+ * serve. Every relay down is different. Returning `[]` then reads as "a member
+ * of nothing", and an app renders an empty account, with no error, for what is
+ * really "could not ask". A relay whose hostname no longer resolves (a node
+ * rebuilt or deleted in the cloud) did exactly that.
+ */
+/**
+ * Why one relay did not answer a listing.
+ *
+ * `refused`: its attestation did not verify (an untrusted image, a release
+ * below the floor). Asking again cannot change that, and it may be worth a
+ * closer look. `unavailable`: something on the way did not answer, or the
+ * relay refused the request itself; trying again later may.
+ */
+export interface RelayListingFailure {
+    relayUrl: string;
+    kind: 'refused' | 'unavailable';
+    error: unknown;
+}
+export declare class RelaysUnavailableError extends Error {
+    readonly failures: readonly RelayListingFailure[];
+    readonly relays: readonly string[];
+    constructor(failures: readonly RelayListingFailure[]);
+    /** Every relay refused its attestation: retrying will not help. */
+    get refused(): boolean;
+}
 type ListedContext = Awaited<ReturnType<MeroClient['admin']['getContexts']>>['contexts'][number];
 /**
  * This account's contexts on every relay it knows, each tagged with the relay
@@ -216,7 +246,8 @@ type ListedContext = Awaited<ReturnType<MeroClient['admin']['getContexts']>>['co
  *
  * Each relay answers only for itself and only for this caller, so the union is
  * exactly the account's contexts across relays. A relay that cannot be reached
- * or logged in to is skipped (its contexts simply do not appear), not fatal.
+ * or logged in to is skipped (its contexts simply do not appear), not fatal,
+ * unless it is every relay: then {@link RelaysUnavailableError}.
  */
 export declare function listDelegatedContexts(s: DelegatedSession): Promise<Array<ListedContext & {
     relayUrl: string;
@@ -226,7 +257,8 @@ type ListedNamespace = Awaited<ReturnType<MeroClient['admin']['listNamespaces']>
  * This account's namespaces on every relay it knows, each tagged with the relay
  * that listed it and recorded as that namespace's relay. Same rules as
  * {@link listDelegatedContexts}: each relay answers for itself and this caller
- * only (`namespace:list-own`); an unreachable relay is skipped.
+ * only (`namespace:list-own`); an unreachable relay is skipped, and every
+ * relay unreachable is {@link RelaysUnavailableError}.
  */
 export declare function listDelegatedNamespaces(s: DelegatedSession): Promise<Array<ListedNamespace & {
     relayUrl: string;

package/dist/account/session.js

@@ -804,24 +804,56 @@ export function knownRelays(s) {
         .map(relayOrigin);
     return [...new Set(all)];
 }
+export class RelaysUnavailableError extends Error {
+    constructor(failures) {
+        super(`none of this account's relays answered: ${failures.map((f) => `${f.relayUrl} (${f.kind})`).join(', ')}`);
+        this.failures = failures;
+        this.name = 'RelaysUnavailableError';
+        this.relays = failures.map((f) => f.relayUrl);
+    }
+    /** Every relay refused its attestation: retrying will not help. */
+    get refused() {
+        return this.failures.every((f) => f.kind === 'refused');
+    }
+}
+/**
+ * One relay's client for a listing, or the failure that stopped it. The key's
+ * own outcome is kept, so a refused attestation is not reported as a relay
+ * that merely did not answer.
+ */
+async function listingClient(s, relayUrl) {
+    const key = await attemptRelayNodeKey(relayUrl);
+    if (key.kind !== 'learned') {
+        console.warn('[mero-js] could not learn the relay node key from its attestation', key.error);
+        return { failure: { relayUrl, kind: key.kind, error: key.error } };
+    }
+    const client = buildDelegatedClient({ ...s, relayUrl }, null);
+    if (!client)
+        return { failure: { relayUrl, kind: 'unavailable', error: new Error(`no client for ${relayUrl}`) } };
+    return { client };
+}
 /**
  * This account's contexts on every relay it knows, each tagged with the relay
  * that listed it — and that relay recorded as the one serving it.
  *
  * Each relay answers only for itself and only for this caller, so the union is
  * exactly the account's contexts across relays. A relay that cannot be reached
- * or logged in to is skipped (its contexts simply do not appear), not fatal.
+ * or logged in to is skipped (its contexts simply do not appear), not fatal,
+ * unless it is every relay: then {@link RelaysUnavailableError}.
  */
 export async function listDelegatedContexts(s) {
     const out = [];
     const map = readRelayMap(s.account);
-    for (const relayUrl of knownRelays(s)) {
+    const relays = knownRelays(s);
+    const failures = [];
+    for (const relayUrl of relays) {
+        const got = await listingClient(s, relayUrl);
+        if ('failure' in got) {
+            failures.push(got.failure);
+            continue;
+        }
+        const { client } = got;
         try {
-            if (!(await resolveRelayNodeKey(relayUrl)))
-                continue;
-            const client = buildDelegatedClient({ ...s, relayUrl }, null);
-            if (!client)
-                continue;
             const { contexts } = await client.admin.getContexts();
             for (const c of contexts ?? []) {
                 out.push({ ...c, relayUrl });
@@ -829,30 +861,37 @@ export async function listDelegatedContexts(s) {
             }
         }
         catch (e) {
+            failures.push({ relayUrl, kind: 'unavailable', error: e });
             console.warn(`[mero-js] could not list contexts on ${relayUrl}`, e);
         }
     }
     writeRelayMap(s.account, map);
+    if (relays.length > 0 && failures.length === relays.length)
+        throw new RelaysUnavailableError(failures);
     return out;
 }
 /**
  * This account's namespaces on every relay it knows, each tagged with the relay
  * that listed it and recorded as that namespace's relay. Same rules as
  * {@link listDelegatedContexts}: each relay answers for itself and this caller
- * only (`namespace:list-own`); an unreachable relay is skipped.
+ * only (`namespace:list-own`); an unreachable relay is skipped, and every
+ * relay unreachable is {@link RelaysUnavailableError}.
  */
 export async function listDelegatedNamespaces(s) {
     var _a, _b;
     const out = [];
     const seen = new Set();
     const map = readRelayMap(s.account);
-    for (const relayUrl of knownRelays(s)) {
+    const relays = knownRelays(s);
+    const failures = [];
+    for (const relayUrl of relays) {
+        const got = await listingClient(s, relayUrl);
+        if ('failure' in got) {
+            failures.push(got.failure);
+            continue;
+        }
+        const { client } = got;
         try {
-            if (!(await resolveRelayNodeKey(relayUrl)))
-                continue;
-            const client = buildDelegatedClient({ ...s, relayUrl }, null);
-            if (!client)
-                continue;
             for (const ns of await client.admin.listNamespaces()) {
                 if (seen.has(ns.namespaceId))
                     continue;
@@ -862,9 +901,12 @@ export async function listDelegatedNamespaces(s) {
             }
         }
         catch (e) {
+            failures.push({ relayUrl, kind: 'unavailable', error: e });
             console.warn(`[mero-js] could not list namespaces on ${relayUrl}`, e);
         }
     }
     writeRelayMap(s.account, map);
+    if (relays.length > 0 && failures.length === relays.length)
+        throw new RelaysUnavailableError(failures);
     return out;
 }