@apex-inc/react 0.3.0

package/dist/esm/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for the @apex-inc/react package.
+ *
+ * Intentionally mirrors `EndUserCommPreferences` from the app source
+ * tree without importing it — the package has no dependency on the
+ * app workspace.
+ */
+export {};

package/dist/esm/useApexPreferences.js

@@ -0,0 +1,189 @@
+/**
+ * `useApexPreferences` — headless data hook backing the
+ * `<ApexPreferenceCenter>` component.
+ *
+ * Customers with their own design system import this hook directly
+ * and render their own controls. The default `<ApexPreferenceCenter>`
+ * built on top of this hook ships as the "drop a tag, get a working
+ * surface" path; the hook is the "I'll style it myself" path.
+ *
+ * The hook never throws — all errors land on `state.error` so the
+ * caller can render an inline message instead of an error boundary
+ * fallback. This matches the dashboard's own preference page UX.
+ */
+import { useCallback, useEffect, useState } from "react";
+const DEFAULT_API = "https://app.apex.inc";
+function decodeHmacEuid(token) {
+    // The Apex token shape is `<base64url-payload>.<base64url-sig>`.
+    // We only read the payload; the server re-verifies the signature
+    // on every call, so we never trust the decoded values on the
+    // client beyond using them as fetch parameters.
+    const parts = token.split(".");
+    if (parts.length !== 2)
+        return {};
+    try {
+        const padded = parts[0]
+            .replace(/-/g, "+")
+            .replace(/_/g, "/")
+            .padEnd(parts[0].length + ((4 - (parts[0].length % 4)) % 4), "=");
+        const json = atob(padded);
+        const obj = JSON.parse(json);
+        return { euid: obj.euid, pk: obj.pk };
+    }
+    catch {
+        return {};
+    }
+}
+export function useApexPreferences(options) {
+    const apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_API).replace(/\/$/, "");
+    // Resolve identity once. With token auth we crack open the payload
+    // to read the workspaceKey + endUserId; with cookie auth we require
+    // both as explicit props.
+    const tokenAuth = "token" in options.endUserAuth ? options.endUserAuth : null;
+    const decoded = tokenAuth ? decodeHmacEuid(tokenAuth.token) : null;
+    const endUserId = options.endUserId ?? decoded?.euid;
+    const workspaceKey = options.workspaceKey ?? decoded?.pk;
+    const [state, setState] = useState({
+        prefs: null,
+        loading: true,
+        saving: false,
+        saved: false,
+        error: null,
+    });
+    const authHeaders = useCallback(() => {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (tokenAuth) {
+            headers["Authorization"] = `Bearer ${tokenAuth.token}`;
+        }
+        if (workspaceKey) {
+            headers["x-workspace-key"] = workspaceKey;
+        }
+        return headers;
+    }, [tokenAuth, workspaceKey]);
+    const fetchOpts = useCallback(() => {
+        const init = { headers: authHeaders() };
+        if (!tokenAuth) {
+            // Cookie-auth callers need credentials forwarded to pick up the
+            // Apex dashboard's `apex_session` cookie.
+            init.credentials = "include";
+        }
+        return init;
+    }, [authHeaders, tokenAuth]);
+    const refresh = useCallback(async () => {
+        if (!endUserId) {
+            setState((s) => ({
+                ...s,
+                loading: false,
+                error: "endUserId not available — pass it explicitly or use a token-based auth.",
+            }));
+            return;
+        }
+        setState((s) => ({ ...s, loading: true, error: null }));
+        try {
+            const url = new URL(`/api/communications/preferences/${encodeURIComponent(endUserId)}`, apiBaseUrl);
+            if (workspaceKey)
+                url.searchParams.set("workspaceKey", workspaceKey);
+            const res = await fetch(url.toString(), fetchOpts());
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status}`);
+            }
+            const prefs = (await res.json());
+            setState((s) => ({ ...s, prefs, loading: false }));
+        }
+        catch (err) {
+            setState((s) => ({
+                ...s,
+                loading: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Failed to load preferences",
+            }));
+        }
+    }, [apiBaseUrl, endUserId, fetchOpts, workspaceKey]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    const save = useCallback(async (patch) => {
+        if (!endUserId)
+            return;
+        setState((s) => ({ ...s, saving: true, saved: false, error: null }));
+        try {
+            const url = new URL(`/api/communications/preferences/${encodeURIComponent(endUserId)}`, apiBaseUrl);
+            if (workspaceKey)
+                url.searchParams.set("workspaceKey", workspaceKey);
+            const res = await fetch(url.toString(), {
+                method: "PATCH",
+                ...fetchOpts(),
+                body: JSON.stringify(patch),
+            });
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status}`);
+            }
+            const saved = (await res.json());
+            setState((s) => ({ ...s, prefs: saved, saving: false, saved: true }));
+            // Clear the "saved!" badge after 2s — matches the dashboard.
+            setTimeout(() => {
+                setState((s) => ({ ...s, saved: false }));
+            }, 2000);
+        }
+        catch (err) {
+            setState((s) => ({
+                ...s,
+                saving: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Failed to save preferences",
+            }));
+        }
+    }, [apiBaseUrl, endUserId, fetchOpts, workspaceKey]);
+    const setGlobalOptOut = useCallback(async (value) => {
+        if (!state.prefs)
+            return;
+        const next = { ...state.prefs, globalOptOut: value };
+        setState((s) => ({ ...s, prefs: next }));
+        await save({ globalOptOut: value });
+    }, [save, state.prefs]);
+    const setChannel = useCallback(async (channel, enabled) => {
+        if (!state.prefs)
+            return;
+        // Mirror the legacy `in_app_push` alias when toggling `inbox`.
+        const channelPatch = {
+            [channel]: enabled,
+        };
+        if (channel === "inbox")
+            channelPatch.in_app_push = enabled;
+        const next = {
+            ...state.prefs,
+            channelPreferences: {
+                ...state.prefs.channelPreferences,
+                ...channelPatch,
+            },
+        };
+        setState((s) => ({ ...s, prefs: next }));
+        await save({ channelPreferences: channelPatch });
+    }, [save, state.prefs]);
+    const setCommunicationOverride = useCallback(async (communicationId, optedOut) => {
+        if (!state.prefs)
+            return;
+        const next = {
+            ...state.prefs,
+            communicationOverrides: {
+                ...state.prefs.communicationOverrides,
+                [communicationId]: { optedOut },
+            },
+        };
+        setState((s) => ({ ...s, prefs: next }));
+        await save({
+            communicationOverrides: { [communicationId]: { optedOut } },
+        });
+    }, [save, state.prefs]);
+    return {
+        ...state,
+        refresh,
+        setGlobalOptOut,
+        setChannel,
+        setCommunicationOverride,
+    };
+}

