@preprio/toolkit 0.6.0-alpha.0 → 0.6.0-alpha.10

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 { NextRequest, NextResponse } from 'next/server';
 import { ReactNode, ReactElement } from 'react';
 
 /** Prepr's variant id for visitors outside every targeted segment. */
@@ -9,6 +9,12 @@ declare const PREPR_DEFAULT_VARIANT = "ALL_OTHER_USERS";
 
 /** The variant ids Prepr chose for one visitor, per personalization group. */
 type PreprDecisions = ReadonlyMap<string, readonly string[]>;
+/**
+ * Variant ids per group from a decision response, de-duplicated and in
+ * Prepr's order. A visitor in several segments can get more than one variant
+ * of the same group, so each entry is a list.
+ */
+declare function decisionsFrom(data: unknown): PreprDecisions;
 interface ResolveVariantsOptions {
     /**
      * The visitor's per-group variants (from a decision query). Without it,
@@ -25,6 +31,24 @@ interface ResolveVariantsOptions {
  */
 declare function resolveVariants<T>(data: T, options?: ResolveVariantsOptions): T;
 
+interface FieldInfo {
+    /** Named type of the field, without list/non-null wrappers. */
+    type: string;
+    /** The field accepts Prepr's `personalize` argument (a stack). */
+    personalizable: boolean;
+}
+interface TypeInfo {
+    fields: Record<string, FieldInfo>;
+    /** Members of a union or implementations of an interface. */
+    possibleTypes: string[];
+    hasContext: boolean;
+}
+/** The slice of the schema the variant transforms need. */
+interface PreprSchemaInfo {
+    queryType: string;
+    types: Record<string, TypeInfo>;
+}
+
 /** A run of stack items that renders the same way: see {@link splitStack}. */
 interface PreprStackBlock<T> {
     key: string;
@@ -166,11 +190,6 @@ interface PreprDecideOptions extends Omit<PreprQueryOptions, 'variants'> {
      * none, e.g. on pages with only A/B tests or no personalization.
      */
     from?: unknown;
-    /**
-     * @internal Ask only about the first personalizable list on each path,
-     * without `from`: what middleware needs for groups at the top of a stack.
-     */
-    topLevelOnly?: boolean;
 }
 interface PreprQueryResult<TResult> {
     data: TResult;
@@ -181,40 +200,184 @@ interface PreprQueryResult<TResult> {
     personalized: boolean;
 }
 
-/** The cookie `resolveDecisions` writes and the `PreprStack` switch reads. */
-declare const PREPR_DECISIONS_COOKIE = "prepr_decisions";
+/**
+ * The schema facts the query rewrites need, from `loadPreprSchema`. Pass it
+ * along; its shape is not part of the public API.
+ */
+type PreprSchema = PreprSchemaInfo;
+/**
+ * Your query, asking for every personalization and A/B variant: what
+ * `query(..., { variants: true })` sends, as a string for your own GraphQL
+ * client. The result is the same for every visitor, so cache it like any
+ * other content query, and render it with `resolveVariants` or `PreprStack`.
+ *
+ * A query without personalizable fields comes back unchanged (minified).
+ */
+declare function toVariantsQuery(document: PreprDocument<unknown, unknown> | string, schema: PreprSchema): string;
+/**
+ * The per-visitor decision query for the same query: send it with the
+ * visitor's Prepr headers, never cached, and pass the response's `data` to
+ * `decisionsFrom`.
+ *
+ * Pass the variants result as `from` whenever you have it: the query then
+ * asks only about the lists that hold segment groups on this page, which is
+ * a few hundred bytes instead of the whole page and markedly faster for a
+ * visitor Prepr has not seen before. Without `from` it asks about every
+ * personalizable list. `topLevelOnly` stops at the first personalizable list
+ * on each path, for middleware that decides only the top of a stack.
+ *
+ * Null when there is nothing to decide: send no request then.
+ */
+declare function toDecisionQuery(document: PreprDocument<unknown, unknown> | string, schema: PreprSchema, options?: {
+    from?: unknown;
+    topLevelOnly?: boolean;
+}): string | null;
+
+/**
+ * Tag for pages showing more items than fit in Next.js's tag limits. Every
+ * webhook event revalidates it, so those pages refresh on any change.
+ */
+declare const PREPR_ANY_ITEM_TAG = "prepr:any";
+/**
+ * Cache tag for every page listing items of one model. `tagItems` adds it to
+ * list queries and to lookups that found nothing; add it yourself with
+ * `cacheTag()` for other pages that depend on which items exist.
+ * `createPreprWebhookRoute` revalidates it when an item of that model is
+ * published, unpublished or deleted.
+ *
+ * The name is compared case-insensitively and without spaces or
+ * punctuation, so the model's name in Prepr (`'Blog post'`, as webhooks send
+ * it) and its GraphQL type (`BlogPost`) give the same tag. A model whose API
+ * ID was renamed away from its name gets two different tags.
+ *
+ * @param model The model's singular name in Prepr or its GraphQL type name.
+ */
+declare const preprModelTag: (model: string) => string;
+/**
+ * Cache tags for every Prepr item in a query result: `prepr:<_id>` for each
+ * object with a string `_id`, at any depth. Pair it with `cacheTag()` inside
+ * `'use cache'`, and a publish webhook revalidates only the pages that show
+ * the changed item. Run the query with `variants: true` so the tags cover
+ * every variant's items, not only those of one visitor.
+ *
+ * Next.js accepts at most 128 tags of 256 characters per `cacheTag()` call.
+ * A result past either limit returns `[PREPR_ANY_ITEM_TAG]` instead, which
+ * every webhook event revalidates.
+ *
+ * @param data A parsed JSON query result, such as `query()`'s `data`.
+ */
+declare function preprCacheTags(data: unknown): string[];
+
+/**
+ * Loads what `toVariantsQuery` and `toDecisionQuery` need to know about your
+ * Prepr schema (which fields take `personalize`, which types can hold
+ * variants) with one introspection request, kept in memory per URL. For a
+ * site that uses its own GraphQL client; `createPreprClient` does this
+ * itself.
+ *
+ * Load it once at startup or lazily before the first rewrite. Schema changes
+ * in Prepr take effect after a restart or redeploy.
+ *
+ * @throws PreprError when the URL is invalid or the request fails; the URL,
+ *   which holds your access token, is never part of the message.
+ */
+declare function loadPreprSchema(url: string, options?: {
+    fetch?: typeof fetch;
+}): Promise<PreprSchemaInfo>;
+
+/** The query a page renders, as `createPreprProxy`'s `page` returns it. */
+interface PreprProxyPage<TVariables = unknown> {
+    document: PreprDocument<unknown, TVariables>;
+    variables?: TVariables;
+    /**
+     * The decision query for `document`, built ahead of time (the codegen
+     * plugin's `<Name>DecisionQuery`). Sent as is, so the proxy never loads
+     * Prepr's schema to derive it; see `resolveDecisions`.
+     */
+    decision?: PreprDocument<unknown, 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;
+    /**
+     * Give up on Prepr after this many ms; the default variants show. A page
+     * load the proxy decides waits for this at most. Default 1000.
+     */
+    timeoutMs?: number;
+    /**
+     * Skip Prepr for decision requests when this resolves to false, for example for
+     * crawlers, so they never wait 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, and the answers to the browser's decision requests.
+ *
+ * A page load the visitor has no recent decision for is decided here, in one
+ * Prepr request for every A/B test and personalization group on the page,
+ * at most `timeoutMs`; the decision goes to the browser in a cookie, so the
+ * personalized sections paint with the visitor's variant. Every other page
+ * load passes straight through: the cookie already holds its decision, or
+ * the page has no personalization. The proxy also answers the decision
+ * requests the browser sends when a visitor points at a link, as text and no
+ * 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`. */
     items: readonly T[];
-    /**
-     * The visitor's decisions, as a promise from `decide()`. Only the parts
-     * that vary per segment wait for it; a failed decision falls back to the
-     * default variants instead of failing the page.
-     */
-    decisions: Promise<PreprDecisions>;
     /**
      * Renders resolved stack items, e.g. your section switch. `index` is the
      * position of the block's first item in the whole stack, for anything that
      * depends on page position, such as which section owns the h1 or the
      * priority image.
      *
-     * `placeholder` is true while this render only stands in for the visitor's
-     * 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 segment variants. 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
-     * from a URL segment). Leave it out to render both variants of each A/B
-     * test and pick the visitor's in the browser before first paint.
+     * from a URL segment): A/B tests then render that bucket only. Leave it out
+     * to render both variants, and let this page view's decision pick the
+     * visitor's, like a segment group's.
      */
     bucket?: string;
-    /** Nonce for the inline A/B switch script, under a strict CSP. */
+    /** Nonce for the inline scripts, under a strict CSP. */
     nonce?: string;
     /**
      * Tag each personalization and A/B variant for Prepr's tracking pixel, so
@@ -225,46 +388,37 @@ interface PreprStackProps<T> {
      * Each item's key goes on the element `render` returns for it, in order,
      * once the page has hydrated. Each variant gets a wrapper with
      * `display: contents`: it takes no box, but CSS child combinators (`>`) and
-     * `:first-child` from the stack's parent no longer reach the sections. Lists
-     * nested inside an item are not tagged; use `preprVariantProps` there.
+     * `:first-child` from the stack's parent no longer reach the sections. A
+     * section holding a personalized list gets the key of the variant it shows.
+     * Only the shown variant is tagged, once it shows: the pixel counts any
+     * tagged element in view, invisible or not.
      */
     trackVariants?: boolean;
-    /**
-     * How many blocks, from the top, are on screen before the visitor scrolls.
-     * Default `0`.
-     *
-     * 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.
-     */
-    aboveTheFold?: number;
 }
 /**
- * Renders a personalized stack with Cache Components / Partial Prerendering.
+ * Renders a personalized stack, entirely in the prerendered page.
  *
- * - Items that never vary render in the static shell.
- * - A/B tests render in the static shell too, once per bucket; a tiny inline
- *   script shows the visitor's bucket (from `resolvePreprBucket`'s cookie)
- *   before first paint, so no variant streams or swaps in. `A` is the
- *   default. Pass `bucket` instead when the route already knows it.
- * - Each segment-personalized group, and each item with segment content
- *   nested inside it, gets its own `<Suspense>` boundary: the default
- *   variant (possibly empty) is the fallback, and this visitor's variant
- *   streams in once `decisions` resolves. Because `items` holds every
- *   variant, a group with no default variant still gets its place.
+ * - Items that never vary render as they are.
+ * - Every A/B test and segment personalization group, at the top of the
+ *   stack or nested inside an item, renders every variant, hidden. The page
+ *   is the same for every visitor and never waits for Prepr: an inline script
+ *   asks `createPreprProxy` for this page view's decision while the page
+ *   loads, and shows the visitor's variant when it answers.
+ *   `PreprPersonalizationSwitch` asks for a link's decision on hover, so it
+ *   is mostly in before the next page paints. Nothing streams, and the
+ *   default variant never shows first to be replaced.
+ *
+ * The page carries the HTML of every variant: an item with nested groups
+ * repeats once per combination of their variants.
  *
  * @example
  * const data = await getPage(slug); // 'use cache' + query(..., { variants: true })
  * <PreprStack
  *   items={data.Page.content}
- *   decisions={prepr.decide(PageDocument, { slug }, { from: data })}
  *   render={(items, { index }) => <Sections sections={items} offset={index} />}
  * />
  */
-declare function PreprStack<T>({ items, decisions, render, bucket, nonce, trackVariants, aboveTheFold, }: PreprStackProps<T>): ReactElement;
+declare function PreprStack<T>({ items, render, bucket, nonce, trackVariants, }: PreprStackProps<T>): ReactElement;
 
 interface PreprNextClientOptions extends PreprClientOptions {
     /** Tags set on every cacheable fetch, for `revalidateTag`. Default `['prepr']`. */
@@ -282,6 +436,21 @@ interface PreprNextQueryOptions extends PreprQueryOptions {
      * skip the Data Cache. The route renders per request.
      */
     personalize?: boolean;
+    /**
+     * Inside `'use cache'` (Cache Components, Next 16+): tags the cache entry
+     * with `preprCacheTags(data)` and the client's `cacheTags`, so
+     * `createPreprWebhookRoute` revalidates exactly the pages showing a changed
+     * item. List queries and lookups that found nothing also get their
+     * model's `preprModelTag`, so publishing a new item refreshes them. Pair it
+     * with `variants: true`, whose result holds every variant's items.
+     *
+     * The fetch then skips the Data Cache: a Data Cache entry carries only the
+     * client's `cacheTags`, so revalidating an item tag would re-run the
+     * `'use cache'` function against the stale response.
+     *
+     * @throws Error — from Next.js when called outside a `'use cache'` function.
+     */
+    tagItems?: boolean;
 }
 interface PreprNextClient {
     /**
@@ -303,42 +472,15 @@ interface PreprNextClient {
      * from everything the middleware forwards: customer profile, UTM
      * parameters, visitor IP, HubSpot id.
      *
-     * Start it without awaiting and hand the promise to `PreprStack`: only the
-     * parts that vary per visitor wait for it.
+     * For rendering variants yourself with `resolveVariants`. `PreprStack`
+     * does not need it: `createPreprProxy` decides every page view.
      */
     decide<TVariables>(document: PreprDocument<unknown, TVariables>, variables?: TVariables, options?: PreprDecideOptions): Promise<PreprDecisions>;
     /**
-     * Whether the query's result holds an A/B test: see `resolvePreprBucket`'s
-     * `onlyIf`. Never reads request headers, so it also works in middleware.
+     * Whether the query's result holds an A/B test. Never reads request
+     * headers, so it also works in middleware.
      */
     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.
-     *
-     * 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.
-     */
-    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>;
 }
 /**
  * Prepr GraphQL client for Next.js (App Router, server only).
@@ -358,4 +500,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, PreprStack, type PreprStackBlock, type PreprStackProps, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, preprVariantProps, resolveVariants, splitStack };
+export { PREPR_ANY_ITEM_TAG, 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 ResolveVariantsOptions, createPreprClient, createPreprProxy, decisionsFrom, loadPreprSchema, preprCacheTags, preprModelTag, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };