@consentera/react-native-consent 2.0.0

package/lib/typescript/src/session.d.ts

@@ -0,0 +1,600 @@
+/**
+ * What this SDK calls itself on the wire, in `X-Consentera-SDK`.
+ *
+ * ONE declaration. The Android and iOS twins each had an SDK_VERSION constant
+ * that no request builder ever read, which is the same as not having one.
+ */
+export declare const SDK_VERSION = "2.0.0";
+export declare const SDK_IDENTIFIER = "react-native/2.0.0";
+/**
+ * The User-Agent the platform's audit coarsening actually parses.
+ *
+ * THE PLATFORM PARSES User-Agent, SO THAT IS WHERE THE VERSION GOES.
+ *
+ * consentera-api/internal/core/audit/user_agent_coarsening_test.go:39-40 drives
+ * CoarsenUserAgent with `ConsenteraSDK/2.3.1 (Android 14; SM-G991B; build 4471)`
+ * and asserts it coarsens to `ConsenteraSDK/2` — the platform has a rule, a test
+ * and an audit consequence for exactly that spelling. The other string in the
+ * platform tree, `consentera-sdk/1.2` (validation_envelope_test.go:233), is an
+ * inert fixture with no parser behind it. So `ConsenteraSDK/<version>` is the one
+ * that is agreed by evidence rather than by preference; raised with the platform
+ * lane as MANIFEST-CORRECTIONS M-11.
+ *
+ * AND X-Consentera-SDK STAYS, because the two answer different questions.
+ * User-Agent is DELIBERATELY COARSENED into the audit record — `ConsenteraSDK/2`
+ * is all that survives, which is the point: an audit row must not carry a
+ * fingerprint of the person's device. A support ticket needs the exact build, and
+ * that is what the custom header carries, outside the audit trail.
+ */
+export declare const SDK_USER_AGENT = "ConsenteraSDK/2.0.0 (react-native)";
+/**
+ * `Retry-After` in either RFC 9110 form — delta-seconds, or an HTTP-date — as
+ * milliseconds, or null when the header is absent or unparseable.
+ *
+ * Capped at 60s: a server that asks for an hour is not something a consent UI
+ * can wait out, and the caller's own deadline should decide.
+ */
+export declare function parseRetryAfter(header: string | null | undefined, now?: number): number | null;
+/**
+ * A typed error with the status, the canonical code and the request id.
+ *
+ * Errors used to be `new Error(\`Consentera \${path} \${status}: \${body}\`)` — a
+ * string, with the response body interpolated into the message (where it could
+ * carry the person's own identifiers into whatever the host logs), and nothing
+ * a caller could switch on.
+ */
+export declare class ConsenteraError extends Error {
+    /** HTTP status, when this came from a non-2xx answer. */
+    readonly status?: number;
+    /** The platform's canonical error code, e.g. `VALIDATION_ERROR`. */
+    readonly code?: string;
+    /**
+     * The platform's own sentence for a refusal: the `message` of its
+     * `{code, message}` envelope, verbatim (SDK register MOB-042). It is what
+     * an app shows the person to say WHY: "\"phone\" is not one of this
+     * organisation's identifier fields — send email". It is kept out of
+     * `message`, like the rest of the body: `message` goes wherever the host
+     * logs, and this is a sentence for a screen. Undefined when the answer had
+     * no envelope, for example a proxy's HTML page.
+     */
+    readonly platformMessage?: string;
+    /** `X-Request-Id` off the response, for a support ticket. */
+    readonly requestId?: string;
+    /** True for a timeout or a transport failure — the call may be retried. */
+    readonly retryable: boolean;
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        platformMessage?: string;
+        requestId?: string;
+        retryable?: boolean;
+    });
+}
+/**
+ * The platform's error envelope, `{code, message}` (core/apierrors/errors.go
+ * APIError), read out of a response body. Tolerates the older
+ * `{error: {code, message}}` nesting. Never throws: a body that is not an
+ * envelope yields nothing.
+ */
+export declare function readErrorEnvelope(text: string): {
+    code?: string;
+    message?: string;
+};
+/**
+ * 160 bits from the platform CSPRNG, URL-safe, unpadded.
+ *
+ * REFUSES RATHER THAN DEGRADING. React Native ships no `crypto.getRandomValues`
+ * by default, and the obvious substitute — `Math.random` — is not a CSPRNG: this
+ * nonce is the only thing standing between a forged
+ * `myapp://consent/callback?status=granted` from another app and a host that
+ * believes it, so a predictable one is worse than none. Install
+ * `react-native-get-random-values` and import it once at the top of your entry
+ * file, which is what every RN crypto consumer already does.
+ */
+export declare function newCallbackState(): string;
+/** The one shape the SDK needs from whichever in-app browser the host installed. */
+export interface InAppBrowserAdapter {
+    /** Open `url`, intercept `redirectScheme`, resolve the URL or null on dismiss. */
+    openAuth(url: string, redirectScheme: string): Promise<string | null>;
+}
+/**
+ * Supply the in-app browser explicitly — for Expo, or for a host that already
+ * has one:
+ *
+ *     import * as WebBrowser from 'expo-web-browser';
+ *     setInAppBrowser({
+ *       openAuth: async (url, scheme) => {
+ *         const r = await WebBrowser.openAuthSessionAsync(url, scheme);
+ *         return r.type === 'success' ? r.url : null;
+ *       },
+ *     });
+ */
+export declare function setInAppBrowser(adapter: InAppBrowserAdapter | null): void;
+/**
+ * The injected adapter, else `react-native-inappbrowser-reborn` if the host
+ * installed it, else null — and null makes `presentConsent` THROW rather than
+ * fall back to `Linking.openURL`.
+ *
+ * The peer is resolved with a guarded `require` rather than a top-level import
+ * on purpose: a static import would make the peer mandatory for every consumer,
+ * including the ones that inject their own.
+ */
+export declare function resolveInAppBrowser(): InAppBrowserAdapter | null;
+export interface SessionConfig {
+    /**
+     * Your backend/proxy base, e.g. https://api.yourbank.in/consentera.
+     * REQUIRED, with no default: a blank or non-http(s) value throws
+     * `ConsenteraError` (`code: 'BACKEND_BASE_URL_REQUIRED'`) from the constructor.
+     */
+    backendBaseUrl: string;
+    /** Registered deep-link scheme (ops: ALLOWED_CALLBACK_APP_SCHEMES) */
+    callbackScheme: string;
+    callbackHost?: string;
+    callbackPath?: string;
+    /** Per-ATTEMPT timeout in ms (default 30000) — a dead backend fails fast. */
+    requestTimeoutMs?: number;
+    /**
+     * Ceiling on the whole call including retries (default 2x requestTimeoutMs).
+     * Without it, N retries multiply the caller's wait by N and a consent screen
+     * hangs for a minute and a half on a bad network.
+     */
+    totalTimeoutMs?: number;
+    /** Attempts INCLUDING the first (default 3). 1 disables retrying. */
+    maxAttempts?: number;
+    /** Full-jitter base delay in ms (default 250). */
+    retryBaseDelayMs?: number;
+    /**
+     * The identifier fields of your organisation's locked integration key, in
+     * the order you prefer them for signing a person in to the privacy portal —
+     * e.g. `['customer_id', 'mobile']`. Optional. {@link ConsenteraSession.openPortal}
+     * uses it to choose which ONE identifier to send when you pass it several;
+     * without it, pass exactly one (MOB-043).
+     */
+    identifierScheme?: string[];
+    /**
+     * Opt-in diagnostics sink. Undefined (the default) means the SDK is SILENT.
+     *
+     * It replaces a bare `console.warn`, which could not be turned off, redirected
+     * or levelled. Nothing PII-bearing is passed here: the messages name
+     * conditions, never values, and the transport deliberately keeps response
+     * bodies out of its errors for the same reason.
+     */
+    onDiagnostic?: (message: string) => void;
+}
+/**
+ * The deep link handed to the platform as `callback_url`, carrying `state`.
+ *
+ * THE STATE SURVIVES THE ROUND TRIP, AND THAT IS A PLATFORM FACT, not an
+ * assumption: `addRedirectParams` (consent/collection.go) appends with `&` when
+ * the callback URL already contains a `?`, so `myapp://consent/callback?state=X`
+ * comes back as `…?artifact_id=…&pending=1&session_id=…&state=X&status=…`
+ * (setRedirectParam re-encodes the query, so the keys arrive sorted). If that ever
+ * changes, `parseCallback` starts refusing every callback rather than silently
+ * accepting a forged one.
+ */
+export declare function callbackUrlFor(cfg: SessionConfig, state: string): string;
+/**
+ * THE STATUS VOCABULARY THE PLATFORM PUTS ON A CALLBACK — and only these.
+ *
+ * consent/collection.go (platform pre-main 35cd853ac7) derives it at
+ * :4094-4098 — `granted`; no purpose granted → `denied`; some denied →
+ * `partial` — and SETS it on the redirect at :4243. Any other value
+ * (`success`, `completed`, `expired`, a different case, none at all) did not
+ * come from the platform and is `unknown`: never read it as a grant.
+ */
+export type CallbackStatus = 'granted' | 'partial' | 'denied' | 'unknown';
+/** Map a raw `status` query value onto the platform's vocabulary. Exact match: the server writes lowercase. */
+export declare function callbackStatusOf(raw: string | null | undefined): CallbackStatus;
+/**
+ * Parsed from the deep link the hosted page redirects to on submit.
+ *
+ * A CALLBACK IS A HINT AND NEVER A DECISION. What `parseCallback` guarantees is
+ * narrower and still worth having: this callback came back to the deep link THIS
+ * SDK asked for, carrying the nonce THIS SDK generated.
+ */
+export interface ConsentCallback {
+    sessionId?: string;
+    artifactId?: string;
+    /** The raw `status` query value, exactly as it arrived. Prefer {@link callbackStatus}. */
+    status?: string;
+    /**
+     * `status` read against the platform's vocabulary: `granted`, `partial`
+     * (some purposes declined) or `denied`, else `unknown`. A HINT, not proof —
+     * confirm by reading the consent back through your backend (`validate`).
+     */
+    callbackStatus: CallbackStatus;
+    /**
+     * `pending=1` on the return (collection.go:4274, walk finding F018): the
+     * consent was recorded and its record is STILL BEING WRITTEN. The platform
+     * sets it on every capture. It is not signed and says nothing about whether
+     * a consent exists — it tells your backend to expect the read-back to wait
+     * (202 + Retry-After) rather than to treat an early miss as "no consent".
+     */
+    pending: boolean;
+    /**
+     * The nonce this SDK generated, echoed back by the platform and already
+     * compared against the expected value before this object was returned.
+     */
+    state?: string;
+    /**
+     * The platform's HMAC over (session_id, artifact_id, status), present only
+     * when the DF has a `callback_signing_secret` (collection.go:4175-4182).
+     *
+     * DO NOT VERIFY IT IN THE APP. Verifying needs the secret, and a secret in an
+     * app binary is not a secret. Send it to your own backend.
+     */
+    signature?: string;
+    /** Every query parameter, for logging. */
+    parameters: Record<string, string>;
+}
+export interface ConsentSession {
+    consent_session_id: string;
+    consent_url: string;
+    notice_hash?: string;
+    /**
+     * When this session stops being usable. Read it: a host that cannot see the
+     * expiry cannot decide whether to re-create rather than re-open. camelCase is
+     * the API's entrenched contract (collection.go:241).
+     */
+    expiresAt?: string;
+    /** The notice VERSION this session is bound to (collection.go:243). */
+    notice_version_id?: string;
+    /** The language the platform actually served, after its fallback chain. */
+    languageCode?: string;
+    /** The schema version the hosted page renders with (collection.go:247). */
+    ui_schema_version?: string;
+    /**
+     * The client-generated nonce this SDK put on the callback URL.
+     *
+     * NOT FROM THE SERVER — `createSession` sets it after parsing the response.
+     * `challengeNonce` is the SERVER's nonce for the render/submit legs and is a
+     * different value with a different job. It is not persisted: if the app is
+     * killed while the browser is open it is gone, which is the case
+     * resume-revalidate covers.
+     */
+    callbackState?: string;
+    /**
+     * camelCase on the wire, and that is the wire, not a transcription error:
+     * `expiresAt`, `languageCode` and `challengeNonce` are pinned camelCase in the
+     * API's own struct as an entrenched contract while the rest of the response is
+     * snake_case.
+     */
+    challengeNonce?: string;
+    /**
+     * The platform's own uuid for the person. Always returned — store it and send
+     * it as `dataPrincipalId` next time.
+     */
+    data_principal_id?: string;
+    /**
+     * Consequences that did not refuse the request. READ THEM: an unknown age, or
+     * a guardian channel whose invitation could not be sent, arrives here with a
+     * 200 and is otherwise invisible.
+     */
+    warnings?: string[];
+    /**
+     * Present when this session is a child's and an invitation went out to the
+     * guardian channel the request carried. The consent is NOT recorded until that
+     * guardian verifies.
+     */
+    guardian_verification?: GuardianVerificationPending;
+}
+/**
+ * The §9(1) state a child's session rests in while the guardian verifies.
+ *
+ * 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 here 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'`. */
+    channel: string;
+    /** Names the guardianship, so it can be followed on the guardian APIs. */
+    link_id: string;
+}
+/**
+ * `data_principal_identifiers` — how every consent LIFECYCLE road names a
+ * person.
+ *
+ * ─── IT IS THE SAME SHAPE AS `dataPrincipal` ON SESSION CREATE (F015) ─────
+ *
+ * An OPEN map keyed by THE TENANT'S OWN LOCKED INTEGRATION KEY — the same
+ * value `data_principal` carries on create (update_context.go:104-119).
+ * F015 (consent/one-identifier-vocabulary-20260922) deleted the earlier
+ * closed five-field object, because a closed struct cannot carry a per-tenant
+ * vocabulary:
+ *
+ *   * ONE VOCABULARY NOW, ONE SPELLING. The mobile atom is `mobile` on BOTH
+ *     roads; F015 removed the old server-side fold, so `phone` is refused BY
+ *     NAME (400 UNKNOWN_IDENTIFIER_FIELD, "…use mobile"). Do NOT send `phone`.
+ *   * THE ADMISSIBLE SET IS PER-TENANT, so this SDK cannot know it and must NOT
+ *     allow-list. Send the fields the organisation locked; the SERVER answers
+ *     UNKNOWN_IDENTIFIER_FIELD, naming the field, when you get it wrong.
+ *   * THERE IS NO `pan` KEY — it is evidence-class and can never be a scheme
+ *     field.
+ *
+ * Only the wire KEY differs from create (`data_principal` may mint a person,
+ * `data_principal_identifiers` resolves only). 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 that one refusal); send the
+ * Aadhaar-LINKED token, never the number.
+ */
+export type DataPrincipalIdentifiers = Record<string, string>;
+/**
+ * The ONE way a consent lifecycle road names a person.
+ *
+ * `data_principal_ref` is REFUSED OUTRIGHT since 2026-09-21 — no transition
+ * period (consent/lifecycle_identity.go:8-11) — and the refusal fires even when
+ * `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.
+ * A union makes the refused request unrepresentable rather than a round trip.
+ */
+export type PrincipalRef = {
+    dataPrincipalId: string;
+    dataPrincipalIdentifiers?: never;
+} | {
+    dataPrincipalIdentifiers: DataPrincipalIdentifiers;
+    dataPrincipalId?: never;
+};
+/** Turn a {@link PrincipalRef} into the body fields that name the person. */
+export declare function principalBody(who: PrincipalRef): Record<string, unknown>;
+/**
+ * The ONE identifier the portal road is sent, as `[kind, value]`.
+ *
+ * The map's only entry, or, when it has several, the first field of
+ * `scheme` that it carries. It throws (a ConsenteraError whose `code` is the
+ * one the server would use) rather than guess: an empty map is
+ * IDENTIFIER_REQUIRED, several entries and no scheme to choose by is
+ * IDENTIFIER_AMBIGUOUS, and `phone` is UNKNOWN_IDENTIFIER_FIELD.
+ */
+export declare function portalIdentifier(identifiers: DataPrincipalIdentifiers, scheme?: readonly string[]): [kind: string, value: string];
+export interface ConsentDecision {
+    decision: string;
+    reason_code?: string;
+    purpose_code?: string;
+    effective_at?: string;
+    expires_at?: string;
+}
+export interface PortalSession {
+    portal_url: string;
+    expires_in_seconds: number;
+    auto_provisioned: boolean;
+}
+export interface CreateSessionRequest {
+    /**
+     * The person's identifiers, KEYED BY THE FIELD NAMES OF YOUR ORGANISATION'S
+     * LOCKED INTEGRATION KEY — `{ email: 'riya@example.in' }`,
+     * `{ customer_id: 'CUST-90210', mobile: '+919876500000' }`.
+     *
+     * A MAP AND NOT A SET OF NAMED FIELDS (U58). The admissible key set is a
+     * PER-TENANT fact the platform reads at request time, and THE TYPE COMES FROM
+     * THE FIELD NAME: there is no declared type to disagree with the value and no
+     * shape to guess from. A field outside your key is refused 400
+     * UNKNOWN_IDENTIFIER_FIELD, whose message LISTS the allowed fields; too few of
+     * them is 400 IDENTIFIER_REQUIRED.
+     *
+     * NO SPELLING IS FOLDED ANY MORE. On a key of {email, mobile}, `phone` is an
+     * unknown field, not a spelling of `mobile`.
+     */
+    dataPrincipal?: Record<string, string>;
+    /** The platform's own uuid for the person, from any previous createSession response. */
+    dataPrincipalId?: string;
+    noticeInternalName: string;
+    /** Bind exactly this version NUMBER of the notice code; omit for its default version. */
+    noticeVersionNumber?: number;
+    sessionRef?: string;
+    /**
+     * YYYY-MM-DD, sent as `age.date_of_birth` (U58; it was
+     * `data_principal_details.date_of_birth`). Age is server-authoritative: the
+     * date is re-read every time, so a person graduates at eighteen without
+     * anyone updating a flag. Omit it and the person's age is UNKNOWN — the
+     * session is still created, and purposes restricted for children are then
+     * refused. A malformed or implausible date is refused 400
+     * INVALID_DATE_OF_BIRTH.
+     */
+    dateOfBirth?: string;
+    /**
+     * Preferred language for the consent page, sent as `language` — ONE field,
+     * replacing `locale_pref`, `notice_language` and `template_language`
+     * together (U58). It goes AHEAD of the tenant's own default in the server's
+     * fallback chain, so send it only when a language was actually asked for. A
+     * language the platform does not serve is refused 400 UNSUPPORTED_LANGUAGE.
+     */
+    language?: string;
+    /** Where the guardian's verification request is sent. Not with [guardianPhone]. */
+    guardianEmail?: string;
+    /** Where the guardian's verification request is sent. Not with [guardianEmail]. */
+    guardianPhone?: string;
+    /**
+     * What the child SAYS the guardian is to them ('mother', 'father', 'legal
+     * guardian', …). Recorded as a CLAIM and confirmed or corrected by the
+     * guardian on the verification road; nothing downstream treats it as proven.
+     */
+    guardianRelationship?: string;
+}
+export declare class ConsenteraSession {
+    private cfg;
+    constructor(cfg: SessionConfig);
+    /**
+     * ONE transport for every road.
+     *
+     * WHAT IT ADDS, and why each one:
+     *
+     *  * **Identity.** `X-Consentera-SDK: react-native/<version>` on every
+     *    request. Without it the platform cannot tell which SDK build produced a
+     *    failure, which is the first question on every support ticket.
+     *  * **Idempotency.** One key per OPERATION, not per attempt: a retried
+     *    mutation must not record a second consent or a second withdrawal. The key
+     *    is minted once per `post` call and reused across its retries.
+     *  * **Retry with backoff and FULL JITTER**, on 429, 5xx and transport
+     *    failures only. Never on a 4xx: a refused body is refused on every
+     *    attempt, and retrying it just spends the tenant's rate budget.
+     *  * **`Retry-After` is obeyed** when the server sends one, in either its
+     *    delta-seconds or HTTP-date form. The platform rate-limits these roads
+     *    (routes_consent.go:377,389,406,567), so this is not hypothetical.
+     *  * **Request id**, surfaced on the error rather than discarded.
+     *  * **A per-ATTEMPT timeout inside a per-CALL deadline**, so N retries cannot
+     *    silently multiply the caller's wait by N.
+     */
+    private post;
+    /**
+     * Sleep before the next attempt. Returns false when the call's deadline would
+     * be passed, in which case the caller throws instead of sleeping into it.
+     *
+     * FULL JITTER: `random(0, base * 2^n)`, the AWS architecture-blog form. A
+     * fixed backoff synchronises every client that failed on the same server
+     * event and reproduces the spike that caused it.
+     */
+    private backoff;
+    /**
+     * Create a consent session; returns the hosted collect URL.
+     *
+     *   createSession({
+     *     dataPrincipal: { email: 'riya@example.in' },
+     *     noticeInternalName: 'bnb_consent_v2',
+     *     dateOfBirth: '1998-04-12',
+     *   })
+     *
+     * Send `dataPrincipal` — the identifiers, keyed by YOUR organisation's locked
+     * integration key — or `dataPrincipalId` when you already hold the platform's
+     * uuid for the person. 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.
+     *
+     * ─── THIS IS THE U58 WIRE, AND THERE IS NO OVERLAP WINDOW ──────────────
+     *
+     * EVERY KEY BELOW IS ONE THE API DECODES. The handler decodes with NO
+     * DisallowUnknownFields — on the old wire and on this one alike — so a key it
+     * does not know is dropped in SILENCE; the request is then refused for
+     * carrying no identifier, which names a condition and not the field you sent.
+     * That is why an SDK on the wrong wire fails obscurely rather than loudly,
+     * and why this version talks to an API carrying U58 and to no other.
+     */
+    createSession(req: CreateSessionRequest): Promise<ConsentSession>;
+    /**
+     * Present the hosted consent notice in an IN-APP browser.
+     *
+     * ─── WHY A PEER AND NOT `Linking.openURL` ───────────────────────────────
+     *
+     * This used to be `Linking.openURL`, which leaves the app entirely for the
+     * external browser. Three things follow and none is acceptable for a consent
+     * surface: the callback comes back over a custom scheme any installed app can
+     * also claim; nothing tells the caller whether the page even opened; and the
+     * person is gone from the app with no cancellation signal. React Native has no
+     * built-in Custom Tabs / SFSafariViewController binding, so the in-app browser
+     * comes from a peer.
+     *
+     * INSTALL THE PEER:
+     *
+     *     npm i react-native-inappbrowser-reborn   # then: cd ios && pod install
+     *
+     * Expo apps can pass `expo-web-browser`'s `openAuthSessionAsync` through
+     * {@link SessionConfig} instead — see `openInAppBrowser` below.
+     *
+     * ─── IT REFUSES RATHER THAN DEGRADING ───────────────────────────────────
+     *
+     * With no peer available this THROWS. It does not fall back to
+     * `Linking.openURL`, because that would quietly restore every property above
+     * on exactly the devices where the peer failed to link.
+     *
+     * @returns the callback URL the in-app browser intercepted, or null when the
+     *   person dismissed it. THE DEEP LINK IS STILL BEST-EFFORT — Chrome blocks
+     *   gesture-less custom-scheme redirects — so treat null as "unknown" and
+     *   re-validate, never as "denied".
+     */
+    presentConsent(session: ConsentSession | string): Promise<string | null>;
+    /**
+     * Open a non-consent hosted page (the DP portal) in the same in-app browser.
+     * Returns nothing to check: the portal has no consent callback.
+     */
+    private presentHosted;
+    /**
+     * Authoritative decision check — the ONLY source of consent truth.
+     *
+     *   validate({ dataPrincipalIdentifiers: { email: 'riya@example.in' } }, 'product_analytics')
+     *   validate({ dataPrincipalId: '…' }, 'product_analytics')
+     *
+     * `data_principal_ref` is REFUSED OUTRIGHT (400, message prefixed
+     * `DATA_PRINCIPAL_REF_REFUSED`). Name people by the organisation's locked
+     * key fields — the mobile atom is `mobile` here and on create alike (F015);
+     * `phone` is refused by name.
+     */
+    validate(who: PrincipalRef, purposeCode: string): Promise<ConsentDecision>;
+    /** Withdraw purposes (codes or UUIDs) for the person named by [who]. */
+    withdraw(who: PrincipalRef, purposes: string[]): Promise<unknown>;
+    /**
+     * Mint a fresh single-use DP-portal SSO link (never cache it).
+     *
+     *   createPortalSession({ mobile: '+919876500000' })
+     *   createPortalSession({ customer_id: 'CUST-90210' })
+     *
+     * The person is named THE SAME WAY AS EVERYWHERE ELSE in this SDK: a map
+     * keyed by your organisation's identifier fields (F015). The KEY is the
+     * identifier's kind. Before MOB-043 this took a bare string and always
+     * declared it `email`, whatever your organisation is keyed on, so an
+     * organisation keyed on mobile or customer_id sent every person's number as
+     * an email address.
+     *
+     * THE WIRE IS STILL THE PAIR. The portal road (rights/principal
+     * portal_session_handlers.go at 4fda7e3d05) takes one `data_principal_ref`
+     * and its `data_principal_ref_type`, and defaults an absent type to email.
+     * So this SDK always sends the type, and sends exactly ONE identifier: the
+     * map's only entry, or, when you pass several and configured
+     * {@link SessionConfig.identifierScheme}, the first scheme field present.
+     *
+     * `phone` is refused here, before the wire (UNKNOWN_IDENTIFIER_FIELD). The
+     * portal road would silently fold it to `mobile`, but this SDK's
+     * vocabulary has one spelling, and on every other road `phone` is refused
+     * by name. The accepted kinds are the platform's resolver set:
+     * customer_id, email, mobile, aadhaar. The platform refuses anything else
+     * and names that set. It auto-provisions a portal account only from an
+     * email; for another kind the person must already have one (404, whose
+     * `platformMessage` says so).
+     */
+    createPortalSession(identifiers: DataPrincipalIdentifiers): Promise<PortalSession>;
+    /** Mint + open the full DP portal in one tap, in the same in-app browser. */
+    openPortal(identifiers: DataPrincipalIdentifiers): Promise<void>;
+    /**
+     * Parse and CHECK the deep link the hosted page redirects to on submit.
+     *
+     * ─── WHAT IS CHECKED, AND WHY EACH ONE ──────────────────────────────────
+     *
+     * scheme AND host AND path, all three. This used to compare only
+     * `url.startsWith('myapp://')`, which accepts
+     * `myapp://anything/anywhere?status=granted`. A custom scheme is first-come on
+     * Android and undefined on iOS: another installed app can register the same
+     * one, and the only thing that distinguishes OUR callback from its invention
+     * is the whole URL plus the nonce.
+     *
+     * `state` must equal `expectedState` when one is given — the nonce
+     * `createSession` put on `callback_url`, echoed back because
+     * `addRedirectParams` (consent/collection.go) appends to an existing query
+     * rather than replacing it.
+     *
+     * The query is parsed with the platform URL parser, not by splitting on `=`.
+     * The old hand-rolled split kept only the first two parts of each pair, so any
+     * value containing `=` — a base64 artifact id, for instance — was silently
+     * truncated.
+     *
+     * ─── WHAT IS STILL NOT PROVEN ───────────────────────────────────────────
+     *
+     * That the person granted anything. `status=granted` is a query parameter, and
+     * this SDK cannot verify the platform's `sig` without the DF's signing secret,
+     * which must not be in the app. ALWAYS confirm by reading the consent back
+     * through your backend (`validate`) — and expect that read to wait while
+     * `pending` is true.
+     *
+     * `callbackStatus` is `granted | partial | denied` exactly as the platform
+     * issues them; anything else is `unknown`, never a grant.
+     *
+     * Pass `expectedState` as null ONLY when the app was killed during the browser
+     * leg and `ConsentSession.callbackState` is genuinely gone — then re-validate
+     * rather than trusting this.
+     *
+     * @throws ConsenteraError when the link is not ours.
+     */
+    parseCallback(url: string, expectedState: string | null): ConsentCallback;
+}
+//# sourceMappingURL=session.d.ts.map

package/lib/typescript/src/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/session.ts"],"names":[],"mappings":"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"}