@redacto.io/consent-sdk-react 10.0.0-beta.9 → 10.0.0

package/src/RedactoPrivacyCenter/api/client.ts

@@ -1,1003 +0,0 @@
-import { apiFetch, ApiError } from "./fetcher";
-import type { ApiFetchOptions, ApiResponse } from "./fetcher";
-import {
-  isSandboxMode,
-  sandboxAuthHeaders,
-  sandboxContact,
-  sandboxQueryIdentity,
-} from "../lib/sandbox";
-import type {
-  CaseMessage,
-  IdentityListResponse,
-  MessageDocument,
-  NotificationActionResponse,
-  NotificationListResponse,
-  NotificationQueryParams,
-  NotificationSummary,
-  SelectPrincipalResponse,
-  UnreadCountResponse,
-  UploadDocumentResponse,
-} from "../lib/types";
-
-/**
- * Base request parameters for consent service calls
- */
-export type BaseRequest = {
-  organisationUuid: string;
-  workspaceUuid: string;
-  authToken: string;
-};
-
-/**
- * Consent service client factory.
- * Creates a client instance with a specific base URL.
- * @param baseUrl - Consent server base URL (Python service, e.g. http://host/consent)
- * @param ledgerBaseUrl - Go ledger base URL (e.g. http://host:8090/consent-ledger).
- *   Used for user-consents reads/writes served from the ledger's `/public/...` paths.
- *   When omitted, those calls fall back to the legacy Python
- *   `/dsar/privacy-center` endpoints and payloads (pre-ledger behavior), so
- *   integrations without a deployed ledger keep working.
- */
-export function createConsentClient(baseUrl: string, ledgerBaseUrl?: string) {
-  const ledgerConfigured = Boolean(ledgerBaseUrl);
-  // Sandbox mode never routes to the Go ledger (it has no sandbox / test::
-  // support). A sandbox token forces the legacy consent-server path regardless
-  // of ledgerBaseUrl, so isolation can't be bypassed by also configuring a ledger.
-  const useLedger = () => ledgerConfigured && !isSandboxMode();
-  const ledgerBase = (ledgerBaseUrl ?? "").replace(/\/$/, "");
-  /**
-   * Privacy Center API fetch wrapper that uses Authorization: Bearer header.
-   * Privacy center endpoints require JWT tokens in Authorization header, not X-Auth-Token.
-   */
-  async function privacyCenterApiFetch<T>(
-    url: string,
-    options: ApiFetchOptions & { authToken?: string }
-  ): Promise<T> {
-    const { authToken, getAuthToken, headers = {}, ...fetchOptions } = options;
-
-    // Build headers using Headers object
-    const requestHeaders = new Headers();
-
-    // Set default headers (skip Content-Type for FormData)
-    const isFormData = fetchOptions.body instanceof FormData;
-    if (!isFormData) {
-      requestHeaders.set("Content-Type", "application/json");
-    }
-    requestHeaders.set("Accept", "application/json");
-
-    // Add custom headers from options
-    if (headers && typeof headers === "object") {
-      if (headers instanceof Headers) {
-        headers.forEach((value, key) => {
-          requestHeaders.set(key, value);
-        });
-      } else {
-        Object.entries(headers as Record<string, string>).forEach(
-          ([key, value]) => {
-            if (value) {
-              requestHeaders.set(key, value);
-            }
-          }
-        );
-      }
-    }
-
-    // Sandbox PoC: send only the X-Consent-Token credential (no JWT bearer). Set
-    // last so it wins over any caller-supplied Authorization header. The acting
-    // identity travels in the request payload -- query params on reads, the body
-    // on writes -- never a header.
-    const sandboxHeaders = sandboxAuthHeaders();
-    if (sandboxHeaders) {
-      Object.entries(sandboxHeaders).forEach(([key, value]) => {
-        requestHeaders.set(key, value);
-      });
-    } else {
-      // Add Authorization Bearer token for privacy center APIs
-      const token = authToken || (getAuthToken ? await getAuthToken() : null);
-      if (token) {
-        const trimmedToken = token.trim();
-        // Format token with Bearer prefix if not already present
-        const bearerToken = trimmedToken.startsWith('Bearer ')
-          ? trimmedToken
-          : `Bearer ${trimmedToken}`;
-        requestHeaders.set("Authorization", bearerToken);
-      }
-    }
-
-    // Build fetch options
-    const fetchOptionsFinal: RequestInit = {
-      ...fetchOptions,
-      headers: requestHeaders,
-    };
-
-    try {
-      const response = await fetch(url, fetchOptionsFinal);
-
-      // Handle non-OK responses
-      if (!response.ok) {
-        let errorMessage = `Request failed with status ${response.status}`;
-        let errorCode: string | undefined;
-        let errorDetail: unknown;
-
-        try {
-          const errorData = (await response.json()) as {
-            detail?: unknown;
-            message?: string;
-            code?: string;
-          } | null;
-          if (errorData) {
-            errorDetail = errorData.detail;
-            if (typeof errorData.code === "string") {
-              errorCode = errorData.code;
-            }
-            if ("detail" in errorData && errorData.detail) {
-              errorMessage =
-                typeof errorData.detail === "string"
-                  ? errorData.detail
-                  : JSON.stringify(errorData.detail, null, 2);
-            } else if ("message" in errorData && errorData.message) {
-              errorMessage = errorData.message;
-            } else if ("code" in errorData && errorData.code) {
-              // e.g. { code: "empty_file" } or { code: "document_already_exists" }
-              errorMessage = errorData.code;
-            }
-          }
-        } catch {
-          // If response is not JSON, try to get text
-          try {
-            const errorText = await response.text();
-            if (errorText) {
-              errorMessage = errorText;
-            }
-          } catch {
-            // Ignore parsing errors
-          }
-        }
-
-        // Throw a typed error carrying the status/code. The `[status]` prefix is
-        // kept in the message for back-compat with callers that branch on it
-        // (e.g. getFormData checks for "404").
-        throw new ApiError(`[${response.status}] ${errorMessage}`, {
-          status: response.status,
-          code: errorCode,
-          detail: errorDetail,
-        });
-      }
-
-      // Parse JSON response
-      const contentType = response.headers.get("Content-Type") || "";
-      if (!contentType.includes("application/json")) {
-        const textResponse = await response.text();
-        throw new Error(
-          `Expected JSON response, got ${contentType}: ${textResponse}`
-        );
-      }
-
-      const data = (await response.json()) as ApiResponse<T> | T;
-
-      // Handle wrapped API responses (code, status, detail format)
-      if (
-        typeof data === "object" &&
-        data !== null &&
-        "code" in data &&
-        "status" in data &&
-        "detail" in data
-      ) {
-        const apiResponse = data as ApiResponse<T>;
-        return apiResponse.detail as T;
-      }
-
-      return data as T;
-    } catch (error) {
-      if (error instanceof Error) {
-        throw error;
-      }
-      throw new Error(`Unknown error occurred: ${String(error)}`);
-    }
-  }
-
-  function privacyCenterUrl(baseRequest: BaseRequest, path: string): string {
-    return `${baseUrl}/organisations/${baseRequest.organisationUuid}/workspaces/${baseRequest.workspaceUuid}/dsar/privacy-center${path}`;
-  }
-
-  function ledgerUrl(baseRequest: BaseRequest, path: string): string {
-    if (!useLedger()) {
-      throw new Error("ledgerUrl called without a configured ledgerBaseUrl");
-    }
-    return `${ledgerBase}/public/organisations/${baseRequest.organisationUuid}/workspaces/${baseRequest.workspaceUuid}${path}`;
-  }
-
-  function caseUrl(baseRequest: BaseRequest, caseUuid: string, path = ''): string {
-    return privacyCenterUrl(baseRequest, `/cases/${caseUuid}${path}`);
-  }
-
-  function notificationUrl(baseRequest: BaseRequest, path = ''): string {
-    const identitySuffix = sandboxIdentitySuffix();
-    if (!identitySuffix) {
-      return privacyCenterUrl(baseRequest, `/notifications${path}`);
-    }
-    const separator = path.includes('?') ? `&${identitySuffix.slice(1)}` : identitySuffix;
-    return privacyCenterUrl(baseRequest, `/notifications${path}${separator}`);
-  }
-
-  function resolveAuthToken(authToken: string | undefined, baseRequest: BaseRequest): string {
-    return authToken || baseRequest.authToken;
-  }
-
-  /**
-   * Append the sandbox acting identity (`primary_email` / `primary_mobile`) to a
-   * query-param bag when sandbox mode is active; a no-op otherwise. The server
-   * resolves the acting test identity from these query params on reads (there is
-   * no subject header). The credential is the X-Consent-Token header set in
-   * privacyCenterApiFetch.
-   */
-  function appendSandboxIdentity(queryParams: URLSearchParams): void {
-    const identity = sandboxQueryIdentity();
-    if (identity) {
-      Object.entries(identity).forEach(([key, value]) => {
-        queryParams.append(key, value);
-      });
-    }
-  }
-
-  /**
-   * The sandbox acting-identity query suffix (`?primary_email=...` /
-   * `?primary_mobile=...`) for endpoints that build a bare URL with no other
-   * query params (the case-communication reads/POSTs). Empty string outside
-   * sandbox mode, so the JWT path is unchanged.
-   */
-  function sandboxIdentitySuffix(): string {
-    const queryParams = new URLSearchParams();
-    appendSandboxIdentity(queryParams);
-    const queryString = queryParams.toString();
-    return queryString ? `?${queryString}` : "";
-  }
-
-  return {
-    /**
-     * Get form data (privacy center)
-     */
-    async getFormData(
-      baseRequest: BaseRequest,
-      contact: string,
-      authToken?: string,
-      options?: ApiFetchOptions & { useSessionAuth?: boolean },
-      language?: string
-    ): Promise<unknown> {
-      const queryParams = new URLSearchParams();
-      if (language) queryParams.append("language", language);
-      const queryString = queryParams.toString();
-      const url = privacyCenterUrl(baseRequest, `/form/data${queryString ? `?${queryString}` : ""}`);
-      const { useSessionAuth = false, getAuthToken, ...fetchOptions } = options || {};
-
-      // Case management uses session-based auth (X-Auth-Token)
-      // Privacy center uses JWT Bearer tokens (Authorization: Bearer)
-      if (useSessionAuth) {
-        return apiFetch(url, {
-          ...fetchOptions,
-          method: "POST",
-          body: JSON.stringify({ contact }),
-          getAuthToken,
-        });
-      }
-
-      // Privacy center: use JWT Bearer token
-      return privacyCenterApiFetch(url, {
-        ...fetchOptions,
-        method: "POST",
-        body: JSON.stringify({ contact }),
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Create case request (privacy center or case management)
-     */
-    async createCaseRequest(
-      baseRequest: BaseRequest,
-      payload: unknown,
-      authToken?: string,
-      options?: ApiFetchOptions & { useSessionAuth?: boolean }
-    ): Promise<unknown> {
-      const url = privacyCenterUrl(baseRequest, '/case');
-      const { useSessionAuth = false, getAuthToken, ...fetchOptions } = options || {};
-
-      // Sandbox mode: the acting test identity is the single `contact` field
-      // (the server has no subject header; it namespaces this identity `test::`).
-      // Merge it into the body only when sandbox mode is active and the payload
-      // is a plain object; the JWT path is left byte-for-byte unchanged.
-      const contact = sandboxContact();
-      const requestPayload =
-        contact && payload && typeof payload === "object"
-          ? { ...(payload as Record<string, unknown>), contact }
-          : payload;
-
-      // Case management uses session-based auth (X-Auth-Token)
-      // Privacy center uses JWT Bearer tokens (Authorization: Bearer)
-      if (useSessionAuth) {
-        return apiFetch(url, {
-          ...fetchOptions,
-          method: "POST",
-          body: JSON.stringify(requestPayload),
-          getAuthToken,
-        });
-      }
-
-      // Privacy center: use JWT Bearer token
-      return privacyCenterApiFetch(url, {
-        ...fetchOptions,
-        method: "POST",
-        body: JSON.stringify(requestPayload),
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Create OTP (public)
-     */
-    async createOtp(
-      organisationId: string,
-      workspaceId: string,
-      email: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const url = `${baseUrl}/public/organisations/${organisationId}/workspaces/${workspaceId}/otp/create`;
-      return apiFetch(url, {
-        ...options,
-        method: "POST",
-        body: JSON.stringify({ to: email, channel: "email" }),
-      });
-    },
-
-    /**
-     * Verify OTP (public)
-     */
-    async verifyOtp(
-      organisationId: string,
-      workspaceId: string,
-      otpId: string,
-      otp: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const url = `${baseUrl}/public/organisations/${organisationId}/workspaces/${workspaceId}/otp/verify`;
-      return apiFetch(url, {
-        ...options,
-        method: "POST",
-        body: JSON.stringify({ uuid: otpId, otp }),
-      });
-    },
-
-    /**
-     * Exchange one-time token for JWT tokens (public)
-     */
-    async exchangeToken(
-      token: string,
-    ): Promise<unknown> {
-      const url = `${baseUrl}/public/tokens/token-exchange?token=${encodeURIComponent(token)}`;
-      const response = await fetch(url, {
-        method: "GET",
-        headers: { "Accept": "application/json" },
-      });
-
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => null) as { detail?: string; message?: string } | null;
-        throw new Error(
-          errorData?.detail || errorData?.message || `Token exchange failed with status ${response.status}`
-        );
-      }
-
-      const data = await response.json() as { code?: number; status?: string; detail?: unknown };
-      if (data && typeof data === "object" && "code" in data && "status" in data && "detail" in data) {
-        return data.detail;
-      }
-      return data;
-    },
-
-    /**
-     * Refresh OTP token (public)
-     */
-    async refreshOtpToken(
-      organisationId: string,
-      workspaceId: string,
-      refreshToken: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const url = `${baseUrl}/public/organisations/${organisationId}/workspaces/${workspaceId}/otp/refresh`;
-      return apiFetch(url, {
-        ...options,
-        method: "POST",
-        body: JSON.stringify({ refresh_token: refreshToken }),
-      });
-    },
-
-    /**
-     * Get products
-     */
-    async getProducts(
-      baseRequest: BaseRequest,
-      skip: number = 0,
-      limit: number = 10,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const url = `${baseUrl}/organisations/${baseRequest.organisationUuid}/workspaces/${baseRequest.workspaceUuid}/notice-management/products/?skip=${skip}&limit=${limit}`;
-      return apiFetch<unknown>(url, {
-        ...options,
-        getAuthToken: async () => baseRequest.authToken,
-      });
-    },
-
-    /**
-     * Get user consents (privacy center)
-     */
-    async getUserConsents(
-      baseRequest: BaseRequest,
-      params: {
-        offset?: number;
-        limit?: number;
-        nominated_offset?: number;
-        nominated_limit?: number;
-        status?: string;
-        product_uuid?: string;
-        search?: string;
-        language?: string;
-      },
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const queryParams = new URLSearchParams();
-      if (params.offset !== undefined) queryParams.append("offset", params.offset.toString());
-      if (params.limit !== undefined) queryParams.append("limit", params.limit.toString());
-      if (params.nominated_offset !== undefined) queryParams.append("nominated_offset", params.nominated_offset.toString());
-      if (params.nominated_limit !== undefined) queryParams.append("nominated_limit", params.nominated_limit.toString());
-      if (params.search) queryParams.append("search", params.search);
-      if (params.status) queryParams.append("status", params.status);
-      if (params.product_uuid) queryParams.append("product_uuid", params.product_uuid);
-      if (params.language) queryParams.append("language", params.language);
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      appendSandboxIdentity(queryParams);
-      const queryString = queryParams.toString();
-      const suffix = `/user-consents${queryString ? `?${queryString}` : ""}`;
-      const url = useLedger()
-        ? ledgerUrl(baseRequest, suffix)
-        : privacyCenterUrl(baseRequest, suffix);
-      return privacyCenterApiFetch(url, {
-        ...options,
-        method: "GET",
-        cache: "no-store",
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Get purposes for a single product card (privacy center) — sister endpoint
-     * for lazy-loading purposes when a card returns has_more_purposes: true.
-     */
-    async getGroupPurposes(
-      baseRequest: BaseRequest,
-      productUuid: string,
-      params: {
-        offset?: number;
-        limit?: number;
-        status?: string;
-        search?: string;
-        language?: string;
-        nominator_uuid?: string;
-      },
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const queryParams = new URLSearchParams();
-      if (params.offset !== undefined) queryParams.append("offset", params.offset.toString());
-      if (params.limit !== undefined) queryParams.append("limit", params.limit.toString());
-      if (params.status) queryParams.append("status", params.status);
-      if (params.search) queryParams.append("search", params.search);
-      if (params.language) queryParams.append("language", params.language);
-      if (params.nominator_uuid) queryParams.append("nominator_uuid", params.nominator_uuid);
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      appendSandboxIdentity(queryParams);
-      const queryString = queryParams.toString();
-      const suffix = `/user-consents/${productUuid}/purposes${queryString ? `?${queryString}` : ""}`;
-      const url = useLedger()
-        ? ledgerUrl(baseRequest, suffix)
-        : privacyCenterUrl(baseRequest, suffix);
-      return privacyCenterApiFetch(url, {
-        ...options,
-        method: "GET",
-        cache: "no-store",
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Manage consent (privacy center) - revoke, regrant, or renew.
-     *
-     * The Go ledger has no manage-consent route, so with a ledger configured
-     * this is expressed as a `partial` submit-consent on the ledger — mirroring
-     * the Python dual-write relay (`build_consent_management_payload`): the
-     * affected purpose is re-submitted with `selected: false` to revoke or
-     * `selected: true` to regrant/renew, and `partial: true` so the rest of the
-     * notice's purposes are left untouched. The principal is resolved from the
-     * JWT, so no `contact`/identifiers are sent in the body, and
-     * `consent_event_uuid` is omitted so the ledger mints a fresh event.
-     *
-     * Without a ledger, the legacy Python `/manage-consent?status=` endpoint is
-     * used with its `{ purpose_uuid, contact, ... }` payload.
-     */
-    async manageConsent(
-      baseRequest: BaseRequest,
-      purposeId: string,
-      // Sent to the legacy Python endpoint only; the ledger resolves the
-      // principal from the JWT, so no identifiers are sent in ledger mode.
-      contact: string,
-      status: 'revoke' | 'regrant' | 'renew',
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">,
-      nominatorContact?: string,
-      dataElementUuids?: string[],
-      productUuid?: string,
-      noticeUuid?: string,
-      dataElements?: Array<{ uuid: string; selected: boolean }>,
-      language?: string
-    ): Promise<unknown> {
-      if (!useLedger()) {
-        const url = privacyCenterUrl(baseRequest, `/manage-consent?status=${status}`);
-        const body: Record<string, unknown> = { purpose_uuid: purposeId, contact };
-        if (nominatorContact) {
-          body.nominator_contact = nominatorContact;
-        }
-        if (Array.isArray(dataElementUuids) && dataElementUuids.length > 0) {
-          body.data_element_uuids = dataElementUuids;
-        }
-        if (productUuid) {
-          body.product_uuid = productUuid;
-        }
-        if (language) {
-          body.language = language;
-        }
-        return privacyCenterApiFetch(url, {
-          ...options,
-          method: "POST",
-          body: JSON.stringify(body),
-          authToken: resolveAuthToken(authToken, baseRequest),
-        });
-      }
-      if (!noticeUuid) {
-        throw new Error("notice_uuid is required to manage consent via the ledger");
-      }
-      const purposeSelected = status !== 'revoke';
-      const elements = (dataElements ?? []).map((de) => {
-        let selected: boolean;
-        if (status === 'revoke') {
-          selected = false;
-        } else if (status === 'regrant') {
-          // Only the data elements the user chose to re-grant become selected.
-          selected = Array.isArray(dataElementUuids)
-            ? dataElementUuids.includes(de.uuid)
-            : de.selected;
-        } else {
-          // renew — preserve the currently-granted set.
-          selected = de.selected;
-        }
-        return { uuid: de.uuid, selected };
-      });
-      const body: Record<string, unknown> = {
-        notice_uuid: noticeUuid,
-        partial: true,
-        declined: false,
-        select_all_mandatory: false,
-        self_declared_adult: false,
-        purposes: [
-          {
-            purpose_uuid: purposeId,
-            selected: purposeSelected,
-            data_elements: elements,
-          },
-        ],
-        ...(language ? { language } : {}),
-      };
-      const url = ledgerUrl(baseRequest, "/submit-consent");
-      return privacyCenterApiFetch(url, {
-        ...options,
-        method: "POST",
-        body: JSON.stringify(body),
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Get activities (privacy center)
-     */
-    async getActivities(
-      baseRequest: BaseRequest,
-      offset?: number,
-      limit?: number,
-      language?: string,
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const queryParams = new URLSearchParams();
-      if (offset !== undefined) queryParams.append("offset", offset.toString());
-      if (limit !== undefined) queryParams.append("limit", limit.toString());
-      if (language) queryParams.append("language", language);
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      appendSandboxIdentity(queryParams);
-      const queryString = queryParams.toString();
-      const url = privacyCenterUrl(baseRequest, `/activities${queryString ? `?${queryString}` : ""}`);
-      return privacyCenterApiFetch<unknown>(url, {
-        ...options,
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * List all data principals that share this session's contact
-     * (shared-contact profile picker). Identity is derived server-side from the
-     * JWT — the caller sends nothing but its bearer token.
-     */
-    async listIdentities(
-      baseRequest: BaseRequest,
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<IdentityListResponse> {
-      const url = privacyCenterUrl(baseRequest, '/identities');
-      return privacyCenterApiFetch<IdentityListResponse>(url, {
-        ...options,
-        cache: 'no-store',
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Re-scope the session to a chosen principal uuid (must be one of the
-     * principals sharing this session's contact). Returns fresh access/refresh
-     * tokens scoped to that principal.
-     */
-    async selectPrincipal(
-      baseRequest: BaseRequest,
-      principalUuid: string,
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<SelectPrincipalResponse> {
-      const url = privacyCenterUrl(baseRequest, '/identities/select');
-      return privacyCenterApiFetch<SelectPrincipalResponse>(url, {
-        ...options,
-        method: 'POST',
-        body: JSON.stringify({ uuid: principalUuid }),
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Get receipts (privacy center) — consent receipts for the authenticated user
-     */
-    async getReceipts(
-      baseRequest: BaseRequest,
-      params: {
-        skip?: number;
-        limit?: number;
-        notice_uuid?: string;
-        event_type?: string;
-        status?: string;
-        created_after?: string;
-        created_before?: string;
-        language?: string;
-      },
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const queryParams = new URLSearchParams();
-      if (params.skip !== undefined) queryParams.append("skip", params.skip.toString());
-      if (params.limit !== undefined) queryParams.append("limit", params.limit.toString());
-      if (params.notice_uuid) queryParams.append("notice_uuid", params.notice_uuid);
-      if (params.event_type) queryParams.append("event_type", params.event_type);
-      if (params.status) queryParams.append("status", params.status);
-      if (params.created_after) queryParams.append("created_after", params.created_after);
-      if (params.created_before) queryParams.append("created_before", params.created_before);
-      if (params.language) queryParams.append("language", params.language);
-      const queryString = queryParams.toString();
-      // With a ledger configured, receipts are served by the Go ledger
-      // (paginated list under /public/...); otherwise the legacy Python
-      // privacy-center list is used. normalizeReceipts tolerates both envelopes.
-      const receiptsSuffix = `/receipts${queryString ? `?${queryString}` : ""}`;
-      const url = useLedger()
-        ? ledgerUrl(baseRequest, receiptsSuffix)
-        : privacyCenterUrl(baseRequest, receiptsSuffix);
-      return privacyCenterApiFetch<unknown>(url, {
-        ...options,
-        method: "GET",
-        cache: "no-store",
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Download a single receipt as a PDF (privacy center).
-     * Returns raw PDF bytes as a Blob — the caller builds an object URL to open/save it.
-     * Uses a direct fetch (not privacyCenterApiFetch) because the response is binary, not JSON,
-     * and the Authorization header must be sent (anchor navigation wouldn't carry it).
-     */
-    async getReceiptPdf(
-      baseRequest: BaseRequest,
-      receiptUuid: string,
-      authToken?: string
-    ): Promise<Blob> {
-      // The ledger serves the receipt PDF at /receipts/{uuid}/download, the
-      // legacy Python service at /receipts/{uuid}/pdf. The receiptUuid always
-      // comes from the same-mode list above, so list and download stay consistent.
-      const url = useLedger()
-        ? ledgerUrl(baseRequest, `/receipts/${receiptUuid}/download`)
-        : privacyCenterUrl(baseRequest, `/receipts/${receiptUuid}/pdf`);
-      const token = resolveAuthToken(authToken, baseRequest);
-      const requestHeaders = new Headers();
-      requestHeaders.set("Accept", "application/pdf");
-      // Sandbox PoC: send the single X-Consent-Token header instead of the JWT
-      // bearer. The receipt PDF download identifies the principal by receiptUuid
-      // (already scoped to the sandbox subject via the same-mode list), so no
-      // extra identity payload is needed here.
-      const sandboxHeaders = sandboxAuthHeaders();
-      if (sandboxHeaders) {
-        Object.entries(sandboxHeaders).forEach(([key, value]) => {
-          requestHeaders.set(key, value);
-        });
-      } else if (token) {
-        const trimmedToken = token.trim();
-        requestHeaders.set(
-          "Authorization",
-          trimmedToken.startsWith("Bearer ") ? trimmedToken : `Bearer ${trimmedToken}`
-        );
-      }
-      const response = await fetch(url, { method: "GET", headers: requestHeaders });
-      if (!response.ok) {
-        let errorMessage = `Request failed with status ${response.status}`;
-        try {
-          const errorData = (await response.json()) as { detail?: unknown; error_code?: string } | null;
-          if (errorData?.detail) {
-            errorMessage =
-              typeof errorData.detail === "string" ? errorData.detail : JSON.stringify(errorData.detail);
-          } else if (errorData?.error_code) {
-            errorMessage = errorData.error_code;
-          }
-        } catch {
-          // non-JSON error body — keep default message
-        }
-        // Prepend HTTP status so callers can branch on it (e.g. 404 = receipt not found)
-        throw new Error(`[${response.status}] ${errorMessage}`);
-      }
-      return response.blob();
-    },
-
-    /**
-     * Get case history (privacy center)
-     */
-    async getCaseHistory(
-      baseRequest: BaseRequest,
-      _contact: string,
-      offset?: number,
-      limit?: number,
-      language?: string,
-      authToken?: string,
-      options?: Omit<ApiFetchOptions, "getAuthToken">
-    ): Promise<unknown> {
-      const queryParams = new URLSearchParams();
-      if (offset !== undefined) queryParams.append("offset", offset.toString());
-      if (limit !== undefined) queryParams.append("limit", limit.toString());
-      if (language) queryParams.append("language", language);
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      appendSandboxIdentity(queryParams);
-      const queryString = queryParams.toString();
-      const url = privacyCenterUrl(baseRequest, `/cases?${queryString}`);
-      return privacyCenterApiFetch<unknown>(url, {
-        ...options,
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    // ─── Case Communication ─────────────────────────────────────────────────
-
-    /**
-     * Get messages for a case (privacy center)
-     */
-    async getCaseMessages(
-      baseRequest: BaseRequest,
-      caseUuid: string,
-      authToken?: string
-    ): Promise<CaseMessage[]> {
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      const url = caseUrl(baseRequest, caseUuid, `/messages${sandboxIdentitySuffix()}`);
-      return privacyCenterApiFetch<CaseMessage[]>(url, {
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Send a message on a case (privacy center)
-     */
-    async sendCaseMessage(
-      baseRequest: BaseRequest,
-      caseUuid: string,
-      body: string,
-      documentUuids: string[],
-      authToken?: string
-    ): Promise<CaseMessage> {
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      const url = caseUrl(baseRequest, caseUuid, `/messages${sandboxIdentitySuffix()}`);
-      return privacyCenterApiFetch<CaseMessage>(url, {
-        method: 'POST',
-        body: JSON.stringify({ body, document_uuids: documentUuids }),
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Upload a document on a case (multipart/form-data, privacy center)
-     */
-    async uploadCaseDocument(
-      baseRequest: BaseRequest,
-      caseUuid: string,
-      file: File,
-      authToken?: string
-    ): Promise<UploadDocumentResponse> {
-      // Sandbox mode: the acting identity travels as query params
-      // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
-      const url = caseUrl(baseRequest, caseUuid, `/upload-document${sandboxIdentitySuffix()}`);
-      const formData = new FormData();
-      formData.append('file', file, file.name); // field name must be exactly "file"
-      // "payload" is required by the privacy-center endpoint (omitting it causes 422)
-      formData.append('payload', JSON.stringify({ metadata: null }));
-      return privacyCenterApiFetch<UploadDocumentResponse>(url, {
-        method: 'POST',
-        body: formData,
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Submit a document against a handler document request (privacy center)
-     */
-    async submitDocumentForRequest(
-      baseRequest: BaseRequest,
-      caseUuid: string,
-      requestEventUuid: string,
-      documentUuid: string,
-      body: string,
-      authToken?: string
-    ): Promise<CaseMessage> {
-      const url = caseUrl(baseRequest, caseUuid, `/document-requests/${requestEventUuid}/submit`);
-      return privacyCenterApiFetch<CaseMessage>(url, {
-        method: 'POST',
-        body: JSON.stringify({ document_uuid: documentUuid, body }),
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Get document info/download URL for a case document (privacy center)
-     */
-    async getCaseDocument(
-      baseRequest: BaseRequest,
-      caseUuid: string,
-      documentUuid: string,
-      authToken?: string
-    ): Promise<MessageDocument> {
-      const url = caseUrl(baseRequest, caseUuid, `/documents/${documentUuid}`);
-      return privacyCenterApiFetch<MessageDocument>(url, {
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    // ─── Notification Hub ─────────────────────────────────────────────────
-
-    /**
-     * List notifications (paginated, with filters)
-     */
-    async getNotifications(
-      baseRequest: BaseRequest,
-      params?: NotificationQueryParams,
-      authToken?: string
-    ): Promise<NotificationListResponse> {
-      const queryParams = new URLSearchParams();
-      if (params?.category) {
-        queryParams.append('category', params.category);
-      }
-      if (params?.notification_type) {
-        queryParams.append('notification_type', params.notification_type);
-      }
-      if (params?.is_read !== undefined) {
-        queryParams.append('is_read', String(params.is_read));
-      }
-      if (params?.skip !== undefined) {
-        queryParams.append('skip', params.skip.toString());
-      }
-      if (params?.limit !== undefined) {
-        queryParams.append('limit', params.limit.toString());
-      }
-      if (params?.include_summary) {
-        queryParams.append('include_summary', 'true');
-      }
-      if (params?.language) {
-        queryParams.append('language', params.language);
-      }
-      const queryString = queryParams.toString();
-      const url = notificationUrl(baseRequest, queryString ? `?${queryString}` : '');
-      return privacyCenterApiFetch<NotificationListResponse>(url, {
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Get notification summary (aggregated counts only)
-     */
-    async getNotificationSummary(
-      baseRequest: BaseRequest,
-      authToken?: string
-    ): Promise<NotificationSummary> {
-      const url = notificationUrl(baseRequest, '/summary');
-      return privacyCenterApiFetch<NotificationSummary>(url, {
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Get unread notification count (lightweight, for badge)
-     */
-    async getUnreadCount(
-      baseRequest: BaseRequest,
-      authToken?: string
-    ): Promise<UnreadCountResponse> {
-      const url = notificationUrl(baseRequest, '/unread-count');
-      return privacyCenterApiFetch<UnreadCountResponse>(url, {
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Mark a single notification as read
-     */
-    async markNotificationRead(
-      baseRequest: BaseRequest,
-      notificationUuid: string,
-      authToken?: string
-    ): Promise<NotificationActionResponse> {
-      const url = notificationUrl(baseRequest, `/${notificationUuid}/read`);
-      return privacyCenterApiFetch<NotificationActionResponse>(url, {
-        method: 'PATCH',
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Mark all notifications as read
-     */
-    async markAllNotificationsRead(
-      baseRequest: BaseRequest,
-      authToken?: string
-    ): Promise<NotificationActionResponse> {
-      const url = notificationUrl(baseRequest, '/mark-all-read');
-      return privacyCenterApiFetch<NotificationActionResponse>(url, {
-        method: 'POST',
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-
-    /**
-     * Acknowledge a notification (sets is_read and is_acknowledged to true)
-     */
-    async acknowledgeNotification(
-      baseRequest: BaseRequest,
-      notificationUuid: string,
-      authToken?: string
-    ): Promise<NotificationActionResponse> {
-      const url = notificationUrl(baseRequest, `/${notificationUuid}/acknowledge`);
-      return privacyCenterApiFetch<NotificationActionResponse>(url, {
-        method: 'POST',
-        authToken: resolveAuthToken(authToken, baseRequest),
-      });
-    },
-  };
-}