@atlasprivacy/consent-sdk 0.0.0-stage → 1.0.0

package/dist/client/consent-client.d.ts

@@ -0,0 +1,79 @@
+import type { Claim, Configuration, ConsentResult, Options } from "../types.js";
+export declare class ConsentClient {
+    private readonly options;
+    /** Loads the app configuration. The form starts separately. */
+    readonly ready: Promise<Configuration>;
+    private readonly api;
+    private readonly key;
+    private config?;
+    private readonly controller;
+    private saved?;
+    private stored?;
+    private preferenceSnapshot;
+    private form?;
+    private host?;
+    private overlay?;
+    private mountTarget?;
+    private readonly accessibility;
+    private destroyed;
+    private launchTask?;
+    private generation;
+    /** Already reported once, so a later mount() or open() that fails on it does not report it again. */
+    private loadFailure;
+    private readonly reportedErrors;
+    constructor(options: Options);
+    private load;
+    private request;
+    private persist;
+    private storageChanged;
+    private documentStorageChanged;
+    private syncSaved;
+    private notifyPreference;
+    private alive;
+    /** A saved choice counts only for the notice now shown. A changed notice or language asks again. */
+    private hasChoice;
+    /** Returns a current browser preference, or null when a new choice is required. */
+    getPreference(): ConsentResult | null;
+    /** Returns browser proof for a verified server-side identity claim. */
+    getClaim(): Claim | null;
+    /**
+     * Makes sure a session exists and returns this visitor's saved choices. The same session is kept
+     * while it is valid, even after the notice or language changes, so the visitor keeps one record
+     * and getClaim() keeps working. Only a session Atlas no longer accepts is replaced.
+     */
+    private session;
+    private reconcileSession;
+    /**
+     * A visitor who saved and is not asked again never opens the form, so nothing renews their
+     * session. When it has under 60 days left, renew it in the background. Failures change nothing.
+     */
+    private renewIfEnding;
+    /** Sends the choices. The form keeps the key, so a retry cannot save twice. */
+    private save;
+    /** Counts the form as seen. A counter failure must not affect the visitor. */
+    private recordView;
+    /** Runs a public operation. A failure goes to onError and the error event, and also rejects. */
+    private reported;
+    /** Inserts the form into an existing container. */
+    mount(target: string | HTMLElement): Promise<void>;
+    private mountForm;
+    /**
+     * Shows the form. A panel that is already mounted is scrolled into view and focused. Otherwise
+     * the form opens as a dialog, and panel clients use the popup layout for it.
+     */
+    open(): Promise<void>;
+    /** Reloads the current notice and session, replacing stale choices and keeping the same placement. */
+    refresh(): Promise<void>;
+    private startForm;
+    private insertForm;
+    private createForm;
+    private complete;
+    private keydown;
+    private pointerdown;
+    private assertAlive;
+    private fail;
+    /** Removes the form and restores page access. The instance can be opened again. */
+    close(silent?: boolean): void;
+    /** Cancels requests, removes listeners, and permanently ends this instance. */
+    destroy(): void;
+}

package/dist/client/dialog.d.ts

@@ -0,0 +1,16 @@
+import type { DisplayMode } from "../types.js";
+export declare class DialogAccessibility {
+    private previousFocus?;
+    private previousOverflow?;
+    private pointerFocus?;
+    notePointer(event: PointerEvent): void;
+    activate(overlay: HTMLDialogElement): void;
+    release(): void;
+}
+export declare function createDialog(form: HTMLElement, mode: DisplayMode): HTMLDialogElement;
+interface DialogOwner {
+    close(): void;
+}
+export declare function claimDialog(owner: DialogOwner): void;
+export declare function releaseDialog(owner: DialogOwner): void;
+export {};

package/dist/client/session-storage.d.ts

