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

package/dist/nextjs/index.cjs

@@ -20,12 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/nextjs/index.ts
 var nextjs_exports = {};
 __export(nextjs_exports, {
-  PREPR_BUCKET_COOKIE: () => PREPR_BUCKET_COOKIE,
   PreprError: () => PreprError,
+  PreprPersonalizationSwitch: () => import_components.PreprPersonalizationSwitch,
   PreprToolbar: () => import_components.PreprToolbar,
   PreprTrackingPixel: () => import_components.PreprTrackingPixel,
   createPreprDraftRoute: () => createPreprDraftRoute,
   createPreprMiddleware: () => createPreprMiddleware,
+  createPreprWebhookRoute: () => createPreprWebhookRoute,
   extractAccessToken: () => extractAccessToken,
   getActiveSegment: () => getActiveSegment,
   getActiveVariant: () => getActiveVariant,
@@ -34,7 +35,6 @@ __export(nextjs_exports, {
   getToolbarProps: () => getToolbarProps,
   isPersonalizedResponse: () => isPersonalizedResponse,
   preprDraftRedirect: () => preprDraftRedirect,
-  resolvePreprBucket: () => resolvePreprBucket,
   validatePreprToken: () => validatePreprToken
 });
 module.exports = __toCommonJS(nextjs_exports);
@@ -43,7 +43,7 @@ module.exports = __toCommonJS(nextjs_exports);
 var import_server = require("next/server");
 
 // src/version.ts
-var VERSION = "0.6.0-alpha.0";
+var VERSION = "0.6.0-alpha.10";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";
@@ -469,55 +469,6 @@ function isPersonalizedResponse(source) {
   return PERSONALIZED_VARY.test(headers2.get("vary") ?? "");
 }
 
-// src/nextjs/bucket.ts
-var PREPR_BUCKET_COOKIE = "prepr_ab_bucket";
-var isBucket = (value) => value === "A" || value === "B";
-function setBucketCookie(request, response, bucket) {
-  response.cookies.set(PREPR_BUCKET_COOKIE, bucket, {
-    path: "/",
-    sameSite: "lax",
-    // Readable on purpose: PreprStack's inline switch reads it before first
-    // paint. It holds only "A" or "B".
-    httpOnly: false,
-    secure: request.nextUrl.protocol === "https:",
-    maxAge: 60 * 60 * 24 * 365
-  });
-}
-async function resolvePreprBucket(request, response, options) {
-  const stored = request.cookies.get(PREPR_BUCKET_COOKIE)?.value;
-  const forced = response.headers.get("x-middleware-request-prepr-abtesting") ?? request.cookies.get(COOKIE_VARIANT)?.value;
-  if (options.preview && isBucket(forced)) {
-    if (forced !== stored) setBucketCookie(request, response, forced);
-    return forced;
-  }
-  if (isBucket(stored)) return stored;
-  if (options.onlyIf) {
-    const needed = await Promise.resolve().then(options.onlyIf).catch(() => true);
-    if (!needed) return "A";
-  }
-  const customerId = request.cookies.get(COOKIE_UID)?.value ?? response.cookies.get(COOKIE_UID)?.value;
-  if (!customerId) return "A";
-  try {
-    const res = await fetch(options.url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Prepr-Customer-Id": customerId
-      },
-      body: JSON.stringify({ query: "{ __typename }" }),
-      cache: "no-store",
-      signal: AbortSignal.timeout(options.timeoutMs ?? 1500)
-    });
-    const bucket = res.headers.get("x-prepr-customer-bucket");
-    if (isBucket(bucket)) {
-      setBucketCookie(request, response, bucket);
-      return bucket;
-    }
-  } catch {
-  }
-  return "A";
-}
-
 // src/nextjs/draft.ts
 var import_headers2 = require("next/headers");
 var import_navigation = require("next/navigation");
