@preprio/toolkit 0.6.0-alpha.5 → 0.6.0-alpha.7

package/dist/nextjs/graphql.d.ts

@@ -1,7 +1,7 @@
-import { NextRequest, NextResponse } from 'next/server';
 import { DocumentNode } from 'graphql';
 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. */
@@ -97,39 +97,6 @@ interface PreprVariantProps {
  */
 declare function preprVariantProps(item: unknown): PreprVariantProps;
 
-/**
- * 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;
-
 /**
  * A GraphQL document accepted by `query`: a plain string, graphql-codegen's
  * `TypedDocumentString` (`documentMode: 'string'`), or any `DocumentNode`,
@@ -223,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;
@@ -238,6 +200,74 @@ interface PreprQueryResult<TResult> {
     personalized: boolean;
 }
 
+/**
+ * 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
@@ -255,25 +285,16 @@ declare function loadPreprSchema(url: string, options?: {
     fetch?: typeof fetch;
 }): Promise<PreprSchemaInfo>;
 
-/** 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;
+    /**
+     * 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`. */
@@ -289,27 +310,26 @@ interface PreprProxyOptions {
     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. */
+    /** Give up on Prepr after this many ms; the default variants show. Default 3000. */
     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.
+     * 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, the A/B bucket, and the segment variants of the groups
- * at the top of each page, so `PreprStack` shows them before first paint.
+ * redirect in preview, and the answers to the browser's decision requests.
  *
- * 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.
+ * Pages themselves never wait for Prepr: they are the same for every visitor
+ * and pass straight through. The browser sends a decision request for each
+ * page view, from the page load and when a visitor presses a link; the proxy
+ * answers it with the visitor's variant of every A/B test and personalization
+ * group on that page, asked from Prepr in one request, as text and no page.
+ * Add your own cookies or headers to the response it returns.
  *
  * @example
  * const handlePrepr = createPreprProxy({
@@ -329,41 +349,30 @@ declare function createPreprProxy(options: PreprProxyOptions): (request: NextReq
 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 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.
+     * 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
@@ -374,49 +383,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 `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; see `defaultVariant`
-     * in `render` to keep their images from downloading. 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 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. A click's
+ *   decision (requested by `PreprPersonalizationSwitch`) is in before the
+ *   next page paints. Nothing streams, and the default variant never shows
+ *   first to be replaced.
  *
- * - 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.
+ * 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']`. */
@@ -434,6 +431,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 {
     /**
@@ -455,31 +467,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 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 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?: ResolveDecisionsOptions): Promise<void>;
 }
 /**
  * Prepr GraphQL client for Next.js (App Router, server only).
@@ -499,4 +495,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 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 };
+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 };