@cookiemunch/testing 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog: @cookiemunch/testing
+
+Every published release, newest first. Dates are the day the version was cut.
+
+## 0.1.0 (2026-10-24)
+
+- Added: `installStub(page, { decision })` (an official stub of the embed's API, versioned as `STUB_VERSION`), `previewUrl(cbid, url, { region, lang, apiKey })` and `decide(page, 'accept' | 'reject' | {…})`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cookie Munch
+
+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,16 @@
-# Temporary Holding Version
+# @cookiemunch/testing
 
-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.
+Test helpers for sites running Cookie Munch: an official, versioned stub of the embed's API, preview
+links, and a helper that answers the real banner. Works with Playwright, or anything with its `Page` shape.
+
+```ts
+import { installStub, previewUrl, decide } from '@cookiemunch/testing';
+
+await installStub(page, { decision: 'accept' });                 // no network, the real API surface
+await page.goto(await previewUrl('your-site-id', 'https://acme.com/pricing', { region: 'de', apiKey }));
+await decide(page, 'reject');                                     // answers the real banner
+```
+
+For a local or preview origin, list it in the site's `devOrigins` (or put `data-env="test"` on the tag):
+the banner then shows to headless browsers and nothing reaches your consent log.
+Docs: [cookiemunch.net/docs/testing](https://cookiemunch.net/docs/testing).

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The official stub of the embed's public API — `window.CookieMunch` (and its `Cookiebot`
+ * alias) plus `window.__fdConsent` — for tests that should not load the real embed.
+ *
+ * It passes the same contract tests as the real embed (test/contract.test.ts), so code that
+ * works against it works against Cookie Munch. It is ONE self-contained function: Playwright
+ * serialises it into the page (`page.addInitScript(cookieMunchStub, options)`), so it may not
+ * close over anything outside itself.
+ */
+type StubDecision = 'accept' | 'reject' | 'none' | Record<string, boolean>;
+interface StubOptions {
+    /** The visitor's answer at load. `none` (default): not decided yet. */
+    decision?: StubDecision;
+    /** The site's custom category ids (`referrals`, `support_chat`, …). */
+    categories?: string[];
+    /** Region code the snapshot reports. Default `eu`. */
+    region?: string;
+    /** `false`: a region that needs no decision (everything allowed until refused). Default true. */
+    required?: boolean;
+}
+/** The version of the stub's contract; it follows `__fdConsent.version`. */
+declare const STUB_VERSION = 1;
+declare function cookieMunchStub(options?: StubOptions): void;
+
+/**
+ * @cookiemunch/testing — test helpers for sites running Cookie Munch (CMU-D02).
+ *
+ *   import { installStub, previewUrl, decide } from '@cookiemunch/testing';
+ *
+ *   await installStub(page, { decision: 'accept' });            // no network, the real API surface
+ *   await page.goto(await previewUrl('cb-…', 'https://acme.com/pricing', { region: 'de', apiKey }));
+ *   await decide(page, 'reject');                                // answers the REAL banner
+ *
+ * Playwright is not a dependency: anything with Playwright's `Page` shape works.
+ * For a local or preview origin, list it in the site's `devOrigins` (or put `data-env="test"`
+ * on the tag): the banner then shows to headless browsers and nothing is recorded.
+ */
+
+/** The part of Playwright's `Page` these helpers use. */
+interface PageLike {
+    addInitScript<A>(script: (arg: A) => unknown, arg: A): Promise<unknown>;
+    evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>;
+    locator(selector: string): LocatorLike;
+}
+interface LocatorLike {
+    first(): LocatorLike;
+    click(opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitFor(opts?: {
+        state?: 'attached' | 'visible';
+        timeout?: number;
+    }): Promise<void>;
+    setChecked(checked: boolean, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    count(): Promise<number>;
+}
+/**
+ * Put the official stub on every page the browser opens, before any page script runs: the
+ * embed's API (`CookieMunch`, `Cookiebot`) and `__fdConsent`, with the decision you choose.
+ * Do not load consent.js as well; block it (`page.route('**\/consent.js', r => r.abort())`).
+ */
+declare function installStub(page: PageLike, options?: StubOptions): Promise<void>;
+interface PreviewOptions {
+    /** A country or subdivision code (`de`, `us-ca`) or `eu`. */
+    region?: string;
+    /** A BCP 47 language tag. */
+    lang?: string;
+    /** An API key with sites:read. Default: process.env.COOKIEMUNCH_API_KEY. */
+    apiKey?: string;
+    /** Default https://api.cookiemunch.net. */
+    baseUrl?: string;
+    /** Token lifetime in seconds, at most 3600. Default 900. */
+    ttlSeconds?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * A preview link for `url`: the real banner, forced to a region and language, shown to a
+ * headless browser, recording nothing. Mints a signed token (POST /v1/sites/{cbid}/preview-token).
+ */
+declare function previewUrl(cbid: string, url: string, opts?: PreviewOptions): Promise<string>;
+/**
+ * Answer the REAL banner as a visitor would: `accept`, `reject`, or per category
+ * (`{ statistics: true, referrals: false }`, opening the settings and saving). Resolves once
+ * the embed has the decision. The banner lives in an open shadow root, which Playwright's CSS
+ * locators pierce.
+ */
+declare function decide(page: PageLike, choice: StubDecision, opts?: {
+    timeout?: number;
+}): Promise<void>;
+
+export { type LocatorLike, type PageLike, type PreviewOptions, STUB_VERSION, type StubDecision, type StubOptions, cookieMunchStub, decide, installStub, previewUrl };

package/dist/index.js

@@ -0,0 +1,197 @@
+// src/stub.ts
+var STUB_VERSION = 1;
+function cookieMunchStub(options = {}) {
+  const w = window;
+  const custom = options.categories ?? [];
+  const required = options.required !== false;
+  const all = ["preferences", "statistics", "marketing", ...custom];
+  let decided = false;
+  let state = {};
+  let stamp = "stub-" + Math.random().toString(36).slice(2, 10);
+  let decidedAt = null;
+  const set = (d) => {
+    if (d === "none" || d === void 0) {
+      decided = false;
+      state = {};
+      for (const c of all) state[c] = !required;
+      return;
+    }
+    decided = true;
+    decidedAt = (/* @__PURE__ */ new Date()).toISOString();
+    state = {};
+    for (const c of all) state[c] = d === "accept" ? true : d === "reject" ? false : d[c] === true || d.all === true && d[c] !== false;
+  };
+  set(options.decision ?? "none");
+  const listeners = {};
+  const fire = (event, ...args) => {
+    for (const fn of (listeners[event] ?? []).slice()) fn(...args);
+  };
+  const consent = () => ({ necessary: true, ...state, stamp });
+  const snapshot = () => ({
+    decided,
+    required,
+    categories: { necessary: true, ...state },
+    stamp,
+    region: options.region ?? "eu",
+    gpc: false,
+    decidedAt
+  });
+  const fdListeners = [];
+  const announce = (cause) => {
+    const c = consent();
+    fire("consentReady", c);
+    const any = state.preferences || state.statistics || state.marketing;
+    fire(any ? "accept" : "decline", c);
+    for (const ev of ["CookieMunchOnConsentReady", any ? "CookieMunchOnAccept" : "CookieMunchOnDecline"]) {
+      w.dispatchEvent(new CustomEvent(ev, { detail: c }));
+    }
+    w.dispatchEvent(new CustomEvent("CookieMunchOnChange", { detail: { consent: c, previous: null, cause } }));
+    const s = snapshot();
+    for (const fn of fdListeners.slice()) fn(s, cause);
+  };
+  const decide2 = (d, cause) => {
+    set(d);
+    announce(cause);
+  };
+  const known = (c) => c === "necessary" || all.indexOf(c) >= 0;
+  const api = {
+    version: "stub",
+    get consent() {
+      return consent();
+    },
+    get hasResponse() {
+      return decided;
+    },
+    get consented() {
+      return decided && all.some((c) => state[c]);
+    },
+    get declined() {
+      return decided && !all.some((c) => state[c]);
+    },
+    // Boolean, like the real one: tri-state lives on __fdConsent.has.
+    hasConsent: (c) => c === "necessary" || state[c] === true,
+    consentId: () => stamp,
+    on: (event, fn) => {
+      (listeners[event] ??= []).push(fn);
+      return () => api.off(event, fn);
+    },
+    once: (event, fn) => {
+      const off = api.on(event, (...a) => (off(), fn(...a)));
+      return off;
+    },
+    off: (event, fn) => {
+      const l = listeners[event] ?? [];
+      const i = l.indexOf(fn);
+      if (i >= 0) l.splice(i, 1);
+    },
+    show: () => Promise.resolve(),
+    showSettings: () => void 0,
+    hide: () => void 0,
+    renew: () => void 0,
+    withdraw: () => decide2("reject", "withdraw"),
+    submitCustomConsent: (p, s, m) => decide2({ ...state, preferences: p, statistics: s, marketing: m }, "selection"),
+    getStatus: () => ({ ui: "ready" })
+  };
+  w.CookieMunch = api;
+  w.Cookiebot = api;
+  const queued = w.__fdConsent && w.__fdConsent.q || [];
+  const fd = {
+    version: 1,
+    provider: "stub",
+    has: (c) => !known(c) ? false : c === "necessary" ? true : decided || !required ? state[c] === true : null,
+    on: (ev, cb) => {
+      if (ev !== "change") return () => void 0;
+      fdListeners.push(cb);
+      if (decided || !required) Promise.resolve().then(() => fdListeners.indexOf(cb) >= 0 && cb(snapshot(), "replay"));
+      return () => {
+        const i = fdListeners.indexOf(cb);
+        if (i >= 0) fdListeners.splice(i, 1);
+      };
+    },
+    ready: () => new Promise((done) => {
+      if (decided || !required) return done(snapshot());
+      const off = fd.on("change", (s) => (off(), done(s)));
+    }),
+    request: (c) => Promise.resolve(fd.has(c) === true),
+    identify: () => void 0,
+    layout: { bottomInset: () => 0, on: () => () => void 0 }
+  };
+  const run = (call) => {
+    const [m, a, b, d] = call;
+    if (m === "on") fd.on(a, b);
+    else if (m === "ready") fd.ready().then(a);
+    else if (m === "request") fd.request(a, b).then(d);
+  };
+  fd.q = { push: (...calls) => (calls.forEach(run), 0) };
+  w.__fdConsent = fd;
+  queued.forEach(run);
+  w.__cmStub = { decide: (d) => decide2(d, d === "accept" ? "accept" : d === "reject" ? "decline" : "selection") };
+  if (decided) Promise.resolve().then(() => announce("replay"));
+}
+
+// src/index.ts
+async function installStub(page, options = {}) {
+  await page.addInitScript(cookieMunchStub, options);
+}
+async function previewUrl(cbid, url, opts = {}) {
+  const env = globalThis.process?.env ?? {};
+  const apiKey = opts.apiKey ?? env.COOKIEMUNCH_API_KEY;
+  if (!apiKey) throw new Error("previewUrl needs an API key with sites:read (apiKey, or COOKIEMUNCH_API_KEY)");
+  const f = opts.fetch ?? globalThis.fetch;
+  if (!f) throw new Error("previewUrl needs fetch");
+  const base = (opts.baseUrl ?? "https://api.cookiemunch.net").replace(/\/+$/, "");
+  const res = await f(`${base}/v1/sites/${encodeURIComponent(cbid)}/preview-token`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ url, ...opts.region ? { region: opts.region } : {}, ...opts.lang ? { lang: opts.lang } : {}, ...opts.ttlSeconds ? { ttlSeconds: opts.ttlSeconds } : {} })
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`preview-token: ${res.status} ${body.error ?? ""}`.trim());
+  if (body.previewUrl) return body.previewUrl;
+  const u = new URL(url);
+  u.searchParams.set("cm_preview", body.token ?? "");
+  if (opts.region) u.searchParams.set("cm_region", opts.region);
+  if (opts.lang) u.searchParams.set("cm_lang", opts.lang);
+  return u.toString();
+}
+async function decide(page, choice, opts = {}) {
+  const timeout = opts.timeout ?? 1e4;
+  const action = async (name) => {
+    const el = page.locator(`[data-action="${name}"]`).first();
+    await el.waitFor({ state: "visible", timeout });
+    await el.click({ timeout });
+  };
+  if (choice === "accept") await action("accept-all");
+  else if (choice === "reject") await action("reject-all");
+  else if (choice !== "none") {
+    await action("customize");
+    for (const [cat, on] of Object.entries(choice)) {
+      const toggle = page.locator(`input[data-cat="${cat}"]`).first();
+      if (await toggle.count() > 0) await toggle.setChecked(on, { timeout });
+    }
+    await action("save");
+  }
+  if (choice !== "none") {
+    await page.evaluate(
+      (t) => new Promise((done, fail) => {
+        const start = Date.now();
+        const tick = () => {
+          const cm = window.CookieMunch;
+          if (cm?.hasResponse) return done();
+          if (Date.now() - start > t) return fail(new Error("the banner did not record a decision"));
+          setTimeout(tick, 50);
+        };
+        tick();
+      }),
+      timeout
+    );
+  }
+}
+export {
+  STUB_VERSION,
+  cookieMunchStub,
+  decide,
+  installStub,
+  previewUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stub.ts","../src/index.ts"],"sourcesContent":["/**\n * The official stub of the embed's public API — `window.CookieMunch` (and its `Cookiebot`\n * alias) plus `window.__fdConsent` — for tests that should not load the real embed.\n *\n * It passes the same contract tests as the real embed (test/contract.test.ts), so code that\n * works against it works against Cookie Munch. It is ONE self-contained function: Playwright\n * serialises it into the page (`page.addInitScript(cookieMunchStub, options)`), so it may not\n * close over anything outside itself.\n */\n\nexport type StubDecision = 'accept' | 'reject' | 'none' | Record<string, boolean>;\n\nexport interface StubOptions {\n  /** The visitor's answer at load. `none` (default): not decided yet. */\n  decision?: StubDecision;\n  /** The site's custom category ids (`referrals`, `support_chat`, …). */\n  categories?: string[];\n  /** Region code the snapshot reports. Default `eu`. */\n  region?: string;\n  /** `false`: a region that needs no decision (everything allowed until refused). Default true. */\n  required?: boolean;\n}\n\n/** The version of the stub's contract; it follows `__fdConsent.version`. */\nexport const STUB_VERSION = 1;\n\nexport function cookieMunchStub(options: StubOptions = {}): void {\n  const w = window as unknown as Record<string, any>;\n  const custom: string[] = options.categories ?? [];\n  const required = options.required !== false;\n  const all = ['preferences', 'statistics', 'marketing', ...custom];\n  let decided = false;\n  let state: Record<string, boolean> = {};\n  let stamp = 'stub-' + Math.random().toString(36).slice(2, 10);\n  let decidedAt: string | null = null;\n  const set = (d: any): void => {\n    if (d === 'none' || d === undefined) {\n      decided = false;\n      state = {};\n      for (const c of all) state[c] = !required;\n      return;\n    }\n    decided = true;\n    decidedAt = new Date().toISOString();\n    state = {};\n    for (const c of all) state[c] = d === 'accept' ? true : d === 'reject' ? false : d[c] === true || (d.all === true && d[c] !== false);\n  };\n  set(options.decision ?? 'none');\n\n  const listeners: Record<string, Array<(...a: any[]) => void>> = {};\n  const fire = (event: string, ...args: any[]): void => {\n    for (const fn of (listeners[event] ?? []).slice()) fn(...args);\n  };\n  const consent = (): Record<string, any> => ({ necessary: true, ...state, stamp });\n  const snapshot = () => ({\n    decided,\n    required,\n    categories: { necessary: true, ...state },\n    stamp,\n    region: options.region ?? 'eu',\n    gpc: false,\n    decidedAt,\n  });\n  const fdListeners: Array<(s: any, cause: string) => void> = [];\n  const announce = (cause: string): void => {\n    const c = consent();\n    fire('consentReady', c);\n    const any = state.preferences || state.statistics || state.marketing;\n    fire(any ? 'accept' : 'decline', c);\n    for (const ev of ['CookieMunchOnConsentReady', any ? 'CookieMunchOnAccept' : 'CookieMunchOnDecline']) {\n      w.dispatchEvent(new CustomEvent(ev, { detail: c }));\n    }\n    w.dispatchEvent(new CustomEvent('CookieMunchOnChange', { detail: { consent: c, previous: null, cause } }));\n    const s = snapshot();\n    for (const fn of fdListeners.slice()) fn(s, cause);\n  };\n  const decide = (d: StubDecision, cause: string): void => {\n    set(d);\n    announce(cause);\n  };\n  const known = (c: string): boolean => c === 'necessary' || all.indexOf(c) >= 0;\n\n  const api: Record<string, any> = {\n    version: 'stub',\n    get consent() {\n      return consent();\n    },\n    get hasResponse() {\n      return decided;\n    },\n    get consented() {\n      return decided && all.some((c) => state[c]);\n    },\n    get declined() {\n      return decided && !all.some((c) => state[c]);\n    },\n    // Boolean, like the real one: tri-state lives on __fdConsent.has.\n    hasConsent: (c: string) => c === 'necessary' || state[c] === true,\n    consentId: () => stamp,\n    on: (event: string, fn: (...a: any[]) => void) => {\n      (listeners[event] ??= []).push(fn);\n      return () => api.off(event, fn);\n    },\n    once: (event: string, fn: (...a: any[]) => void) => {\n      const off = api.on(event, (...a: any[]) => (off(), fn(...a)));\n      return off;\n    },\n    off: (event: string, fn: (...a: any[]) => void) => {\n      const l = listeners[event] ?? [];\n      const i = l.indexOf(fn);\n      if (i >= 0) l.splice(i, 1);\n    },\n    show: () => Promise.resolve(),\n    showSettings: () => undefined,\n    hide: () => undefined,\n    renew: () => undefined,\n    withdraw: () => decide('reject', 'withdraw'),\n    submitCustomConsent: (p: boolean, s: boolean, m: boolean) => decide({ ...state, preferences: p, statistics: s, marketing: m }, 'selection'),\n    getStatus: () => ({ ui: 'ready' }),\n  };\n  w.CookieMunch = api;\n  w.Cookiebot = api;\n\n  const queued: any[] = (w.__fdConsent && w.__fdConsent.q) || [];\n  const fd: Record<string, any> = {\n    version: 1,\n    provider: 'stub',\n    has: (c: string) => (!known(c) ? false : c === 'necessary' ? true : decided || !required ? state[c] === true : null),\n    on: (ev: string, cb: (s: any, cause: string) => void) => {\n      if (ev !== 'change') return () => undefined;\n      fdListeners.push(cb);\n      if (decided || !required) Promise.resolve().then(() => fdListeners.indexOf(cb) >= 0 && cb(snapshot(), 'replay'));\n      return () => {\n        const i = fdListeners.indexOf(cb);\n        if (i >= 0) fdListeners.splice(i, 1);\n      };\n    },\n    ready: () =>\n      new Promise((done) => {\n        if (decided || !required) return done(snapshot());\n        const off = fd.on('change', (s: any) => (off(), done(s)));\n      }),\n    request: (c: string) => Promise.resolve(fd.has(c) === true),\n    identify: () => undefined,\n    layout: { bottomInset: () => 0, on: () => () => undefined },\n  };\n  const run = (call: any[]): void => {\n    const [m, a, b, d] = call;\n    if (m === 'on') fd.on(a, b);\n    else if (m === 'ready') fd.ready().then(a);\n    else if (m === 'request') fd.request(a, b).then(d);\n  };\n  fd.q = { push: (...calls: any[][]) => (calls.forEach(run), 0) };\n  w.__fdConsent = fd;\n  queued.forEach(run);\n  // For tests: change the answer as a visitor would (`window.__cmStub.decide('accept')`).\n  w.__cmStub = { decide: (d: StubDecision) => decide(d, d === 'accept' ? 'accept' : d === 'reject' ? 'decline' : 'selection') };\n  if (decided) Promise.resolve().then(() => announce('replay'));\n}\n","/**\n * @cookiemunch/testing — test helpers for sites running Cookie Munch (CMU-D02).\n *\n *   import { installStub, previewUrl, decide } from '@cookiemunch/testing';\n *\n *   await installStub(page, { decision: 'accept' });            // no network, the real API surface\n *   await page.goto(await previewUrl('cb-…', 'https://acme.com/pricing', { region: 'de', apiKey }));\n *   await decide(page, 'reject');                                // answers the REAL banner\n *\n * Playwright is not a dependency: anything with Playwright's `Page` shape works.\n * For a local or preview origin, list it in the site's `devOrigins` (or put `data-env=\"test\"`\n * on the tag): the banner then shows to headless browsers and nothing is recorded.\n */\n\nimport { cookieMunchStub, type StubOptions, type StubDecision } from './stub.js';\n\nexport { cookieMunchStub, STUB_VERSION, type StubOptions, type StubDecision } from './stub.js';\n\n/** The part of Playwright's `Page` these helpers use. */\nexport interface PageLike {\n  addInitScript<A>(script: (arg: A) => unknown, arg: A): Promise<unknown>;\n  evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>;\n  locator(selector: string): LocatorLike;\n}\nexport interface LocatorLike {\n  first(): LocatorLike;\n  click(opts?: { timeout?: number }): Promise<void>;\n  waitFor(opts?: { state?: 'attached' | 'visible'; timeout?: number }): Promise<void>;\n  setChecked(checked: boolean, opts?: { timeout?: number }): Promise<void>;\n  count(): Promise<number>;\n}\n\n/**\n * Put the official stub on every page the browser opens, before any page script runs: the\n * embed's API (`CookieMunch`, `Cookiebot`) and `__fdConsent`, with the decision you choose.\n * Do not load consent.js as well; block it (`page.route('**\\/consent.js', r => r.abort())`).\n */\nexport async function installStub(page: PageLike, options: StubOptions = {}): Promise<void> {\n  await page.addInitScript(cookieMunchStub, options);\n}\n\nexport interface PreviewOptions {\n  /** A country or subdivision code (`de`, `us-ca`) or `eu`. */\n  region?: string;\n  /** A BCP 47 language tag. */\n  lang?: string;\n  /** An API key with sites:read. Default: process.env.COOKIEMUNCH_API_KEY. */\n  apiKey?: string;\n  /** Default https://api.cookiemunch.net. */\n  baseUrl?: string;\n  /** Token lifetime in seconds, at most 3600. Default 900. */\n  ttlSeconds?: number;\n  fetch?: typeof fetch;\n}\n\n/**\n * A preview link for `url`: the real banner, forced to a region and language, shown to a\n * headless browser, recording nothing. Mints a signed token (POST /v1/sites/{cbid}/preview-token).\n */\nexport async function previewUrl(cbid: string, url: string, opts: PreviewOptions = {}): Promise<string> {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {};\n  const apiKey = opts.apiKey ?? env.COOKIEMUNCH_API_KEY;\n  if (!apiKey) throw new Error('previewUrl needs an API key with sites:read (apiKey, or COOKIEMUNCH_API_KEY)');\n  const f = opts.fetch ?? (globalThis as { fetch?: typeof fetch }).fetch;\n  if (!f) throw new Error('previewUrl needs fetch');\n  const base = (opts.baseUrl ?? 'https://api.cookiemunch.net').replace(/\\/+$/, '');\n  const res = await f(`${base}/v1/sites/${encodeURIComponent(cbid)}/preview-token`, {\n    method: 'POST',\n    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },\n    body: JSON.stringify({ url, ...(opts.region ? { region: opts.region } : {}), ...(opts.lang ? { lang: opts.lang } : {}), ...(opts.ttlSeconds ? { ttlSeconds: opts.ttlSeconds } : {}) }),\n  });\n  const body = (await res.json().catch(() => ({}))) as { previewUrl?: string; token?: string; error?: string };\n  if (!res.ok) throw new Error(`preview-token: ${res.status} ${body.error ?? ''}`.trim());\n  if (body.previewUrl) return body.previewUrl;\n  const u = new URL(url);\n  u.searchParams.set('cm_preview', body.token ?? '');\n  if (opts.region) u.searchParams.set('cm_region', opts.region);\n  if (opts.lang) u.searchParams.set('cm_lang', opts.lang);\n  return u.toString();\n}\n\n/**\n * Answer the REAL banner as a visitor would: `accept`, `reject`, or per category\n * (`{ statistics: true, referrals: false }`, opening the settings and saving). Resolves once\n * the embed has the decision. The banner lives in an open shadow root, which Playwright's CSS\n * locators pierce.\n */\nexport async function decide(page: PageLike, choice: StubDecision, opts: { timeout?: number } = {}): Promise<void> {\n  const timeout = opts.timeout ?? 10_000;\n  const action = async (name: string): Promise<void> => {\n    const el = page.locator(`[data-action=\"${name}\"]`).first();\n    await el.waitFor({ state: 'visible', timeout });\n    await el.click({ timeout });\n  };\n  if (choice === 'accept') await action('accept-all');\n  else if (choice === 'reject') await action('reject-all');\n  else if (choice !== 'none') {\n    await action('customize');\n    for (const [cat, on] of Object.entries(choice)) {\n      const toggle = page.locator(`input[data-cat=\"${cat}\"]`).first();\n      if ((await toggle.count()) > 0) await toggle.setChecked(on, { timeout });\n    }\n    await action('save');\n  }\n  if (choice !== 'none') {\n    await page.evaluate(\n      (t: number) =>\n        new Promise<void>((done, fail) => {\n          const start = Date.now();\n          const tick = (): void => {\n            const cm = (window as unknown as { CookieMunch?: { hasResponse?: boolean } }).CookieMunch;\n            if (cm?.hasResponse) return done();\n            if (Date.now() - start > t) return fail(new Error('the banner did not record a decision'));\n            setTimeout(tick, 50);\n          };\n          tick();\n        }),\n      timeout,\n    );\n  }\n}\n"],"mappings":"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","names":["decide"]}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@cookiemunch/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Test helpers for sites running Cookie Munch: an official versioned stub of the embed's API, preview links, and a helper that answers the real banner",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cookie-Munch/testing.git"
+  },
+  "homepage": "https://cookiemunch.net/docs/testing",
+  "bugs": {
+    "url": "https://github.com/Cookie-Munch/testing/issues"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "2.1.9"
+  }
+}