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

package/dist/nextjs/graphql.d.cts

@@ -0,0 +1,361 @@
+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 { ReactNode, ReactElement } from 'react';
+
+/** Prepr's variant id for visitors outside every targeted segment. */
+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[]>;
+interface ResolveVariantsOptions {
+    /**
+     * The visitor's per-group variants (from a decision query). Without it,
+     * personalization groups show their default variant.
+     */
+    decisions?: PreprDecisions;
+    /** The visitor's A/B bucket. Without it, A/B groups use the decision, then `A`. */
+    bucket?: string;
+}
+/**
+ * Keeps, in every list of a variants query result, only the variants this
+ * visitor gets, at any depth (page stacks, nested stacks, personalized
+ * buttons). Items outside a group are kept as they are.
+ */
+declare function resolveVariants<T>(data: T, options?: ResolveVariantsOptions): T;
+
+/** A run of stack items that renders the same way: see {@link splitStack}. */
+interface PreprStackBlock<T> {
+    key: string;
+    items: T[];
+    /**
+     * Rendered position of the block's first item: a group (whichever variant
+     * shows) takes one position, any other item one each. Use it for anything
+     * that depends on page position, like which section owns the h1.
+     */
+    index: number;
+    /**
+     * Some item in the block (or nested inside one) is a segment variant, so
+     * the block depends on the visitor and is decided per request.
+     */
+    personalized: boolean;
+    /**
+     * Some item in the block (or nested inside one) is an A/B variant. Without
+     * a known bucket, such a block renders once per bucket and the visitor's
+     * bucket is picked in the browser before first paint.
+     */
+    abTest: boolean;
+}
+/**
+ * Splits a variants-query stack into blocks. Each personalization or A/B
+ * group becomes one block (a variant can hold a different number of items
+ * than the default); consecutive items that never vary are merged.
+ */
+declare function splitStack<T>(items: readonly T[]): PreprStackBlock<T>[];
+
+/** The attribute Prepr's tracking pixel reads impressions and conversions from. */
+interface PreprVariantProps {
+    'data-prepr-variant-key'?: string;
+}
+/**
+ * Attributes that let Prepr's tracking pixel count impressions of this item's
+ * variant, for an item from a query run with `variants: true`. Spread them on
+ * the element that shows the item; an item outside any personalization or A/B
+ * group gets none.
+ *
+ * Items rendered by the Next.js `PreprStack` are tagged for you. Reach for this
+ * for items nested inside them (cards, buttons, models in a section) and in
+ * frameworks without `PreprStack`.
+ *
+ * @example
+ * <article {...preprVariantProps(card)}>…</article>
+ */
+declare function preprVariantProps(item: unknown): PreprVariantProps;
+
+/**
+ * A GraphQL document accepted by `query`: a plain string, graphql-codegen's
+ * `TypedDocumentString` (`documentMode: 'string'`), or any `DocumentNode`,
+ * including codegen's default `TypedDocumentNode` output.
+ *
+ * The phantom `__apiType` field is how codegen attaches result and variable
+ * types; matching it structurally keeps `@graphql-typed-document-node/core`
+ * out of this package.
+ */
+type PreprDocument<TResult, TVariables> = string | ({
+    __apiType?: (variables: TVariables) => TResult;
+} & (String | DocumentNode));
+/**
+ * How stega markers are stripped from the response:
+ * - `'urls'`: only from values under URL-like keys (`url`, `slug`, `link`,
+ *   `href`), where markers break links. Text keeps its markers for
+ *   click-to-edit.
+ * - `'all'`: from every string.
+ * - `'none'`: never.
+ */
+type PreprStegaMode = 'urls' | 'all' | 'none';
+interface PreprClientOptions {
+    /** Full Prepr GraphQL URL, `https://graphql.prepr.io/<token>`. */
+    url: string;
+    /**
+     * Fetch implementation. Defaults to the global `fetch`, read at call time so
+     * framework-patched versions (such as Next.js's) are used.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Preview mode: every query skips the HTTP cache so editors see each edit,
+     * and stega defaults to `'urls'` so click-to-edit keeps working.
+     */
+    preview?: boolean;
+    /** Default: `'urls'` when `preview` is true, otherwise `'all'`. */
+    stega?: PreprStegaMode;
+    /**
+     * Send queries as a GET with the request body base64-encoded in a
+     * `Fastly-Query` header, which Prepr's edge serves from the nearest point
+     * of presence (about half the latency of a POST in our measurements).
+     * Queries too large for a header still go as a POST. Off by default: it
+     * relies on Prepr edge behavior that is not part of the documented API.
+     */
+    fastlyQuery?: boolean;
+    /**
+     * @internal Fetch options for the one-time schema introspection, so a
+     * framework wrapper can put it in its data cache.
+     */
+    schemaInit?: RequestInit;
+    /**
+     * Headers sent with every request, such as a header a proxy in front of the
+     * API requires. They are fixed when the client is created, so they cannot
+     * vary per visitor and do not stop responses from being cached. Put
+     * per-request values in the query's `headers` instead.
+     */
+    headers?: HeadersInit;
+}
+interface PreprQueryOptions {
+    /**
+     * Prepr headers to forward, typically from `getPreprHeaders`. Passing any
+     * headers object, even an empty one, makes the request `no-store`: the
+     * response may be personalized and must not be shared between visitors.
+     */
+    headers?: PreprHeaders | HeadersInit;
+    /**
+     * Extra fetch options such as `signal`. `method` and `body` are set by the
+     * client. `init.headers` are merged like `headers`, and also make the
+     * request `no-store`.
+     */
+    init?: RequestInit;
+    /** Per-query fetch, overriding the client's (e.g. SvelteKit's `event.fetch`). */
+    fetch?: typeof fetch;
+    /**
+     * Fetch every variant instead of the visitor's: `personalize: false` is
+     * added to every personalizable field in the query, at any depth, and each
+     * item gets its `_context` (under `_preprContext`). The result is the same
+     * for every visitor, so it can be cached; pass it to `resolveVariants` with
+     * the visitor's `decide()` result to get what they see.
+     *
+     * The client learns which fields are personalizable from one schema
+     * introspection request, made on first use.
+     */
+    variants?: boolean;
+}
+/** Options for `decide()`. */
+interface PreprDecideOptions extends Omit<PreprQueryOptions, 'variants'> {
+    /**
+     * The `variants: true` result this decision is for (the whole `data`
+     * object). The decision query then asks only about the fields that hold
+     * segment personalization groups, and is skipped entirely when there are
+     * 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;
+    /**
+     * True when Prepr reports, through the response's `Vary` header, that the
+     * queried fields hold segment variants or A/B tests.
+     */
+    personalized: boolean;
+}
+
+/** The cookie `resolveDecisions` writes and the `PreprStack` switch reads. */
+declare const PREPR_DECISIONS_COOKIE = "prepr_decisions";
+
+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.
+     */
+    render: (items: T[], position: {
+        index: number;
+        placeholder: 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.
+     */
+    bucket?: string;
+    /** Nonce for the inline A/B switch script, under a strict CSP. */
+    nonce?: string;
+    /**
+     * Tag each personalization and A/B variant for Prepr's tracking pixel, so
+     * it counts impressions (and clicks on `data-prepr-variant-event` elements
+     * inside) without `data-prepr-variant-key` in your components. Default
+     * `false`.
+     *
+     * 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.
+     */
+    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.
+ *
+ * - 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.
+ *
+ * @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;
+
+interface PreprNextClientOptions extends PreprClientOptions {
+    /** Tags set on every cacheable fetch, for `revalidateTag`. Default `['prepr']`. */
+    cacheTags?: string[];
+    /**
+     * `next.revalidate` for cacheable fetches. Unset leaves the installed Next
+     * version's default in place. `false` caches until `revalidateTag` runs,
+     * which suits a publish webhook calling `revalidateTag('prepr')`.
+     */
+    revalidate?: number | false;
+}
+interface PreprNextQueryOptions extends PreprQueryOptions {
+    /**
+     * Forward the visitor's Prepr headers (read through `next/headers`) and
+     * skip the Data Cache. The route renders per request.
+     */
+    personalize?: boolean;
+}
+interface PreprNextClient {
+    /**
+     * Run a GraphQL query against Prepr.
+     *
+     * Without `personalize`, the fetch is tagged for `revalidateTag` and may be
+     * served from the Data Cache. Do not swallow errors thrown here without
+     * `unstable_rethrow`: Next.js signals dynamic rendering by throwing from
+     * inside fetch, and the client passes those signals through untouched.
+     *
+     * @throws PreprError — `INVALID_DOCUMENT`, `FETCH_ERROR`, `HTTP_ERROR`,
+     *   `INVALID_RESPONSE` or `GRAPHQL_ERROR`.
+     */
+    query<TResult, TVariables>(document: PreprDocument<TResult, TVariables>, variables?: TVariables, options?: PreprNextQueryOptions): Promise<PreprQueryResult<TResult>>;
+    /**
+     * Which variant of each personalization and A/B group this visitor gets,
+     * for the query you render with `variants: true`. Forwards the visitor's
+     * Prepr headers (read through `next/headers`); never cached. Prepr decides
+     * 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.
+     */
+    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.
+     */
+    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).
+ *
+ * Headerless queries go through the Data Cache with `cacheTags`; queries with
+ * `personalize: true` forward the visitor's Prepr headers and are never
+ * cached.
+ *
+ * With Cache Components, run headerless queries inside `'use cache'` (the
+ * client's fetch tags carry over to the entry, so `revalidateTag` reaches it)
+ * and `personalize: true` queries inside `<Suspense>`: `personalize` reads
+ * request headers, which `'use cache'` forbids. A headerless query outside
+ * both only prerenders when `revalidate` is set. `preview: true` works inside `'use cache'`, but the entry is still
+ * cached unless draft mode is enabled, which makes Next skip cached entries.
+ *
+ * Requires the `graphql` package, which graphql-codegen already installs.
+ */
+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 };