@apex-inc/react 0.3.0

package/README.md

@@ -0,0 +1,125 @@
+# @apex-inc/react
+
+Embeddable React components for [Apex](https://apex.inc) communication surfaces.
+
+**v0.1 — MVP.** Ships `<ApexPreferenceCenter>` only. Embeddable inbox and web-push subscription components arrive in v0.2 once a design partner validates demand.
+
+## Install
+
+```bash
+npm install @apex-inc/react @apex-inc/sdk
+```
+
+## Quick start (styled default)
+
+```tsx
+import { ApexPreferenceCenter } from "@apex-inc/react";
+
+export default function PreferencesPage({ token }: { token: string }) {
+  return <ApexPreferenceCenter endUserAuth={{ token }} />;
+}
+```
+
+Server-side, mint the token with the Apex SDK:
+
+```ts
+// app/api/apex-token/route.ts (Next.js example)
+import { signEndUserToken } from "@apex-inc/sdk/tokens";
+
+export async function GET(request: Request) {
+  const user = await getCurrentUser(request);
+  const token = signEndUserToken({
+    workspaceKey: process.env.APEX_PROJECT_KEY!,
+    endUserId: user.id,
+    expiresIn: 3600,
+  });
+  return Response.json({ token });
+}
+```
+
+The token is short-lived by design — refresh from your server when it expires.
+
+## Customizing the look
+
+```tsx
+<ApexPreferenceCenter
+  endUserAuth={{ token }}
+  theme={{
+    accentColor: "#0066FF",
+    fontFamily: '"Inter", system-ui, sans-serif',
+    borderRadius: 12,
+  }}
+/>
+```
+
+## Headless — bring your own UI
+
+When the styled default doesn't match your design system, render the component with your own JSX:
+
+```tsx
+import { ApexPreferenceCenter, type ApexChannel } from "@apex-inc/react";
+
+const CHANNELS: ApexChannel[] = ["email", "inbox", "web_push", "mobile_push"];
+
+export default function PreferencesPage({ token }: { token: string }) {
+  return (
+    <ApexPreferenceCenter
+      endUserAuth={{ token }}
+      render={(state) => {
+        if (state.loading) return <Spinner />;
+        if (!state.prefs) return <ErrorState />;
+        return (
+          <YourCard>
+            {CHANNELS.map((ch) => (
+              <YourSwitch
+                key={ch}
+                label={ch}
+                checked={state.prefs!.channelPreferences[ch] ?? true}
+                onChange={(v) => state.setChannel(ch, v)}
+              />
+            ))}
+            <YourDangerSwitch
+              label="Unsubscribe from everything"
+              checked={state.prefs.globalOptOut}
+              onChange={state.setGlobalOptOut}
+            />
+          </YourCard>
+        );
+      }}
+    />
+  );
+}
+```
+
+Or use the `useApexPreferences` hook directly if you'd rather not nest your UI under a render prop.
+
+## API
+
+### `<ApexPreferenceCenter>` props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `endUserAuth` | `{ token: string }` or `{ sessionCookie: true }` | yes | Auth credentials. Use `{ token }` for any external host. |
+| `apiBaseUrl` | `string` | no | Defaults to `https://app.apex.inc`. Override for self-hosted Apex. |
+| `workspaceKey` | `string` | no | Workspace ID. Read from token claims when using `{ token }` auth. |
+| `endUserId` | `string` | no | End-user ID. Read from token claims when using `{ token }` auth. |
+| `theme` | `ApexThemeTokens` | no | Colour and font overrides for the styled default. |
+| `render` | `(state) => JSX` | no | Headless override. When provided, the styled default is skipped. |
+
+### `useApexPreferences(options)`
+
+Returns `{ prefs, loading, saving, saved, error, refresh, setGlobalOptOut, setChannel, setCommunicationOverride }`. Same options as the component minus `theme` and `render`.
+
+## What ships next
+
+The roadmap for v0.2 is gated on at least one production design partner asking for it. The most likely additions are:
+
+- `<ApexInbox>` — drop-in bell + dropdown that mirrors the dashboard's `NotificationBell`.
+- `useApexWebPushSubscription` — headless hook around `navigator.serviceWorker.register('/apex-push-sw.js')` + the subscribe endpoint.
+- An Apex-provided service-worker template you can copy into your `public/` folder.
+
+Until then, keep using Apex's hosted preferences page at `https://app.apex.inc/preferences/<token>` for the customer-facing inbox + web push surfaces.
+
+## License
+
+MIT

package/dist/ApexPreferenceCenter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `<ApexPreferenceCenter>` — drop-in component customers embed on
+ * their settings page so end-users can manage their Apex
+ * communication preferences.
+ *
+ * Two render modes share the same data layer:
+ *
+ *   1. Styled default (`<ApexPreferenceCenter />`). Inline styles
+ *      derived from `theme` props. Zero CSS-in-JS dependency, zero
+ *      CSS import, zero design-system mismatch risk on first paint —
+ *      "just drop the tag and ship."
+ *   2. Headless override. Pass a `render` prop or render the
+ *      `<ApexPreferenceCenter.Headless>` variant directly and use
+ *      `useApexPreferences` to bring your own UI. The hook does all
+ *      the fetching + mutation; your render function returns
+ *      whatever JSX matches your design system.
+ *
+ * The data layer is `useApexPreferences` — see that file for the
+ * exact contract. Both modes share it so the behaviour and error
+ * handling stay identical.
+ */
+import { type UseApexPreferencesOptions, type UseApexPreferencesResult } from "./useApexPreferences";
+import type { ApexThemeTokens } from "./types";
+export interface ApexPreferenceCenterProps extends UseApexPreferencesOptions {
+    /** Optional theme tokens for the styled default. Ignored for the headless variant. */
+    theme?: ApexThemeTokens;
+    /**
+     * Render override. When provided, the styled default is bypassed
+     * and the consumer renders the entire surface using the supplied
+     * hook state. Use this when your app has its own design system.
+     */
+    render?: (state: UseApexPreferencesResult) => React.ReactElement;
+}
+export declare function ApexPreferenceCenter(props: ApexPreferenceCenterProps): React.ReactElement;
+export declare namespace ApexPreferenceCenter {
+    var Headless: (props: UseApexPreferencesOptions & {
+        render: (state: UseApexPreferencesResult) => React.ReactElement;
+    }) => React.ReactElement;
+}
+//# sourceMappingURL=ApexPreferenceCenter.d.ts.map

package/dist/ApexPreferenceCenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApexPreferenceCenter.d.ts","sourceRoot":"","sources":["../src/ApexPreferenceCenter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAe,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,yBACf,SAAQ,yBAAyB;IACjC,sFAAsF;IACtF,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,KAAK,CAAC,YAAY,CAAC;CAClE;AAwBD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,yBAAyB,GAC/B,KAAK,CAAC,YAAY,CAKpB;yBAPe,oBAAoB;0BAgB3B,yBAAyB,GAAG;QACjC,MAAM,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,KAAK,CAAC,YAAY,CAAC;KACjE,KACA,KAAK,CAAC,YAAY"}

package/dist/ApexPreferenceCenter.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApexPreferenceCenter = ApexPreferenceCenter;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * `<ApexPreferenceCenter>` — drop-in component customers embed on
+ * their settings page so end-users can manage their Apex
+ * communication preferences.
+ *
+ * Two render modes share the same data layer:
+ *
+ *   1. Styled default (`<ApexPreferenceCenter />`). Inline styles
+ *      derived from `theme` props. Zero CSS-in-JS dependency, zero
+ *      CSS import, zero design-system mismatch risk on first paint —
+ *      "just drop the tag and ship."
+ *   2. Headless override. Pass a `render` prop or render the
+ *      `<ApexPreferenceCenter.Headless>` variant directly and use
+ *      `useApexPreferences` to bring your own UI. The hook does all
+ *      the fetching + mutation; your render function returns
+ *      whatever JSX matches your design system.
+ *
+ * The data layer is `useApexPreferences` — see that file for the
+ * exact contract. Both modes share it so the behaviour and error
+ * handling stay identical.
+ */
+const react_1 = require("react");
+const useApexPreferences_1 = require("./useApexPreferences");
+const CHANNEL_META = {
+    email: {
+        label: "Email",
+        description: "Marketing emails and product updates",
+    },
+    inbox: {
+        label: "Inbox",
+        description: "In-app messages that stay until you read them",
+    },
+    web_push: {
+        label: "Web push",
+        description: "Browser notifications on your laptop or desktop",
+    },
+    mobile_push: {
+        label: "Mobile push",
+        description: "Push notifications on your phone",
+    },
+};
+function ApexPreferenceCenter(props) {
+    const { theme, render, ...hookOptions } = props;
+    const state = (0, useApexPreferences_1.useApexPreferences)(hookOptions);
+    if (render)
+        return render(state);
+    return (0, jsx_runtime_1.jsx)(StyledPreferenceCenter, { state: state, theme: theme });
+}
+/**
+ * Headless variant — same component, but `render` is required. Use
+ * when your editor's auto-imports surface "the right way" to use the
+ * headless variant. Behaviourally identical to passing `render` to
+ * the default export.
+ */
+ApexPreferenceCenter.Headless = function Headless(props) {
+    const { render, ...hookOptions } = props;
+    const state = (0, useApexPreferences_1.useApexPreferences)(hookOptions);
+    return render(state);
+};
+// ─── Styled default ────────────────────────────────────────────────────────
+function StyledPreferenceCenter({ state, theme, }) {
+    const tokens = (0, react_1.useMemo)(() => ({
+        accentColor: theme?.accentColor ?? "#00BE7D",
+        backgroundColor: theme?.backgroundColor ?? "#ffffff",
+        textColor: theme?.textColor ?? "#1a1a2e",
+        borderRadius: theme?.borderRadius ?? 8,
+        fontFamily: theme?.fontFamily ?? "system-ui, -apple-system, sans-serif",
+    }), [theme]);
+    const containerStyle = {
+        fontFamily: tokens.fontFamily,
+        color: tokens.textColor,
+        backgroundColor: tokens.backgroundColor,
+        borderRadius: tokens.borderRadius,
+        maxWidth: 480,
+        margin: "0 auto",
+    };
+    if (state.loading) {
+        return ((0, jsx_runtime_1.jsx)("div", { style: { ...containerStyle, padding: 32, textAlign: "center" }, children: (0, jsx_runtime_1.jsx)("span", { style: { fontSize: 14, opacity: 0.6 }, children: "Loading preferences\u2026" }) }));
+    }
+    if (state.error && !state.prefs) {
+        return ((0, jsx_runtime_1.jsxs)("div", { style: { ...containerStyle, padding: 32, textAlign: "center" }, children: [(0, jsx_runtime_1.jsx)("p", { style: { fontSize: 14, color: "#EF4444", marginBottom: 8 }, children: "Couldn't load your preferences" }), (0, jsx_runtime_1.jsx)("p", { style: { fontSize: 12, opacity: 0.6 }, children: state.error })] }));
+    }
+    if (!state.prefs)
+        return (0, jsx_runtime_1.jsx)("div", { style: containerStyle });
+    const allOff = state.prefs.globalOptOut;
+    return ((0, jsx_runtime_1.jsxs)("div", { style: containerStyle, children: [(0, jsx_runtime_1.jsxs)("div", { style: { padding: "24px 0", borderBottom: "1px solid #e5e5e5" }, children: [(0, jsx_runtime_1.jsx)("h2", { style: { fontSize: 18, fontWeight: 600, margin: 0 }, children: "Notification preferences" }), (0, jsx_runtime_1.jsx)("p", { style: { fontSize: 13, opacity: 0.6, margin: "4px 0 0" }, children: "Choose how you want to hear from us. You can change this at any time." })] }), (0, jsx_runtime_1.jsxs)("section", { style: { padding: "20px 0" }, children: [(0, jsx_runtime_1.jsx)("h3", { style: {
+                            fontSize: 13,
+                            fontWeight: 600,
+                            textTransform: "uppercase",
+                            letterSpacing: 0.5,
+                            opacity: 0.5,
+                            margin: "0 0 12px",
+                        }, children: "Channels" }), Object.keys(CHANNEL_META).map((ch) => {
+                        const meta = CHANNEL_META[ch];
+                        // Legacy `in_app_push` alias coverage — see useApexPreferences.
+                        const stored = ch === "inbox"
+                            ? state.prefs?.channelPreferences.inbox ??
+                                state.prefs?.channelPreferences.in_app_push ??
+                                true
+                            : state.prefs?.channelPreferences[ch] ?? true;
+                        return ((0, jsx_runtime_1.jsxs)("label", { style: {
+                                display: "flex",
+                                alignItems: "flex-start",
+                                gap: 12,
+                                padding: "12px 0",
+                                borderBottom: "1px solid #f0f0f0",
+                                cursor: allOff ? "not-allowed" : "pointer",
+                                opacity: allOff ? 0.4 : 1,
+                            }, children: [(0, jsx_runtime_1.jsx)("input", { type: "checkbox", checked: !allOff && stored, onChange: (e) => void state.setChannel(ch, e.currentTarget.checked), disabled: allOff, style: {
+                                        marginTop: 2,
+                                        accentColor: tokens.accentColor,
+                                        width: 16,
+                                        height: 16,
+                                    } }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { style: { fontSize: 14, fontWeight: 500 }, children: meta.label }), (0, jsx_runtime_1.jsx)("div", { style: { fontSize: 12, opacity: 0.5, marginTop: 2 }, children: meta.description })] })] }, ch));
+                    })] }), (0, jsx_runtime_1.jsx)("section", { style: {
+                    padding: "20px 0",
+                    borderTop: "1px solid #e5e5e5",
+                }, children: (0, jsx_runtime_1.jsxs)("label", { style: {
+                        display: "flex",
+                        alignItems: "center",
+                        gap: 12,
+                        cursor: "pointer",
+                    }, children: [(0, jsx_runtime_1.jsx)("input", { type: "checkbox", checked: allOff, onChange: (e) => void state.setGlobalOptOut(e.currentTarget.checked), style: { accentColor: "#EF4444", width: 16, height: 16 } }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { style: { fontSize: 14, fontWeight: 500, color: "#EF4444" }, children: "Unsubscribe from all" }), (0, jsx_runtime_1.jsx)("div", { style: { fontSize: 12, opacity: 0.5, marginTop: 2 }, children: "Stop all communications. You can re-enable any time." })] })] }) }), (0, jsx_runtime_1.jsxs)("div", { style: { padding: "12px 0", textAlign: "center", minHeight: 24 }, children: [state.saving && ((0, jsx_runtime_1.jsx)("span", { style: { fontSize: 12, opacity: 0.5 }, children: "Saving\u2026" })), state.saved && ((0, jsx_runtime_1.jsx)("span", { style: { fontSize: 12, color: tokens.accentColor }, children: "\u2713 Preferences saved" })), state.error && state.prefs && ((0, jsx_runtime_1.jsx)("span", { style: { fontSize: 12, color: "#EF4444" }, children: state.error }))] })] }));
+}
+//# sourceMappingURL=ApexPreferenceCenter.js.map