@@ -568,16 +519,128 @@ function createPreprDraftRoute(options) {
   };
 }
 
+// src/nextjs/webhook.ts
+var import_cache = require("next/cache");
+
+// src/core/graphql/cache-tags.ts
+var PREPR_ANY_ITEM_TAG = "prepr:any";
+var PREPR_SCHEMA_TAG = "prepr:schema";
+var preprItemTag = (id) => `prepr:${id}`;
+var NOT_ALPHANUMERIC = /[^a-z0-9]/g;
+var preprModelTag = (model) => `prepr:model:${model.toLowerCase().replace(NOT_ALPHANUMERIC, "")}`;
+
+// src/nextjs/webhook.ts
+var CONTENT_EVENTS = /* @__PURE__ */ new Set([
+  "content_item.published",
+  "content_item.unpublished",
+  "content_item.deleted",
+  "content_item.invalidated",
+  "asset.changed",
+  "asset.deleted"
+]);
+var MODEL_EVENTS = /* @__PURE__ */ new Set([
+  "content_item.published",
+  "content_item.unpublished",
+  "content_item.deleted"
+]);
+var MAX_AGE_MS = 5 * 60 * 1e3;
+var HEX_SIGNATURE = /^[0-9a-f]{64}$/i;
+var BASE64_SIGNATURE = /^[A-Za-z0-9+/]{43}=$/;
+var SIGNATURE_PREFIX = /^sha256=/i;
+var MAX_ID_LENGTH = 200;
+var text = (body, status) => new Response(body, { status, headers: { "Content-Type": "text/plain" } });
+function signatureBytes(header) {
+  const value = header.trim().replace(SIGNATURE_PREFIX, "");
+  if (HEX_SIGNATURE.test(value)) {
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      bytes[i] = parseInt(value.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+  }
+  if (BASE64_SIGNATURE.test(value)) {
+    return Uint8Array.from(atob(value), (char) => char.charCodeAt(0));
+  }
+  return null;
+}
+async function verify(secret, signature, body) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  return crypto.subtle.verify("HMAC", key, signature, body);
+}
+function parse(body) {
+  try {
+    const value = JSON.parse(new TextDecoder().decode(body));
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function eventTime(value) {
+  if (typeof value === "number") return value * 1e3;
+  if (typeof value === "string") return Date.parse(value);
+  return NaN;
+}
+function field(value, key) {
+  return typeof value === "object" && value !== null ? value[key] : void 0;
+}
+var usable = (value) => typeof value === "string" && value !== "" && value.length <= MAX_ID_LENGTH;
+function tagsFor(event) {
+  const name = event.event;
+  if (name === "schema.changed") return [PREPR_SCHEMA_TAG];
+  if (typeof name !== "string" || !CONTENT_EVENTS.has(name)) return [];
+  const tags = [PREPR_ANY_ITEM_TAG];
+  const id = field(event.payload, "id");
+  if (usable(id)) tags.push(preprItemTag(id));
+  const model = field(field(event.payload, "model"), "body_singular");
+  if (MODEL_EVENTS.has(name) && usable(model)) tags.push(preprModelTag(model));
+  return tags;
+}
+function createPreprWebhookRoute(options) {
+  const { profile = { expire: 0 } } = options;
+  return async (request) => {
+    const { secret } = options;
+    if (!secret) return text("Webhook secret not configured", 500);
+    const signature = signatureBytes(
+      request.headers.get("prepr-signature") ?? ""
+    );
+    let body;
+    try {
+      body = await request.arrayBuffer();
+    } catch {
+      return text("Unreadable body", 400);
+    }
+    if (!signature || !await verify(secret, signature, body)) {
+      return text("Invalid signature", 401);
+    }
+    const event = parse(body);
+    if (!event) return text("Invalid body", 400);
+    const sentAt = eventTime(event.created_on);
+    if (Number.isFinite(sentAt) && Math.abs(Date.now() - sentAt) > MAX_AGE_MS) {
+      return text("Expired", 401);
+    }
+    const tags = tagsFor(event);
+    for (const tag of tags) (0, import_cache.revalidateTag)(tag, profile);
+    return Response.json({ revalidated: tags });
+  };
+}
+
 // src/nextjs/index.ts
 var import_components = require("./components.cjs");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  PREPR_BUCKET_COOKIE,
   PreprError,
+  PreprPersonalizationSwitch,
   PreprToolbar,
   PreprTrackingPixel,
   createPreprDraftRoute,
   createPreprMiddleware,
+  createPreprWebhookRoute,
   extractAccessToken,
   getActiveSegment,
   getActiveVariant,
@@ -586,6 +649,5 @@ var import_components = require("./components.cjs");
   getToolbarProps,
   isPersonalizedResponse,
   preprDraftRedirect,
-  resolvePreprBucket,
   validatePreprToken
 });

