@calimero-network/mero-js 21.2.2 → 21.3.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { MeroJsConfig, TokenData } from "./mero-js.js";
 export * from "./http-client/index.js";
 export * from "./auth-api/index.js";
 export * from "./admin-api/index.js";
+export * from "./errors/index.js";
 export { parseAuthCallback, buildAuthLoginUrl } from "./auth/index.js";
 export type { AuthCallbackResult, AuthLoginOptions } from "./auth/index.js";
 export { MemoryTokenStore, LocalStorageTokenStore, } from "./token-store/index.js";

package/dist/index.js

@@ -8,6 +8,8 @@ export * from "./http-client/index.js";
 export * from "./auth-api/index.js";
 // Admin API client
 export * from "./admin-api/index.js";
+// What a failed request means — kind, retryable, the node's own words
+export * from "./errors/index.js";
 // Auth utilities
 export { parseAuthCallback, buildAuthLoginUrl } from "./auth/index.js";
 // Token store

package/dist/index.mjs

@@ -59,6 +59,7 @@ var HTTPError = class extends Error {
     this.headers = headers;
     this.bodyText = bodyText;
     this.name = "HTTPError";
+    this.explanation = explanation;
   }
   toJSON() {
     return {
@@ -755,6 +756,145 @@ function withoutCap(mask, cap) {
   return (mask & ~cap) >>> 0;
 }
 
+// src/errors/classify.ts
+var RETRYABLE = {
+  invalid: false,
+  // The session, not the request: signing in again and repeating it works.
+  unauthorized: true,
+  forbidden: false,
+  // Too broad to give up on — the resource may simply not have synced yet.
+  "not-found": true,
+  conflict: false,
+  gone: false,
+  "too-large": false,
+  "rate-limited": true,
+  unavailable: true,
+  server: true,
+  unreachable: true,
+  unknown: true
+};
+function kindForStatus(status) {
+  switch (status) {
+    case 0:
+      return "unreachable";
+    case 400:
+      return "invalid";
+    case 401:
+      return "unauthorized";
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not-found";
+    case 409:
+      return "conflict";
+    case 410:
+      return "gone";
+    case 413:
+      return "too-large";
+    case 429:
+      return "rate-limited";
+    case 503:
+    case 504:
+      return "unavailable";
+  }
+  if (status >= 500 && status < 600) return "server";
+  if (status >= 400 && status < 500) return "invalid";
+  return "unknown";
+}
+function statusOf(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const shaped = err;
+  for (const candidate of [shaped.status, shaped.response?.status, shaped.statusCode]) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) return candidate;
+  }
+  return void 0;
+}
+function messageOf(err, fallback = "Request failed") {
+  if (typeof err === "string") return err.trim() || fallback;
+  if (!err || typeof err !== "object") return fallback;
+  const shaped = err;
+  for (const candidate of [
+    shaped.explanation,
+    shaped.response?.data?.error,
+    shaped.response?.data?.message,
+    shaped.data?.message,
+    shaped.error,
+    shaped.message
+  ]) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate;
+  }
+  return fallback;
+}
+function classifyError(err) {
+  const status = statusOf(err);
+  let kind;
+  if (status !== void 0) {
+    kind = kindForStatus(status);
+  } else if (err instanceof TypeError) {
+    kind = "unreachable";
+  } else {
+    kind = "unknown";
+  }
+  return { kind, status, retryable: RETRYABLE[kind], message: messageOf(err) };
+}
+
+// src/admin-api/redeem-invitation.ts
+function isSettled(outcome) {
+  return outcome.status !== "failed" || !outcome.retryable;
+}
+function shouldRetain(outcome) {
+  return !isSettled(outcome);
+}
+function reasonFromMessage(message) {
+  const m = message.toLowerCase();
+  if (m.includes("invitation has expired") || m.includes("invitation expired") || // Core rc.56+ names the group between the words: "invitation for group
+  // <id> expired at <secs>".
+  /\binvitation for group .+? expired at \d+/.test(m)) {
+    return "expired";
+  }
+  if (m.includes("malformed") || m.includes("does not match namespace_id") || m.includes("invalid invitation") || /\binvitation for group .+? is invalid:/.test(m)) {
+    return "invalid";
+  }
+  return null;
+}
+function classifyJoinFailure(err, message) {
+  const { kind, status } = classifyError(err);
+  const fromText = reasonFromMessage(message);
+  if (status === 401) return { reason: "signed-out", retryable: true };
+  if (status === 400) return { reason: fromText ?? "invalid", retryable: false };
+  if (status === 410) return { reason: "expired", retryable: false };
+  if (status === 403) return { reason: "refused", retryable: false };
+  if (status === 409) return { reason: fromText ?? "refused", retryable: false };
+  if (kind === "unavailable") return { reason: "no-one-online", retryable: true };
+  if (kind === "unreachable") return { reason: "node-unreachable", retryable: true };
+  if (fromText) return { reason: fromText, retryable: false };
+  return { reason: "unknown", retryable: true };
+}
+async function redeemInvitation(parsed, redeemer) {
+  const { namespaceId, invitation, teamName } = parsed;
+  let joinError = null;
+  try {
+    await redeemer.join(namespaceId, invitation);
+  } catch (err) {
+    joinError = err;
+  }
+  let listed = null;
+  try {
+    listed = (await redeemer.memberships()).includes(namespaceId);
+  } catch {
+    listed = null;
+  }
+  if (joinError === null) {
+    return { status: "joined", namespaceId, teamName };
+  }
+  if (listed === true) {
+    return { status: "already-member", namespaceId, teamName };
+  }
+  const message = messageOf(joinError, "Could not join. Check the invitation.");
+  const { reason, retryable } = classifyJoinFailure(joinError, message);
+  return { status: "failed", namespaceId, message, reason, retryable };
+}
+
 // src/admin-api/admin-client.ts
 function unwrap(response) {
   return response?.data;
@@ -1332,6 +1472,40 @@ var AdminApiClient = class {
     }
     return data;
   }
