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

package/dist/sveltekit/server-CO847mEV.d.cts

@@ -0,0 +1,98 @@
+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';
+
+/**
+ * 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 PreprHeaders as P, PreprError as a, type PreprFeatures as b, type PreprToolbarProps as c, extractAccessToken as e, isPersonalizedResponse as i, validatePreprToken as v };

package/dist/sveltekit/server-CO847mEV.d.ts

@@ -0,0 +1,98 @@
+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';
+
+/**
+ * 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 PreprHeaders as P, PreprError as a, type PreprFeatures as b, type PreprToolbarProps as c, extractAccessToken as e, isPersonalizedResponse as i, validatePreprToken as v };

package/dist/{pixel-B3oQNbZ3.d.cts → types-BYH9XqmN.d.cts}

@@ -64,14 +64,8 @@ interface PreprPreviewOptions extends PreprToolbarOptions {
      */
     ui?: boolean;
     /**
-     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, e.g.
-     * `['http://acme.localhost:8000']`. Intended for self-hosted or locally run
-     * editors; when set, the wildcard no longer applies. Entries are compared to
-     * the editor's origin exactly: scheme, host and port.
-     *
-     * `['*']` accepts any editor origin. Use it for development only: any page
-     * that frames the preview can then switch on preview and edit mode and
-     * receives the field-edit events, which carry content item ids.
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list.
+     * Intended for self-hosted editors; when set, the wildcard no longer applies.
      */
     allowedEditorOrigins?: string[];
     /**
@@ -138,54 +132,6 @@ interface PreprHeaders {
     readonly 'Prepr-User-Agent'?: string;
     readonly 'Prepr-Package'?: string;
 }
-type PreprErrorCode = 'INVALID_TOKEN' | 'MISSING_TOKEN' | 'HTTP_ERROR' | 'FETCH_ERROR' | 'INVALID_RESPONSE' | 'CONTEXT_ERROR';
-
-/**
- * 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;
+type PreprErrorCode = 'INVALID_TOKEN' | 'MISSING_TOKEN' | 'HTTP_ERROR' | 'FETCH_ERROR' | 'INVALID_RESPONSE' | 'CONTEXT_ERROR' | 'GRAPHQL_ERROR' | 'INVALID_DOCUMENT';
 
-export { type Locale as L, type PreprFeatures as P, type ResolvedPreprFeatures as R, type PreprSegment as a, type PreprVariant as b, type PreprToolbarProps as c, type PreprPreviewOptions as d, type PreprErrorCode as e, type PreprHeaders as f, type PreprEnvironment as g, type PreprEventType as h, type PreprFeatureConfig as i, type PreprHeaderName as j, type PreprPixelConfig as k, type PreprToolbarComponentProps as l, type PreprToolbarOptions as m, loadTrackingPixel as n, setTrackingParam as s, trackEvent as t };
+export type { Locale as L, PreprHeaders as P, ResolvedPreprFeatures as R, PreprErrorCode as a, PreprFeatures as b, PreprSegment as c, PreprVariant as d, PreprToolbarProps as e, PreprPreviewOptions as f, PreprEnvironment as g, PreprEventType as h, PreprFeatureConfig as i, PreprHeaderName as j, PreprToolbarComponentProps as k, PreprToolbarOptions as l };

package/dist/{pixel-B3oQNbZ3.d.ts → types-BYH9XqmN.d.ts}

@@ -64,14 +64,8 @@ interface PreprPreviewOptions extends PreprToolbarOptions {
      */
     ui?: boolean;
     /**
-     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, e.g.
-     * `['http://acme.localhost:8000']`. Intended for self-hosted or locally run
-     * editors; when set, the wildcard no longer applies. Entries are compared to
-     * the editor's origin exactly: scheme, host and port.
-     *
-     * `['*']` accepts any editor origin. Use it for development only: any page
-     * that frames the preview can then switch on preview and edit mode and
-     * receives the field-edit events, which carry content item ids.
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list.
+     * Intended for self-hosted editors; when set, the wildcard no longer applies.
      */
     allowedEditorOrigins?: string[];
     /**
@@ -138,54 +132,6 @@ interface PreprHeaders {
     readonly 'Prepr-User-Agent'?: string;
     readonly 'Prepr-Package'?: string;
 }
-type PreprErrorCode = 'INVALID_TOKEN' | 'MISSING_TOKEN' | 'HTTP_ERROR' | 'FETCH_ERROR' | 'INVALID_RESPONSE' | 'CONTEXT_ERROR';
-
-/**
- * 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;
+type PreprErrorCode = 'INVALID_TOKEN' | 'MISSING_TOKEN' | 'HTTP_ERROR' | 'FETCH_ERROR' | 'INVALID_RESPONSE' | 'CONTEXT_ERROR' | 'GRAPHQL_ERROR' | 'INVALID_DOCUMENT';
 
-export { type Locale as L, type PreprFeatures as P, type ResolvedPreprFeatures as R, type PreprSegment as a, type PreprVariant as b, type PreprToolbarProps as c, type PreprPreviewOptions as d, type PreprErrorCode as e, type PreprHeaders as f, type PreprEnvironment as g, type PreprEventType as h, type PreprFeatureConfig as i, type PreprHeaderName as j, type PreprPixelConfig as k, type PreprToolbarComponentProps as l, type PreprToolbarOptions as m, loadTrackingPixel as n, setTrackingParam as s, trackEvent as t };
+export type { Locale as L, PreprHeaders as P, ResolvedPreprFeatures as R, PreprErrorCode as a, PreprFeatures as b, PreprSegment as c, PreprVariant as d, PreprToolbarProps as e, PreprPreviewOptions as f, PreprEnvironment as g, PreprEventType as h, PreprFeatureConfig as i, PreprHeaderName as j, PreprToolbarComponentProps as k, PreprToolbarOptions as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preprio/toolkit",
-  "version": "0.5.0-rc.2",
+  "version": "0.6.0-alpha.0",
   "description": "Prepr personalization, A/B testing and preview toolkit for React, Next.js, Nuxt, Astro, SvelteKit and Express",
   "license": "Apache-2.0",
   "author": "Prepr B.V. (https://prepr.io)",
@@ -39,6 +39,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./graphql": {
+      "types": "./dist/graphql.d.ts",
+      "import": "./dist/graphql.js",
+      "require": "./dist/graphql.cjs"
+    },
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
@@ -54,6 +59,11 @@
       "import": "./dist/nextjs/index.js",
       "require": "./dist/nextjs/index.cjs"
     },
+    "./nextjs/graphql": {
+      "types": "./dist/nextjs/graphql.d.ts",
+      "import": "./dist/nextjs/graphql.js",
+      "require": "./dist/nextjs/graphql.cjs"
+    },
     "./json-script": {
       "types": "./dist/json-script.d.ts",
       "import": "./dist/json-script.js",
@@ -74,18 +84,33 @@
       "import": "./dist/astro/index.js",
       "require": "./dist/astro/index.cjs"
     },
+    "./astro/graphql": {
+      "types": "./dist/astro/graphql.d.ts",
+      "import": "./dist/astro/graphql.js",
+      "require": "./dist/astro/graphql.cjs"
+    },
     "./astro/components/*": "./src/astro/*.astro",
     "./sveltekit": {
       "types": "./dist/sveltekit/index.d.ts",
       "import": "./dist/sveltekit/index.js",
       "require": "./dist/sveltekit/index.cjs"
     },
+    "./sveltekit/graphql": {
+      "types": "./dist/sveltekit/graphql.d.ts",
+      "import": "./dist/sveltekit/graphql.js",
+      "require": "./dist/sveltekit/graphql.cjs"
+    },
     "./sveltekit/components/*": "./src/sveltekit/*.svelte",
     "./nuxt": {
       "types": "./dist/nuxt/index.d.ts",
       "import": "./dist/nuxt/index.js",
       "require": "./dist/nuxt/index.cjs"
     },
+    "./nuxt/graphql": {
+      "types": "./dist/nuxt/graphql.d.ts",
+      "import": "./dist/nuxt/graphql.js",
+      "require": "./dist/nuxt/graphql.cjs"
+    },
     "./nuxt/components/*": "./src/nuxt/*.vue"
   },
   "files": [
@@ -109,6 +134,7 @@
     "preact": "^10.29.7"
   },
   "peerDependencies": {
+    "graphql": ">=16",
     "next": ">=13",
     "react": ">=17",
     "react-dom": ">=17",
@@ -116,6 +142,9 @@
     "vue": ">=3.3"
   },
   "peerDependenciesMeta": {
+    "graphql": {
+      "optional": true
+    },
     "next": {
       "optional": true
     },
@@ -137,6 +166,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "browserslist": "^4.28.7",
+    "graphql": "^16.14.2",
     "happy-dom": "^20.11.1",
     "lightningcss": "^1.33.0",
     "next": "^16.2.12",