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

package/dist/nextjs/index.cjs

@@ -20,9 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/nextjs/index.ts
 var nextjs_exports = {};
 __export(nextjs_exports, {
+  PREPR_BUCKET_COOKIE: () => PREPR_BUCKET_COOKIE,
   PreprError: () => PreprError,
   PreprToolbar: () => import_components.PreprToolbar,
   PreprTrackingPixel: () => import_components.PreprTrackingPixel,
+  createPreprDraftRoute: () => createPreprDraftRoute,
   createPreprMiddleware: () => createPreprMiddleware,
   extractAccessToken: () => extractAccessToken,
   getActiveSegment: () => getActiveSegment,
@@ -30,6 +32,9 @@ __export(nextjs_exports, {
   getPreprHeaders: () => getPreprHeaders,
   getPreprUUID: () => getPreprUUID,
   getToolbarProps: () => getToolbarProps,
+  isPersonalizedResponse: () => isPersonalizedResponse,
+  preprDraftRedirect: () => preprDraftRedirect,
+  resolvePreprBucket: () => resolvePreprBucket,
   validatePreprToken: () => validatePreprToken
 });
 module.exports = __toCommonJS(nextjs_exports);
@@ -38,7 +43,7 @@ module.exports = __toCommonJS(nextjs_exports);
 var import_server = require("next/server");
 
 // src/version.ts
-var VERSION = "0.5.0-rc.2";
+var VERSION = "0.6.0-alpha.1";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";
@@ -83,9 +88,9 @@ function sanitizeHeaderValue(value) {
   return stripped.length > MAX_HEADER_VALUE_LENGTH ? stripped.slice(0, MAX_HEADER_VALUE_LENGTH) : stripped;
 }
 function parseCookies(request) {
-  const cookies = /* @__PURE__ */ new Map();
+  const cookies2 = /* @__PURE__ */ new Map();
   const header = request.headers.get("cookie");
-  if (!header) return cookies;
+  if (!header) return cookies2;
   for (const part of header.split(";")) {
     const eq = part.indexOf("=");
     if (eq === -1) continue;
@@ -93,12 +98,12 @@ function parseCookies(request) {
     const value = part.slice(eq + 1).trim();
     if (!name) continue;
     try {
-      cookies.set(name, decodeURIComponent(value));
+      cookies2.set(name, decodeURIComponent(value));
     } catch {
-      cookies.set(name, value);
+      cookies2.set(name, value);
     }
   }
-  return cookies;
+  return cookies2;
 }
 function processFrameworkRequest(request, opts, framework) {
   const requestHeaders = new Headers(request.headers);
@@ -218,6 +223,10 @@ function processFrameworkRequest(request, opts, framework) {
       });
     }
   }
+  if (requestHeaders.has("Prepr-Segments")) {
+    requestHeaders.delete("Prepr-Customer-Id");
+    requestHeaders.delete("Prepr-Customer-Id-Created");
+  }
   return { requestHeaders, responseCookies };
 }
 
@@ -453,13 +462,121 @@ async function getToolbarProps(token, features) {
   return getToolbarPropsFromHeaders(h, token, features);
 }
 
