@buildinams/core 0.3.1 → 0.4.0

package/dist/cookies/index.js

@@ -0,0 +1,188 @@
+// src/cookies/cookie-header.ts
+var decode = (value) => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+var parseCookieHeader = (header) => {
+  const cookies = /* @__PURE__ */ new Map();
+  for (const pair of header.split(";")) {
+    const separatorIndex = pair.indexOf("=");
+    if (separatorIndex === -1) continue;
+    const name = pair.slice(0, separatorIndex).trim();
+    if (!name || cookies.has(name)) continue;
+    cookies.set(name, decode(pair.slice(separatorIndex + 1).trim()));
+  }
+  return cookies;
+};
+var SAME_SITE = { lax: "Lax", strict: "Strict", none: "None" };
+var PRIORITY = { low: "Low", medium: "Medium", high: "High" };
+var serializeCookie = (name, value, options = {}) => {
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+  parts.push(`Path=${options.path ?? "/"}`);
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (typeof options.maxAge === "number") {
+    parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+  }
+  const expires = options.expires !== void 0 ? new Date(options.expires) : typeof options.maxAge === "number" ? new Date(Date.now() + options.maxAge * 1e3) : void 0;
+  if (expires) parts.push(`Expires=${expires.toUTCString()}`);
+  if (options.secure) parts.push("Secure");
+  if (options.httpOnly) parts.push("HttpOnly");
+  if (options.sameSite) parts.push(`SameSite=${SAME_SITE[options.sameSite]}`);
+  if (options.partitioned) parts.push("Partitioned");
+  if (options.priority) parts.push(`Priority=${PRIORITY[options.priority]}`);
+  return parts.join("; ");
+};
+
+// src/cookies/cookie-store.ts
+var BROWSER_STORE = Symbol("browserCookies");
+
+// src/cookies/browser-cookies.ts
+var listeners = /* @__PURE__ */ new Set();
+var notify = () => {
+  listeners.forEach((listener) => listener());
+};
+var assertBrowser = (method) => {
+  if (typeof document === "undefined") {
+    throw new Error(
+      `browserCookies.${method}() can only be called in the browser. On the server, pass \`await cookies()\` from "next/headers" instead.`
+    );
+  }
+};
+var addExternalChangeListeners = () => {
+  const cookieStore = window.cookieStore;
+  cookieStore?.addEventListener("change", notify);
+  window.addEventListener("focus", notify);
+  document.addEventListener("visibilitychange", notify);
+  return () => {
+    cookieStore?.removeEventListener("change", notify);
+    window.removeEventListener("focus", notify);
+    document.removeEventListener("visibilitychange", notify);
+  };
+};
+var removeExternalChangeListeners;
+var browserCookies = {
+  [BROWSER_STORE]: true,
+  get(name) {
+    assertBrowser("get");
+    const value = parseCookieHeader(document.cookie).get(name);
+    return value === void 0 ? void 0 : { value };
+  },
+  set(name, value, options) {
+    assertBrowser("set");
+    if (options?.httpOnly) {
+      throw new Error(
+        `Cookie "${name}" is httpOnly and can only be written on the server.`
+      );
+    }
+    document.cookie = serializeCookie(name, value, options);
+    notify();
+  },
+  subscribe(listener) {
+    assertBrowser("subscribe");
+    listeners.add(listener);
+    removeExternalChangeListeners ??= addExternalChangeListeners();
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        removeExternalChangeListeners?.();
+        removeExternalChangeListeners = void 0;
+      }
+    };
+  }
+};
+
+// src/cookies/cookie-schema.ts
+var invalid = (expected, raw) => {
+  throw new Error(`Invalid cookie value: expected ${expected}, got "${raw}"`);
+};
+var cookieSchema = {
+  string: () => ({
+    parse: (raw) => raw,
+    serialize: (value) => value
+  }),
+  /** Finite numbers only. */
+  number: () => ({
+    parse: (raw) => {
+      const value = Number(raw);
+      if (raw.trim() === "" || !Number.isFinite(value)) {
+        return invalid("a finite number", raw);
+      }
+      return value;
+    },
+    serialize: (value) => String(value)
+  }),
+  /** Stored as `"true"` / `"false"`. */
+  boolean: () => ({
+    parse: (raw) => {
+      if (raw === "true") return true;
+      if (raw === "false") return false;
+      return invalid('"true" or "false"', raw);
+    },
+    serialize: (value) => String(value)
+  }),
+  /** One of a fixed set of string literals. */
+  enum: (values) => ({
+    parse: (raw) => {
+      if (!values.includes(raw)) {
+        return invalid(`one of ${values.join(", ")}`, raw);
+      }
+      return raw;
+    },
+    serialize: (value) => value
+  }),
+  /**
+   * JSON-encoded value. `validate` receives the result of `JSON.parse` and must return the typed value or throw.
+   * A zod/valibot/etc. `parse` function fits directly.
+   *
+   * @example
+   * ```ts
+   * cookieSchema.json(z.object({ analytics: z.boolean() }).parse);
+   *
+   * // without a validation library
+   * cookieSchema.json((input) => {
+   *   if (typeof input !== "object" || input === null || !("analytics" in input)) throw new Error();
+   *   return { analytics: input.analytics === true };
+   * });
+   * ```
+   */
+  json: (validate) => ({
+    parse: (raw) => validate(JSON.parse(raw)),
+    serialize: (value) => JSON.stringify(value)
+  })
+};
+
+// src/cookies/define-cookie.ts
+function defineCookie(config) {
+  const { name, schema, defaultValue } = config;
+  const options = { path: "/", ...config.options };
+  const fallback = defaultValue === void 0 ? null : defaultValue;
+  const get = (store) => {
+    const raw = store.get(name)?.value;
+    if (raw === void 0) return fallback;
+    try {
+      return schema.parse(raw);
+    } catch {
+      return fallback;
+    }
+  };
+  const set = (store, value, overrides) => {
+    store.set(name, schema.serialize(value), { ...options, ...overrides });
+  };
+  const remove = (store) => {
+    store.set(name, "", { ...options, maxAge: 0, expires: /* @__PURE__ */ new Date(0) });
+  };
+  return {
+    name,
+    httpOnly: options.httpOnly ?? false,
+    get,
+    set,
+    delete: remove
+  };
+}
+
+export { browserCookies, cookieSchema, defineCookie };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/cookies/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cookies/cookie-header.ts","../../src/cookies/cookie-store.ts","../../src/cookies/browser-cookies.ts","../../src/cookies/cookie-schema.ts","../../src/cookies/define-cookie.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { CookieAttributes } from \"./cookie-store\";\n\nconst decode = (value: string) => {\n\ttry {\n\t\treturn decodeURIComponent(value);\n\t} catch {\n\t\treturn value;\n\t}\n};\n\n/**\n * Parses a `Cookie` header / `document.cookie` string. The first occurrence of a name wins, matching how\n * browsers order cookies (most specific path first).\n */\nexport const parseCookieHeader = (header: string): Map<string, string> => {\n\tconst cookies = new Map<string, string>();\n\n\tfor (const pair of header.split(\";\")) {\n\t\tconst separatorIndex = pair.indexOf(\"=\");\n\t\tif (separatorIndex === -1) continue;\n\n\t\tconst name = pair.slice(0, separatorIndex).trim();\n\t\tif (!name || cookies.has(name)) continue;\n\n\t\tcookies.set(name, decode(pair.slice(separatorIndex + 1).trim()));\n\t}\n\n\treturn cookies;\n};\n\nconst SAME_SITE = { lax: \"Lax\", strict: \"Strict\", none: \"None\" } as const;\nconst PRIORITY = { low: \"Low\", medium: \"Medium\", high: \"High\" } as const;\n\n/**\n * Serializes a cookie to a `Set-Cookie` / `document.cookie` string, encoding the value the same way Next.js does.\n */\nexport const serializeCookie = (\n\tname: string,\n\tvalue: string,\n\toptions: CookieAttributes = {},\n): string => {\n\tconst parts = [`${name}=${encodeURIComponent(value)}`];\n\n\tparts.push(`Path=${options.path ?? \"/\"}`);\n\tif (options.domain) parts.push(`Domain=${options.domain}`);\n\n\tif (typeof options.maxAge === \"number\") {\n\t\tparts.push(`Max-Age=${Math.floor(options.maxAge)}`);\n\t}\n\n\tconst expires =\n\t\toptions.expires !== undefined\n\t\t\t? new Date(options.expires)\n\t\t\t: typeof options.maxAge === \"number\"\n\t\t\t\t? new Date(Date.now() + options.maxAge * 1000)\n\t\t\t\t: undefined;\n\tif (expires) parts.push(`Expires=${expires.toUTCString()}`);\n\n\tif (options.secure) parts.push(\"Secure\");\n\tif (options.httpOnly) parts.push(\"HttpOnly\");\n\tif (options.sameSite) parts.push(`SameSite=${SAME_SITE[options.sameSite]}`);\n\tif (options.partitioned) parts.push(\"Partitioned\");\n\tif (options.priority) parts.push(`Priority=${PRIORITY[options.priority]}`);\n\n\treturn parts.join(\"; \");\n};\n","/**\n * Every cookie attribute a store can write. Mirrors the options of Next.js' `cookies().set()`.\n */\nexport type CookieAttributes = {\n\t/** @default \"/\" */\n\tpath?: string;\n\tdomain?: string;\n\t/** Lifetime in seconds, relative to the moment the cookie is written. */\n\tmaxAge?: number;\n\t/** Absolute expiry. A `number` is a unix timestamp in milliseconds. */\n\texpires?: Date | number;\n\tsecure?: boolean;\n\t/** `\"none\"` requires `secure: true`, browsers reject the cookie otherwise. */\n\tsameSite?: \"lax\" | \"strict\" | \"none\";\n\t/** Hides the cookie from client-side JavaScript. Can only be written on the server. */\n\thttpOnly?: boolean;\n\tpartitioned?: boolean;\n\tpriority?: \"low\" | \"medium\" | \"high\";\n};\n\n/**\n * Anything cookies can be read from.\n *\n * Satisfied by:\n * - `await cookies()` from `next/headers` (server components, server actions, route handlers)\n * - `request.cookies` in Next.js proxy / middleware (`NextRequest`)\n * - `response.cookies` in Next.js proxy / middleware / route handlers (`NextResponse`)\n * - `browserCookies` from `@buildinams/core/cookies` (client)\n */\nexport type CookieReader = {\n\tget(name: string): { value: string } | undefined;\n};\n\n/**\n * Anything cookies can be written to.\n *\n * Satisfied by:\n * - `await cookies()` from `next/headers`, in server actions and route handlers only (Next.js throws in server components)\n * - `response.cookies` in Next.js proxy / middleware / route handlers (`NextResponse`)\n * - `browserCookies` from `@buildinams/core/cookies` (client)\n */\nexport type CookieWriter = {\n\tset(name: string, value: string, attributes?: CookieAttributes): unknown;\n};\n\nexport const BROWSER_STORE = Symbol(\"browserCookies\");\n\n/** Marks `browserCookies`, so server-only cookies can reject it at compile time. */\nexport type BrowserBrand = { readonly [BROWSER_STORE]: true };\n\n/** A `CookieReader` that isn't `browserCookies`. Every Next.js cookie store qualifies. */\nexport type ServerCookieReader = CookieReader & {\n\treadonly [BROWSER_STORE]?: never;\n};\n\n/** A `CookieWriter` that isn't `browserCookies`. Every writable Next.js cookie store qualifies. */\nexport type ServerCookieWriter = CookieWriter & {\n\treadonly [BROWSER_STORE]?: never;\n};\n","import { parseCookieHeader, serializeCookie } from \"./cookie-header\";\nimport type { BrowserBrand, CookieReader, CookieWriter } from \"./cookie-store\";\nimport { BROWSER_STORE } from \"./cookie-store\";\n\ntype Listener = () => void;\n\nconst listeners = new Set<Listener>();\n\nconst notify = () => {\n\tlisteners.forEach((listener) => listener());\n};\n\nconst assertBrowser = (method: string) => {\n\tif (typeof document === \"undefined\") {\n\t\tthrow new Error(\n\t\t\t`browserCookies.${method}() can only be called in the browser. On the server, pass \\`await cookies()\\` from \"next/headers\" instead.`,\n\t\t);\n\t}\n};\n\n// Picks up writes we don't make ourselves: server responses, other tabs, devtools.\nconst addExternalChangeListeners = () => {\n\tconst cookieStore = (\n\t\twindow as {\n\t\t\tcookieStore?: Pick<\n\t\t\t\tEventTarget,\n\t\t\t\t\"addEventListener\" | \"removeEventListener\"\n\t\t\t>;\n\t\t}\n\t).cookieStore;\n\n\tcookieStore?.addEventListener(\"change\", notify);\n\twindow.addEventListener(\"focus\", notify);\n\tdocument.addEventListener(\"visibilitychange\", notify);\n\n\treturn () => {\n\t\tcookieStore?.removeEventListener(\"change\", notify);\n\t\twindow.removeEventListener(\"focus\", notify);\n\t\tdocument.removeEventListener(\"visibilitychange\", notify);\n\t};\n};\n\ntype BrowserCookieStore = CookieReader &\n\tCookieWriter &\n\tBrowserBrand & {\n\t\t/** Calls `listener` whenever cookies may have changed. Returns an unsubscribe function. */\n\t\tsubscribe(listener: Listener): () => void;\n\t};\n\nlet removeExternalChangeListeners: (() => void) | undefined;\n\n/**\n * Client-side cookie store backed by `document.cookie`. Implements `CookieReader` and `CookieWriter`, so it can be\n * passed to any cookie definition: `themeCookie.get(browserCookies)`.\n *\n * Reads and writes are synchronous. Values are URL-encoded the same way Next.js does, so cookies written here can be\n * read on the server and vice versa.\n */\nexport const browserCookies: BrowserCookieStore = {\n\t[BROWSER_STORE]: true,\n\n\tget(name) {\n\t\tassertBrowser(\"get\");\n\t\tconst value = parseCookieHeader(document.cookie).get(name);\n\t\treturn value === undefined ? undefined : { value };\n\t},\n\n\tset(name, value, options) {\n\t\tassertBrowser(\"set\");\n\t\tif (options?.httpOnly) {\n\t\t\tthrow new Error(\n\t\t\t\t`Cookie \"${name}\" is httpOnly and can only be written on the server.`,\n\t\t\t);\n\t\t}\n\t\tdocument.cookie = serializeCookie(name, value, options);\n\t\tnotify();\n\t},\n\n\tsubscribe(listener) {\n\t\tassertBrowser(\"subscribe\");\n\t\tlisteners.add(listener);\n\t\tremoveExternalChangeListeners ??= addExternalChangeListeners();\n\n\t\treturn () => {\n\t\t\tlisteners.delete(listener);\n\t\t\tif (listeners.size === 0) {\n\t\t\t\tremoveExternalChangeListeners?.();\n\t\t\t\tremoveExternalChangeListeners = undefined;\n\t\t\t}\n\t\t};\n\t},\n};\n","/**\n * Converts between a typed value and the raw string stored in the cookie.\n *\n * - `parse` receives the decoded cookie string and must **throw** when the value is invalid.\n *   Cookies are user-controlled input, so an invalid value is treated as \"cookie not set\".\n * - `serialize` turns a typed value into a string. URL-encoding is handled by the cookie store, don't encode here.\n *\n * Structurally compatible with `Schema<Value, string>` from `@buildinams/core/schema`.\n *\n * @example\n * ```ts\n * const dateSchema: CookieSchema<Date> = {\n *   parse: (raw) => {\n *     const date = new Date(raw);\n *     if (Number.isNaN(date.getTime())) throw new Error(\"Invalid date\");\n *     return date;\n *   },\n *   serialize: (value) => value.toISOString(),\n * };\n * ```\n */\nexport type CookieSchema<Value> = {\n\tparse: (raw: string) => Value;\n\tserialize: (value: Value) => string;\n};\n\nconst invalid = (expected: string, raw: string): never => {\n\tthrow new Error(`Invalid cookie value: expected ${expected}, got \"${raw}\"`);\n};\n\n/**\n * Ready-made `CookieSchema`s for common value types.\n *\n * @example\n * ```ts\n * cookieSchema.string();                    // string\n * cookieSchema.number();                    // number\n * cookieSchema.boolean();                   // boolean\n * cookieSchema.enum([\"light\", \"dark\"]);     // \"light\" | \"dark\"\n * cookieSchema.json(ConsentSchema.parse);   // z.infer<typeof ConsentSchema>\n * ```\n */\nexport const cookieSchema = {\n\tstring: (): CookieSchema<string> => ({\n\t\tparse: (raw) => raw,\n\t\tserialize: (value) => value,\n\t}),\n\n\t/** Finite numbers only. */\n\tnumber: (): CookieSchema<number> => ({\n\t\tparse: (raw) => {\n\t\t\tconst value = Number(raw);\n\t\t\tif (raw.trim() === \"\" || !Number.isFinite(value)) {\n\t\t\t\treturn invalid(\"a finite number\", raw);\n\t\t\t}\n\t\t\treturn value;\n\t\t},\n\t\tserialize: (value) => String(value),\n\t}),\n\n\t/** Stored as `\"true\"` / `\"false\"`. */\n\tboolean: (): CookieSchema<boolean> => ({\n\t\tparse: (raw) => {\n\t\t\tif (raw === \"true\") return true;\n\t\t\tif (raw === \"false\") return false;\n\t\t\treturn invalid('\"true\" or \"false\"', raw);\n\t\t},\n\t\tserialize: (value) => String(value),\n\t}),\n\n\t/** One of a fixed set of string literals. */\n\tenum: <const Values extends readonly [string, ...string[]]>(\n\t\tvalues: Values,\n\t): CookieSchema<Values[number]> => ({\n\t\tparse: (raw) => {\n\t\t\tif (!(values as readonly string[]).includes(raw)) {\n\t\t\t\treturn invalid(`one of ${values.join(\", \")}`, raw);\n\t\t\t}\n\t\t\treturn raw as Values[number];\n\t\t},\n\t\tserialize: (value) => value,\n\t}),\n\n\t/**\n\t * JSON-encoded value. `validate` receives the result of `JSON.parse` and must return the typed value or throw.\n\t * A zod/valibot/etc. `parse` function fits directly.\n\t *\n\t * @example\n\t * ```ts\n\t * cookieSchema.json(z.object({ analytics: z.boolean() }).parse);\n\t *\n\t * // without a validation library\n\t * cookieSchema.json((input) => {\n\t *   if (typeof input !== \"object\" || input === null || !(\"analytics\" in input)) throw new Error();\n\t *   return { analytics: input.analytics === true };\n\t * });\n\t * ```\n\t */\n\tjson: <Value>(validate: (input: unknown) => Value): CookieSchema<Value> => ({\n\t\tparse: (raw) => validate(JSON.parse(raw)),\n\t\tserialize: (value) => JSON.stringify(value),\n\t}),\n};\n","import type { CookieSchema } from \"./cookie-schema\";\nimport type {\n\tCookieAttributes,\n\tCookieReader,\n\tCookieWriter,\n\tServerCookieReader,\n\tServerCookieWriter,\n} from \"./cookie-store\";\n\n/**\n * Attributes fixed on a cookie definition, applied to every write and to `delete()`.\n */\nexport type CookieOptions = Omit<CookieAttributes, \"expires\">;\n\n/**\n * Per-write lifetime overrides. Path, domain etc. stay on the definition so `delete()` always hits the same cookie.\n */\nexport type CookieWriteOptions = Pick<CookieAttributes, \"maxAge\" | \"expires\">;\n\ntype ReadValue<Value, HasDefault extends boolean> = HasDefault extends true\n\t? Value\n\t: Value | null;\n\n/**\n * A typed cookie readable and writable on the server and in the browser. Create with `defineCookie()`.\n *\n * - `Value`: the type written and read.\n * - `HasDefault`: `true` when a `defaultValue` is defined. Reads return `Value`, otherwise `Value | null`.\n */\nexport type Cookie<Value, HasDefault extends boolean = boolean> = {\n\treadonly name: string;\n\treadonly httpOnly: false;\n\t/** Reads and parses the cookie. Returns the default (or `null`) when it is missing or invalid. */\n\tget(store: CookieReader): ReadValue<Value, HasDefault>;\n\t/** Serializes and writes the cookie with the definition's options. */\n\tset(store: CookieWriter, value: Value, options?: CookieWriteOptions): void;\n\t/** Expires the cookie. */\n\tdelete(store: CookieWriter): void;\n};\n\n/**\n * A typed httpOnly cookie. Same API as `Cookie`, but only accepts server stores: passing `browserCookies` is a\n * compile error, since the browser can't read or write it.\n */\nexport type ServerCookie<Value, HasDefault extends boolean = boolean> = {\n\treadonly name: string;\n\treadonly httpOnly: true;\n\tget(store: ServerCookieReader): ReadValue<Value, HasDefault>;\n\tset(\n\t\tstore: ServerCookieWriter,\n\t\tvalue: Value,\n\t\toptions?: CookieWriteOptions,\n\t): void;\n\tdelete(store: ServerCookieWriter): void;\n};\n\n/**\n * The type written to a cookie.\n *\n * @example\n * ```ts\n * type Theme = CookieWriteValue<typeof themeCookie>; // \"light\" | \"dark\"\n * ```\n */\nexport type CookieWriteValue<\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends Cookie<any> | ServerCookie<any>,\n> = Parameters<T[\"set\"]>[1];\n\n/**\n * The type read from a cookie: `CookieWriteValue | null` when there is no `defaultValue`.\n */\nexport type CookieReadValue<\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends Cookie<any> | ServerCookie<any>,\n> = ReturnType<T[\"get\"]>;\n\ntype CookieConfig<Value, HttpOnly extends boolean> = {\n\t/** Cookie name, as stored in the browser. */\n\tname: string;\n\t/** How to convert between the typed value and the stored string. See `cookieSchema`. */\n\tschema: CookieSchema<Value>;\n\t/** Attributes used for every write. `path` defaults to `\"/\"`. */\n\toptions?: Omit<CookieOptions, \"httpOnly\"> & { httpOnly?: HttpOnly };\n};\n\ntype DefinedCookie<\n\tValue,\n\tHasDefault extends boolean,\n\tHttpOnly extends boolean,\n> = HttpOnly extends true\n\t? ServerCookie<Value, HasDefault>\n\t: Cookie<Value, HasDefault>;\n\n/**\n * Defines a typed cookie that can be read and written with the same API on the server (Next.js) and on the client.\n * With `options.httpOnly: true` it returns a `ServerCookie`, which rejects `browserCookies` at compile time.\n *\n * Define it next to the code it belongs to (e.g. `src/features/auth/cookies.ts`), in a module without\n * `\"use client\"` / `\"use server\"`, so both environments can import it.\n *\n * @example\n * ```ts\n * import { cookieSchema, defineCookie } from \"@buildinams/core/cookies\";\n *\n * export const themeCookie = defineCookie({\n *   name: \"theme\",\n *   schema: cookieSchema.enum([\"light\", \"dark\"]),\n *   defaultValue: \"light\",\n *   options: { maxAge: 60 * 60 * 24 * 365, sameSite: \"lax\" },\n * });\n *\n * // server component / server action / route handler\n * const theme = themeCookie.get(await cookies()); // \"light\" | \"dark\"\n * themeCookie.set(await cookies(), \"dark\"); // server action / route handler only\n *\n * // client\n * themeCookie.set(browserCookies, \"dark\");\n * const theme = useCookieValue(themeCookie); // @buildinams/react/cookies\n * ```\n */\nexport function defineCookie<Value, HttpOnly extends boolean = false>(\n\tconfig: CookieConfig<Value, HttpOnly> & { defaultValue: NoInfer<Value> },\n): DefinedCookie<Value, true, HttpOnly>;\nexport function defineCookie<Value, HttpOnly extends boolean = false>(\n\tconfig: CookieConfig<Value, HttpOnly> & { defaultValue?: undefined },\n): DefinedCookie<Value, false, HttpOnly>;\nexport function defineCookie<Value>(\n\tconfig: CookieConfig<Value, boolean> & { defaultValue?: Value },\n): Cookie<Value> | ServerCookie<Value> {\n\tconst { name, schema, defaultValue } = config;\n\tconst options: CookieOptions = { path: \"/\", ...config.options };\n\tconst fallback = defaultValue === undefined ? null : defaultValue;\n\n\tconst get = (store: CookieReader) => {\n\t\tconst raw = store.get(name)?.value;\n\t\tif (raw === undefined) return fallback;\n\t\ttry {\n\t\t\treturn schema.parse(raw);\n\t\t} catch {\n\t\t\treturn fallback;\n\t\t}\n\t};\n\n\tconst set = (\n\t\tstore: CookieWriter,\n\t\tvalue: Value,\n\t\toverrides?: CookieWriteOptions,\n\t) => {\n\t\tstore.set(name, schema.serialize(value), { ...options, ...overrides });\n\t};\n\n\tconst remove = (store: CookieWriter) => {\n\t\tstore.set(name, \"\", { ...options, maxAge: 0, expires: new Date(0) });\n\t};\n\n\treturn {\n\t\tname,\n\t\thttpOnly: options.httpOnly ?? false,\n\t\tget,\n\t\tset,\n\t\tdelete: remove,\n\t} as Cookie<Value> | ServerCookie<Value>;\n}\n"]}

