@xenia-martech/sdk-js 1.2.0-dev.2 → 1.2.0-dev.4

package/dist/next/index.d.cts

@@ -1,7 +1,183 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { V as VisitorCookieOptions, f as ConsentState, L as XeniaConfig } from '../personalize-content-Clc1oMYY.cjs';
-import { X as XeniaServer } from '../xenia-server-o_wDOcei.cjs';
-import '../api-BEPW0Uan.cjs';
+import { V as VisitorCookieOptions, d as ConsentState, x as XeniaConfig } from '../types-DgVHS4Qw.cjs';
+import { X as XeniaServer } from '../xenia-server-C3O-cWQT.cjs';
+import { j as ViewerGeo, T as TrailView, E as EdgeConsent, f as EdgeFacts, a as DecideOutcome, X as XeniaEdge, G as GeoHeader, h as ManifestKey, e as EdgeDecision, S as SwapGroup } from '../consent-DgWdjsSy.cjs';
+import '../api-0IycTYJR.cjs';
+import '../personalize-content-ghZPKlf1.cjs';
+
+/** Request header the proxy stamps with the URL being served (a Server Component can't see its own). */
+declare const URL_HEADER = "x-xenia-url";
+
+/**
+ * The edge decide flow in one proxy call: which page views need Xenia, the facts Xenia decides on,
+ * and the rewrite to the variant page. Every failure ends in base content.
+ *
+ * Cost per request:
+ * - page no journey targets → an in-memory manifest lookup, no Xenia call
+ * - targeted page, returning visitor → an in-memory decision-cache hit
+ * - targeted page, first view this session → one `/decide` call, capped at the budget
+ */
+
+/** What the proxy knows about this page view. `prepare` may change the fields marked so. */
+interface EdgeRequestContext {
+    request: NextRequest;
+    host: string | null;
+    path: string;
+    /** The visitor this view is decided for (changeable in `prepare`, e.g. a profile's own visitor). */
+    visitorId: string;
+    /** The visitor cookie the browser sent, if any. */
+    existingVisitorId?: string;
+    /** Where the visitor is (changeable in `prepare`, e.g. a QA city). */
+    geo?: ViewerGeo;
+    /** Which source supplied `geo` (see `viewerGeo`). */
+    geoVia: string;
+    /** While a QA city stands in for `geo`: what the edge really detected (for the debug panel). */
+    detectedGeo?: ViewerGeo;
+    device: "mobile" | "tablet" | "desktop";
+    /** First-touch campaign and referrer (changeable in `prepare`). */
+    landing: Record<string, string>;
+    /** Recent views before this one (changeable in `prepare`). */
+    previousTrail: TrailView[];
+    /** The trail with this view first — set after `prepare`. */
+    trail: TrailView[];
+    consent: EdgeConsent;
+    /** "Now" for local-time facts: the real time, or a QA date (changeable in `prepare`). */
+    now: Date;
+}
+/** `error`: something threw (a hook, the edge client) — base content was served. */
+type EdgeExit = "skipped" | "not-targeted" | "no-consent" | "decided" | "error";
+interface EdgeDecisionInfo<S = unknown> {
+    ctx: EdgeRequestContext;
+    exit: EdgeExit;
+    /** The facts sent to `/decide` (standard ones with the site's on top); absent when skipped. */
+    facts?: EdgeFacts;
+    outcome?: DecideOutcome;
+    side?: S;
+    /** The response about to be returned — set cookies on it here. */
+    response: NextResponse;
+}
+interface XeniaEdgeProxyOptions<S = unknown> {
+    /** One client per instance: `createXeniaEdge(…)` from `/edge`. */
+    edge: XeniaEdge;
+    /** Server-only secret the variant token is signed with. */
+    variantSecret: string;
+    /** Where variant pages live. Default `/xv` (`/xv/<token>/women`). */
+    variantPrefix?: string;
+    /** Must match the browser client's `config.prefix`, if you set one. */
+    prefix?: string;
+    cookie?: VisitorCookieOptions;
+    /**
+     * The location headers your host (or edge function) sets and overwrites, e.g.
+     * `["x-vercel-ip-country"]` — see `viewerGeo`. Default none: a visitor can send any header.
+     */
+    geoHeaders?: readonly GeoHeader[];
+    /** Treat `Sec-GPC` / `DNT` as analytics off. Default true. */
+    respectDnt?: boolean;
+    /** Paths with no variant page (app routes): their views join the trail, but they're never decided. */
+    skip?: (path: string) => boolean;
+    /** Adjust the context before facts are built: the visitor, geo, landing or earlier trail. */
+    prepare?: (ctx: EdgeRequestContext) => void | Promise<void>;
+    /** The site's own facts, on top of the standard ones. */
+    facts?: (ctx: EdgeRequestContext) => EdgeFacts | Promise<EdgeFacts>;
+    /** What else makes this visitor's decision different (a new value → a fresh decision). */
+    cacheFacts?: (ctx: EdgeRequestContext) => EdgeFacts | Promise<EdgeFacts>;
+    /** This view's `/decide` budget, instead of the client's (e.g. a journey that calls a back office). */
+    budgetMs?: (ctx: EdgeRequestContext) => number | undefined;
+    /** Work started before `/decide` and awaited after it; its result reaches the hooks below as `side`. */
+    alongside?: (ctx: EdgeRequestContext, keys: ManifestKey[]) => Promise<S>;
+    filterDecisions?: (decisions: EdgeDecision[], ctx: EdgeRequestContext, side: S | undefined, outcome: DecideOutcome) => EdgeDecision[];
+    /**
+     * Where to render this view: a URL to rewrite to, `null` for the page itself, `undefined` for the
+     * default (the signed variant page when anything was swapped). Called on every exit but `skipped`;
+     * `outcome` is absent when Xenia wasn't asked.
+     */
+    rewrite?: (ctx: EdgeRequestContext, groups: SwapGroup[], side: S | undefined, outcome: DecideOutcome | undefined) => URL | null | undefined | Promise<URL | null | undefined>;
+    /** Carried in the variant token beside the swaps (left out if it would make the token too long). */
+    extra?: (ctx: EdgeRequestContext, side: S | undefined, outcome: DecideOutcome) => unknown;
+    /** Called on every exit, with the response about to be returned. */
+    onDecision?: (info: EdgeDecisionInfo<S>) => void | Promise<void>;
+    /** Anything that threw on the way (base content was served instead). Default: nothing. */
+    onError?: (error: unknown) => void;
+    /**
+     * Write what was decided for each page to the `<prefix>_debug` cookie `<XeniaDebugPanel>` reads.
+     * For development and QA only — turn it on with `process.env.NODE_ENV === "development"` or a flag.
+     */
+    debug?: boolean;
+    /** Fields of your own for the panel (or replacements for the SDK's), per page view. */
+    debugInfo?: (info: EdgeDecisionInfo<S>) => Record<string, unknown>;
+    /**
+     * QA overrides for development and QA only: `?xn_geo=<city>` (`QA_CITIES`, or your own `cities`),
+     * `?xn_date=YYYY-MM-DD`, `?xn_geo=off` to forget them, and `?xn_country=GB` under `next dev`.
+     */
+    qa?: boolean | {
+        cities?: Record<string, ViewerGeo>;
+    };
+}
+/**
+ * Next.js `proxy.ts`/`middleware.ts` step for edge personalization: ensures the visitor cookie
+ * (like `xeniaProxy()`), keeps the landing campaign and page trail, decides targeted pages with
+ * Xenia within the budget and rewrites a personalized view to its signed variant page
+ * (`decodeVariant` there). Respects consent (see `edgeConsent`).
+ *
+ * ```ts
+ * const edge = createXeniaEdge({ baseUrl, token: process.env.XENIA_SDK_TOKEN! });
+ * export const proxy = (request: NextRequest) =>
+ *   xeniaEdgeProxy(request, { edge, variantSecret: process.env.XENIA_VARIANT_SECRET! });
+ * ```
+ */
+declare function xeniaEdgeProxy<S = unknown>(request: NextRequest, opts: XeniaEdgeProxyOptions<S>): Promise<NextResponse>;
+
+/**
+ * `GET` for a public, CDN-cached copy of the manifest (version + targeted page patterns only — no
+ * content keys or rules), so a cold proxy instance reads it from the nearby CDN instead of waiting on
+ * Xenia, and the server token never leaves the server. Point the edge client's `manifestUrl` at it.
+ * At build time an unreachable Xenia serves an empty manifest instead of failing the deploy; at
+ * runtime it throws, so the cache keeps the last good copy.
+ *
+ * ```ts
+ * // app/api/xenia/manifest/route.ts
+ * export const revalidate = 36000; // a safety net — the storefront webhook regenerates it at once
+ * export const GET = createManifestRoute({ token: process.env.XENIA_SDK_TOKEN, revalidate });
+ * ```
+ */
+declare function createManifestRoute(opts: {
+    token?: string;
+    baseUrl?: string;
+    revalidate?: number;
+}): () => Promise<Response>;
+/**
+ * `POST` for Xenia's storefront webhook (Journey Orchestrator → Storefront webhook): verifies the
+ * signature (`verifyWebhook`), answers `ping`, and on `manifest.changed` regenerates `paths` (the
+ * manifest route) at once, then runs `onManifestChanged` (e.g. a rebuild hook) and merges what it
+ * returns into the response.
+ */
+declare function createRevalidateRoute(opts: {
+    secret?: string;
+    paths: string[];
+    onManifestChanged?: () => Promise<Record<string, unknown>> | Record<string, unknown>;
+}): (request: Request) => Promise<Response>;
+
+/** One page's entry in the edge debug cookie (written by `xeniaEdgeProxy({ debug })`, read by `<XeniaDebugPanel>`). */
+type DebugEntry = Record<string, unknown> & {
+    page: string;
+};
+/** The debug cookie's pages (it may arrive encoded once or twice); anything unreadable is none. */
+declare function readDebugEntries(raw: string | undefined | null): Record<string, DebugEntry>;
+
+/**
+ * QA and debugging for the edge flow (`xeniaEdgeProxy`'s `qa` and `debug` options):
+ * - QA overrides: `?xn_geo=<city>` places the visitor in a QA city, `?xn_date=YYYY-MM-DD` decides
+ *   as of that day (midday in the US), `?xn_geo=off` forgets them; kept for the visit in a cookie;
+ * - the debug cookie: what was decided for each of the last few pages, read by `<XeniaDebugPanel>`.
+ *   A cookie rather than the HTML, because variant pages are cached and shared.
+ */
+
+/** Cities a QA visitor can be placed in, with what an edge would report for them. */
+declare const QA_CITIES: Record<string, ViewerGeo>;
+interface QaState {
+    geo?: string;
+    date?: string;
+}
 
 /**
  * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.
@@ -13,8 +189,6 @@ import '../api-BEPW0Uan.cjs';
  * visitor id).
  */
 
