@consentera/consent-sdk 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,4 +1,119 @@
-## Unreleased — renewal request wire correction
+# Changelog
+
+All notable changes to `@consentera/consent-sdk`.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.0] — 2026-09-27
+
+A minor release. Nothing you call today changes shape; the new behaviour is
+additive or opt-in. Detail for each item is in the sections below.
+
+- **Added:** `ValidateResponse.applied` / `retry_after` and the opt-in
+  `validate(who, code, { retryWhenPending: true })` (F232, platform
+  `936715ad71`).
+- **Added:** `ConsenteraPlanLimitError` (`kind: 'plan_limit'`) for the
+  platform's 409 `PLAN_LIMIT_REACHED`. An exhaustive `switch` on `kind` needs
+  the new case.
+- **Fixed:** `RenewResponse.retry_after` / `BulkRenewResponse.retry_after` are
+  read from the field the API sends.
+- **Fixed:** `apiEndpoint` / `proxyEndpoint` and the notice widget's
+  `data-api-base` keep their path prefix and never produce `//`.
+- **Deprecated:** the notice widget deriving its API base from its own
+  `<script src>` (HC-12). It still works and logs one warning; set
+  `data-api-base`.
+- **Deprecated:** `RenewResponse.retry_after_seconds`; removed in the next
+  minor release. Read `retry_after`.
+
+## Detail (2.1.0) — validate says when its answer is not yet applied (F232)
+
+Platform producer: **`936715ad71`** (F129, the pending-act overlay on
+`POST /consent/validate`). From that commit the platform keeps an older DENY
+while a newer grant is still being applied, and marks the answer
+`applied: false` with `retry_after` (seconds).
+
+### Added — MINOR version bump
+
+- **`ValidateResponse.applied`** (boolean, always set by the SDK) and
+  **`ValidateResponse.retry_after`** (seconds, optional), on `validate` and on
+  every `validateBulk` result. An absent `applied` (a platform older than
+  `936715ad71`) and a non-boolean one both read as `true`; a `retry_after` that
+  is not a finite number >= 0 is dropped.
+- **`ValidateOptions.retryWhenPending`** (default `false`): when the answer is
+  `applied: false`, wait `retry_after` (1 s if absent, capped at 5 s,
+  `VALIDATE_PENDING_RETRY_CAP_SECONDS`), ask once more and return that answer.
+  Honours `signal` during the wait. Single-purpose `validate`/`isAllowed` only.
+- `normalizeValidateResponse` is exported for callers that read validate
+  through their own transport.
+
+Nothing changes unless you read the new fields or pass the option.
+
+## Detail (2.1.0) — base URLs keep their prefix; the notice widget's src-derived base is deprecated
+
+### Changed — MINOR version bump
+
+- **`consentera-notice-widget.js`: a path prefix in `data-api-base` is kept** on
+  every request. The post-submit hand-over uses the server's absolute URL
+  (`consent_url`, else `redirect_url`) as-is and resolves a relative one under
+  the base instead of against the host root. A non-http(s) redirect target is
+  refused.
+- The widget without `data-api-base` still works. It now derives the base more
+  carefully: a src of the platform's form `<base>/sdk/<file>` gives `<base>`, so
+  a gateway prefix survives (2.0 kept only the origin); any other src gives its
+  origin, as before.
+
+### Deprecated
+
+- **Deriving the notice widget's API base from its own `src`.** It is wrong for
+  a self-hosted or CDN-served copy (the requests go to the CDN). The widget
+  logs one `console.warn`: `set data-api-base; deriving from the script src is
+  deprecated`. Set `data-api-base`. With neither the attribute nor an http(s)
+  src (an inline copy), the widget logs an error, emits
+  `consentera:notice-error` and makes no request.
+
+### Fixed
+
+- `apiEndpoint` and `proxyEndpoint` are trimmed of whitespace and trailing
+  slashes once, when the config is read (`normalizeBaseUrl`), so
+  `https://x/prefix/` and `https://x/prefix` produce the same single-slash URLs
+  with the prefix kept. Applies to the transport (`ConsentEraClient`) and the
+  cookie SDK (`ConsentEraConsent`).
+
+## Detail (2.1.0) — renewal back-off reads `retry_after`
+
+### Fixed
+
+- **`RenewResponse.retry_after`** (seconds). The platform names the back-off
+  field `retry_after` — the canonical field registry's name and the one every
+  202 envelope carries (platform pre-main, `consent/collection.go:4531`,
+  `consent/update_context.go:228`). `RenewResponse` (and `BulkRenewResponse`)
+  modelled `retry_after_seconds`, which the API has never sent, so a caller
+  reading the documented field always got `undefined`. `renew` and `renewBulk`
+  now return `retry_after`.
+
+### Deprecated
+
+- **`RenewResponse.retry_after_seconds`**, for one release. It is populated
+  from `retry_after` so existing readers start working, and a body carrying
+  only the old spelling still decodes into `retry_after`; when both arrive,
+  `retry_after` wins. It will be removed in the next minor release.
+
+## Detail (2.1.0) — plan-limit refusal is its own error
+
+### Added
+
+- **`ConsenteraPlanLimitError`** (`kind: 'plan_limit'`). The platform refuses a
+  consent submit or update that would add a NEW (data principal, purpose)
+  grant past the plan's `consents_max` with 409 `PLAN_LIMIT_REACHED`,
+  `details.reason_code: 'new_consents_only'`, and records nothing (platform
+  pre-main, core/consentbridge/grant_cap.go). It used to fall through to
+  `kind: 'conflict'` — this SDK's word for a duplicate. It now carries
+  `reasonCode`, `limitKey`, `details` and `recorded: false`, is never retried,
+  and fires no `consent.changed`. The DEPA ingest's
+  `ARTEFACT_NOT_ACCEPTED_PLAN_LIMIT` maps to the same class.
+  `ConsenteraErrorKind` gains `'plan_limit'`: an exhaustive `switch` on `kind`
+  needs the new case.
+
+## Detail (2.0.0) — renewal request wire correction
 
 Existing `renewBulk(principalId, purposeIds, noticeHash, uiEventId, options)`
 keeps its call signature and maps purpose IDs to the platform's `renewals`