@@ -0,0 +1,13 @@
+import type { ConsentResult } from "../types.js";
+export interface Saved {
+    token: string;
+    expires: string;
+    result?: ConsentResult;
+}
+/** Stored preferences are untrusted input: keep them only if they have the expected shape. */
+export declare function readSaved(raw: string | null): Saved | undefined;
+/** Undefined means storage is inaccessible; null means the key was removed. */
+export declare function readStorage(key: string): string | null | undefined;
+export declare function storeSaved(key: string, saved: Saved | undefined): boolean;
+/** Same-document clients do not receive native storage events. No credentials go in this event. */
+export declare const STORAGE_EVENT = "atlas-consent:storage";

package/dist/client/transport.d.ts

@@ -0,0 +1 @@
+export declare function request<T>(url: string, lifetime: AbortSignal, init?: RequestInit, fallback?: string): Promise<T>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { ConsentClient } from "./client/consent-client.js";
+import type { Options } from "./types.js";
+export { ConsentClient };
+export { VERSION } from "./shared/constants.js";
+export * from "./types.js";
+export declare function create(options: Options): ConsentClient;

package/dist/manifest.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0.0",
+  "files": {
+    "atlas-consent.js": "1gbGCvUMfC0ainfkRXZbd5RI0y4JxTIq7EVsFKeI3d7t4X+6AH/W8dL90BxXeMnC",
+    "atlas-consent.esm.js": "wJJZ22AdV+n/zMfShp14mvapLmaWEiNIdrsXywzxu0SWCYMYfTQsdvEYXQ7bSpY1",
+    "atlas-consent-ui.js": "kiHnJlrweigYAue/aKZvCgt+nGoYSw5VAMSa+ZkVYiEonif/vHuBn54RTTSoEu/O",
+    "ui.html": "gkXwlOaVjJxvFsh06VvDdbrhZlwvda+y/UOgJpqeNzn8F8j5kGIN7HiUh/PtudLT"
+  },
+  "environment": "production",
+  "api_base_url": "https://play.dashboard.atlaskyc.com/v3/api"
+}

package/dist/shared/build-config.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_API_BASE_URL: string;

package/dist/shared/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const VERSION = "1.0.0";
+export declare const PROTOCOL = "atlas-consent:1";
+export declare const REQUEST_TIMEOUT_MS = 15000;

package/dist/shared/notice-validation.d.ts

@@ -0,0 +1,3 @@
+import type { Purpose } from "../types.js";
+/** Validate every notice field the renderer reads. Missing fields use complete purpose fallbacks. */
+export declare function validNotice(value: unknown, purposes: Purpose[]): boolean;

package/dist/shared/protocol.d.ts

@@ -0,0 +1,9 @@
+import type { Configuration, ConsentResult } from "../types.js";
+export declare function randomId(): string;
+export declare function validMessage(value: unknown, channel: string): value is {
+    protocol: string;
+    channel: string;
+    type: string;
+    [key: string]: unknown;
+};
+export declare function validResult(value: unknown, config: Configuration): value is ConsentResult;

package/dist/shared/urls.d.ts

@@ -0,0 +1,3 @@
+export declare function baseUrl(value: string): string;
+/** Backend base URL implied by the SDK script address, or an error that says how to fix a mismatch. */
+export declare function apiBaseFromScript(src: string): string;

package/dist/shared/validation.d.ts