package/dist/define-events-CxZjoUlG.d.ts

@@ -0,0 +1,255 @@
+type PageType = "home" | "collection" | "product" | "search" | "cart" | "checkout" | "account" | "content" | (string & Record<never, never>);
+/** What `videos()` reports for a video. */
+type VideoPlayed = {
+    videoTitle?: string;
+    videoUrl?: string;
+    /** E.g. `"html5"` or `"youtube"`. */
+    videoProvider?: string;
+    /** Seconds. */
+    videoDuration?: number;
+    /** Seconds. */
+    videoCurrentTime?: number;
+    videoPercent?: number;
+};
+/** What `forms()` reports for a form. Never field values. */
+type FormUsed = {
+    formId?: string;
+    formName?: string;
+    /** Absolute URL the form submits to. */
+    formDestination?: string;
+};
+/** What `pageViews()` reports: the page's fields from `attributes("page-view")`, with the project's own. */
+type PageViewed = {
+    url?: string;
+    title?: string;
+    pageType?: PageType;
+};
+/** What `clicks()` reports for a link or button. */
+type Clicked = {
+    elementType: "link" | "button";
+    /** Stable id, independent of locale and copy. */
+    elementId?: string;
+    text?: string;
+    /** Absolute. Links only. */
+    url?: string;
+    /** Whether the link leaves the site. */
+    outbound?: boolean;
+    /** Where on the page, e.g. `"header"` or `"footer"`. */
+    location?: string;
+};
+/** What `scroll()` reports, once per URL for each threshold. */
+type Scrolled = {
+    /** The threshold reached, of the element scrolled into view. */
+    percentScrolled: number;
+    /** Stable id, for pages with several tracked elements. */
+    elementId?: string;
+};
+/** The project's data for what `ecommerce()` reports, set on elements with `attach()`. */
+type EcommerceShapes = {
+    /** A product, e.g. `{ product, variant }`. On cards and product pages alike. */
+    item: object;
+    list: object;
+    promotion: object;
+};
+/** A shape of `Shapes` that's an object, or `never` without it. */
+type ShapeLeaf<Shapes, Key extends string> = Shapes extends {
+    [K in Key]: infer Leaf extends object;
+} ? Leaf : never;
+/** An item where it was seen or selected: its list, its position in it, and the promotion around it. */
+type PlacedItem<Shapes extends EcommerceShapes> = {
+    item: Shapes["item"];
+    list?: Shapes["list"];
+    /** In its list, from 0. */
+    index?: number;
+    promotion?: Shapes["promotion"];
+};
+/** What `ecommerce()` reports, by name: the project's item, list and promotion, placed by the markup around them. */
+type EcommerceOccurrences<Shapes extends EcommerceShapes> = {
+    /** On a product page or quick view, placed where the product was last selected. */
+    itemViewed: PlacedItem<Shapes>;
+    itemSelected: PlacedItem<Shapes>;
+    /** One per list and batch. */
+    itemsViewed: {
+        list?: Shapes["list"];
+        items: Omit<PlacedItem<Shapes>, "list">[];
+    };
+    /** With the items featured in it outside a list. */
+    promotionViewed: {
+        promotion: Shapes["promotion"];
+        items: Shapes["item"][];
+    };
+    /** With `item` when the click was on a featured item. */
+    promotionSelected: {
+        promotion: Shapes["promotion"];
+        item?: Shapes["item"];
+    };
+};
+/** A cart line's change, as `createCartChanges()` reports it. */
+type CartChange<Item> = {
+    item: Item;
+    /** Added or removed. */
+    quantity: number;
+    /** Unit price. */
+    price: number;
+};
+/** What `createCartChanges()` reports, by name, for the project's cart line item. */
+type CartOccurrences<Item> = {
+    addedToCart: {
+        currency: string;
+        value: number;
+        items: CartChange<Item>[];
+    };
+    removedFromCart: {
+        currency: string;
+        value: number;
+        items: CartChange<Item>[];
+    };
+};
+
+/** What a project emits: each event's name with its payload. Declare it with `type`, as an `interface` isn't one. */
+type EventMap = Record<string, object>;
+/** `EcommerceShapes` of a project's events. */
+type ShapesOf<Events> = {
+    item: Events extends {
+        itemViewed: {
+            item: infer Item extends object;
+        };
+    } ? Item : Events extends {
+        itemSelected: {
+            item: infer Item extends object;
+        };
+    } ? Item : Events extends {
+        itemsViewed: {
+            items: {
+                item: infer Item extends object;
+            }[];
+        };
+    } ? Item : Events extends {
+        promotionViewed: {
+            items: (infer Item extends object)[];
+        };
+    } ? Item : never;
+    list: Events extends {
+        itemsViewed: {
+            list?: infer List;
+        };
+    } ? Extract<List, object> : Events extends {
+        itemSelected: {
+            list?: infer List;
+        };
+    } ? Extract<List, object> : Events extends {
+        itemViewed: {
+            list?: infer List;
+        };
+    } ? Extract<List, object> : never;
+    promotion: Events extends {
+        promotionViewed: {
+            promotion: infer Promotion extends object;
+        };
+    } ? Promotion : Events extends {
+        promotionSelected: {
+            promotion: infer Promotion extends object;
+        };
+    } ? Promotion : Events extends {
+        itemSelected: {
+            promotion?: infer Promotion;
+        };
+    } ? Extract<Promotion, object> : never;
+};
+/** The cart line item of a project's events. */
+type CartItemOf<Events> = Events extends {
+    addedToCart: {
+        items: CartChange<infer Item>[];
+    };
+} ? Item : never;
+type AnalyticsEventName<Events extends EventMap> = keyof Events & string;
+/** Payload is optional when every field of it is. */
+type AnalyticsPayloadArgs<Events extends EventMap, N extends AnalyticsEventName<Events>> = Record<never, never> extends Events[N] ? [payload?: Events[N]] : [payload: Events[N]];
+/** The logged-in visitor. Destinations decide which fields they forward, and only with the consent they need. */
+type AnalyticsUser = {
+    id?: string;
+    email?: string;
+    /** E.164, e.g. `"+31612345678"`. */
+    phone?: string;
+    /** Whether the customer has ordered before. */
+    type?: "new" | "returning";
+};
+/** Fields for `context` and `setContext()`, with the project's own `Context`. */
+type AnalyticsContextFields<Context extends object = Record<never, never>> = {
+    user?: AnalyticsUser & (Context extends {
+        user?: infer User;
+    } ? User : unknown);
+    /** BCP 47, e.g. `"nl-NL"`. */
+    locale?: string;
+    /** The storefront market, ISO 3166-1 alpha-2, e.g. `"NL"`. Not where the visitor is. */
+    market?: string;
+} & Omit<Context, "user">;
+type AnalyticsContext<Context extends object = Record<never, never>> = {
+    url: string;
+    title: string;
+    referrer: string;
+} & AnalyticsContextFields<Context>;
+/** What's tracked, as subscribers and connected destinations receive it. */
+type AnalyticsEnvelope<Events extends EventMap, Context extends object = Record<never, never>, N extends AnalyticsEventName<Events> = AnalyticsEventName<Events>> = {
+    [K in N]: {
+        /** Unique per event; lets destinations dedupe client and server events (e.g. Meta `eventID`). */
+        id: string;
+        name: K;
+        payload: Events[K];
+        context: AnalyticsContext<Context>;
+    };
+}[N];
+
+declare const shapeType: unique symbol;
+/** A type as a value, from `shape<T>()`. Holds nothing at runtime. */
+type Shape<T> = {
+    readonly [shapeType]?: T;
+};
+/**
+ * A type as a value, e.g. an event's payload in `defineEvents()`. Holds nothing at runtime, so it costs nothing in the
+ * bundle.
+ *
+ * @example
+ * ```ts
+ * defineEvents({ login: { description: "…", payload: shape<{ method: "email" }>() } });
+ * ```
+ */
+declare const shape: <T>() => Shape<T>;
+/** One event of the project: what it means and when it's tracked, and its payload. */
+type EventDefinition<Payload extends object = object> = {
+    /** When it's tracked and what it means, for whoever reads the catalog: developers, agents and analysts. */
+    description: string;
+    /** Leave it out for events without fields. */
+    payload?: Shape<Payload>;
+};
+/** Every event of the project, by name. */
+type EventCatalog<Events extends EventMap = EventMap> = {
+    [N in keyof Events]: Record<never, never> extends Events[N] ? EventDefinition<Events[N]> : EventDefinition<Events[N]> & {
+        payload: Shape<Events[N]>;
+    };
+};
+/** The events of a catalog from `defineEvents()`, for `createAnalytics<Events>()`. */
+type EventsOf<Catalog> = {
+    [N in keyof Catalog]: Catalog[N] extends {
+        payload?: Shape<infer Payload>;
+    } ? unknown extends Payload ? Record<never, never> : Payload : Record<never, never>;
+};
+/**
+ * Declares the project's events as a value: each event's name, what it means, and its payload. It's the one place
+ * to read what the project tracks, also at runtime through `analytics.routes()`. Pass it to `createAnalytics()`.
+ *
+ * @example
+ * ```ts
+ * export const events = defineEvents({
+ *   newsletterSignedUp: {
+ *     description: "The newsletter form was submitted successfully.",
+ *     payload: shape<{ source: "footer" | "popup" }>(),
+ *   },
+ * });
+ *
+ * export type Events = EventsOf<typeof events>;
+ * ```
+ */
+declare const defineEvents: <Catalog extends Record<string, EventDefinition>>(catalog: Catalog) => Catalog;
+
+export { type AnalyticsEventName as A, type CartItemOf as C, type EventMap as E, type FormUsed as F, type PageViewed as P, type Shape as S, type VideoPlayed as V, type AnalyticsPayloadArgs as a, type AnalyticsContextFields as b, type AnalyticsEnvelope as c, type EventCatalog as d, defineEvents as e, type EventDefinition as f, type EventsOf as g, type AnalyticsContext as h, type AnalyticsUser as i, type EcommerceShapes as j, type ShapesOf as k, type Clicked as l, type EcommerceOccurrences as m, type ShapeLeaf as n, type Scrolled as o, type PageType as p, type CartOccurrences as q, shape as s };

