@apex-inc/react 0.3.0

package/dist/useApexPreferences.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useApexPreferences = useApexPreferences;
+const react_1 = require("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 {};
+    }
+}
+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] = (0, react_1.useState)({
+        prefs: null,
+        loading: true,
+        saving: false,
+        saved: false,
+        error: null,
+    });
+    const authHeaders = (0, react_1.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 = (0, react_1.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 = (0, react_1.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]);
+    (0, react_1.useEffect)(() => {
+        void refresh();
+    }, [refresh]);
+    const save = (0, react_1.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 = (0, react_1.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 = (0, react_1.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 = (0, react_1.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,
+    };
+}
+//# sourceMappingURL=useApexPreferences.js.map

package/dist/useApexPreferences.js.map

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@apex-inc/react",
+  "version": "0.3.0",
+  "description": "React components and hooks for Apex — ApexPreferenceCenter for communication preferences plus useApexVariant for code-level A/B experiments.",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "skills"],
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.esm.json",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "apex",
+    "react",
+    "preferences",
+    "notifications",
+    "preference-center"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "typescript": "^5.7.0"
+  }
+}