package/dist/experiments.d.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+export type Variant = "control" | "variant_b";
+/**
+ * Resolution config. `apiBase` defaults to "" (same-origin). When set
+ * (along with `workspaceKey` for cross-origin customer apps), requests
+ * carry the `x-apex-workspace` header and target the absolute base.
+ */
+export interface ApexExperimentConfig {
+    /** Apex API base URL, e.g. "https://app.apex.inc". Default "" (same-origin). */
+    apiBase?: string;
+    /** Workspace key — sent as the `x-apex-workspace` header when present. */
+    workspaceKey?: string;
+}
+/**
+ * Provides experiment resolution config (apiBase / workspaceKey) to
+ * every `useApexVariant` call below it. Optional — per-call overrides
+ * and same-origin defaults work without it.
+ */
+export declare function ApexProvider(props: {
+    apiBase?: string;
+    workspaceKey?: string;
+    children: ReactNode;
+}): JSX.Element;
+/**
+ * React hook for code-level A/B experiments.
+ *
+ * Returns "control" or "variant_b" based on:
+ *  1. Preview mode (?_apex_preview=variant_b&_apex_exp=<id>)
+ *  2. Cached assignment in localStorage
+ *  3. Server assignment (GET /api/experiments/{id}/assign?source=sdk)
+ *  4. Deterministic hash of visitorId + experimentId (fallback)
+ *
+ * Falls back to "control" on server render and on any error.
+ *
+ * Config resolution: per-call `overrides` win over `<ApexProvider>`
+ * context, which wins over the same-origin default (`apiBase: ""`).
+ */
+export declare function useApexVariant(experimentId: string, overrides?: ApexExperimentConfig): Variant;
+/**
+ * Clear a cached assignment (useful when an experiment is archived/completed).
+ */
+export declare function clearApexVariant(experimentId: string): void;
+/**
+ * Check if currently in Apex preview mode for a specific experiment.
+ */
+export declare function useApexPreview(experimentId?: string): {
+    isPreview: boolean;
+    previewVariant: Variant | null;
+};
+//# sourceMappingURL=experiments.d.ts.map

