@peax/consent-core 0.6.0

package/dist/storage.d.ts

@@ -0,0 +1,77 @@
+import * as z from 'zod/mini';
+
+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>>;
+
+export declare type ConsentStorage = Readonly<{
+    /** Null means no record. Invalid or unreadable records return failure, never empty choices. */
+    load: () => Promise<ConsentStorageResult<ConsentState | null>>;
+    /** Captures validated state at invocation; writes run in invocation order. */
+    save: (state: unknown) => Promise<ConsentStorageResult<void>>;
+    /** Available only when the adapter supports external record invalidation. Does not load or save. */
+    subscribe?: (listener: () => void) => () => void;
+}>;
+
+/** One record, scoped by the adapter's key or endpoint. Only null means absent. */
+export declare type ConsentStorageAdapter = Readonly<{
+    read: () => string | null | Promise<string | null>;
+    write: (record: string) => void | Promise<void>;
+    /** Optional lazy, key-scoped external invalidations; notifications contain no stored values. */
+    subscribe?: (listener: () => void) => () => void;
+}>;
+
+/** Storage failures deliberately exclude raw errors, URLs, headers, and stored values. */
+export declare type ConsentStorageError = Readonly<{
+    type: 'read' | 'write';
+}> | Readonly<{
+    type: 'validation';
+    issues: readonly ValidationIssue[];
+}>;
+
+export declare type ConsentStorageResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    error: ConsentStorageError;
+}>;
+
+/** Explicit persistence, independent of any runtime. No reads/writes occur on creation. */
+export declare function createConsentStorage(adapter: ConsentStorageAdapter): ConsentStorage;
+
+/** GET returns the wire record (204/404 means absent); PUT replaces it. No retries. */
+export declare function createFetchStorageAdapter({ url, fetch: fetchRequest, requestInit, }: FetchStorageAdapterOptions): ConsentStorageAdapter;
+
+export declare function createLocalStorageAdapter({ key, storage }: LocalStorageAdapterOptions): ConsentStorageAdapter;
+
+export declare type FetchStorageAdapterOptions = Readonly<{
+    url: string;
+    fetch?: typeof globalThis.fetch;
+    /** GET/PUT, body, no-store caching and rejected redirects are controlled by the adapter. */
+    requestInit?: Omit<RequestInit, 'method' | 'body' | 'cache' | 'redirect'>;
+}>;
+
+export declare type LocalStorageAdapterOptions = Readonly<{
+    key: string;
+    /** Defaults to globalThis.localStorage, resolved only during read/write/explicit subscription. */
+    storage?: Pick<Storage, 'getItem' | 'setItem'>;
+}>;
+
+/** A validation issue without a copy of the rejected input. */
+declare type ValidationIssue = Readonly<{
+    code: string;
+    path: readonly (string | number)[];
+    message: string;
+}>;
+
+export { }

package/dist/storage.js

@@ -0,0 +1,207 @@
+import { t as assertStorageIdentifier } from "./assertStorageIdentifier-BQuj-9bp.js";
+import * as z from "zod/mini";
+//#region src/utils/validation.ts
+var nonemptyStringSchema = /* @__PURE__ */ (() => z.string({ error: "Expected a nonempty string." }).check(z.refine((value) => value.trim().length > 0, { error: "Expected a nonempty string." })))();
+var consentVersionSchema = /* @__PURE__ */ (() => z.int({ error: "Expected a positive safe integer consent version." }).check(z.positive({ error: "Expected a positive safe integer consent version." })))();
+/** Internal adapter: keep Zod errors out of the public result contract. */
+function validateWithSchema(schema, input) {
+	const result = schema.safeParse(input, { error: (issue) => issue.code === "unrecognized_keys" ? `Unexpected fields: ${issue.keys.join(", ")}.` : issue.code === "invalid_type" ? `Expected ${issue.expected}.` : "Invalid consent data." });
+	if (result.success) return {
+		success: true,
+		data: result.data
+	};
+	return {
+		success: false,
+		issues: result.error.issues.map((issue) => ({
+			code: issue.code,
+			path: issue.path.map((segment) => typeof segment === "number" ? segment : String(segment)),
+			message: issue.message
+		}))
+	};
+}
+//#endregion
+//#region src/consent/schemas.ts
+var consentDecisionSchema = /* @__PURE__ */ z.enum(["granted", "denied"], { error: "Expected granted or denied." });
+var consentChoiceSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	useId: nonemptyStringSchema,
+	consentVersion: consentVersionSchema,
+	decision: consentDecisionSchema
+})))();
+var consentStateSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({ choices: z.readonly(z.array(consentChoiceSchema).check((context) => {
+	const ids = /* @__PURE__ */ new Set();
+	context.value.forEach((choice, index) => {
+		if (ids.has(choice.useId)) context.issues.push({
+			code: "custom",
+			path: [index, "useId"],
+			message: "Only one consent choice per use is allowed.",
+			input: choice.useId
+		});
+		ids.add(choice.useId);
+	});
+})) })))();
+//#endregion
+//#region src/storage/schemas.ts
+var consentRecordV1Schema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	formatVersion: z.literal(1),
+	state: consentStateSchema
+})))();
+var consentRecordHeaderSchema = /* @__PURE__ */ (() => z.object({ formatVersion: z.int().check(z.positive()) }))();
+//#endregion
+//#region src/storage/decodeConsentState.ts
+function failure(code, message, path = []) {
+	return {
+		success: false,
+		issues: [{
+			code,
+			path,
+			message
+		}]
+	};
+}
+/** Restores validated choices, not permissions. Missing storage is handled by the caller. */
+function decodeConsentState(input) {
+	if (typeof input !== "string") return failure("invalid_type", "Expected a JSON string.");
+	let record;
+	try {
+		record = JSON.parse(input);
+	} catch {
+		return failure("invalid_json", "Invalid consent JSON.");
+	}
+	const header = validateWithSchema(consentRecordHeaderSchema, record);
+	if (!header.success) return header;
+	if (header.data.formatVersion !== 1) return failure("unsupported_format_version", "Unsupported consent storage format version.", ["formatVersion"]);
+	const result = validateWithSchema(consentRecordV1Schema, record);
+	if (!result.success) return result;
+	return {
+		success: true,
+		data: result.data.state
+	};
+}
+//#endregion
+//#region src/storage/encodeConsentState.ts
+/** Encodes decoded JSON-like choices without policy reconciliation or storage I/O. */
+function encodeConsentState(input) {
+	const result = validateWithSchema(consentRecordV1Schema, {
+		formatVersion: 1,
+		state: input
+	});
+	if (!result.success) return result;
+	return {
+		success: true,
+		data: JSON.stringify(result.data)
+	};
+}
+//#endregion
+//#region src/storage/createConsentStorage.ts
+/** Explicit persistence, independent of any runtime. No reads/writes occur on creation. */
+function createConsentStorage(adapter) {
+	let pending = Promise.resolve();
+	const subscribe = adapter.subscribe;
+	function enqueue(operation) {
+		const result = pending.then(operation);
+		pending = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	return Object.freeze({
+		...subscribe ? { subscribe: (listener) => subscribe.call(adapter, listener) } : {},
+		load: () => enqueue(async () => {
+			let record;
+			try {
+				record = await adapter.read();
+			} catch {
+				return {
+					success: false,
+					error: { type: "read" }
+				};
+			}
+			if (record === null) return {
+				success: true,
+				data: null
+			};
+			const decoded = decodeConsentState(record);
+			return decoded.success ? decoded : {
+				success: false,
+				error: {
+					type: "validation",
+					issues: decoded.issues
+				}
+			};
+		}),
+		save: (state) => {
+			const encoded = encodeConsentState(state);
+			if (!encoded.success) return Promise.resolve({
+				success: false,
+				error: {
+					type: "validation",
+					issues: encoded.issues
+				}
+			});
+			return enqueue(async () => {
+				try {
+					await adapter.write(encoded.data);
+					return {
+						success: true,
+						data: void 0
+					};
+				} catch {
+					return {
+						success: false,
+						error: { type: "write" }
+					};
+				}
+			});
+		}
+	});
+}
+//#endregion
+//#region src/storage/fetch/createFetchStorageAdapter.ts
+/** GET returns the wire record (204/404 means absent); PUT replaces it. No retries. */
+function createFetchStorageAdapter({ url, fetch: fetchRequest, requestInit }) {
+	assertStorageIdentifier(url);
+	async function request(method, body) {
+		const headers = new Headers(requestInit?.headers);
+		headers.set("Accept", "application/json");
+		if (method === "PUT") headers.set("Content-Type", "application/json");
+		const init = {
+			...requestInit,
+			method,
+			headers,
+			body: body ?? null,
+			cache: "no-store",
+			redirect: "error"
+		};
+		return fetchRequest ? fetchRequest(url, init) : globalThis.fetch(url, init);
+	}
+	return Object.freeze({
+		read: async () => {
+			const response = await request("GET");
+			if (response.status === 204 || response.status === 404) return null;
+			if (response.status !== 200) throw new Error(`Consent read failed (HTTP ${response.status}).`);
+			return response.text();
+		},
+		write: async (record) => {
+			const response = await request("PUT", record);
+			if (!response.ok) throw new Error(`Consent write failed (HTTP ${response.status}).`);
+		}
+	});
+}
+//#endregion
+//#region src/storage/localstorage/createLocalStorageAdapter.ts
+function createLocalStorageAdapter({ key, storage }) {
+	assertStorageIdentifier(key);
+	return Object.freeze({
+		read: () => (storage ?? globalThis.localStorage).getItem(key),
+		write: (record) => (storage ?? globalThis.localStorage).setItem(key, record),
+		subscribe(listener) {
+			if (typeof window === "undefined") return () => {};
+			const backend = storage ?? globalThis.localStorage;
+			const changed = (event) => {
+				if (event.storageArea === backend && (event.key === key || event.key === null)) listener();
+			};
+			window.addEventListener("storage", changed);
+			return () => window.removeEventListener("storage", changed);
+		}
+	});
+}
+//#endregion
+export { createConsentStorage, createFetchStorageAdapter, createLocalStorageAdapter };

package/dist/validate-D16G7mdG.js

@@ -0,0 +1,15 @@
+//#region src/enforcement/_utils/validate.ts
+/**
+* Constructor guard shared by every enforcement entry point. Runs before any caller-supplied
+* getter, so a malformed guard is rejected at creation rather than during a granted call.
+*/
+function requireConsent(consent) {
+	const candidate = consent;
+	if (!candidate || typeof candidate.evaluate !== "function" || typeof candidate.subscribe !== "function") throw new TypeError("Expected a consent runtime.");
+}
+/** Use IDs are exact: surrounding whitespace is significant and never trimmed. */
+function requireUseId(useId) {
+	if (typeof useId !== "string" || useId.trim().length === 0) throw new TypeError("Expected a non blank use ID.");
+}
+//#endregion
+export { requireUseId as n, requireConsent as t };

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@peax/consent-core",
+  "version": "0.6.0",
+  "description": "Framework-independent consent state and runtime primitives.",
+  "keywords": [
+    "consent-management",
+    "cookie-consent",
+    "privacy",
+    "gdpr",
+    "typescript",
+    "framework-agnostic"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/peaxco/consent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peaxco/consent.git",
+    "directory": "packages/consent-core"
+  },
+  "bugs": {
+    "url": "https://github.com/peaxco/consent/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./enforcement/fetch": {
+      "types": "./dist/enforcement/fetch.d.ts",
+      "import": "./dist/enforcement/fetch.js",
+      "default": "./dist/enforcement/fetch.js"
+    },
+    "./enforcement/axios": {
+      "types": "./dist/enforcement/axios.d.ts",
+      "import": "./dist/enforcement/axios.js",
+      "default": "./dist/enforcement/axios.js"
+    },
+    "./enforcement/request-rules": {
+      "types": "./dist/enforcement/request-rules.d.ts",
+      "import": "./dist/enforcement/request-rules.js",
+      "default": "./dist/enforcement/request-rules.js"
+    },
+    "./enforcement/script": {
+      "types": "./dist/enforcement/script.d.ts",
+      "import": "./dist/enforcement/script.js",
+      "default": "./dist/enforcement/script.js"
+    },
+    "./enforcement/iframe": {
+      "types": "./dist/enforcement/iframe.d.ts",
+      "import": "./dist/enforcement/iframe.js",
+      "default": "./dist/enforcement/iframe.js"
+    },
+    "./enforcement/integration": {
+      "types": "./dist/enforcement/integration.d.ts",
+      "import": "./dist/enforcement/integration.js",
+      "default": "./dist/enforcement/integration.js"
+    },
+    "./enforcement/posthog": {
+      "types": "./dist/enforcement/posthog.d.ts",
+      "import": "./dist/enforcement/posthog.js",
+      "default": "./dist/enforcement/posthog.js"
+    },
+    "./enforcement/markup": {
+      "types": "./dist/enforcement/markup.d.ts",
+      "import": "./dist/enforcement/markup.js",
+      "default": "./dist/enforcement/markup.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js",
+      "default": "./dist/storage.js"
+    },
+    "./storage/localforage": {
+      "types": "./dist/storage/localforage.d.ts",
+      "import": "./dist/storage/localforage.js",
+      "default": "./dist/storage/localforage.js"
+    },
+    "./storage/sync": {
+      "types": "./dist/storage/sync.d.ts",
+      "import": "./dist/storage/sync.js",
+      "default": "./dist/storage/sync.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "vite build && vite build --mode entries",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "axios": "^1.20.0",
+    "localforage": "^1.10.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    },
+    "localforage": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "axios": "^1.20.0",
+    "jsdom": "30.1.1",
+    "localforage": "^1.10.0",
+    "typescript": "5.9.3",
+    "vite": "^8.3.2",
+    "vite-plugin-dts": "^5.1.1",
+    "vitest": "^5.0.3"
+  }
+}