@peax/consent-core 0.6.0

package/dist/enforcement/script.d.ts

@@ -0,0 +1,240 @@
+import * as z from 'zod/mini';
+
+/** Disjoint category/use decisions for one scope actually presented to the user. */
+declare type BatchCommand = z.infer<typeof consentDecisionsCommandSchema>;
+
+/** Records choices only for category members in userConsentedPolicy, not future members. */
+declare type CategoryConsentCommand = z.infer<typeof categoryConsentCommandSchema>;
+
+declare const categoryConsentCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    categoryId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+/** userConsentedPolicy is the scope shown for this decision, including a denial. */
+declare type ConsentDecisionCommand = z.infer<typeof consentDecisionCommandSchema>;
+
+declare const consentDecisionCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    useId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+declare type ConsentDecisionsCommand = Readonly<Omit<BatchCommand, 'decisions'> & {
+    decisions: readonly ExclusiveTarget<BatchCommand['decisions'][number]>[];
+}>;
+
+declare const consentDecisionsCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    decisions: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>, z.ZodMiniReadonly<z.ZodMiniObject<{
+        categoryId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>]>>>;
+}, z.core.$strict>>;
+
+declare type ConsentDeniedReason = 'unknown-use' | 'undecided' | 'denied' | 'consent-version-mismatch';
+
+/**
+ * Shared shape for enforcement guard errors. Only the concrete classes are public: each subpath
+ * exports exactly one of them, so consumers keep their own `instanceof` and literal `name` type.
+ */
+declare abstract class ConsentEnforcementError<Reason extends string> extends Error {
+    readonly useId: string;
+    readonly reason: Reason;
+    constructor(message: string, useId: string, reason: Reason);
+}
+
+declare type ConsentEvaluation = Readonly<{
+    allowed: true;
+}> | Readonly<{
+    allowed: false;
+    reason: ConsentDeniedReason;
+}>;
+
+declare type ConsentPolicy = z.infer<typeof consentPolicySchema>;
+
+declare const consentPolicySchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        title: z.ZodMiniString<string>;
+        description: z.ZodMiniString<string>;
+    }, z.core.$strict>>>>;
+    uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        serviceId: z.ZodMiniString<string>;
+        categoryId: z.ZodMiniString<string>;
+        purposeId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** A current use with no decision or a grant for a different consent version. */
+declare type ConsentRequirement = Readonly<{
+    useId: string;
+    categoryId: string;
+    /** The version required by the current policy for this use. */
+    consentVersion: number;
+    reason: 'undecided' | 'consent-version-mismatch';
+}>;
+
+/** In-memory runtime; methods can be passed as callbacks without binding. */
+declare type ConsentRuntime = Readonly<{
+    getSnapshot: () => ConsentSnapshot;
+    evaluate: (useId: string) => ConsentEvaluation;
+    /** Includes undecided uses and version-mismatched grants, not explicit denials. */
+    getMismatchedConsent: () => readonly ConsentRequirement[];
+    /**
+     * Replace all choices from trusted persistence, preserving unknown uses and recorded versions.
+     * Validation checks structure, not evidence of user consent; use decision methods for new choices.
+     * Does not replace policy, renew versions or perform I/O. Effective changes notify existing guards.
+     */
+    restoreState: (state: unknown) => ValidationResult<ConsentSnapshot>;
+    setConsentDecision: (command: ConsentDecisionCommand) => ValidationResult<ConsentSnapshot>;
+    setCategoryConsent: (command: CategoryConsentCommand) => ValidationResult<ConsentSnapshot>;
+    /** Validates all targets before one commit; observer errors can throw after that commit. */
+    setConsentDecisions: (command: ConsentDecisionsCommand) => ValidationResult<ConsentSnapshot>;
+    updatePolicy: (currentAppPolicy: unknown) => ValidationResult<ConsentSnapshot>;
+    subscribe: (listener: () => void) => () => void;
+}>;
+
+export declare type ConsentScript = Readonly<{
+    /** Throws synchronously if blocked; each permitted call creates one owned script. */
+    load: (options: ConsentScriptLoadOptions) => ConsentScriptHandle;
+    dispose: () => void;
+}>;
+
+export declare class ConsentScriptError extends ConsentEnforcementError<ConsentScriptErrorReason> {
+    readonly name = "ConsentScriptError";
+    constructor(useId: string, reason: ConsentScriptErrorReason);
+}
+
+export declare type ConsentScriptErrorReason = ConsentDeniedReason | 'disposed' | 'removed' | 'load-error';
+
+export declare type ConsentScriptHandle = Readonly<{
+    element: HTMLScriptElement;
+    /** Native load completion, not proof of SDK initialization or ongoing consent. */
+    ready: Promise<void>;
+    /** Removes this node. Cannot undo execution or guarantee cancellation of its download. */
+    remove: () => void;
+}>;
+
+export declare type ConsentScriptLoadOptions = Readonly<{
+    /** External HTTP(S) URL, relative to the parent's document when needed. No inline scripts. */
+    src: string;
+    /** Defaults to document.head; must be connected. */
+    parent?: HTMLElement;
+    type?: 'classic' | 'module';
+    /** Defaults to true, like native dynamically inserted scripts. */
+    async?: boolean;
+    nonce?: string;
+    integrity?: string;
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    referrerPolicy?: ReferrerPolicy;
+}>;
+
+export declare type ConsentScriptOptions = Readonly<{
+    consent: Pick<ConsentRuntime, 'evaluate' | 'subscribe'>;
+    useId: string;
+}>;
+
+/** One active app policy and recorded choices; not a history of policies shown to users. */
+declare type ConsentSnapshot = Readonly<{
+    currentAppPolicy: ConsentPolicy;
+    state: ConsentState;
+}>;
+
+declare type ConsentState = z.infer<typeof consentStateSchema>;
+
+declare const consentStateSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    choices: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** External-script insertion guard, not a sandbox or an SDK shutdown mechanism. */
+export declare function createConsentScript({ consent, useId }: ConsentScriptOptions): ConsentScript;
+
+declare type ExclusiveTarget<T> = T extends {
+    useId: string;
+} ? T & {
+    readonly categoryId?: never;
+} : T & {
+    readonly useId?: never;
+};
+
+/** A validation issue without a copy of the rejected input. */
+declare type ValidationIssue = Readonly<{
+    code: string;
+    path: readonly (string | number)[];
+    message: string;
+}>;
+
+declare type ValidationResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    issues: readonly ValidationIssue[];
+}>;
+
+export { }

