@consentera/consent-sdk 2.0.0 → 2.1.0

package/dist/react/index.mjs

@@ -79,6 +79,15 @@ const CODE_KIND = {
     CONFLICT: 'conflict',
     IDEMPOTENCY_KEY_REUSE: 'conflict',
     RATE_LIMIT_EXCEEDED: 'rate_limit',
+    // 409 — the ORGANISATION's plan, never the person's answer. The consent cap
+    // refuses a submit/update that would add a NEW (data principal, purpose)
+    // grant past the plan's consents_max (platform
+    // core/consentbridge/grant_cap.go: NewGrantCapRefusal), and nothing was
+    // recorded. The DEPA ingest answers the same stop in its own vocabulary
+    // (consent/depa/df_handlers.go). Its own kind, so it is never read as a
+    // `conflict` (a duplicate), a network failure, or a refusal by the person.
+    PLAN_LIMIT_REACHED: 'plan_limit',
+    ARTEFACT_NOT_ACCEPTED_PLAN_LIMIT: 'plan_limit',
     INTERNAL_ERROR: 'server',
     INTERNAL_SERVER_ERROR: 'server',
     DATABASE_ERROR: 'server',
@@ -187,6 +196,41 @@ class ConsenteraNetworkError extends ConsenteraError {
 }
 class ConsenteraTimeoutError extends ConsenteraError {
 }
+/**
+ * The organisation's plan cannot take this change: HTTP 409 with code
+ * `PLAN_LIMIT_REACHED` (or `ARTEFACT_NOT_ACCEPTED_PLAN_LIMIT` on the DEPA
+ * ingest). For consent it means the submit or update would have added a NEW
+ * (data principal, purpose) grant past the plan's `consents_max`, and
+ * `reasonCode` is `'new_consents_only'`.
+ *
+ * What it is NOT, and must never be shown or reported as:
+ *   * the person's refusal — they did not deny anything; do not record,
+ *     display or emit it as `denied`;
+ *   * a transient failure — retrying the same request gets the same answer
+ *     until the organisation's plan changes, so this SDK never retries it.
+ *
+ * `recorded` is always `false`: the platform wrote nothing, fired no callback
+ * and emitted no event. Show the person a neutral "this organisation can't
+ * accept new consents right now" (the platform's own `message` is written for
+ * them) and leave their existing choices as they were.
+ */
+class ConsenteraPlanLimitError extends ConsenteraError {
+    /** `details.reason_code` — `'new_consents_only'` for the consent cap. */
+    reasonCode;
+    /** `details.limit_key` — set on an admin create refusal (e.g. `'consents_max'`), absent on a consent submit. */
+    limitKey;
+    /** The envelope's `details`, as sent. */
+    details;
+    /** Always false: a plan-limit refusal records nothing. */
+    recorded = false;
+    constructor(init) {
+        super({ ...init, retryable: false });
+        const d = init.details;
+        this.details = d;
+        this.reasonCode = typeof d?.reason_code === 'string' ? d.reason_code : undefined;
+        this.limitKey = typeof d?.limit_key === 'string' ? d.limit_key : undefined;
+    }
+}
 const KIND_CLASS = {
     config: ConsenteraConfigError,
     auth: ConsenteraAuthError,
@@ -197,6 +241,7 @@ const KIND_CLASS = {
     not_found: ConsenteraNotFoundError,
     conflict: ConsenteraConflictError,
     rate_limit: ConsenteraRateLimitError,
+    plan_limit: ConsenteraPlanLimitError,
     server: ConsenteraServerError,
     network: ConsenteraNetworkError,
     timeout: ConsenteraTimeoutError,
@@ -206,7 +251,7 @@ const KIND_CLASS = {
 function newOfKind(init) {
     return new KIND_CLASS[init.kind](init);
 }
-/** Pull `{code, message}` off a parsed body, tolerating the `{error:{...}}` wrapper. */
+/** Pull `{code, message, details}` off a parsed body, tolerating the `{error:{...}}` wrapper. */
 function readEnvelope(body) {
     if (!body || typeof body !== 'object')
         return {};
@@ -214,16 +259,20 @@ function readEnvelope(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 };
+    const details = inner.details && typeof inner.details === 'object' && !Array.isArray(inner.details)
+        ? inner.details
+        : undefined;
+    return { code, message, details };
 }
 /** Build the error for a non-2xx response. */
 function errorFromResponse(args) {
-    const { code, message } = readEnvelope(args.body);
+    const { code, message, details } = readEnvelope(args.body);
     const kind = (code && CODE_KIND[code]) || kindForStatus(args.status);
-    const retryable = args.status === 429 || args.status >= 500;
+    const retryable = kind !== 'plan_limit' && (args.status === 429 || args.status >= 500);
     return newOfKind({
         kind,
         code,
+        details,
         status: args.status,
         requestId: args.requestId,
         responseBody: args.body,
@@ -412,7 +461,7 @@ function removeStored(kind, key) {
  * 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_VERSION = '2.1.0';
 const SDK_PLATFORM = 'web';
 /** The value of the `X-Consentera-SDK` header: `<surface>/<version>`. */
 const SDK_HEADER_VALUE = `js/${SDK_VERSION}`;
@@ -420,8 +469,8 @@ 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
+ *     User-Agent:        ConsenteraSDK/2.1.0 (<platform>; <runtime>)
+ *     X-Consentera-SDK:  <surface>/2.1.0
  *
  * `ConsenteraSDK/<version>` is the form the PLATFORM ALREADY PARSES:
  * `internal/core/audit/user_agent_coarsening_test.go:39-40` asserts that
@@ -523,7 +572,7 @@ function newRequestId() {
     // 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) {
+function sleep$1(ms, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(cancelledError('request cancelled'));
@@ -545,16 +594,35 @@ function backoffMs(attempt, policy, random = Math.random) {
     const exp = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** attempt);
     return Math.floor(random() * exp);
 }
+/**
+ * The ONE normalisation of a configured base URL (HC-13): surrounding
+ * whitespace and every trailing slash are trimmed, once, when the config is
+ * read — and nothing else changes, so a gateway path prefix
+ * ("https://gw.corp/consentera/") is kept. Every join below then adds exactly
+ * one slash. The same rule Android (`trimEnd('/')`) and the CLI (`/\/+$/`)
+ * apply.
+ */
+function normalizeBaseUrl(base) {
+    return (typeof base === 'string' ? base.trim().replace(/\/+$/, '') : base);
+}
+function normalizeBases(config) {
+    const out = { ...config };
+    if (out.apiEndpoint !== undefined)
+        out.apiEndpoint = normalizeBaseUrl(out.apiEndpoint);
+    if (out.proxyEndpoint !== undefined)
+        out.proxyEndpoint = normalizeBaseUrl(out.proxyEndpoint);
+    return out;
+}
 class HttpTransport {
     config;
     logger;
     constructor(config, logger) {
-        this.config = config;
+        this.config = normalizeBases(config);
         this.logger = logger;
     }
     /** Swap config after construction (the client re-reads customHeaders each call). */
     updateConfig(patch) {
-        this.config = { ...this.config, ...patch };
+        this.config = { ...this.config, ...normalizeBases(patch) };
     }
     /**
      * The credential decision for one road, in one place so the policy can be
@@ -776,7 +844,7 @@ class HttpTransport {
                 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);
+            await sleep$1(wait, options.signal);
         }
         /* istanbul ignore next — the loop always throws on its last attempt. */
         throw lastError ?? networkError(`${method} ${path} failed`);
@@ -1406,6 +1474,56 @@ function principalBody(who) {
  * ConsentEra Consent SDK — Consent Validation
  * Validate consent status for single or multiple purposes
  */
+/** The longest the {@link ValidateOptions.retryWhenPending} re-ask will wait, in seconds. */
+const VALIDATE_PENDING_RETRY_CAP_SECONDS = 5;
+/** The wait used when an `applied: false` answer carries no usable `retry_after`. */
+const VALIDATE_PENDING_DEFAULT_SECONDS = 1;
+/**
+ * The platform's validate answer, with `applied` and `retry_after` read the
+ * one way every SDK reads them:
+ *
+ *  * `applied` — a JSON boolean is kept; absent (a platform older than
+ *    936715ad71) or any other type reads as `true`.
+ *  * `retry_after` — kept when it is a finite number >= 0 (rounded up to whole
+ *    seconds); anything else is dropped.
+ *
+ * Every other field passes through untouched.
+ */
+function normalizeValidateResponse(raw) {
+    const r = raw;
+    const out = { ...r };
+    out.applied = typeof r.applied === 'boolean' ? r.applied : true;
+    const ra = r.retry_after;
+    if (typeof ra === 'number' && Number.isFinite(ra) && ra >= 0) {
+        out.retry_after = Math.ceil(ra);
+    }
+    else {
+        delete out.retry_after;
+    }
+    return out;
+}
+/** The wait before the one re-ask, in milliseconds. */
+function pendingRetryDelayMs(answer) {
+    const asked = answer.retry_after ?? VALIDATE_PENDING_DEFAULT_SECONDS;
+    return Math.min(asked, VALIDATE_PENDING_RETRY_CAP_SECONDS) * 1000;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('aborted'));
+            return;
+        }
+        const t = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(signal?.reason ?? new Error('aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
 class ConsentValidator {
     request;
     logger;
@@ -1434,7 +1552,19 @@ class ConsentValidator {
      */
     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 });
+        const ask = async () => normalizeValidateResponse(await this.request('POST', '/consent/validate', body, undefined, { signal: options?.signal, timeoutMs: options?.timeoutMs }));
+        let response = await ask();
+        if (options?.retryWhenPending && response.applied === false) {
+            // ONE re-ask, never a loop: the second answer is returned whatever it
+            // says, so a projection that is still behind cannot hold the caller.
+            const waitMs = pendingRetryDelayMs(response);
+            this.logger.debug('Validate answer not yet applied; asking once more', {
+                purpose: purposeCode,
+                waitMs,
+            });
+            await sleep(waitMs, options.signal);
+            response = await ask();
+        }
         // 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.
@@ -1457,7 +1587,10 @@ class ConsentValidator {
             ...principalBody(who),
             purpose_codes: purposeCodes,
         };
-        const response = await this.request('POST', '/consent/validate/bulk', body, undefined, { signal: options?.signal, timeoutMs: options?.timeoutMs });
+        const raw = await this.request('POST', '/consent/validate/bulk', body, undefined, { signal: options?.signal, timeoutMs: options?.timeoutMs });
+        const response = Array.isArray(raw?.results)
+            ? { ...raw, results: raw.results.map((r) => normalizeValidateResponse(r)) }
+            : raw;
         this.logger.debug('Bulk consent validated', {
             namedBy: 'data_principal_id' in who ? 'data_principal_id' : 'data_principal_identifiers',
             purposes: purposeCodes.length,
@@ -1572,6 +1705,16 @@ class ConsentManager {
     /**
      * Update consent decisions for a data principal.
      * Pass an array of purpose updates (grant or deny).
+     *
+     * @throws {ConsenteraPlanLimitError} HTTP 409 `PLAN_LIMIT_REACHED`,
+     *   `reasonCode: 'new_consents_only'` — the update would add a NEW
+     *   (data principal, purpose) grant past the organisation's plan
+     *   (`consents_max`). NOTHING was recorded and no `consent.changed` event
+     *   fires. It is not the person's refusal: never record or show it as
+     *   `denied`, and do not retry the same update — show a neutral "can't
+     *   accept new consents right now" instead. A denial, a withdrawal and a
+     *   re-grant of a purpose the person already holds are never refused.
+     *   `grant()` and `deny()` go through here and throw the same.
      */
     async update(dataPrincipalId, updates, context, uiEventId = 'btn_save_preferences', options) {
         const body = {
@@ -1681,7 +1824,7 @@ class ConsentManager {
             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 });
+        const response = withRetryAfter(await this.request('POST', '/consent/renew', body, undefined, { ...this.mutation(options), raw: true }));
         this.logger.info('Consent renewed', {
             dataPrincipal: dataPrincipalId,
             purposes: purposeIds,
@@ -1700,7 +1843,7 @@ class ConsentManager {
             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 });
+        const response = withRetryAfter(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,
@@ -1713,6 +1856,25 @@ class ConsentManager {
         return response;
     }
 }
+/**
+ * The renewal back-off is `retry_after` on the wire (seconds) — the platform's
+ * canonical field name. RenewResponse used to model `retry_after_seconds`, which
+ * the API never sends. For one release both spellings are read and both are
+ * populated: `retry_after` wins when both arrive, a legacy `retry_after_seconds`
+ * still decodes, and the deprecated alias mirrors the canonical value. Nothing is
+ * added when neither is present, and the caller's object is never mutated.
+ */
+function withRetryAfter(response) {
+    const body = response?.body;
+    if (!body)
+        return response;
+    const canonical = typeof body.retry_after === 'number' ? body.retry_after : undefined;
+    const legacy = typeof body.retry_after_seconds === 'number' ? body.retry_after_seconds : undefined;
+    const value = canonical ?? legacy;
+    if (value === undefined || (body.retry_after === value && body.retry_after_seconds === value))
+        return response;
+    return { ...response, body: { ...body, retry_after: value, retry_after_seconds: value } };
+}
 
 /**
  * Consentera Consent SDK — Callback Handler