+  /**
+   * Join the namespace an invitation grants, and say what happened — including
+   * when the request failed but the join landed anyway.
+   *
+   * Use this rather than {@link joinNamespace} whenever someone is following an
+   * invitation. A join waits for a member to come online and can outlast any
+   * proxy in front of the node; the request then fails while the join
+   * succeeds. This sends the join once, then checks {@link listNamespaces}:
+   * a failed request whose namespace is listed is `already-member`, a success.
+   *
+   * Never throws for an ordinary failure. A failed outcome carries a `reason`
+   * read off the node's status (core rc.56+), and `retryable`, which says
+   * whether to keep the invitation for another attempt.
+   *
+   * @param namespaceId the namespace the invitation names, 64 hex
+   * @param invitation the signed invitation, as the inviter's node minted it
+   * @param options `groupName` is sent with the join; `teamName` is echoed back
+   *   on a successful outcome for the caller's UI
+   */
+  async redeemInvitation(namespaceId, invitation, options = {}) {
+    const { groupName, teamName } = options;
+    return redeemInvitation(
+      { namespaceId, invitation, teamName },
+      {
+        join: async () => {
+          await this.joinNamespace(
+            namespaceId,
+            groupName === void 0 ? { invitation } : { invitation, groupName }
+          );
+        },
+        memberships: async () => (await this.listNamespaces() ?? []).map((n) => n.namespaceId)
+      }
+    );
+  }
   async createGroupInNamespace(namespaceId, request) {
     return unwrap(
       await this.httpClient.post(
@@ -7556,6 +7730,7 @@ export {
   admitterAddrsFromNetworkStatus,
   buildAuthLoginUrl,
   callerProof,
+  classifyError,
   combineSignals,
   compareSemver,
   connectCloud,
@@ -7589,6 +7764,7 @@ export {
   hasCap,
   hexEncodeUtf8,
   intentHash,
+  isSettled,
   jsonCodec,
   localNodeUrl,
   login,
@@ -7596,8 +7772,10 @@ export {
   nodeEndpoint,
   parseAuthCallback,
   probeNodeHealth,
+  redeemInvitation,
   requestBodyHash,
   routingProofHeaders,
+  shouldRetain,
   signAccountLink,
   signAccountLogin,
   signDeviceCert,