+// src/core/personalization.ts
+var PERSONALIZED_VARY = /\bPrepr-(Segments|ABTesting)/i;
+function isPersonalizedResponse(source) {
+  const headers2 = "headers" in source ? source.headers : source;
+  return PERSONALIZED_VARY.test(headers2.get("vary") ?? "");
+}
+
+// src/nextjs/bucket.ts
+var PREPR_BUCKET_COOKIE = "prepr_ab_bucket";
+var isBucket = (value) => value === "A" || value === "B";
+function setBucketCookie(request, response, bucket) {
+  response.cookies.set(PREPR_BUCKET_COOKIE, bucket, {
+    path: "/",
+    sameSite: "lax",
+    // Readable on purpose: PreprStack's inline switch reads it before first
+    // paint. It holds only "A" or "B".
+    httpOnly: false,
+    secure: request.nextUrl.protocol === "https:",
+    maxAge: 60 * 60 * 24 * 365
+  });
+}
+async function resolvePreprBucket(request, response, options) {
+  const stored = request.cookies.get(PREPR_BUCKET_COOKIE)?.value;
+  const forced = response.headers.get("x-middleware-request-prepr-abtesting") ?? request.cookies.get(COOKIE_VARIANT)?.value;
+  if (options.preview && isBucket(forced)) {
+    if (forced !== stored) setBucketCookie(request, response, forced);
+    return forced;
+  }
+  if (isBucket(stored)) return stored;
+  if (options.onlyIf) {
+    const needed = await Promise.resolve().then(options.onlyIf).catch(() => true);
+    if (!needed) return "A";
+  }
+  const customerId = request.cookies.get(COOKIE_UID)?.value ?? response.cookies.get(COOKIE_UID)?.value;
+  if (!customerId) return "A";
+  try {
+    const res = await fetch(options.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Prepr-Customer-Id": customerId
+      },
+      body: JSON.stringify({ query: "{ __typename }" }),
+      cache: "no-store",
+      signal: AbortSignal.timeout(options.timeoutMs ?? 1500)
+    });
+    const bucket = res.headers.get("x-prepr-customer-bucket");
+    if (isBucket(bucket)) {
+      setBucketCookie(request, response, bucket);
+      return bucket;
+    }
+  } catch {
+  }
+  return "A";
+}
+
+// src/nextjs/draft.ts
+var import_headers2 = require("next/headers");
+var import_navigation = require("next/navigation");
+var import_server3 = require("next/server");
+var DRAFT_COOKIE = "__prerender_bypass";
+var RETURN_PARAM = "prepr_draft";
+var DEFAULT_ROUTE = "/api/prepr/draft";
+function preprDraftRedirect(request, options) {
+  if (!options.preview) return null;
+  if (request.method !== "GET" && request.method !== "HEAD") return null;
+  const url = request.nextUrl;
+  if (url.pathname === (options.route ?? DEFAULT_ROUTE)) return null;
+  if (request.cookies.has(DRAFT_COOKIE)) {
+    if (!url.searchParams.has(RETURN_PARAM)) return null;
+    const clean = url.clone();
+    clean.searchParams.delete(RETURN_PARAM);
+    return import_server3.NextResponse.redirect(clean, 307);
+  }
+  if (url.searchParams.has(RETURN_PARAM)) return null;
+  const target = new URL(options.route ?? DEFAULT_ROUTE, request.url);
+  target.searchParams.set("to", url.pathname + url.search);
+  return import_server3.NextResponse.redirect(target, 307);
+}
+function createPreprDraftRoute(options) {
+  return async (request) => {
+    if (!options.preview) return new Response("Not found", { status: 404 });
+    (await (0, import_headers2.draftMode)()).enable();
+    const self = new URL(request.url);
+    if (self.protocol === "https:") {
+      const jar = await (0, import_headers2.cookies)();
+      const draft = jar.get(DRAFT_COOKIE);
+      if (draft) {
+        jar.set({
+          name: DRAFT_COOKIE,
+          value: draft.value,
+          path: "/",
+          httpOnly: true,
+          secure: true,
+          sameSite: "none",
+          partitioned: true
+        });
+      }
+    }
+    let to = new URL(self.searchParams.get("to") ?? "/", self);
+    if (to.origin !== self.origin) to = new URL("/", self);
+    to.searchParams.set(RETURN_PARAM, "1");
+    (0, import_navigation.redirect)(to.pathname + to.search);
+  };
+}
+
 // src/nextjs/index.ts
 var import_components = require("./components.cjs");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PREPR_BUCKET_COOKIE,
   PreprError,
   PreprToolbar,
   PreprTrackingPixel,
+  createPreprDraftRoute,
   createPreprMiddleware,
   extractAccessToken,
   getActiveSegment,
@@ -467,5 +584,8 @@ var import_components = require("./components.cjs");
   getPreprHeaders,
   getPreprUUID,
   getToolbarProps,
+  isPersonalizedResponse,
+  preprDraftRedirect,
+  resolvePreprBucket,
   validatePreprToken
 });

package/dist/nextjs/index.d.cts

@@ -1,137 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-
-type Dictionary = Record<string, unknown>;
-declare const dictionaries: {
-    en: Dictionary;
-    nl: Dictionary;
-};
-type Locale = keyof typeof dictionaries;
-
-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 PreprToolbarOptions {
-    debug?: boolean;
-    locale?: Locale;
-    /** Disable features app-wide. Pass the same object to the middleware. */
-    features?: PreprFeatures;
-}
-/**
- * Options for the preview runtime. Two independent axes: `features` decides
- * *what runs*, `ui` decides *whether the toolbar is visible*.
- */
-interface PreprPreviewOptions extends PreprToolbarOptions {
-    /**
-     * Mount the visible `<prepr-toolbar>` element. Default `true`.
-     *
-     * `false` keeps every non-visual side effect wired — click-to-edit, the
-     * editor bridge, scroll restore, cookies and headers — with no chrome of its
-     * own. That is how a site gets live editing, or editor scroll restore, while
-     * rendering its own UI instead of the bar.
-     *
-     * Already implied inside the editor's iframe (the CMS owns the chrome there)
-     * and by `?prepr_hide_bar=true`, so this option is for consumers who want a
-     * headless preview by their own choice.
-     */
-    ui?: boolean;
-    /**
-     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, e.g.
-     * `['http://acme.localhost:8000']`. Intended for self-hosted or locally run
-     * editors; when set, the wildcard no longer applies. Entries are compared to
-     * the editor's origin exactly: scheme, host and port.
-     *
-     * `['*']` accepts any editor origin. Use it for development only: any page
-     * that frames the preview can then switch on preview and edit mode and
-     * receives the field-edit events, which carry content item ids.
-     */
-    allowedEditorOrigins?: string[];
-    /**
-     * Strip the invisible stega characters out of visible text at runtime.
-     * Default `true`.
-     *
-     * Preview content carries an encoded payload inside the text itself. Left in
-     * place it is invisible but real: it inflates `String.length`, breaks text
-     * measurement and truncation, and is announced by screen readers.
-     *
-     * Set `false` only when the site already strips the characters itself — for
-     * example by passing every field through `stegaClean` as it renders.
-     * Click-to-edit is unaffected either way: elements are still tagged from the
-     * payload, so the overlay keeps working.
-     */
-    autoClean?: boolean;
-}
-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[];
-}
-/**
- * Prop type for the framework `<PreprToolbar>` components: the toolbar data
- * plus the options bag core `createPreprPreview` accepts.
- */
-interface PreprToolbarComponentProps extends PreprToolbarProps {
-    options?: PreprPreviewOptions;
-}
-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';
+import { b as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-CjpELYvq.cjs';
+export { a as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-CjpELYvq.cjs';
 
 interface PreprMiddlewareOptions {
     /** Enable preview-mode headers (segment/AB overrides, preview bar). */
@@ -175,24 +44,61 @@ declare function getPreprHeaders(): Promise<PreprHeaders>;
  */
 declare function getToolbarProps(token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
 
-/** 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);
+/** Cookie holding the visitor's A/B bucket, as Prepr assigned it. */
+declare const PREPR_BUCKET_COOKIE = "prepr_ab_bucket";
+type PreprBucket = 'A' | 'B';
+interface ResolvePreprBucketOptions {
+    /** Full Prepr GraphQL URL. */
+    url: string;
+    /** Preview mode: the toolbar's A/B override wins. */
+    preview?: boolean;
+    /** Abort the one-time lookup after this many ms. Default 1500. */
+    timeoutMs?: number;
+    /**
+     * Look the bucket up only when this resolves to true, typically "does this
+     * page have an A/B test": `() => prepr.hasAbTests(PageDocument, { slug })`.
+     * Only called for visitors without a bucket cookie, so visitors on pages
+     * without A/B tests never wait for the lookup.
+     */
+    onlyIf?: () => boolean | Promise<boolean>;
+}
+declare function resolvePreprBucket(request: NextRequest, response: NextResponse, options: ResolvePreprBucketOptions): Promise<PreprBucket>;
+
+interface PreprDraftOptions {
+    /** Whether this deployment serves preview content. Outside it, both helpers do nothing. */
+    preview: boolean;
+    /** Path of the route handler made with `createPreprDraftRoute`. Default `/api/prepr/draft`. */
+    route?: string;
 }
 /**
- * Asserts `token` is the full `https://graphql.prepr.io/<token>` URL.
- * @throws PreprError if the token is missing or not an HTTPS URL.
+ * In preview, sends a visitor without draft mode through the draft route once,
+ * from middleware (`proxy.ts`). Returns the redirect to send, or `null` to
+ * carry on.
+ *
+ * Draft mode is what keeps preview fresh with Cache Components: Next.js then
+ * renders every page per request and skips `'use cache'` entries and the Data
+ * Cache, so an edit shows on the next load without a publish webhook.
+ *
+ * Call it first in the proxy, before `createPreprMiddleware`.
+ *
+ * @example
+ * const draft = preprDraftRedirect(request, { preview });
+ * if (draft) return draft;
  */
-declare function validatePreprToken(token: string): void;
+declare function preprDraftRedirect(request: NextRequest, options: PreprDraftOptions): NextResponse | null;
 /**
- * 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.
+ * The route handler `preprDraftRedirect` sends preview visitors to: turns on
+ * draft mode and redirects back to the page. Answers 404 outside preview.
+ * Only same-origin paths are followed, so it cannot be used as an open
+ * redirect.
+ *
+ * @example
+ * // app/api/prepr/draft/route.ts
+ * export const GET = createPreprDraftRoute({
+ *   preview: process.env.PREPR_ENV === 'preview',
+ * });
  */
-declare function extractAccessToken(graphqlUrl: string): string;
+declare function createPreprDraftRoute(options: Pick<PreprDraftOptions, 'preview'>): (request: Request) => Promise<Response>;
 
 /**
  * Loader + typed facade for Prepr's CDN tracking pixel, so consumers don't have
@@ -248,4 +154,4 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
 
-export { PreprError, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, createPreprMiddleware, extractAccessToken, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, validatePreprToken };
+export { PREPR_BUCKET_COOKIE, type PreprBucket, type PreprDraftOptions, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type ResolvePreprBucketOptions, createPreprDraftRoute, createPreprMiddleware, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect, resolvePreprBucket };

package/dist/nextjs/index.d.ts

@@ -1,137 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-
-type Dictionary = Record<string, unknown>;
-declare const dictionaries: {
-    en: Dictionary;
-    nl: Dictionary;
-};
-type Locale = keyof typeof dictionaries;
-
-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 PreprToolbarOptions {
-    debug?: boolean;
-    locale?: Locale;
-    /** Disable features app-wide. Pass the same object to the middleware. */
-    features?: PreprFeatures;
-}
-/**
- * Options for the preview runtime. Two independent axes: `features` decides
- * *what runs*, `ui` decides *whether the toolbar is visible*.
- */
-interface PreprPreviewOptions extends PreprToolbarOptions {
-    /**
-     * Mount the visible `<prepr-toolbar>` element. Default `true`.
-     *
-     * `false` keeps every non-visual side effect wired — click-to-edit, the
-     * editor bridge, scroll restore, cookies and headers — with no chrome of its
-     * own. That is how a site gets live editing, or editor scroll restore, while
-     * rendering its own UI instead of the bar.
-     *
-     * Already implied inside the editor's iframe (the CMS owns the chrome there)
-     * and by `?prepr_hide_bar=true`, so this option is for consumers who want a
-     * headless preview by their own choice.
-     */
-    ui?: boolean;
-    /**
-     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, e.g.
-     * `['http://acme.localhost:8000']`. Intended for self-hosted or locally run
-     * editors; when set, the wildcard no longer applies. Entries are compared to
-     * the editor's origin exactly: scheme, host and port.
-     *
-     * `['*']` accepts any editor origin. Use it for development only: any page
-     * that frames the preview can then switch on preview and edit mode and
-     * receives the field-edit events, which carry content item ids.
-     */
-    allowedEditorOrigins?: string[];
-    /**
-     * Strip the invisible stega characters out of visible text at runtime.
-     * Default `true`.
-     *
-     * Preview content carries an encoded payload inside the text itself. Left in
-     * place it is invisible but real: it inflates `String.length`, breaks text
-     * measurement and truncation, and is announced by screen readers.
-     *
-     * Set `false` only when the site already strips the characters itself — for
-     * example by passing every field through `stegaClean` as it renders.
-     * Click-to-edit is unaffected either way: elements are still tagged from the
-     * payload, so the overlay keeps working.
-     */
-    autoClean?: boolean;
-}
-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[];
-}
-/**
- * Prop type for the framework `<PreprToolbar>` components: the toolbar data
- * plus the options bag core `createPreprPreview` accepts.
- */
-interface PreprToolbarComponentProps extends PreprToolbarProps {
-    options?: PreprPreviewOptions;
-}
-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';
+import { b as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-CjpELYvq.js';
+export { a as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-CjpELYvq.js';
 
 interface PreprMiddlewareOptions {
     /** Enable preview-mode headers (segment/AB overrides, preview bar). */
@@ -175,24 +44,61 @@ declare function getPreprHeaders(): Promise<PreprHeaders>;
  */
 declare function getToolbarProps(token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
 
-/** 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);
+/** Cookie holding the visitor's A/B bucket, as Prepr assigned it. */
+declare const PREPR_BUCKET_COOKIE = "prepr_ab_bucket";
+type PreprBucket = 'A' | 'B';
+interface ResolvePreprBucketOptions {
+    /** Full Prepr GraphQL URL. */
+    url: string;
+    /** Preview mode: the toolbar's A/B override wins. */
+    preview?: boolean;
+    /** Abort the one-time lookup after this many ms. Default 1500. */
+    timeoutMs?: number;
+    /**
+     * Look the bucket up only when this resolves to true, typically "does this
+     * page have an A/B test": `() => prepr.hasAbTests(PageDocument, { slug })`.
+     * Only called for visitors without a bucket cookie, so visitors on pages
+     * without A/B tests never wait for the lookup.
+     */
+    onlyIf?: () => boolean | Promise<boolean>;
+}
+declare function resolvePreprBucket(request: NextRequest, response: NextResponse, options: ResolvePreprBucketOptions): Promise<PreprBucket>;
+
+interface PreprDraftOptions {
+    /** Whether this deployment serves preview content. Outside it, both helpers do nothing. */
+    preview: boolean;
+    /** Path of the route handler made with `createPreprDraftRoute`. Default `/api/prepr/draft`. */
+    route?: string;
 }
 /**
- * Asserts `token` is the full `https://graphql.prepr.io/<token>` URL.
- * @throws PreprError if the token is missing or not an HTTPS URL.
+ * In preview, sends a visitor without draft mode through the draft route once,
+ * from middleware (`proxy.ts`). Returns the redirect to send, or `null` to
+ * carry on.
+ *
+ * Draft mode is what keeps preview fresh with Cache Components: Next.js then
+ * renders every page per request and skips `'use cache'` entries and the Data
+ * Cache, so an edit shows on the next load without a publish webhook.
+ *
+ * Call it first in the proxy, before `createPreprMiddleware`.
+ *
+ * @example
+ * const draft = preprDraftRedirect(request, { preview });
+ * if (draft) return draft;
  */
-declare function validatePreprToken(token: string): void;
+declare function preprDraftRedirect(request: NextRequest, options: PreprDraftOptions): NextResponse | null;
 /**
- * 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.
+ * The route handler `preprDraftRedirect` sends preview visitors to: turns on
+ * draft mode and redirects back to the page. Answers 404 outside preview.
+ * Only same-origin paths are followed, so it cannot be used as an open
+ * redirect.
+ *
+ * @example
+ * // app/api/prepr/draft/route.ts
+ * export const GET = createPreprDraftRoute({
+ *   preview: process.env.PREPR_ENV === 'preview',
+ * });
  */
-declare function extractAccessToken(graphqlUrl: string): string;
+declare function createPreprDraftRoute(options: Pick<PreprDraftOptions, 'preview'>): (request: Request) => Promise<Response>;
 
 /**
  * Loader + typed facade for Prepr's CDN tracking pixel, so consumers don't have
@@ -248,4 +154,4 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
 
-export { PreprError, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, createPreprMiddleware, extractAccessToken, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, validatePreprToken };
+export { PREPR_BUCKET_COOKIE, type PreprBucket, type PreprDraftOptions, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type ResolvePreprBucketOptions, createPreprDraftRoute, createPreprMiddleware, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect, resolvePreprBucket };