@redacto.io/consent-sdk-react 5.2.0 → 5.3.0

package/src/shared/api-errors.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared API error handling for the consent-sdk-react package.
+ *
+ * The backend (consent-server) owns the user-facing copy. Each error
+ * response carries:
+ *   - `message`: user-safe text the SDK displays verbatim
+ *   - `error_code`: stable identifier for programmatic branching
+ *
+ * The SDK never re-translates a code into a message. To change wording,
+ * update the server titles registry -- no SDK release required.
+ */
+
+export type ApiErrorCode =
+  | "INVALID_TOKEN"
+  | "TOKEN_TENANT_MISMATCH"
+  | "UNAUTHORIZED"
+  | "USER_NOT_FOUND"
+  | "USER_EMAIL_MISMATCH"
+  | "USER_MOBILE_MISMATCH"
+  | "USER_CONTACT_MISMATCH"
+  | "NO_IDENTIFIER_PROVIDED"
+  | "INVALID_PAYLOAD"
+  | "VALIDATION_ERROR"
+  | "NOTICE_NOT_FOUND"
+  | "NOTICE_CONFIGURATION_NOT_FOUND"
+  | "NOTICE_STILL_IN_DRAFT"
+  | "CONSENT_ALREADY_PROVIDED"
+  | "PURPOSE_NOT_FOUND"
+  | "INVALID_PURPOSE"
+  | "INVALID_DATA_ELEMENTS"
+  | "MISSING_PURPOSE"
+  | "MISSING_DATA_ELEMENTS"
+  | "REQUIRED_DATA_ELEMENT_NOT_ENABLED"
+  | "AUDIO_NOT_FOUND"
+  | "INVALID_LANGUAGE"
+  | "VERIFICATION_FAILED"
+  | "VERIFICATION_EXPIRED"
+  | "GUARDIAN_INFO_NOT_FOUND"
+  | "GUARDIAN_SESSION_INVALID"
+  | "SESSION_EXPIRED"
+  | "INTERNAL_ERROR";
+
+interface ApiErrorDetail {
+  message?: string;
+  error_code?: string | null;
+  // Ninja's auth-pipeline auto-401 returns `{detail: {detail: "Unauthorized"}}`
+  // -- the inner `detail` is a string. Captured here so the parser can use
+  // it as a last-resort message extraction.
+  detail?: string;
+}
+
+interface ApiErrorBody {
+  message?: string;
+  error_code?: string | null;
+  // `detail` may arrive as:
+  //   { message: "...", error_code: "..." }    -- our MessageResponse via Ninja
+  //   { detail: "..." }                         -- Ninja auto-401
+  //   "..."                                     -- direct string from some endpoints
+  //   [...]                                     -- Ninja auto-422 Pydantic errors
+  detail?: ApiErrorDetail | string | unknown[];
+}
+
+// `ApiErrorCode | (string & {})` keeps literal autocomplete on `code` while
+// still permitting unknown strings from forward-compatible server versions.
+// A bare `ApiErrorCode | string` would widen to `string` and lose the
+// literal suggestions.
+export type ApiErrorCodeLike = ApiErrorCode | (string & {});
+
+export class ApiError extends Error {
+  readonly status: number;
+  readonly code?: ApiErrorCodeLike;
+
+  constructor(opts: {
+    status: number;
+    code?: ApiErrorCodeLike;
+    message: string;
+  }) {
+    super(opts.message);
+    this.name = "ApiError";
+    this.status = opts.status;
+    this.code = opts.code;
+  }
+}
+
+// Tier-3 fallbacks for failure modes where the server did not produce
+// a parseable body with `message`. Common case: Ninja's auth pipeline
+// rejects a request before reaching our handler, returning
+// `{detail: {detail: "Unauthorized"}}` with no message field. The
+// fallback is a static, user-safe hint -- never an override of a
+// server-supplied message.
+function statusFallback(status: number): string | undefined {
+  if (status === 401) {
+    return "Your session has expired. Please request a new access link.";
+  }
+  if (status === 403) {
+    return "You do not have access to this resource.";
+  }
+  if (status >= 500) {
+    return "Something went wrong on our end. Please try again later.";
+  }
+  return undefined;
+}
+
+/**
+ * Build an ApiError from a non-OK fetch Response.
+ *
+ * Order of preference for the user-facing message:
+ *   1. `message` field from the backend response body (preferred -- the
+ *      SDK-consumed endpoints always populate this with user-safe copy).
+ *   2. Status-based fallback (only when the server omitted a message,
+ *      e.g. Ninja's auto-401 for an expired JWT).
+ *   3. The caller-supplied fallback (used when the body is missing or
+ *      unparseable -- network error, non-JSON proxy page).
+ *
+ * The `code` field is exposed as-is for programmatic branching. Consumers
+ * that want compile-time safety should narrow against `ApiErrorCode`.
+ */
+function extractFromDetail(
+  detail: ApiErrorBody["detail"]
+): { message?: string; code?: string | null } {
+  // String detail (e.g. some endpoints return `{detail: "..."}` directly).
+  if (typeof detail === "string") {
+    return { message: detail };
+  }
+  // Array detail (Ninja's auto-422 Pydantic validation errors): no usable
+  // single message; let the caller fall back to status/generic copy.
+  if (Array.isArray(detail)) {
+    return {};
+  }
+  // Object detail covers both shapes:
+  //   our MessageResponse: { message, error_code }
+  //   Ninja auto-401:      { detail: "Unauthorized" }
+  if (detail && typeof detail === "object") {
+    const obj = detail as ApiErrorDetail;
+    return { message: obj.message ?? obj.detail, code: obj.error_code };
+  }
+  return {};
+}
+
+export async function parseApiError(
+  response: Response,
+  fallbackMessage: string
+): Promise<ApiError> {
+  let body: ApiErrorBody | undefined;
+  let parsedBody = false;
+  try {
+    body = (await response.json()) as ApiErrorBody;
+    parsedBody = true;
+  } catch {
+    body = undefined;
+  }
+
+  const fromDetail = extractFromDetail(body?.detail);
+  const serverMessage = body?.message ?? fromDetail.message;
+  // Status fallback only applies when the body parsed but had no message
+  // (e.g. Ninja auto-401's `{detail: {detail: "Unauthorized"}}`). When the
+  // body is unparseable (proxy HTML 502, empty body, network jank) the
+  // caller's per-endpoint fallback is the more accurate hint -- a 401 from
+  // a misbehaving proxy is not necessarily an expired session.
+  const message =
+    serverMessage ??
+    (parsedBody ? statusFallback(response.status) : undefined) ??
+    fallbackMessage;
+  const code = body?.error_code ?? fromDetail.code ?? undefined;
+
+  return new ApiError({
+    status: response.status,
+    code,
+    message,
+  });
+}