Error handling

import { AbadgeApiError } from "@abadge/sdk";

class AbadgeApiError extends Error {
  readonly statusCode: number;                        // HTTP status code
  readonly code: ErrorCode | string;                  // e.g. "PERMISSION_DENIED"
  readonly message: string;                           // Human-readable description (inherited from Error)
  readonly hint?: string;                             // Actionable next step, if provided
  readonly meta?: Readonly<Record<string, unknown>>;  // Structured context for clients
  readonly issues?: ReadonlyArray<                     // VALIDATION_ERROR only
    { path: (string | number)[]; message: string }
  >;

  static fromResponse(res: Response, fallback: string): Promise<AbadgeApiError>;
  static fromUnknown(error: unknown, fallback: string): AbadgeApiError;
}

import { AbadgeAgentClient, AbadgeApiError } from "@abadge/sdk";

try {
  const result = await agent.access.read(itemId, { field: "password" });
} catch (err) {
  if (err instanceof AbadgeApiError) {
    console.error(`${err.code}: ${err.message}`);
    console.error(`Hint: ${err.hint}`);
  }
  throw err;
}

switch (err.code) {
  case "PERMISSION_DENIED":
    // No matching permission for (agent, item, capability)
    break;
  case "PERMISSION_EXPIRED":
    // Permission existed but has passed expiresAt
    break;
  case "AGENT_REVOKED":
    // Agent has been revoked; authentication failed
    break;
  case "AGENT_SESSION_NOT_FOUND":
    // abs_... token not found or expired; reconnect
    break;
  case "FIELD_NOT_FOUND":
    // Named field not present; err.meta.availableFields lists valid names
    break;
  case "MULTI_FIELD_ITEM":
    // Item has multiple fields; pass field
    break;
  case "STALE_VERSION":
    // Optimistic-concurrency conflict; re-fetch and retry
    break;
  case "RATE_LIMITED":
    // Too many requests; back off
    break;
  case "SESSION_REFRESH_FAILED":
    // SDK background refresh exhausted retries; disconnect/reconnect
    break;
}

try {
  await agent.access.read(itemId);
} catch (err) {
  if (err instanceof AbadgeApiError && err.code === "MULTI_FIELD_ITEM") {
    const fields = err.meta?.availableFields as string[];
    return await agent.access.read(itemId, { field: fields[0] });
  }
  throw err;
}

try {
  await agent.access.read(itemId);
} catch (err) {
  if (err instanceof AbadgeApiError && err.code === "SESSION_REFRESH_FAILED") {
    agent.disconnect();
    await agent.connect();
    return await agent.access.read(itemId);
  }
  throw err;
}

catch (err) {
  if (err instanceof AbadgeApiError && err.code === "VALIDATION_ERROR") {
    for (const issue of err.issues ?? []) {
      console.error(`${issue.path.join(".")}: ${issue.message}`);
    }
  }
}

import { SecretValue } from "@abadge/sdk";

const result = await agent.access.read(itemId);
if (result.storageMode !== "server_managed") throw new Error("Expected server_managed");

const secret = new SecretValue(result.payload.fields.password as string);
console.log(secret);          // SecretValue([REDACTED])
const plaintext = secret.expose();