package/dist/ApexPreferenceCenter.js.map

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

package/dist/esm/ApexPreferenceCenter.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `<ApexPreferenceCenter>` — drop-in component customers embed on
+ * their settings page so end-users can manage their Apex
+ * communication preferences.
+ *
+ * Two render modes share the same data layer:
+ *
+ *   1. Styled default (`<ApexPreferenceCenter />`). Inline styles
+ *      derived from `theme` props. Zero CSS-in-JS dependency, zero
+ *      CSS import, zero design-system mismatch risk on first paint —
+ *      "just drop the tag and ship."
+ *   2. Headless override. Pass a `render` prop or render the
+ *      `<ApexPreferenceCenter.Headless>` variant directly and use
+ *      `useApexPreferences` to bring your own UI. The hook does all
+ *      the fetching + mutation; your render function returns
+ *      whatever JSX matches your design system.
+ *
+ * The data layer is `useApexPreferences` — see that file for the
+ * exact contract. Both modes share it so the behaviour and error
+ * handling stay identical.
+ */
+import { useMemo } from "react";
+import { useApexPreferences, } from "./useApexPreferences";
+const CHANNEL_META = {
+    email: {
+        label: "Email",
+        description: "Marketing emails and product updates",
+    },
+    inbox: {
+        label: "Inbox",
+        description: "In-app messages that stay until you read them",
+    },
+    web_push: {
+        label: "Web push",
+        description: "Browser notifications on your laptop or desktop",
+    },
+    mobile_push: {
+        label: "Mobile push",
+        description: "Push notifications on your phone",
+    },
+};
+export function ApexPreferenceCenter(props) {
+    const { theme, render, ...hookOptions } = props;
+    const state = useApexPreferences(hookOptions);
+    if (render)
+        return render(state);
+    return _jsx(StyledPreferenceCenter, { state: state, theme: theme });
+}
+/**
+ * Headless variant — same component, but `render` is required. Use
+ * when your editor's auto-imports surface "the right way" to use the
+ * headless variant. Behaviourally identical to passing `render` to
+ * the default export.
+ */
+ApexPreferenceCenter.Headless = function Headless(props) {
+    const { render, ...hookOptions } = props;
+    const state = useApexPreferences(hookOptions);
+    return render(state);
+};
+// ─── Styled default ────────────────────────────────────────────────────────
+function StyledPreferenceCenter({ state, theme, }) {
+    const tokens = useMemo(() => ({
+        accentColor: theme?.accentColor ?? "#00BE7D",
+        backgroundColor: theme?.backgroundColor ?? "#ffffff",
+        textColor: theme?.textColor ?? "#1a1a2e",
+        borderRadius: theme?.borderRadius ?? 8,
+        fontFamily: theme?.fontFamily ?? "system-ui, -apple-system, sans-serif",
+    }), [theme]);
+    const containerStyle = {
+        fontFamily: tokens.fontFamily,
+        color: tokens.textColor,
+        backgroundColor: tokens.backgroundColor,
+        borderRadius: tokens.borderRadius,
+        maxWidth: 480,
+        margin: "0 auto",
+    };
+    if (state.loading) {
+        return (_jsx("div", { style: { ...containerStyle, padding: 32, textAlign: "center" }, children: _jsx("span", { style: { fontSize: 14, opacity: 0.6 }, children: "Loading preferences\u2026" }) }));
+    }
+    if (state.error && !state.prefs) {
+        return (_jsxs("div", { style: { ...containerStyle, padding: 32, textAlign: "center" }, children: [_jsx("p", { style: { fontSize: 14, color: "#EF4444", marginBottom: 8 }, children: "Couldn't load your preferences" }), _jsx("p", { style: { fontSize: 12, opacity: 0.6 }, children: state.error })] }));
+    }
+    if (!state.prefs)
+        return _jsx("div", { style: containerStyle });
+    const allOff = state.prefs.globalOptOut;
+    return (_jsxs("div", { style: containerStyle, children: [_jsxs("div", { style: { padding: "24px 0", borderBottom: "1px solid #e5e5e5" }, children: [_jsx("h2", { style: { fontSize: 18, fontWeight: 600, margin: 0 }, children: "Notification preferences" }), _jsx("p", { style: { fontSize: 13, opacity: 0.6, margin: "4px 0 0" }, children: "Choose how you want to hear from us. You can change this at any time." })] }), _jsxs("section", { style: { padding: "20px 0" }, children: [_jsx("h3", { style: {
+                            fontSize: 13,
+                            fontWeight: 600,
+                            textTransform: "uppercase",
+                            letterSpacing: 0.5,
+                            opacity: 0.5,
+                            margin: "0 0 12px",
+                        }, children: "Channels" }), Object.keys(CHANNEL_META).map((ch) => {
+                        const meta = CHANNEL_META[ch];
+                        // Legacy `in_app_push` alias coverage — see useApexPreferences.
+                        const stored = ch === "inbox"
+                            ? state.prefs?.channelPreferences.inbox ??
+                                state.prefs?.channelPreferences.in_app_push ??
+                                true
+                            : state.prefs?.channelPreferences[ch] ?? true;
+                        return (_jsxs("label", { style: {
+                                display: "flex",
+                                alignItems: "flex-start",
+                                gap: 12,
+                                padding: "12px 0",
+                                borderBottom: "1px solid #f0f0f0",
+                                cursor: allOff ? "not-allowed" : "pointer",
+                                opacity: allOff ? 0.4 : 1,
+                            }, children: [_jsx("input", { type: "checkbox", checked: !allOff && stored, onChange: (e) => void state.setChannel(ch, e.currentTarget.checked), disabled: allOff, style: {
+                                        marginTop: 2,
+                                        accentColor: tokens.accentColor,
+                                        width: 16,
+                                        height: 16,
+                                    } }), _jsxs("div", { children: [_jsx("div", { style: { fontSize: 14, fontWeight: 500 }, children: meta.label }), _jsx("div", { style: { fontSize: 12, opacity: 0.5, marginTop: 2 }, children: meta.description })] })] }, ch));
+                    })] }), _jsx("section", { style: {
+                    padding: "20px 0",
+                    borderTop: "1px solid #e5e5e5",
+                }, children: _jsxs("label", { style: {
+                        display: "flex",
+                        alignItems: "center",
+                        gap: 12,
+                        cursor: "pointer",
+                    }, children: [_jsx("input", { type: "checkbox", checked: allOff, onChange: (e) => void state.setGlobalOptOut(e.currentTarget.checked), style: { accentColor: "#EF4444", width: 16, height: 16 } }), _jsxs("div", { children: [_jsx("div", { style: { fontSize: 14, fontWeight: 500, color: "#EF4444" }, children: "Unsubscribe from all" }), _jsx("div", { style: { fontSize: 12, opacity: 0.5, marginTop: 2 }, children: "Stop all communications. You can re-enable any time." })] })] }) }), _jsxs("div", { style: { padding: "12px 0", textAlign: "center", minHeight: 24 }, children: [state.saving && (_jsx("span", { style: { fontSize: 12, opacity: 0.5 }, children: "Saving\u2026" })), state.saved && (_jsx("span", { style: { fontSize: 12, color: tokens.accentColor }, children: "\u2713 Preferences saved" })), state.error && state.prefs && (_jsx("span", { style: { fontSize: 12, color: "#EF4444" }, children: state.error }))] })] }));
+}