package/dist/enforcement/script.js

@@ -0,0 +1,2 @@
+import { n as ConsentScriptError, t as createConsentScript } from "../createConsentScript-C_4ecSTX.js";
+export { ConsentScriptError, createConsentScript };

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import * as z from 'zod/mini';
+
+/** Disjoint category/use decisions for one scope actually presented to the user. */
+declare type BatchCommand = z.infer<typeof consentDecisionsCommandSchema>;
+
+/** Records choices only for category members in userConsentedPolicy, not future members. */
+export declare type CategoryConsentCommand = z.infer<typeof categoryConsentCommandSchema>;
+
+declare const categoryConsentCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    categoryId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+/** An explicit decision; absence of a choice means undecided. */
+export declare type ConsentChoice = z.infer<typeof consentChoiceSchema>;
+
+declare const consentChoiceSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    useId: z.ZodMiniString<string>;
+    consentVersion: z.ZodMiniInt;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+export declare type ConsentDecision = z.infer<typeof consentDecisionSchema>;
+
+/** userConsentedPolicy is the scope shown for this decision, including a denial. */
+export declare type ConsentDecisionCommand = z.infer<typeof consentDecisionCommandSchema>;
+
+declare const consentDecisionCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    useId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+declare const consentDecisionSchema: z.ZodMiniEnum<{
+    granted: "granted";
+    denied: "denied";
+}>;
+
+export declare type ConsentDecisionsCommand = Readonly<Omit<BatchCommand, 'decisions'> & {
+    decisions: readonly ExclusiveTarget<BatchCommand['decisions'][number]>[];
+}>;
+
+declare const consentDecisionsCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    decisions: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>, z.ZodMiniReadonly<z.ZodMiniObject<{
+        categoryId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>]>>>;
+}, z.core.$strict>>;
+
+declare type ConsentDeniedReason = 'unknown-use' | 'undecided' | 'denied' | 'consent-version-mismatch';
+
+export declare type ConsentEvaluation = Readonly<{
+    allowed: true;
+}> | Readonly<{
+    allowed: false;
+    reason: ConsentDeniedReason;
+}>;
+
+export declare type ConsentPolicy = z.infer<typeof consentPolicySchema>;
+
+declare const consentPolicySchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        title: z.ZodMiniString<string>;
+        description: z.ZodMiniString<string>;
+    }, z.core.$strict>>>>;
+    uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        serviceId: z.ZodMiniString<string>;
+        categoryId: z.ZodMiniString<string>;
+        purposeId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** An app-defined reason for processing, reusable across service uses. */
+export declare type ConsentPurpose = z.infer<typeof consentPurposeSchema>;
+
+declare const consentPurposeSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    id: z.ZodMiniString<string>;
+    title: z.ZodMiniString<string>;
+    description: z.ZodMiniString<string>;
+}, z.core.$strict>>;
+
+/** A current use with no decision or a grant for a different consent version. */
+export declare type ConsentRequirement = Readonly<{
+    useId: string;
+    categoryId: string;
+    /** The version required by the current policy for this use. */
+    consentVersion: number;
+    reason: 'undecided' | 'consent-version-mismatch';
+}>;
+
+/** In-memory runtime; methods can be passed as callbacks without binding. */
+export declare type ConsentRuntime = Readonly<{
+    getSnapshot: () => ConsentSnapshot;
+    evaluate: (useId: string) => ConsentEvaluation;
+    /** Includes undecided uses and version-mismatched grants, not explicit denials. */
+    getMismatchedConsent: () => readonly ConsentRequirement[];
+    /**
+     * Replace all choices from trusted persistence, preserving unknown uses and recorded versions.
+     * Validation checks structure, not evidence of user consent; use decision methods for new choices.
+     * Does not replace policy, renew versions or perform I/O. Effective changes notify existing guards.
+     */
+    restoreState: (state: unknown) => ValidationResult<ConsentSnapshot>;
+    setConsentDecision: (command: ConsentDecisionCommand) => ValidationResult<ConsentSnapshot>;
+    setCategoryConsent: (command: CategoryConsentCommand) => ValidationResult<ConsentSnapshot>;
+    /** Validates all targets before one commit; observer errors can throw after that commit. */
+    setConsentDecisions: (command: ConsentDecisionsCommand) => ValidationResult<ConsentSnapshot>;
+    updatePolicy: (currentAppPolicy: unknown) => ValidationResult<ConsentSnapshot>;
+    subscribe: (listener: () => void) => () => void;
+}>;
+
+/** One active app policy and recorded choices; not a history of policies shown to users. */
+export declare type ConsentSnapshot = Readonly<{
+    currentAppPolicy: ConsentPolicy;
+    state: ConsentState;
+}>;
+
+export declare type ConsentState = z.infer<typeof consentStateSchema>;
+
+declare const consentStateSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    choices: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** An optional use declared by the app, independent of user choices. */
+export declare type ConsentUse = z.infer<typeof consentUseSchema>;
+
+declare const consentUseSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    id: z.ZodMiniString<string>;
+    serviceId: z.ZodMiniString<string>;
+    categoryId: z.ZodMiniString<string>;
+    purposeId: z.ZodMiniString<string>;
+    consentVersion: z.ZodMiniInt;
+}, z.core.$strict>>;
+
+/** Creates an isolated runtime from decoded data; invalid input creates no instance. */
+export declare function createConsent(input: unknown): ValidationResult<ConsentRuntime>;
+
+export declare type CreateConsentOptions = z.infer<typeof createConsentOptionsSchema>;
+
+declare const createConsentOptionsSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    currentAppPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    initialState: z.ZodMiniReadonly<z.ZodMiniObject<{
+        choices: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            useId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+            decision: z.ZodMiniEnum<{
+                granted: "granted";
+                denied: "denied";
+            }>;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+
+declare type ExclusiveTarget<T> = T extends {
+    useId: string;
+} ? T & {
+    readonly categoryId?: never;
+} : T & {
+    readonly useId?: never;
+};
+
+/** A validation issue without a copy of the rejected input. */
+export declare type ValidationIssue = Readonly<{
+    code: string;
+    path: readonly (string | number)[];
+    message: string;
+}>;
+
+export declare type ValidationResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    issues: readonly ValidationIssue[];
+}>;
+
+export { }