@preprio/toolkit 0.6.0-alpha.1 → 0.6.0-alpha.3

package/dist/nextjs/graphql.js

@@ -1,10 +1,13 @@
 import {
   PreprError,
+  createPreprMiddleware,
   getPreprHeaders,
   getPreprHeadersFromHeaders,
   isPersonalizedResponse,
+  preprDraftRedirect,
+  resolvePreprBucket,
   validatePreprToken
-} from "./chunk-BQ6IGSH6.js";
+} from "./chunk-5XGJJVGX.js";
 
 // src/core/variants/constants.ts
 var PREPR_CONTEXT_ALIAS = "_preprContext";
@@ -871,6 +874,49 @@ async function loadPreprSchema(url, options = {}) {
   return schema;
 }
 
+// src/core/refresh.ts
+var PREPR_REFRESH_COOKIE = "prepr_refresh";
+var PREPR_REFRESH_HEADER = "Prepr-Refresh";
+var REFRESH_MAX_PATHS = 5;
+var SAFE_PATH = /^\/(?![/\\])[\w\-./%]{0,200}$/;
+function safePath(path) {
+  return SAFE_PATH.test(path) ? path : void 0;
+}
+function isFresh(at, freshFor, now = Date.now()) {
+  const age = now - at;
+  return at > 0 && age >= 0 && age < freshFor;
+}
+function cleanEntries(entries) {
+  const out = [];
+  for (const entry of entries) {
+    if (out.length === REFRESH_MAX_PATHS) break;
+    if (safePath(entry.path) && !out.some((e) => e.path === entry.path)) {
+      out.push(entry);
+    }
+  }
+  return out;
+}
+function parseRefresh(raw) {
+  return cleanEntries(
+    (raw ?? "").split("|").map((pair) => {
+      const split = pair.lastIndexOf("~");
+      const at = Number(split < 0 ? "" : pair.slice(split + 1));
+      return {
+        path: split < 0 ? pair : pair.slice(0, split),
+        at: Number.isFinite(at) && at > 0 ? Math.floor(at) : 0
+      };
+    })
+  );
+}
+function serializeRefresh(entries) {
+  return cleanEntries(entries).map((entry) => `${entry.path}~${Math.floor(entry.at)}`).join("|");
+}
+function parseRefreshPaths(header) {
+  return cleanEntries(
+    (header ?? "").split("|").map((path) => ({ path, at: 0 }))
+  ).map((entry) => entry.path);
+}
+
 // src/nextjs/decisions.ts
 var PREPR_DECISIONS_COOKIE = "prepr_decisions";
 var DECISIONS_MAX_GROUPS = 40;
@@ -902,61 +948,230 @@ function forwardedHeaders(request, response) {
   }
   return getPreprHeadersFromHeaders(headers);
 }