@@ -8,12 +123,7 @@ argument remains accepted but is not a server-stored renewal field. Exported
 request types now describe these actual wire bodies. Response metadata and
 idempotency/cancellation options remain available.
 
-# Changelog
-
-All notable changes to `@consentera/consent-sdk`.
-This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## Unreleased — callback status contract (not published)
+## Detail (2.0.0) — callback status contract
 
 ### Changed
 
@@ -47,7 +157,7 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **`CallbackStatus` no longer includes `'expired'`.** Nothing on the platform
   produced it; a return URL saying `status=expired` is now `unverified`.
 
-## Unreleased — M4 integration
+## Detail (2.0.0) — M4 integration
 
 ### Changed
 

package/README.md

@@ -259,6 +259,19 @@ if (await ce.consent.isAllowed({ data_principal_identifiers: { email } }, 'produ
 the next call can name the person by `{ data_principal_id }` and send no
 identifier at all.
 
+**A DENY that is still catching up.** Right after the person grants, the
+platform can still be applying that grant, and until it has, validate answers
+from the state it recorded before, typically a DENY. From platform `936715ad71`
+the answer says so: `applied` is false and `retry_after` gives the seconds to
+wait before asking again. That flag is true on every other answer, and on a
+platform older than that commit (the field is absent there). A newer *refusal*
+is never pending: it decides at once. Treat an unapplied DENY as "not yet", not
+as "no": keep processing off, and ask again. `ce.consent.validate(who,
+'product_analytics', { retryWhenPending: true })` waits `retry_after` (1 s if
+none was sent, capped at 5 s), asks once more and returns that second answer,
+whatever it says. The re-ask is off by default. Bulk results carry both fields
+but are not re-asked.
+
 ### Naming a Data Principal
 
 `data_principal_identifiers` is an **open map keyed by your organisation's own
@@ -387,6 +400,49 @@ withdraw, …) remain server-to-server and go through `proxyEndpoint` in a brows
 
 ---
 
+## Base URL and path prefixes
+
+`apiEndpoint` and `proxyEndpoint` may carry a path prefix
+(`https://gw.corp.example/consentera`); the prefix is kept. Trailing slashes are
+trimmed once, when the configuration is read, so `https://x/prefix/` and
+`https://x/prefix` send the same request and no request carries `//`.
+
+Against `apiEndpoint` the SDK appends `/api/v1/public/...` (consent roads) and
+`/api/v1/cookie-consent/...` (the cookie banner). That `/api/v1` route prefix is
+fixed and not configurable. Through `proxyEndpoint` it appends only the SDK path
+(`/consent/...`, `/df/...`), so your proxy chooses the upstream path — that is
+the way to target a gateway that re-maps `/api/v1`. The root README, "Base URLs,
+gateway prefixes and the fixed route prefix", has the rule for every SDK.
+
+### The drop-in notice widget (`consentera-notice-widget.js`)
+
+**Set `data-api-base`.** Without it the widget falls back to deriving the base
+from its own `src`, and that fallback is **deprecated**. When the src has the
+platform's form `<API base>/sdk/<file>`, everything before `/sdk/` is used, so a
+gateway prefix is kept. Any other src is ambiguous and only its **origin** is
+used. That is wrong whenever the file is self-hosted or served from a CDN,
+because the requests then go to the CDN. The widget logs one `console.warn`
+(`set data-api-base; deriving from the script src is deprecated`). An inline
+copy with neither the attribute nor an http(s) `src` logs
+`[consentera-notice] data-api-base is required`, emits
+`consentera:notice-error`, and makes **no** network call.
+
+```html
+<div id="consentera-notice"></div>
+<script
+  src="https://cdn.your-site.example/consentera-notice-widget.js"
+  data-api-base="https://<your Consentera API host>[/<gateway prefix>]"
+  data-tenant-code="<your tenant code>"
+  data-slug="<consent page slug>"
+></script>
+```
+
+A path prefix in `data-api-base` is kept on every call. The hand-over to the
+hosted consent page uses the server's URL exactly as sent when it is absolute;
+a relative one is resolved under `data-api-base`, prefix included.
+
+---
+
 ## Reliability
 
 Every request carries a deadline, retries safely, and can be cancelled.
@@ -431,6 +487,39 @@ try {
 
 Switch on `kind` (closed, exhaustive); read `code` for the platform's exact word.
 
+### When the organisation's plan cannot take a new consent
+
+`consent.update()` (and `grant()` / `deny()`, which call it) throws
+**`ConsenteraPlanLimitError`** — `kind: 'plan_limit'`, `code: 'PLAN_LIMIT_REACHED'`,
+`status: 409`, `reasonCode: 'new_consents_only'` — when the change would add a
+**new** (data principal, purpose) grant past the plan's `consents_max`.
+**Nothing was recorded**, no `consent.changed` event fires, and the SDK does not
+retry it (the same request gets the same answer until the plan changes).
+
+```ts
+import { ConsenteraPlanLimitError } from '@consentera/consent-sdk';
+
+try {
+  await ce.consent.grant(principalId, [purposeId], noticeContext);
+} catch (err) {
+  if (err instanceof ConsenteraPlanLimitError) {
+    // NOT the person's refusal — never store or show it as "denied".
+    // Leave their existing choices as they were and tell them, neutrally,
+    // that this organisation can't accept new consents right now
+    // (err.message is the platform's person-facing sentence).
+    showNotice(err.message);
+    return;
+  }
+  throw err;
+}
+```
+
+A denial, a withdrawal, a renewal and a re-grant of a purpose the person already
+holds are never refused, and creating a session is never refused. On the hosted
+page (`collect` popup / redirect) the platform shows the person the message
+itself and fires no callback, so the popup resolves `dismissed` when they close
+it — never `denied`.
+
 ## Privacy defaults
 
 - **`collectContext: 'minimal'`** by default: platform, device type, browser
@@ -447,8 +536,8 @@ Switch on `kind` (closed, exhaustive); read `code` for the platform's exact word
 Every request carries the pair agreed across all six Consentera SDKs:
 
 ```
-User-Agent:        ConsenteraSDK/2.0.0 (<platform>; <runtime>)
-X-Consentera-SDK:  js/2.0.0
+User-Agent:        ConsenteraSDK/2.1.0 (<platform>; <runtime>)
+X-Consentera-SDK:  js/2.1.0
 ```
 
 `ConsenteraSDK/<version>` is the form the platform's audit pipeline already

package/dist/consentera-consent.cjs

@@ -1749,6 +1749,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',
@@ -1857,6 +1866,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,
@@ -1867,6 +1911,7 @@ const KIND_CLASS = {
     not_found: ConsenteraNotFoundError,
     conflict: ConsenteraConflictError,
     rate_limit: ConsenteraRateLimitError,
+    plan_limit: ConsenteraPlanLimitError,
     server: ConsenteraServerError,
     network: ConsenteraNetworkError,
     timeout: ConsenteraTimeoutError,
@@ -1876,7 +1921,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 {};
@@ -1884,16 +1929,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,
@@ -1936,7 +1985,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}`;
@@ -1944,8 +1993,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
@@ -2047,7 +2096,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'));
@@ -2069,16 +2118,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
@@ -2300,7 +2368,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`);
@@ -2379,7 +2447,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();
@@ -3688,6 +3758,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;
@@ -3716,7 +3836,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.
@@ -3739,7 +3871,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,
@@ -3854,6 +3989,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 = {
@@ -3963,7 +4108,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,
@@ -3982,7 +4127,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,
@@ -3995,6 +4140,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
@@ -4883,6 +5047,7 @@ exports.ConsenteraIdentityError = ConsenteraIdentityError;
 exports.ConsenteraNetworkError = ConsenteraNetworkError;
 exports.ConsenteraNotFoundError = ConsenteraNotFoundError;
 exports.ConsenteraPermissionError = ConsenteraPermissionError;
+exports.ConsenteraPlanLimitError = ConsenteraPlanLimitError;
 exports.ConsenteraRateLimitError = ConsenteraRateLimitError;
 exports.ConsenteraServerError = ConsenteraServerError;
 exports.ConsenteraTimeoutError = ConsenteraTimeoutError;
@@ -4899,6 +5064,7 @@ exports.SDK_NAME = SDK_NAME;
 exports.SDK_PLATFORM = SDK_PLATFORM;
 exports.SDK_VERSION = SDK_VERSION;
 exports.TCFManager = TCFManager;
+exports.VALIDATE_PENDING_RETRY_CAP_SECONDS = VALIDATE_PENDING_RETRY_CAP_SECONDS;
 exports.buildClientContext = buildClientContext;
 exports.claimedCallbackStatus = claimedCallbackStatus;
 exports.default = ConsentEraConsent;
@@ -4907,6 +5073,7 @@ exports.isBrowser = isBrowser;
 exports.isSecretKey = isSecretKey;
 exports.isSiteKey = isSiteKey;
 exports.newRequestId = newRequestId;
+exports.normalizeValidateResponse = normalizeValidateResponse;
 exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.principalBody = principalBody;
 exports.readDecisionMessage = readDecisionMessage;