package/dist/nextjs/index.d.cts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { b as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-CjpELYvq.cjs';
-export { a as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-CjpELYvq.cjs';
+import { a as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-BL-sqZvu.cjs';
+export { b as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-BL-sqZvu.cjs';
 
 interface PreprMiddlewareOptions {
     /** Enable preview-mode headers (segment/AB overrides, preview bar). */
@@ -44,26 +44,6 @@ declare function getPreprHeaders(): Promise<PreprHeaders>;
  */
 declare function getToolbarProps(token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
 
-/** Cookie holding the visitor's A/B bucket, as Prepr assigned it. */
-declare const PREPR_BUCKET_COOKIE = "prepr_ab_bucket";
-type PreprBucket = 'A' | 'B';
-interface ResolvePreprBucketOptions {
-    /** Full Prepr GraphQL URL. */
-    url: string;
-    /** Preview mode: the toolbar's A/B override wins. */
-    preview?: boolean;
-    /** Abort the one-time lookup after this many ms. Default 1500. */
-    timeoutMs?: number;
-    /**
-     * Look the bucket up only when this resolves to true, typically "does this
-     * page have an A/B test": `() => prepr.hasAbTests(PageDocument, { slug })`.
-     * Only called for visitors without a bucket cookie, so visitors on pages
-     * without A/B tests never wait for the lookup.
-     */
-    onlyIf?: () => boolean | Promise<boolean>;
-}
-declare function resolvePreprBucket(request: NextRequest, response: NextResponse, options: ResolvePreprBucketOptions): Promise<PreprBucket>;
-
 interface PreprDraftOptions {
     /** Whether this deployment serves preview content. Outside it, both helpers do nothing. */
     preview: boolean;
@@ -100,6 +80,47 @@ declare function preprDraftRedirect(request: NextRequest, options: PreprDraftOpt
  */
 declare function createPreprDraftRoute(options: Pick<PreprDraftOptions, 'preview'>): (request: Request) => Promise<Response>;
 
+/** How a revalidated page refreshes, as Next.js's `revalidateTag` takes it. */
+type PreprRevalidateProfile = string | {
+    expire?: number;
+};
+interface PreprWebhookOptions {
+    /**
+     * The webhook's ID, shown in Prepr under Settings → Webhooks. Prepr signs
+     * each request with it (HMAC-SHA256 of the body, in the `Prepr-Signature`
+     * header). Keep it in an environment variable.
+     */
+    secret: string | undefined;
+    /**
+     * Passed to `revalidateTag`. The default `{ expire: 0 }` shows a publish
+     * on the very next request; `'max'` serves the old page once more while
+     * the new one renders in the background.
+     */
+    profile?: PreprRevalidateProfile;
+}
+/**
+ * Route handler for a Prepr webhook that refreshes only the cached pages
+ * showing the changed item: those tagged by `query(..., { tagItems: true })`
+ * or `preprCacheTags`. On publish, unpublish and delete it also revalidates
+ * the item's `preprModelTag`, so list pages and lookups that found nothing
+ * pick up new and removed items. `schema.changed` refreshes the schema the
+ * client rewrites queries with.
+ *
+ * Other events (draft edits, new assets, visitors, segments) are
+ * acknowledged and revalidate nothing, so the webhook can subscribe to
+ * everything.
+ *
+ * Requests without a valid `Prepr-Signature` or older than five minutes get
+ * 401; without `secret` every request gets 500.
+ *
+ * @example
+ * // app/api/prepr/webhook/route.ts
+ * export const POST = createPreprWebhookRoute({
+ *   secret: process.env.PREPR_WEBHOOK_SECRET,
+ * });
+ */
+declare function createPreprWebhookRoute(options: PreprWebhookOptions): (request: Request) => Promise<Response>;
+
 /**
  * Loader + typed facade for Prepr's CDN tracking pixel, so consumers don't have
  * to paste a `<script>` tag. The pixel itself lives on the CDN; this only sets
@@ -153,5 +174,22 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  * `createPreprPreview` mounts imperatively.
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
+/**
+ * Gets each client-side navigation's decision in before the click: when the
+ * visitor hovers over a same-site link (or presses it, on touch devices), it
+ * asks `createPreprProxy` which variants they get on that page, so the new
+ * page paints with them. A click whose decision is not in yet (a quick tap,
+ * a link reached by keyboard) waits for it; one the visitor's recent
+ * decisions already cover, or one to a page without personalization, goes
+ * through at once.
+ *
+ * Mount it once in the root layout, so links on pages without a
+ * `PreprStack` are covered too. Clicks with a modifier key, links to other
+ * sites and links that open a new tab or download are left alone.
+ *
+ * @example
+ * <PreprPersonalizationSwitch />
+ */
+declare function PreprPersonalizationSwitch(): null;
 
-export { PREPR_BUCKET_COOKIE, type PreprBucket, type PreprDraftOptions, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type ResolvePreprBucketOptions, createPreprDraftRoute, createPreprMiddleware, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect, resolvePreprBucket };
+export { type PreprDraftOptions, type PreprMiddlewareOptions, PreprPersonalizationSwitch, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type PreprWebhookOptions, createPreprDraftRoute, createPreprMiddleware, createPreprWebhookRoute, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect };

package/dist/nextjs/index.d.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { b as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-CjpELYvq.js';
-export { a as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-CjpELYvq.js';
+import { a as PreprFeatures, P as PreprHeaders, c as PreprToolbarProps, d as PreprToolbarComponentProps } from './server-BL-sqZvu.js';
+export { b as PreprError, e as extractAccessToken, i as isPersonalizedResponse, v as validatePreprToken } from './server-BL-sqZvu.js';
 
 interface PreprMiddlewareOptions {
     /** Enable preview-mode headers (segment/AB overrides, preview bar). */
@@ -44,26 +44,6 @@ declare function getPreprHeaders(): Promise<PreprHeaders>;
  */
 declare function getToolbarProps(token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
 
-/** Cookie holding the visitor's A/B bucket, as Prepr assigned it. */
-declare const PREPR_BUCKET_COOKIE = "prepr_ab_bucket";
-type PreprBucket = 'A' | 'B';
-interface ResolvePreprBucketOptions {
-    /** Full Prepr GraphQL URL. */
-    url: string;
-    /** Preview mode: the toolbar's A/B override wins. */
-    preview?: boolean;
-    /** Abort the one-time lookup after this many ms. Default 1500. */
-    timeoutMs?: number;
-    /**
-     * Look the bucket up only when this resolves to true, typically "does this
-     * page have an A/B test": `() => prepr.hasAbTests(PageDocument, { slug })`.
-     * Only called for visitors without a bucket cookie, so visitors on pages
-     * without A/B tests never wait for the lookup.
-     */
-    onlyIf?: () => boolean | Promise<boolean>;
-}
-declare function resolvePreprBucket(request: NextRequest, response: NextResponse, options: ResolvePreprBucketOptions): Promise<PreprBucket>;
-
 interface PreprDraftOptions {
     /** Whether this deployment serves preview content. Outside it, both helpers do nothing. */
     preview: boolean;
@@ -100,6 +80,47 @@ declare function preprDraftRedirect(request: NextRequest, options: PreprDraftOpt
  */
 declare function createPreprDraftRoute(options: Pick<PreprDraftOptions, 'preview'>): (request: Request) => Promise<Response>;
 
+/** How a revalidated page refreshes, as Next.js's `revalidateTag` takes it. */
+type PreprRevalidateProfile = string | {
+    expire?: number;
+};
+interface PreprWebhookOptions {
+    /**
+     * The webhook's ID, shown in Prepr under Settings → Webhooks. Prepr signs
+     * each request with it (HMAC-SHA256 of the body, in the `Prepr-Signature`
+     * header). Keep it in an environment variable.
+     */
+    secret: string | undefined;
+    /**
+     * Passed to `revalidateTag`. The default `{ expire: 0 }` shows a publish
+     * on the very next request; `'max'` serves the old page once more while
+     * the new one renders in the background.
+     */
+    profile?: PreprRevalidateProfile;
+}
+/**
+ * Route handler for a Prepr webhook that refreshes only the cached pages
+ * showing the changed item: those tagged by `query(..., { tagItems: true })`
+ * or `preprCacheTags`. On publish, unpublish and delete it also revalidates
+ * the item's `preprModelTag`, so list pages and lookups that found nothing
+ * pick up new and removed items. `schema.changed` refreshes the schema the
+ * client rewrites queries with.
+ *
+ * Other events (draft edits, new assets, visitors, segments) are
+ * acknowledged and revalidate nothing, so the webhook can subscribe to
+ * everything.
+ *
+ * Requests without a valid `Prepr-Signature` or older than five minutes get
+ * 401; without `secret` every request gets 500.
+ *
+ * @example
+ * // app/api/prepr/webhook/route.ts
+ * export const POST = createPreprWebhookRoute({
+ *   secret: process.env.PREPR_WEBHOOK_SECRET,
+ * });
+ */
+declare function createPreprWebhookRoute(options: PreprWebhookOptions): (request: Request) => Promise<Response>;
+
 /**
  * Loader + typed facade for Prepr's CDN tracking pixel, so consumers don't have
  * to paste a `<script>` tag. The pixel itself lives on the CDN; this only sets
@@ -153,5 +174,22 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  * `createPreprPreview` mounts imperatively.
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
+/**
+ * Gets each client-side navigation's decision in before the click: when the
+ * visitor hovers over a same-site link (or presses it, on touch devices), it
+ * asks `createPreprProxy` which variants they get on that page, so the new
+ * page paints with them. A click whose decision is not in yet (a quick tap,
+ * a link reached by keyboard) waits for it; one the visitor's recent
+ * decisions already cover, or one to a page without personalization, goes
+ * through at once.
+ *
+ * Mount it once in the root layout, so links on pages without a
+ * `PreprStack` are covered too. Clicks with a modifier key, links to other
+ * sites and links that open a new tab or download are left alone.
+ *
+ * @example
+ * <PreprPersonalizationSwitch />
+ */
+declare function PreprPersonalizationSwitch(): null;
 
-export { PREPR_BUCKET_COOKIE, type PreprBucket, type PreprDraftOptions, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type ResolvePreprBucketOptions, createPreprDraftRoute, createPreprMiddleware, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect, resolvePreprBucket };
+export { type PreprDraftOptions, type PreprMiddlewareOptions, PreprPersonalizationSwitch, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type PreprWebhookOptions, createPreprDraftRoute, createPreprMiddleware, createPreprWebhookRoute, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, preprDraftRedirect };