dynalitics-consent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dynalitics contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# dynalitics-consent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An optional **consent banner** for [dynalitics](https://www.npmjs.com/package/dynalitics). It asks visitors whether they allow analytics, remembers the answer in one first-party cookie, and gives your server a one-line helper that turns that answer into the `consent` boolean `track()` expects.
+
+`dynalitics` itself never asks for consent: it only honours the boolean you pass. Use this package if you want dynalitics to do the asking; skip it if you already have a consent manager (then pass its answer to `track()` yourself).
+
+> **Early release (`0.1.x`; the API may still change before 1.0).** Tested in jsdom (plain DOM and React, including server rendering); not yet in real browsers.
+
+```sh
+npm install dynalitics-consent     # no runtime dependencies; react is an optional peer
+```
+
+## How it fits together
+
+```
+browser                                           your server
+  <ConsentBanner message="..." />                   consentFromRequest(req)  -> true / false
+    visitor clicks Allow / Reject                     |
+    -> cookie dynalitics_consent=granted|denied  ---> dyn.track({ consent, ... })
+```
+
+Until the visitor clicks, there is no cookie, the helper returns `false`, and dynalitics stores only the page and the time. Nothing personal is ever recorded before a choice.
+
+## 1. Show the banner
+
+**React:**
+
+```tsx
+import { ConsentBanner } from 'dynalitics-consent/react';
+import 'dynalitics-consent/styles.css';
+
+export function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <ConsentBanner
+        enabled={true}
+        message="We count the pages you visit to improve this site. Do you allow analytics?"
+        acceptLabel="Allow"
+        rejectLabel="No thanks"
+        policyUrl="/privacy"
+      />
+    </>
+  );
+}
+```
+
+**Without React** (any site, any framework):
+
+```ts
+import { mountConsentBanner } from 'dynalitics-consent';
+import 'dynalitics-consent/styles.css'; // or copy dist/styles.css into your own stylesheet
+
+const banner = mountConsentBanner({
+  message: 'We count the pages you visit to improve this site. Do you allow analytics?',
+  policyUrl: '/privacy',
+});
+```
+
+The banner only appears when the visitor has not chosen yet.
+
+### Options (the same for both)
+
+| Option        | Default                | What it does                                                                                        |
+| ------------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `message`     | **required**           | the question, as plain text                                                                         |
+| `enabled`     | `true`                 | `false` shows nothing and never touches the cookie                                                  |
+| `title`       | none                   | an optional heading, plain text                                                                     |
+| `acceptLabel` | `'Allow'`              | text of the allow button                                                                            |
+| `rejectLabel` | `'Reject'`             | text of the reject button                                                                           |
+| `policyUrl`   | none                   | link to your privacy policy: a path like `/privacy` or an `https://` URL (anything else is ignored) |
+| `policyLabel` | `'Privacy policy'`     | text of that link                                                                                   |
+| `cookieName`  | `'dynalitics_consent'` | change it only if it clashes; use the same name on the server                                       |
+| `maxAgeDays`  | `180`                  | how long the answer is remembered (1 to 395 days)                                                   |
+| `onChange`    | none                   | `(choice: 'granted' \| 'denied') => void`, called after a click                                     |
+
+All text is rendered as text, never as HTML, so it is safe to load it from a CMS.
+
+## 2. Read the answer on the server
+
+```ts
+import { createDynalitics } from 'dynalitics';
+import { postgres } from 'dynalitics-postgres';
+import { consentFromRequest } from 'dynalitics-consent/server';
+
+const dyn = await createDynalitics({ adapter: postgres /* ... */ });
+
+app.use((req, res, next) => {
+  void dyn.track({
+    pageVisited: req.originalUrl,
+    consent: consentFromRequest(req), // true only after the visitor clicked "Allow"
+    ip: req.ip,
+    userId: req.user?.id,
+  });
+  next();
+});
+```
+
+`consentFromRequest` accepts a Node request (Express, Fastify, `node:http`), a Fetch `Request` (Next.js route handlers, Hono, Bun, Deno) or a raw `Cookie` header string. It returns `true` **only** for an explicit "Allow". No cookie, "Reject", an unknown value, a malformed header, or two conflicting cookies all give `false`. It never throws for a request.
+
+## 3. Let visitors change their mind
+
+Consent must be as easy to withdraw as to give. Put a "Cookie settings" link somewhere permanent, such as your footer:
+
+```tsx
+import { useConsent } from 'dynalitics-consent/react';
+
+function CookieSettingsLink() {
+  const { reopen } = useConsent();
+  return (
+    <button type="button" onClick={reopen}>
+      Cookie settings
+    </button>
+  );
+}
+```
+
+Without React, call `banner.open()` on the handle `mountConsentBanner` returned.
+
+`useConsent()` also gives you `choice` (`'granted'`, `'denied'` or `null`), `grant()` and `deny()`, if you prefer to build your own UI. Without React the same is available as `readConsent()`, `writeConsent(choice)` and `clearConsent()`. Every change also fires a `dynalitics:consent` event on `window` with `detail.choice`.
+
+## What it does and does not do
+
+- **One cookie, nothing else.** `dynalitics_consent=granted|denied; Path=/; Max-Age=…; SameSite=Lax`, plus `Secure` on https pages, written only when the visitor clicks. No local storage, no network requests, no tracking of any kind.
+- **Equal choices.** Allow and Reject are the same element with the same style; neither is pre-selected or highlighted.
+- **Accessible.** A non-modal dialog (`role="dialog"`, `aria-modal="false"`) labelled by its title or message; it does not trap focus or block the page. Buttons are at least 44 px tall, with visible focus rings. Hidden when printing.
+- **Strict-CSP friendly.** Styling is class-based in a separate stylesheet; no inline `style` attributes, no injected `<style>` tags.
+- **Server rendering.** The React banner renders nothing on the server and decides in the browser, so hydration never mismatches.
+- **Theming.** Override the CSS custom properties on `.dy-consent` (`--dy-consent-bg`, `--dy-consent-fg`, `--dy-consent-muted`, `--dy-consent-rule`, `--dy-consent-focus`, `--dy-consent-font`). It follows `prefers-color-scheme` by default.
+- **Not legal advice.** The wording of your message, your privacy policy, and whether a banner is enough in your jurisdiction remain your responsibility.
+
+## Entry points
+
+| Import                          | Contents                                                                  |
+| ------------------------------- | ------------------------------------------------------------------------- |
+| `dynalitics-consent`            | `mountConsentBanner`, `readConsent`, `writeConsent`, `clearConsent` (DOM) |
+| `dynalitics-consent/react`      | `<ConsentBanner>`, `useConsent()`                                         |
+| `dynalitics-consent/server`     | `consentFromRequest`, `parseConsentCookie` (no DOM; runs anywhere)        |
+| `dynalitics-consent/styles.css` | the banner's stylesheet                                                   |
+
+The full contract is in [`docs/SPEC.md` section 19](https://github.com/lucsoftsl/dynalitics/blob/main/docs/SPEC.md).
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { type ConsentChoice } from './shared.js';
+export type { ConsentChoice } from './shared.js';
+export interface ConsentBannerOptions {
+    /** Default true. When false nothing is rendered and the cookie is neither read nor written. */
+    readonly enabled?: boolean;
+    /** Plain text shown to the visitor. Required. */
+    readonly message: string;
+    readonly title?: string;
+    readonly acceptLabel?: string;
+    readonly rejectLabel?: string;
+    /** A same-site path (`/privacy`) or an http(s) URL; anything else is not rendered. */
+    readonly policyUrl?: string;
+    readonly policyLabel?: string;
+    /** Must equal the server helper's. Default 'dynalitics_consent'. */
+    readonly cookieName?: string | undefined;
+    /** How long the choice is remembered, 1..395 days. Default 180. */
+    readonly maxAgeDays?: number | undefined;
+    readonly onChange?: (choice: ConsentChoice) => void;
+}
+export interface CookieOptions {
+    readonly cookieName?: string | undefined;
+    readonly maxAgeDays?: number | undefined;
+}
+export interface ConsentBannerHandle {
+    /** The stored choice, or null when the visitor has not chosen (or the banner is disabled). */
+    readonly choice: () => ConsentChoice | null;
+    /** Shows the banner again whatever was stored: wire it to a "Cookie settings" link. */
+    readonly open: () => void;
+    /** Removes the banner from the page (the stored choice stays). */
+    readonly destroy: () => void;
+}
+export declare const CONSENT_EVENT = "dynalitics:consent";
+/** The stored choice from `document.cookie`, or null. Safe to call during server rendering (returns null). */
+export declare function readConsent(options?: CookieOptions): ConsentChoice | null;
+/** Stores a choice, tells listeners (`dynalitics:consent` on window). Use it for your own UI instead of the banner. */
+export declare function writeConsent(choice: ConsentChoice, options?: CookieOptions): void;
+/** Deletes the stored choice: the visitor is asked again on the next page. */
+export declare function clearConsent(options?: CookieOptions): void;
+/** Builds the banner element. Every visitor-facing string goes in as text. */
+export declare function buildBanner(o: ConsentBannerOptions, choose: (c: ConsentChoice) => void): HTMLElement;
+/**
+ * Shows the banner when the visitor has not chosen yet. Returns a handle to reopen it (withdrawal) or remove it.
+ * `container` defaults to `document.body`.
+ */
+export declare function mountConsentBanner(options: ConsentBannerOptions, container?: HTMLElement): ConsentBannerHandle;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,115 @@
+// 'dynalitics-consent': a consent banner in plain DOM (docs/SPEC.md section 19). Text only, no HTML parsing, no
+// network requests; the only thing it stores is one first-party cookie holding the visitor's choice.
+import { assertCookieName, assertMaxAgeDays, choiceFromCookieHeader, consentCookie, DEFAULT_COOKIE_NAME, DEFAULT_MAX_AGE_DAYS, safePolicyUrl, } from './shared.js';
+export const CONSENT_EVENT = 'dynalitics:consent';
+const isSecurePage = () => globalThis.location?.protocol === 'https:';
+/** The stored choice from `document.cookie`, or null. Safe to call during server rendering (returns null). */
+export function readConsent(options = {}) {
+    const name = assertCookieName(options.cookieName ?? DEFAULT_COOKIE_NAME);
+    if (typeof document === 'undefined')
+        return null;
+    return choiceFromCookieHeader(document.cookie, name);
+}
+/** Stores a choice, tells listeners (`dynalitics:consent` on window). Use it for your own UI instead of the banner. */
+export function writeConsent(choice, options = {}) {
+    if (choice !== 'granted' && choice !== 'denied')
+        throw new TypeError("dynalitics-consent: choice must be 'granted' or 'denied'");
+    const name = assertCookieName(options.cookieName ?? DEFAULT_COOKIE_NAME);
+    const days = assertMaxAgeDays(options.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS);
+    if (typeof document === 'undefined')
+        return;
+    document.cookie = consentCookie(name, choice, days * 86_400, isSecurePage());
+    globalThis.dispatchEvent?.(new CustomEvent(CONSENT_EVENT, { detail: { choice } }));
+}
+/** Deletes the stored choice: the visitor is asked again on the next page. */
+export function clearConsent(options = {}) {
+    const name = assertCookieName(options.cookieName ?? DEFAULT_COOKIE_NAME);
+    if (typeof document === 'undefined')
+        return;
+    document.cookie = consentCookie(name, '', 0, isSecurePage());
+}
+let ids = 0;
+/** Builds the banner element. Every visitor-facing string goes in as text. */
+export function buildBanner(o, choose) {
+    const id = `dy-consent-${++ids}`;
+    const root = document.createElement('div');
+    root.className = 'dy-consent';
+    root.setAttribute('role', 'dialog');
+    root.setAttribute('aria-modal', 'false');
+    root.setAttribute('aria-labelledby', o.title ? `${id}-t` : `${id}-m`);
+    if (o.title) {
+        const h = document.createElement('p');
+        h.className = 'dy-consent-title';
+        h.id = `${id}-t`;
+        h.textContent = o.title;
+        root.appendChild(h);
+    }
+    const msg = document.createElement('p');
+    msg.className = 'dy-consent-msg';
+    msg.id = `${id}-m`;
+    msg.textContent = o.message;
+    root.appendChild(msg);
+    const url = safePolicyUrl(o.policyUrl);
+    if (url) {
+        const a = document.createElement('a');
+        a.className = 'dy-consent-link';
+        a.href = url;
+        a.textContent = o.policyLabel ?? 'Privacy policy';
+        root.appendChild(a);
+    }
+    const actions = document.createElement('div');
+    actions.className = 'dy-consent-actions';
+    // Same element, same class, document order reject-then-accept: neither choice is visually favoured.
+    for (const [choice, label] of [
+        ['denied', o.rejectLabel ?? 'Reject'],
+        ['granted', o.acceptLabel ?? 'Allow'],
+    ]) {
+        const b = document.createElement('button');
+        b.type = 'button';
+        b.className = 'dy-consent-btn';
+        b.dataset['choice'] = choice;
+        b.textContent = label;
+        b.addEventListener('click', () => choose(choice));
+        actions.appendChild(b);
+    }
+    root.appendChild(actions);
+    return root;
+}
+function validate(o) {
+    if (typeof o.message !== 'string' || o.message.trim() === '')
+        throw new TypeError('dynalitics-consent: message is required');
+    assertCookieName(o.cookieName ?? DEFAULT_COOKIE_NAME);
+    assertMaxAgeDays(o.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS);
+}
+/**
+ * Shows the banner when the visitor has not chosen yet. Returns a handle to reopen it (withdrawal) or remove it.
+ * `container` defaults to `document.body`.
+ */
+export function mountConsentBanner(options, container) {
+    validate(options);
+    const cookie = { cookieName: options.cookieName, maxAgeDays: options.maxAgeDays };
+    const enabled = options.enabled !== false;
+    let el = null;
+    const destroy = () => {
+        el?.remove();
+        el = null;
+    };
+    const open = () => {
+        if (!enabled || el || typeof document === 'undefined')
+            return;
+        el = buildBanner(options, (c) => {
+            writeConsent(c, cookie);
+            destroy();
+            options.onChange?.(c);
+        });
+        (container ?? document.body).appendChild(el);
+    };
+    if (enabled && readConsent(cookie) === null)
+        open();
+    return {
+        choice: () => (enabled ? readConsent(cookie) : null),
+        open,
+        destroy,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.d.ts

@@ -0,0 +1,16 @@
+import { type ReactElement } from 'react';
+import { type ConsentBannerOptions, type ConsentChoice, type CookieOptions } from '../index.js';
+export type { ConsentBannerOptions, ConsentChoice, CookieOptions } from '../index.js';
+export interface UseConsent {
+    /** null until the visitor chose (and always null during server rendering). */
+    readonly choice: ConsentChoice | null;
+    readonly grant: () => void;
+    readonly deny: () => void;
+    /** Shows the banner again, whatever was stored. */
+    readonly reopen: () => void;
+}
+/** The visitor's choice, kept in sync with the banner and with other tabs' writes on this page. */
+export declare function useConsent(options?: CookieOptions): UseConsent;
+export type ConsentBannerProps = ConsentBannerOptions;
+export declare function ConsentBanner(props: ConsentBannerProps): ReactElement | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.js

@@ -0,0 +1,56 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// 'dynalitics-consent/react' (docs/SPEC.md 19). Same DOM and class names as the plain-DOM banner, so one stylesheet
+// serves both. Renders nothing on the server and on the first client render, so hydration never mismatches.
+import { useCallback, useEffect, useId, useState } from 'react';
+import { CONSENT_EVENT, readConsent, writeConsent, } from '../index.js';
+import { safePolicyUrl } from '../shared.js';
+/** Asks every mounted <ConsentBanner> to show itself again (withdrawal / "Cookie settings"). */
+const OPEN_EVENT = 'dynalitics:consent-open';
+/** The visitor's choice, kept in sync with the banner and with other tabs' writes on this page. */
+export function useConsent(options = {}) {
+    const { cookieName, maxAgeDays } = options;
+    const [choice, setChoice] = useState(null);
+    useEffect(() => {
+        const sync = () => setChoice(readConsent({ cookieName }));
+        sync();
+        window.addEventListener(CONSENT_EVENT, sync);
+        return () => window.removeEventListener(CONSENT_EVENT, sync);
+    }, [cookieName]);
+    const write = useCallback((c) => writeConsent(c, { cookieName, maxAgeDays }), [cookieName, maxAgeDays]);
+    return {
+        choice,
+        grant: () => write('granted'),
+        deny: () => write('denied'),
+        reopen: () => window.dispatchEvent(new Event(OPEN_EVENT)),
+    };
+}
+function assertMessage(message) {
+    if (typeof message !== 'string' || message.trim() === '')
+        throw new TypeError('dynalitics-consent: message is required');
+}
+export function ConsentBanner(props) {
+    assertMessage(props.message);
+    const { enabled = true, cookieName, maxAgeDays, onChange } = props;
+    const id = useId();
+    const [open, setOpen] = useState(false);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (readConsent({ cookieName }) === null)
+            setOpen(true);
+        const reopen = () => setOpen(true);
+        window.addEventListener(OPEN_EVENT, reopen);
+        return () => window.removeEventListener(OPEN_EVENT, reopen);
+    }, [enabled, cookieName]);
+    if (!enabled || !open)
+        return null;
+    const choose = (c) => {
+        writeConsent(c, { cookieName, maxAgeDays });
+        setOpen(false);
+        onChange?.(c);
+    };
+    const url = safePolicyUrl(props.policyUrl);
+    return (_jsxs("div", { className: "dy-consent", role: "dialog", "aria-modal": "false", "aria-labelledby": props.title ? `${id}-t` : `${id}-m`, children: [props.title ? (_jsx("p", { className: "dy-consent-title", id: `${id}-t`, children: props.title })) : null, _jsx("p", { className: "dy-consent-msg", id: `${id}-m`, children: props.message }), url ? (_jsx("a", { className: "dy-consent-link", href: url, children: props.policyLabel ?? 'Privacy policy' })) : null, _jsxs("div", { className: "dy-consent-actions", children: [_jsx("button", { type: "button", className: "dy-consent-btn", "data-choice": "denied", onClick: () => choose('denied'), children: props.rejectLabel ?? 'Reject' }), _jsx("button", { type: "button", className: "dy-consent-btn", "data-choice": "granted", onClick: () => choose('granted'), children: props.acceptLabel ?? 'Allow' })] })] }));
+}
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+export { choiceFromCookieHeader as parseConsentCookie } from './shared.js';
+export type { ConsentChoice } from './shared.js';
+/** Anything that carries a Cookie header: a Node IncomingMessage, a Fetch Request, or a plain headers object. */
+export type RequestLike = string | {
+    readonly headers: {
+        readonly get: (name: string) => string | null;
+    };
+} | {
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+};
+export interface ConsentFromRequestOptions {
+    /** Must equal the banner's `cookieName`. Default 'dynalitics_consent'. */
+    readonly cookieName?: string;
+}
+/**
+ * `true` only when the visitor chose "allow". No choice, "reject", a malformed header or conflicting cookies are all
+ * `false`, which dynalitics stores as "no consent" (page and time only). Never throws for a request.
+ */
+export declare function consentFromRequest(req: RequestLike, options?: ConsentFromRequestOptions): boolean;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,33 @@
+// 'dynalitics-consent/server': turns the banner's cookie into the boolean `track()` takes (docs/SPEC.md 19.4).
+// No DOM and no Node imports, so it runs in Node, edge runtimes, Bun and Deno alike.
+import { assertCookieName, choiceFromCookieHeader, DEFAULT_COOKIE_NAME } from './shared.js';
+export { choiceFromCookieHeader as parseConsentCookie } from './shared.js';
+function cookieHeader(req) {
+    if (typeof req === 'string')
+        return req;
+    const headers = req?.headers;
+    if (typeof headers !== 'object' || headers === null)
+        return null;
+    if (typeof headers.get === 'function') {
+        const value = headers.get('cookie');
+        return typeof value === 'string' ? value : null;
+    }
+    const raw = headers['cookie'];
+    if (typeof raw === 'string')
+        return raw;
+    return Array.isArray(raw) && raw.every((v) => typeof v === 'string') ? raw.join('; ') : null;
+}
+/**
+ * `true` only when the visitor chose "allow". No choice, "reject", a malformed header or conflicting cookies are all
+ * `false`, which dynalitics stores as "no consent" (page and time only). Never throws for a request.
+ */
+export function consentFromRequest(req, options = {}) {
+    const name = assertCookieName(options.cookieName ?? DEFAULT_COOKIE_NAME);
+    try {
+        return choiceFromCookieHeader(cookieHeader(req), name) === 'granted';
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/shared.d.ts

@@ -0,0 +1,17 @@
+export type ConsentChoice = 'granted' | 'denied';
+export declare const DEFAULT_COOKIE_NAME = "dynalitics_consent";
+export declare const DEFAULT_MAX_AGE_DAYS = 180;
+export declare const MAX_AGE_DAYS_LIMIT = 395;
+/** Throws on a cookie name that could break the `Cookie` header (it comes from host config, never from a visitor). */
+export declare function assertCookieName(name: string): string;
+export declare function assertMaxAgeDays(days: number): number;
+/**
+ * The stored choice in a `Cookie` header. Fails closed: a missing cookie, an unknown value, or the same cookie twice
+ * with different values (e.g. one set on a parent domain) is "no choice" (null).
+ */
+export declare function choiceFromCookieHeader(header: string | null | undefined, name?: string): ConsentChoice | null;
+/** The `Set-Cookie`/`document.cookie` string that stores a choice (or deletes it with `maxAgeSeconds = 0`). */
+export declare function consentCookie(name: string, value: ConsentChoice | '', maxAgeSeconds: number, secure: boolean): string;
+/** A link target the banner may render: a same-site path or an http(s) URL. Anything else (javascript:, data:) is null. */
+export declare function safePolicyUrl(url: string | undefined): string | null;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.js

@@ -0,0 +1,55 @@
+// Pure helpers shared by the banner and the server helper (docs/SPEC.md section 19). No DOM, no Node APIs.
+export const DEFAULT_COOKIE_NAME = 'dynalitics_consent';
+export const DEFAULT_MAX_AGE_DAYS = 180;
+export const MAX_AGE_DAYS_LIMIT = 395;
+const COOKIE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/** Throws on a cookie name that could break the `Cookie` header (it comes from host config, never from a visitor). */
+export function assertCookieName(name) {
+    if (!COOKIE_NAME.test(name))
+        throw new TypeError('dynalitics-consent: cookieName must match ^[A-Za-z0-9_-]{1,64}$');
+    return name;
+}
+export function assertMaxAgeDays(days) {
+    if (!Number.isInteger(days) || days < 1 || days > MAX_AGE_DAYS_LIMIT)
+        throw new TypeError(`dynalitics-consent: maxAgeDays must be an integer 1..${MAX_AGE_DAYS_LIMIT}`);
+    return days;
+}
+/**
+ * The stored choice in a `Cookie` header. Fails closed: a missing cookie, an unknown value, or the same cookie twice
+ * with different values (e.g. one set on a parent domain) is "no choice" (null).
+ */
+export function choiceFromCookieHeader(header, name = DEFAULT_COOKIE_NAME) {
+    if (typeof header !== 'string' || header.length === 0)
+        return null;
+    const values = new Set();
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            values.add(part.slice(eq + 1).trim());
+    }
+    if (values.size !== 1)
+        return null;
+    const [value] = values;
+    return value === 'granted' || value === 'denied' ? value : null;
+}
+/** The `Set-Cookie`/`document.cookie` string that stores a choice (or deletes it with `maxAgeSeconds = 0`). */
+export function consentCookie(name, value, maxAgeSeconds, secure) {
+    return `${name}=${value}; Path=/; Max-Age=${maxAgeSeconds}; SameSite=Lax${secure ? '; Secure' : ''}`;
+}
+/** A link target the banner may render: a same-site path or an http(s) URL. Anything else (javascript:, data:) is null. */
+export function safePolicyUrl(url) {
+    if (typeof url !== 'string' || url.length === 0 || url.length > 2048)
+        return null;
+    if (/^\/(?!\/)/.test(url))
+        return url;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? parsed.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/styles.css

@@ -0,0 +1,80 @@
+/* dynalitics-consent banner. Classes only (works under a strict CSP without 'unsafe-inline' for attributes).
+   Theme it by overriding the custom properties on .dy-consent. */
+.dy-consent {
+  --dy-consent-bg: #faf7f0;
+  --dy-consent-fg: #1a1915;
+  --dy-consent-muted: #4f4b43;
+  --dy-consent-rule: #8c8472;
+  --dy-consent-focus: #b03a0a;
+  --dy-consent-font: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  position: fixed;
+  z-index: 2147483000;
+  inset: auto 16px 16px 16px;
+  max-width: 560px;
+  margin-inline: auto;
+  box-sizing: border-box;
+  display: grid;
+  gap: 12px;
+  padding: 20px;
+  background: var(--dy-consent-bg);
+  color: var(--dy-consent-fg);
+  border: 1px solid var(--dy-consent-rule);
+  border-radius: 4px;
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.18);
+  font: 400 15px/1.5 var(--dy-consent-font);
+}
+@media (prefers-color-scheme: dark) {
+  .dy-consent {
+    --dy-consent-bg: #1f1d18;
+    --dy-consent-fg: #f3eee4;
+    --dy-consent-muted: #b2ab9b;
+    --dy-consent-rule: #7a7360;
+    --dy-consent-focus: #ff8a5b;
+  }
+}
+.dy-consent-title {
+  margin: 0;
+  font-weight: 600;
+}
+.dy-consent-msg {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+.dy-consent-link {
+  color: inherit;
+  justify-self: start;
+  text-underline-offset: 3px;
+}
+.dy-consent-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  justify-content: flex-end;
+}
+/* Both choices share this one rule: neither is styled to look like the "default". */
+.dy-consent-btn {
+  flex: 1 1 140px;
+  min-height: 44px;
+  padding: 0 16px;
+  font: inherit;
+  font-weight: 600;
+  color: var(--dy-consent-fg);
+  background: transparent;
+  border: 1px solid var(--dy-consent-fg);
+  border-radius: 4px;
+  cursor: pointer;
+}
+.dy-consent-btn:hover {
+  background: var(--dy-consent-fg);
+  color: var(--dy-consent-bg);
+}
+.dy-consent-btn:focus-visible,
+.dy-consent-link:focus-visible {
+  outline: 3px solid var(--dy-consent-focus);
+  outline-offset: 2px;
+}
+@media print {
+  .dy-consent {
+    display: none;
+  }
+}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "dynalitics-consent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Optional consent banner for dynalitics (plain DOM and React) plus a server helper that turns the visitor's choice into the boolean track() takes.",
+  "keywords": [
+    "analytics",
+    "dynalitics",
+    "consent",
+    "cookie-banner",
+    "gdpr",
+    "privacy",
+    "react"
+  ],
+  "license": "MIT",
+  "author": "dynalitics contributors",
+  "homepage": "https://github.com/lucsoftsl/dynalitics/tree/main/packages/dynalitics-consent#readme",
+  "bugs": {
+    "url": "https://github.com/lucsoftsl/dynalitics/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucsoftsl/dynalitics.git",
+    "directory": "packages/dynalitics-consent"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b && node scripts/copy-css.mjs"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}