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

package/README.md

@@ -424,6 +424,102 @@ Outside preview both do nothing (the route answers 404). Keep the route out of y
 
 Do not catch and swallow errors from `query` without [`unstable_rethrow`](https://nextjs.org/docs/app/api-reference/functions/unstable_rethrow): Next.js signals dynamic rendering by throwing from inside `fetch`, and the client passes those signals through.
 
+#### Using your own GraphQL client
+
+Everything the toolkit's client does for personalization is two query rewrites and one helper. Use them with any client: Apollo, urql, or plain `fetch`.
+
+1. **Variants query** (same for every visitor, cache it): `toVariantsQuery(query, schema)`.
+2. **Decision query** (per visitor, never cached, with the visitor's Prepr headers): `toDecisionQuery(query, schema, { from: variantsData })`, then `decisionsFrom(data)`.
+3. **Render** with `PreprStack` (Next.js) or `resolveVariants(data, { decisions, bucket })` anywhere.
+
+The rewrites need to know which fields take `personalize`: `loadPreprSchema(url)` fetches that once and keeps it in memory.
+
+```ts
+import {
+  decisionsFrom,
+  loadPreprSchema,
+  resolveVariants,
+  toDecisionQuery,
+  toVariantsQuery,
+} from '@preprio/toolkit/graphql';
+
+const url = process.env.PREPR_GRAPHQL_URL!;
+const schema = await loadPreprSchema(url);
+
+async function post(
+  query: string,
+  variables: object,
+  headers: HeadersInit = {},
+) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify({ query, variables }),
+  });
+  const json = await res.json();
+  if (!res.ok || json.errors)
+    throw new Error(`Prepr GraphQL request failed (${res.status})`);
+  return json.data;
+}
+
+const variables = { slug: '/' };
+const page = await post(toVariantsQuery(PAGE_QUERY, schema), variables); // cacheable
+
+const decisionQuery = toDecisionQuery(PAGE_QUERY, schema, { from: page });
+const decisions = decisionQuery
+  ? decisionsFrom(await post(decisionQuery, variables, visitorPreprHeaders))
+  : new Map();
+
+const content = resolveVariants(page.Page.content, { decisions, bucket });
+```
+
+`visitorPreprHeaders` are the headers the middleware forwards (`getPreprHeaders()` in Next.js); `bucket` is the visitor's A/B bucket (`resolvePreprBucket` stores it in a cookie).
+
+With Apollo, parse the strings once and use them like any document:
+
+```ts
+import { gql } from '@apollo/client';
+
+const PageVariants = gql(toVariantsQuery(PAGE_QUERY, schema));
+const { data: page } = await client.query({ query: PageVariants, variables });
+
+const decisionQuery = toDecisionQuery(PAGE_QUERY, schema, { from: page });
+const decisions = decisionQuery
+  ? decisionsFrom(
+      (
+        await client.query({
+          query: gql(decisionQuery),
+          variables,
+          context: { headers: visitorPreprHeaders },
+          fetchPolicy: 'no-cache', // per visitor: never from Apollo's cache
+        })
+      ).data,
+    )
+  : new Map();
+```
+
+**At build time with graphql-codegen.** The plugin writes both queries per named query into a file, so nothing is rewritten and no schema is loaded at runtime:
+
+```ts
+// codegen.ts
+generates: {
+  'src/gql/prepr-queries.ts': {
+    plugins: ['@preprio/toolkit/graphql/codegen'],
+  },
+},
+```
+
+```ts
+import {
+  GetPageBySlugDecisionQuery,
+  GetPageBySlugVariantsQuery,
+} from './gql/prepr-queries';
+```
+
+Only named queries with personalizable fields get exports; two queries with the same name fail the run. The generated decision query asks about every personalizable list. When you have the variants result at hand, `toDecisionQuery(query, schema, { from })` is smaller and markedly faster for visitors Prepr has not seen before.
+
+A/B tests need no decision query: render both variants and pick the visitor's bucket, as `PreprStack` and `resolvePreprBucket` do, or pass the bucket to `resolveVariants`.
+
 ### Image loader
 
 Prepr's stream CDN resizes at the edge. Routing `next/image` through the bundled loader makes Next request the exact width it needs, instead of pulling the full-resolution original and re-encoding it through `/_next/image`.
@@ -825,6 +921,17 @@ Import `PreprError` from the same subpath as the client when checking `instanceo
 
 `isPersonalizedResponse(response)`, exported from every entry point, reads the same verdict from a response fetched with your own client. It does not need `graphql`.
 
+For your own GraphQL client (see [Using your own GraphQL client](#using-your-own-graphql-client)), every `/graphql` subpath also exports:
+
+| Function                                                   | Returns                                                                                |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `loadPreprSchema(url, { fetch? })`                         | What the rewrites need from your schema, loaded once per URL. Failures are not cached. |
+| `toVariantsQuery(query, schema)`                           | The variants query as a string: what `variants: true` sends.                           |
+| `toDecisionQuery(query, schema, { from?, topLevelOnly? })` | The per-visitor decision query as a string, or `null` when there is nothing to decide. |
+| `decisionsFrom(data)`                                      | Decisions from a decision query's `data`, for `resolveVariants` or `PreprStack`.       |
+
+`@preprio/toolkit/graphql/codegen` is a graphql-codegen plugin that writes `<Name>VariantsQuery` and `<Name>DecisionQuery` for every named query with personalizable fields.
+
 ### Token helpers
 
 Exported from every entry point, including the core.

package/dist/astro/{chunk-3UVUDDNY.js → chunk-O7N6GPAH.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.6.0-alpha.0";
+var VERSION = "0.6.0-alpha.1";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/astro/graphql.cjs

@@ -23,10 +23,14 @@ __export(graphql_exports, {
   PREPR_DEFAULT_VARIANT: () => PREPR_DEFAULT_VARIANT,
   PreprError: () => PreprError,
   createPreprClient: () => createPreprClient2,
+  decisionsFrom: () => decisionsFrom,
   isPersonalizedResponse: () => isPersonalizedResponse,
+  loadPreprSchema: () => loadPreprSchema,
   preprVariantProps: () => preprVariantProps,
   resolveVariants: () => resolveVariants,
-  splitStack: () => splitStack
+  splitStack: () => splitStack,
+  toDecisionQuery: () => toDecisionQuery,
+  toVariantsQuery: () => toVariantsQuery
 });
 module.exports = __toCommonJS(graphql_exports);
 
@@ -564,6 +568,63 @@ function toVariantsDocument(document2, schema) {
   };
 }
 
+// src/core/graphql/document.ts
+var import_printer = require("graphql/language/printer.js");
+var import_stripIgnoredCharacters = require("graphql/utilities/stripIgnoredCharacters.js");
+var printed = /* @__PURE__ */ new WeakMap();
+function isDocumentNode(value) {
+  return typeof value === "object" && value !== null && value.kind === "Document" && Array.isArray(value.definitions);
+}
+function invalidDocument(originalError) {
+  return new PreprError(
+    "Expected a GraphQL query string, TypedDocumentString or DocumentNode",
+    "INVALID_DOCUMENT",
+    "createPreprClient",
+    originalError
+  );
+}
+var minified = /* @__PURE__ */ new Map();
+var MINIFIED_CACHE_LIMIT = 500;
+function minify(query) {
+  const cached = minified.get(query);
+  if (cached !== void 0) return cached;
+  let result = query;
+  try {
+    result = (0, import_stripIgnoredCharacters.stripIgnoredCharacters)(query);
+  } catch {
+  }
+  if (minified.size < MINIFIED_CACHE_LIMIT) minified.set(query, result);
+  return result;
+}
+function resolveQuery(document2) {
+  if (typeof document2 === "string") return minify(document2);
+  if (document2 instanceof String) return minify(document2.toString());
+  if (!isDocumentNode(document2)) throw invalidDocument();
+  let query = printed.get(document2);
+  if (query === void 0) {
+    try {
+      query = minify((0, import_printer.print)(document2));
+    } catch (error) {
+      throw invalidDocument(error instanceof Error ? error : void 0);
+    }
+    printed.set(document2, query);
+  }
+  return query;
+}
+
+// src/core/variants/queries.ts
+function toVariantsQuery(document2, schema) {
+  return resolveQuery(toVariantsDocument(document2, schema));
+}
+function toDecisionQuery(document2, schema, options = {}) {
+  const paths = options.from === void 0 ? void 0 : personalizationPaths(options.from);
+  if (paths && paths.size === 0) return null;
+  const decision = toDecisionDocument(document2, schema, paths, {
+    topLevelOnly: !paths && options.topLevelOnly
+  });
+  return decision ? resolveQuery(decision) : null;
+}
+
 // src/core/graphql/transport.ts
 var import_stega2 = require("@vercel/stega");
 
@@ -623,50 +684,6 @@ function stegaClean(text) {
   return (0, import_stega.vercelStegaClean)(text);
 }
 
-// src/core/graphql/document.ts
-var import_printer = require("graphql/language/printer.js");
-var import_stripIgnoredCharacters = require("graphql/utilities/stripIgnoredCharacters.js");
-var printed = /* @__PURE__ */ new WeakMap();
-function isDocumentNode(value) {
-  return typeof value === "object" && value !== null && value.kind === "Document" && Array.isArray(value.definitions);
-}
-function invalidDocument(originalError) {
-  return new PreprError(
-    "Expected a GraphQL query string, TypedDocumentString or DocumentNode",
-    "INVALID_DOCUMENT",
-    "createPreprClient",
-    originalError
-  );
-}
-var minified = /* @__PURE__ */ new Map();
-var MINIFIED_CACHE_LIMIT = 500;
-function minify(query) {
-  const cached = minified.get(query);
-  if (cached !== void 0) return cached;
-  let result = query;
-  try {
-    result = (0, import_stripIgnoredCharacters.stripIgnoredCharacters)(query);
-  } catch {
-  }
-  if (minified.size < MINIFIED_CACHE_LIMIT) minified.set(query, result);
-  return result;
-}
-function resolveQuery(document2) {
-  if (typeof document2 === "string") return minify(document2);
-  if (document2 instanceof String) return minify(document2.toString());
-  if (!isDocumentNode(document2)) throw invalidDocument();
-  let query = printed.get(document2);
-  if (query === void 0) {
-    try {
-      query = minify((0, import_printer.print)(document2));
-    } catch (error) {
-      throw invalidDocument(error instanceof Error ? error : void 0);
-    }
-    printed.set(document2, query);
-  }
-  return query;
-}
-
 // src/core/graphql/transport.ts
 var OPERATION_NAME = /\b(?:query|mutation|subscription)\s+([_A-Za-z][_0-9A-Za-z]*)/;
 var STEGA_RAW = new RegExp(
@@ -853,16 +870,18 @@ function isParseableUrl(url) {
     return false;
   }
 }
-function createPreprClient(options) {
-  const { url } = options;
+function assertPreprUrl(url, source) {
   validatePreprToken(url);
   if (!isParseableUrl(url)) {
     throw new PreprError(
       "Prepr GraphQL URL is not a valid URL",
       "INVALID_TOKEN",
-      "createPreprClient"
+      source
     );
   }
+}
+function createPreprClient(options) {
+  assertPreprUrl(options.url, "createPreprClient");
   const run = createTransport(options);
   const probeVary = createVaryProbe(run, options);
   let schema;
@@ -965,6 +984,30 @@ function createEventClient(options, adapter) {
   };
 }
 
+// src/core/graphql/schema-loader.ts
+var schemas = /* @__PURE__ */ new Map();
+async function loadPreprSchema(url, options = {}) {
+  assertPreprUrl(url, "loadPreprSchema");
+  let schema = schemas.get(url);
+  if (!schema) {
+    const run = createTransport({ url, fetch: options.fetch, stega: "none" });
+    schema = run(
+      PREPR_SCHEMA_QUERY
+    ).then((result) => toSchemaInfo(result.data)).catch((error) => {
+      schemas.delete(url);
+      if (error instanceof PreprError) throw error;
+      throw new PreprError(
+        "Prepr schema response is not an introspection result",
+        "INVALID_RESPONSE",
+        "loadPreprSchema",
+        error instanceof Error ? error : void 0
+      );
+    });
+    schemas.set(url, schema);
+  }
+  return schema;
+}
+
 // src/astro/graphql.ts
 function createPreprClient2(options) {
   return createEventClient(options, {
@@ -976,8 +1019,12 @@ function createPreprClient2(options) {
   PREPR_DEFAULT_VARIANT,
   PreprError,
   createPreprClient,
+  decisionsFrom,
   isPersonalizedResponse,
+  loadPreprSchema,
   preprVariantProps,
   resolveVariants,
-  splitStack
+  splitStack,
+  toDecisionQuery,
+  toVariantsQuery
 });

package/dist/astro/graphql.d.cts

@@ -7,6 +7,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,
@@ -23,6 +29,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;
@@ -71,6 +95,39 @@ 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`,
@@ -211,6 +268,23 @@ interface PreprEventClient<TEvent> {
     }): Promise<PreprDecisions>;
 }
 
