@openzeppelin/guardian-client 0.15.0 → 0.16.0

package/src/http.test.ts

@@ -69,6 +69,97 @@ describe('GuardianHttpClient', () => {
       expect(error).toBeInstanceOf(GuardianHttpError);
       expect(error.status).toBe(500);
       expect(error.statusText).toBe('Internal Server Error');
+      // Non-JSON body: no typed envelope fields.
+      expect(error.code).toBeNull();
+      expect(error.releasedAt).toBeNull();
+    });
+
+    it('exposes code and released_at from a GUARDIAN_ACCOUNT_RELEASED envelope', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_ACCOUNT_RELEASED',
+            message: 'This account has moved to a different guardian. Reconnect it to continue.',
+            meta: { retryable: false, released_at: '2026-07-06T10:00:00Z' },
+          }),
+      });
+
+      const error = await client.getPubkey().catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(409);
+      expect(error.code).toBe('account_released');
+      expect(error.rawCode).toBe('GUARDIAN_ACCOUNT_RELEASED');
+      expect(error.releasedAt).toBe('2026-07-06T10:00:00Z');
+    });
+
+    it('exposes code without releasedAt for other envelope errors', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: async () =>
+          JSON.stringify({
+            code: 'account_not_found',
+            message: "We couldn't find that. It may have been completed or removed.",
+            meta: { retryable: false },
+          }),
+      });
+
+      const error = await client.getPubkey().catch((e) => e);
+      expect(error.code).toBe('account_not_found');
+      expect(error.releasedAt).toBeNull();
+    });
+  });
+
+  describe('getStatus', () => {
+    it('maps the server status response to camelCase', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          status: 'ok',
+          version: '0.1.0',
+          git_commit: 'abc123def456',
+          environment: 'devnet',
+          started_at: '2026-06-17T10:00:00Z',
+          uptime_seconds: 3600,
+        }),
+      });
+
+      const status = await client.getStatus();
+
+      expect(status).toEqual({
+        status: 'ok',
+        version: '0.1.0',
+        gitCommit: 'abc123def456',
+        environment: 'devnet',
+        startedAt: '2026-06-17T10:00:00Z',
+        uptimeSeconds: 3600,
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:3000/status',
+        expect.objectContaining({
+          method: 'GET',
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+          }),
+        })
+      );
+    });
+
+    it('should throw GuardianHttpError on non-ok response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 503,
+        statusText: 'Service Unavailable',
+        text: async () => 'down',
+      });
+
+      const error = await client.getStatus().catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(503);
     });
   });
 
@@ -365,6 +456,157 @@ describe('GuardianHttpClient', () => {
     });
   });
 