package/dist/destination-5KJ5PeR3.d.ts

@@ -0,0 +1,122 @@
+import { c as ConsentState, C as ConsentCategory } from './index-Zef1nnTP.js';
+import { E as EventMap, h as AnalyticsContext, A as AnalyticsEventName, f as EventDefinition, c as AnalyticsEnvelope, g as EventsOf } from './define-events-CxZjoUlG.js';
+
+/** One event in a destination's own vocabulary, narrowed by `name`. */
+type DestinationEvent<Accepts extends object> = {
+    [N in keyof Accepts & string]: {
+        name: N;
+        payload: Accepts[N];
+    };
+}[keyof Accepts & string];
+/** What a destination's callbacks receive with each payload. */
+type DestinationEventContext<Context extends object = Record<never, never>> = {
+    /** Of the tracked event: unique per event, e.g. for Meta's `eventID`. */
+    id: string;
+    /** Of the tracked event, with the project's own fields too. */
+    context: AnalyticsContext<Context>;
+    /** The current answer, `null` until answered, e.g. to send personal data only with marketing consent. */
+    consent: ConsentState;
+};
+/** What a destination's `setup` receives. */
+type DestinationSetupContext<Accepts extends object, Context extends object = Record<never, never>> = {
+    /** Subscribes a callback to one of the destination's events. Returns a function that unsubscribes it. */
+    subscribe: <N extends keyof Accepts & string>(event: N, callback: (payload: Accepts[N], context: DestinationEventContext<Context>) => void) => () => void;
+};
+/**
+ * Forwards events to one provider (GTM, Meta, Shopify, …), in the provider's own vocabulary: `Accepts` holds the
+ * minimum shape of every event it takes. Shaped like Hydrogen's `StorefrontAnalyticsDestination`. `map()` turns it
+ * into one that accepts the project's events, which `withConsent()` hands to `createAnalytics()`. Telling a provider the
+ * visitor's consent is a `ConsentTarget`'s job.
+ */
+type AnalyticsDestination<Accepts extends object, Context extends object = Record<never, never>> = {
+    /** Prefixes this destination's errors and warnings in the console. */
+    name: string;
+    /**
+     * The events it subscribes to, so `routes()` can list them without setting it up, e.g. on the server. Without it,
+     * it counts as receiving every event.
+     */
+    events?: readonly (keyof Accepts & string)[];
+    /**
+     * Runs once in the browser when analytics is created, before consent is answered: subscribe to events here, but
+     * load the provider's script once the first event arrives. Events wait for an async setup. When it throws or
+     * rejects, the error is logged and the destination receives nothing.
+     */
+    setup: (context: DestinationSetupContext<Accepts, Context>) => void | Promise<void>;
+};
+/** One event, several (e.g. one per item), or `null` to send nothing. */
+type MappingResult<Accepts extends object> = DestinationEvent<Accepts> | readonly DestinationEvent<Accepts>[] | null;
+/** Per event of `Events`, what a destination receives. Events without an entry aren't sent. */
+type AnalyticsMapping<Events extends EventMap, Accepts extends object, Context extends object = Record<never, never>> = {
+    [N in AnalyticsEventName<Events>]?: (payload: Events[N], event: {
+        id: string;
+        name: N;
+        context: AnalyticsContext<Context>;
+    }) => MappingResult<Accepts>;
+};
+/**
+ * Categories that must all be granted before a destination receives events; until consent is answered, they're queued
+ * for it. `"none"` delivers every event straight away, even before consent is answered, for providers that gate on
+ * consent themselves, e.g. GTM with Consent Mode.
+ */
+type ConsentRequirement = readonly [ConsentCategory, ...ConsentCategory[]] | "none";
+/** What `createAnalytics()` takes: a destination of the project's events with the consent it requires, from `withConsent()`. */
+type ConsentedDestination<Events extends EventMap, Context extends object = Record<never, never>> = AnalyticsDestination<Events, Context> & {
+    requires: ConsentRequirement;
+};
+/**
+ * Maps the project's events onto a destination: per event of `createAnalytics<Events>()`, what the destination
+ * receives, typed by what it accepts. Events without an entry aren't sent to it. Returns a destination that accepts the
+ * project's events, for `withConsent()`. Inside `withConsent()`, it takes the events from there. See `docs/analytics.md`.
+ *
+ * @example
+ * ```ts
+ * map(metaDestination(), {
+ *   newsletterSignedUp: ({ source }) => ({ name: "Lead", payload: { content_name: source } }),
+ * });
+ * ```
+ */
+declare const map: <Accepts extends object, Events extends EventMap, Context extends object = Record<never, never>>(destination: AnalyticsDestination<Accepts>, mapping: AnalyticsMapping<NoInfer<Events>, Accepts, NoInfer<Context>>) => AnalyticsDestination<Events, Context>;
+/**
+ * A mapping with an entry for every event of the catalog, e.g. to send the events without one of their own in a
+ * generic format. Spread it first, so the entries after it override it.
+ *
+ * @example
+ * ```ts
+ * map(gtmDestination(), { ...mapEvery(events, toGa4CustomEvent), ...ga4Mapping<Events>({ item: toGa4Item }) });
+ * ```
+ */
+declare const mapEvery: <Catalog extends Record<string, EventDefinition>, Result extends {
+    name: string;
+    payload: unknown;
+} | readonly {
+    name: string;
+    payload: unknown;
+}[] | null, Context extends object = Record<never, never>>(events: Catalog, toEvent: (event: AnalyticsEnvelope<EventsOf<Catalog>, Context>) => Result) => { [N in keyof Catalog & string]: (payload: EventsOf<Catalog>[N], event: {
+    id: string;
+    name: N;
+    context: AnalyticsContext<Context>;
+}) => Result; };
+/**
+ * Gives a destination of the project's events, usually from `map()`, the consent it requires, for `createAnalytics()`.
+ * Required, so consent is never left out by accident. Inside `createAnalytics()`, it takes the events from there.
+ *
+ * @example
+ * ```ts
+ * createAnalytics<Events>({
+ *   events,
+ *   consent,
+ *   destinations: [
+ *     withConsent(map(gtmDestination(), ga4Mapping<Events>({ item: toGa4Item })), "none"),
+ *     withConsent(
+ *       map(metaDestination(), {
+ *         newsletterSignedUp: ({ source }) => ({ name: "Lead", payload: { content_name: source } }),
+ *       }),
+ *       ["marketing"],
+ *     ),
+ *   ],
+ * });
+ * ```
+ */
+declare const withConsent: <Events extends EventMap, Context extends object = Record<never, never>>(destination: AnalyticsDestination<Events, Context>, requires: ConsentRequirement) => ConsentedDestination<Events, Context>;
+
+export { type AnalyticsDestination as A, type ConsentedDestination as C, type DestinationEvent as D, type MappingResult as M, type AnalyticsMapping as a, type ConsentRequirement as b, type DestinationEventContext as c, type DestinationSetupContext as d, mapEvery as e, map as m, withConsent as w };

package/dist/index-Zef1nnTP.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generic consent categories. Strictly necessary storage is always allowed, so it has no category.
+ *
+ * | Category      | Google Consent Mode v2                                | Shopify Customer Privacy      | Meta Pixel       |
+ * | ------------- | ----------------------------------------------------- | ----------------------------- | ---------------- |
+ * | `preferences` | `functionality_storage`, `personalization_storage`    | `preferences`                 | —                |
+ * | `analytics`   | `analytics_storage`                                   | `analytics`                   | —                |
+ * | `marketing`   | `ad_storage`, `ad_user_data`, `ad_personalization`    | `marketing`, read with `sale_of_data` | `grant`/`revoke` |
+ */
+declare const CONSENT_CATEGORIES: readonly ["preferences", "analytics", "marketing"];
+type ConsentCategory = (typeof CONSENT_CATEGORIES)[number];
+type Consent = Record<ConsentCategory, boolean>;
+/** `null` until the visitor has answered. */
+type ConsentState = Consent | null;
+/**
+ * Where consent comes from, usually a consent platform: `cookiebotConsent()`, `oneTrustConsent()`, or your own.
+ * Pass it to `createAnalytics()` from `@buildinams/core/analytics`.
+ */
+type ConsentSource = {
+    /** The platform, e.g. `"cookiebot"`. Consent isn't applied to a `ConsentTarget` with the same name. */
+    name?: string;
+    /** `null` until the visitor has answered, and on the server. */
+    get: () => Consent | null;
+    /** Calls `listener` with answered consent when it may have changed; repeats are fine. Returns an unsubscribe function. */
+    subscribe: (listener: (consent: Consent) => void) => () => void;
+};
+/**
+ * Is told the visitor's consent, e.g. Google Consent Mode or Shopify's Customer Privacy API. Pass it to
+ * `createAnalytics({ consentTargets })`, which applies every answer, except to a target named like the source.
+ */
+type ConsentTarget = {
+    name: string;
+    apply: (consent: Consent) => void | Promise<void>;
+};
+
+export { type ConsentCategory as C, type ConsentSource as a, type ConsentTarget as b, type ConsentState as c, type Consent as d, CONSENT_CATEGORIES as e };