package/dist/experiments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments.d.ts","sourceRoot":"","sources":["../src/experiments.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,GAAG,CAAC,OAAO,CAMd;AAiFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,oBAAoB,GAC/B,OAAO,CA0DT;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC,CAaA"}

package/dist/experiments.js

@@ -0,0 +1,207 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApexProvider = ApexProvider;
+exports.useApexVariant = useApexVariant;
+exports.clearApexVariant = clearApexVariant;
+exports.useApexPreview = useApexPreview;
+/**
+ * Code-level A/B experiment hooks for customer React apps.
+ *
+ * This is the publishable generalization of the app-internal
+ * `useApexVariant` hook. The behavior is identical to the first-party
+ * web hook — preview params, localStorage cache, visitor cookie,
+ * assignment fetch, murmur-hash fallback, and the canonical
+ * `experiment_exposure` event (deduped per arm) — but the API base
+ * and workspace are configurable so it works from a CUSTOMER's origin,
+ * not just same-origin first-party apps.
+ *
+ * Configure once with `<ApexProvider apiBase="https://app.apex.inc"
+ * workspaceKey="ws_…">`, or pass `{ apiBase, workspaceKey }` per call.
+ * With no config the hook defaults to same-origin (`apiBase: ""`), so
+ * first-party apps keep working unchanged.
+ */
+const react_1 = require("react");
+const ApexExperimentContext = (0, react_1.createContext)({});
+/**
+ * Provides experiment resolution config (apiBase / workspaceKey) to
+ * every `useApexVariant` call below it. Optional — per-call overrides
+ * and same-origin defaults work without it.
+ */
+function ApexProvider(props) {
+    const value = {
+        apiBase: props.apiBase,
+        workspaceKey: props.workspaceKey,
+    };
+    return (0, react_1.createElement)(ApexExperimentContext.Provider, { value }, props.children);
+}
+function murmurhash3(key) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        h ^= key.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0) % 100;
+}
+function getVisitorId() {
+    if (typeof window === "undefined")
+        return "";
+    const key = "apex_vid";
+    const match = document.cookie.match(new RegExp(`(?:^|; )${key}=([^;]*)`));
+    if (match)
+        return decodeURIComponent(match[1]);
+    const id = crypto.randomUUID();
+    const d = new Date();
+    d.setTime(d.getTime() + 365 * 86400000);
+    document.cookie = `${key}=${encodeURIComponent(id)};expires=${d.toUTCString()};path=/;SameSite=Lax`;
+    return id;
+}
+function normalizeBase(apiBase) {
+    return (apiBase ?? "").replace(/\/$/, "");
+}
+function workspaceHeaders(workspaceKey) {
+    return workspaceKey ? { "x-apex-workspace": workspaceKey } : {};
+}
+/**
+ * Fire-once-per-arm exposure tracking. The denominator every experiment
+ * surface counts against (canonical `experiment_exposure` event). Deduped
+ * per (experiment, variant) for the page session so re-renders don't spam.
+ */
+const firedExposures = new Set();
+function fireExposure(experimentId, variant, config) {
+    if (typeof window === "undefined")
+        return;
+    const key = `${experimentId}:${variant}`;
+    if (firedExposures.has(key))
+        return;
+    firedExposures.add(key);
+    const visitorId = getVisitorId();
+    const base = normalizeBase(config.apiBase);
+    try {
+        void fetch(`${base}/api/events`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...workspaceHeaders(config.workspaceKey),
+            },
+            credentials: "include",
+            keepalive: true,
+            body: JSON.stringify({
+                type: "experiment_exposure",
+                visitorId,
+                url: window.location.href,
+                timestamp: new Date().toISOString(),
+                experimentId,
+                variant,
+                data: { experiment_id: experimentId, variant_key: variant, surface: "web" },
+            }),
+        }).catch(() => { });
+    }
+    catch {
+        /* exposure tracking is best-effort */
+    }
+}
+function getPreviewParams() {
+    if (typeof window === "undefined")
+        return null;
+    const params = new URLSearchParams(window.location.search);
+    const variant = params.get("_apex_preview");
+    const expId = params.get("_apex_exp");
+    if (variant)
+        return { variant, expId };
+    return null;
+}
+/**
+ * React hook for code-level A/B experiments.
+ *
+ * Returns "control" or "variant_b" based on:
+ *  1. Preview mode (?_apex_preview=variant_b&_apex_exp=<id>)
+ *  2. Cached assignment in localStorage
+ *  3. Server assignment (GET /api/experiments/{id}/assign?source=sdk)
+ *  4. Deterministic hash of visitorId + experimentId (fallback)
+ *
+ * Falls back to "control" on server render and on any error.
+ *
+ * Config resolution: per-call `overrides` win over `<ApexProvider>`
+ * context, which wins over the same-origin default (`apiBase: ""`).
+ */
+function useApexVariant(experimentId, overrides) {
+    const ctx = (0, react_1.useContext)(ApexExperimentContext);
+    const apiBase = overrides?.apiBase ?? ctx.apiBase ?? "";
+    const workspaceKey = overrides?.workspaceKey ?? ctx.workspaceKey;
+    const config = { apiBase, workspaceKey };
+    const [variant, setVariant] = (0, react_1.useState)(() => {
+        const preview = getPreviewParams();
+        if (preview && (!preview.expId || preview.expId === experimentId)) {
+            return preview.variant;
+        }
+        if (typeof window === "undefined")
+            return "control";
+        const cached = localStorage.getItem(`apex_var_${experimentId}`);
+        if (cached === "control" || cached === "variant_b")
+            return cached;
+        return "control";
+    });
+    (0, react_1.useEffect)(() => {
+        // Preview mode is the author previewing — not a real exposure.
+        const preview = getPreviewParams();
+        if (preview && (!preview.expId || preview.expId === experimentId))
+            return;
+        const cacheKey = `apex_var_${experimentId}`;
+        const cached = localStorage.getItem(cacheKey);
+        if (cached === "control" || cached === "variant_b") {
+            // Already assigned this session — still count the exposure (deduped).
+            fireExposure(experimentId, cached, config);
+            return;
+        }
+        const visitorId = getVisitorId();
+        if (!visitorId)
+            return;
+        const base = normalizeBase(apiBase);
+        fetch(`${base}/api/experiments/${experimentId}/assign?source=sdk`, {
+            credentials: "include",
+            headers: workspaceHeaders(workspaceKey),
+        })
+            .then((r) => {
+            if (!r.ok)
+                throw new Error(`${r.status}`);
+            return r.json();
+        })
+            .then((data) => {
+            localStorage.setItem(cacheKey, data.variant);
+            setVariant(data.variant);
+            fireExposure(experimentId, data.variant, config);
+        })
+            .catch(() => {
+            const bucket = murmurhash3(visitorId + experimentId);
+            const fallback = bucket < 50 ? "control" : "variant_b";
+            localStorage.setItem(cacheKey, fallback);
+            setVariant(fallback);
+            fireExposure(experimentId, fallback, config);
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [experimentId, apiBase, workspaceKey]);
+    return variant;
+}
+/**
+ * Clear a cached assignment (useful when an experiment is archived/completed).
+ */
+function clearApexVariant(experimentId) {
+    if (typeof window !== "undefined") {
+        localStorage.removeItem(`apex_var_${experimentId}`);
+    }
+}
+/**
+ * Check if currently in Apex preview mode for a specific experiment.
+ */
+function useApexPreview(experimentId) {
+    const [state] = (0, react_1.useState)(() => {
+        const preview = getPreviewParams();
+        if (preview && (!experimentId || !preview.expId || preview.expId === experimentId)) {
+            return { isPreview: true, previewVariant: preview.variant };
+        }
+        return { isPreview: false, previewVariant: null };
+    });
+    return state;
+}
+//# sourceMappingURL=experiments.js.map

package/dist/experiments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments.js","sourceRoot":"","sources":["../src/experiments.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @apex-inc/react — embeddable React components for Apex
+ * communication surfaces.
+ *
+ * MVP scope (v0.1):
+ *   - <ApexPreferenceCenter> — styled + headless variants.
+ *   - useApexPreferences — headless hook for full-custom UIs.
+ *
+ * Deferred to v0.2 (gated on design-partner demand):
+ *   - <ApexInbox> embeddable bell + drawer
+ *   - useApexWebPushSubscription
+ *   - Customer service-worker template
+ *
+ * Design rationale: every product on the planet needs a preferences
+ * UI; only some need an embedded inbox. Shipping the universal piece
+ * first lets us validate demand for the channel-specific pieces.
+ */
+export { ApexPreferenceCenter } from "./ApexPreferenceCenter";
+export type { ApexPreferenceCenterProps } from "./ApexPreferenceCenter";
+export { useApexPreferences, type UseApexPreferencesOptions, type UseApexPreferencesState, type UseApexPreferencesActions, type UseApexPreferencesResult, } from "./useApexPreferences";
+export type { ApexChannel, ApexChannelRead, ApexCommPreferences, ApexEndUserAuth, ApexThemeTokens, } from "./types";
+export { ApexProvider, useApexVariant, useApexPreview, clearApexVariant, type Variant, type ApexExperimentConfig, } from "./experiments";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,KAAK,OAAO,EACZ,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * @apex-inc/react — embeddable React components for Apex
+ * communication surfaces.
+ *
+ * MVP scope (v0.1):
+ *   - <ApexPreferenceCenter> — styled + headless variants.
+ *   - useApexPreferences — headless hook for full-custom UIs.
+ *
+ * Deferred to v0.2 (gated on design-partner demand):
+ *   - <ApexInbox> embeddable bell + drawer
+ *   - useApexWebPushSubscription
+ *   - Customer service-worker template
+ *
+ * Design rationale: every product on the planet needs a preferences
+ * UI; only some need an embedded inbox. Shipping the universal piece
+ * first lets us validate demand for the channel-specific pieces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearApexVariant = exports.useApexPreview = exports.useApexVariant = exports.ApexProvider = exports.useApexPreferences = exports.ApexPreferenceCenter = void 0;
+var ApexPreferenceCenter_1 = require("./ApexPreferenceCenter");
+Object.defineProperty(exports, "ApexPreferenceCenter", { enumerable: true, get: function () { return ApexPreferenceCenter_1.ApexPreferenceCenter; } });
+var useApexPreferences_1 = require("./useApexPreferences");
+Object.defineProperty(exports, "useApexPreferences", { enumerable: true, get: function () { return useApexPreferences_1.useApexPreferences; } });
+// ─── Code-level A/B experiments ───────────────────────────────────────────
+var experiments_1 = require("./experiments");
+Object.defineProperty(exports, "ApexProvider", { enumerable: true, get: function () { return experiments_1.ApexProvider; } });
+Object.defineProperty(exports, "useApexVariant", { enumerable: true, get: function () { return experiments_1.useApexVariant; } });
+Object.defineProperty(exports, "useApexPreview", { enumerable: true, get: function () { return experiments_1.useApexPreview; } });
+Object.defineProperty(exports, "clearApexVariant", { enumerable: true, get: function () { return experiments_1.clearApexVariant; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAE7B,2DAM8B;AAL5B,wHAAA,kBAAkB,OAAA;AAcpB,6EAA6E;AAC7E,6CAOuB;AANrB,2GAAA,YAAY,OAAA;AACZ,6GAAA,cAAc,OAAA;AACd,6GAAA,cAAc,OAAA;AACd,+GAAA,gBAAgB,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared types for the @apex-inc/react package.
+ *
+ * Intentionally mirrors `EndUserCommPreferences` from the app source
+ * tree without importing it — the package has no dependency on the
+ * app workspace.
+ */
+export type ApexChannel = "email" | "inbox" | "web_push" | "mobile_push";
+/**
+ * The legacy `in_app_push` channel still appears on records authored
+ * before DFC-007. Treated as an alias for `inbox` on read.
+ */
+export type ApexChannelRead = ApexChannel | "in_app_push";
+export interface ApexCommPreferences {
+    endUserId: string;
+    workspaceKey: string;
+    globalOptOut: boolean;
+    channelPreferences: Partial<Record<ApexChannelRead, boolean>>;
+    communicationOverrides: Record<string, {
+        optedOut: boolean;
+    }>;
+    journeyOverrides?: Record<string, {
+        optedOut: boolean;
+    }>;
+    updatedAt: string;
+}
+/**
+ * Auth credentials for the embedded preference center.
+ *
+ * Production integrations always pass `{ token }` — an Apex-signed
+ * HMAC token minted server-side via `apex.signEndUserToken(...)` (or
+ * the matching helper in the customer's preferred Apex SDK). The
+ * token carries `pk` (workspaceKey) and `euid` (endUserId), so the
+ * component doesn't need either prop separately.
+ *
+ * `{ sessionCookie: true }` is reserved for the Apex dashboard's own
+ * dogfood path — same-origin callers (us.apex.inc) can rely on the
+ * dashboard's Cognito session cookie. Customer apps embedding this
+ * component on their own domain must use a token.
+ */
+export type ApexEndUserAuth = {
+    token: string;
+} | {
+    sessionCookie: true;
+};
+export interface ApexThemeTokens {
+    /** Accent colour for the active checkbox. Defaults to Apex green (`#00BE7D`). */
+    accentColor?: string;
+    /** Background colour for the surrounding container. */
+    backgroundColor?: string;
+    /** Foreground text colour. */
+    textColor?: string;
+    /** Optional border radius in px. */
+    borderRadius?: number;
+    /** Font stack. */
+    fontFamily?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;AAEzE;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,aAAa,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,kBAAkB,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9D,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared types for the @apex-inc/react package.
+ *
+ * Intentionally mirrors `EndUserCommPreferences` from the app source
+ * tree without importing it — the package has no dependency on the
+ * app workspace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/useApexPreferences.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `useApexPreferences` — headless data hook backing the
+ * `<ApexPreferenceCenter>` component.
+ *
+ * Customers with their own design system import this hook directly
+ * and render their own controls. The default `<ApexPreferenceCenter>`
+ * built on top of this hook ships as the "drop a tag, get a working
+ * surface" path; the hook is the "I'll style it myself" path.
+ *
+ * The hook never throws — all errors land on `state.error` so the
+ * caller can render an inline message instead of an error boundary
+ * fallback. This matches the dashboard's own preference page UX.
+ */
+import type { ApexChannel, ApexCommPreferences, ApexEndUserAuth } from "./types";
+export interface UseApexPreferencesOptions {
+    /** Base URL of the Apex API. Defaults to `https://app.apex.inc`. */
+    apiBaseUrl?: string;
+    /**
+     * Workspace identifier. Required for `{ sessionCookie }` auth; for
+     * `{ token }` auth the value comes from the token's `pk` claim and
+     * passing it explicitly is optional.
+     */
+    workspaceKey?: string;
+    /**
+     * End-user identifier (their id in your system). Required for
+     * `{ sessionCookie }` auth; with `{ token }` auth the helper uses
+     * the token's `euid` claim.
+     */
+    endUserId?: string;
+    /** Auth credentials. See `ApexEndUserAuth` for the two shapes. */
+    endUserAuth: ApexEndUserAuth;
+}
+export interface UseApexPreferencesState {
+    prefs: ApexCommPreferences | null;
+    loading: boolean;
+    saving: boolean;
+    saved: boolean;
+    error: string | null;
+}
+export interface UseApexPreferencesActions {
+    refresh: () => Promise<void>;
+    setGlobalOptOut: (value: boolean) => Promise<void>;
+    setChannel: (channel: ApexChannel, enabled: boolean) => Promise<void>;
+    setCommunicationOverride: (communicationId: string, optedOut: boolean) => Promise<void>;
+}
+export type UseApexPreferencesResult = UseApexPreferencesState & UseApexPreferencesActions;
+export declare function useApexPreferences(options: UseApexPreferencesOptions): UseApexPreferencesResult;
+//# sourceMappingURL=useApexPreferences.d.ts.map

package/dist/useApexPreferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApexPreferences.d.ts","sourceRoot":"","sources":["../src/useApexPreferences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,eAAe,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,wBAAwB,EAAE,CACxB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,OAAO,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,MAAM,MAAM,wBAAwB,GAAG,uBAAuB,GAC5D,yBAAyB,CAAC;AA2B5B,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CA8K1B"}