+  describe('abandonCandidate', () => {
+    it('should record an abandon intent and map the response to camelCase', async () => {
+      client.setSigner(mockSigner);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          account_id: '0x' + 'a'.repeat(30),
+          nonce: 7,
+          state: 'pending',
+          abandon_requested_at: '2026-07-14T12:00:00Z',
+        }),
+      });
+
+      const result = await client.abandonCandidate('0x' + 'a'.repeat(30), 7);
+
+      expect(result).toEqual({
+        accountId: '0x' + 'a'.repeat(30),
+        nonce: 7,
+        state: 'pending',
+        abandonRequestedAt: '2026-07-14T12:00:00Z',
+      });
+
+      // Wire format is snake_case
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:3000/delta/candidate/abandon',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            account_id: '0x' + 'a'.repeat(30),
+            nonce: 7,
+          }),
+        })
+      );
+    });
+
+    it('surfaces 409 GUARDIAN_CANDIDATE_LANDED with a parseable error envelope', async () => {
+      client.setSigner(mockSigner);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_CANDIDATE_LANDED',
+            message: "This transaction already went through, so it can't be abandoned.",
+            meta: { retryable: false },
+          }),
+      });
+
+      const error = await client
+        .abandonCandidate('0x' + 'a'.repeat(30), 7)
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(409);
+      expect(error.code).toBe('candidate_landed');
+      expect(error.rawCode).toBe('GUARDIAN_CANDIDATE_LANDED');
+    });
+
+    it('surfaces 404 delta_not_found when no candidate exists at the nonce', async () => {
+      client.setSigner(mockSigner);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: async () =>
+          JSON.stringify({
+            code: 'delta_not_found',
+            message: "We couldn't find that. It may have been completed or removed.",
+            meta: { retryable: false },
+          }),
+      });
+
+      const error = await client
+        .abandonCandidate('0x' + 'a'.repeat(30), 7)
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(404);
+      expect(error.code).toBe('delta_not_found');
+    });
+  });
+
+  describe('abandonStatus', () => {
+    const serverDelta = (status: object) => ({
+      account_id: '0x' + 'a'.repeat(30),
+      nonce: 7,
+      prev_commitment: '0x' + 'b'.repeat(64),
+      delta_payload: { tx_summary: { data: 'base64summary' }, signatures: [] },
+      status,
+    });
+
+    it('classifies a still-pending candidate as waiting', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({ status: 'candidate', timestamp: '2026-07-14T12:00:00Z' }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('waiting');
+    });
+
+    it('classifies a canonicalized delta as landed', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({ status: 'canonical', timestamp: '2026-07-14T12:00:00Z' }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('landed');
+    });
+
+    it('classifies a client-abandoned discard as abandoned', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({
+            status: 'discarded',
+            timestamp: '2026-07-14T12:00:00Z',
+            reason: 'client_abandoned',
+          }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('abandoned');
+    });
+
+    it('classifies a reasonless discard and a missing delta as unexpected', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({ status: 'discarded', timestamp: '2026-07-14T12:00:00Z' }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('unexpected');
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: async () =>
+          JSON.stringify({
+            code: 'delta_not_found',
+            message: "We couldn't find that. It may have been completed or removed.",
+            meta: { retryable: false },
+          }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('unexpected');
+    });
+  });
+
   describe('signDeltaProposal', () => {
     it('should sign a delta proposal', async () => {
       client.setSigner(mockSigner);
@@ -733,6 +975,27 @@ describe('GuardianHttpError', () => {
     expect(error.name).toBe('GuardianHttpError');
   });
 
+  it('parses a { code, message, meta } body into structured accessors (feature 009)', () => {
+    const body = JSON.stringify({
+      code: 'rate_limit_exceeded',
+      message: 'Too many requests — please try again shortly.',
+      meta: { retryable: true, retry_after_secs: 30 },
+    });
+    const error = new GuardianHttpError(429, 'Too Many Requests', body);
+    expect(error.code).toBe('rate_limit_exceeded');
+    expect(error.userMessage).toBe('Too many requests — please try again shortly.');
+    expect(error.meta?.retryable).toBe(true);
+    expect(error.meta?.retryAfterSecs).toBe(30); // snake_case → camelCase
+  });
+
+  it('leaves accessors undefined for a non-JSON / non-conforming body', () => {
+    const plain = new GuardianHttpError(502, 'Bad Gateway', 'upstream exploded');
+    expect(plain.code).toBeNull();
+    expect(plain.releasedAt).toBeNull();
+    expect(plain.userMessage).toBeUndefined();
+    expect(plain.meta).toBeUndefined();
+  });
+
   describe('error envelope contract (account-paused path)', () => {
     let client: GuardianHttpClient;
     beforeEach(() => {
@@ -743,15 +1006,18 @@ describe('GuardianHttpError', () => {
     it('surfaces 409 GUARDIAN_ACCOUNT_PAUSED with a parseable error envelope on pushDeltaProposal', async () => {
       client.setSigner(mockSigner);
 
-      // The server's GuardianError::AccountPaused → IntoResponse contract.
-      // Locks client/server in lockstep: a regression to the legacy
+      // The server's GuardianError::AccountPaused → IntoResponse contract,
+      // reshaped to { code, message, meta } (feature 009). Locks client/server
+      // in lockstep: a regression to the legacy { success, error, paused_* } or
       // "(400, {delta: {account_id: 'error text'}})" shape would break this.
       const envelope = {
-        success: false,
         code: 'GUARDIAN_ACCOUNT_PAUSED',
-        error: 'Account is paused: compliance review',
-        paused_at: '2026-05-20T10:00:00Z',
-        paused_reason: 'compliance review',
+        message: "This account is paused and can't approve transactions right now.",
+        meta: {
+          retryable: false,
+          paused_at: '2026-05-20T10:00:00Z',
+          paused_reason: 'compliance review',
+        },
       };
 
       mockFetch.mockResolvedValueOnce({
@@ -772,26 +1038,37 @@ describe('GuardianHttpError', () => {
         .catch((e) => e as GuardianHttpError);
 
       expect(error).toBeInstanceOf(GuardianHttpError);
-      expect((error as GuardianHttpError).status).toBe(409);
-
-      const parsed = JSON.parse((error as GuardianHttpError).body);
-      expect(parsed.success).toBe(false);
-      expect(parsed.code).toBe('GUARDIAN_ACCOUNT_PAUSED');
-      expect(typeof parsed.error).toBe('string');
-      expect(parsed.paused_at).toBe('2026-05-20T10:00:00Z');
-      expect(parsed.paused_reason).toBe('compliance review');
-      // Negative assertion: legacy "stuff error into delta.account_id" shape.
+      const e = error as GuardianHttpError;
+      expect(e.status).toBe(409);
+
+      // Structured accessors parsed from { code, message, meta } (feature 009).
+      expect(e.code).toBe('account_paused');
+      expect(e.rawCode).toBe('GUARDIAN_ACCOUNT_PAUSED');
+      expect(typeof e.userMessage).toBe('string');
+      expect(e.userMessage).not.toContain('compliance review'); // sanitized
+      expect(e.meta?.retryable).toBe(false);
+      expect(e.meta?.pausedAt).toBe('2026-05-20T10:00:00Z');
+      expect(e.meta?.pausedReason).toBe('compliance review');
+
+      const parsed = JSON.parse(e.body);
+      // Legacy fields gone; not a domain object.
+      expect(parsed.success).toBeUndefined();
+      expect(parsed.error).toBeUndefined();
       expect(parsed.delta).toBeUndefined();
     });
 
     it('surfaces 401 AUTHENTICATION_FAILED with a parseable error envelope', async () => {
       client.setSigner(mockSigner);
       const envelope = {
-        success: false,
         code: 'authentication_failed',
-        error: 'Invalid signature',
+        message: 'Your session has expired. Please sign in again.',
+        meta: { retryable: false },
       };
-      mockFetch.mockResolvedValueOnce({
+      // `authentication_failed` triggers the replay-retry path (the specific
+      // "Replay attack" detail is sanitized off the wire in feature 009, so we
+      // retry on the auth code). Use a persistent mock so the retries resolve
+      // and the final attempt throws the typed error.
+      mockFetch.mockResolvedValue({
         ok: false,
         status: 401,
         statusText: 'Unauthorized',
@@ -807,10 +1084,12 @@ describe('GuardianHttpError', () => {
         .catch((e) => e as GuardianHttpError);
 
       expect(error).toBeInstanceOf(GuardianHttpError);
-      expect((error as GuardianHttpError).status).toBe(401);
-      const parsed = JSON.parse((error as GuardianHttpError).body);
-      expect(parsed.success).toBe(false);
-      expect(parsed.code).toBe('authentication_failed');
+      const e = error as GuardianHttpError;
+      expect(e.status).toBe(401);
+      expect(e.code).toBe('authentication_failed');
+      expect(typeof e.userMessage).toBe('string');
+      const parsed = JSON.parse(e.body);
+      expect(parsed.success).toBeUndefined();
       expect(parsed.delta).toBeUndefined();
     });
   });

package/src/http.ts

@@ -1,4 +1,10 @@
+import {
+  type GuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from './error-codes.js';
 import type {
+  AbandonCandidateResponse,
+  AbandonStatus,
   ConfigureRequest,
   ConfigureResponse,
   DeltaObject,
@@ -12,9 +18,12 @@ import type {
   SignatureScheme,
   Signer,
   StateObject,
+  StatusResponse,
 } from './types.js';
 import { RequestAuthPayload } from './auth-request.js';
 import type {
+  ServerAbandonCandidateRequest,
+  ServerAbandonCandidateResponse,
   ServerDeltaObject,
   ServerDeltaProposalResponse,
   ServerLookupResponse,
@@ -23,6 +32,7 @@ import type {
   ServerStateObject,
   ServerConfigureResponse,
   ServerPushDeltaResponse,
+  ServerStatusResponse,
 } from './server-types.js';
 import {
   fromServerConfigureResponse,
@@ -36,16 +46,125 @@ import {
 } from './conversion.js';
 
 /**
- * Error thrown by the GUARDIAN HTTP client.
+ * Structured machine-readable side-data on a GUARDIAN error
+ * (feature `009-human-readable-errors`). `retryable` is always present.
+ */
+export interface GuardianErrorMeta {
+  retryable: boolean;
+  retryAfterSecs?: number;
+  missingPermissions?: string[];
+  pausedAt?: string;
+  pausedReason?: string | null;
+  releasedAt?: string;
+}
+
+interface ParsedGuardianError {
+  /** Typed code, or `null` when the wire code is outside the known vocabulary. */
+  code: GuardianErrorCode | null;
+  /** Verbatim wire code, kept even when it does not narrow to the union. */
+  rawCode: string;
+  message: string;
+  meta: GuardianErrorMeta;
+}
+
+/**
+ * Parse a GUARDIAN error body `{ code, message, meta }` (feature 009),
+ * mapping the server's snake_case `meta` fields to camelCase. Returns
+ * `undefined` for non-JSON or non-conforming bodies — including a missing
+ * `meta` or a non-boolean `meta.retryable`, which the contract requires;
+ * treating those as conforming would silently misclassify retryability for
+ * bodies from older servers or intermediary proxies.
+ */
+function parseGuardianErrorBody(body: string): ParsedGuardianError | undefined {
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+  if (typeof json !== 'object' || json === null) return undefined;
+  const obj = json as Record<string, unknown>;
+  if (typeof obj.code !== 'string' || typeof obj.message !== 'string') return undefined;
+
+  if (typeof obj.meta !== 'object' || obj.meta === null || Array.isArray(obj.meta)) {
+    return undefined;
+  }
+  const rawMeta = obj.meta as Record<string, unknown>;
+  if (typeof rawMeta.retryable !== 'boolean') return undefined;
+  const code = normalizeGuardianErrorCode(obj.code);
+  const meta: GuardianErrorMeta = { retryable: rawMeta.retryable };
+  if (
+    typeof rawMeta.retry_after_secs === 'number' &&
+    Number.isInteger(rawMeta.retry_after_secs) &&
+    rawMeta.retry_after_secs >= 0
+  ) {
+    meta.retryAfterSecs = rawMeta.retry_after_secs;
+  }
+  if (Array.isArray(rawMeta.missing_permissions)) {
+    meta.missingPermissions = rawMeta.missing_permissions.filter(
+      (x): x is string => typeof x === 'string'
+    );
+  }
+  if (typeof rawMeta.paused_at === 'string') meta.pausedAt = rawMeta.paused_at;
+  if (typeof rawMeta.released_at === 'string') meta.releasedAt = rawMeta.released_at;
+  if (typeof rawMeta.paused_reason === 'string' || rawMeta.paused_reason === null) {
+    meta.pausedReason = rawMeta.paused_reason as string | null;
+  }
+  return { code, rawCode: obj.code, message: obj.message, meta };
+}
+
+/**
+ * Error thrown by the GUARDIAN HTTP client. Parses the `{ code, message, meta }`
+ * error body (feature 009): branch on {@link code}, display {@link userMessage}.
  */
 export class GuardianHttpError extends Error {
+  /**
+   * Typed, compiler-checked Guardian error code (issue #318), normalized to
+   * snake_case (e.g. `account_paused`, `account_released`,
+   * `commitment_mismatch`). `null` when the body is not a conforming JSON
+   * envelope OR the server emitted a code outside this client's known
+   * vocabulary — in the latter case {@link rawCode} still carries the
+   * verbatim wire string. Branch on this rather than on `body` text or the
+   * HTTP status alone; comparing against a non-member literal is a type
+   * error, so typos are caught at compile time.
+   */
+  public readonly code: GuardianErrorCode | null;
+  /**
+   * Verbatim wire code as the server sent it (e.g.
+   * `GUARDIAN_ACCOUNT_PAUSED`), including codes a newer server may emit
+   * that this client does not know. `null` only when the body carried no
+   * conforming envelope. For logging/telemetry; branch on {@link code}.
+   */
+  public readonly rawCode: string | null;
+  /** Short, user-safe message — safe to display verbatim in a wallet UI. */
+  readonly userMessage?: string;
+  /** Structured side-data (`retryable`, `retryAfterSecs`, …). */
+  readonly meta?: GuardianErrorMeta;
+  /**
+   * RFC 3339 UTC timestamp at which the guardian released the account
+   * after it switched to a different guardian. Convenience accessor for
+   * `meta.releasedAt`; present only when `code === 'account_released'`
+   * (wire form `GUARDIAN_ACCOUNT_RELEASED`, HTTP 409); the account is
+   * terminal on this server until re-onboarded via `configure`.
+   */
+  public readonly releasedAt: string | null;
+
   constructor(
     public readonly status: number,
     public readonly statusText: string,
     public readonly body: string
   ) {
-    super(`GUARDIAN HTTP error ${status}: ${statusText} - ${body}`);
+    // Only the parsed, user-safe message is folded into Error.message; the
+    // raw body (which may carry backend/proxy internals) stays on the `body`
+    // field for diagnostics only.
+    const parsed = parseGuardianErrorBody(body);
+    super(`GUARDIAN HTTP error ${status}: ${statusText}${parsed ? ` - ${parsed.message}` : ''}`);
     this.name = 'GuardianHttpError';
+    this.code = parsed?.code ?? null;
+    this.rawCode = parsed?.rawCode ?? null;
+    this.userMessage = parsed?.message;
+    this.meta = parsed?.meta;
+    this.releasedAt = parsed?.meta.releasedAt ?? null;
   }
 }
 
@@ -87,6 +206,19 @@ export class GuardianHttpClient {
     };
   }
 
+  async getStatus(): Promise<StatusResponse> {
+    const response = await this.fetch('/status', { method: 'GET' });
+    const data = (await response.json()) as ServerStatusResponse;
+    return {
+      status: data.status,
+      version: data.version,
+      gitCommit: data.git_commit,
+      environment: data.environment,
+      startedAt: data.started_at,
+      uptimeSeconds: data.uptime_seconds,
+    };
+  }
+
   async configure(request: ConfigureRequest): Promise<ConfigureResponse> {
     const serverRequest = toServerConfigureRequest(request);
     const response = await this.fetchAuthenticated('/configure', {
@@ -157,6 +289,65 @@ export class GuardianHttpClient {
     };
   }
 
+  /**
+   * Request abandonment of a pending canonicalization candidate whose
+   * transaction will never land on-chain (issue #319).
+   *
+   * Records an abandon *intent* (`202 Accepted`): the delta stays a
+   * candidate — the account stays locked — until the guardian's worker
+   * confirms over the abandon quarantine that the transaction did not
+   * land, then discards the delta as `client_abandoned` and releases the
+   * account (typically well under a minute). Poll {@link abandonStatus}
+   * for the resolution. Refused with `GUARDIAN_CANDIDATE_LANDED` (409)
+   * when the transaction actually landed. Retries are idempotent and
+   * preserve the original request timestamp.
+   */
+  async abandonCandidate(accountId: string, nonce: number): Promise<AbandonCandidateResponse> {
+    const serverRequest: ServerAbandonCandidateRequest = { account_id: accountId, nonce };
+    const response = await this.fetchAuthenticated('/delta/candidate/abandon', {
+      method: 'POST',
+      body: JSON.stringify(serverRequest),
+    }, accountId, serverRequest);
+    const server = (await response.json()) as ServerAbandonCandidateResponse;
+    return {
+      accountId: server.account_id,
+      nonce: server.nonce,
+      state: server.state,
+      abandonRequestedAt: server.abandon_requested_at,
+    };
+  }
+
+  /**
+   * Poll the resolution of an abandon request made with
+   * {@link abandonCandidate}: `'waiting'` while the quarantine runs,
+   * `'landed'` if the transaction landed after all (the delta
+   * canonicalized), `'abandoned'` once the delta is discarded as
+   * client-abandoned and the account released, `'unexpected'` for any
+   * state no abandon flow produces (including a missing delta).
+   */
+  async abandonStatus(accountId: string, nonce: number): Promise<AbandonStatus> {
+    let delta: DeltaObject;
+    try {
+      delta = await this.getDelta(accountId, nonce);
+    } catch (e) {
+      if (e instanceof GuardianHttpError && e.code === 'delta_not_found') {
+        return 'unexpected';
+      }
+      throw e;
+    }
+    switch (delta.status.status) {
+      case 'candidate':
+        return 'waiting';
+      case 'canonical':
+        return 'landed';
+      case 'discarded':
+        return delta.status.reason === 'client_abandoned' ? 'abandoned' : 'unexpected';
+      default:
+        return 'unexpected';
+    }
+  }
+
+
   async signDeltaProposal(request: SignProposalRequest): Promise<DeltaObject> {
     const serverRequest = toServerSignProposalRequest(request);
     const response = await this.fetchAuthenticated('/delta/proposal', {
@@ -303,7 +494,16 @@ export class GuardianHttpClient {
         },
       });
     } catch (err) {
-      if (retries > 0 && err instanceof GuardianHttpError && err.body.includes('Replay attack')) {
+      // Replay rejections (stale timestamp) are transient: retry once with a
+      // fresh timestamp. The specific "Replay attack" detail is now sanitized
+      // off the wire (feature 009), so branch on the stable auth code instead.
+      // Retrying a genuine auth failure is harmless — one extra attempt that
+      // also fails — and only happens when a retry budget remains.
+      if (
+        retries > 0 &&
+        err instanceof GuardianHttpError &&
+        err.code === 'authentication_failed'
+      ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
         return this.fetchAuthenticated(path, init, accountId, requestPayload, retries - 1);
       }

package/src/index.ts

@@ -1,7 +1,16 @@
 export { GuardianHttpClient, GuardianHttpError } from './http.js';
+export type { GuardianErrorMeta } from './http.js';
+export {
+  GUARDIAN_ERROR_CODES,
+  isGuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from './error-codes.js';
+export type { GuardianErrorCode } from './error-codes.js';
 export { RequestAuthPayload } from './auth-request.js';
 
 export type {
+  AbandonCandidateResponse,
+  AbandonStatus,
   Signer,
   FalconSignature,
   EcdsaSignature,
@@ -18,6 +27,7 @@ export type {
   ConfigureRequest,
   ConfigureResponse,
   PubkeyResponse,
+  StatusResponse,
   DeltaProposalRequest,
   DeltaProposalResponse,
   ProposalsResponse,