@atlasauth/js 0.18.0 → 0.19.0

package/dist/policies.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Policy acceptance (Terms of Service, privacy policy, any policy the
+ * application defines) — the Frontend API helpers every framework SDK and
+ * custom UI share.
+ *
+ *  - `getPolicies()` — the current version of every policy, ready to render
+ *    (`content_html` is already sanitised; `content_sha256` is its hash).
+ *  - `buildPolicyAcceptances()` — turn what the user saw into the
+ *    `policy_acceptances` a sign-up, a held sign-in or an in-app acceptance sends.
+ *  - `startSignUp({ policyAcceptances })` — accept at sign-up.
+ *  - `acceptAttemptPolicies()` — continue a sign-in (or social sign-up) the
+ *    server held at `needs_policy_acceptance`; the completion carries the
+ *    ticket exactly like any other step.
+ *  - `getMyPolicies()` / `acceptPolicies()` — the signed-in user's standing,
+ *    and accepting from inside the app (e.g. a banner during a grace window).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPolicies = getPolicies;
+exports.buildPolicyAcceptances = buildPolicyAcceptances;
+exports.acceptPoliciesBody = acceptPoliciesBody;
+exports.acceptAttemptPolicies = acceptAttemptPolicies;
+exports.getMyPolicies = getMyPolicies;
+exports.acceptPolicies = acceptPolicies;
+/** `GET /v1/client/policies` — the current version of every policy. */
+async function getPolicies(client, opts = {}) {
+    const q = opts.locale ? `?locale=${encodeURIComponent(opts.locale)}` : '';
+    const res = await client.request(`/v1/client/policies${q}`, { method: 'GET' });
+    return res.ok && res.data ? { ok: true, data: res.data } : { ok: false, errors: res.errors };
+}
+/**
+ * Build `policy_acceptances` from the policies the user was shown and agreed
+ * to (public policies or an attempt's `pending_policies`). `evidence` carries
+ * the per-policy reading signals the UI measured.
+ */
+function buildPolicyAcceptances(shown, evidence = {}, opts = {}) {
+    return shown.map((p) => {
+        const key = ('key' in p && typeof p.key === 'string' ? p.key : undefined) ?? p.policy ?? '';
+        const e = evidence[key] ?? {};
+        const display = (p.display === 'checkbox' || p.display === 'scroll' || p.display === 'link' ? p.display : undefined);
+        return {
+            policy: key,
+            version_id: p.version_id,
+            content_sha256: p.content_sha256,
+            ...(display ? { display } : {}),
+            ...(e.scrolledToEnd !== undefined ? { scrolled_to_end: e.scrolledToEnd } : {}),
+            ...(e.viewMs !== undefined ? { view_ms: Math.max(0, Math.round(e.viewMs)) } : {}),
+            ...(opts.locale ? { locale: opts.locale } : {}),
+        };
+    });
+}
+/**
+ * The `accept_policies` request body: the acceptances plus the proof of the
+ * held attempt — the one-time `policy_acceptance_token` (the flow's
+ * `policyToken`, else the token on the held attempt view), else the attempt's
+ * `poll_secret` (a magic-link or QR tab). The attempt id alone is never enough.
+ */
+function acceptPoliciesBody(proof, acceptances) {
+    const viewToken = typeof proof.attempt?.policy_acceptance_token === 'string' ? proof.attempt.policy_acceptance_token : null;
+    const token = proof.policyToken || viewToken;
+    return {
+        policy_acceptances: acceptances,
+        ...(token ? { policy_acceptance_token: token } : proof.pollSecret ? { poll_secret: proof.pollSecret } : {}),
+    };
+}
+/**
+ * `POST /v1/client/sign_ins/:id/accept_policies` — continue an attempt held at
+ * `needs_policy_acceptance`. Uses the flow's `policyToken` (or its poll secret
+ * for magic-link / QR tabs). The result is the next flow state: usually
+ * `complete` with a `ticket` to exchange, or still `needs_policy_acceptance`
+ * when a newer version was published meanwhile.
+ */
+async function acceptAttemptPolicies(client, state, acceptances) {
+    const id = state.attempt?.id;
+    if (!id)
+        return { ...state, errors: [{ code: 'VALIDATION_FAILED', message: 'There is no sign-in attempt to continue.' }] };
+    const res = await client.post(`/v1/client/sign_ins/${encodeURIComponent(id)}/accept_policies`, acceptPoliciesBody({ policyToken: state.policyToken, attempt: state.attempt, pollSecret: state.pollSecret }, acceptances));
+    if (!res.ok || !res.data)
+        return { ...state, busy: false, errors: res.errors };
+    const view = res.data;
+    return {
+        attempt: view,
+        errors: [],
+        busy: false,
+        pollSecret: state.pollSecret,
+        ticket: view.ticket ?? null,
+        prepared: null,
+        policyToken: view.policy_acceptance_token ?? null,
+    };
+}
+/** `GET /v1/client/me/policies` — the signed-in user's standing on every policy. */
+async function getMyPolicies(client) {
+    const res = await client.request('/v1/client/me/policies', { method: 'GET' });
+    return res.ok && res.data ? { ok: true, data: res.data } : { ok: false, errors: res.errors };
+}
+/** `POST /v1/client/me/policies/accept` — accept from inside the app. */
+async function acceptPolicies(client, acceptances) {
+    const res = await client.post('/v1/client/me/policies/accept', {
+        policy_acceptances: acceptances,
+    });
+    return res.ok && res.data ? { ok: true, data: res.data } : { ok: false, errors: res.errors };
+}
+//# sourceMappingURL=policies.js.map

