@dengdeng0324/cookie-consent-sdk 1.0.2

package/README.md

@@ -0,0 +1,56 @@
+# @dengdeng0324/cookie-consent-sdk
+
+一个使用 TypeScript、Lit 3 和 Shadow DOM 构建的框架无关 Cookie 同意 SDK。它负责地区模式、UI、状态持久化和明确选择上报；宿主应用根据最终状态自行控制 GA/GTM。
+
+## 快速开始
+
+```bash
+pnpm add @dengdeng0324/cookie-consent-sdk
+```
+
+```ts
+import cookieManager from '@dengdeng0324/cookie-consent-sdk';
+
+const unsubscribe = cookieManager.onDataChange((data) => {
+  if (data.preference.analytics) {
+    // 宿主在这里加载 Analytics。
+  }
+});
+
+await cookieManager.init({
+  language: 'zh',
+  privacyPolicyUrl: '/privacy',
+  regionEndpoint: '/api/user/region',
+  reportEndpoint: '/api/consent/report',
+});
+```
+
+可选后端契约：
+
+- `GET regionEndpoint`，5 秒超时，失败时回退 `{ countryCode: '', mode: 'opt_in' }`。
+- `POST reportEndpoint`，仅为 `accept_all` 和 `reject_all` 上报 `{ site, mode, country, choice }`。
+
+SDK 不内置任何公司域名。端点由宿主通过 `regionEndpoint`、`reportEndpoint` 传入，也可通过 `fetch` 注入 Mock；不传端点时不会发起对应网络请求。
+
+## 公共 API
+
+- `init(options)`：初始化并返回首个 `ConsentData`。
+- `onDataChange(listener)`：订阅状态，返回取消订阅函数。
+- `getData()`：获取不可变状态快照。
+- `openPreferences()`：由宿主重新打开偏好中心。
+- `update(options)`：更新语言、主题和政策链接，不重新判断地区。
+- `destroy()`：卸载 UI 并清理订阅。
+- `reset()`：删除本地同意 Cookie 并销毁实例，主要用于 QA。
+
+测试地区可传 `qaRegion: 'DE' | 'US' | 'EU' | 'notice_only'`，或使用页面参数 `?cookie_region=DE`。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+pnpm dev
+```
+
+自定义偏好和关闭 Notice 只写本地 Cookie，不调用上报接口。SDK 不会加载任何分析脚本。

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+type ConsentMode = 'opt_in' | 'notice_only';
+type ConsentView = 'hidden' | 'banner' | 'notice' | 'preferences';
+type ConsentAction = 'accept_all' | 'reject_all' | 'save_preferences' | 'acknowledge';
+interface ConsentPreference {
+    necessary: true;
+    analytics: boolean;
+    marketing: boolean;
+    personalization: boolean;
+}
+interface ConsentData {
+    countryCode: string;
+    mode: ConsentMode;
+    hasChoice: boolean;
+    preference: ConsentPreference;
+    updatedAt?: string;
+}
+interface ThemeOptions {
+    primaryColor?: string;
+    surfaceColor?: string;
+    textColor?: string;
+    borderRadius?: string;
+}
+interface ConsentTranslations {
+    title: string;
+    description: string;
+    acceptAll: string;
+    rejectAll: string;
+    customize: string;
+    save: string;
+    close: string;
+    noticeTitle: string;
+    noticeDescription: string;
+    acknowledge: string;
+    preferencesTitle: string;
+    preferencesDescription: string;
+    necessary: string;
+    necessaryDescription: string;
+    analytics: string;
+    analyticsDescription: string;
+    marketing: string;
+    marketingDescription: string;
+    personalization: string;
+    personalizationDescription: string;
+    alwaysOn: string;
+    privacyPolicy: string;
+}
+interface RegionResult {
+    countryCode: string;
+    mode: ConsentMode;
+}
+interface CookieManagerOptions {
+    language?: string;
+    translations?: Record<string, Partial<ConsentTranslations>>;
+    theme?: ThemeOptions;
+    privacyPolicyUrl?: string;
+    regionEndpoint?: string;
+    reportEndpoint?: string;
+    cookieName?: string;
+    cookieDomain?: string;
+    cookieMaxAgeDays?: number;
+    mountTarget?: HTMLElement | string;
+    requestTimeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    qaRegion?: string;
+}
+type ConsentListener = (data: Readonly<ConsentData>) => void;
+interface StoredConsent extends ConsentData {
+    version: 1;
+}
+
+declare class CookieManager {
+    private options;
+    private listeners;
+    private data?;
+    private view;
+    private cookie?;
+    private reporter?;
+    private i18n?;
+    private ui?;
+    private initialized;
+    private initializing?;
+    init(options?: CookieManagerOptions): Promise<Readonly<ConsentData>>;
+    onDataChange(listener: ConsentListener): () => void;
+    getData(): Readonly<ConsentData> | undefined;
+    openPreferences(): void;
+    update(options: Partial<CookieManagerOptions>): void;
+    destroy(): void;
+    reset(): void;
+    private initialize;
+    private handleAction;
+    private save;
+    private notify;
+    private render;
+    private snapshot;
+    private qaRegionFromLocation;
+    private allPreferences;
+    private assertInitialized;
+}
+
+declare class ConsentCookie {
+    private readonly name;
+    private readonly domain?;
+    private readonly maxAgeDays;
+    constructor(name?: string, domain?: string | undefined, maxAgeDays?: number);
+    read(): StoredConsent | undefined;
+    write(data: ConsentData): void;
+    remove(): void;
+}
+
+declare function modeForCountry(countryCode: string): ConsentMode;
+declare function parseQaRegion(value?: string | null): RegionResult | undefined;
+declare class RegionClient {
+    private readonly endpoint?;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(endpoint?: string | undefined, fetcher?: typeof globalThis.fetch, timeoutMs?: number);
+    detect(): Promise<RegionResult>;
+}
+
+type ReportableChoice = 'accept_all' | 'reject_all';
+
+declare const cookieManager: CookieManager;
+
+export { type ConsentAction, ConsentCookie, type ConsentData, type ConsentListener, type ConsentMode, type ConsentPreference, type ConsentTranslations, type ConsentView, CookieManager, type CookieManagerOptions, RegionClient, type RegionResult, type ReportableChoice, type StoredConsent, type ThemeOptions, cookieManager, cookieManager as default, modeForCountry, parseQaRegion };

package/dist/index.js

@@ -0,0 +1,681 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/defaults.ts
+var DEFAULT_PREFERENCE = {
+  necessary: true,
+  analytics: false,
+  marketing: false,
+  personalization: false
+};
+var EN_TRANSLATIONS = {
+  title: "Your privacy choices",
+  description: "We use cookies to keep this site working and, with your permission, to understand usage and personalize your experience.",
+  acceptAll: "Accept all",
+  rejectAll: "Reject all",
+  customize: "Manage preferences",
+  save: "Save Preferences",
+  close: "Close",
+  noticeTitle: "Cookie notice",
+  noticeDescription: "We use cookies to improve your experience on our platform. By continuing to use our site, you agree to our use of cookies.",
+  acknowledge: "Got It",
+  preferencesTitle: "Cookie Preferences",
+  preferencesDescription: "Choose which optional cookies you allow. Strictly necessary cookies cannot be disabled.",
+  necessary: "Strictly Necessary Cookies",
+  necessaryDescription: "These cookies are essential for the platform to function and cannot be switched off. They are set in response to actions you take, such as logging in or saving your preferences, and cannot be disabled.",
+  analytics: "Analytics Cookies",
+  analyticsDescription: "These cookies help us understand how visitors use our platform by collecting anonymized usage data. This information helps us improve our products and user experience.",
+  marketing: "Advertising Cookies",
+  marketingDescription: "These cookies are set by our advertising partners to build a profile of your interests and show you relevant ads on other sites. They do not store personal data directly but uniquely identify your browser and device.",
+  personalization: "Functional Cookies",
+  personalizationDescription: "These cookies allow the platform to remember your choices and provide enhanced, personalized features such as language preferences and UI settings. Disabling them may affect some platform functionality.",
+  alwaysOn: "Always On",
+  privacyPolicy: "Learn more"
+};
+var ZH_TRANSLATIONS = {
+  title: "\u60A8\u7684\u9690\u79C1\u9009\u62E9",
+  description: "\u6211\u4EEC\u4F7F\u7528 Cookie \u6765\u7EF4\u6301\u7F51\u7AD9\u8FD0\u884C\uFF1B\u7ECF\u60A8\u5141\u8BB8\u540E\uFF0C\u8FD8\u4F1A\u7528\u4E8E\u5206\u6790\u4F7F\u7528\u60C5\u51B5\u5E76\u63D0\u4F9B\u4E2A\u6027\u5316\u4F53\u9A8C\u3002",
+  acceptAll: "\u5168\u90E8\u63A5\u53D7",
+  rejectAll: "\u5168\u90E8\u62D2\u7EDD",
+  customize: "\u7BA1\u7406\u504F\u597D",
+  save: "\u4FDD\u5B58\u504F\u597D",
+  close: "\u5173\u95ED",
+  noticeTitle: "Cookie \u901A\u77E5",
+  noticeDescription: "\u6211\u4EEC\u4F7F\u7528 Cookie \u6539\u5584\u60A8\u5728\u5E73\u53F0\u4E0A\u7684\u4F53\u9A8C\u3002\u7EE7\u7EED\u4F7F\u7528\u672C\u7F51\u7AD9\u5373\u8868\u793A\u60A8\u540C\u610F\u6211\u4EEC\u4F7F\u7528 Cookie\u3002",
+  acknowledge: "\u77E5\u9053\u4E86",
+  preferencesTitle: "Cookie \u504F\u597D\u8BBE\u7F6E",
+  preferencesDescription: "\u8BF7\u9009\u62E9\u5141\u8BB8\u4F7F\u7528\u7684\u53EF\u9009 Cookie\u3002\u4E25\u683C\u5FC5\u8981 Cookie \u65E0\u6CD5\u5173\u95ED\u3002",
+  necessary: "\u4E25\u683C\u5FC5\u8981 Cookie",
+  necessaryDescription: "\u8FD9\u4E9B Cookie \u662F\u5E73\u53F0\u6B63\u5E38\u8FD0\u884C\u6240\u5FC5\u9700\u7684\uFF0C\u65E0\u6CD5\u5173\u95ED\u3002\u5B83\u4EEC\u4F1A\u5728\u60A8\u767B\u5F55\u6216\u4FDD\u5B58\u504F\u597D\u8BBE\u7F6E\u7B49\u64CD\u4F5C\u65F6\u542F\u7528\u3002",
+  analytics: "\u5206\u6790 Cookie",
+  analyticsDescription: "\u8FD9\u4E9B Cookie \u901A\u8FC7\u6536\u96C6\u533F\u540D\u4F7F\u7528\u6570\u636E\uFF0C\u5E2E\u52A9\u6211\u4EEC\u4E86\u89E3\u8BBF\u5BA2\u5982\u4F55\u4F7F\u7528\u5E73\u53F0\u5E76\u6539\u5584\u4EA7\u54C1\u4F53\u9A8C\u3002",
+  marketing: "\u5E7F\u544A Cookie",
+  marketingDescription: "\u8FD9\u4E9B Cookie \u7528\u4E8E\u5EFA\u7ACB\u5174\u8DA3\u753B\u50CF\u5E76\u5728\u5176\u4ED6\u7F51\u7AD9\u4E0A\u5C55\u793A\u76F8\u5173\u5E7F\u544A\u3002",
+  personalization: "\u529F\u80FD Cookie",
+  personalizationDescription: "\u8FD9\u4E9B Cookie \u4F1A\u8BB0\u4F4F\u8BED\u8A00\u548C\u754C\u9762\u8BBE\u7F6E\u7B49\u9009\u62E9\uFF0C\u4EE5\u63D0\u4F9B\u589E\u5F3A\u7684\u4E2A\u6027\u5316\u529F\u80FD\u3002",
+  alwaysOn: "\u59CB\u7EC8\u542F\u7528",
+  privacyPolicy: "\u4E86\u89E3\u66F4\u591A"
+};
+
+// src/consent-cookie.ts
+import Cookies from "js-cookie";
+var ConsentCookie = class {
+  constructor(name = "cookie_consent", domain, maxAgeDays = 180) {
+    this.name = name;
+    this.domain = domain;
+    this.maxAgeDays = maxAgeDays;
+  }
+  read() {
+    const raw = Cookies.get(this.name);
+    if (!raw) return void 0;
+    try {
+      const value = JSON.parse(raw);
+      if (!isStoredConsent(value)) return void 0;
+      return {
+        ...value,
+        countryCode: value.countryCode.trim().toUpperCase() || "EU",
+        hasChoice: true,
+        preference: { ...value.preference, necessary: true }
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  write(data) {
+    const value = { ...data, version: 1, hasChoice: true };
+    Cookies.set(this.name, JSON.stringify(value), {
+      expires: this.maxAgeDays,
+      sameSite: "Lax",
+      secure: globalThis.location?.protocol === "https:",
+      domain: this.domain
+    });
+  }
+  remove() {
+    Cookies.remove(this.name, { domain: this.domain });
+  }
+};
+function isStoredConsent(value) {
+  const preference = value.preference;
+  return value.version === 1 && typeof value.countryCode === "string" && (value.mode === "opt_in" || value.mode === "notice_only") && typeof preference === "object" && preference !== null && typeof preference.analytics === "boolean" && typeof preference.marketing === "boolean" && typeof preference.personalization === "boolean";
+}
+
+// src/i18n.ts
+import i18next from "i18next";
+var ConsentI18n = class {
+  constructor(language = "en", custom = {}) {
+    this.instance = i18next.createInstance();
+    const languages = /* @__PURE__ */ new Set(["en", "zh", ...Object.keys(custom)]);
+    const resources = Object.fromEntries([...languages].map((code) => {
+      const base = code.startsWith("zh") ? ZH_TRANSLATIONS : EN_TRANSLATIONS;
+      return [code, { translation: { ...base, ...custom[code] } }];
+    }));
+    void this.instance.init({ lng: language, fallbackLng: "en", resources, initImmediate: false });
+  }
+  setLanguage(language) {
+    void this.instance.changeLanguage(language);
+  }
+  text(key) {
+    return this.instance.t(key);
+  }
+  get language() {
+    return this.instance.language;
+  }
+};
+
+// src/region-client.ts
+var OPT_IN_COUNTRIES = /* @__PURE__ */ new Set([
+  "AT",
+  "BE",
+  "BG",
+  "HR",
+  "CY",
+  "CZ",
+  "DK",
+  "EE",
+  "FI",
+  "FR",
+  "DE",
+  "GR",
+  "HU",
+  "IE",
+  "IT",
+  "LV",
+  "LT",
+  "LU",
+  "MT",
+  "NL",
+  "PL",
+  "PT",
+  "RO",
+  "SK",
+  "SI",
+  "ES",
+  "SE",
+  "IS",
+  "LI",
+  "NO",
+  "GB"
+]);
+var PRIVACY_SAFE_REGION = Object.freeze({
+  countryCode: "EU",
+  mode: "opt_in"
+});
+function modeForCountry(countryCode) {
+  return OPT_IN_COUNTRIES.has(countryCode.toUpperCase()) ? "opt_in" : "notice_only";
+}
+function parseQaRegion(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toUpperCase();
+  if (["EU", "EEA", "OPT_IN"].includes(normalized)) return { countryCode: "EU", mode: "opt_in" };
+  if (["NON_EU", "NOTICE", "NOTICE_ONLY"].includes(normalized)) return { countryCode: "US", mode: "notice_only" };
+  if (/^[A-Z]{2}$/.test(normalized)) return { countryCode: normalized, mode: modeForCountry(normalized) };
+  return void 0;
+}
+var RegionClient = class {
+  constructor(endpoint, fetcher = globalThis.fetch, timeoutMs = 5e3) {
+    this.endpoint = endpoint;
+    this.fetcher = fetcher;
+    this.timeoutMs = timeoutMs;
+  }
+  async detect() {
+    if (!this.endpoint) return { ...PRIVACY_SAFE_REGION };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetcher(this.endpoint, {
+        signal: controller.signal,
+        credentials: "include",
+        headers: { Accept: "application/json" }
+      });
+      if (!response.ok) throw new Error(`Region request failed (${response.status})`);
+      const body = await response.json();
+      const countryCode = body.countryCode?.toUpperCase();
+      if (!countryCode) throw new Error("Region response is missing countryCode");
+      return { countryCode, mode: body.mode ?? modeForCountry(countryCode) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/report-client.ts
+var ConsentReportClient = class {
+  constructor(endpoint, fetcher = globalThis.fetch, timeoutMs = 5e3) {
+    this.endpoint = endpoint;
+    this.fetcher = fetcher;
+    this.timeoutMs = timeoutMs;
+  }
+  async report(choice, data) {
+    if (!this.endpoint) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetcher(this.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        credentials: "include",
+        keepalive: true,
+        signal: controller.signal,
+        body: JSON.stringify({
+          site: globalThis.location?.hostname ?? "",
+          mode: data.mode,
+          country: data.countryCode,
+          choice
+        })
+      });
+      if (!response.ok) throw new Error(`Consent report failed (${response.status})`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/ui/cookie-consent-manager.ts
+import { LitElement, css, html, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+var CookieConsentManagerElement = class extends LitElement {
+  constructor() {
+    super(...arguments);
+    this.translations = EN_TRANSLATIONS;
+    this.theme = {};
+    this.view = "hidden";
+    this.privacyPolicyUrl = "";
+    this.draft = {
+      necessary: true,
+      analytics: false,
+      marketing: false,
+      personalization: false
+    };
+  }
+  willUpdate(changed) {
+    if (changed.has("data") && this.data) this.draft = { ...this.data.preference };
+  }
+  emit(action, preference) {
+    this.dispatchEvent(new CustomEvent("cookie-consent-action", {
+      detail: { action, preference },
+      bubbles: true,
+      composed: true
+    }));
+  }
+  toggle(key, checked) {
+    this.draft = { ...this.draft, [key]: checked };
+  }
+  styleVariables() {
+    return [
+      `--cc-primary:${this.theme.primaryColor ?? "#20bf63"}`,
+      `--cc-surface:${this.theme.surfaceColor ?? "#ffffff"}`,
+      `--cc-text:${this.theme.textColor ?? "#172033"}`,
+      `--cc-radius:${this.theme.borderRadius ?? "16px"}`
+    ].join(";");
+  }
+  render() {
+    if (!this.data || this.view === "hidden") return nothing;
+    return html`<div style=${this.styleVariables()}>
+      ${this.view === "banner" ? this.renderBanner() : nothing}
+      ${this.view === "notice" ? this.renderNotice() : nothing}
+      ${this.view === "preferences" ? this.renderPreferences() : nothing}
+    </div>`;
+  }
+  renderBanner() {
+    const t = this.translations;
+    return html`<section class="banner" role="dialog" aria-modal="false" aria-labelledby="cc-title">
+      <h2 id="cc-title" class="sr-only">${t.title}</h2>
+      <button class="close" aria-label="${t.rejectAll} — ${t.close}" @click=${() => this.emit("reject_all")}>×</button>
+      <p>${t.description} ${this.policyLink()}</p>
+      <div class="eu-actions">
+        <button class="primary eu-accept" @click=${() => this.emit("accept_all")}>${t.acceptAll}</button>
+        <button @click=${() => this.emit("reject_all")}>${t.rejectAll}</button>
+        <button @click=${() => this.emit("open_preferences")}>${t.customize}</button>
+      </div>
+    </section>`;
+  }
+  renderNotice() {
+    const t = this.translations;
+    return html`<aside class="notice" role="dialog" aria-labelledby="cc-notice-title">
+      <h2 id="cc-notice-title" class="sr-only">${t.noticeTitle}</h2>
+      <button class="close" aria-label=${t.close} @click=${() => this.emit("acknowledge")}>×</button>
+      <p>${t.noticeDescription} ${this.policyLink()}</p>
+      <button class="notice-acknowledge" @click=${() => this.emit("acknowledge")}>${t.acknowledge}</button>
+    </aside>`;
+  }
+  renderPreferences() {
+    const t = this.translations;
+    return html`<div class="backdrop" @click=${(event) => {
+      if (event.target === event.currentTarget) this.emit("close_preferences");
+    }}>
+      <section class="modal" role="dialog" aria-modal="true" aria-labelledby="cc-preferences-title">
+        <header>
+          <h2 id="cc-preferences-title">${t.preferencesTitle}</h2>
+          <button class="close modal-close" aria-label=${t.close} @click=${() => this.emit("close_preferences")}>×</button>
+        </header>
+        <div class="categories">
+          ${this.category("necessary", t.necessary, t.necessaryDescription, true)}
+          ${this.category("personalization", t.personalization, t.personalizationDescription, this.draft.personalization)}
+          ${this.category("analytics", t.analytics, t.analyticsDescription, this.draft.analytics)}
+          ${this.category("marketing", t.marketing, t.marketingDescription, this.draft.marketing)}
+        </div>
+        <footer>
+          <button class="save" @click=${() => this.emit("save_preferences", this.draft)}>${t.save}</button>
+        </footer>
+      </section>
+    </div>`;
+  }
+  category(key, title, description, checked) {
+    const necessary = key === "necessary";
+    return html`<section class="category">
+      <div class="category-head">
+        <div class="category-title">
+          <strong>${title}</strong>
+          ${necessary ? html`<span class="always">${this.translations.alwaysOn}</span>` : nothing}
+        </div>
+        <input
+          type="checkbox"
+          aria-label=${title}
+          .checked=${checked}
+          ?disabled=${necessary}
+          @change=${(event) => !necessary && this.toggle(key, event.target.checked)}
+        />
+      </div>
+      <p>${description}</p>
+    </section>`;
+  }
+  policyLink() {
+    return this.privacyPolicyUrl ? html`<a href=${this.privacyPolicyUrl} target="_blank" rel="noopener">${this.translations.privacyPolicy}</a>` : nothing;
+  }
+};
+CookieConsentManagerElement.styles = css`
+    :host { font-family: Arial, Helvetica, ui-sans-serif, system-ui, sans-serif; color: var(--cc-text); }
+    * { box-sizing: border-box; }
+    .banner { position: fixed; z-index: 2147483000; right: 24px; bottom: 24px; width: min(440px, calc(100vw - 32px)); padding: 44px 24px 22px; background: var(--cc-surface); color: #171717; border: 1px solid #dedede; border-radius: 14px; box-shadow: 0 10px 28px rgba(0, 0, 0, .16); }
+    .banner p { margin: 0; color: #171717; font-size: 16px; line-height: 1.5; }
+    .eu-actions { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; margin-top: 18px; }
+    .eu-actions button { width: 100%; height: 44px; min-height: 44px; padding-inline: 12px; border-color: #dedede; border-radius: 12px; background: #fff; color: #171717; font-size: 15px; font-weight: 400; }
+    .eu-actions .eu-accept { grid-column: 1 / -1; border-color: var(--cc-primary); background: var(--cc-primary); color: #fff; }
+    .copy { flex: 1; min-width: 0; }
+    .eyebrow { color: var(--cc-primary); font-size: 11px; font-weight: 800; letter-spacing: .12em; text-transform: uppercase; }
+    h2 { margin: 5px 0 8px; font-size: 22px; line-height: 1.2; }
+    p { margin: 0; color: color-mix(in srgb, var(--cc-text), transparent 25%); font-size: 14px; line-height: 1.55; }
+    a { color: currentColor; text-decoration: underline; text-decoration-thickness: 2px; text-underline-offset: 3px; }
+    .actions { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; justify-content: flex-end; }
+    button { appearance: none; min-height: 42px; padding: 0 18px; border: 1px solid color-mix(in srgb, var(--cc-text), transparent 76%); border-radius: calc(var(--cc-radius) * .55); background: var(--cc-surface); color: var(--cc-text); font: inherit; font-weight: 700; cursor: pointer; }
+    button:hover { filter: brightness(.97); transform: translateY(-1px); }
+    button:focus-visible, input:focus-visible, a:focus-visible { outline: 3px solid color-mix(in srgb, var(--cc-primary), transparent 60%); outline-offset: 2px; }
+    button.primary { border-color: var(--cc-primary); background: var(--cc-primary); color: white; }
+    button.link { border-color: transparent; background: transparent; color: var(--cc-primary); padding-inline: 8px; }
+    .notice { position: fixed; z-index: 2147483000; right: 24px; bottom: 24px; width: min(440px, calc(100vw - 32px)); padding: 44px 24px 22px; background: var(--cc-surface); color: #171717; border: 1px solid #dedede; border-radius: 14px; box-shadow: 0 10px 28px rgba(0, 0, 0, .16); }
+    .notice p { margin: 0 0 18px; color: #171717; font-size: 16px; line-height: 1.5; }
+    .notice-acknowledge { width: 100%; height: 44px; min-height: 44px; border-color: #dedede; border-radius: 12px; background: #fff; color: #171717; font-size: 15px; font-weight: 400; }
+    .close { position: absolute; top: 14px; right: 16px; width: 26px; min-height: 26px; padding: 0; border: 0; border-radius: 4px; background: transparent; color: #111; font-size: 24px; font-weight: 400; line-height: 1; }
+    .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+    .backdrop { position: fixed; z-index: 2147483000; inset: 0; display: grid; place-items: center; padding: 32px; background: rgba(15, 23, 42, .28); backdrop-filter: blur(3px); }
+    .modal { position: relative; display: flex; flex-direction: column; width: min(640px, 100%); max-height: calc(100vh - 64px); overflow: auto; padding: 24px; background: #fff; color: #0d0d0f; border: 1px solid #dedede; border-radius: 16px; box-shadow: 0 18px 48px rgba(15, 23, 42, .18); }
+    header { display: flex; justify-content: space-between; align-items: center; min-height: 36px; }
+    header h2 { margin: 0; font-size: 26px; font-weight: 700; line-height: 1.2; letter-spacing: -.02em; }
+    .modal-close { top: 25px; right: 24px; }
+    .categories { margin: 16px 0 20px; }
+    .category { padding: 14px 0; border-bottom: 1px solid #d9d9dd; }
+    .category + .category { padding-top: 16px; }
+    .category-head { display: flex; align-items: center; justify-content: space-between; gap: 22px; }
+    .category-title { display: flex; align-items: center; gap: 14px; min-width: 0; }
+    .category strong { font-size: 18px; font-weight: 700; line-height: 1.25; }
+    .category p { margin: 8px 0 0; color: #70717e; font-size: 15px; line-height: 1.5; }
+    .always { display: inline-flex; align-items: center; min-height: 25px; padding: 2px 10px; border-radius: 999px; background: var(--cc-primary); color: #fff; font-size: 13px; font-weight: 400; white-space: nowrap; }
+    input { appearance: none; flex: 0 0 54px; width: 54px; height: 30px; margin: 0; border-radius: 999px; background: #aeb7c8; cursor: pointer; transition: .2s; }
+    input::before { content: ''; display: block; width: 25px; height: 25px; margin: 2.5px; border-radius: 50%; background: white; box-shadow: 0 1px 3px #0003; transition: .2s; }
+    input:checked { background: var(--cc-primary); }
+    input:checked::before { transform: translateX(24px); }
+    input:disabled { cursor: default; opacity: .42; }
+    footer { display: flex; justify-content: flex-end; margin-top: auto; }
+    button.save { min-width: 168px; height: 48px; border-color: #dedee4; border-radius: 12px; background: #fff; color: #111; font-size: 16px; font-weight: 400; }
+    @media (max-width: 640px) {
+      .banner { right: 12px; bottom: 12px; left: 12px; width: auto; padding: 42px 20px 20px; }
+      .banner p { font-size: 15px; }
+      .eu-actions { grid-template-columns: 1fr; }
+      .eu-actions .eu-accept { grid-column: auto; }
+      .notice { right: 12px; bottom: 12px; left: 12px; width: auto; padding: 42px 20px 20px; }
+      .notice p { font-size: 15px; }
+      .actions { display: grid; grid-template-columns: 1fr; }
+      .actions button { width: 100%; }
+      .modal { height: auto; max-height: calc(100vh - 24px); padding: 24px 22px; }
+      header h2 { font-size: 27px; }
+      .modal-close { top: 22px; right: 20px; }
+      .category strong { font-size: 19px; }
+      .category p { font-size: 16px; }
+      .always { min-height: 26px; padding-inline: 10px; font-size: 14px; }
+      input { flex-basis: 54px; width: 54px; height: 31px; }
+      input::before { width: 26px; height: 26px; }
+      input:checked::before { transform: translateX(23px); }
+      button.save { width: 100%; }
+    }
+    @media (prefers-reduced-motion: no-preference) {
+      .banner { animation: notice-appear .25s ease-out; }
+      .notice { animation: notice-appear .25s ease-out; }
+      .modal { animation: appear .25s ease-out; }
+      @keyframes rise { from { opacity: 0; transform: translateY(18px); } }
+      @keyframes notice-appear { from { opacity: 0; transform: translateY(10px); } }
+      @keyframes appear { from { opacity: 0; transform: translateY(10px) scale(.98); } }
+    }
+  `;
+__decorateClass([
+  property({ attribute: false })
+], CookieConsentManagerElement.prototype, "data", 2);
+__decorateClass([
+  property({ attribute: false })
+], CookieConsentManagerElement.prototype, "translations", 2);
+__decorateClass([
+  property({ attribute: false })
+], CookieConsentManagerElement.prototype, "theme", 2);
+__decorateClass([
+  property({ attribute: false })
+], CookieConsentManagerElement.prototype, "view", 2);
+__decorateClass([
+  property({ type: String })
+], CookieConsentManagerElement.prototype, "privacyPolicyUrl", 2);
+__decorateClass([
+  state()
+], CookieConsentManagerElement.prototype, "draft", 2);
+CookieConsentManagerElement = __decorateClass([
+  customElement("cookie-consent-manager")
+], CookieConsentManagerElement);
+
+// src/ui-controller.ts
+var UIController = class {
+  constructor(options, i18n) {
+    this.options = options;
+    this.i18n = i18n;
+    this.onAction = (event) => this.handler?.(event.detail);
+  }
+  mount(handler) {
+    if (this.element) return;
+    const target = this.resolveTarget();
+    this.handler = handler;
+    this.element = document.createElement("cookie-consent-manager");
+    this.element.addEventListener("cookie-consent-action", this.onAction);
+    target.append(this.element);
+  }
+  render(data, view) {
+    if (!this.element) return;
+    this.element.data = data;
+    this.element.view = view;
+    this.element.theme = this.options.theme ?? {};
+    this.element.privacyPolicyUrl = this.options.privacyPolicyUrl ?? "";
+    this.element.translations = this.translationSnapshot();
+  }
+  update(options) {
+    this.options = { ...this.options, ...options, theme: { ...this.options.theme, ...options.theme } };
+  }
+  destroy() {
+    this.element?.removeEventListener("cookie-consent-action", this.onAction);
+    this.element?.remove();
+    this.element = void 0;
+  }
+  resolveTarget() {
+    if (this.options.mountTarget instanceof HTMLElement) return this.options.mountTarget;
+    if (typeof this.options.mountTarget === "string") {
+      const target = document.querySelector(this.options.mountTarget);
+      if (target) return target;
+    }
+    return document.body;
+  }
+  translationSnapshot() {
+    const keys = [
+      "title",
+      "description",
+      "acceptAll",
+      "rejectAll",
+      "customize",
+      "save",
+      "close",
+      "noticeTitle",
+      "noticeDescription",
+      "acknowledge",
+      "preferencesTitle",
+      "preferencesDescription",
+      "necessary",
+      "necessaryDescription",
+      "analytics",
+      "analyticsDescription",
+      "marketing",
+      "marketingDescription",
+      "personalization",
+      "personalizationDescription",
+      "alwaysOn",
+      "privacyPolicy"
+    ];
+    return Object.fromEntries(keys.map((key) => [key, this.i18n.text(key)]));
+  }
+};
+
+// src/cookie-manager.ts
+var CookieManager = class {
+  constructor() {
+    this.options = {};
+    this.listeners = /* @__PURE__ */ new Set();
+    this.view = "hidden";
+    this.initialized = false;
+  }
+  init(options = {}) {
+    if (this.initializing) return this.initializing;
+    this.initializing = this.initialize(options);
+    return this.initializing;
+  }
+  onDataChange(listener) {
+    this.listeners.add(listener);
+    if (this.data) listener(this.snapshot());
+    return () => this.listeners.delete(listener);
+  }
+  getData() {
+    return this.data ? this.snapshot() : void 0;
+  }
+  openPreferences() {
+    this.assertInitialized();
+    this.view = "preferences";
+    this.render();
+  }
+  update(options) {
+    this.assertInitialized();
+    this.options = {
+      ...this.options,
+      ...options,
+      theme: { ...this.options.theme, ...options.theme },
+      translations: { ...this.options.translations, ...options.translations }
+    };
+    if (options.language) this.i18n?.setLanguage(options.language);
+    this.ui?.update(this.options);
+    this.render();
+  }
+  destroy() {
+    this.ui?.destroy();
+    this.listeners.clear();
+    this.ui = void 0;
+    this.initialized = false;
+    this.initializing = void 0;
+  }
+  reset() {
+    this.cookie?.remove();
+    this.destroy();
+    this.data = void 0;
+    this.view = "hidden";
+  }
+  async initialize(options) {
+    this.options = options;
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const timeout = options.requestTimeoutMs ?? 5e3;
+    this.cookie = new ConsentCookie(options.cookieName, options.cookieDomain, options.cookieMaxAgeDays);
+    this.reporter = new ConsentReportClient(options.reportEndpoint, fetcher, timeout);
+    this.i18n = new ConsentI18n(options.language, options.translations);
+    const qa = parseQaRegion(options.qaRegion ?? this.qaRegionFromLocation());
+    const stored = qa ? void 0 : this.cookie.read();
+    if (stored) {
+      this.data = { ...stored, preference: { ...stored.preference, necessary: true } };
+    } else {
+      let region = qa;
+      if (!region) {
+        const client = new RegionClient(options.regionEndpoint, fetcher, timeout);
+        try {
+          region = await client.detect();
+        } catch {
+          region = { ...PRIVACY_SAFE_REGION };
+        }
+      }
+      const preference = region.mode === "notice_only" ? this.allPreferences(true) : { ...DEFAULT_PREFERENCE };
+      this.data = { ...region, hasChoice: false, preference };
+    }
+    if (typeof document !== "undefined") {
+      this.ui = new UIController(this.options, this.i18n);
+      this.ui.mount((detail) => this.handleAction(detail));
+    }
+    this.initialized = true;
+    this.view = this.data.hasChoice ? "hidden" : this.data.mode === "opt_in" ? "banner" : "notice";
+    this.render();
+    this.notify();
+    return this.snapshot();
+  }
+  handleAction(detail) {
+    switch (detail.action) {
+      case "open_preferences":
+        this.view = "preferences";
+        this.render();
+        return;
+      case "close_preferences":
+        this.view = this.data?.hasChoice ? "hidden" : this.data?.mode === "opt_in" ? "banner" : "notice";
+        this.render();
+        return;
+      case "accept_all":
+        this.save(this.allPreferences(true), "accept_all");
+        return;
+      case "reject_all":
+        this.save(this.allPreferences(false), "reject_all");
+        return;
+      case "save_preferences":
+        if (detail.preference) this.save(detail.preference);
+        return;
+      case "acknowledge":
+        this.save(this.data?.preference ?? this.allPreferences(true));
+    }
+  }
+  save(preference, reportChoice) {
+    if (!this.data) return;
+    this.data = {
+      ...this.data,
+      hasChoice: true,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      preference: { ...preference, necessary: true }
+    };
+    this.cookie?.write(this.data);
+    this.view = "hidden";
+    this.render();
+    this.notify();
+    if (reportChoice) void this.reporter?.report(reportChoice, this.data).catch(() => void 0);
+  }
+  notify() {
+    const snapshot = this.snapshot();
+    for (const listener of this.listeners) {
+      try {
+        listener(snapshot);
+      } catch {
+      }
+    }
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent("cookie-consent:change", { detail: snapshot }));
+    }
+  }
+  render() {
+    if (this.data) this.ui?.render(this.snapshot(), this.view);
+  }
+  snapshot() {
+    if (!this.data) throw new Error("CookieManager has not initialized");
+    return Object.freeze({ ...this.data, preference: Object.freeze({ ...this.data.preference }) });
+  }
+  qaRegionFromLocation() {
+    if (typeof location === "undefined") return null;
+    return new URLSearchParams(location.search).get("cookie_region");
+  }
+  allPreferences(value) {
+    return { necessary: true, analytics: value, marketing: value, personalization: value };
+  }
+  assertInitialized() {
+    if (!this.initialized) throw new Error("Call cookieManager.init() first");
+  }
+};
+
+// src/index.ts
+var cookieManager = new CookieManager();
+var index_default = cookieManager;
+export {
+  ConsentCookie,
+  CookieManager,
+  RegionClient,
+  cookieManager,
+  index_default as default,
+  modeForCountry,
+  parseQaRegion
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dengdeng0324/cookie-consent-sdk",
+  "version": "1.0.2",
+  "description": "Framework-agnostic cookie consent state machine and Lit Web Components UI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pubfree-Labs/cookie-consent-sdk.git"
+  },
+  "homepage": "https://github.com/Pubfree-Labs/cookie-consent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Pubfree-Labs/cookie-consent-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": true,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepare": "npm run build",
+    "dev": "vite demo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "i18next": "^25.3.0",
+    "js-cookie": "^3.0.5",
+    "lit": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/js-cookie": "^3.0.6",
+    "happy-dom": "^18.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": { "node": ">=20" },
+  "packageManager": "pnpm@10.15.0"
+}