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

package/dist/astro/graphql.d.cts

@@ -0,0 +1,231 @@
+import { DocumentNode } from 'graphql';
+import { P as PreprHeaders, a as PreprErrorCode, A as AstroLikeContext } from './index-XT_z-RYT.cjs';
+export { i as isPersonalizedResponse } from './index-XT_z-RYT.cjs';
+
+/** 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;
+}
+
+/**
+ * Query options for frameworks without an implicit request scope.
+ * `personalize: true` requires the request `event`; the compiler enforces it.
+ */
+type PreprEventQueryOptions<TEvent> = PreprQueryOptions & ({
+    personalize?: false;
+    event?: TEvent;
+} | {
+    personalize: true;
+    event: TEvent;
+});
+interface PreprEventClient<TEvent> {
+    /**
+     * Run a GraphQL query against Prepr. With `personalize: true`, the Prepr
+     * headers of `event` are forwarded and the request is `no-store`; without
+     * it the request is identical for every visitor.
+     *
+     * @throws PreprError — as `PreprClient.query`, plus `CONTEXT_ERROR` when
+     *   `personalize` is true and no `event` is passed.
+     */
+    query<TResult, TVariables>(document: PreprDocument<TResult, TVariables>, variables?: TVariables, options?: PreprEventQueryOptions<TEvent>): Promise<PreprQueryResult<TResult>>;
+    /**
+     * Which variant of each group this visitor gets, for the query you render
+     * with `variants: true`. Forwards the Prepr headers of `event`.
+     *
+     * @throws PreprError — `CONTEXT_ERROR` without an `event`.
+     */
+    decide<TVariables>(document: PreprDocument<unknown, TVariables>, variables: TVariables | undefined, options: PreprDecideOptions & {
+        event: TEvent;
+    }): Promise<PreprDecisions>;
+}
+
+/** Error thrown by the token helpers and the segments fetch. */
+declare class PreprError extends Error {
+    readonly code: PreprErrorCode;
+    readonly context?: string | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, code: PreprErrorCode, context?: string | undefined, originalError?: Error | undefined);
+}
+
+/**
+ * Prepr GraphQL client for Astro. Pass `Astro` (in a page or component) or
+ * the endpoint or middleware context as `event`. With `personalize: true`,
+ * the Prepr headers `onPreprRequest` set on the request are forwarded.
+ *
+ * Requires the `graphql` package, which graphql-codegen already installs.
+ */
+declare function createPreprClient(options: PreprClientOptions): PreprEventClient<AstroLikeContext>;
+
+export { AstroLikeContext, PREPR_DEFAULT_VARIANT, type PreprClientOptions, type PreprDecideOptions, type PreprDecisions, type PreprDocument, PreprError, type PreprEventClient, type PreprEventQueryOptions, type PreprQueryResult, type PreprStackBlock, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, preprVariantProps, resolveVariants, splitStack };

package/dist/astro/graphql.d.ts

@@ -0,0 +1,231 @@
+import { DocumentNode } from 'graphql';
+import { P as PreprHeaders, a as PreprErrorCode, A as AstroLikeContext } from './index-XT_z-RYT.js';
+export { i as isPersonalizedResponse } from './index-XT_z-RYT.js';
+
+/** 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;
+}
+
+/**
+ * Query options for frameworks without an implicit request scope.
+ * `personalize: true` requires the request `event`; the compiler enforces it.
+ */
+type PreprEventQueryOptions<TEvent> = PreprQueryOptions & ({
+    personalize?: false;
+    event?: TEvent;
+} | {
+    personalize: true;
+    event: TEvent;
+});
+interface PreprEventClient<TEvent> {
+    /**
+     * Run a GraphQL query against Prepr. With `personalize: true`, the Prepr
+     * headers of `event` are forwarded and the request is `no-store`; without
+     * it the request is identical for every visitor.
+     *
+     * @throws PreprError — as `PreprClient.query`, plus `CONTEXT_ERROR` when
+     *   `personalize` is true and no `event` is passed.
+     */
+    query<TResult, TVariables>(document: PreprDocument<TResult, TVariables>, variables?: TVariables, options?: PreprEventQueryOptions<TEvent>): Promise<PreprQueryResult<TResult>>;
+    /**
+     * Which variant of each group this visitor gets, for the query you render
+     * with `variants: true`. Forwards the Prepr headers of `event`.
+     *
+     * @throws PreprError — `CONTEXT_ERROR` without an `event`.
+     */
+    decide<TVariables>(document: PreprDocument<unknown, TVariables>, variables: TVariables | undefined, options: PreprDecideOptions & {
+        event: TEvent;
+    }): Promise<PreprDecisions>;
+}
+
+/** Error thrown by the token helpers and the segments fetch. */
+declare class PreprError extends Error {
+    readonly code: PreprErrorCode;
+    readonly context?: string | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, code: PreprErrorCode, context?: string | undefined, originalError?: Error | undefined);
+}
+
+/**
+ * Prepr GraphQL client for Astro. Pass `Astro` (in a page or component) or
+ * the endpoint or middleware context as `event`. With `personalize: true`,
+ * the Prepr headers `onPreprRequest` set on the request are forwarded.
+ *
+ * Requires the `graphql` package, which graphql-codegen already installs.
+ */
+declare function createPreprClient(options: PreprClientOptions): PreprEventClient<AstroLikeContext>;
+
+export { AstroLikeContext, PREPR_DEFAULT_VARIANT, type PreprClientOptions, type PreprDecideOptions, type PreprDecisions, type PreprDocument, PreprError, type PreprEventClient, type PreprEventQueryOptions, type PreprQueryResult, type PreprStackBlock, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, preprVariantProps, resolveVariants, splitStack };