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

package/dist/nextjs/graphql.d.cts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { DocumentNode } from 'graphql';
-import { P as PreprHeaders } from './server-CjpELYvq.cjs';
-export { a as PreprError, i as isPersonalizedResponse } from './server-CjpELYvq.cjs';
+import { P as PreprHeaders, a as PreprFeatures } from './server-BL-sqZvu.cjs';
+export { b as PreprError, i as isPersonalizedResponse } from './server-BL-sqZvu.cjs';
 import { ReactNode, ReactElement } from 'react';
 
 /** Prepr's variant id for visitors outside every targeted segment. */
@@ -257,6 +257,74 @@ declare function loadPreprSchema(url: string, options?: {
 
 /** The cookie `resolveDecisions` writes and the `PreprStack` switch reads. */
 declare const PREPR_DECISIONS_COOKIE = "prepr_decisions";
+interface ResolveDecisionsOptions {
+    /** Give up after this many ms; the default variant shows. Default 1000. */
+    timeoutMs?: number;
+    /**
+     * Keep the stored decision for this many ms instead of asking Prepr again.
+     * Default 10 000; `0` asks on every request. Background refreshes by
+     * `PreprPersonalizationSwitch` keep it fresh, so a page view rarely waits.
+     */
+    freshFor?: number;
+    /** Skip the decision when this resolves to false. */
+    onlyIf?: () => boolean | Promise<boolean>;
+}
+
+/** The query a page renders, as `createPreprProxy`'s `page` returns it. */
+interface PreprProxyPage<TVariables = unknown> {
+    document: PreprDocument<unknown, TVariables>;
+    variables?: TVariables;
+}
+interface PreprProxyOptions {
+    /** A client made with this package's Next `createPreprClient`. */
+    client: PreprNextClient;
+    /**
+     * The query the page at `url` renders with `variants: true`, or `null` for
+     * a URL that is not a CMS page. Sites that route every page through one
+     * query need one line:
+     * `(url) => ({ document: PageDocument, variables: { slug: url.pathname } })`.
+     */
+    page: (url: URL) => PreprProxyPage<any> | null | undefined;
+    /** Whether this deployment serves preview content (draft mode, toolbar overrides). */
+    preview?: boolean;
+    /** Features disabled app-wide, as for `createPreprMiddleware`. */
+    features?: PreprFeatures;
+    /** See `resolveDecisions`. Default 10 000 ms. */
+    freshFor?: number;
+    /** Give up on Prepr after this many ms; the default variant shows. Default 1000. */
+    timeoutMs?: number;
+    /**
+     * Skip the A/B bucket lookup and segment decisions (page requests and
+     * refreshes) when this resolves to false, for example for crawlers: they
+     * carry no cookies, so every crawler request is a first visit that waits
+     * for Prepr. Those requests get the default variants.
+     */
+    onlyIf?: (request: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Everything Prepr needs in the proxy (`proxy.ts`), in one call: the visitor's
+ * Prepr headers and customer id (`createPreprMiddleware`), the draft-mode
+ * redirect in preview, the A/B bucket, and the segment variants of the groups
+ * at the top of each page, so `PreprStack` shows them before first paint.
+ *
+ * It also answers the background refreshes `PreprPersonalizationSwitch`
+ * sends: those return `204` with fresh decision cookies and never render a
+ * page. Add your own cookies or headers to the response it returns.
+ *
+ * @example
+ * const handlePrepr = createPreprProxy({
+ *   client: prepr,
+ *   page: (url) => ({ document: PageDocument, variables: { slug: url.pathname } }),
+ *   preview: process.env.PREPR_ENV === 'preview',
+ * });
+ * export function proxy(request: NextRequest) {
+ *   return handlePrepr(request);
+ * }
+ *
+ * @throws PreprError `CONTEXT_ERROR` when `client` was not made by the Next
+ *   `createPreprClient`.
+ */
+declare function createPreprProxy(options: PreprProxyOptions): (request: NextRequest) => Promise<NextResponse>;
 
 interface PreprStackProps<T> {
     /** A stack (e.g. `page.content`) from a query run with `variants: true`. */
@@ -277,10 +345,17 @@ interface PreprStackProps<T> {
      * variant of a segment group (the default variant, shown until the
      * decision streams in). Leave `data-prepr-variant-key` off it: the tracking
      * pixel would count an impression of a variant the visitor may never get.
+     *
+     * `defaultVariant` is false for the variants that are in the page but
+     * hidden unless the visitor gets them: the other buckets of an A/B test and
+     * the other segment variants above the fold. Give only the default variant
+     * `priority` images, and the others `loading="lazy"`: the browser downloads
+     * a hidden eager image anyway, but skips a hidden lazy one.
      */
     render: (items: T[], position: {
         index: number;
         placeholder: boolean;
+        defaultVariant: boolean;
     }) => ReactNode;
     /**
      * The visitor's A/B bucket, when the route already knows it (for example
@@ -305,14 +380,17 @@ interface PreprStackProps<T> {
     trackVariants?: boolean;
     /**
      * How many blocks, from the top, are on screen before the visitor scrolls.
-     * Default `0`.
+     * Default `1`; set it higher when more sections fit on the first screen
+     * (take the larger screen when it differs per device), or `0` to stream
+     * every segment group.
      *
      * Their segment groups do not stream: every variant is in the cached page,
      * and the variant the proxy decided (`prepr.resolveDecisions`) shows before
      * first paint, so nothing on screen changes while the page loads. Without
      * a decision (no cookie yet, or the proxy's lookup failed) the default
-     * variant shows. Costs the HTML of the other variants; images in them still
-     * download. An item with a segment group nested inside it keeps streaming.
+     * variant shows. Costs the HTML of the other variants; see `defaultVariant`
+     * in `render` to keep their images from downloading. An item with a
+     * segment group nested inside it keeps streaming.
      */
     aboveTheFold?: number;
 }
@@ -388,31 +466,20 @@ interface PreprNextClient {
     hasAbTests<TVariables>(document: PreprDocument<unknown, TVariables>, variables?: TVariables): Promise<boolean>;
     /**
      * In middleware (`proxy.ts`): asks Prepr which segment variant this visitor
-     * gets for each personalization group on the page, and stores the answer in
-     * the `prepr_decisions` cookie on `response`. `PreprStack` with
-     * `aboveTheFold` then shows those variants before first paint instead of
-     * streaming them in.
+     * gets for each personalization group at the top of the page, and stores
+     * the answer in the `prepr_decisions` cookie on `response`. `PreprStack`
+     * then shows those variants before first paint instead of streaming them
+     * in. `createPreprProxy` calls this for you.
      *
      * Call it after `createPreprMiddleware`, whose visitor headers (customer id,
-     * UTM parameters, IP, HubSpot id) it forwards. A decision is an uncached
-     * Prepr request, made once per visit by default (see `reuse`); limit it
-     * with `onlyIf` to pages whose personalized content is above the fold.
-     * Pages without segment groups are skipped after a cached check. Never throws and gives up after `timeoutMs`
-     * (default 1000): the default variant shows instead.
+     * UTM parameters, IP, HubSpot id) it forwards. A stored decision that
+     * covers the page is kept for `freshFor` (default 10 s); a first visit, UTM
+     * parameters and a segment forced in preview always ask again. Pages
+     * without segment groups at the top are skipped after a cached check.
+     * Never throws and gives up after `timeoutMs` (default 1000): the default
+     * variant shows instead.
      */
-    resolveDecisions<TVariables>(request: NextRequest, response: NextResponse, document: PreprDocument<unknown, TVariables>, variables?: TVariables, options?: {
-        timeoutMs?: number;
-        /**
-         * Reuse the stored decision for the rest of the visit instead of asking
-         * Prepr on every page view. Default `true`. Asks again when UTM
-         * parameters arrive, on a first visit, and when preview forces a
-         * segment. A visitor who joins a segment mid-visit (say, by submitting
-         * a form) sees the change from their next asked request.
-         */
-        reuse?: boolean;
-        /** Skip the decision when this resolves to false, e.g. for pages without a personalized hero. */
-        onlyIf?: () => boolean | Promise<boolean>;
-    }): Promise<void>;
+    resolveDecisions<TVariables>(request: NextRequest, response: NextResponse, document: PreprDocument<unknown, TVariables>, variables?: TVariables, options?: ResolveDecisionsOptions): Promise<void>;
 }
 /**
  * Prepr GraphQL client for Next.js (App Router, server only).
@@ -432,4 +499,4 @@ interface PreprNextClient {
  */
 declare function createPreprClient(options: PreprNextClientOptions): PreprNextClient;
 
-export { PREPR_DECISIONS_COOKIE, PREPR_DEFAULT_VARIANT, type PreprDecideOptions, type PreprDecisions, type PreprDocument, type PreprNextClient, type PreprNextClientOptions, type PreprNextQueryOptions, type PreprQueryResult, type PreprSchema, PreprStack, type PreprStackBlock, type PreprStackProps, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };
+export { PREPR_DECISIONS_COOKIE, PREPR_DEFAULT_VARIANT, type PreprDecideOptions, type PreprDecisions, type PreprDocument, type PreprNextClient, type PreprNextClientOptions, type PreprNextQueryOptions, type PreprProxyOptions, type PreprProxyPage, type PreprQueryResult, type PreprSchema, PreprStack, type PreprStackBlock, type PreprStackProps, type PreprStegaMode, type PreprVariantProps, type ResolveDecisionsOptions, type ResolveVariantsOptions, createPreprClient, createPreprProxy, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };

package/dist/nextjs/graphql.d.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { DocumentNode } from 'graphql';
-import { P as PreprHeaders } from './server-CjpELYvq.js';
-export { a as PreprError, i as isPersonalizedResponse } from './server-CjpELYvq.js';
+import { P as PreprHeaders, a as PreprFeatures } from './server-BL-sqZvu.js';
+export { b as PreprError, i as isPersonalizedResponse } from './server-BL-sqZvu.js';
 import { ReactNode, ReactElement } from 'react';
 
 /** Prepr's variant id for visitors outside every targeted segment. */
@@ -257,6 +257,74 @@ declare function loadPreprSchema(url: string, options?: {
 
 /** The cookie `resolveDecisions` writes and the `PreprStack` switch reads. */
 declare const PREPR_DECISIONS_COOKIE = "prepr_decisions";
+interface ResolveDecisionsOptions {
+    /** Give up after this many ms; the default variant shows. Default 1000. */
+    timeoutMs?: number;
+    /**
+     * Keep the stored decision for this many ms instead of asking Prepr again.
+     * Default 10 000; `0` asks on every request. Background refreshes by
+     * `PreprPersonalizationSwitch` keep it fresh, so a page view rarely waits.
+     */
+    freshFor?: number;
+    /** Skip the decision when this resolves to false. */
+    onlyIf?: () => boolean | Promise<boolean>;
+}
+
+/** The query a page renders, as `createPreprProxy`'s `page` returns it. */
+interface PreprProxyPage<TVariables = unknown> {
+    document: PreprDocument<unknown, TVariables>;
+    variables?: TVariables;
+}
+interface PreprProxyOptions {
+    /** A client made with this package's Next `createPreprClient`. */
+    client: PreprNextClient;
+    /**
+     * The query the page at `url` renders with `variants: true`, or `null` for
+     * a URL that is not a CMS page. Sites that route every page through one
+     * query need one line:
+     * `(url) => ({ document: PageDocument, variables: { slug: url.pathname } })`.
+     */
+    page: (url: URL) => PreprProxyPage<any> | null | undefined;
+    /** Whether this deployment serves preview content (draft mode, toolbar overrides). */
+    preview?: boolean;
+    /** Features disabled app-wide, as for `createPreprMiddleware`. */
+    features?: PreprFeatures;
+    /** See `resolveDecisions`. Default 10 000 ms. */
+    freshFor?: number;
+    /** Give up on Prepr after this many ms; the default variant shows. Default 1000. */
+    timeoutMs?: number;
+    /**
+     * Skip the A/B bucket lookup and segment decisions (page requests and
+     * refreshes) when this resolves to false, for example for crawlers: they
+     * carry no cookies, so every crawler request is a first visit that waits
+     * for Prepr. Those requests get the default variants.
+     */
+    onlyIf?: (request: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Everything Prepr needs in the proxy (`proxy.ts`), in one call: the visitor's
+ * Prepr headers and customer id (`createPreprMiddleware`), the draft-mode
+ * redirect in preview, the A/B bucket, and the segment variants of the groups
+ * at the top of each page, so `PreprStack` shows them before first paint.
+ *
+ * It also answers the background refreshes `PreprPersonalizationSwitch`
+ * sends: those return `204` with fresh decision cookies and never render a
+ * page. Add your own cookies or headers to the response it returns.
+ *
+ * @example
+ * const handlePrepr = createPreprProxy({
+ *   client: prepr,
+ *   page: (url) => ({ document: PageDocument, variables: { slug: url.pathname } }),
+ *   preview: process.env.PREPR_ENV === 'preview',
+ * });
+ * export function proxy(request: NextRequest) {
+ *   return handlePrepr(request);
+ * }
+ *
+ * @throws PreprError `CONTEXT_ERROR` when `client` was not made by the Next
+ *   `createPreprClient`.
+ */
+declare function createPreprProxy(options: PreprProxyOptions): (request: NextRequest) => Promise<NextResponse>;
 
 interface PreprStackProps<T> {
     /** A stack (e.g. `page.content`) from a query run with `variants: true`. */
@@ -277,10 +345,17 @@ interface PreprStackProps<T> {
      * variant of a segment group (the default variant, shown until the
      * decision streams in). Leave `data-prepr-variant-key` off it: the tracking
      * pixel would count an impression of a variant the visitor may never get.
+     *
+     * `defaultVariant` is false for the variants that are in the page but
+     * hidden unless the visitor gets them: the other buckets of an A/B test and
+     * the other segment variants above the fold. Give only the default variant
+     * `priority` images, and the others `loading="lazy"`: the browser downloads
+     * a hidden eager image anyway, but skips a hidden lazy one.
      */
     render: (items: T[], position: {
         index: number;
         placeholder: boolean;
+        defaultVariant: boolean;
     }) => ReactNode;
     /**
      * The visitor's A/B bucket, when the route already knows it (for example
@@ -305,14 +380,17 @@ interface PreprStackProps<T> {
     trackVariants?: boolean;
     /**
      * How many blocks, from the top, are on screen before the visitor scrolls.
-     * Default `0`.
+     * Default `1`; set it higher when more sections fit on the first screen
+     * (take the larger screen when it differs per device), or `0` to stream
+     * every segment group.
      *
      * Their segment groups do not stream: every variant is in the cached page,
      * and the variant the proxy decided (`prepr.resolveDecisions`) shows before
      * first paint, so nothing on screen changes while the page loads. Without
      * a decision (no cookie yet, or the proxy's lookup failed) the default
-     * variant shows. Costs the HTML of the other variants; images in them still
-     * download. An item with a segment group nested inside it keeps streaming.
+     * variant shows. Costs the HTML of the other variants; see `defaultVariant`
+     * in `render` to keep their images from downloading. An item with a
+     * segment group nested inside it keeps streaming.
      */
     aboveTheFold?: number;
 }
@@ -388,31 +466,20 @@ interface PreprNextClient {
     hasAbTests<TVariables>(document: PreprDocument<unknown, TVariables>, variables?: TVariables): Promise<boolean>;
     /**
      * In middleware (`proxy.ts`): asks Prepr which segment variant this visitor
-     * gets for each personalization group on the page, and stores the answer in
-     * the `prepr_decisions` cookie on `response`. `PreprStack` with
-     * `aboveTheFold` then shows those variants before first paint instead of
-     * streaming them in.
+     * gets for each personalization group at the top of the page, and stores
+     * the answer in the `prepr_decisions` cookie on `response`. `PreprStack`
+     * then shows those variants before first paint instead of streaming them
+     * in. `createPreprProxy` calls this for you.
      *
      * Call it after `createPreprMiddleware`, whose visitor headers (customer id,
-     * UTM parameters, IP, HubSpot id) it forwards. A decision is an uncached
-     * Prepr request, made once per visit by default (see `reuse`); limit it
-     * with `onlyIf` to pages whose personalized content is above the fold.
-     * Pages without segment groups are skipped after a cached check. Never throws and gives up after `timeoutMs`
-     * (default 1000): the default variant shows instead.
+     * UTM parameters, IP, HubSpot id) it forwards. A stored decision that
+     * covers the page is kept for `freshFor` (default 10 s); a first visit, UTM
+     * parameters and a segment forced in preview always ask again. Pages
+     * without segment groups at the top are skipped after a cached check.
+     * Never throws and gives up after `timeoutMs` (default 1000): the default
+     * variant shows instead.
      */
-    resolveDecisions<TVariables>(request: NextRequest, response: NextResponse, document: PreprDocument<unknown, TVariables>, variables?: TVariables, options?: {
-        timeoutMs?: number;
-        /**
-         * Reuse the stored decision for the rest of the visit instead of asking
-         * Prepr on every page view. Default `true`. Asks again when UTM
-         * parameters arrive, on a first visit, and when preview forces a
-         * segment. A visitor who joins a segment mid-visit (say, by submitting
-         * a form) sees the change from their next asked request.
-         */
-        reuse?: boolean;
-        /** Skip the decision when this resolves to false, e.g. for pages without a personalized hero. */
-        onlyIf?: () => boolean | Promise<boolean>;
-    }): Promise<void>;
+    resolveDecisions<TVariables>(request: NextRequest, response: NextResponse, document: PreprDocument<unknown, TVariables>, variables?: TVariables, options?: ResolveDecisionsOptions): Promise<void>;
 }
 /**
  * Prepr GraphQL client for Next.js (App Router, server only).
@@ -432,4 +499,4 @@ interface PreprNextClient {
  */
 declare function createPreprClient(options: PreprNextClientOptions): PreprNextClient;
 
-export { PREPR_DECISIONS_COOKIE, PREPR_DEFAULT_VARIANT, type PreprDecideOptions, type PreprDecisions, type PreprDocument, type PreprNextClient, type PreprNextClientOptions, type PreprNextQueryOptions, type PreprQueryResult, type PreprSchema, PreprStack, type PreprStackBlock, type PreprStackProps, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };
+export { PREPR_DECISIONS_COOKIE, PREPR_DEFAULT_VARIANT, type PreprDecideOptions, type PreprDecisions, type PreprDocument, type PreprNextClient, type PreprNextClientOptions, type PreprNextQueryOptions, type PreprProxyOptions, type PreprProxyPage, type PreprQueryResult, type PreprSchema, PreprStack, type PreprStackBlock, type PreprStackProps, type PreprStegaMode, type PreprVariantProps, type ResolveDecisionsOptions, type ResolveVariantsOptions, createPreprClient, createPreprProxy, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };