@consentera/consent-sdk 2.0.0

package/dist/react/index.mjs

@@ -0,0 +1,2724 @@
+'use client';
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { createContext, useMemo, useState, useEffect, useContext, useRef, useCallback } from 'react';
+
+/**
+ * Consentera Consent SDK — the error taxonomy.
+ *
+ * ONE class with a discriminant, plus subclasses for `instanceof`. Before 2.0.0
+ * there was a single `ConsentEraApiError` carrying `statusCode` and the raw
+ * `responseBody`, which meant a caller who wanted to know *what went wrong* had
+ * to dig a string out of an untyped body — and the two things support asks for
+ * first, the canonical code and the request id, were both discarded. The API
+ * has carried them the whole time: the envelope is `{code, message}`
+ * (core/apierrors/errors.go:33-38) over ~141 codes of which 22 are canonical
+ * (core/apierrors/canonical_codes.go), and `X-Request-ID` is set by
+ * chi middleware and CORS-exposed so a browser can read it
+ * (cmd/api/main.go:1266, :1272).
+ *
+ * `kind` is the discriminant to switch on. The CODE is the platform's word and
+ * may be one of many; the KIND is this SDK's classification of it and is a
+ * closed set, so `switch (err.kind)` stays exhaustive when the platform adds a
+ * code. Both are on the error — never infer the kind from the code yourself.
+ */
+/**
+ * Canonical code → kind. Codes taken from the platform's registry; anything not
+ * listed falls back to the HTTP status, and a code we have never seen is
+ * therefore still classified rather than dropped into `unknown`.
+ */
+const CODE_KIND = {
+    // 400 — the request itself
+    VALIDATION_ERROR: 'validation',
+    INVALID_REQUEST_BODY: 'validation',
+    INVALID_JSON: 'validation',
+    INVALID_UUID: 'validation',
+    BAD_REQUEST: 'validation',
+    MISSING_REQUIRED_FIELD: 'validation',
+    MISSING_TENANT_ID: 'validation',
+    INVALID_TENANT_ID: 'validation',
+    INVALID_DATE_OF_BIRTH: 'validation',
+    INVALID_IDENTIFIER_FORMAT: 'validation',
+    // identity — the U58 / lifecycle identity family, which is what an
+    // integrator gets wrong most often and most expensively
+    DATA_PRINCIPAL_REF_REFUSED: 'identity',
+    UNKNOWN_IDENTIFIER_FIELD: 'identity',
+    IDENTIFIER_REQUIRED: 'identity',
+    IDENTITY_MISMATCH: 'identity',
+    // guardian / age
+    GUARDIAN_REQUIRED: 'guardian',
+    GUARDIAN_CONSENT_REQUIRED: 'guardian',
+    GUARDIAN_TOKEN_REQUIRED: 'guardian',
+    GUARDIAN_EVIDENCE_MISSING: 'guardian',
+    GUARDIAN_IDENTITY_NOT_VERIFIED: 'guardian',
+    GUARDIAN_ADULT_NOT_VERIFIED: 'guardian',
+    GUARDIAN_VERIFICATION_METHOD_INVALID: 'guardian',
+    AGE_REQUIRED: 'guardian',
+    // 401
+    UNAUTHORIZED: 'auth',
+    INVALID_CREDENTIALS: 'auth',
+    TOKEN_MISSING: 'auth',
+    TOKEN_INVALID: 'auth',
+    TOKEN_EXPIRED: 'auth',
+    TOKEN_MALFORMED: 'auth',
+    TOKEN_REVOKED: 'auth',
+    SESSION_NOT_FOUND: 'auth',
+    SESSION_EXPIRED: 'auth',
+    SESSION_REVOKED: 'auth',
+    // 403
+    FORBIDDEN: 'permission',
+    TENANT_MISMATCH: 'permission',
+    TENANT_SUSPENDED: 'permission',
+    ACCOUNT_DISABLED: 'permission',
+    PRIVILEGE_ESCALATION: 'permission',
+    SCHEME_NOT_CONFIGURED: 'permission',
+    CSRF_TOKEN_MISSING: 'permission',
+    CSRF_TOKEN_INVALID: 'permission',
+    // 404 / 409 / 429 / 5xx
+    NOT_FOUND: 'not_found',
+    USER_NOT_FOUND: 'not_found',
+    CONFLICT: 'conflict',
+    IDEMPOTENCY_KEY_REUSE: 'conflict',
+    RATE_LIMIT_EXCEEDED: 'rate_limit',
+    INTERNAL_ERROR: 'server',
+    INTERNAL_SERVER_ERROR: 'server',
+    DATABASE_ERROR: 'server',
+};
+function kindForStatus(status) {
+    if (status === 401)
+        return 'auth';
+    if (status === 403)
+        return 'permission';
+    if (status === 404)
+        return 'not_found';
+    if (status === 409)
+        return 'conflict';
+    if (status === 429)
+        return 'rate_limit';
+    if (status >= 500)
+        return 'server';
+    if (status >= 400)
+        return 'validation';
+    return 'unknown';
+}
+/**
+ * Parse `Retry-After`, which RFC 9110 §10.2.3 allows to be either a count of
+ * seconds or an HTTP-date. Returns milliseconds, or undefined when the header
+ * is absent or unparseable — never NaN, because a NaN delay becomes an
+ * immediate retry and turns a 429 into a hot loop.
+ */
+function parseRetryAfterMs(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : undefined;
+    }
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - now);
+}
+/** The base error every road in this SDK throws. */
+class ConsenteraError extends Error {
+    /** This SDK's classification. A closed set — safe to switch on. */
+    kind;
+    /** The platform's canonical error code, when the response carried one. */
+    code;
+    /** HTTP status; 0 for a transport failure that never reached a status. */
+    status;
+    /** `X-Request-ID` off the response. Quote this in a support ticket. */
+    requestId;
+    /** The parsed response body, or the raw text when it was not JSON. */
+    responseBody;
+    /** Whether THIS SDK would retry it. Already applied internally. */
+    retryable;
+    /** Server-asked wait, from `Retry-After`, in ms. */
+    retryAfterMs;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = new.target.name;
+        this.kind = init.kind;
+        this.code = init.code;
+        this.status = init.status ?? 0;
+        this.requestId = init.requestId;
+        this.responseBody = init.responseBody;
+        this.retryable = init.retryable ?? false;
+        this.retryAfterMs = init.retryAfterMs;
+        // Extending Error across the ES5 target rollup emits breaks instanceof
+        // without this; new.target is the actual subclass.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** @deprecated 2.0.0 — use `status`. Kept so 1.x `err.statusCode` still reads. */
+    get statusCode() {
+        return this.status;
+    }
+    /** A one-line form safe to log: no body, no identifiers. */
+    toString() {
+        const bits = [this.name, this.code ?? this.kind];
+        if (this.status)
+            bits.push(String(this.status));
+        if (this.requestId)
+            bits.push(`req=${this.requestId}`);
+        return `${bits.join(' ')}: ${this.message}`;
+    }
+}
+class ConsenteraConfigError extends ConsenteraError {
+}
+class ConsenteraAuthError extends ConsenteraError {
+}
+class ConsenteraPermissionError extends ConsenteraError {
+}
+class ConsenteraValidationError extends ConsenteraError {
+}
+class ConsenteraIdentityError extends ConsenteraError {
+}
+class ConsenteraGuardianError extends ConsenteraError {
+}
+class ConsenteraNotFoundError extends ConsenteraError {
+}
+class ConsenteraConflictError extends ConsenteraError {
+}
+class ConsenteraRateLimitError extends ConsenteraError {
+}
+class ConsenteraServerError extends ConsenteraError {
+}
+class ConsenteraNetworkError extends ConsenteraError {
+}
+class ConsenteraTimeoutError extends ConsenteraError {
+}
+const KIND_CLASS = {
+    config: ConsenteraConfigError,
+    auth: ConsenteraAuthError,
+    permission: ConsenteraPermissionError,
+    validation: ConsenteraValidationError,
+    identity: ConsenteraIdentityError,
+    guardian: ConsenteraGuardianError,
+    not_found: ConsenteraNotFoundError,
+    conflict: ConsenteraConflictError,
+    rate_limit: ConsenteraRateLimitError,
+    server: ConsenteraServerError,
+    network: ConsenteraNetworkError,
+    timeout: ConsenteraTimeoutError,
+    cancelled: ConsenteraError,
+    unknown: ConsenteraError,
+};
+function newOfKind(init) {
+    return new KIND_CLASS[init.kind](init);
+}
+/** Pull `{code, message}` off a parsed body, tolerating the `{error:{...}}` wrapper. */
+function readEnvelope(body) {
+    if (!body || typeof body !== 'object')
+        return {};
+    const o = body;
+    const inner = o.error && typeof o.error === 'object' ? o.error : o;
+    const code = typeof inner.code === 'string' ? inner.code : undefined;
+    const message = typeof inner.message === 'string' ? inner.message : undefined;
+    return { code, message };
+}
+/** Build the error for a non-2xx response. */
+function errorFromResponse(args) {
+    const { code, message } = readEnvelope(args.body);
+    const kind = (code && CODE_KIND[code]) || kindForStatus(args.status);
+    const retryable = args.status === 429 || args.status >= 500;
+    return newOfKind({
+        kind,
+        code,
+        status: args.status,
+        requestId: args.requestId,
+        responseBody: args.body,
+        retryable,
+        retryAfterMs: args.retryAfterMs,
+        message: message ||
+            `${args.method} ${args.path} failed: ${args.status}${args.statusText ? ` ${args.statusText}` : ''}`,
+    });
+}
+/** A request that never reached a status: DNS, TLS, offline, CORS. */
+function networkError(message, cause) {
+    return new ConsenteraNetworkError({ kind: 'network', message, status: 0, retryable: true, cause });
+}
+/** The SDK's own deadline fired. */
+function timeoutError(message, cause) {
+    return new ConsenteraTimeoutError({ kind: 'timeout', message, status: 0, retryable: true, cause });
+}
+/** The caller's AbortSignal fired. NEVER retryable: the caller asked to stop. */
+function cancelledError(message, cause) {
+    return new ConsenteraError({ kind: 'cancelled', message, status: 0, retryable: false, cause });
+}
+/** Misconfiguration found before anything went on the wire. */
+function configError(message, code) {
+    return new ConsenteraConfigError({ kind: 'config', message, status: 0, code, retryable: false });
+}
+
+/**
+ * Consentera Consent SDK — THE artifact read, in one place.
+ *
+ * `ConsentSession.getArtifact` and the callback handler's confirmation both
+ * read GET /consent/artifacts/{artifact_id}, and before this file each spelled
+ * the request itself. Both spelled it WITHOUT `?session_id=`, which on the
+ * platform that ships is the difference between two answers:
+ *
+ *   without session_id   a consent whose artifact is still being written is a
+ *                        404 ARTIFACT_NOT_FOUND — the same word a guessed id
+ *                        gets. The callback handler therefore had to read
+ *                        every 404 as "maybe pending" and poll it, so a FORGED
+ *                        artifact_id came back `pending` instead of refused.
+ *   with session_id      202 + Retry-After while the projection is owed; 404
+ *                        only when the id was never issued for that session or
+ *                        will never be written. (GetArtifactHandler,
+ *                        consent/collection.go:4409-4520 at 4fda7e3d05; walk
+ *                        finding F018; SDK register WEB-033.)
+ *
+ * Measured on setup.consentera.in (4fda7e3d05): an unknown artifact read with a
+ * real session is 404; the walk's real artifact with its session is 200. See
+ * fixtures/platform-wire/artifact-read.*.json at the repo root.
+ *
+ * WHAT THE session_id DOES NOT DO (walk finding F077, measured): once the
+ * artifact row exists the 200 path reads by tenant + artifact_id ALONE. The
+ * same artifact read with a random session_id is still 200. So a 200 does not
+ * prove the artifact belongs to your session; compare its `data_principal_id`
+ * with the one your session create returned (the callback handler does).
+ */
+/** Retry-After when the 202 carried neither the header nor `retry_after`. */
+const DEFAULT_PENDING_RETRY_MS = 1000;
+function artifactPath(artifactId) {
+    // encodeURIComponent: an id with a URL-special character (or a caller passing
+    // a path fragment) would otherwise reshape the request.
+    return `/consent/artifacts/${encodeURIComponent(artifactId)}`;
+}
+/**
+ * Read one artifact. Resolves `recorded` (200) or `pending` (202); a 404, a
+ * 403 and everything else is the transport's typed ConsenteraError.
+ */
+async function readArtifact(request, artifactId, options = {}) {
+    const res = await request('GET', artifactPath(artifactId), undefined, { session_id: options.sessionId || undefined }, { raw: true, signal: options.signal, timeoutMs: options.timeoutMs });
+    if (res.status === 200 && res.body && typeof res.body === 'object') {
+        return { state: 'recorded', artifact: res.body, requestId: res.requestId };
+    }
+    if (res.status === 202 && res.body && typeof res.body === 'object') {
+        const pending = res.body;
+        const fromBody = typeof pending.retry_after === 'number' && pending.retry_after >= 0 ? pending.retry_after * 1000 : undefined;
+        return {
+            state: 'pending',
+            pending,
+            retryAfterMs: res.retryAfterMs ?? fromBody ?? DEFAULT_PENDING_RETRY_MS,
+            requestId: res.requestId,
+        };
+    }
+    // Any other 2xx (a 204, a 200 with no body) is not an answer this road
+    // gives. Reporting it as an artifact would be inventing one.
+    throw errorFromResponse({
+        status: res.status,
+        statusText: 'not an artifact read answer (expected 200 or 202 with a JSON body)',
+        body: res.body,
+        requestId: res.requestId,
+        method: 'GET',
+        path: artifactPath(artifactId),
+    });
+}
+
+/**
+ * Consentera Consent SDK — guarded browser storage.
+ *
+ * EVERY ACCESS IS WRAPPED, AND THAT IS NOT DEFENSIVENESS. `localStorage` and
+ * `sessionStorage` THROW rather than return null in ordinary, common
+ * configurations: Safari's private browsing on old versions, a site with
+ * cookies blocked, a sandboxed iframe without `allow-same-origin`, a quota that
+ * is full. Before 2.0.0 `ConsentStorage.save()` called `localStorage.setItem`
+ * bare, so a visitor with storage blocked did not get a degraded banner — they
+ * got an exception out of the middle of a consent write.
+ *
+ * ONE implementation, so the "did we remember to try/catch this one" question
+ * is asked once. `ConsenteraConsent.getOrCreateDeviceId` already had the right
+ * shape; it was the only place that did.
+ *
+ * When storage is unavailable the SDK degrades to a per-page memory map: the
+ * flow still works within the page, it just does not survive a reload. That is
+ * the correct trade for a consent handshake, which is short-lived.
+ */
+const memory = {
+    local: new Map(),
+    session: new Map(),
+};
+/** The one place key names are spelled, so a reader and a writer cannot drift. */
+const storageKeys = {
+    session: (id) => `consentera_session_${id}`,
+    callback: (id) => `consentera_callback_${id}`,
+    pendingSync: 'consentera_pending_sync',
+    deviceId: 'consentera_device_id',
+};
+function backing(kind) {
+    try {
+        if (typeof window === 'undefined')
+            return null;
+        const s = kind === 'local' ? window.localStorage : window.sessionStorage;
+        // Touching the object is itself what throws in a blocked context, so the
+        // probe has to be a real operation rather than a truthiness check.
+        const probe = '__consentera_probe__';
+        s.setItem(probe, '1');
+        s.removeItem(probe);
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+function readStored(kind, key) {
+    const s = backing(kind);
+    if (!s)
+        return memory[kind].get(key) ?? null;
+    try {
+        return s.getItem(key);
+    }
+    catch {
+        return memory[kind].get(key) ?? null;
+    }
+}
+/** Returns false when the value could not be persisted anywhere durable. */
+function writeStored(kind, key, value) {
+    const s = backing(kind);
+    if (s) {
+        try {
+            s.setItem(key, value);
+            return true;
+        }
+        catch {
+            /* quota or policy — fall through to memory */
+        }
+    }
+    memory[kind].set(key, value);
+    return false;
+}
+function removeStored(kind, key) {
+    const s = backing(kind);
+    if (s) {
+        try {
+            s.removeItem(key);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    memory[kind].delete(key);
+}
+
+/**
+ * The SDK's own version, sent on every request as `X-Consentera-SDK`.
+ *
+ * KEPT IN SYNC BY A TEST, NOT BY A BUILD STEP. `src/__tests__/core/version.test.ts`
+ * reads package.json and fails when the two disagree, so a release that forgets
+ * this file cannot go green. A build-time codegen would have been the other
+ * option; it was rejected because the constant then does not exist when a host
+ * builds from src, and because a generated file in the tree is one command from
+ * being overwritten with the wrong value and nothing noticing.
+ */
+const SDK_VERSION = '2.0.0';
+const SDK_PLATFORM = 'web';
+/** The value of the `X-Consentera-SDK` header: `<surface>/<version>`. */
+const SDK_HEADER_VALUE = `js/${SDK_VERSION}`;
+/**
+ * The `User-Agent` half of the pair, agreed across all six surfaces
+ * (coordinator ruling 2026-09-22):
+ *
+ *     User-Agent:        ConsenteraSDK/2.0.0 (<platform>; <runtime>)
+ *     X-Consentera-SDK:  <surface>/2.0.0
+ *
+ * `ConsenteraSDK/<version>` is the form the PLATFORM ALREADY PARSES:
+ * `internal/core/audit/user_agent_coarsening_test.go:39-40` asserts that
+ * `ConsenteraSDK/2.3.1 (Android 14; SM-G991B; build 4471)` coarsens to
+ * `ConsenteraSDK/2`, so this is the shape its audit pipeline expects rather
+ * than a new one. (A second spelling, `consentera-sdk/1.2`, appears in
+ * `validation_envelope_test.go:233`; the pair above is the agreed one.)
+ *
+ * IN A BROWSER THIS HEADER CANNOT BE SENT. `User-Agent` is a forbidden header
+ * name (fetch spec §forbidden-request-header), so a browser silently drops any
+ * attempt to set it — the SDK does not try, and the browser build identifies
+ * itself with `X-Consentera-SDK` alone. The Node build (and the CLI) send both,
+ * because there the header is ours to set.
+ */
+function userAgentValue(runtime) {
+    const rt = (typeof process !== 'undefined' && process.versions?.node ? `node ${process.versions.node}` : 'unknown');
+    return `ConsenteraSDK/${SDK_VERSION} (${SDK_PLATFORM}; ${rt})`;
+}
+
+/**
+ * Consentera Consent SDK — the transport.
+ *
+ * Everything that talks to the platform goes through `HttpTransport.request`.
+ * One implementation, because the four things below are the ones that are
+ * always missing when each caller writes its own `fetch`:
+ *
+ *  1. A DEADLINE. `fetch` has none. Before 2.0.0 a hung connection hung the
+ *     caller's promise forever, which on a consent gate means a page that never
+ *     renders. Every request now carries an AbortController, linked to the
+ *     caller's own signal so `AbortSignal` cancellation still works.
+ *  2. RETRIES that are safe. Exponential backoff with full jitter on network
+ *     failure, 5xx and 429, honouring `Retry-After` when the server sends one.
+ *  3. ONE IDEMPOTENCY KEY PER LOGICAL OPERATION. Before 2.0.0 the key was
+ *     minted inside the request function from `Date.now()` + `Math.random()`,
+ *     so it changed on every attempt and the caller could not supply one — a
+ *     dedupe mechanism that was present and could not dedupe anything. The key
+ *     is now minted ONCE per logical operation, reused on every retry of it,
+ *     and `options.idempotencyKey` overrides it.
+ *  4. THE REQUEST ID. The platform sets `X-Request-ID` and CORS-exposes it
+ *     (cmd/api/main.go:1266, :1272). It is now on every error.
+ *
+ * WHAT IS DELIBERATELY NOT HERE: no request or response BODY is ever logged.
+ * The body of a session create is the Data Principal's identifiers.
+ */
+const DEFAULT_RETRY = { attempts: 3, baseDelayMs: 250, maxDelayMs: 4000 };
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** `typeof window !== 'undefined'` in one place, so a test can reason about it. */
+function isBrowser() {
+    return typeof window !== 'undefined';
+}
+/** A secret DF key: the platform's prefixes for the two secret classes. */
+function isSecretKey(key) {
+    return !!key && (key.startsWith('tiq_live_') || key.startsWith('tiq_test_'));
+}
+/** A public site key. */
+function isSiteKey(key) {
+    return !!key && key.startsWith('tiq_pub_');
+}
+/**
+ * THE ONE REFUSAL, in one place — used by BOTH entry points (ConsentEraClient
+ * and ConsenteraConsent), because a rule enforced at only one door is not a
+ * rule. A secret key in a browser is not a warning: the bundle is public, so by
+ * the time it runs the key is already published to every visitor. Refusing at
+ * construction is the only point at which the integrator still has the option
+ * of not shipping it.
+ *
+ * `fix` is the entry-point-specific remedy (a proxy endpoint for the lifecycle
+ * client, a public site key for the cookie SDK); everything else — the reason,
+ * the prefix echo, the escape hatch — is identical, which is exactly why it
+ * lives here rather than being copied and left to drift.
+ */
+function assertNoSecretKeyInBrowser(opts) {
+    if (!isBrowser() || !opts.apiKey || opts.unsafeAllowSecretKeyInBrowser)
+        return;
+    throw configError('Consentera: `apiKey` is a SECRET and this SDK is running in a browser, where every ' +
+        'visitor can read the bundle. ' +
+        opts.fix +
+        ' ' +
+        (isSecretKey(opts.apiKey)
+            ? `The key supplied starts with "${opts.apiKey.slice(0, 9)}" — rotate it, it is now in a bundle. `
+            : '') +
+        'If you are certain this code never reaches a browser (a test harness with a jsdom window, ' +
+        'a server-side render that only looks like one), set `unsafeAllowSecretKeyInBrowser: true` ' +
+        'and every request will warn.', 'SECRET_KEY_IN_BROWSER');
+}
+/**
+ * Crypto-strong id. `Math.random()` was what minted idempotency keys before
+ * 2.0.0; it is neither unpredictable nor collision-safe at 6 characters.
+ */
+function newRequestId() {
+    const c = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
+    if (c && typeof c.randomUUID === 'function')
+        return c.randomUUID();
+    if (c && typeof c.getRandomValues === 'function') {
+        const b = c.getRandomValues(new Uint8Array(16));
+        return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+    }
+    // Last resort for an ancient browser. Recorded rather than silent: a caller
+    // on such a browser should supply its own idempotencyKey.
+    return `nc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(cancelledError('request cancelled'));
+            return;
+        }
+        const t = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(cancelledError('request cancelled'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Full-jitter backoff (AWS's "Exponential Backoff and Jitter"): random in [0, cap]. */
+function backoffMs(attempt, policy, random = Math.random) {
+    const exp = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** attempt);
+    return Math.floor(random() * exp);
+}
+class HttpTransport {
+    config;
+    logger;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    /** Swap config after construction (the client re-reads customHeaders each call). */
+    updateConfig(patch) {
+        this.config = { ...this.config, ...patch };
+    }
+    /**
+     * The credential decision for one road, in one place so the policy can be
+     * read rather than reconstructed from call sites.
+     *
+     * Returns the auth headers to send, or throws a config error naming the fix.
+     */
+    authHeadersFor(road, viaProxy) {
+        const { apiKey, siteKey, unsafeAllowSecretKeyInBrowser } = this.config;
+        const browser = isBrowser();
+        // In proxy mode the DF's own server holds the credential and adds it. The
+        // SDK sends none — a key sent here would be a key in the bundle.
+        if (viaProxy)
+            return {};
+        if (road === 'session')
+            return {};
+        if (road === 'public') {
+            if (siteKey)
+                return { 'X-API-Key': siteKey };
+            // A public road with no site key is legitimate: /notices/current takes a
+            // tenant_code in the query.
+            return {};
+        }
+        // road === 'df'
+        if (browser && !unsafeAllowSecretKeyInBrowser) {
+            throw configError('Consentera: this call needs a Data Fiduciary credential, which is a SECRET and must ' +
+                'never be in a browser bundle. Set `proxyEndpoint` to your own server route (it holds ' +
+                'the tiq_live_/tiq_test_ key and forwards the call), or run this call server-side. ' +
+                'A public site key (tiq_pub_) cannot authorise it: the lifecycle roads are ' +
+                'server-to-server. A site key opens only the public read roads and the ' +
+                'session-scoped render/submit, and only for the origins in its allowed_domains.', 'SECRET_KEY_IN_BROWSER');
+        }
+        if (apiKey) {
+            if (browser && unsafeAllowSecretKeyInBrowser) {
+                this.logger.warn('Consentera: SENDING A SECRET KEY FROM A BROWSER because ' +
+                    'unsafeAllowSecretKeyInBrowser is set. Every visitor to this page can read it. ' +
+                    'Rotate the key and move to proxyEndpoint.');
+            }
+            return { 'X-API-Key': apiKey };
+        }
+        if (isSiteKey(siteKey)) {
+            throw configError('Consentera: a site key (tiq_pub_) was supplied for a Data Fiduciary lifecycle road. ' +
+                'Those roads are server-to-server; a site key opens only the public read roads and the ' +
+                'session-scoped render/submit, so this call would be refused 403. Use `proxyEndpoint`, ' +
+                'or a secret key server-side.', 'SITE_KEY_ON_DF_ROAD');
+        }
+        throw configError('Consentera: no credential for a Data Fiduciary road. Set `proxyEndpoint` (browser) or ' +
+            '`apiKey` (server).', 'NO_CREDENTIAL');
+    }
+    urlFor(path, query) {
+        const { proxyEndpoint, apiEndpoint } = this.config;
+        // A session/public road is reachable without the DF's proxy, but when a
+        // proxy is configured everything goes through it: one origin to allow-list.
+        const viaProxy = !!proxyEndpoint;
+        const base = viaProxy ? proxyEndpoint : apiEndpoint;
+        const prefix = this.config.apiPathPrefix ?? '/api/v1/public';
+        if (prefix !== '/api/v1/public' && prefix !== '/api/v1/cookie-consent') {
+            throw configError('Consentera: unsupported transport API plane.');
+        }
+        let url = viaProxy ? `${base}${path}` : `${base}${prefix}${path}`;
+        if (query) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null)
+                    params.set(k, String(v));
+            }
+            const qs = params.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        return { url, viaProxy };
+    }
+    async request(method, path, body, options = {}) {
+        const road = options.road ?? 'df';
+        const { url, viaProxy } = this.urlFor(path, options.query);
+        const policy = { ...DEFAULT_RETRY, ...this.config.retry, ...options.retry };
+        const timeoutMs = options.timeoutMs ?? this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const doFetch = this.config.fetchImpl ?? globalThis.fetch;
+        if (typeof doFetch !== 'function') {
+            throw configError('Consentera: no fetch implementation available in this environment.');
+        }
+        const headers = {
+            Accept: 'application/json',
+            // THE PAIR, and why only one half of it is here.
+            //
+            // All six surfaces identify themselves as
+            //   User-Agent:       ConsenteraSDK/<version> (<platform>; <runtime>)
+            //   X-Consentera-SDK: <surface>/<version>
+            // the first being the form the platform's audit pipeline already parses
+            // (core/audit/user_agent_coarsening_test.go:39-40 coarsens
+            // `ConsenteraSDK/2.3.1 (…)` to `ConsenteraSDK/2`).
+            //
+            // `User-Agent` is a FORBIDDEN HEADER NAME in a browser: fetch drops any
+            // attempt to set it, silently, so setting it here would be a line that
+            // looks like identification and is not. It is therefore added only when
+            // there is no `window` — the Node build — and the browser identifies
+            // itself with X-Consentera-SDK alone.
+            'X-Consentera-SDK': SDK_HEADER_VALUE,
+            ...(isBrowser() ? {} : { 'User-Agent': userAgentValue() }),
+            ...this.authHeadersFor(road, viaProxy),
+        };
+        if (!viaProxy && road !== 'session' && this.config.tenantId)
+            headers['X-Tenant-Id'] = this.config.tenantId;
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        // ONE key for this logical operation, reused on every attempt below.
+        if (method !== 'GET')
+            headers['Idempotency-Key'] = options.idempotencyKey ?? newRequestId();
+        const custom = typeof this.config.customHeaders === 'function' ? this.config.customHeaders() : this.config.customHeaders;
+        Object.assign(headers, custom, options.headers);
+        let outgoing = body;
+        if (body !== undefined && this.config.beforeSend) {
+            const kept = this.config.beforeSend({ method, path, body });
+            if (kept === null || kept === undefined) {
+                throw configError(`Consentera: beforeSend refused ${method} ${path}. Nothing was sent.`, 'BEFORE_SEND_REFUSED');
+            }
+            outgoing = kept;
+        }
+        const payload = outgoing === undefined ? undefined : JSON.stringify(outgoing);
+        let lastError;
+        for (let attempt = 0; attempt < policy.attempts; attempt++) {
+            if (options.signal?.aborted)
+                throw cancelledError('request cancelled before attempt');
+            const started = Date.now();
+            let timedOut = false;
+            const controller = new AbortController();
+            const timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeoutMs);
+            const onCallerAbort = () => controller.abort();
+            options.signal?.addEventListener('abort', onCallerAbort, { once: true });
+            try {
+                const response = await doFetch(url, {
+                    method,
+                    headers,
+                    body: payload,
+                    signal: controller.signal,
+                });
+                const elapsed = Date.now() - started;
+                const requestId = response.headers?.get?.('X-Request-Id') ?? undefined;
+                if (response.ok) {
+                    // NEVER the body — see the header of this file.
+                    this.logger.debug(`${method} ${path} -> ${response.status} (${elapsed}ms)`, { requestId });
+                    const wrap = (parsed) => (options.raw
+                        ? {
+                            status: response.status,
+                            body: parsed,
+                            requestId,
+                            retryAfterMs: parseRetryAfterMs(response.headers?.get?.('Retry-After')),
+                        }
+                        : parsed);
+                    if (response.status === 204)
+                        return wrap(undefined);
+                    const text = await response.text();
+                    if (!text)
+                        return wrap(undefined);
+                    try {
+                        return wrap(JSON.parse(text));
+                    }
+                    catch {
+                        // A 200 whose body is not JSON is a SERVER problem. Reporting it as
+                        // a network error (which 1.x did) sends the integrator to look at
+                        // their connection.
+                        throw errorFromResponse({
+                            status: response.status,
+                            body: text,
+                            requestId,
+                            method,
+                            path,
+                            statusText: 'response body is not JSON',
+                        });
+                    }
+                }
+                const rawText = await response.text();
+                let parsed = rawText;
+                try {
+                    parsed = JSON.parse(rawText);
+                }
+                catch {
+                    /* keep the text */
+                }
+                const retryAfterMs = parseRetryAfterMs(response.headers?.get?.('Retry-After'));
+                lastError = errorFromResponse({
+                    status: response.status,
+                    statusText: response.statusText,
+                    body: parsed,
+                    requestId,
+                    retryAfterMs,
+                    method,
+                    path,
+                });
+                this.logger.debug(`${method} ${path} -> ${response.status} ${lastError.code ?? ''} (${elapsed}ms)`, { requestId });
+            }
+            catch (err) {
+                if (err instanceof ConsenteraError) {
+                    if (!err.retryable)
+                        throw err;
+                    lastError = err;
+                }
+                else if (timedOut) {
+                    lastError = timeoutError(`${method} ${path} timed out after ${timeoutMs}ms`, err);
+                }
+                else if (options.signal?.aborted) {
+                    throw cancelledError(`${method} ${path} cancelled`, err);
+                }
+                else {
+                    lastError = networkError(`${method} ${path}: ${err?.message ?? 'network error'}`, err);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', onCallerAbort);
+            }
+            if (!lastError.retryable || attempt === policy.attempts - 1)
+                throw lastError;
+            if (policy.maxRetryAfterMs !== undefined && lastError.retryAfterMs !== undefined &&
+                lastError.retryAfterMs > policy.maxRetryAfterMs)
+                throw lastError;
+            const wait = lastError.retryAfterMs ?? backoffMs(attempt, policy);
+            this.logger.debug(`${method} ${path} retry ${attempt + 1}/${policy.attempts - 1} in ${wait}ms (${lastError.code ?? lastError.kind})`);
+            await sleep(wait, options.signal);
+        }
+        /* istanbul ignore next — the loop always throws on its last attempt. */
+        throw lastError ?? networkError(`${method} ${path} failed`);
+    }
+}
+
+/**
+ * Consentera Consent SDK — the consent popup, and the ONE message it listens for.
+ *
+ * ─── WHAT /collect ACTUALLY POSTS (SDK register WEB-035) ────────────────────
+ *
+ * After a decision, an EMBEDDED /collect page (window.parent !== window) posts
+ * exactly one message to its parent. That is decisionMessage() in
+ * consentera-ui/src/app/collect/[sessionId]/decision-message.ts, posted at
+ * page.tsx:1535-1545 (grant) and :1670-1680 (decline) on the served commit
+ * 4fda7e3d05:
+ *
+ *   { type: 'consentera:submitted' | 'consentera:declined',
+ *     session_id, artifact_id, status: 'granted'|'partial'|'denied', pending,
+ *     sessionId, redirectUrl, choices }          // the three legacy fields
+ *
+ * `choices` rides only on a submit. The TARGET ORIGIN is the origin of the
+ * session's callback_url (redirect-trust.ts parentOriginFor), so the page that
+ * frames /collect must be on the callback's origin or the browser drops the
+ * message without a word.
+ *
+ * Before this file the SDK opened the page with window.open and listened for
+ * `consentera:consent-result`, a type the platform has never sent. That was
+ * wrong twice over, because a window.open popup is a TOP-LEVEL page. It posts
+ * nothing: it navigates to the callback instead. The storage fallback polled
+ * sessionStorage, which a separate window does not share. So the promise could
+ * end only when the window closed, as `unverified`, or at the 10-minute
+ * timeout.
+ *
+ * So the popup is now what the platform's own website popup is: a dialog on
+ * THIS page with /collect in an iframe (consentera-ui/src/lib/onboarding/
+ * website-consent.ts, createDialog). It is the presentation in which /collect
+ * reports the decision.
+ *
+ * ─── WHAT THE RESULT IS, AND WHAT IT IS NOT ────────────────────────────────
+ *
+ * The message comes from the platform's origin and from the frame this SDK
+ * opened (both are checked), so it is the platform page's report of the
+ * decision. It is not the consent record. The record is the artefact: confirm
+ * it with getArtifact(artifact_id, { sessionId }) through your proxy, or on
+ * your server, before you act on a grant.
+ */
+const TYPES = new Set(['consentera:submitted', 'consentera:declined']);
+const STATUSES = new Set(['granted', 'partial', 'denied']);
+function queryOf(url) {
+    if (typeof url !== 'string' || !url)
+        return null;
+    try {
+        return new URL(url, 'https://collect.invalid').searchParams;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The platform's own rule for a status the message did not carry
+ * (decision-message.ts decisionStatus): the redirect URL's status when it has
+ * one, else from the choices — none granted → denied, some denied → partial,
+ * else granted.
+ */
+function derivedStatus(q, choices) {
+    const fromUrl = q?.get('status');
+    if (fromUrl && STATUSES.has(fromUrl))
+        return fromUrl;
+    const values = Object.values(choices ?? {});
+    const granted = values.filter(Boolean).length;
+    if (granted === 0)
+        return 'denied';
+    if (granted < values.length)
+        return 'partial';
+    return 'granted';
+}
+/**
+ * Read a MessageEvent as /collect's decision — or null when it is not one, or
+ * not from where it must come from.
+ *
+ * Exported for a Data Fiduciary that frames consent_url itself: the same
+ * checks, one implementation.
+ *
+ *   origin    must equal the /collect origin (the consent_url's origin)
+ *   source    when given, must be the frame that was opened
+ *   type      consentera:submitted | consentera:declined
+ *   session   `session_id` (or the legacy `sessionId`) must be this session;
+ *             when both are present they must agree
+ */
+function readDecisionMessage(event, expected) {
+    if (!expected.origin || event.origin !== expected.origin)
+        return null;
+    if (expected.source !== undefined && event.source !== expected.source)
+        return null;
+    const data = event.data;
+    if (!data || typeof data !== 'object' || typeof data.type !== 'string' || !TYPES.has(data.type))
+        return null;
+    const snake = typeof data.session_id === 'string' && data.session_id ? data.session_id : undefined;
+    const legacy = typeof data.sessionId === 'string' && data.sessionId ? data.sessionId : undefined;
+    if (snake && legacy && snake !== legacy)
+        return null;
+    const sessionId = snake ?? legacy;
+    if (!sessionId || sessionId !== expected.sessionId)
+        return null;
+    const redirectUrl = typeof data.redirectUrl === 'string' && data.redirectUrl ? data.redirectUrl : undefined;
+    const q = queryOf(redirectUrl);
+    const choices = data.choices && typeof data.choices === 'object' ? data.choices : undefined;
+    const type = data.type;
+    // The platform's own value when it sent one; otherwise its own derivation.
+    // A decline carries no choices, so it derives `denied` unless the redirect
+    // URL says otherwise.
+    const status = typeof data.status === 'string' && STATUSES.has(data.status)
+        ? data.status
+        : derivedStatus(q, type === 'consentera:declined' ? undefined : choices);
+    const artifactId = typeof data.artifact_id === 'string' && data.artifact_id ? data.artifact_id : (q?.get('artifact_id') ?? '');
+    return {
+        outcome: 'decided',
+        type,
+        session_id: sessionId,
+        artifact_id: artifactId,
+        status,
+        pending: data.pending === true || q?.get('pending') === '1',
+        ...(redirectUrl ? { redirect_url: redirectUrl } : {}),
+        ...(choices ? { choices } : {}),
+    };
+}
+/**
+ * Refuse a callback that cannot deliver the decision to this page.
+ * Returns the refusal, or null when the callback is fine or unknown.
+ */
+function callbackOriginProblem(callbackUrl, pageOrigin) {
+    if (!callbackUrl)
+        return null;
+    let cb;
+    try {
+        cb = new URL(callbackUrl, pageOrigin);
+    }
+    catch {
+        return `the session's callback_url (${callbackUrl}) is not a URL`;
+    }
+    if (cb.protocol !== 'https:' && cb.protocol !== 'http:') {
+        return (`the session's callback_url is an app link (${cb.protocol}//…). /collect then posts its decision to its ` +
+            'own origin, which this page is not, so the popup would never hear it. Use redirectToConsent, or ' +
+            'create the session with a callback_url on this page’s origin.');
+    }
+    if (cb.origin !== pageOrigin) {
+        return (`/collect posts the decision to the callback's origin (${cb.origin}), and this page is ${pageOrigin}. ` +
+            'The browser drops a message addressed to another origin, so the popup would never hear it. ' +
+            'Create the session with a callback_url on this page’s origin.');
+    }
+    return null;
+}
+/**
+ * Open consent_url in a dialog on this page and resolve with the decision
+ * /collect posts, or `dismissed` when the person closes it.
+ */
+function openConsentDialog(session, options = {}) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        throw new Error('openConsentPopup can only be used in browser environments');
+    }
+    const problem = callbackOriginProblem(options.callbackUrl, window.location.origin);
+    if (problem) {
+        return Promise.reject(configError(`Consentera: ${problem}`, 'CALLBACK_ORIGIN_MISMATCH'));
+    }
+    let consentOrigin;
+    try {
+        consentOrigin = new URL(session.consent_url, window.location.href).origin;
+    }
+    catch {
+        return Promise.reject(configError('Consentera: consent_url is not a URL.', 'CONSENT_URL_INVALID'));
+    }
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;
+    const title = options.title ?? 'Your consent choices';
+    const host = options.container ?? document.body;
+    return new Promise((resolve, reject) => {
+        const previouslyFocused = document.activeElement;
+        const previousOverflow = document.documentElement.style.overflow;
+        const overlay = document.createElement('div');
+        overlay.dataset.consenteraPopup = 'true';
+        overlay.style.cssText =
+            'position:fixed;inset:0;z-index:2147483000;display:flex;align-items:center;justify-content:center;' +
+                'padding:12px;background:rgba(15,23,42,.6)';
+        const box = document.createElement('div');
+        box.setAttribute('role', 'dialog');
+        box.setAttribute('aria-modal', 'true');
+        box.setAttribute('aria-label', title);
+        box.style.cssText =
+            'display:flex;flex-direction:column;width:100%;max-width:680px;height:min(780px,100%);background:#fff;' +
+                'border-radius:14px;overflow:hidden;box-shadow:0 24px 64px rgba(0,0,0,.35)';
+        const head = document.createElement('div');
+        head.style.cssText = 'display:flex;justify-content:flex-end;padding:8px;border-bottom:1px solid #e5e7eb';
+        const close = document.createElement('button');
+        close.type = 'button';
+        close.textContent = 'Close';
+        close.setAttribute('aria-label', `Close — ${title}`);
+        close.style.cssText =
+            'font:inherit;font-size:14px;padding:8px 14px;min-height:40px;border:1px solid #d1d5db;border-radius:8px;' +
+                'background:#fff;color:#111827;cursor:pointer';
+        const frame = document.createElement('iframe');
+        frame.title = title;
+        frame.src = session.consent_url;
+        frame.style.cssText = 'flex:1;width:100%;border:0;background:#fff';
+        head.append(close);
+        box.append(head, frame);
+        overlay.append(box);
+        host.append(overlay);
+        document.documentElement.style.overflow = 'hidden';
+        close.focus();
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            window.removeEventListener('message', onMessage);
+            document.removeEventListener('keydown', onKey, true);
+            overlay.remove();
+            document.documentElement.style.overflow = previousOverflow;
+            if (previouslyFocused && typeof previouslyFocused.focus === 'function')
+                previouslyFocused.focus();
+            fn();
+        };
+        const dismiss = () => finish(() => resolve({ outcome: 'dismissed', session_id: session.consent_session_id }));
+        const onMessage = (event) => {
+            const decision = readDecisionMessage(event, {
+                origin: consentOrigin,
+                sessionId: session.consent_session_id,
+                source: frame.contentWindow,
+            });
+            if (decision)
+                finish(() => resolve(decision));
+        };
+        const onKey = (event) => {
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                dismiss();
+            }
+        };
+        const deadline = setTimeout(() => finish(() => reject(new Error(`Consentera: the consent dialog had no decision within ${timeoutMs}ms. The session is still ` +
+            'valid — verify it server-side, or reopen it.'))), timeoutMs);
+        close.addEventListener('click', dismiss);
+        window.addEventListener('message', onMessage);
+        document.addEventListener('keydown', onKey, true);
+    });
+}
+
+/**
+ * ConsentEra Consent SDK — Session Management
+ * Create consent sessions, retrieve artifacts, handle redirect flows
+ */
+class ConsentSession {
+    request;
+    config;
+    logger;
+    /**
+     * The callback_url each session was created with, in this page. The popup
+     * needs it: /collect posts its decision to that URL's origin.
+     */
+    callbackUrls = new Map();
+    constructor(request, config, logger) {
+        this.request = request;
+        this.config = config;
+        this.logger = logger;
+    }
+    /**
+     * Create a new consent session for consent collection.
+     * Returns a session with consent_url for redirect/popup flow.
+     *
+     *   createSession({
+     *     data_principal: { email: 'riya@example.in' },
+     *     notice_internal_name: 'bnb_consent_v2',
+     *     age: { date_of_birth: '1998-04-12' },
+     *   })
+     *
+     * Identity is `data_principal` — the identifiers, keyed by THIS
+     * ORGANISATION'S locked integration key — or `data_principal_id`; the type of
+     * {@link CreateSessionRequest} requires at least one of the two, because the
+     * API refuses a request with neither.
+     *
+     * ─── THIS IS THE U58 WIRE, AND THERE IS NO OVERLAP WINDOW ────────────────
+     *
+     * `data_principal_ref`, `data_principal_ref_type`, `data_principal_details`,
+     * `locale_pref`, `notice_language`, `template_language` and `purpose_ids` are
+     * DELETED from the API's request struct. This SDK version talks to an API
+     * carrying U58 and to no other, in both directions:
+     *
+     *   old SDK -> new API   the identifiers are dropped, then 400
+     *   new SDK -> old API   the identifiers are dropped, then 400
+     *
+     * EVERY FIELD THIS BUILDS IS A FIELD THE API DECODES. The handler decodes
+     * with a plain `json.Decoder` and NO `DisallowUnknownFields` — on BOTH wires
+     * — so a key it does not know is dropped in silence rather than refused. That
+     * is why the two wires cannot be mixed and why the failure above is a 400
+     * about a MISSING identifier rather than about the field you sent. Check a
+     * field against the request struct before adding it.
+     */
+    async createSession(params, options) {
+        // THE CALLBACK STATE, minted here and nowhere else — before the call,
+        // because callback_url is a REQUEST field. See withCallbackState.
+        const requestedCallback = params.callback_url || this.config.callbackUrl;
+        const state = requestedCallback ? newCallbackState() : undefined;
+        const body = {
+            ui_mode: params.ui_mode || 'redirect',
+            callback_url: requestedCallback && state ? withCallbackState(requestedCallback, state) : undefined,
+        };
+        // The identifiers, by the tenant's own field names. Sent as-is: this SDK
+        // does not know the key and must not guess at it — a field outside the key
+        // is the API's 400 UNKNOWN_IDENTIFIER_FIELD, which can name the allowed
+        // fields, and a guess here could only turn that into silence.
+        if (params.data_principal && Object.keys(params.data_principal).length > 0) {
+            body.data_principal = params.data_principal;
+        }
+        if (params.data_principal_id)
+            body.data_principal_id = params.data_principal_id;
+        if (params.age && params.age.date_of_birth) {
+            body.age = { date_of_birth: params.age.date_of_birth };
+        }
+        // ONE language field. Only sent when a language was actually asked for: it
+        // goes to the FRONT of the server's locale fallback chain, AHEAD of the
+        // tenant's own default, so a hard-coded fallback here would override that
+        // default for every caller who never set one.
+        const language = params.language || this.config.language;
+        if (language)
+            body.language = language;
+        if (params.session_ref)
+            body.session_ref = params.session_ref;
+        if (params.notice_internal_name)
+            body.notice_internal_name = params.notice_internal_name;
+        if (params.notice_version_number !== undefined) {
+            body.notice_version_number = params.notice_version_number;
+        }
+        if (params.customer_token)
+            body.customer_token = params.customer_token;
+        // The guardian channel — top-level, and never inside data_principal, which
+        // holds the identifiers of the person the consent is ABOUT. Either, not
+        // both: one invitation goes to one address.
+        if (params.guardian_email)
+            body.guardian_email = params.guardian_email;
+        if (params.guardian_phone)
+            body.guardian_phone = params.guardian_phone;
+        if (params.guardian_relationship) {
+            body.guardian_relationship = params.guardian_relationship;
+        }
+        const response = await this.request('POST', '/consent/sessions', body, undefined, {
+            // ONE key for this logical session creation, reused across the
+            // transport's own retries so a retried create cannot mint two sessions
+            // for one person.
+            idempotencyKey: options?.idempotencyKey ?? newRequestId(),
+            signal: options?.signal,
+            timeoutMs: options?.timeoutMs,
+        });
+        // THE STORED HALF OF THE CALLBACK HANDSHAKE. CallbackHandler.parseCallback
+        // reads this record back, compares the session id and the STATE this SDK
+        // put on callback_url, and refuses anything that does not match. It is not
+        // the server's challengeNonce: that is the hosted page's credential, it
+        // rides consent_url, and the platform's return never carries it — storing
+        // it here is what made every genuine web redirect come back `unverified`.
+        const persisted = writeStored('session', storageKeys.session(response.consent_session_id), JSON.stringify({
+            session_id: response.consent_session_id,
+            ...(state ? { state } : {}),
+            notice_hash: response.notice_hash,
+            // The person this session is ABOUT. The callback handler compares it
+            // with the artifact's data_principal_id, because the platform's 200
+            // artifact read does not check the session (walk finding F077).
+            data_principal_id: response.data_principal_id,
+            created_at: new Date().toISOString(),
+        }));
+        if (!persisted) {
+            // Storage is blocked; the handshake now lives in memory and will not
+            // survive the redirect. Say so, because the callback will come back
+            // `unverified` and the integrator needs to know why.
+            this.logger.warn('Consentera: browser storage is unavailable, so the callback handshake cannot survive a ' +
+                'page navigation. Use ui_mode "popup", or verify the artifact server-side.');
+        }
+        if (typeof body.callback_url === 'string' && body.callback_url) {
+            this.callbackUrls.set(response.consent_session_id, body.callback_url);
+        }
+        this.logger.info('Consent session created', {
+            session_id: response.consent_session_id,
+        });
+        return response;
+    }
+    /**
+     * Redirect the user to the ConsentEra consent collection widget.
+     * Only works in browser environments.
+     */
+    redirectToConsent(session) {
+        if (typeof window === 'undefined') {
+            throw new Error('redirectToConsent can only be used in browser environments');
+        }
+        window.location.href = session.consent_url;
+    }
+    /**
+     * Open the consent page in a dialog ON THIS PAGE and resolve with the
+     * decision it reports, or `{ outcome: 'dismissed' }` when the person closes
+     * it. Rejects after `timeoutMs` (default 10 minutes).
+     *
+     *   const r = await consent.openConsentPopup(session);
+     *   if (r.outcome === 'decided') confirmOnServer(r.session_id, r.artifact_id);
+     *
+     * It listens for the ONE message /collect posts, `consentera:submitted` /
+     * `consentera:declined`, from the /collect origin and the frame it opened.
+     * See consent/consentPopup.ts for the wire and for why this is a dialog and
+     * not window.open (a top-level /collect posts nothing) (SDK register WEB-035).
+     *
+     * THIS PAGE MUST BE ON THE CALLBACK'S ORIGIN: /collect addresses the message
+     * to the session's callback_url origin. A session created by this SDK is
+     * checked before anything opens (`CALLBACK_ORIGIN_MISMATCH`); pass
+     * `callbackUrl` when your server set a different one. The page must also be
+     * in your integration client's Allowed Domains, or the platform refuses to
+     * be framed (frame-ancestors).
+     *
+     * The result is what the platform page reported, not the consent record:
+     * confirm the artefact before acting on a grant.
+     */
+    openConsentPopup(session, options) {
+        return openConsentDialog(session, {
+            ...options,
+            callbackUrl: options?.callbackUrl ?? this.callbackUrls.get(session.consent_session_id) ?? this.config.callbackUrl,
+        });
+    }
+    /**
+     * Read a consent artifact.
+     *
+     *   const r = await consent.getArtifact(artifactId, { sessionId });
+     *   if (r.state === 'pending') retryIn(r.retryAfterMs);   // 202: recorded, still being written
+     *   else use(r.artifact);                                  // 200
+     *
+     * PASS THE SESSION ID the callback gave you. The platform answers 202 for a
+     * consent whose artifact is still being written only when it can see which
+     * session is asking; without it that consent is a 404, the same answer a
+     * guessed id gets. A 404 WITH a session id means the artifact was never
+     * issued for that session: it throws a ConsenteraNotFoundError.
+     *
+     * A 200 is not proof the artifact belongs to your session — the platform
+     * checks the session only while the artifact is missing (walk finding F077).
+     * Compare `artifact.data_principal_id` with your session's.
+     */
+    async getArtifact(artifactId, options) {
+        return readArtifact(this.request, artifactId, options);
+    }
+}
+/**
+ * A fresh per-attempt callback state: 32 random bytes, hex. From the platform
+ * CSPRNG only — there is no Math.random fallback, because a guessable state is
+ * a forgeable callback. (`newRequestId` may fall back; this must not.)
+ */
+function newCallbackState() {
+    const c = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
+    if (!c || typeof c.getRandomValues !== 'function') {
+        throw configError('Consentera: no crypto.getRandomValues here, so no unguessable callback state can be made. ' +
+            'This SDK will not fall back to Math.random for it.', 'NO_SECURE_RANDOM');
+    }
+    return Array.from(c.getRandomValues(new Uint8Array(32)), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * callback_url with this SDK's `state` added to its query.
+ *
+ * WHY IT SURVIVES THE ROUND TRIP — a platform fact, read on pre-main
+ * 35cd853ac7: addRedirectParams appends session_id/artifact_id to callback_url
+ * with `&` when it already has a `?` (redirect_params.go:17), and
+ * setRedirectParam then parses, SETS status / pending / sig and re-encodes —
+ * every other key, `state` included, is kept. The mobile SDKs have bound their
+ * callbacks this way since 2.0.0.
+ *
+ * `state` IS RESERVED. A callback_url that already carries one is refused
+ * rather than overwritten: overwriting would silently break the Data
+ * Fiduciary's own use of it, and keeping theirs would bind nothing.
+ */
+function withCallbackState(callbackUrl, state) {
+    let u;
+    try {
+        u = new URL(callbackUrl);
+    }
+    catch {
+        throw configError(`Consentera: callback_url must be an absolute URL (the platform refuses anything else); got ${JSON.stringify(callbackUrl.slice(0, 80))}`, 'INVALID_CALLBACK_URL');
+    }
+    if (u.searchParams.has('state')) {
+        throw configError('Consentera: callback_url already carries a `state` parameter. This SDK puts its own callback ' +
+            'state there to bind the return to this browser; use a different parameter name for yours.', 'CALLBACK_STATE_RESERVED');
+    }
+    u.searchParams.set('state', state);
+    return u.toString();
+}
+
+/**
+ * ConsentEra Consent SDK — Context Helpers
+ * Build client context and affirmative action payloads
+ */
+/** Strip the query and fragment: the parts that carry the host's own data. */
+function pagePath(href) {
+    try {
+        const u = new URL(href);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build client context from the current browser environment.
+ *
+ * @param sessionId optional consent session to correlate against
+ * @param mode      how much to collect; see {@link ContextMode}. Default `minimal`.
+ */
+function buildClientContext(sessionId, mode = 'minimal') {
+    if (mode === 'none')
+        return undefined;
+    if (typeof window === 'undefined') {
+        return {
+            user_agent: 'Consentera SDK (SSR)',
+            platform: 'web',
+        };
+    }
+    const ua = navigator.userAgent;
+    let browserName = 'Unknown';
+    let browserVersion = '';
+    let osName = 'Unknown';
+    let osVersion = '';
+    let deviceType = 'desktop';
+    // Browser detection
+    if (ua.includes('Chrome') && !ua.includes('Edg')) {
+        browserName = 'Chrome';
+        browserVersion = ua.match(/Chrome\/([\d.]+)/)?.[1] || '';
+    }
+    else if (ua.includes('Safari') && !ua.includes('Chrome')) {
+        browserName = 'Safari';
+        browserVersion = ua.match(/Version\/([\d.]+)/)?.[1] || '';
+    }
+    else if (ua.includes('Firefox')) {
+        browserName = 'Firefox';
+        browserVersion = ua.match(/Firefox\/([\d.]+)/)?.[1] || '';
+    }
+    else if (ua.includes('Edg')) {
+        browserName = 'Edge';
+        browserVersion = ua.match(/Edg\/([\d.]+)/)?.[1] || '';
+    }
+    // OS detection
+    if (ua.includes('Windows')) {
+        osName = 'Windows';
+        osVersion = ua.match(/Windows NT ([\d.]+)/)?.[1] || '';
+    }
+    else if (ua.includes('Mac OS X')) {
+        osName = 'macOS';
+        osVersion = ua.match(/Mac OS X ([\d_.]+)/)?.[1]?.replace(/_/g, '.') || '';
+    }
+    else if (ua.includes('Android')) {
+        osName = 'Android';
+        osVersion = ua.match(/Android ([\d.]+)/)?.[1] || '';
+    }
+    else if (ua.includes('iPhone') || ua.includes('iPad')) {
+        osName = 'iOS';
+        osVersion = ua.match(/OS ([\d_]+)/)?.[1]?.replace(/_/g, '.') || '';
+    }
+    else if (ua.includes('Linux')) {
+        osName = 'Linux';
+    }
+    // Device type
+    if (/Mobi|Android.*Mobile|iPhone/.test(ua)) {
+        deviceType = 'mobile';
+    }
+    else if (/iPad|Android(?!.*Mobile)|Tablet/.test(ua)) {
+        deviceType = 'tablet';
+    }
+    const minimal = {
+        platform: 'web',
+        device_type: deviceType,
+        browser_name: browserName,
+        os_name: osName,
+        session_id: sessionId,
+    };
+    if (mode === 'minimal')
+        return minimal;
+    return {
+        ...minimal,
+        user_agent: ua,
+        screen_resolution: `${window.screen.width}x${window.screen.height}`,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        browser_version: browserVersion,
+        os_version: osVersion,
+        page_url: pagePath(window.location.href),
+        referrer: document.referrer ? pagePath(document.referrer) : undefined,
+    };
+}
+/**
+ * Build an affirmative action payload.
+ */
+function buildAffirmativeAction(uiEventId, type = 'button') {
+    return {
+        type,
+        ui_event_id: uiEventId,
+        captured_at: new Date().toISOString(),
+    };
+}
+/**
+ * Turn a {@link PrincipalRef} into the request-body fields that name the
+ * person. Sends exactly ONE of the two keys, never both and never an empty
+ * object.
+ *
+ * NEVER BOTH, and that is not tidiness: the API refuses a request carrying
+ * `data_principal_ref` even when `data_principal_id` is also present, for the
+ * stated reason that two fields naming a person can disagree and the caller
+ * would never learn which one the answer was about. Sending one key keeps this
+ * SDK on the right side of that rule by construction.
+ */
+function principalBody(who) {
+    if ('data_principal_id' in who && who.data_principal_id) {
+        return { data_principal_id: who.data_principal_id };
+    }
+    const ids = who.data_principal_identifiers;
+    if (!ids || Object.keys(ids).length === 0) {
+        // The identifier FIELDS are the tenant's own locked integration key, which
+        // this SDK cannot know and does not enumerate (F015): a message listing a
+        // fixed five would name fields this organisation may not use and omit ones
+        // it does. The SERVER lists the key's actual fields in its
+        // UNKNOWN_IDENTIFIER_FIELD refusal; here we only say WHERE the fields come
+        // from.
+        throw new Error('Consentera: name the Data Principal with data_principal_id, or with ' +
+            'data_principal_identifiers carrying the identifier fields of this ' +
+            'organisation\'s integration key. data_principal_ref is refused by the API.');
+    }
+    return { data_principal_identifiers: ids };
+}
+
+/**
+ * ConsentEra Consent SDK — Consent Validation
+ * Validate consent status for single or multiple purposes
+ */
+class ConsentValidator {
+    request;
+    logger;
+    constructor(request, logger) {
+        this.request = request;
+        this.logger = logger;
+    }
+    /**
+     * Validate consent for a single purpose.
+     * Returns ALLOW or DENY with reason code.
+     *
+     *   check({ data_principal_identifiers: { email: 'riya@example.in' } },
+     *         'product_analytics')
+     *   check({ data_principal_id: '…' }, 'product_analytics')
+     *
+     * ─── data_principal_ref IS REFUSED OUTRIGHT ────────────────────────────
+     *
+     * Owner ruling 2026-09-21, no transition period
+     * (consent/lifecycle_identity.go:8-11). A request carrying it is answered
+     * 400 VALIDATION_ERROR whose message begins `DATA_PRINCIPAL_REF_REFUSED`,
+     * and the refusal fires even when `data_principal_id` is also present.
+     *
+     * NAME PEOPLE BY THE ORGANISATION'S LOCKED KEY FIELDS (F015): the mobile atom
+     * is `mobile` on this road AND on create — `phone` is refused by name. See
+     * {@link DataPrincipalIdentifiers}.
+     */
+    async check(who, purposeCode, options) {
+        const body = { ...principalBody(who), purpose_code: purposeCode };
+        const response = await this.request('POST', '/consent/validate', body, undefined, { signal: options?.signal, timeoutMs: options?.timeoutMs });
+        // Never log the identifiers themselves — they are raw PII, and this line
+        // used to carry the opaque handle verbatim. Log WHICH way the person was
+        // named, which is what a support question actually needs.
+        this.logger.debug('Consent validated', {
+            namedBy: 'data_principal_id' in who ? 'data_principal_id' : 'data_principal_identifiers',
+            purpose: purposeCode,
+            decision: response.decision,
+        });
+        return response;
+    }
+    /**
+     * Validate consent for multiple purposes at once.
+     * Returns results map indexed by purpose code.
+     *
+     * `data_principal_ref` AND `data_principal_refs` are both refused here
+     * (consent/validate.go:249,257).
+     */
+    async checkBulk(who, purposeCodes, options) {
+        const body = {
+            ...principalBody(who),
+            purpose_codes: purposeCodes,
+        };
+        const response = await this.request('POST', '/consent/validate/bulk', body, undefined, { signal: options?.signal, timeoutMs: options?.timeoutMs });
+        this.logger.debug('Bulk consent validated', {
+            namedBy: 'data_principal_id' in who ? 'data_principal_id' : 'data_principal_identifiers',
+            purposes: purposeCodes.length,
+            results: response.results?.map((r) => `${r.purpose_code}:${r.decision}`),
+        });
+        return response;
+    }
+    /**
+     * Quick boolean check — is this purpose allowed?
+     *
+     *   isAllowed({ data_principal_identifiers: { email: 'riya@example.in' } },
+     *             'product_analytics')
+     */
+    async isAllowed(who, purposeCode, options) {
+        const result = await this.check(who, purposeCode, options);
+        return result.decision === 'ALLOW';
+    }
+    /**
+     * Check multiple purposes and return a map of purpose → boolean.
+     */
+    async areAllowed(who, purposeCodes) {
+        const response = await this.checkBulk(who, purposeCodes);
+        const map = new Map();
+        for (const result of response.results || []) {
+            // purpose_code is omitempty on the wire; a result without one is keyed
+            // by its purpose_id rather than dropped under an `undefined` key.
+            map.set(result.purpose_code ?? result.purpose_id, result.decision === 'ALLOW');
+        }
+        return map;
+    }
+}
+
+/**
+ * ConsentEra Consent SDK — Consent Lifecycle Manager
+ * Update, withdraw, and renew consent decisions
+ */
+class ConsentManager {
+    request;
+    logger;
+    /**
+     * Called after every successful consent mutation with
+     * {dataPrincipalId, changes:[{purpose_id,status}], source}. The client wires this
+     * to its EventEmitter as the public `consent.changed` event — downstream
+     * code (tracker gates, Consent Mode bridges) subscribes instead of polling.
+     */
+    onChanged;
+    contextMode;
+    constructor(request, logger, options) {
+        this.request = request;
+        this.logger = logger;
+        this.contextMode = options?.contextMode ?? 'minimal';
+    }
+    /** The client context for a mutation, at whatever detail the host allowed. */
+    context() {
+        return buildClientContext(undefined, this.contextMode);
+    }
+    /** One key per logical operation, reused by the transport across its retries. */
+    mutation(options) {
+        return {
+            idempotencyKey: options?.idempotencyKey ?? newRequestId(),
+            signal: options?.signal,
+            timeoutMs: options?.timeoutMs,
+        };
+    }
+    emitChanged(dataPrincipalId, changes, source) {
+        try {
+            this.onChanged?.({ dataPrincipalId, changes, source });
+        }
+        catch (e) {
+            this.logger.warn('consent.changed listener threw', { error: String(e) });
+        }
+    }
+    // =========================================================================
+    // Consent Update
+    // =========================================================================
+    /**
+     * Get the current consent context for a data principal.
+     * Returns all consents with their current status.
+     *
+     * ─── THIS ROAD TAKES THE ID AND NOTHING ELSE ──────────────────────────
+     *
+     * It is a GET, so the only place an identifier could go is the query string,
+     * and the platform refuses to put one there: a query string is written
+     * VERBATIM into the access log of every hop that sees the request line, kept
+     * in browser history, and sent onward in the Referer header
+     * (consent/lifecycle_identity.go:120-133). So this road was RESTRICTED to
+     * `data_principal_id`, not converted to identifiers the way the POST roads
+     * were — `?data_principal_ref=` is refused `DATA_PRINCIPAL_REF_REFUSED`
+     * even when `data_principal_id` is also present.
+     *
+     * IF YOU HOLD AN IDENTIFIER AND NOT THE ID: resolve it once with
+     * `validate.check({ data_principal_identifiers: … }, purpose)` and read
+     * `data_principal_id` off that response, then call this with the id.
+     *
+     * The parameter used to be `dataPrincipalIdOrRef` and guessed by UUID shape:
+     * anything not UUID-shaped went out as `data_principal_ref`, which this road
+     * now refuses. The guess is gone — a non-UUID is rejected here, by name.
+     */
+    async getUpdateContext(dataPrincipalId, queryParams) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(dataPrincipalId)) {
+            throw new Error('Consentera: getUpdateContext takes a data_principal_id (a uuid), not an identifier. ' +
+                'This road deliberately accepts no identifiers — a query string is written verbatim ' +
+                'into access logs, browser history and Referer headers. Resolve the id once with ' +
+                'validate.check({ data_principal_identifiers: … }, purpose) and pass the ' +
+                'data_principal_id from its response.');
+        }
+        const params = { data_principal_id: dataPrincipalId };
+        if (queryParams?.language_code)
+            params.language_code = queryParams.language_code;
+        return this.request('GET', '/consent/update/context', undefined, params);
+    }
+    /**
+     * Update consent decisions for a data principal.
+     * Pass an array of purpose updates (grant or deny).
+     */
+    async update(dataPrincipalId, updates, context, uiEventId = 'btn_save_preferences', options) {
+        const body = {
+            data_principal_id: dataPrincipalId,
+            notice_version_id: context.noticeVersionId,
+            notice_hash: context.noticeHash,
+            language_code: context.languageCode || 'en',
+            updates,
+            affirmative_action: buildAffirmativeAction(uiEventId),
+            client_context: this.context(),
+        };
+        await this.request('POST', '/consent/update', body, undefined, this.mutation(options));
+        this.logger.info('Consent updated', {
+            dataPrincipal: dataPrincipalId,
+            updates: updates.map((u) => `${u.purpose_id}:${u.new_status}`),
+        });
+        this.emitChanged(dataPrincipalId, updates.map((u) => ({ purpose_id: u.purpose_id, status: u.new_status })), 'update');
+    }
+    /**
+     * Convenience: Grant specific purposes.
+     */
+    async grant(dataPrincipalId, purposeIds, context, uiEventId = 'btn_grant_consent', options) {
+        const updates = purposeIds.map((id) => ({
+            purpose_id: id,
+            new_status: 'granted',
+        }));
+        return this.update(dataPrincipalId, updates, context, uiEventId, options);
+    }
+    /**
+     * Convenience: Deny specific purposes.
+     */
+    async deny(dataPrincipalId, purposeIds, context, uiEventId = 'btn_deny_consent', options) {
+        const updates = purposeIds.map((id) => ({
+            purpose_id: id,
+            new_status: 'denied',
+        }));
+        return this.update(dataPrincipalId, updates, context, uiEventId, options);
+    }
+    // =========================================================================
+    // Consent Withdrawal
+    // =========================================================================
+    /**
+     * Get the withdrawal context — which consents can be withdrawn.
+     */
+    async getWithdrawalContext(dataPrincipalId) {
+        return this.request('GET', '/consent/withdrawal/context', undefined, { data_principal_id: dataPrincipalId });
+    }
+    /**
+     * Withdraw consent for specific purposes.
+     */
+    async withdraw(dataPrincipalId, purposeIds, reason, uiEventId = 'btn_withdraw_consent', options) {
+        const body = {
+            data_principal_id: dataPrincipalId,
+            purposes: purposeIds,
+            reason,
+            affirmative_action: buildAffirmativeAction(uiEventId),
+            client_context: this.context(),
+        };
+        await this.request('POST', '/consent/withdraw', body, undefined, this.mutation(options));
+        this.logger.info('Consent withdrawn', {
+            dataPrincipal: dataPrincipalId,
+            purposes: purposeIds,
+        });
+        this.emitChanged(dataPrincipalId, purposeIds.map((p) => ({ purpose_id: p, status: 'withdrawn' })), 'withdraw');
+    }
+    /**
+     * Bulk withdraw consent for multiple purposes.
+     */
+    async withdrawBulk(dataPrincipalId, purposeIds, reason, uiEventId = 'btn_withdraw_all', options) {
+        const body = {
+            data_principal_id: dataPrincipalId,
+            purposes: purposeIds,
+            reason,
+            affirmative_action: buildAffirmativeAction(uiEventId),
+            client_context: this.context(),
+        };
+        await this.request('POST', '/consent/withdraw/bulk', body, undefined, this.mutation(options));
+        this.logger.info('Bulk consent withdrawn', {
+            dataPrincipal: dataPrincipalId,
+            purposes: purposeIds.length,
+        });
+        this.emitChanged(dataPrincipalId, purposeIds.map((p) => ({ purpose_id: p, status: 'withdrawn' })), 'withdraw_bulk');
+    }
+    /**
+     * Get withdrawal analytics (reasons, trends).
+     */
+    async getWithdrawalAnalytics() {
+        return this.request('GET', '/consent/withdrawal/analytics');
+    }
+    // =========================================================================
+    // Consent Renewal
+    // =========================================================================
+    /**
+     * Get the renewal context — which consents are expiring and need renewal.
+     */
+    async getRenewalContext(dataPrincipalId) {
+        return this.request('GET', '/consent/renewal/context', undefined, { data_principal_id: dataPrincipalId });
+    }
+    /**
+     * Renew consent for specific purposes.
+     */
+    async renew(dataPrincipalId, purposeIds, noticeHash, uiEventId = 'btn_renew_consent', options) {
+        const body = {
+            data_principal_id: dataPrincipalId,
+            purpose_ids: purposeIds,
+            notice_hash: noticeHash,
+            captured_at: buildAffirmativeAction(uiEventId).captured_at,
+            client_context: this.context(),
+        };
+        const response = await this.request('POST', '/consent/renew', body, undefined, { ...this.mutation(options), raw: true });
+        this.logger.info('Consent renewed', {
+            dataPrincipal: dataPrincipalId,
+            purposes: purposeIds,
+        });
+        this.emitChanged(dataPrincipalId, response.body.renewed_consents.map((p) => ({ purpose_id: p.purpose_id, status: 'granted' })), 'renew');
+        return response;
+    }
+    /**
+     * Bulk renew all expiring consents.
+     */
+    async renewBulk(dataPrincipalId, purposeIds, noticeHash, uiEventId = 'btn_renew_all', options) {
+        const body = {
+            data_principal_id: dataPrincipalId,
+            renewals: purposeIds.map(purpose_id => ({ purpose_id })),
+            notice_hash: noticeHash,
+            captured_at: buildAffirmativeAction(uiEventId).captured_at,
+            client_context: this.context(),
+        };
+        const response = await this.request('POST', '/consent/renew/bulk', body, undefined, { ...this.mutation(options), raw: true });
+        this.logger.info('Bulk consent renewed', {
+            dataPrincipal: dataPrincipalId,
+            purposes: response.body.success_count,
+        });
+        if (response.body.renewed_consents.length > 0) {
+            this.emitChanged(dataPrincipalId, response.body.renewed_consents.map((p) => ({
+                purpose_id: p.purpose_id, status: 'granted',
+            })), 'renew');
+        }
+        return response;
+    }
+}
+
+/**
+ * Consentera Consent SDK — Callback Handler
+ *
+ * ─── THIS ROAD FAILS CLOSED, AND BEFORE 2.0.0 IT DID NOT ───────────────────
+ *
+ * The 1.x handler read `session_id`, `artifact_id` and `status` out of
+ * `window.location.search`, looked up the stored session, logged
+ * "Callback verified against stored session" — and then verified NOTHING. It
+ * never parsed the record it had stored, never compared the nonce, never
+ * compared the notice hash, and returned `status: 'completed'` for any URL
+ * carrying an `artifact_id` (the `normalizeStatus` default). A link to
+ *
+ *     https://your-site.example/consent/done?session_id=x&artifact_id=y
+ *
+ * made `consent.handleCallback()` answer "completed" with no consent given.
+ * The log line said "verified" the whole time, which is why it survived review.
+ *
+ * What replaces it:
+ *
+ *   1. The stored record is PARSED. Its session id must equal the one in the
+ *      URL, and the `state` THIS SDK minted and put on callback_url at create
+ *      must come back on the return. A mismatch, an absence, or an
+ *      unparseable record is `unverified`.
+ *
+ *      IT IS THE SDK'S OWN STATE, NOT THE SERVER'S challengeNonce. Until the
+ *      callback-contract fix this compared the create response's
+ *      `challengeNonce` with a `nonce` on the return — and the platform's
+ *      return never carries one (collection.go:4225-4288 adds session_id,
+ *      artifact_id, status, pending and, when signed, sig). challengeNonce is
+ *      the hosted page's own credential: it rides consent_url
+ *      (`/collect/<id>?nonce=…`, :2010) and comes back on the page's submit
+ *      (:3509-3543). So every genuine web redirect came back `unverified`.
+ *      The state survives because the platform builds the return ON TOP of
+ *      callback_url's existing query — the mobile SDKs' binding, the same way.
+ *   2. `completed` is only ever reached by CONFIRMING THE ARTIFACT with the
+ *      platform — `GET /consent/artifacts/{id}` through the same road the rest
+ *      of the SDK uses, which in a browser is the Data Fiduciary's proxy. The
+ *      URL is a claim; the artifact is the evidence.
+ *   3. Everything else is `unverified`. There is no path from a query string to
+ *      `completed`.
+ *
+ * `parseCallback` is therefore ASYNC now. The synchronous
+ * {@link CallbackHandler.readCallbackParams} is kept for a caller that only
+ * wants to know what the URL says — it is named so that using it as a decision
+ * is visibly the wrong thing.
+ */
+const PLATFORM_CALLBACK_STATUSES = new Set(['granted', 'partial', 'denied']);
+/** Map the raw `status` query value onto the platform's vocabulary. Exact match: the server writes lowercase. */
+function claimedCallbackStatus(raw) {
+    return raw && PLATFORM_CALLBACK_STATUSES.has(raw) ? raw : 'unknown';
+}
+class CallbackHandler {
+    logger;
+    request;
+    options;
+    constructor(logger, request, options = {}) {
+        this.logger = logger;
+        this.request = request;
+        this.options = options;
+    }
+    /**
+     * Read the callback URL's claims. THIS IS NOT A DECISION — the values come
+     * from the address bar and anyone can type them. Use {@link parseCallback}.
+     */
+    readCallbackParams(searchParams) {
+        let params;
+        if (!searchParams) {
+            if (typeof window === 'undefined') {
+                throw new Error('readCallbackParams requires searchParams in non-browser environments');
+            }
+            params = new URLSearchParams(window.location.search);
+        }
+        else if (typeof searchParams === 'string') {
+            params = new URLSearchParams(searchParams);
+        }
+        else {
+            params = searchParams;
+        }
+        return {
+            session_id: params.get('session_id') || params.get('consent_session_id') || '',
+            artifact_id: params.get('artifact_id') || params.get('consent_artifact_id') || undefined,
+            raw_status: params.get('status') || '',
+            claimed_status: claimedCallbackStatus(params.get('status')),
+            pending: params.get('pending') === '1',
+            state: params.get('state') || undefined,
+            // The platform's HMAC over session|artifact|status; present only when the
+            // DF registered a callback_signing_secret (collection.go:4280-4288).
+            sig: params.get('sig') || undefined,
+            error: params.get('error') || undefined,
+        };
+    }
+    /**
+     * Verify a consent callback. Resolves `completed` ONLY when the stored
+     * session matches and the artifact was confirmed with the platform.
+     */
+    async parseCallback(searchParams) {
+        const claim = this.readCallbackParams(searchParams);
+        const base = {
+            session_id: claim.session_id,
+            artifact_id: claim.artifact_id,
+            claimed_status: claim.claimed_status,
+            claimed_pending: claim.pending,
+            status: 'unverified',
+        };
+        if (claim.error) {
+            return this.finish({ ...base, status: 'error', error: claim.error, reason: 'the platform returned an error' });
+        }
+        if (!claim.session_id) {
+            return this.finish({ ...base, status: 'unverified', reason: 'the callback names no session' });
+        }
+        // 1. The stored side of the handshake.
+        const raw = readStored('session', storageKeys.session(claim.session_id));
+        if (!raw) {
+            return this.finish({
+                ...base,
+                reason: 'no session was stored in this browser for that id — the session was created elsewhere, ' +
+                    'the tab was replaced, or the callback was not produced by this flow',
+            });
+        }
+        let stored;
+        try {
+            stored = JSON.parse(raw);
+        }
+        catch {
+            removeStored('session', storageKeys.session(claim.session_id));
+            return this.finish({ ...base, reason: 'the stored session record could not be parsed' });
+        }
+        removeStored('session', storageKeys.session(claim.session_id));
+        if (stored.session_id && stored.session_id !== claim.session_id) {
+            return this.finish({ ...base, reason: 'the stored session id does not match the callback' });
+        }
+        // The state is the anti-forgery binding: this SDK minted it at create, put
+        // it on callback_url, and only a real return trip to THIS browser carries
+        // it back. It is REQUIRED — a record without one cannot bind anything.
+        if (!stored.state) {
+            return this.finish({
+                ...base,
+                reason: 'the stored session has no callback state: it was created without a callback_url, or by an ' +
+                    'SDK version that bound the callback to the server challengeNonce (which the platform never ' +
+                    'returns). Read the consent back through your backend instead.',
+            });
+        }
+        if (!claim.state) {
+            return this.finish({ ...base, reason: 'the callback carries no state, and the session was created with one' });
+        }
+        if (!timingSafeEqual(stored.state, claim.state)) {
+            return this.finish({ ...base, reason: 'the callback state does not match the stored session' });
+        }
+        // 2. THE PLATFORM'S SIGNATURE, when it sent one.
+        //
+        // A `sig` on the URL means the DF registered a callback_signing_secret and
+        // the platform signed status + artifact with it. Ignoring it would make the
+        // signature decorative, so a sig that cannot be checked is `unverified` —
+        // the SDK does not fall back to "well, the state matched".
+        let signature = 'absent';
+        if (claim.sig) {
+            if (!this.options.verifySignature) {
+                return this.finish({
+                    ...base,
+                    signature: 'unverifiable',
+                    reason: 'the callback is signed and no verifier is configured. The signing key is your ' +
+                        'callback_signing_secret, which must not be in a browser: set ' +
+                        '`verifyCallbackSignature` to call your own server, which uses ' +
+                        'verifyCallbackSignature(secret, …) from this package.',
+                });
+            }
+            let ok = false;
+            try {
+                ok = await this.options.verifySignature({
+                    sessionId: claim.session_id,
+                    artifactId: claim.artifact_id ?? '',
+                    status: claim.raw_status,
+                    sig: claim.sig,
+                });
+            }
+            catch (err) {
+                return this.finish({
+                    ...base,
+                    signature: 'unverifiable',
+                    reason: `the signature verifier threw: ${String(err)}`,
+                });
+            }
+            if (!ok) {
+                return this.finish({ ...base, signature: 'invalid', reason: 'the callback signature did not verify' });
+            }
+            signature = 'verified';
+        }
+        // 3. The platform's vocabulary, exactly: granted | partial | denied
+        //    (collection.go:4094-4098). A denial is a real, verified outcome — no
+        //    artifact exists to confirm, and the state above proved the round trip.
+        //    Anything else did not come from the platform and goes nowhere near the
+        //    success road: before this, `completed`, `success`, a missing status or
+        //    any other value fell through to the artifact read and could come back
+        //    `completed`, while `expired`/`rejected`/`timeout` — which the platform
+        //    never sends — had branches of their own.
+        if (claim.claimed_status === 'denied') {
+            return this.finish({ ...base, status: 'denied', signature });
+        }
+        if (claim.claimed_status === 'unknown') {
+            return this.finish({
+                ...base,
+                signature,
+                reason: `the callback status ${JSON.stringify(claim.raw_status)} is not a status the platform issues ` +
+                    '(granted | partial | denied). Read the consent back through your backend.',
+            });
+        }
+        // 4. granted | partial: `completed` requires the artifact, from the
+        //    platform, not the URL. pending=1 (always set on the capture road)
+        //    means the first read may be a 202; confirmArtifact waits for it.
+        if (!claim.artifact_id) {
+            return this.finish({ ...base, signature, reason: 'the callback claims success but names no artifact' });
+        }
+        if (!this.request) {
+            return this.finish({
+                ...base,
+                signature,
+                reason: 'no transport available to confirm the artifact. Construct the handler through ' +
+                    'ConsentEraClient so it can call GET /consent/artifacts/{id}.',
+            });
+        }
+        return this.confirmArtifact(base, claim.artifact_id, claim.session_id, stored.data_principal_id, signature);
+    }
+    /**
+     * Read the artifact back FOR THIS SESSION, waiting while the platform says
+     * it is still being written.
+     *
+     * THE READ CARRIES ?session_id=, AND THAT DECIDES WHAT A 404 MEANS (WEB-033).
+     * With it the platform answers 202 + Retry-After while the projection is
+     * owed and 404 only when the id was never issued for this session (or will
+     * never be written). Until WEB-033 the read went out without it, so every
+     * absence was a 404, and this method polled every 404 as "maybe pending" — a
+     * forged artifact_id came back `pending` instead of refused.
+     *
+     *   200  the artifact. Then it must name the person this browser's session
+     *        was created for (below). Then `completed`.
+     *   202  recorded, not readable yet: wait Retry-After inside the budget, else
+     *        `pending`.
+     *   404  `unverified`, at once. Not polled: it is an answer, not a delay.
+     *   else `unverified` (403, network, timeout — unproven is unproven).
+     *
+     * THE BINDING IS THE PERSON, NOT A RESPONSE FIELD (WEB-034). This method used
+     * to compare `consent_session_id` on the artifact with the callback's
+     * session. The platform's artifact carries no such field (measured on
+     * setup.consentera.in, fixtures/platform-wire/artifact-read.200.*.json), so
+     * the check was skipped on every real response and bound nothing. What the
+     * artifact does carry is `data_principal_id`, and the session create
+     * returned the same field for the person the session is about. They must be
+     * equal. This matters because the platform's 200 path does not check the
+     * session (walk finding F077, measured: the same artifact read with a random
+     * session_id is still 200), so without it a callback carrying someone
+     * else's artifact_id would confirm.
+     */
+    async confirmArtifact(base, artifactId, sessionId, expectedPrincipal, signature) {
+        const budgetMs = this.options.artifactWaitMs ?? 15_000;
+        const deadline = Date.now() + budgetMs;
+        for (;;) {
+            let read;
+            try {
+                read = await readArtifact(this.request, artifactId, { sessionId });
+            }
+            catch (err) {
+                const detail = err instanceof ConsenteraError ? err.toString() : String(err);
+                if (err instanceof ConsenteraError && (err.status === 404 || err.kind === 'not_found')) {
+                    return this.finish({
+                        ...base,
+                        signature,
+                        reason: `the platform has no artifact ${artifactId} for session ${sessionId}: it was never ` +
+                            'issued for this session, or will never be written. A forged or mismatched ' +
+                            `artifact_id reads exactly like this. (${detail})`,
+                    });
+                }
+                // A 403, a network failure, anything else: unproven, so unverified.
+                return this.finish({ ...base, signature, reason: `the artifact could not be confirmed: ${detail}` });
+            }
+            if (read.state === 'recorded') {
+                const artifact = read.artifact;
+                if (artifact.artifact_id && artifact.artifact_id !== artifactId) {
+                    return this.finish({ ...base, signature, reason: 'the platform returned a different artifact than the one read' });
+                }
+                if (!expectedPrincipal) {
+                    return this.finish({
+                        ...base,
+                        signature,
+                        reason: 'the stored session names no data_principal_id, so the artifact cannot be tied to ' +
+                            'the person this session was created for. Create the session with this SDK version, ' +
+                            'or confirm the artifact server-side.',
+                    });
+                }
+                if (artifact.data_principal_id !== expectedPrincipal) {
+                    return this.finish({
+                        ...base,
+                        signature,
+                        reason: "the artifact names a different Data Principal from this browser's session — it is " +
+                            'not this consent',
+                    });
+                }
+                return this.finish({ ...base, status: 'completed', artifact, signature });
+            }
+            // 202: recorded, still being written.
+            const remaining = deadline - Date.now();
+            if (remaining <= 0 || read.retryAfterMs > remaining) {
+                return this.finish({
+                    ...base,
+                    status: 'pending',
+                    signature,
+                    retryAfterMs: read.retryAfterMs,
+                    reason: `the platform says the consent was recorded and its artifact is still being written ` +
+                        `(${read.pending.reason || 'pending'}); read it again in ${read.retryAfterMs}ms. ` +
+                        'This is NOT a failure and NOT a consent that did not happen.',
+                });
+            }
+            await new Promise((r) => setTimeout(r, read.retryAfterMs));
+        }
+    }
+    /** Is this page a consent callback? Says nothing about whether it is genuine. */
+    isCallback(searchParams) {
+        const params = new URLSearchParams(searchParams || (typeof window !== 'undefined' ? window.location.search : ''));
+        return params.has('session_id') || params.has('consent_session_id');
+    }
+    /** Record the outcome for the popup flow to collect, and log it. */
+    finish(result) {
+        if (result.session_id) {
+            writeStored('session', storageKeys.callback(result.session_id), JSON.stringify(result));
+        }
+        if (result.status === 'completed') {
+            this.logger.info('Consent callback verified', { session_id: result.session_id, status: result.status });
+        }
+        else if (result.status === 'pending') {
+            this.logger.info('Consent callback verified; artifact not readable yet', {
+                session_id: result.session_id,
+                status: result.status,
+            });
+        }
+        else {
+            this.logger.warn('Consent callback NOT verified', {
+                session_id: result.session_id,
+                status: result.status,
+                reason: result.reason,
+            });
+        }
+        return result;
+    }
+}
+/** Constant-time string compare, so a state cannot be guessed byte by byte. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+
+/**
+ * ConsentEra Consent SDK — DF Configuration Client
+ * Fetch Data Fiduciary configuration, purposes, and notice details
+ */
+class DFConfigClient {
+    request;
+    logger;
+    cachedConfig = null;
+    constructor(request, logger) {
+        this.request = request;
+        this.logger = logger;
+    }
+    /**
+     * Get the full DF configuration (tenant info, purposes, notices, branding).
+     * Results are cached for the lifetime of the client instance.
+     */
+    async getConfig(language) {
+        if (this.cachedConfig)
+            return this.cachedConfig;
+        const params = {};
+        if (language)
+            params.language_code = language;
+        const config = await this.request('GET', '/df/config', undefined, params, 
+        // The DF read roads are openable by a public site key (route membership,
+        // not the four legacy permission names — see README). Marking the road
+        // 'public' is what stops the transport demanding a secret / proxy for a
+        // browser call that legitimately carries only the site key.
+        { road: 'public' });
+        this.cachedConfig = config;
+        this.logger.info('DF config loaded', {
+            tenant: config.tenant_name,
+            purposes: config.purposes?.length,
+        });
+        return config;
+    }
+    /**
+     * Get all purposes configured for this DF.
+     */
+    async getPurposes() {
+        const response = await this.request('GET', '/df/purposes', undefined, undefined, { road: 'public' });
+        return Array.isArray(response) ? response : response.purposes || [];
+    }
+    /**
+     * Get purposes associated with a specific notice.
+     * This returns the ordered list of purposes as they appear in the notice.
+     */
+    async getNoticePurposes(noticeInternalName, language) {
+        const params = {};
+        if (noticeInternalName)
+            params.notice_internal_name = noticeInternalName;
+        if (language)
+            params.language_code = language;
+        return this.request('GET', '/df/notice/purposes', undefined, params, { road: 'public' });
+    }
+    /**
+     * Get the pre-rendered HTML+CSS snapshot for a notice, including purpose snapshot.
+     * Use this instead of getConfig() for bootstrapping notice-based consent UIs.
+     *
+     * @param noticeName - internal_name of the notice (required)
+     * @param noticeLanguage - language of the notice content (default: tenant primary language)
+     * @param templateLanguage - language for widget UI labels (optional)
+     */
+    async getNoticeTemplate(noticeName, noticeLanguage, templateLanguage) {
+        const params = { notice: noticeName };
+        if (noticeLanguage)
+            params.notice_language = noticeLanguage;
+        if (templateLanguage)
+            params.template_language = templateLanguage;
+        const response = await this.request('GET', '/df/notice/template', undefined, params, { road: 'public' });
+        this.logger.info('Notice template loaded', { notice: noticeName, language: noticeLanguage });
+        // The endpoint wraps in { data: ... }
+        return response.data ?? response;
+    }
+    /**
+     * Get the widget template for a consent SESSION's collection UI.
+     *
+     * THE ROUTE CHANGED IN 2.0.0, because the old one did not exist. This called
+     * GET /df/widget-template, which is a 404 — there is no such platform route.
+     * The real widget template is session-scoped: GET
+     * /consent/sessions/{id}/widget-template (routes_consent.go:125), which sits
+     * in the pre-auth throttle group and takes NO DF credential — the session id
+     * and its nonce are the capability. So this needs a session id, and rides the
+     * `session` road (no key, no proxy required).
+     *
+     * For the notice-authoring template keyed by internal_name, use
+     * {@link getNoticeTemplate}, which is the site-key-openable /df/notice/template.
+     *
+     * @param sessionId the consent_session_id from createSession()
+     */
+    async getSessionWidgetTemplate(sessionId) {
+        return this.request('GET', `/consent/sessions/${encodeURIComponent(sessionId)}/widget-template`, undefined, undefined, { road: 'session' });
+    }
+    /**
+     * Clear the cached config (useful after config changes).
+     */
+    clearCache() {
+        this.cachedConfig = null;
+    }
+}
+
+/**
+ * ConsentEra Consent SDK — Principal Client
+ * Data principal rights: Portal SSO, data export, deletion requests
+ */
+class PrincipalClient {
+    request;
+    logger;
+    // `config` is accepted and ignored: the portal road takes nothing from it,
+    // and the argument stays so the client's construction call reads the same as
+    // every other sub-client's.
+    constructor(request, _config, logger) {
+        this.request = request;
+        this.logger = logger;
+    }
+    /**
+     * Generate a principal portal SSO token.
+     * Returns a URL the data principal can visit to manage their consents.
+     *
+     * THIS ROAD STILL TAKES data_principal_ref, AND THAT IS CORRECT. It is
+     * identity/dfclient's (handlers.go:1418-1428), not the consent module's, so
+     * the 2026-09-21 ruling that refuses the field across the consent surface
+     * does not reach it. A sweep that converted this call would break a working
+     * endpoint.
+     */
+    async getPortalToken(dataPrincipalRef, redirectPath) {
+        const body = {
+            data_principal_ref: dataPrincipalRef,
+            redirect_path: redirectPath,
+        };
+        const response = await this.request('POST', '/df/principal-token', body);
+        this.logger.info('Principal portal token generated', {
+            dataPrincipal: dataPrincipalRef,
+            expires_in: response.expires_in,
+        });
+        return response;
+    }
+    /**
+     * Get the full portal URL for a data principal.
+     * Convenience method that returns just the redirect URL string.
+     */
+    async getPortalUrl(dataPrincipalRef, redirectPath) {
+        const token = await this.getPortalToken(dataPrincipalRef, redirectPath);
+        return token.redirect_url;
+    }
+    /**
+     * Open the principal portal in a new browser window/tab.
+     */
+    async openPortal(dataPrincipalRef, redirectPath) {
+        if (typeof window === 'undefined') {
+            throw new Error('openPortal can only be used in browser environments');
+        }
+        const url = await this.getPortalUrl(dataPrincipalRef, redirectPath);
+        window.open(url, '_blank', 'noopener,noreferrer');
+        this.logger.info('Principal portal opened', { dataPrincipal: dataPrincipalRef });
+    }
+}
+
+/**
+ * Simple Event Emitter
+ */
+class EventEmitter {
+    events = new Map();
+    /**
+     * Register event listener
+     */
+    on(event, callback) {
+        if (!this.events.has(event)) {
+            this.events.set(event, new Set());
+        }
+        this.events.get(event).add(callback);
+    }
+    /**
+     * Remove event listener
+     */
+    off(event, callback) {
+        const callbacks = this.events.get(event);
+        if (callbacks) {
+            callbacks.delete(callback);
+        }
+    }
+    /**
+     * Emit event
+     */
+    emit(event, ...args) {
+        const callbacks = this.events.get(event);
+        if (callbacks) {
+            callbacks.forEach((callback) => {
+                try {
+                    callback(...args);
+                }
+                catch (error) {
+                    console.error(`Error in event handler for ${event}:`, error);
+                }
+            });
+        }
+    }
+    /**
+     * Register one-time event listener
+     */
+    once(event, callback) {
+        const onceWrapper = (...args) => {
+            this.off(event, onceWrapper);
+            callback(...args);
+        };
+        this.on(event, onceWrapper);
+    }
+    /**
+     * Remove all listeners
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this.events.delete(event);
+        }
+        else {
+            this.events.clear();
+        }
+    }
+}
+
+/* eslint-disable no-console -- THIS FILE IS THE CONSOLE WRITE. The `no-console`
+   rule exists so that no OTHER file writes to the host's console directly; the
+   whole point of routing through here is that a host can set the level or
+   replace the sink. Disabling it anywhere else is the thing the rule is for. */
+class Logger {
+    level;
+    prefix = '[ConsentEra]';
+    constructor(level = 'info') {
+        this.level = level;
+    }
+    shouldLog(level) {
+        const levels = ['debug', 'info', 'warn', 'error'];
+        return levels.indexOf(level) >= levels.indexOf(this.level);
+    }
+    debug(...args) {
+        if (this.shouldLog('debug')) {
+            console.debug(this.prefix, ...args);
+        }
+    }
+    info(...args) {
+        if (this.shouldLog('info')) {
+            console.info(this.prefix, ...args);
+        }
+    }
+    warn(...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(this.prefix, ...args);
+        }
+    }
+    error(...args) {
+        if (this.shouldLog('error')) {
+            console.error(this.prefix, ...args);
+        }
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+}
+
+/**
+ * Consentera Consent SDK — the client.
+ *
+ * ─── THE CREDENTIAL RULE, AND IT IS ENFORCED HERE AT CONSTRUCTION ──────────
+ *
+ * A BROWSER BUNDLE NEVER CARRIES A SECRET (owner ruling 2026-09-22). Before
+ * 2.0.0 this file said the opposite in a comment — "Prefer site key (public,
+ * safe for frontend) over API key (secret, server-side only)" — and then sent
+ * whichever of the two it was given, from wherever it was running. Both halves
+ * of that sentence were wrong in a way that only showed up in production:
+ *
+ *   the site key does not work.  The platform replaces a site key's permissions
+ *   with exactly {consent.render, widget.render, session.submit, session.render}
+ *   (core/auth/df/api_usage.go:105-110, :1115) and NO ROUTE REQUIRES ANY OF THEM
+ *   — a grep for RequireDFPermission of those four names over the whole API
+ *   returns nothing. Every consent lifecycle road requires
+ *   engagement.consent.{collect,read,validate,update,withdraw,renew}
+ *   (cmd/api/routes_consent.go:377-569). The intersection is empty, so a browser
+ *   configured the recommended way got 403 on every call.
+ *
+ *   the secret key does work — which is worse. It is the only credential that
+ *   authorises those roads, so "make it work" meant putting a tiq_live_ key in
+ *   a public bundle.
+ *
+ * So the rule is now structural rather than advisory:
+ *
+ *   in a browser  a Data Fiduciary road MUST go through `proxyEndpoint` — your
+ *                 own server route, which holds the secret and forwards. An
+ *                 `apiKey` in a browser is REFUSED AT CONSTRUCTION.
+ *   on a server   `apiKey` directly, as always.
+ *   public roads  may carry `siteKey`; they carry no secret.
+ *   session roads carry no key at all: the session id and its nonce are the
+ *                 capability.
+ *
+ * WHAT THE PLATFORM MUST STILL DO for the public half to be usable from a
+ * browser without a proxy is a separate unit and is written down in
+ * README.md → "What the platform must guarantee".
+ */
+class ConsentEraClient extends EventEmitter {
+    config;
+    logger;
+    transport;
+    /** Consent session creation and artifact retrieval */
+    session;
+    /** Consent validation (single + bulk) */
+    validate;
+    /** Consent update, withdrawal, and renewal */
+    manage;
+    /** Callback handler for redirect flows */
+    callback;
+    /** DF configuration and notice purposes */
+    df;
+    /** Data principal rights and portal SSO */
+    principal;
+    /**
+     * Unified consent namespace — aggregates session, validate, manage, callback.
+     */
+    consent;
+    constructor(config) {
+        super();
+        if (!config.apiEndpoint && !config.proxyEndpoint) {
+            throw configError('Consentera: set `proxyEndpoint` (your own server route — required in a browser for ' +
+                'consent lifecycle roads) or `apiEndpoint` (server-side use).', 'ENDPOINT_REQUIRED');
+        }
+        // A tenant id is needed only where THIS SDK names the tenant: direct mode,
+        // which sends X-Tenant-Id. Behind `proxyEndpoint` your server holds the key
+        // and the key names the tenant, so the SDK sends no tenant header, and
+        // demanding the value anyway made every integrator invent one (WEB-036).
+        if (!config.tenantId && !config.proxyEndpoint) {
+            throw configError('Consentera: tenantId is required with `apiEndpoint`. (Behind `proxyEndpoint` it is optional: ' +
+                'your server supplies the tenant.)', 'TENANT_ID_REQUIRED');
+        }
+        // THE ONE REFUSAL — the shared guard, so this client and the ConsenteraConsent
+        // cookie SDK enforce the identical rule at their two doors.
+        assertNoSecretKeyInBrowser({
+            apiKey: config.apiKey,
+            unsafeAllowSecretKeyInBrowser: config.unsafeAllowSecretKeyInBrowser,
+            fix: 'Move the key to your own server and point the SDK at it with ' +
+                '`proxyEndpoint: "/api/consentera"`; the browser then sends no credential at all.',
+        });
+        this.config = config;
+        this.logger = new Logger(config.debug ? 'debug' : 'info');
+        this.transport = new HttpTransport({
+            tenantId: config.tenantId,
+            apiEndpoint: config.apiEndpoint,
+            proxyEndpoint: config.proxyEndpoint,
+            apiKey: config.apiKey,
+            siteKey: config.siteKey,
+            customHeaders: config.customHeaders,
+            unsafeAllowSecretKeyInBrowser: config.unsafeAllowSecretKeyInBrowser,
+            timeoutMs: config.timeoutMs,
+            retry: config.retry,
+            beforeSend: config.beforeSend,
+            fetchImpl: config.fetchImpl,
+        }, this.logger);
+        const requestFn = this.request.bind(this);
+        this.session = new ConsentSession(requestFn, config, this.logger);
+        this.validate = new ConsentValidator(requestFn, this.logger);
+        this.manage = new ConsentManager(requestFn, this.logger, {
+            contextMode: config.collectContext ?? 'minimal',
+        });
+        // Public event bus: every successful consent mutation (update/grant/deny/
+        // withdraw/renew) re-emits as `consent.changed` — subscribe with
+        // client.on('consent.changed', cb) instead of polling validate.
+        this.manage.onChanged = (payload) => this.emit('consent.changed', payload);
+        this.callback = new CallbackHandler(this.logger, requestFn, {
+            verifySignature: config.verifyCallbackSignature,
+            artifactWaitMs: config.artifactWaitMs,
+        });
+        this.df = new DFConfigClient(requestFn, this.logger);
+        this.principal = new PrincipalClient(requestFn, config, this.logger);
+        this.consent = {
+            createSession: this.session.createSession.bind(this.session),
+            redirectToConsent: this.session.redirectToConsent.bind(this.session),
+            openConsentPopup: this.session.openConsentPopup.bind(this.session),
+            getArtifact: this.session.getArtifact.bind(this.session),
+            validate: this.validate.check.bind(this.validate),
+            validateBulk: this.validate.checkBulk.bind(this.validate),
+            isAllowed: this.validate.isAllowed.bind(this.validate),
+            areAllowed: this.validate.areAllowed.bind(this.validate),
+            handleCallback: this.callback.parseCallback.bind(this.callback),
+            isCallback: this.callback.isCallback.bind(this.callback),
+            getContext: this.manage.getUpdateContext.bind(this.manage),
+            update: this.manage.update.bind(this.manage),
+            grant: this.manage.grant.bind(this.manage),
+            deny: this.manage.deny.bind(this.manage),
+            getWithdrawalContext: this.manage.getWithdrawalContext.bind(this.manage),
+            withdraw: this.manage.withdraw.bind(this.manage),
+            withdrawBulk: this.manage.withdrawBulk.bind(this.manage),
+            getRenewalContext: this.manage.getRenewalContext.bind(this.manage),
+            renew: this.manage.renew.bind(this.manage),
+            renewBulk: this.manage.renewBulk.bind(this.manage),
+        };
+        this.logger.info('Consentera client initialised', {
+            mode: config.proxyEndpoint ? 'proxy' : 'direct',
+            tenantId: config.tenantId,
+        });
+    }
+    /**
+     * Central HTTP request method. Delegates to {@link HttpTransport}, which owns
+     * the deadline, the retry policy, the idempotency key and the credential rule.
+     *
+     * @param queryParams query string values (the legacy 4th-argument position)
+     * @param options     per-request road, idempotency key, signal, timeout, retry
+     */
+    async request(method, path, body, queryParams, options = {}) {
+        try {
+            return await this.transport.request(method, path, body, {
+                ...options,
+                query: { ...queryParams, ...options.query },
+            });
+        }
+        catch (err) {
+            if (err instanceof ConsenteraError)
+                this.emit('error', err);
+            throw err;
+        }
+    }
+    /** Build client context — delegates to shared helper */
+    static buildClientContext = buildClientContext;
+    /** Build affirmative action — delegates to shared helper */
+    static buildAffirmativeAction = buildAffirmativeAction;
+    /** Get the current configuration. The credentials are redacted. */
+    getConfig() {
+        const copy = { ...this.config };
+        if (copy.apiKey)
+            copy.apiKey = `${copy.apiKey.slice(0, 9)}…`;
+        return copy;
+    }
+}
+
+const ConsentEraContext = createContext(null);
+function ConsentEraProvider({ config, children }) {
+    // Construct in the memo, but NEVER write state from it. The outcome — client
+    // or error — is the memo's value, so a double invocation under StrictMode
+    // produces the same value twice instead of two state writes.
+    const built = useMemo(() => {
+        try {
+            return { client: new ConsentEraClient(config), error: null };
+        }
+        catch (err) {
+            return { client: null, error: err };
+        }
+        // The client is rebuilt only when something it is made of changes. `config`
+        // itself is deliberately not a dependency: hosts pass an object literal,
+        // which is a new reference every render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [config.tenantId, config.apiKey, config.siteKey, config.apiEndpoint, config.proxyEndpoint]);
+    const [runtimeError, setRuntimeError] = useState(null);
+    useEffect(() => {
+        // A new client means the previous client's errors are no longer ours.
+        setRuntimeError(null);
+        const client = built.client;
+        if (!client)
+            return;
+        const handleError = (err) => setRuntimeError(err);
+        client.on('error', handleError);
+        return () => {
+            client.off('error', handleError);
+        };
+    }, [built.client]);
+    const value = useMemo(() => ({ client: built.client, loading: false, error: built.error ?? runtimeError }), [built.client, built.error, runtimeError]);
+    return jsx(ConsentEraContext.Provider, { value: value, children: children });
+}
+/**
+ * What a hook sees outside any provider. A VALUE and not a throw (WEB-038): a
+ * throw during render unmounts the whole tree above the nearest error
+ * boundary, so a consent SDK that throws takes down the page it was meant to
+ * gate. The gate below fails closed on it; the error says what to fix.
+ */
+const MISSING_PROVIDER = {
+    client: null,
+    loading: false,
+    error: new Error('Consentera: useConsentEra* was called outside <ConsentEraProvider>. Wrap the tree in it.'),
+};
+/**
+ * The context as provided: `client` is null when the configuration was
+ * refused (then `error` says why) or when there is no provider at all (then
+ * `error` says that). NEVER throws.
+ */
+function useConsentEraContext() {
+    return useContext(ConsentEraContext) ?? MISSING_PROVIDER;
+}
+/**
+ * The client, or `client: null` with the reason in `error`. NEVER throws
+ * during render (SDK register WEB-038).
+ *
+ * It used to throw when the provider's configuration was refused: a missing
+ * tenantId, a secret key in a browser. That threw from inside render, so a
+ * configuration mistake did not produce a closed consent gate. It produced a
+ * blank page, measured in the React demos. Render your fallback on
+ * `client === null`. `error` is a ConsenteraError whose `code` names the
+ * refusal (`SECRET_KEY_IN_BROWSER`, `ENDPOINT_REQUIRED`, …).
+ */
+function useConsentEraClient() {
+    return useConsentEraContext();
+}
+
+/**
+ * Main hook for accessing all Consentera consent operations.
+ *
+ * @example
+ * ```tsx
+ * function LoanPage() {
+ *   const { consent, error } = useConsentEra();
+ *   if (!consent) return <p>Consent is unavailable: {error?.message}</p>;
+ *
+ *   const handleApply = async () => {
+ *     const check = await consent.validate(
+ *       { data_principal_identifiers: { email: 'user@example.com' } },
+ *       'credit_assessment'
+ *     );
+ *     if (check.decision === 'DENY') {
+ *       const s = await consent.createSession({
+ *         // keyed by THIS organisation's locked integration key — the SAME
+ *         // open map the validate call above passes, one vocabulary on both
+ *         // roads (F015). Only the wire KEY differs: `data_principal` here
+ *         // may mint a person, `data_principal_identifiers` only resolves.
+ *         data_principal: { email: 'user@example.com' },
+ *         notice_internal_name: 'loan_notice',
+ *       });
+ *       consent.redirectToConsent(s);
+ *     }
+ *   };
+ * }
+ * ```
+ */
+function useConsentEra() {
+    const { client, loading, error } = useConsentEraClient();
+    return useMemo(() => ({
+        ready: client !== null,
+        consent: client?.consent ?? null,
+        session: client?.session ?? null,
+        validate: client?.validate ?? null,
+        manage: client?.manage ?? null,
+        callback: client?.callback ?? null,
+        df: client?.df ?? null,
+        principal: client?.principal ?? null,
+        loading,
+        error,
+    }), [client, loading, error]);
+}
+
+/**
+ * Stable identity for a `who` that hosts pass as an object literal.
+ *
+ * IT ENUMERATES WHATEVER IS THERE, and since F015 that is load-bearing rather
+ * than merely tidy. `data_principal_identifiers` is an OPEN map keyed by the
+ * tenant's own locked integration key, so a key function that walked a FIXED
+ * field list would read nothing at all for a tenant keyed on an atom outside
+ * that list — every such person would hash to the same empty key, the hook
+ * would treat two different people as one, and the gate would answer for the
+ * wrong person. Under the old closed five-field type that bug was impossible;
+ * under the open map it is one `['email','mobile',…]` away.
+ */
+function whoKey(who) {
+    if (!who)
+        return '';
+    if ('data_principal_id' in who && who.data_principal_id)
+        return `id:${who.data_principal_id}`;
+    const ids = who.data_principal_identifiers ?? {};
+    return `ids:${Object.keys(ids)
+        .sort()
+        .map((k) => `${k}=${ids[k] ?? ''}`)
+        .join('&')}`;
+}
+function useConsentValidation(who, purposeCode, options) {
+    // `client` is null when the provider's configuration was refused or there is
+    // no provider. Every hook below is still called (the rules of hooks); none
+    // of them sends anything without a client, and the gate stays closed with
+    // the reason in `error` (WEB-038: this used to throw during render).
+    const { client, error: clientError } = useConsentEraClient();
+    const [allowed, setAllowed] = useState(null);
+    const [result, setResult] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const autoCheck = options?.autoCheck !== false;
+    const watchChanges = options?.watchChanges !== false;
+    const key = whoKey(who);
+    // The value the effect depends on; `who` by reference would re-run forever.
+    const stableWho = useMemo(() => who, [key]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Monotonic: only the newest request may write state.
+    const seqRef = useRef(0);
+    const abortRef = useRef(null);
+    const recheck = useCallback(async () => {
+        if (!client || !stableWho || !purposeCode)
+            return;
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        const seq = ++seqRef.current;
+        const current = () => seq === seqRef.current && !controller.signal.aborted;
+        setLoading(true);
+        setError(null);
+        try {
+            const response = await client.validate.check(stableWho, purposeCode, {
+                signal: controller.signal,
+            });
+            if (!current())
+                return;
+            setResult(response);
+            setAllowed(response.decision === 'ALLOW');
+        }
+        catch (err) {
+            if (!current())
+                return;
+            setError(err);
+            // FAIL CLOSED: an unknown decision is not an allowed one.
+            setAllowed(null);
+        }
+        finally {
+            if (current())
+                setLoading(false);
+        }
+    }, [client, stableWho, purposeCode]);
+    useEffect(() => {
+        if (autoCheck && stableWho && purposeCode) {
+            void recheck();
+        }
+        return () => {
+            abortRef.current?.abort();
+        };
+    }, [autoCheck, stableWho, purposeCode, recheck]);
+    // Close the gate when consent changes under it.
+    useEffect(() => {
+        if (!client || !watchChanges || !stableWho || !purposeCode)
+            return;
+        const onChanged = (payload) => {
+            const touched = payload?.changes?.some((c) => c.purpose_id === purposeCode);
+            // A change with no purpose list, or one naming this purpose, both mean
+            // "what you know is stale". Re-checking is cheap; being wrong is not.
+            if (touched || !payload?.changes?.length)
+                void recheck();
+        };
+        client.on('consent.changed', onChanged);
+        return () => {
+            client.off('consent.changed', onChanged);
+        };
+    }, [client, watchChanges, stableWho, purposeCode, recheck]);
+    if (!client)
+        return { allowed: null, result: null, loading: false, error: clientError, recheck };
+    return { allowed, result, loading, error, recheck };
+}
+
+function ConsentGate({ who, purposeCode, children, fallback = null, loading: loadingContent, }) {
+    const { allowed, loading } = useConsentValidation(who, purposeCode);
+    if (loading) {
+        return jsx(Fragment, { children: loadingContent ?? fallback });
+    }
+    if (!allowed) {
+        return jsx(Fragment, { children: fallback });
+    }
+    return jsx(Fragment, { children: children });
+}
+
+export { ConsentEraProvider, ConsentGate, useConsentEra, useConsentEraClient, useConsentEraContext, useConsentValidation };
+//# sourceMappingURL=index.mjs.map