+var preprClientInternals = /* @__PURE__ */ new WeakMap();
+var DEFAULT_FRESH_FOR_MS = 1e4;
+async function decidePage(client, seenGroups, headers, document2, variables, timeoutMs = 1e3) {
+  if (!await client.hasSegments(document2, variables)) return void 0;
+  const decided = await client.decide(document2, variables, {
+    topLevelOnly: true,
+    headers,
+    init: { signal: AbortSignal.timeout(timeoutMs) }
+  });
+  let byVariables = seenGroups.get(document2);
+  if (!byVariables) {
+    byVariables = /* @__PURE__ */ new Map();
+    seenGroups.set(document2, byVariables);
+  }
+  const pageKey = JSON.stringify(variables ?? null);
+  let groups = byVariables.get(pageKey);
+  if (!groups) {
+    if (byVariables.size >= SEEN_MAX_PAGES) {
+      byVariables.delete(byVariables.keys().next().value);
+    }
+    groups = /* @__PURE__ */ new Set();
+    byVariables.set(pageKey, groups);
+  }
+  for (const group of decided.keys()) groups.add(group);
+  return decided;
+}
+function writeDecisions(request, response, decided, paths) {
+  const next = /* @__PURE__ */ new Map();
+  for (const decisions of decided) {
+    for (const [group, variants] of decisions) {
+      if (SAFE_ID.test(group) && !next.has(group)) {
+        next.set(
+          group,
+          variants.filter((v) => SAFE_ID.test(v))
+        );
+      }
+    }
+  }
+  for (const [group, variants] of parseDecisions(
+    request.cookies.get(PREPR_DECISIONS_COOKIE)?.value
+  )) {
+    if (!next.has(group)) next.set(group, variants);
+  }
+  const options = {
+    path: "/",
+    sameSite: "lax",
+    httpOnly: false,
+    secure: request.nextUrl.protocol === "https:"
+  };
+  if (next.size > 0) {
+    response.cookies.set(
+      PREPR_DECISIONS_COOKIE,
+      serializeDecisions(next),
+      options
+    );
+  }
+  if (paths.length > 0) {
+    const at = Date.now();
+    response.cookies.set(
+      PREPR_REFRESH_COOKIE,
+      serializeRefresh([
+        ...paths.map((path) => ({ path, at })),
+        ...parseRefresh(request.cookies.get(PREPR_REFRESH_COOKIE)?.value)
+      ]),
+      options
+    );
+  }
+}
+function pagePath(request) {
+  return request.nextUrl.basePath + request.nextUrl.pathname;
+}
+function contextChanged(request, headers) {
+  return headers.get("Prepr-Customer-Id-Created") === "true" || headers.has("Prepr-Segments") || [...request.nextUrl.searchParams.keys()].some(
+    (key) => key.startsWith("utm_")
+  );
+}
 async function resolveDecisionsWith(client, seenGroups, request, response, document2, variables, options) {
   try {
     if (options?.onlyIf && !await options.onlyIf()) return;
-    if (!await client.hasSegments(document2, variables)) return;
+    const known = seenGroups.get(document2)?.get(JSON.stringify(variables ?? null));
+    const path = pagePath(request);
     const headers = mergePreprHeaders(forwardedHeaders(request, response));
     const stored = parseDecisions(
       request.cookies.get(PREPR_DECISIONS_COOKIE)?.value
     );
-    const pageKey = `${JSON.stringify(variables ?? null)}`;
-    let byVariables = seenGroups.get(document2);
-    if (!byVariables) {
-      byVariables = /* @__PURE__ */ new Map();
-      seenGroups.set(document2, byVariables);
-    }
-    const known = byVariables.get(pageKey);
-    const isNewVisitor = headers.get("Prepr-Customer-Id-Created") === "true";
-    const contextChanged = isNewVisitor || headers.has("Prepr-Segments") || [...request.nextUrl.searchParams.keys()].some(
-      (key) => key.startsWith("utm_")
-    );
-    if (options?.reuse !== false && !contextChanged && known && [...known].every((group) => stored.has(group))) {
+    const decidedAt = parseRefresh(request.cookies.get(PREPR_REFRESH_COOKIE)?.value).find(
+      (entry) => entry.path === path
+    )?.at ?? 0;
+    const fresh = isFresh(decidedAt, options?.freshFor ?? DEFAULT_FRESH_FOR_MS);
+    if (fresh && known && !contextChanged(request, headers) && [...known].every((group) => stored.has(group))) {
       return;
     }
-    const decided = await client.decide(document2, variables, {
-      topLevelOnly: true,
+    const decided = await decidePage(
+      client,
+      seenGroups,
       headers,
-      init: { signal: AbortSignal.timeout(options?.timeoutMs ?? 1e3) }
+      document2,
+      variables,
+      options?.timeoutMs
+    );
+    if (!decided || decided.size === 0) return;
+    writeDecisions(request, response, [decided], [path]);
+  } catch (error) {
+    if (isFrameworkSignal(error)) throw error;
+  }
+}
+
+// src/nextjs/proxy.ts
+import { NextResponse } from "next/server";
+function isPagePath(pathname) {
+  return !pathname.startsWith("/_next/") && !pathname.startsWith("/api/") && !/\.[^/]*$/.test(pathname);
+}
+function createPreprProxy(options) {
+  const internals = preprClientInternals.get(options.client);
+  if (!internals) {
+    throw new PreprError(
+      "createPreprProxy needs a client made by createPreprClient from @preprio/toolkit/nextjs/graphql",
+      "CONTEXT_ERROR",
+      "createPreprProxy"
+    );
+  }
+  const { client, seenGroups, url } = internals;
+  const preview = options.preview ?? false;
+  const allowed = async (request) => {
+    if (!options.onlyIf) return true;
+    try {
+      return await options.onlyIf(request);
+    } catch {
+      return false;
+    }
+  };
+  const lookup = (target) => {
+    try {
+      return options.page(target) ?? null;
+    } catch {
+      return null;
+    }
+  };
+  async function refresh(request, response, paths) {
+    const answer = new NextResponse(null, {
+      status: 204,
+      headers: { "Cache-Control": "no-store" }
     });
-    if (!known && byVariables.size >= SEEN_MAX_PAGES) {
-      byVariables.delete(byVariables.keys().next().value);
+    for (const cookie of response.cookies.getAll()) answer.cookies.set(cookie);
+    const site = request.headers.get("sec-fetch-site");
+    if (request.method !== "GET" || site !== null && site !== "same-origin" || !await allowed(request)) {
+      return answer;
     }
-    const groups = known ?? /* @__PURE__ */ new Set();
-    for (const group of decided.keys()) groups.add(group);
-    byVariables.set(pageKey, groups);
-    const next = /* @__PURE__ */ new Map();
-    for (const [group, variants] of decided) {
-      if (SAFE_ID.test(group)) {
-        next.set(
-          group,
-          variants.filter((v) => SAFE_ID.test(v))
-        );
-      }
+    const own = new Set(
+      parseRefresh(request.cookies.get(PREPR_REFRESH_COOKIE)?.value).map(
+        (entry) => entry.path
+      )
+    );
+    const basePath = request.nextUrl.basePath;
+    const headers = mergePreprHeaders(forwardedHeaders(request, response));
+    const decided = await Promise.all(
+      paths.map(async (path) => {
+        if (!own.has(path) || !path.startsWith(basePath)) return void 0;
+        const pathname = path.slice(basePath.length) || "/";
+        if (!isPagePath(pathname)) return void 0;
+        const target = lookup(new URL(pathname, request.url));
+        if (!target) return void 0;
+        try {
+          const decisions = await decidePage(
+            client,
+            seenGroups,
+            headers,
+            target.document,
+            target.variables,
+            options.timeoutMs
+          );
+          return decisions?.size ? [path, decisions] : void 0;
+        } catch (error) {
+          if (isFrameworkSignal(error)) throw error;
+          return void 0;
+        }
+      })
+    );
+    const found = decided.filter((entry) => entry !== void 0);
+    writeDecisions(
+      request,
+      answer,
+      found.map(([, decisions]) => decisions),
+      found.map(([path]) => path)
+    );
+    return answer;
+  }
+  return async (request) => {
+    if (request.headers.has(PREPR_REFRESH_HEADER)) {
+      return refresh(
+        request,
+        createPreprMiddleware(request, { preview, features: options.features }),
+        parseRefreshPaths(request.headers.get(PREPR_REFRESH_HEADER))
+      );
     }
-    for (const [group, variants] of stored) {
-      if (!next.has(group)) next.set(group, variants);
+    const target = isPagePath(request.nextUrl.pathname) ? lookup(request.nextUrl) : null;
+    if (target && preview) {
+      const draft = preprDraftRedirect(request, { preview });
+      if (draft) return draft;
     }
-    if (next.size === 0) return;
-    response.cookies.set(PREPR_DECISIONS_COOKIE, serializeDecisions(next), {
-      path: "/",
-      sameSite: "lax",
-      // Read by the inline switch script before first paint.
-      httpOnly: false
+    const response = createPreprMiddleware(request, {
+      preview,
+      features: options.features
     });
-  } catch (error) {
-    if (isFrameworkSignal(error)) throw error;
-  }
+    if (target && await allowed(request)) {
+      await Promise.all([
+        resolvePreprBucket(request, response, {
+          url,
+          preview,
+          onlyIf: () => options.client.hasAbTests(target.document, target.variables)
+        }),
+        resolveDecisionsWith(
+          client,
+          seenGroups,
+          request,
+          response,
+          target.document,
+          target.variables,
+          { freshFor: options.freshFor, timeoutMs: options.timeoutMs }
+        )
+      ]);
+    }
+    return response;
+  };
 }
 
 // src/nextjs/stack.ts
@@ -989,7 +1204,11 @@ function applyPreprAbBucket() {
     state.__preprAbSheet.textContent = css;
   }
 }
-function applyPreprDecisions() {
+function applyPreprDecisions(view) {
+  const viewState = window;
+  const current = view === void 0 ? location.pathname + location.search : view;
+  if (viewState.__preprDecisionsView === current) return;
+  viewState.__preprDecisionsView = current;
   const match = document.cookie.match(/(?:^|; )prepr_decisions=([^;]*)/);
   let raw;
   try {
@@ -1031,7 +1250,11 @@ function applyPreprDecisions() {
 }
 
 // src/nextjs/stack.ts
-import { PreprAbSwitch, PreprVariantTracking } from "./components.js";
+import {
+  PreprAbSwitch,
+  PreprPersonalizationSwitch,
+  PreprVariantTracking
+} from "./components.js";
 var AB_ATTRIBUTE = "data-prepr-ab";
 var AB_BUCKETS = ["A", "B"];
 var AB_BASE_CSS = `[${AB_ATTRIBUTE}]{display:contents}[${AB_ATTRIBUTE}]:not([${AB_ATTRIBUTE}="A"]){display:none}`;
@@ -1053,13 +1276,18 @@ function renderBuckets(items, render, options) {
     abTest,
     index,
     track,
-    placeholder = false
+    placeholder = false,
+    defaultVariant = true
   } = options;
   const renderVariant = (variant, key) => {
     const resolved = resolveVariants(items, { decisions, bucket: variant });
-    const content = render(resolved, { index, placeholder });
-    const variantKeys = track ? variantKeysOf(resolved) : [];
     const ab = abTest && !bucket ? variant : void 0;
+    const content = render(resolved, {
+      index,
+      placeholder,
+      defaultVariant: defaultVariant && (ab === void 0 || ab === "A")
+    });
+    const variantKeys = track ? variantKeysOf(resolved) : [];
     if (variantKeys.length > 0) {
       return createElement(
         PreprVariantTracking,
@@ -1097,7 +1325,8 @@ function renderAllVariants(block, render, options) {
         decisions: /* @__PURE__ */ new Map([[group, [variant]]]),
         abTest: false,
         index: block.index,
-        track: options.track
+        track: options.track,
+        defaultVariant: variant === PREPR_DEFAULT_VARIANT
       })
     )
   );
@@ -1130,7 +1359,7 @@ function PreprStack({
   bucket,
   nonce,
   trackVariants = false,
-  aboveTheFold = 0
+  aboveTheFold = 1
 }) {
   decisions.catch(() => void 0);
   const blocks = splitStack(items);
@@ -1153,7 +1382,8 @@ function PreprStack({
         nonce,
         dangerouslySetInnerHTML: { __html: AB_SWITCH_SCRIPT }
       }),
-      createElement(PreprAbSwitch)
+      createElement(PreprAbSwitch),
+      hasDecided && createElement(PreprPersonalizationSwitch, { refresh: false })
     ),
     ...blocks.map((block) => {
       if (decidedInProxy(block)) {
@@ -1202,7 +1432,7 @@ function createPreprClient2(options) {
     ...coreOptions
   });
   const seenGroups = /* @__PURE__ */ new Map();
-  return {
+  const nextClient = {
     async query(document2, variables, queryOptions = {}) {
       const { personalize = false, ...rest } = queryOptions;
       const init = rest.init;
@@ -1243,6 +1473,12 @@ function createPreprClient2(options) {
       options2
     )
   };
+  preprClientInternals.set(nextClient, {
+    client,
+    seenGroups,
+    url: coreOptions.url
+  });
+  return nextClient;
 }
 export {
   PREPR_DECISIONS_COOKIE,
@@ -1250,6 +1486,7 @@ export {
   PreprError,
   PreprStack,
   createPreprClient2 as createPreprClient,
+  createPreprProxy,
   decisionsFrom,
   isPersonalizedResponse,
   loadPreprSchema,

package/dist/nextjs/index.cjs

@@ -22,6 +22,7 @@ var nextjs_exports = {};
 __export(nextjs_exports, {
   PREPR_BUCKET_COOKIE: () => PREPR_BUCKET_COOKIE,
   PreprError: () => PreprError,
+  PreprPersonalizationSwitch: () => import_components.PreprPersonalizationSwitch,
   PreprToolbar: () => import_components.PreprToolbar,
   PreprTrackingPixel: () => import_components.PreprTrackingPixel,
   createPreprDraftRoute: () => createPreprDraftRoute,
@@ -43,7 +44,7 @@ module.exports = __toCommonJS(nextjs_exports);
 var import_server = require("next/server");
 
 // src/version.ts
-var VERSION = "0.6.0-alpha.1";
+var VERSION = "0.6.0-alpha.3";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";
@@ -574,6 +575,7 @@ var import_components = require("./components.cjs");
 0 && (module.exports = {
   PREPR_BUCKET_COOKIE,
   PreprError,
+  PreprPersonalizationSwitch,
   PreprToolbar,
   PreprTrackingPixel,
   createPreprDraftRoute,

package/dist/nextjs/index.d.cts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-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';
+import { a as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-BL-sqZvu.cjs';
+export { b as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-BL-sqZvu.cjs';
 
 interface PreprMiddlewareOptions {
     /** Enable preview-mode headers (segment/AB overrides, preview bar). */
@@ -153,5 +153,34 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  * `createPreprPreview` mounts imperatively.
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
+interface PreprPersonalizationSwitchProps {
+    /**
+     * Keep segment decisions fresh in the background. Default `true`. Leave it
+     * on for the instance in your root layout; `PreprStack` renders its own
+     * with `false`.
+     */
+    refresh?: boolean;
+    /** Same as `createPreprProxy`'s `freshFor`. Default 10 000 ms. */
+    freshFor?: number;
+}
+/**
+ * Shows the segment variants decided in the proxy for the groups above the
+ * fold, before the page paints, and keeps those decisions fresh while the
+ * visitor browses: a short while after each page view, when the visitor
+ * points at a link to a personalized page, and when the tab comes back.
+ * Because the next page's decision is already in place when it opens, a
+ * visitor who joins a segment mid-visit sees it on their next page view,
+ * without anything on screen changing.
+ *
+ * Mount it once in the root layout. The background refreshes are answered by
+ * `createPreprProxy`; with a proxy that calls `resolveDecisions` itself, the
+ * first refresh gets a page back and refreshing stops for the browser
+ * session. The decisions themselves come from `createPreprProxy` or
+ * `resolveDecisions` in `proxy.ts`.
+ *
+ * @example
+ * <PreprPersonalizationSwitch />
+ */
+declare function PreprPersonalizationSwitch({ refresh, freshFor, }: PreprPersonalizationSwitchProps): null;
 
-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 };
+export { PREPR_BUCKET_COOKIE, type PreprBucket, type PreprDraftOptions, type PreprMiddlewareOptions, PreprPersonalizationSwitch, type PreprPersonalizationSwitchProps, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type ResolvePreprBucketOptions, createPreprDraftRoute, createPreprMiddleware, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect, resolvePreprBucket };

package/dist/nextjs/index.d.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-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';
+import { a as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-BL-sqZvu.js';
+export { b as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-BL-sqZvu.js';
 
 interface PreprMiddlewareOptions {
     /** Enable preview-mode headers (segment/AB overrides, preview bar). */
@@ -153,5 +153,34 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  * `createPreprPreview` mounts imperatively.
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
+interface PreprPersonalizationSwitchProps {
+    /**
+     * Keep segment decisions fresh in the background. Default `true`. Leave it
+     * on for the instance in your root layout; `PreprStack` renders its own
+     * with `false`.
+     */
+    refresh?: boolean;
+    /** Same as `createPreprProxy`'s `freshFor`. Default 10 000 ms. */
+    freshFor?: number;
+}
+/**
+ * Shows the segment variants decided in the proxy for the groups above the
+ * fold, before the page paints, and keeps those decisions fresh while the
+ * visitor browses: a short while after each page view, when the visitor
+ * points at a link to a personalized page, and when the tab comes back.
+ * Because the next page's decision is already in place when it opens, a
+ * visitor who joins a segment mid-visit sees it on their next page view,
+ * without anything on screen changing.
+ *
+ * Mount it once in the root layout. The background refreshes are answered by
+ * `createPreprProxy`; with a proxy that calls `resolveDecisions` itself, the
+ * first refresh gets a page back and refreshing stops for the browser
+ * session. The decisions themselves come from `createPreprProxy` or
+ * `resolveDecisions` in `proxy.ts`.
+ *
+ * @example
+ * <PreprPersonalizationSwitch />
+ */
+declare function PreprPersonalizationSwitch({ refresh, freshFor, }: PreprPersonalizationSwitchProps): null;
 
-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 };
+export { PREPR_BUCKET_COOKIE, type PreprBucket, type PreprDraftOptions, type PreprMiddlewareOptions, PreprPersonalizationSwitch, type PreprPersonalizationSwitchProps, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type ResolvePreprBucketOptions, createPreprDraftRoute, createPreprMiddleware, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect, resolvePreprBucket };