+/**
+ * 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>;
+
 /** Error thrown by the token helpers and the segments fetch. */
 declare class PreprError extends Error {
     readonly code: PreprErrorCode;
@@ -228,4 +302,4 @@ declare class PreprError extends Error {
  */
 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 };
+export { AstroLikeContext, PREPR_DEFAULT_VARIANT, type PreprClientOptions, type PreprDecideOptions, type PreprDecisions, type PreprDocument, PreprError, type PreprEventClient, type PreprEventQueryOptions, type PreprQueryResult, type PreprSchema, type PreprStackBlock, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };

package/dist/astro/graphql.d.ts

@@ -7,6 +7,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,
@@ -23,6 +29,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;
@@ -71,6 +95,39 @@ 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`,
@@ -211,6 +268,23 @@ interface PreprEventClient<TEvent> {
     }): Promise<PreprDecisions>;
 }
 
+/**
+ * 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>;
+
 /** Error thrown by the token helpers and the segments fetch. */
 declare class PreprError extends Error {
     readonly code: PreprErrorCode;
@@ -228,4 +302,4 @@ declare class PreprError extends Error {
  */
 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 };
+export { AstroLikeContext, PREPR_DEFAULT_VARIANT, type PreprClientOptions, type PreprDecideOptions, type PreprDecisions, type PreprDocument, PreprError, type PreprEventClient, type PreprEventQueryOptions, type PreprQueryResult, type PreprSchema, type PreprStackBlock, type PreprStegaMode, type PreprVariantProps, type ResolveVariantsOptions, createPreprClient, decisionsFrom, loadPreprSchema, preprVariantProps, resolveVariants, splitStack, toDecisionQuery, toVariantsQuery };