@@ -0,0 +1,4 @@
+import type { Configuration } from "../types.js";
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function validChoices(value: unknown, config: Configuration): value is Record<string, boolean>;
+export declare function validConfiguration(value: unknown, appId: string): value is Configuration;

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type DisplayMode = "panel" | "popup" | "page";
+export interface Purpose {
+    id: number;
+    name: string;
+    required: boolean;
+    description: string;
+    data_items: unknown[];
+}
+export interface Appearance {
+    theme: "light" | "dark" | "system";
+    primary_color: string;
+    background_color: string;
+    text_color: string;
+    radius: "sharp" | "soft" | "round";
+    font: "system" | "serif" | "rounded";
+    density: "comfortable" | "compact";
+}
+export interface Configuration {
+    appearance?: Partial<Appearance>;
+    app_id: string;
+    name: string;
+    description: string | null;
+    mode: DisplayMode;
+    level_id: string;
+    template_id: string | null;
+    revision: number;
+    sdk_version: string;
+    language_code: string;
+    config_version: string;
+    purposes: Purpose[];
+    notice: Record<string, unknown>;
+}
+export interface ConsentResult {
+    ref_id: string;
+    app_id: string;
+    level_id: string;
+    config_version: string;
+    choices: Record<string, boolean>;
+}
+export interface Claim {
+    app_id: string;
+    ref_id: string;
+    claim_token: string;
+}
+export interface Options {
+    appId: string;
+    apiBaseUrl?: string;
+    mode?: DisplayMode;
+    language?: string;
+    /** Colors and style. They override the look saved in Atlas. Wording always comes from the consent level. */
+    appearance?: Partial<Appearance>;
+    target?: string | HTMLElement;
+    autoShow?: boolean;
+    onComplete?: (result: ConsentResult, claim: Claim) => void;
+    /** Observe initial saved consent, changes in this or other tabs, and storage removal. */
+    onPreferenceChange?: (result: ConsentResult | null) => void;
+    onError?: (error: ConsentError) => void;
+    onClose?: () => void;
+}
+export declare class ConsentError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status?: number);
+}

package/dist/ui/appearance.d.ts

@@ -0,0 +1,6 @@
+import type { Appearance } from "../types.js";
+export interface AppearanceController {
+    apply(input: Partial<Appearance> | undefined): void;
+    destroy(): void;
+}
+export declare function createAppearance(target: HTMLElement): AppearanceController;

package/dist/ui/components.d.ts

@@ -0,0 +1,5 @@
+import type { DataItem } from "./notice-types.js";
+export declare function summary(items?: DataItem[], categories?: string[]): HTMLElement | null;
+export declare function accordion(label: string, description: string | undefined, items: string[]): HTMLElement;
+/** Section text as the notice writer formatted it: paragraphs, lists, emphasis and links. */
+export declare function paragraphs(value: string | undefined): HTMLElement | null;

package/dist/ui/consent-form.d.ts

@@ -0,0 +1,41 @@
+import type { Appearance, Configuration, ConsentResult, DisplayMode } from "../types.js";
+export interface DecisionPayload {
+    config_version: string;
+    language_code: string;
+    answers: {
+        purpose_id: number;
+        given: boolean;
+    }[];
+}
+export interface ConsentFormOptions {
+    host: HTMLElement;
+    config: Configuration;
+    choices: Record<string, boolean>;
+    mode: DisplayMode;
+    appearance?: Partial<Appearance>;
+    /** Dashboard preview: nothing is saved and focus is left alone. */
+    demo?: boolean;
+    save: (payload: DecisionPayload, idempotencyKey: string) => Promise<ConsentResult>;
+    onComplete: (result: ConsentResult) => void;
+    onError: (error: unknown) => void;
+    onClose: () => void;
+    onRefresh?: () => Promise<void>;
+}
+/** The consent form. It only draws and collects choices; the caller owns every API call. */
+export declare class ConsentForm {
+    private readonly options;
+    private readonly root;
+    private readonly appearance;
+    private readonly state;
+    private syncChecks;
+    private pendingKey;
+    private pendingBody;
+    private needsRefresh;
+    constructor(options: ConsentFormOptions);
+    /** Call once the host is in the document, so popup and page modes can move focus inside. */
+    render(): void;
+    setAppearance(appearance: Partial<Appearance> | undefined): void;
+    destroy(): void;
+    private message;
+    private submit;
+}

package/dist/ui/dom.d.ts

@@ -0,0 +1,8 @@
+export declare function element<K extends keyof HTMLElementTagNameMap>(tag: K, text?: string, className?: string): HTMLElementTagNameMap[K];
+/** The text of a notice value, with any markup removed and entities decoded. */
+export declare function plain(value: unknown): string;
+/**
+ * Notice text with its formatting. DOMPurify handles parsing, including Trusted Types enforcement.
+ * Rebuild the sanitized nodes to apply our heading and link presentation rules.
+ */
+export declare function rich(value: unknown): DocumentFragment;

