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

package/dist/nuxt/server-8v6OHbsw.d.ts

@@ -0,0 +1,158 @@
+interface PreprSegment {
+    readonly _id: string;
+    readonly name: string;
+}
+/**
+ * Per-feature config. `false` is shorthand for `{ enabled: false }`; the object
+ * form leaves room for per-feature options later without a breaking change.
+ */
+type PreprFeatureConfig = boolean | {
+    enabled?: boolean;
+};
+/** Toolkit features a consumer can turn off. Omitted keys stay enabled. */
+interface PreprFeatures {
+    /** Segment picker, `Prepr-Segments` header and its cookie/query param. */
+    segments?: PreprFeatureConfig;
+    /** A/B variant switch, `Prepr-ABtesting` header and its cookie/query param. */
+    abTesting?: PreprFeatureConfig;
+    /**
+     * The site's own click-to-edit: the toolbar's Edit mode control, the stega
+     * tooltip/overlay and the close-edit pill.
+     *
+     * NOT a security control, and NOT the Prepr editor's live preview. When the
+     * site is framed by the editor, `prepr:initVE` still activates edit mode —
+     * that is the CMS operating inside its own iframe, not an affordance offered
+     * to visitors. See iframe-bridge.ts.
+     */
+    editMode?: PreprFeatureConfig;
+}
+interface PreprToolbarProps {
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
+    /** Available segments to personalize on. */
+    readonly segments?: readonly PreprSegment[];
+    /** @deprecated Alias for `segments`. */
+    readonly data?: readonly PreprSegment[];
+}
+type PreprVariant = 'A' | 'B';
+interface PreprHeaders {
+    readonly 'prepr-customer-id'?: string;
+    readonly 'Prepr-Segments'?: string;
+    readonly 'Prepr-ABtesting'?: PreprVariant;
+    readonly 'Prepr-Preview-Bar'?: 'true';
+    readonly 'Prepr-Context-utm_source'?: string;
+    readonly 'Prepr-Context-utm_medium'?: string;
+    readonly 'Prepr-Context-utm_term'?: string;
+    readonly 'Prepr-Context-utm_content'?: string;
+    readonly 'Prepr-Context-utm_campaign'?: string;
+    readonly 'Prepr-Context-initial_referral'?: string;
+    readonly 'Prepr-Visitor-IP'?: string;
+    readonly 'Prepr-Hubspot-Id'?: string;
+    readonly 'Prepr-Customer-Id-Created'?: 'true';
+    /** The visitor's browser User-Agent, used by the API for device detection. */
+    readonly 'User-Agent'?: string;
+    /** @deprecated Never populated; the visitor's value is under `User-Agent`. */
+    readonly 'Prepr-User-Agent'?: string;
+    readonly 'Prepr-Package'?: string;
+}
+type PreprErrorCode = 'INVALID_TOKEN' | 'MISSING_TOKEN' | 'HTTP_ERROR' | 'FETCH_ERROR' | 'INVALID_RESPONSE' | 'CONTEXT_ERROR' | 'GRAPHQL_ERROR' | 'INVALID_DOCUMENT';
+
+interface PreprMiddlewareOptions {
+    /** Enable preview-mode headers (segment/AB overrides, preview bar). */
+    preview?: boolean;
+    /**
+     * Disable features app-wide. Pass the same object you give the toolbar: a
+     * disabled feature injects no header and persists no cookie, whatever the
+     * request carries.
+     */
+    features?: PreprFeatures;
+    /** Override the version reported in Prepr-Package (mainly for tests). */
+    version?: string;
+}
+
+/**
+ * Structural stand-in for h3's `H3Event`, so this package needs no build-time
+ * dependency on `h3`/`nuxt`. Only the fields `handlePreprRequest` uses.
+ *
+ * `node` ties this to Nitro's Node.js preset (the Nuxt default). Edge presets
+ * expose no raw Node request/response to fold headers back onto.
+ */
+interface H3EventLike {
+    node: {
+        req: {
+            url?: string;
+            headers: Record<string, string | string[] | undefined>;
+        };
+        res: {
+            /** Node's `ServerResponse.appendHeader` (Node >= 18.3). */
+            appendHeader(name: string, value: string): unknown;
+        };
+    };
+    /** Request-scoped bag shared with route handlers and Vue via `useRequestEvent`. */
+    context: Record<string, unknown>;
+}
+/** Key under which `handlePreprRequest` mirrors the forwarded Prepr `Headers`. */
+declare const PREPR_CONTEXT_KEY = "prepr";
+/**
+ * Nuxt server middleware entry point — call it inside `defineEventHandler` in
+ * `server/middleware/prepr.ts`:
+ *
+ * ```ts
+ * export default defineEventHandler(event => {
+ *   handlePreprRequest(event, { preview: import.meta.dev });
+ * });
+ * ```
+ *
+ * The computed Prepr headers are folded back onto the raw Node request
+ * (lowercased, as Node stores them), which is what `useRequestHeaders()` and
+ * downstream handlers read. The same `Headers` are mirrored onto
+ * `event.context.prepr` for callers who prefer an explicit read
+ * (`getPreprHeadersFromEvent`). Cookies are appended to the response.
+ */
+declare function handlePreprRequest(event: H3EventLike, options?: PreprMiddlewareOptions): void;
+/**
+ * Personalization headers to forward to your GraphQL fetch, from the h3 event.
+ * Empty `Headers` if `handlePreprRequest` did not run, so the result is always
+ * safe to spread.
+ */
+declare function getPreprHeadersFromEvent(event: Pick<H3EventLike, 'context'>): Headers;
+
+/**
+ * Whether a Prepr GraphQL response differs per visitor, read from its `Vary`
+ * header. Use it when fetching with your own GraphQL client; the toolkit's
+ * `createPreprClient` already returns it as `personalized`.
+ *
+ * Never throws; a response without `Vary` is not personalized.
+ */
+declare function isPersonalizedResponse(source: Response | Headers): boolean;
+
+/** 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);
+}
+/**
+ * Asserts `token` is the full `https://graphql.prepr.io/<token>` URL.
+ * @throws PreprError if the token is missing or not an HTTPS URL.
+ */
+declare function validatePreprToken(token: string): void;
+/**
+ * Pulls the access token out of a GraphQL URL: `https://graphql.prepr.io/abc123`
+ * -> `abc123`.
+ * @throws PreprError if the URL is not a valid `graphql.prepr.io` URL.
+ */
+declare function extractAccessToken(graphqlUrl: string): string;
+
+export { type H3EventLike as H, type PreprHeaders as P, PreprError as a, type PreprFeatures as b, type PreprToolbarProps as c, PREPR_CONTEXT_KEY as d, type PreprMiddlewareOptions as e, extractAccessToken as f, getPreprHeadersFromEvent as g, handlePreprRequest as h, isPersonalizedResponse as i, validatePreprToken as v };

