@preprio/toolkit 0.1.0-beta.1

package/dist/sveltekit/index.js

@@ -0,0 +1,334 @@
+// src/version.ts
+var VERSION = "0.1.0-beta.1";
+
+// src/core/constants.ts
+var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";
+var COOKIE_SEGMENT = "Prepr-Segments";
+var COOKIE_VARIANT = "Prepr-ABtesting";
+var COOKIE_UID = "__prepr_uid";
+var COOKIE_HUBSPOT = "hubspotutk";
+var PARAM_SEGMENT = "prepr_preview_segment";
+var PARAM_VARIANT = "prepr_preview_ab";
+var PARAM_HIDE_BAR = "prepr_hide_bar";
+var ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
+
+// src/core/middleware.ts
+var UTM_PARAMS = [
+  "utm_source",
+  "utm_medium",
+  "utm_term",
+  "utm_content",
+  "utm_campaign"
+];
+function parseCookies(request) {
+  const cookies = /* @__PURE__ */ new Map();
+  const header = request.headers.get("cookie");
+  if (!header) return cookies;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const name = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (!name) continue;
+    cookies.set(name, decodeURIComponent(value));
+  }
+  return cookies;
+}
+function processPreprRequest(request, opts) {
+  const requestHeaders = new Headers(request.headers);
+  const responseCookies = [];
+  const requestCookies = parseCookies(request);
+  const searchParams = new URL(request.url).searchParams;
+  for (const key of UTM_PARAMS) {
+    const value = searchParams.get(key);
+    if (value !== null) {
+      requestHeaders.set(`Prepr-Context-${key}`, value);
+    }
+  }
+  const referer = request.headers.get("referer");
+  if (referer) {
+    requestHeaders.set("Prepr-Context-initial_referral", referer);
+  }
+  const userAgent = request.headers.get("user-agent");
+  if (userAgent) {
+    requestHeaders.set("Prepr-User-Agent", userAgent);
+  }
+  requestHeaders.set("Prepr-Package", `@preprio/toolkit@${opts?.version ?? VERSION}`);
+  const ip = request.headers.get("Cf-Connecting-Ip") ?? request.headers.get("x-real-ip");
+  if (ip) {
+    requestHeaders.set("Prepr-Visitor-IP", ip);
+  }
+  const hutkCookie = requestCookies.get(COOKIE_HUBSPOT);
+  if (hutkCookie) {
+    requestHeaders.set("Prepr-Hubspot-Id", hutkCookie);
+  }
+  let uid = requestCookies.get(COOKIE_UID);
+  if (!uid) {
+    uid = crypto.randomUUID();
+    responseCookies.push({
+      name: COOKIE_UID,
+      value: uid,
+      maxAge: ONE_YEAR_SECONDS,
+      path: "/"
+    });
+    requestHeaders.set("Prepr-Customer-Id-Created", "true");
+  }
+  requestHeaders.set("Prepr-Customer-Id", uid);
+  if (!opts?.preview) {
+    return { requestHeaders, responseCookies };
+  }
+  const hasPreviewParams = searchParams.has(PARAM_SEGMENT) || searchParams.has(PARAM_VARIANT);
+  if (!hasPreviewParams) {
+    const previewModeCookie = requestCookies.get(COOKIE_PREVIEW_MODE);
+    const previewModeEnabled = previewModeCookie !== "false";
+    if (!previewModeEnabled) {
+      return { requestHeaders, responseCookies };
+    }
+  }
+  requestHeaders.set("Prepr-Preview-Bar", "true");
+  const isLivePreview = searchParams.get(PARAM_HIDE_BAR) === "true";
+  if (!isLivePreview) {
+    const segmentCookie = requestCookies.get(COOKIE_SEGMENT);
+    if (segmentCookie) {
+      requestHeaders.set("Prepr-Segments", segmentCookie);
+    }
+    const abCookie = requestCookies.get(COOKIE_VARIANT);
+    if (abCookie) {
+      requestHeaders.set("Prepr-ABtesting", abCookie);
+    }
+  }
+  const previewAb = searchParams.get(PARAM_VARIANT);
+  if (previewAb !== null) {
+    requestHeaders.set("Prepr-ABtesting", previewAb);
+    if (!isLivePreview) {
+      responseCookies.push({
+        name: COOKIE_VARIANT,
+        value: previewAb,
+        maxAge: ONE_YEAR_SECONDS,
+        path: "/"
+      });
+    }
+  }
+  const previewSegment = searchParams.get(PARAM_SEGMENT);
+  if (previewSegment !== null) {
+    requestHeaders.set("Prepr-Segments", previewSegment);
+    if (!isLivePreview) {
+      responseCookies.push({
+        name: COOKIE_SEGMENT,
+        value: previewSegment,
+        maxAge: ONE_YEAR_SECONDS,
+        path: "/"
+      });
+    }
+  }
+  return { requestHeaders, responseCookies };
+}
+
+// src/sveltekit/hooks.ts
+var PREPR_LOCALS_KEY = "prepr";
+function preprHandle(options) {
+  return async ({ event, resolve }) => {
+    const { requestHeaders, responseCookies } = processPreprRequest(event.request, options);
+    requestHeaders.forEach((value, key) => {
+      event.request.headers.set(key, value);
+    });
+    if (event.locals) {
+      event.locals[PREPR_LOCALS_KEY] = requestHeaders;
+    }
+    const response = await resolve(event);
+    for (const cookie of responseCookies) {
+      const parts = [
+        `${cookie.name}=${encodeURIComponent(cookie.value)}`,
+        `Max-Age=${cookie.maxAge}`,
+        `Path=${cookie.path}`
+      ];
+      response.headers.append("Set-Cookie", parts.join("; "));
+    }
+    return response;
+  };
+}
+function getPreprHeadersFromLocals(locals) {
+  const headers = locals[PREPR_LOCALS_KEY];
+  return headers instanceof Headers ? headers : new Headers();
+}
+
+// src/core/server.ts
+var PreprError = class extends Error {
+  constructor(message, code, context, originalError) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.originalError = originalError;
+    this.name = "PreprError";
+  }
+};
+function getPreprUUIDFromHeaders(headers) {
+  return headers.get("prepr-customer-id");
+}
+function getActiveSegmentFromHeaders(headers) {
+  return headers.get("Prepr-Segments");
+}
+function getActiveVariantFromHeaders(headers) {
+  return headers.get("Prepr-ABtesting");
+}
+var PREPR_HEADER_KEYS = [
+  "prepr-customer-id",
+  "Prepr-Segments",
+  "Prepr-ABtesting",
+  "Prepr-Preview-Bar",
+  "Prepr-Context-utm_source",
+  "Prepr-Context-utm_medium",
+  "Prepr-Context-utm_term",
+  "Prepr-Context-utm_content",
+  "Prepr-Context-utm_campaign",
+  "Prepr-Context-initial_referral",
+  "Prepr-Visitor-IP",
+  "Prepr-Hubspot-Id",
+  "Prepr-Customer-Id-Created",
+  "Prepr-User-Agent"
+];
+function getPreprHeadersFromHeaders(headers) {
+  const preprHeaders = {};
+  const copy = (key) => {
+    const value = headers.get(key);
+    if (value !== null) {
+      preprHeaders[key] = value;
+    }
+  };
+  for (const key of PREPR_HEADER_KEYS) {
+    copy(key);
+  }
+  return preprHeaders;
+}
+function validatePreprToken(token) {
+  if (!token) {
+    throw new PreprError("Token is required", "MISSING_TOKEN", "validatePreprToken");
+  }
+  if (!token.startsWith("https://")) {
+    throw new PreprError(
+      "Token must be a valid HTTPS URL",
+      "INVALID_TOKEN",
+      "validatePreprToken"
+    );
+  }
+}
+function extractAccessToken(graphqlUrl) {
+  let url;
+  try {
+    url = new URL(graphqlUrl);
+  } catch (error) {
+    throw new PreprError(
+      "Token must be a valid URL",
+      "INVALID_TOKEN",
+      "extractAccessToken",
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+  if (url.hostname !== "graphql.prepr.io") {
+    throw new PreprError(
+      "Token must be a graphql.prepr.io URL",
+      "INVALID_TOKEN",
+      "extractAccessToken"
+    );
+  }
+  const pathParts = url.pathname.split("/");
+  const token = pathParts[pathParts.length - 1];
+  if (!token) {
+    throw new PreprError(
+      "Token URL is missing an access token segment",
+      "INVALID_TOKEN",
+      "extractAccessToken"
+    );
+  }
+  return token;
+}
+async function getPreprEnvironmentSegments(token) {
+  validatePreprToken(token);
+  try {
+    const response = await fetch(token, {
+      headers: {
+        "User-Agent": `Prepr-Preview-Bar/${VERSION}`,
+        "Content-Type": "application/json"
+      },
+      method: "POST",
+      body: JSON.stringify({
+        query: `{
+                _Segments {
+                    _id
+                    name
+                }
+            }`
+      })
+    });
+    if (!response.ok) {
+      throw new PreprError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        "HTTP_ERROR",
+        "getPreprEnvironmentSegments"
+      );
+    }
+    const json = await response.json();
+    if (!json || !json.data || !json.data._Segments) {
+      throw new PreprError(
+        "Invalid response format from Prepr API",
+        "INVALID_RESPONSE",
+        "getPreprEnvironmentSegments"
+      );
+    }
+    return json.data._Segments;
+  } catch (error) {
+    if (error instanceof PreprError) {
+      throw error;
+    }
+    throw new PreprError(
+      "Failed to fetch segments from Prepr API",
+      "FETCH_ERROR",
+      "getPreprEnvironmentSegments",
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+}
+async function getToolbarPropsFromHeaders(headers, token) {
+  let segments = [];
+  try {
+    segments = await getPreprEnvironmentSegments(token);
+  } catch {
+    segments = [];
+  }
+  return {
+    activeSegment: getActiveSegmentFromHeaders(headers),
+    activeVariant: getActiveVariantFromHeaders(headers),
+    segments,
+    data: segments
+  };
+}
+
+// src/sveltekit/server.ts
+function getPreprUUID(headers) {
+  return getPreprUUIDFromHeaders(headers);
+}
+function getActiveSegment(headers) {
+  return getActiveSegmentFromHeaders(headers);
+}
+function getActiveVariant(headers) {
+  return getActiveVariantFromHeaders(headers);
+}
+function getPreprHeaders(headers) {
+  return getPreprHeadersFromHeaders(headers);
+}
+async function getToolbarProps(headers, token) {
+  return getToolbarPropsFromHeaders(headers, token);
+}
+export {
+  PREPR_LOCALS_KEY,
+  PreprError,
+  extractAccessToken,
+  getActiveSegment,
+  getActiveVariant,
+  getPreprHeaders,
+  getPreprHeadersFromLocals,
+  getPreprUUID,
+  getToolbarProps,
+  preprHandle,
+  validatePreprToken
+};

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@preprio/toolkit",
+  "version": "0.1.0-beta.1",
+  "description": "Prepr personalization, A/B testing and preview toolkit for Next.js, Astro, SvelteKit and Express",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/preprio/prepr-toolkit.git",
+    "directory": "packages/toolkit"
+  },
+  "homepage": "https://github.com/preprio/prepr-toolkit#readme",
+  "bugs": "https://github.com/preprio/prepr-toolkit/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./nextjs": {
+      "types": "./dist/nextjs/index.d.ts",
+      "import": "./dist/nextjs/index.js",
+      "require": "./dist/nextjs/index.cjs"
+    },
+    "./nextjs/image-loader": {
+      "types": "./dist/nextjs/image-loader.d.ts",
+      "import": "./dist/nextjs/image-loader.js",
+      "require": "./dist/nextjs/image-loader.cjs"
+    },
+    "./astro": {
+      "types": "./dist/astro/index.d.ts",
+      "import": "./dist/astro/index.js",
+      "require": "./dist/astro/index.cjs"
+    },
+    "./astro/components/*": "./src/astro/*.astro",
+    "./sveltekit": {
+      "types": "./dist/sveltekit/index.d.ts",
+      "import": "./dist/sveltekit/index.js",
+      "require": "./dist/sveltekit/index.cjs"
+    },
+    "./sveltekit/components/*": "./src/sveltekit/*.svelte"
+  },
+  "files": [
+    "dist",
+    "src/astro/*.astro",
+    "src/sveltekit/*.svelte"
+  ],
+  "dependencies": {
+    "@vercel/stega": "^1.1.0",
+    "preact": "^10.29.7"
+  },
+  "peerDependencies": {
+    "next": ">=13",
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "browserslist": "^4.28.7",
+    "happy-dom": "^20.11.1",
+    "lightningcss": "^1.33.0",
+    "next": "^16.2.12",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "gen:css": "node scripts/compile-css.mjs",
+    "prebuild": "rm -rf dist && pnpm gen:css && node scripts/check-version.mjs",
+    "pretest": "pnpm gen:css",
+    "pretypecheck": "pnpm gen:css",
+    "build": "tsup",
+    "postbuild": "node scripts/check-exports.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/astro/PreprToolbar.astro

@@ -0,0 +1,53 @@
+---
+/**
+ * Server-renders nothing visible — mounts the framework-free Prepr toolbar
+ * custom element client-side via `createPreprToolbar` (core).
+ *
+ * Ships as SOURCE: this file is compiled by the *consumer's* Astro/Vite
+ * pipeline (not by this package's own `tsup` build), matching how Astro
+ * component libraries distribute `.astro` files. See package.json's
+ * `./astro/components/*` export map entry and `files` field.
+ *
+ * Astro is multi-page (MPA) by default, so the default navigation adapter
+ * (core's `window.location.assign`, used when no `navigation` override is
+ * passed to `createPreprToolbar`) is the correct choice here — a full page
+ * navigation re-runs Astro's server-rendered output (and this component's
+ * frontmatter) with the new query params, which is what drives segment /
+ * A/B query-param personalization. No client-router
+ * integration is wired up; consumers using Astro's View Transitions/client
+ * router can pass their own adapter if they fork this component.
+ *
+ * Server → client props transfer: the props are emitted into a
+ * `<script type="application/json">` tag and read back by a SEPARATE,
+ * NON-inline `<script>` that Astro/Vite bundles. We deliberately do NOT use
+ * `define:vars`, which would force the mount script to be `is:inline` —
+ * Astro/Vite do not process bare `import` specifiers in inline scripts, so
+ * `import { createPreprToolbar } from '@preprio/toolkit'` would fail to
+ * resolve in the browser. A processed (bundled) module script gets its
+ * imports rewritten to real, hashed module URLs, so the import resolves.
+ * (JSON-serializable values only — matches `PreprToolbarProps`, a plain
+ * data shape of primitives/arrays.)
+ */
+import type { PreprToolbarProps } from '@preprio/toolkit';
+
+type Props = PreprToolbarProps;
+
+const { activeSegment, activeVariant, segments, data } = Astro.props as Props;
+// `data` is the deprecated alias for `segments`; accept either.
+const props = { activeSegment, activeVariant, segments: segments ?? data ?? [] };
+---
+
+<script
+  type="application/json"
+  data-prepr-toolbar-props
+  set:html={JSON.stringify(props)}
+/>
+
+<script>
+  import { createPreprToolbar } from '@preprio/toolkit';
+
+  const el = document.querySelector('script[data-prepr-toolbar-props]');
+  if (el?.textContent) {
+    createPreprToolbar({ props: JSON.parse(el.textContent) });
+  }
+</script>

package/src/astro/PreprTrackingPixel.astro

@@ -0,0 +1,48 @@
+---
+/**
+ * Loads Prepr's CDN tracking pixel client-side via `loadTrackingPixel`
+ * (core). Renders nothing visible.
+ *
+ * Ships as SOURCE — see `PreprToolbar.astro` for the rationale (compiled by
+ * the consumer's own Astro pipeline, not this package's `tsup` build).
+ *
+ * Server → client props transfer: props are emitted into a
+ * `<script type="application/json">` tag and read back by a SEPARATE,
+ * NON-inline `<script>` that Astro/Vite bundles. We deliberately avoid
+ * `define:vars` (which forces `is:inline`) because inline scripts do not get
+ * their bare `import` specifiers processed — `import { loadTrackingPixel }
+ * from '@preprio/toolkit'` would fail to resolve in the browser. See
+ * `PreprToolbar.astro` for the full explanation.
+ */
+interface Props {
+  id: string;
+  config?: {
+    destinations?: { googleTagManager?: boolean };
+    variantImpressionThreshold?: number;
+  };
+}
+
+const { id, config } = Astro.props as Props;
+// JSON-serialize into a plain data payload. An omitted `config` becomes
+// `undefined`, which `JSON.stringify` drops from the object entirely — the
+// mount script normalizes a missing `config` back to `undefined` so
+// `loadTrackingPixel`'s `config !== undefined` check (core/pixel.ts) behaves
+// the same as calling it directly with no config argument.
+const payload = { id, config };
+---
+
+<script
+  type="application/json"
+  data-prepr-pixel-props
+  set:html={JSON.stringify(payload)}
+/>
+
+<script>
+  import { loadTrackingPixel } from '@preprio/toolkit';
+
+  const el = document.querySelector('script[data-prepr-pixel-props]');
+  if (el?.textContent) {
+    const { id, config } = JSON.parse(el.textContent);
+    loadTrackingPixel(id, config ?? undefined);
+  }
+</script>

package/src/sveltekit/PreprToolbar.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  /**
+   * Mounts the Prepr toolbar custom element (and stega edit mode); renders
+   * nothing itself. `onMount` keeps it off the SSR path.
+   *
+   * Ships as source — the consumer's Vite/Svelte pipeline compiles this, not
+   * our tsup build. See the `./sveltekit/components/*` export in package.json.
+   */
+  import { onMount } from 'svelte';
+  import { createPreprToolbar } from '@preprio/toolkit';
+  import type { PreprToolbarProps } from '@preprio/toolkit';
+
+  let { activeSegment, activeVariant, data, segments }: PreprToolbarProps = $props();
+
+  onMount(() => {
+    const controller = createPreprToolbar({
+      props: { activeSegment, activeVariant, data, segments },
+    });
+    return () => controller.destroy();
+  });
+</script>

package/src/sveltekit/PreprTrackingPixel.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  /**
+   * Loads Prepr's CDN tracking pixel client-side via `loadTrackingPixel`
+   * (core). Renders nothing visible. Ships as SOURCE — see PreprToolbar.svelte.
+   */
+  import { onMount } from 'svelte';
+  import { loadTrackingPixel } from '@preprio/toolkit';
+
+  interface Props {
+    id: string;
+    config?: {
+      destinations?: { googleTagManager?: boolean };
+      variantImpressionThreshold?: number;
+    };
+  }
+
+  let { id, config }: Props = $props();
+
+  onMount(() => {
+    loadTrackingPixel(id, config ?? undefined);
+  });
+</script>