package/dist/ui/form.d.ts

@@ -0,0 +1,16 @@
+import type { Configuration, DisplayMode } from "../types.js";
+export interface FormState {
+    choices: Record<string, boolean>;
+    busy: boolean;
+}
+export interface FormOptions {
+    root: HTMLElement;
+    config: Configuration;
+    state: FormState;
+    mode: DisplayMode;
+    demo: boolean;
+    onClose: () => void;
+    onSubmit: () => Promise<void>;
+    onChange: () => void;
+}
+export declare function renderForm({ root, config: configuration, state, mode, demo, onClose, onSubmit, onChange, }: FormOptions): () => void;

package/dist/ui/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/notice-types.d.ts

@@ -0,0 +1,50 @@
+export interface Button {
+    button_type: string;
+    button_text?: string;
+    button_enabled?: boolean;
+    button_data?: {
+        accept_necessary_text?: string;
+        accept_selected_text?: string;
+    };
+}
+export interface Block {
+    section_type: string;
+    section_data: {
+        section_title?: string;
+        section_body?: string;
+        title?: string;
+        buttons?: Button[];
+        sections?: Block[];
+    };
+}
+export interface DataItem {
+    data_item_name?: string;
+}
+export interface Notice {
+    /** The language of purposes, collected and shared, which Atlas keeps in one language. */
+    sections_language_code?: string;
+    content?: {
+        consent_data?: Block[];
+    };
+    purposes?: {
+        purpose_reason?: string;
+        purpose_reason_original?: string;
+        desc?: string;
+        sub_items?: {
+            purpose_id: number;
+            purpose_name?: string;
+            data_items?: DataItem[];
+            data_categories?: string[];
+        }[];
+    }[];
+    collected?: {
+        data_category_name?: string;
+        desc?: string;
+        sub_items?: string[];
+    }[];
+    shared?: {
+        purpose_name?: string;
+        data_categories?: string[];
+        data_items?: DataItem[];
+    }[];
+}

package/dist/ui/styles.d.ts

@@ -0,0 +1 @@
+export declare function installStyles(root: ShadowRoot): void;

package/dist/ui.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Consent preferences</title><style>html,body,#atlas-root{height:100%;margin:0}</style></head><body><main id="atlas-root">Loading consent…</main><script src="./atlas-consent-ui.js" defer></script></body></html>

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@atlasprivacy/consent-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Atlas consent UI and browser SDK",
+  "type": "module",
+  "main": "dist/atlas-consent.esm.js",
+  "module": "dist/atlas-consent.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/atlas-consent.js"
+  ],
+  "scripts": {
+    "build": "npm run typecheck && node scripts/build.mjs && tsc --emitDeclarationOnly",
+    "test": "node --import tsx --test tests/unit/*.test.* tests/integration/*.test.*",
+    "test:browser": "playwright test",
+    "sync:backend": "node scripts/sync-backend.mjs",
+    "check": "npm run format:check && npm run lint && npm run test && npm run build && npm run test:package",
+    "prepack": "npm run build",
+    "lint": "eslint src tests scripts playwright.config.ts eslint.config.mjs --max-warnings 0",
+    "lint:fix": "npm run lint -- --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test:package": "node tests/package/consumer.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.1",
+    "@types/node": "^22.0.0",
+    "dompurify": "^3.4.17",
+    "esbuild": "^0.25.0",
+    "eslint": "10.14.0",
+    "prettier": "3.9.10",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "8.72.1"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24"
+  },
+  "license": "MIT",
+  "jsdelivr": "dist/atlas-consent.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/atlas-consent.esm.js",
+      "default": "./dist/atlas-consent.esm.js"
+    },
+    "./browser": "./dist/atlas-consent.js"
+  },
+  "overrides": {
+    "minimatch": "11.0.1"
+  },
+  "gitHead": "e7662a3670dffef99077952b1ddd538722d05d06"
+}