package/dist/pixel-DwW7cXJm.d.cts

@@ -0,0 +1,49 @@
+/**
+ * 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
+ * up the handoff.
+ *
+ * The CDN script expects a queue stub to already exist when it loads, so the
+ * contract must be reproduced exactly:
+ *   - `window.prepr` pushes `arguments` onto `.queue` until the real script
+ *     lands and replaces `.process`.
+ *   - `.t` must be a `Date.now()` timestamp.
+ *   - The tag is inserted async, `src` cache-busted every 24h via
+ *     `Math.ceil(Date.now() / cacheTime) * cacheTime`.
+ */
+/** Config accepted by the CDN pixel. */
+interface PreprPixelConfig {
+    destinations?: {
+        googleTagManager?: boolean;
+    };
+    variantImpressionThreshold?: number;
+}
+type PreprQueueArgs = unknown[];
+interface PreprQueueFn {
+    (...args: PreprQueueArgs): void;
+    queue: PreprQueueArgs[];
+    t: number;
+    process?: (...args: PreprQueueArgs) => void;
+}
+declare global {
+    interface Window {
+        prepr?: PreprQueueFn;
+    }
+}
+/**
+ * Install the queue stub, inject the pixel script, then queue
+ * `('init', trackingId, config?)` and `('event', 'pageload')` in that order.
+ *
+ * Idempotent, and a no-op outside a browser.
+ */
+declare function loadTrackingPixel(trackingId: string, config?: PreprPixelConfig): void;
+/**
+ * Send a tracking event through `window.prepr`. Only depends on `window.prepr`
+ * existing, never on how it got installed. Warns once and returns quietly when
+ * no pixel is present.
+ */
+declare function trackEvent(name: string, data?: string | Record<string, unknown>): void;
+/** Loader-independent like `trackEvent`; warns once if no pixel is installed. */
+declare function setTrackingParam(key: string, value: string): void;
+
+export { type PreprPixelConfig as P, loadTrackingPixel as l, setTrackingParam as s, trackEvent as t };

package/dist/pixel-DwW7cXJm.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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
+ * up the handoff.
+ *
+ * The CDN script expects a queue stub to already exist when it loads, so the
+ * contract must be reproduced exactly:
+ *   - `window.prepr` pushes `arguments` onto `.queue` until the real script
+ *     lands and replaces `.process`.
+ *   - `.t` must be a `Date.now()` timestamp.
+ *   - The tag is inserted async, `src` cache-busted every 24h via
+ *     `Math.ceil(Date.now() / cacheTime) * cacheTime`.
+ */
+/** Config accepted by the CDN pixel. */
+interface PreprPixelConfig {
+    destinations?: {
+        googleTagManager?: boolean;
+    };
+    variantImpressionThreshold?: number;
+}
+type PreprQueueArgs = unknown[];
+interface PreprQueueFn {
+    (...args: PreprQueueArgs): void;
+    queue: PreprQueueArgs[];
+    t: number;
+    process?: (...args: PreprQueueArgs) => void;
+}
+declare global {
+    interface Window {
+        prepr?: PreprQueueFn;
+    }
+}
+/**
+ * Install the queue stub, inject the pixel script, then queue
+ * `('init', trackingId, config?)` and `('event', 'pageload')` in that order.
+ *
+ * Idempotent, and a no-op outside a browser.
+ */
+declare function loadTrackingPixel(trackingId: string, config?: PreprPixelConfig): void;
+/**
+ * Send a tracking event through `window.prepr`. Only depends on `window.prepr`
+ * existing, never on how it got installed. Warns once and returns quietly when
+ * no pixel is present.
+ */
+declare function trackEvent(name: string, data?: string | Record<string, unknown>): void;
+/** Loader-independent like `trackEvent`; warns once if no pixel is installed. */
+declare function setTrackingParam(key: string, value: string): void;
+
+export { type PreprPixelConfig as P, loadTrackingPixel as l, setTrackingParam as s, trackEvent as t };