-/** Request header `xeniaProxy()` stamps with the URL being served. */
-declare const URL_HEADER = "x-xenia-url";
 interface XeniaProxyOptions {
     /** Request headers to forward (e.g. your own additions); defaults to the incoming ones. */
     headers?: Headers;
@@ -71,4 +245,4 @@ declare function consentFromNext(prefix?: string): Promise<ConsentState>;
  */
 declare function personalizeOnce<T>(key: string, personalize: () => Promise<T>): Promise<T>;
 
-export { URL_HEADER, type XeniaProxyOptions, consentFromNext, personalizeOnce, xeniaProxy, xeniaServerFromNext };
+export { type DebugEntry, type EdgeDecisionInfo, type EdgeExit, type EdgeRequestContext, QA_CITIES, type QaState, URL_HEADER, type XeniaEdgeProxyOptions, type XeniaProxyOptions, consentFromNext, createManifestRoute, createRevalidateRoute, personalizeOnce, readDebugEntries, xeniaEdgeProxy, xeniaProxy, xeniaServerFromNext };

package/dist/next/index.d.ts

@@ -1,7 +1,183 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { V as VisitorCookieOptions, f as ConsentState, L as XeniaConfig } from '../personalize-content-Clc1oMYY.js';
-import { X as XeniaServer } from '../xenia-server-BWhWD0La.js';
-import '../api-CktVQ6Gl.js';
+import { V as VisitorCookieOptions, d as ConsentState, x as XeniaConfig } from '../types-DgVHS4Qw.js';
+import { X as XeniaServer } from '../xenia-server-DV8Sjmoo.js';
+import { j as ViewerGeo, T as TrailView, E as EdgeConsent, f as EdgeFacts, a as DecideOutcome, X as XeniaEdge, G as GeoHeader, h as ManifestKey, e as EdgeDecision, S as SwapGroup } from '../consent-Cemn91j3.js';
+import '../api-COXWLL5L.js';
+import '../personalize-content-c2DDAV6g.js';
+
+/** Request header the proxy stamps with the URL being served (a Server Component can't see its own). */
+declare const URL_HEADER = "x-xenia-url";
+
+/**
+ * The edge decide flow in one proxy call: which page views need Xenia, the facts Xenia decides on,
+ * and the rewrite to the variant page. Every failure ends in base content.
+ *
+ * Cost per request:
+ * - page no journey targets → an in-memory manifest lookup, no Xenia call
+ * - targeted page, returning visitor → an in-memory decision-cache hit
+ * - targeted page, first view this session → one `/decide` call, capped at the budget
+ */
+
+/** What the proxy knows about this page view. `prepare` may change the fields marked so. */
+interface EdgeRequestContext {
+    request: NextRequest;
+    host: string | null;
+    path: string;
+    /** The visitor this view is decided for (changeable in `prepare`, e.g. a profile's own visitor). */
+    visitorId: string;
+    /** The visitor cookie the browser sent, if any. */
+    existingVisitorId?: string;
+    /** Where the visitor is (changeable in `prepare`, e.g. a QA city). */
+    geo?: ViewerGeo;
+    /** Which source supplied `geo` (see `viewerGeo`). */
+    geoVia: string;
+    /** While a QA city stands in for `geo`: what the edge really detected (for the debug panel). */
+    detectedGeo?: ViewerGeo;
+    device: "mobile" | "tablet" | "desktop";
+    /** First-touch campaign and referrer (changeable in `prepare`). */
+    landing: Record<string, string>;
+    /** Recent views before this one (changeable in `prepare`). */
+    previousTrail: TrailView[];
+    /** The trail with this view first — set after `prepare`. */
+    trail: TrailView[];
+    consent: EdgeConsent;
+    /** "Now" for local-time facts: the real time, or a QA date (changeable in `prepare`). */
+    now: Date;
+}
+/** `error`: something threw (a hook, the edge client) — base content was served. */
+type EdgeExit = "skipped" | "not-targeted" | "no-consent" | "decided" | "error";
+interface EdgeDecisionInfo<S = unknown> {
+    ctx: EdgeRequestContext;
+    exit: EdgeExit;
+    /** The facts sent to `/decide` (standard ones with the site's on top); absent when skipped. */
+    facts?: EdgeFacts;
+    outcome?: DecideOutcome;
+    side?: S;
+    /** The response about to be returned — set cookies on it here. */
+    response: NextResponse;
+}
+interface XeniaEdgeProxyOptions<S = unknown> {
+    /** One client per instance: `createXeniaEdge(…)` from `/edge`. */
+    edge: XeniaEdge;
+    /** Server-only secret the variant token is signed with. */
+    variantSecret: string;
+    /** Where variant pages live. Default `/xv` (`/xv/<token>/women`). */
+    variantPrefix?: string;
+    /** Must match the browser client's `config.prefix`, if you set one. */
+    prefix?: string;
+    cookie?: VisitorCookieOptions;
+    /**
+     * The location headers your host (or edge function) sets and overwrites, e.g.
+     * `["x-vercel-ip-country"]` — see `viewerGeo`. Default none: a visitor can send any header.
+     */
+    geoHeaders?: readonly GeoHeader[];
+    /** Treat `Sec-GPC` / `DNT` as analytics off. Default true. */
+    respectDnt?: boolean;
+    /** Paths with no variant page (app routes): their views join the trail, but they're never decided. */
+    skip?: (path: string) => boolean;
+    /** Adjust the context before facts are built: the visitor, geo, landing or earlier trail. */
+    prepare?: (ctx: EdgeRequestContext) => void | Promise<void>;
+    /** The site's own facts, on top of the standard ones. */
+    facts?: (ctx: EdgeRequestContext) => EdgeFacts | Promise<EdgeFacts>;
+    /** What else makes this visitor's decision different (a new value → a fresh decision). */
+    cacheFacts?: (ctx: EdgeRequestContext) => EdgeFacts | Promise<EdgeFacts>;
+    /** This view's `/decide` budget, instead of the client's (e.g. a journey that calls a back office). */
+    budgetMs?: (ctx: EdgeRequestContext) => number | undefined;
+    /** Work started before `/decide` and awaited after it; its result reaches the hooks below as `side`. */
+    alongside?: (ctx: EdgeRequestContext, keys: ManifestKey[]) => Promise<S>;
+    filterDecisions?: (decisions: EdgeDecision[], ctx: EdgeRequestContext, side: S | undefined, outcome: DecideOutcome) => EdgeDecision[];
+    /**
+     * Where to render this view: a URL to rewrite to, `null` for the page itself, `undefined` for the
+     * default (the signed variant page when anything was swapped). Called on every exit but `skipped`;
+     * `outcome` is absent when Xenia wasn't asked.
+     */
+    rewrite?: (ctx: EdgeRequestContext, groups: SwapGroup[], side: S | undefined, outcome: DecideOutcome | undefined) => URL | null | undefined | Promise<URL | null | undefined>;
+    /** Carried in the variant token beside the swaps (left out if it would make the token too long). */
+    extra?: (ctx: EdgeRequestContext, side: S | undefined, outcome: DecideOutcome) => unknown;
+    /** Called on every exit, with the response about to be returned. */
+    onDecision?: (info: EdgeDecisionInfo<S>) => void | Promise<void>;
+    /** Anything that threw on the way (base content was served instead). Default: nothing. */
+    onError?: (error: unknown) => void;
+    /**
+     * Write what was decided for each page to the `<prefix>_debug` cookie `<XeniaDebugPanel>` reads.
+     * For development and QA only — turn it on with `process.env.NODE_ENV === "development"` or a flag.
+     */
+    debug?: boolean;
+    /** Fields of your own for the panel (or replacements for the SDK's), per page view. */
+    debugInfo?: (info: EdgeDecisionInfo<S>) => Record<string, unknown>;
+    /**
+     * QA overrides for development and QA only: `?xn_geo=<city>` (`QA_CITIES`, or your own `cities`),
+     * `?xn_date=YYYY-MM-DD`, `?xn_geo=off` to forget them, and `?xn_country=GB` under `next dev`.
+     */
+    qa?: boolean | {
+        cities?: Record<string, ViewerGeo>;
+    };
+}
+/**
+ * Next.js `proxy.ts`/`middleware.ts` step for edge personalization: ensures the visitor cookie
+ * (like `xeniaProxy()`), keeps the landing campaign and page trail, decides targeted pages with
+ * Xenia within the budget and rewrites a personalized view to its signed variant page
+ * (`decodeVariant` there). Respects consent (see `edgeConsent`).
+ *
+ * ```ts
+ * const edge = createXeniaEdge({ baseUrl, token: process.env.XENIA_SDK_TOKEN! });
+ * export const proxy = (request: NextRequest) =>
+ *   xeniaEdgeProxy(request, { edge, variantSecret: process.env.XENIA_VARIANT_SECRET! });
+ * ```
+ */
+declare function xeniaEdgeProxy<S = unknown>(request: NextRequest, opts: XeniaEdgeProxyOptions<S>): Promise<NextResponse>;
+
+/**
+ * `GET` for a public, CDN-cached copy of the manifest (version + targeted page patterns only — no
+ * content keys or rules), so a cold proxy instance reads it from the nearby CDN instead of waiting on
+ * Xenia, and the server token never leaves the server. Point the edge client's `manifestUrl` at it.
+ * At build time an unreachable Xenia serves an empty manifest instead of failing the deploy; at
+ * runtime it throws, so the cache keeps the last good copy.
+ *
+ * ```ts
+ * // app/api/xenia/manifest/route.ts
+ * export const revalidate = 36000; // a safety net — the storefront webhook regenerates it at once
+ * export const GET = createManifestRoute({ token: process.env.XENIA_SDK_TOKEN, revalidate });
+ * ```
+ */
+declare function createManifestRoute(opts: {
+    token?: string;
+    baseUrl?: string;
+    revalidate?: number;
+}): () => Promise<Response>;
+/**
+ * `POST` for Xenia's storefront webhook (Journey Orchestrator → Storefront webhook): verifies the
+ * signature (`verifyWebhook`), answers `ping`, and on `manifest.changed` regenerates `paths` (the
+ * manifest route) at once, then runs `onManifestChanged` (e.g. a rebuild hook) and merges what it
+ * returns into the response.
+ */
+declare function createRevalidateRoute(opts: {
+    secret?: string;
+    paths: string[];
+    onManifestChanged?: () => Promise<Record<string, unknown>> | Record<string, unknown>;
+}): (request: Request) => Promise<Response>;
+
+/** One page's entry in the edge debug cookie (written by `xeniaEdgeProxy({ debug })`, read by `<XeniaDebugPanel>`). */
+type DebugEntry = Record<string, unknown> & {
+    page: string;
+};
+/** The debug cookie's pages (it may arrive encoded once or twice); anything unreadable is none. */
+declare function readDebugEntries(raw: string | undefined | null): Record<string, DebugEntry>;
+
+/**
+ * QA and debugging for the edge flow (`xeniaEdgeProxy`'s `qa` and `debug` options):
+ * - QA overrides: `?xn_geo=<city>` places the visitor in a QA city, `?xn_date=YYYY-MM-DD` decides
+ *   as of that day (midday in the US), `?xn_geo=off` forgets them; kept for the visit in a cookie;
+ * - the debug cookie: what was decided for each of the last few pages, read by `<XeniaDebugPanel>`.
+ *   A cookie rather than the HTML, because variant pages are cached and shared.
+ */
+
+/** Cities a QA visitor can be placed in, with what an edge would report for them. */
+declare const QA_CITIES: Record<string, ViewerGeo>;
+interface QaState {
+    geo?: string;
+    date?: string;
+}
 
 /**
  * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.
@@ -13,8 +189,6 @@ import '../api-CktVQ6Gl.js';
  * visitor id).
  */
 
-/** Request header `xeniaProxy()` stamps with the URL being served. */
-declare const URL_HEADER = "x-xenia-url";
 interface XeniaProxyOptions {
     /** Request headers to forward (e.g. your own additions); defaults to the incoming ones. */
     headers?: Headers;
@@ -71,4 +245,4 @@ declare function consentFromNext(prefix?: string): Promise<ConsentState>;
  */
 declare function personalizeOnce<T>(key: string, personalize: () => Promise<T>): Promise<T>;
 
-export { URL_HEADER, type XeniaProxyOptions, consentFromNext, personalizeOnce, xeniaProxy, xeniaServerFromNext };
+export { type DebugEntry, type EdgeDecisionInfo, type EdgeExit, type EdgeRequestContext, QA_CITIES, type QaState, URL_HEADER, type XeniaEdgeProxyOptions, type XeniaProxyOptions, consentFromNext, createManifestRoute, createRevalidateRoute, personalizeOnce, readDebugEntries, xeniaEdgeProxy, xeniaProxy, xeniaServerFromNext };