package/dist/esm/experiments.js

@@ -0,0 +1,200 @@
+"use client";
+/**
+ * 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.
+ */
+import { createContext, createElement, useContext, useEffect, useState } from "react";
+const ApexExperimentContext = createContext({});
+/**
+ * Provides experiment resolution config (apiBase / workspaceKey) to
+ * every `useApexVariant` call below it. Optional — per-call overrides
+ * and same-origin defaults work without it.
+ */
+export function ApexProvider(props) {
+    const value = {
+        apiBase: props.apiBase,
+        workspaceKey: props.workspaceKey,
+    };
+    return 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: ""`).
+ */
+export function useApexVariant(experimentId, overrides) {
+    const ctx = useContext(ApexExperimentContext);
+    const apiBase = overrides?.apiBase ?? ctx.apiBase ?? "";
+    const workspaceKey = overrides?.workspaceKey ?? ctx.workspaceKey;
+    const config = { apiBase, workspaceKey };
+    const [variant, setVariant] = 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";
+    });
+    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).
+ */
+export function clearApexVariant(experimentId) {
+    if (typeof window !== "undefined") {
+        localStorage.removeItem(`apex_var_${experimentId}`);
+    }
+}
+/**
+ * Check if currently in Apex preview mode for a specific experiment.
+ */
+export function useApexPreview(experimentId) {
+    const [state] = 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;
+}

package/dist/esm/index.js

@@ -0,0 +1,21 @@
+/**
+ * @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 { useApexPreferences, } from "./useApexPreferences";
+// ─── Code-level A/B experiments ───────────────────────────────────────────
+export { ApexProvider, useApexVariant, useApexPreview, clearApexVariant, } from "./experiments";