@consentera/consent-sdk 2.0.0

package/dist/types/types/consent-lifecycle.d.ts

@@ -0,0 +1,804 @@
+/**
+ * ConsentEra Consent SDK — Consent Lifecycle Types
+ * Types matching the ConsentEra Go API request/response shapes
+ */
+import type { RetryPolicy } from '../core/http';
+import type { ContextMode } from '../utils/context';
+export interface ConsentEraClientConfig {
+    /** Secret API key for server-side use (tiq_live_*). Do NOT embed in frontend code. */
+    apiKey?: string;
+    /** Public site key for frontend use (tiq_pub_*). Safe to embed in client-side code. */
+    siteKey?: string;
+    /**
+     * Your tenant id. REQUIRED with `apiEndpoint` (direct mode), where it is sent
+     * as X-Tenant-Id. OPTIONAL with `proxyEndpoint`: your server holds the key and
+     * the key names the tenant, and the SDK sends no tenant header through a proxy
+     * (SDK register WEB-036).
+     */
+    tenantId?: string;
+    /** ConsentEra API base URL (for direct mode, e.g. 'http://localhost:8080') */
+    apiEndpoint?: string;
+    /** Proxy endpoint (for proxy mode, e.g. '/api/consentera') — API key injected server-side */
+    proxyEndpoint?: string;
+    /**
+     * Absolute URL to redirect back to after consent collection. createSession
+     * adds this SDK's own `state` to it (the callback binding), so `state` is
+     * reserved: a URL that already carries one is refused.
+     */
+    callbackUrl?: string;
+    /**
+     * Default language for the consent session. It is sent as the wire field
+     * `language`; when it is absent NOTHING is sent, which means the TENANT'S
+     * own default language.
+     *
+     * THE WIRE NAME IS `language` SINCE U58. It was `locale_pref`, and
+     * `notice_language` and `template_language` stood beside it — three fields
+     * for one question. The API decodes exactly one now
+     * (`core/dpintake/dpintake.go:109`) and the other three are deleted from the
+     * request struct. A caller still sending them has them dropped in silence,
+     * because the handler decodes without `DisallowUnknownFields`.
+     */
+    language?: string;
+    /** Enable debug logging. Never logs a request or response BODY — see core/http.ts. */
+    debug?: boolean;
+    /** Custom headers to include in every request. Can be a static object or a function for dynamic values. */
+    customHeaders?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Allow a SECRET `apiKey` although a `window` exists. Refused by default —
+     * see the header of core/ConsentEraClient.ts. Every request then warns.
+     */
+    unsafeAllowSecretKeyInBrowser?: boolean;
+    /** Per-request deadline in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Retry policy: attempts (default 3), baseDelayMs (250), maxDelayMs (4000). */
+    retry?: Partial<RetryPolicy>;
+    /**
+     * How much browser environment travels with a consent mutation.
+     * Default `minimal`; 1.x behaved as `full` with no way to turn it off.
+     */
+    collectContext?: ContextMode;
+    /**
+     * Last look at every request body before it leaves. Return the body to send;
+     * return null to refuse the call (which raises, never sends nothing quietly).
+     */
+    beforeSend?: (req: {
+        method: string;
+        path: string;
+        body: unknown;
+    }) => unknown | null;
+    /** Inject a fetch implementation (tests, a polyfill, a traced fetch). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Verify the platform's `sig` on a consent callback. The signing key is the
+     * DF's callback_signing_secret and must NOT be in a browser, so in a browser
+     * this calls your own server. See {@link CallbackSignatureVerifier}.
+     */
+    verifyCallbackSignature?: import('../consent/CallbackHandler').CallbackSignatureVerifier;
+    /**
+     * How long the callback road waits for the consent artifact to become
+     * readable. It is written asynchronously after submit (5.2–10.8s measured),
+     * so a read at callback time 404s. Default 15000; 0 disables the wait and
+     * returns `pending` at once.
+     */
+    artifactWaitMs?: number;
+}
+/**
+ * `data_principal` — the person's identifiers, KEYED BY THE FIELD NAMES OF THE
+ * TENANT'S LOCKED INTEGRATION KEY.
+ *
+ * A MAP AND NOT AN INTERFACE, and that is the point, not a shortcut. The
+ * admissible key set is a PER-TENANT fact the platform reads at request time:
+ * a tenant keyed on `{email, mobile}` accepts exactly `email` and `mobile`. A
+ * closed interface would have to name every identifier type the platform
+ * knows, and then every tenant's request object would carry every OTHER
+ * tenant's fields as optional — which is the second, unchecked identifier door
+ * U58 exists to delete. The server's own type is
+ * `map[string]string` (`core/dpintake/dpintake.go:82`).
+ *
+ * THE TYPE COMES FROM THE FIELD NAME. There is no declared type to disagree
+ * with the value and no shape to guess from, so `data_principal_ref_type` and
+ * the shape-guesser behind it are both gone. A vernacular spelling is NOT
+ * folded any more either: on a tenant keyed on `{email, mobile}`, `phone` is an
+ * UNKNOWN FIELD (400 `UNKNOWN_IDENTIFIER_FIELD`, which lists the allowed
+ * fields) rather than a spelling of `mobile`.
+ *
+ *   { email: 'riya@example.in' }
+ *   { customer_id: 'CUST-90210', mobile: '+919876500000' }
+ */
+export type DataPrincipal = Record<string, string>;
+/**
+ * `age` — the ONE age signal, and it is a date.
+ *
+ * `is_minor`, `is_declared_adult` and `self_declared_adult` are deleted from
+ * this request, because a flag cannot graduate anyone at eighteen: a person
+ * marked `is_minor` in March is still marked one the following March, while a
+ * date of birth answers the question again every time it is asked. The date is
+ * SERVER-AUTHORITATIVE — the platform derives the age and is never told it
+ * (`core/dpintake/dpintake.go:92-94`).
+ */
+export interface Age {
+    /**
+     * `YYYY-MM-DD` and nothing else. Any other format, a future date, or an
+     * implausible one is refused 400 `INVALID_DATE_OF_BIRTH`.
+     *
+     * SEND IT. With no date the person's age is UNKNOWN — the session is still
+     * created and the response carries a warning, because the consequence is
+     * otherwise invisible: purposes restricted for children are refused, and if
+     * this person IS a child no parental consent can be sought.
+     *
+     * If the date IS a child's, the request must also carry a guardian channel
+     * (`guardian_email` or `guardian_phone`) or it is refused 412
+     * `GUARDIAN_REQUIRED`.
+     */
+    date_of_birth?: string;
+}
+/**
+ * Session-create request — POST /api/v1/public/consent/sessions
+ *
+ * ─── U58 (IK-WIRE): THIS IS A PUBLIC WIRE BREAK ───────────────────────────
+ *
+ * The identity, age and language halves of this body are the platform's
+ * `core/dpintake.Object`, EMBEDDED in the request struct
+ * (`consent/collection.go:152`), so `data_principal`, `data_principal_id`,
+ * `age` and `language` decode at the TOP LEVEL. The same four fields identify
+ * a person on all four consent-collection roads — the hosted page, the kiosk,
+ * QR identify and this endpoint.
+ *
+ * WHAT WENT, AND WHY:
+ *
+ *   data_principal_ref, data_principal_ref_type
+ *       -> data_principal. THE TYPE COMES FROM THE FIELD NAME.
+ *   data_principal_details.{email,phone,customer_id,aadhaar,pan}
+ *       -> deleted. A second, unchecked identifier door: these became refs
+ *          ALONGSIDE data_principal_ref, judged against no scheme.
+ *   data_principal_details.name          -> read by nothing.
+ *   data_principal_details.guardian_ref  -> names a DIFFERENT person; the
+ *          guardian channel below replaces it.
+ *   is_minor, is_declared_adult          -> age.date_of_birth.
+ *   locale_pref, notice_language, template_language -> language.
+ *   purpose_ids                          -> deleted. The NOTICE decides the
+ *          purposes (DPDP §5); the field bought only a fail-fast 400 on ids
+ *          that were never going to be used.
+ *
+ * THERE IS NO OVERLAP WINDOW. The handler decodes with a plain `json.Decoder`
+ * and NO `DisallowUnknownFields` on both wires, so a body in the other shape is
+ * not refused for being the other shape — its identifiers are dropped without a
+ * word and the request is then refused for carrying none. This SDK version
+ * talks to an API carrying U58 and to no other.
+ *
+ * IDENTITY IS REQUIRED AND THE TYPE SAYS SO. Send `data_principal` (the
+ * identifiers) or `data_principal_id` (the platform's own uuid for the person,
+ * returned by every session create), or both — sent together they must agree,
+ * or the call is refused 409 `IDENTITY_MISMATCH`. A request carrying neither
+ * falls to the key's floor (400 `IDENTIFIER_REQUIRED`), so the union below
+ * makes that a COMPILE error instead of a round trip.
+ */
+export type CreateSessionRequest = CreateSessionRequestFields & ({
+    data_principal: DataPrincipal;
+    data_principal_id?: string;
+} | {
+    data_principal?: DataPrincipal;
+    data_principal_id: string;
+});
+/** The non-identity half of {@link CreateSessionRequest}. */
+export interface CreateSessionRequestFields {
+    /**
+     * The person's identifiers, by the field names of this organisation's locked
+     * integration key. See {@link DataPrincipal}.
+     *
+     * A field outside the key is refused 400 `UNKNOWN_IDENTIFIER_FIELD` and the
+     * message LISTS the allowed fields, because an integrator cannot read the key
+     * from outside. Too few of them is 400 `IDENTIFIER_REQUIRED`, whose message
+     * names the fields and never the mode.
+     */
+    data_principal?: DataPrincipal;
+    /** The platform's own uuid for the person, from any previous CreateSessionResponse. */
+    data_principal_id?: string;
+    /** The ONE age signal. See {@link Age}. */
+    age?: Age;
+    /**
+     * Preferred language for the consent page, as an ISO code. It goes to the
+     * FRONT of the locale fallback chain, AHEAD of the tenant's own default — so
+     * send it only when a language was actually asked for. A language the
+     * platform does not serve is refused 400 `UNSUPPORTED_LANGUAGE`, and that
+     * message names the list.
+     *
+     * ONE FIELD. It replaces `locale_pref`, `notice_language` and
+     * `template_language` together.
+     */
+    language?: string;
+    session_ref?: string;
+    notice_internal_name?: string;
+    /**
+     * Bind exactly this version NUMBER of the notice code, which must be active;
+     * omit to bind the code's default version.
+     *
+     * This field was `notice_version_id` (a UUID string) and the API has never
+     * had such a key: it decoded into nothing and was silently dropped, so every
+     * caller that set it silently got the default version and no error.
+     */
+    notice_version_number?: number;
+    ui_mode?: 'redirect' | 'embedded_popup' | 'embedded_page' | 'api_only';
+    /** Absolute return URL. createSession adds its own `state` to it; `state` is reserved. */
+    callback_url?: string;
+    /** HMAC-signed token from a campaign SMS URL, linking this session to an existing customer record. */
+    customer_token?: string;
+    /** Where the guardian's verification request is sent. Not with `guardian_phone`. */
+    guardian_email?: string;
+    /** Where the guardian's verification request is sent. Not with `guardian_email`. */
+    guardian_phone?: string;
+    /**
+     * What the child SAYS the guardian is to them ('mother', 'father', 'legal
+     * guardian', …). Recorded as a CLAIM on the pending link and confirmed or
+     * corrected by the guardian themselves on the verification road; nothing
+     * downstream treats it as proven.
+     *
+     * There is no `guardian_name`: a name is a claim about a second person made
+     * by somebody else, held in the child's own record, with no way to reach them
+     * and nobody able to correct it.
+     */
+    guardian_relationship?: string;
+}
+/**
+ * Session-create response.
+ *
+ * THE FIELD NAMES ARE NOT UNIFORM AND THAT IS THE WIRE, not a transcription
+ * error here: `expiresAt`, `languageCode` and `challengeNonce` are camelCase on
+ * the wire and the rest are snake_case. They are pinned that way in the API's
+ * own struct as an entrenched contract
+ * (`consent/collection.go:238-260`, `canonical-field:waive`).
+ */
+export interface CreateSessionResponse {
+    consent_session_id: string;
+    /** Always returned, so a caller can store it and send it next time. */
+    data_principal_id: string;
+    consent_url: string;
+    /** camelCase on the wire. */
+    expiresAt: string;
+    notice_version_id: string;
+    notice_hash: string;
+    /** The language the session actually resolved to. camelCase on the wire. */
+    languageCode: string;
+    /** camelCase on the wire. */
+    challengeNonce: string;
+    ui_schema_version: string;
+    /**
+     * Consequences that did not refuse the request — an unknown age, for one.
+     * Read them: the effect is otherwise invisible.
+     */
+    warnings?: string[];
+    /**
+     * Present when this session is a child's and an invitation went out to the
+     * guardian channel this request carried. The consent is NOT recorded until
+     * that guardian verifies.
+     */
+    guardian_verification?: GuardianVerificationPending;
+}
+/**
+ * The guardian invitation raised by a session create that carried a channel.
+ *
+ * IT CARRIES NO LINK AND NO TOKEN, deliberately. The verification URL is a
+ * bearer credential — address-bound, 72 hours, single use — and it goes to the
+ * guardian's own address. Returning it on this response would put it in the
+ * organisation's logs, and the organisation is not the party the link is for.
+ */
+export interface GuardianVerificationPending {
+    /** `'pending'`: the guardianship exists and nothing about it is proven yet. */
+    status: string;
+    /**
+     * Which channel the invitation went out on — `'email'` or `'sms'`. Never the
+     * address, which the organisation already has.
+     */
+    channel: string;
+    /** Names the guardianship, so it can be followed on the guardian APIs. */
+    link_id: string;
+}
+export interface SessionRenderResponse {
+    session_id: string;
+    notice: NoticeContent;
+    purposes: RenderPurpose[];
+    notice_details: NoticeDetails;
+    branding: BrandingConfig;
+}
+export interface NoticeContent {
+    title: string;
+    description: string;
+    version: string;
+}
+export interface RenderPurpose {
+    id: string;
+    code: string;
+    name: string;
+    description: string;
+    mandatory: boolean;
+    default_status: string;
+    sort_order: number;
+    legal_basis?: string;
+    retention_period?: string;
+}
+export interface NoticeDetails {
+    dpo_name?: string;
+    dpo_email?: string;
+    dpo_phone?: string;
+    grievance_url?: string;
+    privacy_policy_url?: string;
+}
+export interface BrandingConfig {
+    logo_url?: string;
+    primary_color?: string;
+    secondary_color?: string;
+    font_family?: string;
+}
+/**
+ * GET /v1/consent/artifacts/{artifact_id}.
+ *
+ * TRANSCRIBED FROM ArtifactDetailsResponse
+ * (consent/collection.go:4270-4278). It used to declare `data_principal_ref`,
+ * `notice_version_id`, `status` and `updated_at` — the API sends NONE of those
+ * four, so each read back `undefined` and nothing said so. `artifact_type` and
+ * `data_principal_id`, which it DOES send, were missing.
+ */
+export interface ConsentArtifact {
+    artifact_id: string;
+    artifact_version: number;
+    artifact_type: string;
+    /** The platform's own uuid for the person. The artifact names no identifier. */
+    data_principal_id: string;
+    purposes: ArtifactPurpose[];
+    created_at: string;
+}
+/**
+ * The 202 body of GET /v1/consent/artifacts/{artifact_id}?session_id=… — the
+ * consent WAS recorded and acknowledged, and its artifact is still being
+ * written (walk finding F018).
+ *
+ * Transcribed from ArtifactPendingResponse
+ * (consent/collection.go:4373-4400 at 4fda7e3d05). A DIFFERENT SHAPE FROM
+ * {@link ConsentArtifact} on purpose: a pending notice read as an artifact
+ * would be an artifact with no purposes, which looks like "consented to
+ * nothing". The status CODE is the platform's contract; `status: 'pending'`
+ * is the stable body discriminant beside it.
+ */
+export interface ArtifactPending {
+    status: 'pending';
+    /** The id that WILL carry this consent — the one the callback named. */
+    artifact_id: string;
+    /** The session the read presented, echoed. */
+    session_id: string;
+    /**
+     * Diagnostic, not the decision: `projection_pending`, `projection_committing`,
+     * or `parked_<reason>` when an operator owes the projection.
+     */
+    reason: string;
+    /**
+     * Seconds, as on the Retry-After header (1 while the worker owes it, 60 when
+     * parked). The wire name is `retry_after`.
+     */
+    retry_after: number;
+    /** Human-readable, and not a contract. */
+    message: string;
+}
+/**
+ * What an artifact read can answer, as a union the compiler makes you branch
+ * on. A 404 is not in it: that is a thrown ConsenteraNotFoundError, and with a
+ * `session_id` it means the id was never issued for that session.
+ */
+export type ArtifactReadResult = {
+    state: 'recorded';
+    artifact: ConsentArtifact;
+    requestId?: string;
+} | {
+    state: 'pending';
+    pending: ArtifactPending;
+    /** When to read again, from Retry-After (or `retry_after`), in ms. */
+    retryAfterMs: number;
+    requestId?: string;
+};
+export interface ArtifactPurpose {
+    purpose_id: string;
+    purpose_code: string;
+    purpose_name?: string;
+    status: ConsentStatus;
+    effective_at?: string;
+    expires_at?: string;
+    legal_basis?: string;
+}
+export type ConsentStatus = 'granted' | 'denied' | 'withdrawn' | 'not_set' | 'expired';
+/**
+ * `data_principal_identifiers` — how every consent LIFECYCLE road names a
+ * person.
+ *
+ * ─── IT IS THE SAME SHAPE AS `data_principal` ON SESSION CREATE (F015) ─────
+ *
+ * An OPEN map keyed by THE TENANT'S OWN LOCKED INTEGRATION KEY — the same
+ * `core/dpintake.DataPrincipal` create takes, validated by the same
+ * `dpintake.Validate` (consent/update_context.go:104-119). An earlier turn of
+ * this SDK typed it as a CLOSED five-field object; F015
+ * (consent/one-identifier-vocabulary-20260922) deleted that struct, because a
+ * closed struct has three faults a per-tenant vocabulary cannot carry:
+ *
+ *   * ONE VOCABULARY NOW, ONE SPELLING. The mobile atom is `mobile` on BOTH
+ *     roads. It used to be `phone` here and `mobile` on create, folded
+ *     server-side; F015 removed the fold, so `phone` is refused BY NAME
+ *     (400 UNKNOWN_IDENTIFIER_FIELD, "…This platform spells that identifier
+ *     'mobile': use mobile"). Do NOT send `phone`.
+ *   * THE ADMISSIBLE SET IS PER-TENANT, so this SDK cannot know it and must
+ *     NOT allow-list. A tenant keyed on `{customer_id}` names people by
+ *     `customer_id`; one keyed on `{email, mobile}` by those. Send the fields
+ *     the organisation locked; the SERVER answers UNKNOWN_IDENTIFIER_FIELD,
+ *     naming the field and listing the key\'s actual fields, when you get it
+ *     wrong. A closed type here would reject a legal key at compile time.
+ *   * THERE IS NO `pan` KEY. `pan` is an evidence-class identifier and can
+ *     never be a scheme field (tenant_identifier_scheme_types_chk, 00697), so
+ *     it is not an example and not a member of any allow-list.
+ *
+ * ─── THE KEY DIFFERS FROM CREATE; THE VALUE DOES NOT ──────────────────────
+ *
+ * Create spells the object `data_principal`; these roads keep
+ * `data_principal_identifiers`. Only the wire KEY differs — the value is the
+ * same open scheme-keyed map. The two answer different questions:
+ * `data_principal` on create MAY MINT a person, while this one is resolve-only
+ * and never creates anybody (lifecycle_identity.go). Unifying the key would be
+ * a wire break for every live integration.
+ *
+ * ANY ONE FIELD IS ENOUGH. A raw 12-digit `aadhaar` value is refused
+ * 400 INVALID_IDENTIFIER_FORMAT (F015 folded the old AADHAAR_RAW_REFUSED into
+ * the one format refusal create already answers); send the Aadhaar-LINKED
+ * token, never the number.
+ *
+ * THE REFUSALS A CALLER MEETS, all from the ONE validator create shares:
+ *   - `UNKNOWN_IDENTIFIER_FIELD`   400  a field outside the tenant's key, by
+ *                                       name, with the atom to use for a
+ *                                       vernacular spelling ("phone" -> mobile)
+ *   - `IDENTIFIER_REQUIRED`        400  nothing named a person
+ *   - `INVALID_IDENTIFIER_FORMAT`  400  a value that cannot be an identifier of
+ *                                       its type (raw Aadhaar lives here now)
+ *   - `SCHEME_NOT_CONFIGURED`      the organisation has not locked how it
+ *                                       identifies people, so no field means
+ *                                       anything yet
+ */
+export type DataPrincipalIdentifiers = Record<string, string>;
+/**
+ * POST /v1/consent/validate.
+ *
+ * ─── data_principal_ref IS REFUSED OUTRIGHT ──────────────────────────────
+ *
+ * Owner ruling, 2026-09-21: no transition period and no deprecation window
+ * (consent/lifecycle_identity.go:8-11). A request carrying it is answered
+ * 400 VALIDATION_ERROR whose message begins `DATA_PRINCIPAL_REF_REFUSED`
+ * (the one machine-readable token, lifecycle_identity.go:68) — and the refusal
+ * fires EVEN IF `data_principal_id` is also present, because two fields naming
+ * a person can disagree and the caller would never learn which one the answer
+ * was about.
+ *
+ * WHAT WAS WRONG WITH IT, since it is easy to get backwards: the old field was
+ * ONE OPAQUE UNTYPED HANDLE. An untyped value with no locked scheme to narrow
+ * it is fanned across every probe order, and under a two-identifier scheme a
+ * bare 12-digit value is undecidable between `aadhaar` and `customer_id` — so
+ * the spine refused it rather than guess, because guessing wrong writes a
+ * person split in two. This is OPAQUE HANDLE -> TYPED IDENTIFIERS.
+ *
+ * Name the person with `data_principal_id`, or with
+ * `data_principal_identifiers`; the union below makes sending neither a
+ * COMPILE error instead of a round trip.
+ */
+export type ValidateRequest = ValidateRequestFields & ({
+    data_principal_id: string;
+    data_principal_identifiers?: DataPrincipalIdentifiers;
+} | {
+    data_principal_id?: string;
+    data_principal_identifiers: DataPrincipalIdentifiers;
+});
+/** The non-identity half of {@link ValidateRequest}. */
+export interface ValidateRequestFields {
+    data_principal_id?: string;
+    data_principal_identifiers?: DataPrincipalIdentifiers;
+    purpose_code?: string;
+    purpose_id?: string;
+    /** Optional: validate against the purpose's allowed_channels. */
+    channel?: string;
+}
+/**
+ * POST /v1/consent/validate — the platform's answer, field for field.
+ *
+ * TRANSCRIBED FROM ValidateResponse (consent/validate.go:142-165 at
+ * 4fda7e3d05) and checked against a live answer from setup.consentera.in
+ * (fixtures/platform-wire/validate.200.allow.json). It used to lack
+ * `data_principal_id`, the field the platform returns so a caller can drop
+ * the identifiers on the next call, and which the runbook's validate step
+ * reads (SDK register WEB-037). It also declared an `artifact_id` that the
+ * platform never sends. That field is gone.
+ */
+export interface ValidateResponse {
+    decision: 'ALLOW' | 'DENY';
+    reason_code: ConsentReasonCode;
+    /** The platform's uuid for the person asked about. Hold it; later calls need no identifier. */
+    data_principal_id: string;
+    purpose_id: string;
+    /** Omitted by the platform when the purpose has no code. */
+    purpose_code?: string;
+    effective_at?: string;
+    expires_at?: string;
+    /** Server time of the decision. The request's own timestamp is ignored. */
+    validated_at: string;
+    /** DPDP §4 basis: `consent`, `legitimate_use`, … */
+    legal_basis?: string;
+    is_mandatory?: boolean;
+    /** The §7 / §17 limb invoked when decision is ALLOW and legal_basis is not consent. */
+    dpdp_exemption_basis?: string;
+    /** Human-readable, and not a contract. */
+    message?: string;
+}
+/**
+ * `reason_code` on a validate response — the DPDP reason the decision came out
+ * the way it did. Transcribed from the Reason* constants in
+ * consentera-api/internal/modules/consent/consent/validate.go.
+ *
+ * NOT A CLOSED UNION, and the `string` arm is not laziness: validate.go mints
+ * `"CONSENT_" + strings.ToUpper(currentStatus)` for any consent status it has
+ * no named constant for, so the set genuinely cannot be enumerated ahead of
+ * time. A closed union would make a legitimate response a type error.
+ *
+ * TWO MEMBERS THIS UNION USED TO CARRY WERE NOT REASON CODES.
+ * `PURPOSE_MANDATORY` appears nowhere in the platform — not in a Go file, not
+ * in a doc — and the code it was presumably meant to be is `PURPOSE_INACTIVE`.
+ * `CONSENT_NOT_FOUND` is real but belongs to a DIFFERENT vocabulary: it is an
+ * HTTP error code (apierrors/errors.go, a 404 on a receipt or a withdrawal),
+ * never a validate reason. The reason code for "no consent record exists" is
+ * `NO_CONSENT_FOUND`, which this union did not have — so the one outcome an
+ * integrator most needs to branch on was the one it could not name.
+ */
+export type ConsentReasonCode = 'CONSENT_GRANTED' | 'LEGITIMATE_USE' | 'LEGAL_OBLIGATION' | 'MEDICAL_EMERGENCY' | 'EMPLOYMENT_PURPOSE' | 'PUBLIC_INTEREST' | 'NO_CONSENT_FOUND' | 'CONSENT_DENIED' | 'CONSENT_WITHDRAWN' | 'CONSENT_EXPIRED' | 'CONSENT_NOT_EFFECTIVE' | 'CONSENT_PENDING_CONFIRMATION' | 'DATA_PRINCIPAL_NOT_FOUND' | 'PURPOSE_INACTIVE' | 'MINOR_NO_GUARDIAN' | 'CHANNEL_NOT_ALLOWED' | 'LU_CONTRACT_LAPSED' | (string & {});
+/**
+ * POST /v1/consent/validate/bulk.
+ *
+ * `data_principal_ref` AND `data_principal_refs` are both refused, with the
+ * same `DATA_PRINCIPAL_REF_REFUSED` prefix (consent/validate.go:249,257).
+ * One person by `data_principal_id` or `data_principal_identifiers`; many by
+ * `data_principal_ids` or `data_principal_identifiers_list`.
+ */
+export type BulkValidateRequest = BulkValidateRequestFields & ({
+    data_principal_id: string;
+} | {
+    data_principal_identifiers: DataPrincipalIdentifiers;
+} | {
+    data_principal_ids: string[];
+} | {
+    data_principal_identifiers_list: DataPrincipalIdentifiers[];
+});
+/** The non-identity half of {@link BulkValidateRequest}. */
+export interface BulkValidateRequestFields {
+    /** One person. */
+    data_principal_id?: string;
+    data_principal_identifiers?: DataPrincipalIdentifiers;
+    /** Many people, one per element. */
+    data_principal_ids?: string[];
+    data_principal_identifiers_list?: DataPrincipalIdentifiers[];
+    purpose_codes?: string[];
+    purpose_code?: string;
+    purpose_id?: string;
+}
+/** BulkValidateResponse (consent/validate.go:290-295). */
+export interface BulkValidateResponse {
+    results: ValidateResponse[];
+    total_count: number;
+    allow_count: number;
+    deny_count: number;
+}
+export interface UpdateContextResponse {
+    data_principal_id: string;
+    consents: ConsentContextItem[];
+    notice_version_id: string;
+    notice_hash: string;
+    language_code: string;
+}
+export interface ConsentContextItem {
+    purpose_id: string;
+    purpose_code?: string;
+    purpose_name: string;
+    current_status: ConsentStatus;
+    mandatory: boolean;
+    withdrawable: boolean;
+    last_updated_at?: string;
+    artifact_id?: string;
+    artifact_version?: number;
+}
+export interface UpdateConsentRequest {
+    data_principal_id: string;
+    notice_version_id: string;
+    notice_hash: string;
+    language_code?: string;
+    updates: ConsentUpdate[];
+    affirmative_action: AffirmativeAction;
+    client_context?: ClientContext;
+}
+export interface ConsentUpdate {
+    purpose_id: string;
+    new_status: 'granted' | 'denied';
+}
+export interface WithdrawalContextResponse {
+    data_principal_id: string;
+    consents: ConsentContextItem[];
+    notice_version_id: string;
+    notice_hash: string;
+}
+export interface WithdrawRequest {
+    data_principal_id: string;
+    purposes: string[];
+    reason?: string;
+    affirmative_action: AffirmativeAction;
+    client_context?: ClientContext;
+}
+export interface BulkWithdrawRequest {
+    data_principal_id: string;
+    purposes: string[];
+    reason?: string;
+    affirmative_action: AffirmativeAction;
+    client_context?: ClientContext;
+}
+export interface RenewalContextResponse {
+    data_principal_id: string;
+    expiring_consents: ExpiringConsent[];
+    notice_version_id: string;
+    notice_hash: string;
+}
+export interface ExpiringConsent {
+    purpose_id: string;
+    purpose_name: string;
+    current_status: ConsentStatus;
+    expires_at: string;
+    days_remaining: number;
+    renewable: boolean;
+}
+export interface RenewRequest {
+    data_principal_id: string;
+    purpose_ids: string[];
+    notice_hash: string;
+    /** Client observation time; the server owns the recorded time. */
+    captured_at?: string;
+    client_context?: ClientContext;
+}
+/** The canonical renewal evidence returned by the existing renewal roads. */
+export interface RenewedConsentInfo {
+    purpose_id: string;
+    previous_expiry?: string;
+    new_expiry?: string;
+}
+export interface RenewResponse {
+    /** Present when durable acceptance is awaiting the canonical stored artifact. */
+    status?: 'pending';
+    /** Server guidance for the existing bound artifact GET; never repeat the POST. */
+    retry_after_seconds?: number;
+    artifact_id: string;
+    artifact_version: number;
+    data_principal_id: string;
+    renewed_consents: RenewedConsentInfo[];
+    /** Existing artifact-read binding; retain it when the POST is accepted with 202. */
+    session_id?: string;
+    /** Only present when the server returned the canonical stored artifact hash. */
+    integrity_hash?: string;
+}
+export interface BulkRenewResponse extends RenewResponse {
+    success_count: number;
+    failure_count: number;
+    failed_renewals?: Array<{
+        purpose_id: string;
+        error: string;
+    }>;
+}
+export interface BulkRenewRequest {
+    data_principal_id: string;
+    renewals: Array<{
+        purpose_id: string;
+        new_expiry_days?: number;
+    }>;
+    notice_hash: string;
+    /** Client observation time; the server owns the recorded time. */
+    captured_at?: string;
+    client_context?: ClientContext;
+}
+export interface AffirmativeAction {
+    type: 'button' | 'toggle' | 'checkbox';
+    ui_event_id: string;
+    captured_at: string;
+}
+export interface ClientContext {
+    ip?: string;
+    user_agent?: string;
+    platform: 'web' | 'mobile' | 'api';
+    device_type?: 'desktop' | 'mobile' | 'tablet';
+    screen_resolution?: string;
+    timezone?: string;
+    browser_name?: string;
+    browser_version?: string;
+    os_name?: string;
+    os_version?: string;
+    session_id?: string;
+    page_url?: string;
+    referrer?: string;
+}
+export interface DFConfig {
+    tenant_id: string;
+    tenant_name: string;
+    purposes: DFPurpose[];
+    notices: DFNotice[];
+    regulations: string[];
+    languages: string[];
+    branding: BrandingConfig;
+}
+export interface DFPurpose {
+    id: string;
+    code: string;
+    name: string;
+    description: string;
+    category: string;
+    mandatory: boolean;
+    default_status: string;
+    retention_period?: string;
+    legal_basis?: string;
+    sort_order: number;
+}
+export interface DFNotice {
+    id: string;
+    internal_name: string;
+    title: string;
+    version: string;
+    status: string;
+}
+export interface NoticePurposesResponse {
+    notice_id: string;
+    notice_internal_name: string;
+    notice_title: string;
+    notice_version: string;
+    purposes: NoticePurpose[];
+}
+export interface NoticePurpose {
+    id: string;
+    code: string;
+    name: string;
+    description: string;
+    mandatory: boolean;
+    sort_order: number;
+    legal_basis?: string;
+    retention_period?: string;
+    data_categories?: string[];
+}
+/**
+ * POST /v1/df/principal-token.
+ *
+ * THIS ROAD STILL TAKES data_principal_ref, AND THAT IS CORRECT — do not
+ * "fix" it. It lives in identity/dfclient (handlers.go:1418-1428), not in the
+ * consent module, so the 2026-09-21 ruling that refuses the field across the
+ * consent surface does not reach it: it still accepts data_principal_id OR
+ * data_principal_ref and requires one of the two.
+ */
+export interface PrincipalTokenRequest {
+    data_principal_ref: string;
+    redirect_path?: string;
+}
+export interface PrincipalTokenResponse {
+    token: string;
+    redirect_url: string;
+    expires_in: number;
+}
+export interface WithdrawalAnalytics {
+    total_withdrawals: number;
+    by_purpose: Record<string, number>;
+    by_period: Record<string, number>;
+    reasons: WithdrawalReason[];
+}
+export interface WithdrawalReason {
+    reason: string;
+    count: number;
+    percentage: number;
+}
+export interface ApiResponse<T> {
+    data?: T;
+    error?: ApiError;
+}
+export interface ApiError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export type ConsentLifecycleEvent = 'session:created' | 'session:completed' | 'session:expired' | 'consent:validated' | 'consent:updated' | 'consent:withdrawn' | 'consent:renewed' | 'config:loaded' | 'principal:redirected' | 'error';