@calimero-network/mero-js 26.0.0 → 26.1.0

package/dist/account/join-with-node.d.ts

@@ -21,18 +21,13 @@
  * `signer == credential.statement.sign_pk` before applying a join — so an
  * admitter can carry this and can never author it: it cannot admit a different
  * account, change the group, or grant a role. It can refuse, and that is all.
- * This is also why the fleet ingress leaves the route unauthenticated, and why
- * this posts with `fetch` rather than through `AdminApiClient`, which is built
- * around a node credential this caller does not have.
- *
- * ## Why it lives here and not in mero-js
- *
- * Two reasons. `mero-js` is read-only for this change by instruction, and the
- * shape that is actually useful to a caller is the one that hands back a
- * {@link DelegatedSession} — the node that admitted you is the node to connect
- * through — which is `mero-react`'s concern. The pieces that are pure SDK, the
- * borsh op layout and the request type, are used from `mero-js` unchanged and
- * are not reimplemented here.
+ * This is also why core serves the route without a credential (it sits on the
+ * public admin router, beside `/health` and the intent routes, on every node
+ * whatever its auth mode), why the fleet ingress exempts the one anchored path,
+ * and why this posts with `fetch` rather than through `AdminApiClient`, which is
+ * built around a node credential this caller does not have. A node that predates
+ * that change and runs embedded auth answers 401 here; the failure is reported at
+ * the `admit` step like any other refusal.
  *
  * ## Why the op has no parents
  *

package/dist/account/join-with-node.js

@@ -21,18 +21,13 @@
  * `signer == credential.statement.sign_pk` before applying a join — so an
  * admitter can carry this and can never author it: it cannot admit a different
  * account, change the group, or grant a role. It can refuse, and that is all.
- * This is also why the fleet ingress leaves the route unauthenticated, and why
- * this posts with `fetch` rather than through `AdminApiClient`, which is built
- * around a node credential this caller does not have.
- *
- * ## Why it lives here and not in mero-js
- *
- * Two reasons. `mero-js` is read-only for this change by instruction, and the
- * shape that is actually useful to a caller is the one that hands back a
- * {@link DelegatedSession} — the node that admitted you is the node to connect
- * through — which is `mero-react`'s concern. The pieces that are pure SDK, the
- * borsh op layout and the request type, are used from `mero-js` unchanged and
- * are not reimplemented here.
+ * This is also why core serves the route without a credential (it sits on the
+ * public admin router, beside `/health` and the intent routes, on every node
+ * whatever its auth mode), why the fleet ingress exempts the one anchored path,
+ * and why this posts with `fetch` rather than through `AdminApiClient`, which is
+ * built around a node credential this caller does not have. A node that predates
+ * that change and runs embedded auth answers 401 here; the failure is reported at
+ * the `admit` step like any other refusal.
  *
  * ## Why the op has no parents
  *

package/dist/admin-api/redeem-invitation.d.ts

@@ -27,7 +27,14 @@ export type InviteFailureReason =
 'expired'
 /** The link is malformed or names nothing joinable. Only a new link helps. */
  | 'invalid'
-/** The node refused this person (removed, blocked, not allowed). */
+/**
+ * This person already joined with this link once, and has since left. A link
+ * admits each person once: only a new one helps.
+ */
+ | 'already-used'
+/** An admin removed this person. No link readmits them; an admin must re-add them. */
+ | 'removed'
+/** The node refused this person for another reason (blocked, not allowed). */
  | 'refused'
 /** This client's session with the node lapsed; signing in finishes it. */
  | 'signed-out'

package/dist/admin-api/redeem-invitation.js

@@ -28,9 +28,46 @@ export function isSettled(outcome) {
 export function shouldRetain(outcome) {
     return !isSettled(outcome);
 }
+/**
+ * The refusal codes a join route answers with beside `error` (core's
+ * `join_refusal_code`), and what each one tells a person.
+ *
+ * `join_refused_by_member` is absent on purpose: a member that refused may only
+ * be behind, so it says nothing final on its own, and the member's own words
+ * (in the message) are read by {@link reasonFromMessage} instead.
+ */
+const REASON_FOR_CODE = {
+    invitation_expired: 'expired',
+    invitation_invalid: 'invalid',
+    invitation_already_used: 'already-used',
+    removed_from_group: 'removed',
+    reentry_blocked: 'refused',
+};
+/**
+ * The machine-readable `code` a node put beside its `error`, if any: on
+ * mero-js's `HTTPError` it is in the body text, on an axios-style error in
+ * `response.data`.
+ */
+function refusalCodeOf(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const shaped = err;
+    if (typeof shaped.response?.data?.code === 'string')
+        return shaped.response.data.code;
+    if (typeof shaped.bodyText !== 'string')
+        return undefined;
+    try {
+        const body = JSON.parse(shaped.bodyText);
+        return typeof body?.code === 'string' ? body.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Which reason the message alone names, for a node that answers without a
- * useful status — older than rc.56, where every refusal was a bare 500.
+ * useful status — older than rc.56, where every refusal was a bare 500 — or
+ * without a `code`, or for a member's refusal quoted inside a retryable answer.
  *
  * Kept narrow on purpose. Anything not recognised here stays retryable, because
  * the cost of retrying a dead link is one more attempt, while the cost of
@@ -51,8 +88,19 @@ function reasonFromMessage(message) {
         /\binvitation for group .+? is invalid:/.test(m)) {
         return 'invalid';
     }
+    // Core's own words for a spent link and a removal (`MembershipError`), which a
+    // refusing member also quotes back to the joiner.
+    if (m.includes('has already used this invitation'))
+        return 'already-used';
+    if (/\bwas removed from group\b/.test(m))
+        return 'removed';
     return null;
 }
+/**
+ * The reasons that are final whatever status carried them: no later attempt
+ * with this link can succeed for this person.
+ */
+const FINAL_FROM_TEXT = new Set(['already-used', 'removed']);
 /**
  * Why a join failed, and whether a later attempt could work.
  *
@@ -65,6 +113,21 @@ function reasonFromMessage(message) {
 function classifyJoinFailure(err, message) {
     const { kind, status } = classifyError(err);
     const fromText = reasonFromMessage(message);
+    // A code is the node naming the refusal itself: nothing below can know better.
+    const code = refusalCodeOf(err);
+    const fromCode = code ? REASON_FOR_CODE[code] : undefined;
+    if (fromCode)
+        return { reason: fromCode, retryable: false };
+    // A spent link or a removal is final even when a member said it inside a
+    // retryable answer (a 503 for a join every peer refused): asking again only
+    // asks the same members, who will say the same.
+    if (fromText && FINAL_FROM_TEXT.has(fromText))
+        return { reason: fromText, retryable: false };
+    // Any other member refusal is not "no one is online": someone answered, and
+    // their words are the message. Kept, since a member behind on the team's
+    // history refuses what it has not seen yet.
+    if (code === 'join_refused_by_member')
+        return { reason: 'unknown', retryable: true };
     if (status === 401)
         return { reason: 'signed-out', retryable: true };
     if (status === 400)