@consentera/consent-sdk 2.0.0 → 2.1.0

package/dist/consentera-consent.mjs

@@ -1745,6 +1745,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',
@@ -1853,6 +1862,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,
@@ -1863,6 +1907,7 @@ const KIND_CLASS = {
     not_found: ConsenteraNotFoundError,
     conflict: ConsenteraConflictError,
     rate_limit: ConsenteraRateLimitError,
+    plan_limit: ConsenteraPlanLimitError,
     server: ConsenteraServerError,
     network: ConsenteraNetworkError,
     timeout: ConsenteraTimeoutError,
@@ -1872,7 +1917,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 {};
@@ -1880,16 +1925,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,
@@ -1932,7 +1981,7 @@ const ConsentEraApiError = ConsenteraError;
  * being overwritten with the wrong value and nothing noticing.
  */
 const SDK_NAME = 'consent-sdk-js';
-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}`;
@@ -1940,8 +1989,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
@@ -2043,7 +2092,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'));
@@ -2065,16 +2114,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
@@ -2296,7 +2364,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`);
@@ -2375,7 +2443,9 @@ class ConsentEraConsent extends EventEmitter {
                 "Consentera API origin (the SDK calls `${apiEndpoint}/api/v1/cookie-consent/*`); with " +
                 'the script-tag build, set `data-api-endpoint`.', 'ENDPOINT_REQUIRED');
         }
-        this.config = this.mergeDefaults(config);
+        // Trimmed ONCE, here (HC-13): "https://x/prefix/" and "https://x/prefix"
+        // are the same base, the prefix is kept, and no request carries "//".
+        this.config = this.mergeDefaults({ ...config, apiEndpoint: normalizeBaseUrl(config.apiEndpoint) });
         this.logger = new Logger(config.apiKey ? 'info' : 'debug');
         this.storage = new ConsentStorage(this.config.storage);
         this.deviceId = this.getOrCreateDeviceId();
@@ -3684,6 +3754,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;
@@ -3712,7 +3832,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.
@@ -3735,7 +3867,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,
@@ -3850,6 +3985,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 = {
@@ -3959,7 +4104,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,
@@ -3978,7 +4123,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,
@@ -3991,6 +4136,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
@@ -4860,5 +5024,5 @@ if (typeof window !== 'undefined') {
     window.ConsentEraConsent = ConsentEraConsent;
 }
 
-export { CallbackHandler, ConsentBanner, ConsentEraApiError, ConsentEraClient, ConsentEraConsent, ConsentManager, ConsentModeBridge, ConsentSession, ConsentStorage, ConsentValidator, ConsenteraAuthError, ConsenteraConfigError, ConsenteraConflictError, ConsenteraError, ConsenteraGuardianError, ConsenteraIdentityError, ConsenteraNetworkError, ConsenteraNotFoundError, ConsenteraPermissionError, ConsenteraRateLimitError, ConsenteraServerError, ConsenteraTimeoutError, ConsenteraValidationError, DEFAULT_RETRY, DEFAULT_TIMEOUT_MS, DFConfigClient, GPPManager, HttpTransport, PreferenceCenter, PrincipalClient, SDK_HEADER_VALUE, SDK_NAME, SDK_PLATFORM, SDK_VERSION, TCFManager, buildClientContext, claimedCallbackStatus, ConsentEraConsent as default, installConsentModeBridge, isBrowser, isSecretKey, isSiteKey, newRequestId, parseRetryAfterMs, principalBody, readDecisionMessage, readStored, removeStored, storageAvailable, storageKeys, verifyCallbackSignature, writeStored };
+export { CallbackHandler, ConsentBanner, ConsentEraApiError, ConsentEraClient, ConsentEraConsent, ConsentManager, ConsentModeBridge, ConsentSession, ConsentStorage, ConsentValidator, ConsenteraAuthError, ConsenteraConfigError, ConsenteraConflictError, ConsenteraError, ConsenteraGuardianError, ConsenteraIdentityError, ConsenteraNetworkError, ConsenteraNotFoundError, ConsenteraPermissionError, ConsenteraPlanLimitError, ConsenteraRateLimitError, ConsenteraServerError, ConsenteraTimeoutError, ConsenteraValidationError, DEFAULT_RETRY, DEFAULT_TIMEOUT_MS, DFConfigClient, GPPManager, HttpTransport, PreferenceCenter, PrincipalClient, SDK_HEADER_VALUE, SDK_NAME, SDK_PLATFORM, SDK_VERSION, TCFManager, VALIDATE_PENDING_RETRY_CAP_SECONDS, buildClientContext, claimedCallbackStatus, ConsentEraConsent as default, installConsentModeBridge, isBrowser, isSecretKey, isSiteKey, newRequestId, normalizeValidateResponse, parseRetryAfterMs, principalBody, readDecisionMessage, readStored, removeStored, storageAvailable, storageKeys, verifyCallbackSignature, writeStored };
 //# sourceMappingURL=consentera-consent.mjs.map