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

package/dist/nextjs/graphql.d.ts

@@ -0,0 +1,435 @@
+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 { 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[]>;
+/**
+ * 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,
+     * 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;
+
+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;
+    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;
+
+/**
+ * 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`,
+ * 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;
+}
+
+/**
+ * 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 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, type PreprSchema, PreprStack, type PreprStackBlock, type PreprStackProps, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };