@zeroad.network/token 0.13.6 → 0.13.8

package/README.md

@@ -1,75 +1,82 @@
 # Introduction
 
-This NPM module is meant to be used by sites participating in [Zero Ad Network](https://zeroad.network) program, that are running in either Node.js, Bun or Deno runtimes.
+This NPM module is designed for sites running Node.js, Bun, or Deno that participate in the [Zero Ad Network](https://zeroad.network) program.
 
-The `@zeroad.network/token` module acts as an HTTP‑header‑based "access / entitlement token" library. It is a lightweight, TypeScript ready, fully open source, well tested and has no production dependencies.
+The `@zeroad.network/token` module is a lightweight, TypeScript-ready, open-source, and fully tested HTTP-header-based "access/entitlement token" library with no production dependencies.
 
-Up-to-date and in depth guides, how-to's and platform implementation details can be found at [the official Zero Ad Network documentation portal](https://docs.zeroad.network).
+For detailed guides and implementation instructions, see the [official Zero Ad Network documentation](https://docs.zeroad.network).
 
-## Runtime compatibility
+## Runtime Compatibility
 
-| Runtime | Compatibility | ESM | CJS |
-| :------ | :------------ | :-: | :-: |
-| Node.js | 16+           | ✅  | ✅  |
-| Bun     | 1.1.0+        | ✅  | ✅  |
-| Deno    | 2.0.0+        | ✅  | ✅  |
+| Runtime | Version | ESM | CJS |
+| :------ | :------ | :-: | :-: |
+| Node.js | 16+     | ✅  | ✅  |
+| Bun     | 1.1.0+  | ✅  | ✅  |
+| Deno    | 2.0.0+  | ✅  | ✅  |
 
 ## Purpose
 
-It helps partnered site developer to:
+The module helps developers to:
+
+- Generate a valid "Welcome Header" when `clientId` and `features` are provided.
+- Inject a valid site's HTTP Response Header (**Welcome Header**) into every endpoint. Example:
 
-- Inject a valid site's HTTP Response Header known as "Welcome Header" to every endpoint. An example:
   ```http
-  X-Better-Web-Welcome: "AZqnKU56eIC7vCD1PPlwHg^1^3"
+  X-Better-Web-Welcome: "Z2CclA8oXIT1e0QmqTWF8w^1^3"
   ```
-- Check for Zero Ad Network user's token presence that gets injected as a HTTP Request Header by their browser extension. An example of such Request Header:
+
+- Detect and parse Zero Ad Network user tokens sent via HTTP Request Header. Example:
+
   ```http
   X-Better-Web-Hello: "Aav2IXRoh0oKBw==.2yZfC2/pM9DWfgX+von4IgWLmN9t67HJHLiee/gx4+pFIHHurwkC3PCHT1Kaz0yUhx3crUaxST+XLlRtJYacAQ=="
   ```
-- If found, parse the token from the HTTP Request Header value and verify its integrity.
-- (Optionally) Generate a valid "Welcome Header" value when `siteId` UUID and site `features` array are provided.
 
-## Implementation details
+- Verify client token integrity locally.
 
-The module uses the `node:crypto` runtime module to ensure the user's Request Header payload is valid by verifying its signature for the payload using Zero Ad Network's public ED25519 cryptographic key which is supplied within the module. Then:
+## Implementation Details
 
-- User's token payload is decoded and token's protocol version, expiration timestamp and site's feature list are extracted.
-- A map of the site's features and their toggle states is generated.
-- An expired token will produce a feature list with all flags being set to `false`.
+- Uses `node:crypto` to verify token signatures with Zero Ad Network's public ED25519 key.
+- Decodes token payload to extract protocol version, expiration timestamp, and site features.
+- Generates a feature map; expired tokens produce all flags as `false`.
 
-Parsed token result example:
+Parsed token example:
 
 ```js
 {
-  ADS_OFF: boolean,
-  COOKIE_CONSENT_OFF: boolean,
-  MARKETING_DIALOG_OFF: boolean,
-  CONTENT_PAYWALL_OFF: boolean,
-  SUBSCRIPTION_ACCESS_ON: boolean,
+  HIDE_ADVERTISEMENTS: boolean,
+  HIDE_COOKIE_CONSENT_SCREEN: boolean,
+  HIDE_MARKETING_DIALOGS: boolean,
+  DISABLE_NON_FUNCTIONAL_TRACKING: boolean,
+  DISABLE_CONTENT_PAYWALL: boolean,
+  ENABLE_SUBSCRIPTION_ACCESS: boolean,
 };
 ```
 
-User's token payload verification is done locally within your app and no data leaves your server.
+- Verification occurs locally; no data leaves your server.
+- Parsing and verification adds roughly 0.06ms–0.6ms to endpoint execution time (tested on M1 MacBook Pro). Performance may vary.
+- Redis caching tests show local verification is faster than retrieving cached results.
 
-When a token is present, parsing and token integrity verification will roughly add between `0.06ms` to `0.6ms` to the total endpoint execution time (as per testing done on a M1 MacBook Pro). Your mileage will vary depending on your hardware, but the impact should stay minimal.
+## Benefits of Joining
 
-As per our exploratory test results in attempts to cache the token and its parsed results in Redis - it takes longer to retrieve the cached result than to verify token payload integrity.
+Partnering with Zero Ad Network allows your site to:
 
-## Why to join
+- Generate a new revenue stream by:
+  - Providing a clean, unobstructed user experience
+  - Removing paywalls and enabling free access to your base subscription plan
+  - Or both combined
+- Contribute to a truly joyful, user-friendly internet experience
 
-By partnering with Zero Ad Network your site establishes a new stream of revenue enabling you to provide a tangible and meaningful value while simultaneously providing a pure, clean and unobstructed site UI that everyone loves.
+## Onboarding Your Site
 
-With every new site joining us, it becomes easier to reshape the internet closer to its original intention - a joyful and wonderful experience for everyone.
+1. [Sign up](https://zeroad.network/login) with Zero Ad Network.
+2. [Register your site](https://zeroad.network/publisher/sites/add) to receive your unique `X-Better-Web-Welcome` header.
 
-## Onboard your site
+Your site must include this header on all publicly accessible HTML or RESTful endpoints so that Zero Ad Network users’ browser extensions can recognize participation.
 
-To register your site, [sign up](https://zeroad.network/login) with Zero Ad Network and [register your site](https://zeroad.network/publisher/sites/add). On the second step of the Site registration process you'll be provided with your unique `X-Better-Web-Welcome` header value.
+## Module Installation
 
-If you decide for your site to participate in the Zero Ad Network program, then it must respond with this header at all times on every publicly accessible endpoint containing HTML or RESTful response. When Zero Ad Network users visit your site, this allows their browser extension to know your site is participating in the program.
-
-## Module installation
-
-Great news for TypeScript enjoyers, the module is written purely in TypeScript, hence all types and interfaces are readily available. The module works well in EcmaScript (`import {} from ""`) and CommonJS `const {} = require("")` environments. If unsure - prefer ESM when possible.
+- Written entirely in TypeScript with full types and interfaces.
+- Supports both ESM (`import`) and CommonJS (`require`). ESM is recommended when possible.
 
 To install the module use your favourite package manager:
 
@@ -92,15 +99,15 @@ deno add npm:@zeroad.network/token
 
 ## Examples
 
-To find more example implementations for `Express.js` (JavaScript), `Hono` and `Fastify` (both TypeScript), please go to [examples section on our Github repository](https://github.com/laurynas-karvelis/zeroad-token-ts/tree/main/examples/).
+For more example implementations using `Express.js` (JavaScript), `Hono`, and `Fastify` (TypeScript), visit the [examples section on our GitHub repository](https://github.com/laurynas-karvelis/zeroad-token-typescript/tree/main/examples/).
 
-Take this JavaScript example as a quick reference. The example will show how to:
+The following JavaScript example provides a quick reference, demonstrating how to:
 
-- Inject the "Welcome Header" into each response;
-- Parse user's token from their request header;
-- Use the `tokenContext` value later in your controllers and templates.
+- Inject the "Welcome Header" into responses
+- Parse the user's token from the request header
+- Use the `tokenContext` in controllers and templates
 
-An Express.js v.5 example of a minimal app:
+Minimal Express.js v5 app example:
 
 ```js
 import express from "express";
@@ -108,42 +115,47 @@ import { Site } from "@zeroad.network/token";
 
 const app = express();
 
-// Initialize your Zero Ad Network module once at startup.
-// "Welcome Header" value is acquired during Site's registration process at Zero Ad Network platform (see https://zeroad.network).
-const ZERO_AD_NETWORK_WELCOME_HEADER_VALUE = "AZqnKU56eIC7vCD1PPlwHg^1^3";
-const site = Site(ZERO_AD_NETWORK_WELCOME_HEADER_VALUE);
+// Initialize the Zero Ad Network module at app startup.
+// Your site's `clientId` value is obtained during site registration on the Zero Ad Network platform (https://zeroad.network).
+const ZERO_AD_NETWORK_CLIENT_ID = "Z2CclA8oXIT1e0QmqTWF8w";
+const site = Site({
+  clientId: ZERO_AD_NETWORK_CLIENT_ID,
+  features: [FEATURES.CLEAN_WEB, FEATURES.ONE_PASS],
+});
 
 app
-  // Your middleware
+  // Apply middleware for all routes
   .use((req, res, next) => {
-    // Inject "X-Better-Web-Welcome" header
+    // Inject the "X-Better-Web-Welcome" header into the response
     res.set(site.SERVER_HEADER_NAME, site.SERVER_HEADER_VALUE);
 
-    // Parse the request token from incoming client token header value.
-    // And attach parsed info to request object for downstream usage.
-    req.tokenContext = site.parseToken(req.get[site.CLIENT_HEADER_NAME]);
+    // Parse the incoming user token from the request header
+    // Attach the parsed token data to the request object for downstream use
+    req.tokenContext = site.parseClientToken(req.get(site.CLIENT_HEADER_NAME));
 
     next();
   })
   .get("/", (req, res) => {
-    // If you would print it's contents:
+    // Access parsed token data for this request
     console.log(req.tokenContext);
 
-    // This will produce:
+    // Example structure of tokenContext:
     req.tokenContext = {
-      // If set to true: Render no advertisements anywhere on the page
-      ADS_OFF: boolean,
-      // If set to true: Render no Cookie Consent screens (headers, footers or dialogs) on the page with complete OPT-OUT for non-functional trackers
-      COOKIE_CONSENT_OFF: boolean,
-      // If set to true: Render no marketing dialogs or popups such as newsletter, promotion etc. on the page
-      MARKETING_DIALOG_OFF: boolean,
-      // If set to true: Provide automatic access to otherwise paywalled content such as articles, news etc.
-      CONTENT_PAYWALL_OFF: boolean,
-      // If set to true: Provide automatic access to site features provided behind a SaaS at least the basic subscription plan
-      SUBSCRIPTION_ACCESS_ON: boolean,
+      // If `true`: Hide advertisements on the page
+      HIDE_ADVERTISEMENTS: boolean,
+      // If `true`: Disable all Cookie Consent screens (headers, footers, or dialogs)
+      HIDE_COOKIE_CONSENT_SCREEN: boolean,
+      // If `true`: Disable all marketing dialogs or popups (newsletters, promotions, etc.)
+      HIDE_MARKETING_DIALOGS: boolean,
+      // If `true`: Fully opt out the user of non-functional trackers
+      DISABLE_NON_FUNCTIONAL_TRACKING: boolean,
+      // If `true`: Provide Free access to content behind a paywall (news, articles, etc.)
+      DISABLE_CONTENT_PAYWALL: boolean,
+      // If `true`: Provide Free access to your base subscription plan (if subscription model is present)
+      ENABLE_SUBSCRIPTION_ACCESS: boolean,
     };
 
-    // In your template adjust your content depending on tokenContext values
+    // Adjust content in your templates based on tokenContext values
     res.render("index.ejs", { tokenContext });
   });
 

package/dist/browser-BiNZ2c6t.d.cts

@@ -0,0 +1,47 @@
+/**
+ * Official Zero Ad Network public key.
+ * Used to verify that `X-Better-Web-Hello` header values are authentic
+ * and have not been tampered with.
+ */
+declare const ZEROAD_NETWORK_PUBLIC_KEY: string;
+/**
+ * IMPORTANT: Requirements listed for each feature class MUST be fulfilled fully.
+ * Failure to comply will result in the site getting banned from Zero Ad Network platform.
+ */
+declare enum FEATURES {
+    /**
+     * Feature requirements:
+     *  - Disable all advertisements on the page;
+     *  - Disable all Cookie Consent screens (headers, footers, or dialogs);
+     *  - Fully opt out the user of non-functional trackers;
+     *  - Disable all marketing dialogs or popups (newsletters, promotions, etc.).
+     */
+    CLEAN_WEB = 1,
+    /**
+     * Feature requirements:
+     *  - Provide Free access to content behind a paywall (news, articles, etc.);
+     *  - Provide Free access to your base subscription plan (if subscription model is present).
+     */
+    ONE_PASS = 2
+}
+declare enum SERVER_HEADERS {
+    WELCOME = "X-Better-Web-Welcome"
+}
+declare enum CLIENT_HEADERS {
+    HELLO = "X-Better-Web-Hello"
+}
+declare enum PROTOCOL_VERSION {
+    V_1 = 1
+}
+declare const CURRENT_PROTOCOL_VERSION = PROTOCOL_VERSION.V_1;
+
+declare function encodeServerHeader(clientId: string, features: FEATURES[]): string;
+type WelcomeHeader = {
+    clientId: string;
+    version: PROTOCOL_VERSION;
+    features: (keyof typeof FEATURES)[];
+};
+declare function decodeServerHeader(headerValue: string | null | undefined): WelcomeHeader | undefined;
+
+export { CLIENT_HEADERS as C, FEATURES as F, PROTOCOL_VERSION as P, SERVER_HEADERS as S, ZEROAD_NETWORK_PUBLIC_KEY as Z, CURRENT_PROTOCOL_VERSION as a, decodeServerHeader as d, encodeServerHeader as e };
+export type { WelcomeHeader as W };

package/dist/browser-BiNZ2c6t.d.mts

@@ -0,0 +1,47 @@
+/**
+ * Official Zero Ad Network public key.
+ * Used to verify that `X-Better-Web-Hello` header values are authentic
+ * and have not been tampered with.
+ */
+declare const ZEROAD_NETWORK_PUBLIC_KEY: string;
+/**
+ * IMPORTANT: Requirements listed for each feature class MUST be fulfilled fully.
+ * Failure to comply will result in the site getting banned from Zero Ad Network platform.
+ */
+declare enum FEATURES {
+    /**
+     * Feature requirements:
+     *  - Disable all advertisements on the page;
+     *  - Disable all Cookie Consent screens (headers, footers, or dialogs);
+     *  - Fully opt out the user of non-functional trackers;
+     *  - Disable all marketing dialogs or popups (newsletters, promotions, etc.).
+     */
+    CLEAN_WEB = 1,
+    /**
+     * Feature requirements:
+     *  - Provide Free access to content behind a paywall (news, articles, etc.);
+     *  - Provide Free access to your base subscription plan (if subscription model is present).
+     */
+    ONE_PASS = 2
+}
+declare enum SERVER_HEADERS {
+    WELCOME = "X-Better-Web-Welcome"
+}
+declare enum CLIENT_HEADERS {
+    HELLO = "X-Better-Web-Hello"
+}
+declare enum PROTOCOL_VERSION {
+    V_1 = 1
+}
+declare const CURRENT_PROTOCOL_VERSION = PROTOCOL_VERSION.V_1;
+
+declare function encodeServerHeader(clientId: string, features: FEATURES[]): string;
+type WelcomeHeader = {
+    clientId: string;
+    version: PROTOCOL_VERSION;
+    features: (keyof typeof FEATURES)[];
+};
+declare function decodeServerHeader(headerValue: string | null | undefined): WelcomeHeader | undefined;
+
+export { CLIENT_HEADERS as C, FEATURES as F, PROTOCOL_VERSION as P, SERVER_HEADERS as S, ZEROAD_NETWORK_PUBLIC_KEY as Z, CURRENT_PROTOCOL_VERSION as a, decodeServerHeader as d, encodeServerHeader as e };
+export type { WelcomeHeader as W };

package/dist/browser-CMCq-bkd.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+let currentLevel = "error";
+function setLogLevel(level) {
+  if (levels[level] !== void 0) {
+    currentLevel = level;
+  }
+}
+function log(level, ...args) {
+  if (levels[level] <= levels[currentLevel]) {
+    console.log(`[${level.toUpperCase()}]`, ...args);
+  }
+}
+
+const ZEROAD_NETWORK_PUBLIC_KEY = "MCowBQYDK2VwAyEAignXRaTQtxEDl4ThULucKNQKEEO2Lo5bEO8qKwjSDVs=";
+var FEATURES = /* @__PURE__ */ ((FEATURES2) => {
+  FEATURES2[FEATURES2["CLEAN_WEB"] = 1] = "CLEAN_WEB";
+  FEATURES2[FEATURES2["ONE_PASS"] = 2] = "ONE_PASS";
+  return FEATURES2;
+})(FEATURES || {});
+var SERVER_HEADERS = /* @__PURE__ */ ((SERVER_HEADERS2) => {
+  SERVER_HEADERS2["WELCOME"] = "X-Better-Web-Welcome";
+  return SERVER_HEADERS2;
+})(SERVER_HEADERS || {});
+var CLIENT_HEADERS = /* @__PURE__ */ ((CLIENT_HEADERS2) => {
+  CLIENT_HEADERS2["HELLO"] = "X-Better-Web-Hello";
+  return CLIENT_HEADERS2;
+})(CLIENT_HEADERS || {});
+var PROTOCOL_VERSION = /* @__PURE__ */ ((PROTOCOL_VERSION2) => {
+  PROTOCOL_VERSION2[PROTOCOL_VERSION2["V_1"] = 1] = "V_1";
+  return PROTOCOL_VERSION2;
+})(PROTOCOL_VERSION || {});
+const CURRENT_PROTOCOL_VERSION = 1 /* V_1 */;
+
+let SITE_FEATURES_NATIVE$1;
+const getSiteFeaturesNative = () => {
+  if (SITE_FEATURES_NATIVE$1?.length) return SITE_FEATURES_NATIVE$1;
+  return SITE_FEATURES_NATIVE$1 = Object.entries(FEATURES).filter(([key]) => isNaN(Number(key)));
+};
+const toBase64 = (data) => {
+  if (typeof data.toBase64 === "function") return data.toBase64();
+  if (typeof Buffer !== "undefined") return Buffer.from(data).toString("base64");
+  if (typeof btoa === "function") {
+    let binary = "";
+    for (let i = 0; i < data.length; i++) {
+      binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary);
+  }
+  throw new Error("Base64 encoding not supported in this environment");
+};
+const fromBase64 = (input) => {
+  if (typeof Uint8Array.fromBase64 === "function") return Uint8Array.fromBase64(input);
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(input, "base64"));
+  if (typeof atob === "function") {
+    const binary = atob(input);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  throw new Error("Base64 decoding not supported in this environment");
+};
+const assert = (value, message) => {
+  if (!value) throw new Error(message);
+};
+const hasFlag = (flag, flags) => Boolean(flag & flags);
+const setFlags = (features = []) => features.reduce((acc, feature) => acc | feature, 0);
+
+const SEPARATOR = "^";
+const SITE_FEATURES_NATIVE = getSiteFeaturesNative();
+const validFeatureValues = Object.values(FEATURES).filter((key) => !isNaN(Number(key)));
+const validFeatureKeys = Object.values(FEATURES).filter((key) => isNaN(Number(key)));
+function encodeServerHeader(clientId, features) {
+  if (!clientId?.length) {
+    throw new Error("The provided `clientId` value cannot be an empty string");
+  }
+  if (!features?.length) {
+    throw new Error("At least one Site feature must be provided");
+  }
+  if (features.filter((feature) => validFeatureValues.includes(feature)).length !== features.length) {
+    throw new Error(`Only valid Site features are allowed: ${validFeatureKeys.join(" | ")}`);
+  }
+  return [clientId, CURRENT_PROTOCOL_VERSION, setFlags(features)].join(SEPARATOR);
+}
+function decodeServerHeader(headerValue) {
+  if (!headerValue?.length) return;
+  try {
+    const parts = headerValue.split(SEPARATOR);
+    assert(parts.length === 3, "Invalid header value format");
+    const [clientId, protocolVersion, flags] = parts;
+    assert(
+      Object.values(PROTOCOL_VERSION).includes(Number(protocolVersion)),
+      "Invalid or unsupported protocol version"
+    );
+    assert(Number(flags).toFixed(0).toString() === flags, "Invalid flags number");
+    let features = [];
+    for (const [feature, shift] of SITE_FEATURES_NATIVE) {
+      if (hasFlag(Number(flags), shift)) features.push(feature);
+    }
+    return {
+      version: Number(protocolVersion),
+      clientId,
+      features
+    };
+  } catch (err) {
+    log("warn", "Could not decode server header value", { reason: err?.message });
+  }
+}
+
+exports.CLIENT_HEADERS = CLIENT_HEADERS;
+exports.CURRENT_PROTOCOL_VERSION = CURRENT_PROTOCOL_VERSION;
+exports.FEATURES = FEATURES;
+exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
+exports.SERVER_HEADERS = SERVER_HEADERS;
+exports.ZEROAD_NETWORK_PUBLIC_KEY = ZEROAD_NETWORK_PUBLIC_KEY;
+exports.decodeServerHeader = decodeServerHeader;
+exports.encodeServerHeader = encodeServerHeader;
+exports.fromBase64 = fromBase64;
+exports.getSiteFeaturesNative = getSiteFeaturesNative;
+exports.hasFlag = hasFlag;
+exports.log = log;
+exports.setFlags = setFlags;
+exports.setLogLevel = setLogLevel;
+exports.toBase64 = toBase64;

package/dist/browser-Citg0bh9.mjs

@@ -0,0 +1,116 @@
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+let currentLevel = "error";
+function setLogLevel(level) {
+  if (levels[level] !== void 0) {
+    currentLevel = level;
+  }
+}
+function log(level, ...args) {
+  if (levels[level] <= levels[currentLevel]) {
+    console.log(`[${level.toUpperCase()}]`, ...args);
+  }
+}
+
+const ZEROAD_NETWORK_PUBLIC_KEY = "MCowBQYDK2VwAyEAignXRaTQtxEDl4ThULucKNQKEEO2Lo5bEO8qKwjSDVs=";
+var FEATURES = /* @__PURE__ */ ((FEATURES2) => {
+  FEATURES2[FEATURES2["CLEAN_WEB"] = 1] = "CLEAN_WEB";
+  FEATURES2[FEATURES2["ONE_PASS"] = 2] = "ONE_PASS";
+  return FEATURES2;
+})(FEATURES || {});
+var SERVER_HEADERS = /* @__PURE__ */ ((SERVER_HEADERS2) => {
+  SERVER_HEADERS2["WELCOME"] = "X-Better-Web-Welcome";
+  return SERVER_HEADERS2;
+})(SERVER_HEADERS || {});
+var CLIENT_HEADERS = /* @__PURE__ */ ((CLIENT_HEADERS2) => {
+  CLIENT_HEADERS2["HELLO"] = "X-Better-Web-Hello";
+  return CLIENT_HEADERS2;
+})(CLIENT_HEADERS || {});
+var PROTOCOL_VERSION = /* @__PURE__ */ ((PROTOCOL_VERSION2) => {
+  PROTOCOL_VERSION2[PROTOCOL_VERSION2["V_1"] = 1] = "V_1";
+  return PROTOCOL_VERSION2;
+})(PROTOCOL_VERSION || {});
+const CURRENT_PROTOCOL_VERSION = 1 /* V_1 */;
+
+let SITE_FEATURES_NATIVE$1;
+const getSiteFeaturesNative = () => {
+  if (SITE_FEATURES_NATIVE$1?.length) return SITE_FEATURES_NATIVE$1;
+  return SITE_FEATURES_NATIVE$1 = Object.entries(FEATURES).filter(([key]) => isNaN(Number(key)));
+};
+const toBase64 = (data) => {
+  if (typeof data.toBase64 === "function") return data.toBase64();
+  if (typeof Buffer !== "undefined") return Buffer.from(data).toString("base64");
+  if (typeof btoa === "function") {
+    let binary = "";
+    for (let i = 0; i < data.length; i++) {
+      binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary);
+  }
+  throw new Error("Base64 encoding not supported in this environment");
+};
+const fromBase64 = (input) => {
+  if (typeof Uint8Array.fromBase64 === "function") return Uint8Array.fromBase64(input);
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(input, "base64"));
+  if (typeof atob === "function") {
+    const binary = atob(input);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  throw new Error("Base64 decoding not supported in this environment");
+};
+const assert = (value, message) => {
+  if (!value) throw new Error(message);
+};
+const hasFlag = (flag, flags) => Boolean(flag & flags);
+const setFlags = (features = []) => features.reduce((acc, feature) => acc | feature, 0);
+
+const SEPARATOR = "^";
+const SITE_FEATURES_NATIVE = getSiteFeaturesNative();
+const validFeatureValues = Object.values(FEATURES).filter((key) => !isNaN(Number(key)));
+const validFeatureKeys = Object.values(FEATURES).filter((key) => isNaN(Number(key)));
+function encodeServerHeader(clientId, features) {
+  if (!clientId?.length) {
+    throw new Error("The provided `clientId` value cannot be an empty string");
+  }
+  if (!features?.length) {
+    throw new Error("At least one Site feature must be provided");
+  }
+  if (features.filter((feature) => validFeatureValues.includes(feature)).length !== features.length) {
+    throw new Error(`Only valid Site features are allowed: ${validFeatureKeys.join(" | ")}`);
+  }
+  return [clientId, CURRENT_PROTOCOL_VERSION, setFlags(features)].join(SEPARATOR);
+}
+function decodeServerHeader(headerValue) {
+  if (!headerValue?.length) return;
+  try {
+    const parts = headerValue.split(SEPARATOR);
+    assert(parts.length === 3, "Invalid header value format");
+    const [clientId, protocolVersion, flags] = parts;
+    assert(
+      Object.values(PROTOCOL_VERSION).includes(Number(protocolVersion)),
+      "Invalid or unsupported protocol version"
+    );
+    assert(Number(flags).toFixed(0).toString() === flags, "Invalid flags number");
+    let features = [];
+    for (const [feature, shift] of SITE_FEATURES_NATIVE) {
+      if (hasFlag(Number(flags), shift)) features.push(feature);
+    }
+    return {
+      version: Number(protocolVersion),
+      clientId,
+      features
+    };
+  } catch (err) {
+    log("warn", "Could not decode server header value", { reason: err?.message });
+  }
+}
+
+export { CLIENT_HEADERS as C, FEATURES as F, PROTOCOL_VERSION as P, SERVER_HEADERS as S, ZEROAD_NETWORK_PUBLIC_KEY as Z, setLogLevel as a, CURRENT_PROTOCOL_VERSION as b, decodeServerHeader as d, encodeServerHeader as e, fromBase64 as f, getSiteFeaturesNative as g, hasFlag as h, log as l, setFlags as s, toBase64 as t };

package/dist/browser.d.mts

@@ -1,54 +1 @@
-/**
- * This is an official ZeroAd Network public key.
- * Used to verify `X-Better-Web-User` header values are not tampered with.
- */
-declare const ZEROAD_NETWORK_PUBLIC_KEY: string;
-declare enum FEATURES {
-    /** Render no advertisements anywhere on the page */
-    ADS_OFF = 1,
-    /** Render no Cookie Consent screens (headers, footers or dialogs) on the page with complete OPT-OUT for non-functional trackers */
-    COOKIE_CONSENT_OFF = 2,
-    /** Render no marketing dialogs or popups such as newsletter, promotion etc. on the page */
-    MARKETING_DIALOG_OFF = 4,
-    /** Provide automatic access to otherwise paywalled content such as articles, news etc. */
-    CONTENT_PAYWALL_OFF = 8,
-    /** Provide automatic access to site features provided behind a SaaS at least the basic subscription plan */
-    SUBSCRIPTION_ACCESS_ON = 16
-}
-type UUID = string;
-declare enum SERVER_HEADERS {
-    WELCOME = "X-Better-Web-Welcome"
-}
-declare enum CLIENT_HEADERS {
-    HELLO = "X-Better-Web-Hello"
-}
-declare enum PROTOCOL_VERSION {
-    V_1 = 1
-}
-declare const CURRENT_PROTOCOL_VERSION = PROTOCOL_VERSION.V_1;
-type ServerHeaderExtendedOptions = {
-    siteId: UUID;
-    features: FEATURES[];
-};
-type ServerHeaderOptions = NonNullable<string | ServerHeaderExtendedOptions>;
-type WelcomeHeader = {
-    version: PROTOCOL_VERSION;
-    features: (keyof typeof FEATURES)[];
-    siteId: UUID;
-};
-type ClientParsedHeader = {
-    version: PROTOCOL_VERSION;
-    expiresAt: Date;
-    flags: number;
-};
-
-declare class ServerHeader {
-    NAME: SERVER_HEADERS;
-    VALUE: string;
-    constructor(options: ServerHeaderOptions);
-    encode(siteId: UUID, features: FEATURES[]): string;
-    static decode(headerValue: string | undefined): WelcomeHeader | undefined;
-}
-
-export { CLIENT_HEADERS, CURRENT_PROTOCOL_VERSION, FEATURES, PROTOCOL_VERSION, SERVER_HEADERS, ServerHeader, ZEROAD_NETWORK_PUBLIC_KEY };
-export type { ClientParsedHeader, ServerHeaderExtendedOptions, ServerHeaderOptions, UUID, WelcomeHeader };
+export { C as CLIENT_HEADERS, a as CURRENT_PROTOCOL_VERSION, F as FEATURES, P as PROTOCOL_VERSION, S as SERVER_HEADERS, Z as ZEROAD_NETWORK_PUBLIC_KEY, d as decodeServerHeader } from './browser-BiNZ2c6t.mjs';

package/dist/browser.mjs

@@ -1 +1 @@
-export { C as CLIENT_HEADERS, c as CURRENT_PROTOCOL_VERSION, F as FEATURES, P as PROTOCOL_VERSION, b as SERVER_HEADERS, S as ServerHeader, Z as ZEROAD_NETWORK_PUBLIC_KEY } from './browser-DDeUUPbU.mjs';
+export { C as CLIENT_HEADERS, b as CURRENT_PROTOCOL_VERSION, F as FEATURES, P as PROTOCOL_VERSION, S as SERVER_HEADERS, Z as ZEROAD_NETWORK_PUBLIC_KEY, d as decodeServerHeader } from './browser-Citg0bh9.mjs';