@preprio/toolkit 0.5.0-rc.1 → 0.6.0-alpha.0

package/dist/nuxt/index.js

@@ -1,394 +1,17 @@
-// src/version.ts
-var VERSION = "0.5.0-rc.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/features.ts
-function isEnabled(config) {
-  if (typeof config === "boolean") return config;
-  return config?.enabled ?? true;
-}
-function resolveFeatures(features) {
-  return {
-    segments: isEnabled(features?.segments),
-    abTesting: isEnabled(features?.abTesting),
-    editMode: isEnabled(features?.editMode)
-  };
-}
-var ALL_FEATURES_ENABLED = Object.freeze({
-  segments: true,
-  abTesting: true,
-  editMode: true
-});
-
-// src/core/middleware.ts
-var UTM_PARAMS = [
-  "utm_source",
-  "utm_medium",
-  "utm_term",
-  "utm_content",
-  "utm_campaign"
-];
-var MAX_HEADER_VALUE_LENGTH = 2048;
-function sanitizeHeaderValue(value) {
-  const stripped = value.replace(/[\u0000-\u001f\u007f]/g, "");
-  return stripped.length > MAX_HEADER_VALUE_LENGTH ? stripped.slice(0, MAX_HEADER_VALUE_LENGTH) : stripped;
-}
-function serializeCookie(cookie) {
-  const parts = [
-    `${cookie.name}=${encodeURIComponent(cookie.value)}`,
-    `Max-Age=${cookie.maxAge}`,
-    `Path=${cookie.path}`
-  ];
-  if (cookie.sameSite) {
-    parts.push(`SameSite=${cookie.sameSite}`);
-  }
-  if (cookie.secure) {
-    parts.push("Secure");
-  }
-  return parts.join("; ");
-}
-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;
-    try {
-      cookies.set(name, decodeURIComponent(value));
-    } catch {
-      cookies.set(name, value);
-    }
-  }
-  return cookies;
-}
-function processFrameworkRequest(request, opts, framework) {
-  const requestHeaders = new Headers(request.headers);
-  const responseCookies = [];
-  const inboundPreprHeaders = [];
-  requestHeaders.forEach((_value, key) => {
-    if (key.toLowerCase().startsWith("prepr-")) {
-      inboundPreprHeaders.push(key);
-    }
-  });
-  for (const key of inboundPreprHeaders) {
-    requestHeaders.delete(key);
-  }
-  const requestCookies = parseCookies(request);
-  const url = new URL(request.url);
-  const searchParams = url.searchParams;
-  const forwardedProto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
-  const isSecure = forwardedProto ? forwardedProto === "https" : url.protocol === "https:";
-  const crossSite = isSecure ? { sameSite: "None", secure: true } : {};
-  for (const key of UTM_PARAMS) {
-    const value = searchParams.get(key);
-    if (value !== null) {
-      requestHeaders.set(`Prepr-Context-${key}`, sanitizeHeaderValue(value));
-    }
-  }
-  const referer = request.headers.get("referer");
-  if (referer) {
-    requestHeaders.set(
-      "Prepr-Context-initial_referral",
-      sanitizeHeaderValue(referer)
-    );
-  }
-  const userAgent = request.headers.get("user-agent");
-  if (userAgent) {
-    requestHeaders.set("User-Agent", sanitizeHeaderValue(userAgent));
-  }
-  const packageParts = [`@preprio/toolkit@${opts?.version ?? VERSION}`];
-  if (framework) packageParts.push(`framework=${framework}`);
-  packageParts.push(`preview=${opts?.preview ? "true" : "false"}`);
-  requestHeaders.set("Prepr-Package", packageParts.join("; "));
-  const ip = request.headers.get("Cf-Connecting-Ip") ?? request.headers.get("x-real-ip");
-  if (ip) {
-    requestHeaders.set("Prepr-Visitor-IP", sanitizeHeaderValue(ip));
-  }
-  const hutkCookie = requestCookies.get(COOKIE_HUBSPOT);
-  if (hutkCookie) {
-    requestHeaders.set("Prepr-Hubspot-Id", sanitizeHeaderValue(hutkCookie));
-  }
-  let uid = sanitizeHeaderValue(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 features = resolveFeatures(opts?.features);
-  const hasPreviewParams = features.segments && searchParams.has(PARAM_SEGMENT) || features.abTesting && 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 && !requestCookies.has(COOKIE_PREVIEW_MODE)) {
-    responseCookies.push({
-      name: COOKIE_PREVIEW_MODE,
-      value: "true",
-      maxAge: ONE_YEAR_SECONDS,
-      path: "/",
-      ...crossSite
-    });
-  }
-  if (!isLivePreview) {
-    const segmentCookie = features.segments ? requestCookies.get(COOKIE_SEGMENT) : void 0;
-    if (segmentCookie) {
-      requestHeaders.set("Prepr-Segments", sanitizeHeaderValue(segmentCookie));
-    }
-    const abCookie = features.abTesting ? requestCookies.get(COOKIE_VARIANT) : void 0;
-    if (abCookie) {
-      requestHeaders.set("Prepr-ABtesting", sanitizeHeaderValue(abCookie));
-    }
-  }
-  const previewAb = features.abTesting ? searchParams.get(PARAM_VARIANT) : null;
-  if (previewAb !== null) {
-    requestHeaders.set("Prepr-ABtesting", sanitizeHeaderValue(previewAb));
-    if (!isLivePreview) {
-      responseCookies.push({
-        name: COOKIE_VARIANT,
-        value: previewAb,
-        maxAge: ONE_YEAR_SECONDS,
-        path: "/",
-        ...crossSite
-      });
-    }
-  }
-  const previewSegment = features.segments ? searchParams.get(PARAM_SEGMENT) : null;
-  if (previewSegment !== null) {
-    requestHeaders.set("Prepr-Segments", sanitizeHeaderValue(previewSegment));
-    if (!isLivePreview) {
-      responseCookies.push({
-        name: COOKIE_SEGMENT,
-        value: previewSegment,
-        maxAge: ONE_YEAR_SECONDS,
-        path: "/",
-        ...crossSite
-      });
-    }
-  }
-  return { requestHeaders, responseCookies };
-}
-
-// src/nuxt/middleware.ts
-var PREPR_CONTEXT_KEY = "prepr";
-function handlePreprRequest(event, options) {
-  const req = event.node.req;
-  const host = typeof req.headers.host === "string" ? req.headers.host : "localhost";
-  const request = new Request(`http://${host}${req.url ?? "/"}`);
-  for (const [key, value] of Object.entries(req.headers)) {
-    if (typeof value === "string") {
-      request.headers.set(key, value);
-    } else if (Array.isArray(value)) {
-      request.headers.set(key, value.join(", "));
-    }
-  }
-  const { requestHeaders, responseCookies } = processFrameworkRequest(
-    request,
-    options,
-    "nuxt"
-  );
-  requestHeaders.forEach((value, key) => {
-    req.headers[key.toLowerCase()] = value;
-  });
-  event.context[PREPR_CONTEXT_KEY] = requestHeaders;
-  for (const cookie of responseCookies) {
-    event.node.res.appendHeader("Set-Cookie", serializeCookie(cookie));
-  }
-}
-function getPreprHeadersFromEvent(event) {
-  const headers = event.context[PREPR_CONTEXT_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",
-  "User-Agent",
-  "Prepr-Package"
-];
-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: {
-        "Prepr-Package": `@preprio/toolkit@${VERSION}`,
-        // Duplicates the version in Prepr-Package. It keeps the User-Agent
-        // format used by `@preprio/prepr-nextjs`, for Prepr API consumers that
-        // still identify the toolbar by that string.
-        "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, features) {
-  const resolved = resolveFeatures(features);
-  let segments = [];
-  if (resolved.segments) {
-    try {
-      segments = await getPreprEnvironmentSegments(token);
-    } catch {
-      segments = [];
-    }
-  }
-  return {
-    activeSegment: resolved.segments ? getActiveSegmentFromHeaders(headers) : null,
-    activeVariant: resolved.abTesting ? getActiveVariantFromHeaders(headers) : null,
-    segments,
-    data: segments
-  };
-}
+import {
+  PREPR_CONTEXT_KEY,
+  PreprError,
+  extractAccessToken,
+  getActiveSegmentFromHeaders,
+  getActiveVariantFromHeaders,
+  getPreprHeadersFromEvent,
+  getPreprHeadersFromHeaders,
+  getPreprUUIDFromHeaders,
+  getToolbarPropsFromHeaders,
+  handlePreprRequest,
+  isPersonalizedResponse,
+  validatePreprToken
+} from "./chunk-P6ENNAEE.js";
 
 // src/nuxt/server.ts
 function getPreprUUID(headers) {
@@ -417,5 +40,6 @@ export {
   getPreprUUID,
   getToolbarProps,
   handlePreprRequest,
+  isPersonalizedResponse,
   validatePreprToken
 };

package/dist/nuxt/server-8v6OHbsw.d.cts

@@ -0,0 +1,158 @@
+interface PreprSegment {
+    readonly _id: string;
+    readonly name: string;
+}
+/**
+ * Per-feature config. `false` is shorthand for `{ enabled: false }`; the object
+ * form leaves room for per-feature options later without a breaking change.
+ */
+type PreprFeatureConfig = boolean | {
+    enabled?: boolean;
+};
+/** Toolkit features a consumer can turn off. Omitted keys stay enabled. */
+interface PreprFeatures {
+    /** Segment picker, `Prepr-Segments` header and its cookie/query param. */
+    segments?: PreprFeatureConfig;
+    /** A/B variant switch, `Prepr-ABtesting` header and its cookie/query param. */
+    abTesting?: PreprFeatureConfig;
+    /**
+     * The site's own click-to-edit: the toolbar's Edit mode control, the stega
+     * tooltip/overlay and the close-edit pill.
+     *
+     * NOT a security control, and NOT the Prepr editor's live preview. When the
+     * site is framed by the editor, `prepr:initVE` still activates edit mode —
+     * that is the CMS operating inside its own iframe, not an affordance offered
+     * to visitors. See iframe-bridge.ts.
+     */
+    editMode?: PreprFeatureConfig;
+}
+interface PreprToolbarProps {
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
+    /** Available segments to personalize on. */
+    readonly segments?: readonly PreprSegment[];
+    /** @deprecated Alias for `segments`. */
+    readonly data?: readonly PreprSegment[];
+}
+type PreprVariant = 'A' | 'B';
+interface PreprHeaders {
+    readonly 'prepr-customer-id'?: string;
+    readonly 'Prepr-Segments'?: string;
+    readonly 'Prepr-ABtesting'?: PreprVariant;
+    readonly 'Prepr-Preview-Bar'?: 'true';
+    readonly 'Prepr-Context-utm_source'?: string;
+    readonly 'Prepr-Context-utm_medium'?: string;
+    readonly 'Prepr-Context-utm_term'?: string;
+    readonly 'Prepr-Context-utm_content'?: string;
+    readonly 'Prepr-Context-utm_campaign'?: string;
+    readonly 'Prepr-Context-initial_referral'?: string;
+    readonly 'Prepr-Visitor-IP'?: string;
+    readonly 'Prepr-Hubspot-Id'?: string;
+    readonly 'Prepr-Customer-Id-Created'?: 'true';
+    /** The visitor's browser User-Agent, used by the API for device detection. */
+    readonly 'User-Agent'?: string;
+    /** @deprecated Never populated; the visitor's value is under `User-Agent`. */
+    readonly 'Prepr-User-Agent'?: string;
+    readonly 'Prepr-Package'?: string;
+}
+type PreprErrorCode = 'INVALID_TOKEN' | 'MISSING_TOKEN' | 'HTTP_ERROR' | 'FETCH_ERROR' | 'INVALID_RESPONSE' | 'CONTEXT_ERROR' | 'GRAPHQL_ERROR' | 'INVALID_DOCUMENT';
+
+interface PreprMiddlewareOptions {
+    /** Enable preview-mode headers (segment/AB overrides, preview bar). */
+    preview?: boolean;
+    /**
+     * Disable features app-wide. Pass the same object you give the toolbar: a
+     * disabled feature injects no header and persists no cookie, whatever the
+     * request carries.
+     */
+    features?: PreprFeatures;
+    /** Override the version reported in Prepr-Package (mainly for tests). */
+    version?: string;
+}
+
+/**
+ * Structural stand-in for h3's `H3Event`, so this package needs no build-time
+ * dependency on `h3`/`nuxt`. Only the fields `handlePreprRequest` uses.
+ *
+ * `node` ties this to Nitro's Node.js preset (the Nuxt default). Edge presets
+ * expose no raw Node request/response to fold headers back onto.
+ */
+interface H3EventLike {
+    node: {
+        req: {
+            url?: string;
+            headers: Record<string, string | string[] | undefined>;
+        };
+        res: {
+            /** Node's `ServerResponse.appendHeader` (Node >= 18.3). */
+            appendHeader(name: string, value: string): unknown;
+        };
+    };
+    /** Request-scoped bag shared with route handlers and Vue via `useRequestEvent`. */
+    context: Record<string, unknown>;
+}
+/** Key under which `handlePreprRequest` mirrors the forwarded Prepr `Headers`. */
+declare const PREPR_CONTEXT_KEY = "prepr";
+/**
+ * Nuxt server middleware entry point — call it inside `defineEventHandler` in
+ * `server/middleware/prepr.ts`:
+ *
+ * ```ts
+ * export default defineEventHandler(event => {
+ *   handlePreprRequest(event, { preview: import.meta.dev });
+ * });
+ * ```
+ *
+ * The computed Prepr headers are folded back onto the raw Node request
+ * (lowercased, as Node stores them), which is what `useRequestHeaders()` and
+ * downstream handlers read. The same `Headers` are mirrored onto
+ * `event.context.prepr` for callers who prefer an explicit read
+ * (`getPreprHeadersFromEvent`). Cookies are appended to the response.
+ */
+declare function handlePreprRequest(event: H3EventLike, options?: PreprMiddlewareOptions): void;
+/**
+ * Personalization headers to forward to your GraphQL fetch, from the h3 event.
+ * Empty `Headers` if `handlePreprRequest` did not run, so the result is always
+ * safe to spread.
+ */
+declare function getPreprHeadersFromEvent(event: Pick<H3EventLike, 'context'>): Headers;
+
+/**
+ * Whether a Prepr GraphQL response differs per visitor, read from its `Vary`
+ * header. Use it when fetching with your own GraphQL client; the toolkit's
+ * `createPreprClient` already returns it as `personalized`.
+ *
+ * Never throws; a response without `Vary` is not personalized.
+ */
+declare function isPersonalizedResponse(source: Response | Headers): boolean;
+
+/** Error thrown by the token helpers and the segments fetch. */
+declare class PreprError extends Error {
+    readonly code: PreprErrorCode;
+    readonly context?: string | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, code: PreprErrorCode, context?: string | undefined, originalError?: Error | undefined);
+}
+/**
+ * Asserts `token` is the full `https://graphql.prepr.io/<token>` URL.
+ * @throws PreprError if the token is missing or not an HTTPS URL.
+ */
+declare function validatePreprToken(token: string): void;
+/**
+ * Pulls the access token out of a GraphQL URL: `https://graphql.prepr.io/abc123`
+ * -> `abc123`.
+ * @throws PreprError if the URL is not a valid `graphql.prepr.io` URL.
+ */
+declare function extractAccessToken(graphqlUrl: string): string;
+
+export { type H3EventLike as H, type PreprHeaders as P, PreprError as a, type PreprFeatures as b, type PreprToolbarProps as c, PREPR_CONTEXT_KEY as d, type PreprMiddlewareOptions as e, extractAccessToken as f, getPreprHeadersFromEvent as g, handlePreprRequest as h, isPersonalizedResponse as i, validatePreprToken as v };