package/dist/policies.js.map

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

package/dist/policy-acceptance.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Policy acceptance (terms of service, privacy, any policy) at sign-up and
+ * sign-in: the framework-agnostic half every prebuilt UI shares.
+ *
+ * What lives here:
+ *  - the wire types and tolerant normalisers for `GET /v1/client/policies`,
+ *    `GET /v1/client/me/policies` and a sign-in attempt's `pending_policies`;
+ *  - {@link PolicyAcceptanceController}, a small observable state machine: the
+ *    policies to show, one checked/read flag per policy, the document the user
+ *    has open (and for how long), and the `policy_acceptances` payload to send;
+ *  - the pure helpers a UI needs: scroll-to-end detection, a focus trap, a safe
+ *    markdown renderer for policies delivered as markdown, and the 422
+ *    `POLICY_ACCEPTANCE_REQUIRED` reader;
+ *  - the FAPI calls: load policies, accept them in a sign-in attempt, accept
+ *    them from inside the app.
+ *
+ * Display modes (a policy's `display`):
+ *  - `checkbox`: a checkbox, combined into one sentence when several policies
+ *    use it (or one each); the policy name opens the document in an in-page
+ *    viewer, not a new tab;
+ *  - `scroll`: an unskippable modal, accepted only after the end of the text is
+ *    seen (or the text fits); declining cancels;
+ *  - `link`: a clickwrap sentence under the submit button; submitting accepts.
+ *
+ * Nothing here is a security boundary: `scrolled_to_end` and `view_ms` are
+ * client-attested evidence the server records alongside the acceptance.
+ */
+import type { FieldError } from './attempt';
+import type { FapiClient } from './fapi';
+import { acceptAttemptPolicies, type PolicyAcceptance, type PolicyDisplayMode } from './policies';
+/** A policy's display mode (same as {@link PolicyDisplayMode}). */
+export type PolicyDisplay = PolicyDisplayMode;
+export type PolicyAppliesTo = 'sign_up' | 'sign_in_and_sign_up';
+/** One policy's current version as the Frontend API serves it, camelCased. */
+export interface Policy {
+    key: string;
+    title: string;
+    display: PolicyDisplay;
+    required: boolean;
+    appliesTo: PolicyAppliesTo;
+    versionId: string;
+    version: string;
+    /** Sanitised HTML — what the user sees and what {@link Policy.contentSha256} covers. */
+    contentHtml: string | null;
+    contentMarkdown: string | null;
+    contentUrl: string | null;
+    contentSha256: string;
+    effectiveAt: string | null;
+    summaryOfChanges: string | null;
+    /** On a sign-in's pending policy: whether the user accepted an earlier version (so "what changed" applies). Null when unknown. */
+    reaccept: boolean | null;
+}
+/** One entry of the `policy_acceptances` request body, as {@link PolicyAcceptanceController.build} makes it (always with `display`). */
+export type PolicyAcceptancePayload = PolicyAcceptance & {
+    display: PolicyDisplay;
+};
+/** A signed-in user's standing on one policy (`GET /v1/client/me/policies`). */
+export interface MyPolicyStatus {
+    key: string;
+    title: string;
+    acceptedVersion: string | null;
+    currentVersion: string | null;
+    needsReaccept: boolean;
+    graceEndsAt: string | null;
+}
+/** Read one policy from the wire (snake_case, flat or with a nested `version`/`current_version` object). */
+export declare function normalizePolicy(raw: unknown): Policy | null;
+/** Read a list of policies from any of the shapes the API uses (`[..]`, `{policies}`, `{data}`). */
+export declare function normalizePolicies(body: unknown): Policy[];
+/** The policies a sign-in attempt is waiting on (`pending_policies`). */
+export declare function pendingPoliciesOf(attempt: {
+    pending_policies?: unknown;
+} | null | undefined): Policy[];
+/** Read `GET /v1/client/me/policies`. */
+export declare function normalizeMyPolicies(body: unknown): MyPolicyStatus[];
+/** Whether an error list contains the server's "accept the policies" refusal. */
+export declare function isPolicyAcceptanceRequired(errors: readonly FieldError[] | null | undefined): boolean;
+/** `GET /v1/client/policies`, read into {@link Policy} objects (empty on failure). */
+export declare function loadPolicies(client: FapiClient, opts?: {
+    locale?: string;
+    signIn?: boolean;
+}): Promise<Policy[]>;
+/**
+ * The policies a sign-up must show: every one with a published version. Required
+ * ones block the submit; optional ones may be left unticked.
+ */
+export declare function getSignUpPolicies(client: FapiClient, opts?: {
+    locale?: string;
+}): Promise<Policy[]>;
+/** `GET /v1/client/me/policies`, read into {@link MyPolicyStatus} entries (empty on failure). */
+export declare function loadMyPolicies(client: FapiClient): Promise<MyPolicyStatus[]>;
+/** `POST /v1/client/me/policies/accept`: accept from inside the app (a banner). */
+export declare function acceptMyPolicies(client: FapiClient, acceptances: PolicyAcceptance[]): Promise<{
+    ok: boolean;
+    errors: FieldError[];
+}>;
+/**
+ * `POST /v1/client/sign_ins/:id/accept_policies`: accept the `pending_policies`
+ * of an attempt in `needs_policy_acceptance` (the same call as
+ * {@link acceptAttemptPolicies}). Returns the continued flow (a session ticket,
+ * or still held when a newer version was published); on a refusal the attempt is kept.
+ */
+export declare const acceptSignInPolicies: typeof acceptAttemptPolicies;
+/** Parse the JSON the headless `advance` step carries in `values.policy_acceptances`. */
+export declare function parsePolicyAcceptances(value: string | undefined): PolicyAcceptance[];
+export interface PolicyControllerOptions {
+    /** One checkbox for every checkbox-mode policy (default) or one each. */
+    combined?: boolean;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+}
+export interface PolicySnapshot {
+    policies: Policy[];
+    combined: boolean;
+    /** Key of the document open in the in-page viewer, or null. */
+    viewing: string | null;
+    /** Whether the checkbox-mode policies are all ticked (combined box) . */
+    combinedChecked: boolean;
+}
+/**
+ * The state machine behind every policy UI. Subscribe for changes; read
+ * {@link satisfied} to enable the submit and {@link build} for the request body.
+ * State is kept per `versionId`, so a refreshed list (after a 422) keeps the
+ * ticks the user already made on versions that did not change.
+ */
+export declare class PolicyAcceptanceController {
+    private list;
+    private entries;
+    private open;
+    private listeners;
+    private readonly now;
+    readonly combined: boolean;
+    constructor(policies?: Policy[], options?: PolicyControllerOptions);
+    subscribe(fn: () => void): () => void;
+    private emit;
+    private entry;
+    get policies(): Policy[];
+    get viewing(): Policy | null;
+    snapshot(): PolicySnapshot;
+    /** Replace the policies (e.g. after a refresh); ticks on unchanged versions survive. */
+    setPolicies(policies: Policy[]): void;
+    checkboxPolicies(): Policy[];
+    scrollPolicies(): Policy[];
+    linkPolicies(): Policy[];
+    isChecked(key: string): boolean;
+    setChecked(key: string, checked: boolean): void;
+    /** Tick or untick every checkbox-mode policy at once (the combined box). */
+    setAllChecked(checked: boolean): void;
+    /** The user accepted a scroll-mode policy in its modal. */
+    acceptScroll(key: string): void;
+    /** The first scroll-mode policy still to be read and accepted, or null. */
+    pendingScroll(): Policy | null;
+    /** Open a document in the in-page viewer and start its reading clock. */
+    openDocument(key: string): void;
+    closeDocument(): void;
+    /** Start the reading clock for a policy shown some other way (a modal). */
+    startClock(key: string): void;
+    stopClock(key: string): void;
+    /** The scroll-to-end flag was reached while reading `key`. */
+    markScrolledToEnd(key: string): void;
+    hasScrolledToEnd(key: string): boolean;
+    viewMs(key: string): number;
+    /** The required policies still unaccepted. Scroll-mode ones are accepted in their modal, not by a box. */
+    missing(): Policy[];
+    /** Whether the submit may go: every required policy is accepted. Scroll-mode ones count as pending until read. */
+    satisfied(): boolean;
+    /** Whether the submit button may be enabled: scroll-mode policies are read on submit, so they do not block it. */
+    canSubmit(): boolean;
+    /** The `policy_acceptances` body: every accepted policy (and every clickwrap one). */
+    build(): PolicyAcceptancePayload[];
+}
+/** Build a controller already holding `policies` (a sign-in's `pending_policies`, a banner's, …). */
+export declare function createPolicyController(policies?: Policy[], options?: PolicyControllerOptions): PolicyAcceptanceController;
+/** Whether a scroll container has reached its end (also true when the content fits). */
+export declare function isScrolledToEnd(el: {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}, slack?: number): boolean;
+/**
+ * Call `onEnd` once the end of a scroll container has been seen: an
+ * IntersectionObserver on an end sentinel (scrolling, the keyboard, a screen
+ * reader all count), with a scroll listener fallback; and straight away when the
+ * content fits. Returns a function that stops watching.
+ */
+export declare function observeScrollEnd(scroller: HTMLElement, sentinel: HTMLElement | null, onEnd: () => void): () => void;
+/**
+ * Keep Tab inside `container` (a modal) and, when `escape` is `false`, swallow
+ * Escape so the dialog can only be left by its buttons. Returns a release
+ * function that also restores focus to whatever had it.
+ */
+export declare function trapFocus(container: HTMLElement, options?: {
+    initialFocus?: HTMLElement | null;
+    escape?: boolean;
+}): () => void;
+/**
+ * A small, safe markdown renderer (headings, paragraphs, lists, bold, italics,
+ * code, http(s) links). Every character of input is HTML-escaped first, so it
+ * can never inject markup. It is the fallback for a policy delivered as
+ * markdown only; the server normally sends sanitised HTML.
+ */
+export declare function markdownToSafeHtml(markdown: string): string;
+/** The HTML to draw for a policy: the server's sanitised HTML, else its markdown rendered safely. */
+export declare function policyHtml(policy: Pick<Policy, 'contentHtml' | 'contentMarkdown'>): string;
+/** A readable "effective 24 Oct 2026" style date, or '' when unparsable. */
+export declare function formatPolicyDate(iso: string | null | undefined): string;
+/** The English strings every policy UI draws (`policy.*` catalog keys). */
+export declare const POLICY_STRINGS: Readonly<Record<string, string>>;
+/** A `t` function over a catalog lookup that falls back to the English policy strings. */
+export declare function policyTranslator(lookup: (key: string, vars?: Record<string, string>) => string): (key: string, vars?: Record<string, string>) => string;
+/** Join titles as "A, B and C". */
+export declare function joinTitles(titles: string[], and: string): string;
+/** Split a `{name}` template into the text before and after the placeholder (for sentences that embed links). */
+export declare function splitTemplate(template: string, name: string): [string, string];
+/**
+ * After the server answered 422 `POLICY_ACCEPTANCE_REQUIRED` (a policy was
+ * published or changed while the form was open): reload the policies into the
+ * controller so the form re-shows what is needed now. Returns whether the error
+ * was that refusal.
+ */
+export declare function refreshPoliciesOnRequired(client: FapiClient, controller: PolicyAcceptanceController, errors: readonly FieldError[] | null | undefined, opts?: {
+    locale?: string;
+}): Promise<boolean>;
+/**
+ * For a sign-in attempt in `needs_policy_acceptance`: a controller holding its
+ * `pending_policies` — with the content fetched from `GET /v1/client/policies`
+ * when the attempt only listed them.
+ */
+export declare function controllerForPending(client: FapiClient, attempt: {
+    pending_policies?: unknown;
+} | null | undefined, opts?: PolicyControllerOptions & {
+    locale?: string;
+}): Promise<PolicyAcceptanceController>;
+/**
+ * In-app re-acceptance for a signed-in user, framework-free: loads
+ * `GET /v1/client/me/policies`, builds a controller for the policies that need
+ * re-accepting ({@link begin}) and posts the acceptance ({@link accept}). The
+ * framework SDKs' `<PolicyGate>` wraps it.
+ */
+export declare class PolicyGateController {
+    private readonly client;
+    private readonly locale?;
+    /** The policies that need re-acceptance (empty when none, or before {@link load}). */
+    pending: MyPolicyStatus[];
+    loaded: boolean;
+    private listeners;
+    constructor(client: FapiClient, locale?: string | undefined);
+    subscribe(fn: () => void): () => void;
+    private emit;
+    load(): Promise<void>;
+    /** The soonest end of grace among the pending policies, or null. */
+    get graceEndsAt(): string | null;
+    /** A controller over the pending policies' current versions, all required. */
+    begin(): Promise<PolicyAcceptanceController>;
+    accept(controller: PolicyAcceptanceController): Promise<{
+        ok: boolean;
+        errors: FieldError[];
+    }>;
+}