@sentientui/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,136 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SentientConfig, SentientClient } from '@sentientui/core';
+export { deriveSessionSegment as detectSegment } from '@sentientui/core';
+
+/** How to render adaptive slots during SSR when assignments are not preloaded. */
+type SsrFallback = 'first' | 'none';
+type AdaptiveProviderProps = {
+    apiKey: string;
+    context: SentientConfig['context'];
+    ingestUrl: string;
+    debug?: boolean;
+    /**
+     * SSR-preloaded assignments from `preloadAssignments()` / `loadAdaptiveAssignments()`.
+     * Passed through to `useAssignment` as synchronous initial state so crawlers and
+     * the first paint see real content (recommended for SEO).
+     */
+    initialAssignments?: Record<string, string>;
+    /**
+     * Bandit segment from SSR (`device:source`). Keeps cache, assign, and worker
+     * weights on one row — must match `loadAdaptiveAssignments` / session upsert.
+     */
+    sessionSegment?: string;
+    /**
+     * When no `initialAssignments` exist for a component, `'first'` renders
+     * `variantIds[0]` in server HTML (safe default for SEO). Use `'none'` only for
+     * decorative slots marked `clientOnly`.
+     * @default 'first'
+     */
+    ssrFallback?: SsrFallback;
+    /**
+     * Consent gate. When `false` the SDK is not initialised and no events are
+     * sent. Flip to `true` (e.g. after the user accepts the cookie banner) to
+     * initialise and begin tracking.
+     */
+    consent?: boolean;
+    /**
+     * Called once per component the first time a variant is resolved for that
+     * component in this session. Use to forward assignments to your own analytics
+     * (Mixpanel, PostHog, Segment, etc.) without having to wrap `useAssignment`.
+     */
+    onAssignment?: (componentId: string, variantId: string) => void;
+    children: ReactNode;
+};
+/**
+ * Initialises the Sentient core SDK in a useEffect (SSR-safe) and exposes the
+ * client via React context. Re-initialises when `consent` changes.
+ */
+declare function AdaptiveProvider(props: AdaptiveProviderProps): JSX.Element;
+/**
+ * Returns the SentientClient, or null until the provider has finished
+ * initialising on the client.
+ */
+declare function useSentient(): SentientClient | null;
+/** Internal: SSR-preloaded assignments for hydration-safe first render. */
+declare function useInitialAssignments(): Record<string, string>;
+
+type ScrollDepthGoal = {
+    type: 'scroll_depth';
+    threshold: number;
+};
+type ClickGoal = {
+    type: 'click';
+    selector?: string;
+};
+type FormSubmitGoal = {
+    type: 'form_submit';
+};
+type CompositeGoal = {
+    type: 'composite';
+    all: GoalConfig[];
+};
+type GoalConfig = ScrollDepthGoal | ClickGoal | FormSubmitGoal | CompositeGoal;
+type AdaptiveProps = {
+    id: string;
+    variants: Record<string, ReactNode>;
+    goal: string | GoalConfig;
+    /**
+     * When true, renders nothing during SSR and before client hydration.
+     * Use when you cannot pass `initialAssignments` and prefer a blank slot over
+     * a hydration mismatch. Tradeoff: minor CLS on first paint.
+     */
+    clientOnly?: boolean;
+};
+declare function AdaptiveImpl(props: AdaptiveProps): JSX.Element | null;
+/** Re-renders only when the chosen variant changes. */
+declare const Adaptive: react.MemoExoticComponent<typeof AdaptiveImpl>;
+
+declare global {
+    interface Window {
+        __sentient_overrides?: Record<string, string>;
+    }
+}
+type AssignmentState = {
+    variantId: string | null;
+    isLoading: boolean;
+};
+/**
+ * Returns a sticky variant assignment for a component.
+ *
+ * First render reads the local SDK cache; if empty, falls back to a
+ * deterministic default and asynchronously calls `/v1/assign`. The server
+ * picks the actual variant via ε-greedy and the result replaces the fallback
+ * on the next render. Subsequent paints read synchronously from cache —
+ * no flicker, no loading state after first paint.
+ */
+declare function useAssignment(componentId: string, variantIds: string[]): AssignmentState;
+
+/** Per-component weights store with isolated subscriptions. */
+type VariantWeight = {
+    variantId: string;
+    pulls: number;
+    avgReward: number;
+};
+type ComponentWeights = {
+    componentId: string;
+    variants: VariantWeight[];
+    updatedAt: number;
+};
+type Listener = (weights: ComponentWeights) => void;
+/**
+ * Subscribes a listener to a single component. Returns an unsubscribe function.
+ * Updates to other components never trigger this listener.
+ */
+declare function subscribe(componentId: string, cb: Listener): () => void;
+/**
+ * Replaces the weights for a component and notifies only that component's
+ * subscribers.
+ */
+declare function update(componentId: string, weights: ComponentWeights): void;
+/**
+ * Returns the latest known weights for a component, or null if none seen.
+ */
+declare function getWeights(componentId: string): ComponentWeights | null;
+
+export { Adaptive, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FormSubmitGoal, type GoalConfig, type ScrollDepthGoal, type SsrFallback, type VariantWeight, getWeights, subscribe as subscribeWeights, update as updateWeights, useAssignment, useInitialAssignments, useSentient };

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SentientConfig, SentientClient } from '@sentientui/core';
+export { deriveSessionSegment as detectSegment } from '@sentientui/core';
+
+/** How to render adaptive slots during SSR when assignments are not preloaded. */
+type SsrFallback = 'first' | 'none';
+type AdaptiveProviderProps = {
+    apiKey: string;
+    context: SentientConfig['context'];
+    ingestUrl: string;
+    debug?: boolean;
+    /**
+     * SSR-preloaded assignments from `preloadAssignments()` / `loadAdaptiveAssignments()`.
+     * Passed through to `useAssignment` as synchronous initial state so crawlers and
+     * the first paint see real content (recommended for SEO).
+     */
+    initialAssignments?: Record<string, string>;
+    /**
+     * Bandit segment from SSR (`device:source`). Keeps cache, assign, and worker
+     * weights on one row — must match `loadAdaptiveAssignments` / session upsert.
+     */
+    sessionSegment?: string;
+    /**
+     * When no `initialAssignments` exist for a component, `'first'` renders
+     * `variantIds[0]` in server HTML (safe default for SEO). Use `'none'` only for
+     * decorative slots marked `clientOnly`.
+     * @default 'first'
+     */
+    ssrFallback?: SsrFallback;
+    /**
+     * Consent gate. When `false` the SDK is not initialised and no events are
+     * sent. Flip to `true` (e.g. after the user accepts the cookie banner) to
+     * initialise and begin tracking.
+     */
+    consent?: boolean;
+    /**
+     * Called once per component the first time a variant is resolved for that
+     * component in this session. Use to forward assignments to your own analytics
+     * (Mixpanel, PostHog, Segment, etc.) without having to wrap `useAssignment`.
+     */
+    onAssignment?: (componentId: string, variantId: string) => void;
+    children: ReactNode;
+};
+/**
+ * Initialises the Sentient core SDK in a useEffect (SSR-safe) and exposes the
+ * client via React context. Re-initialises when `consent` changes.
+ */
+declare function AdaptiveProvider(props: AdaptiveProviderProps): JSX.Element;
+/**
+ * Returns the SentientClient, or null until the provider has finished
+ * initialising on the client.
+ */
+declare function useSentient(): SentientClient | null;
+/** Internal: SSR-preloaded assignments for hydration-safe first render. */
+declare function useInitialAssignments(): Record<string, string>;
+
+type ScrollDepthGoal = {
+    type: 'scroll_depth';
+    threshold: number;
+};
+type ClickGoal = {
+    type: 'click';
+    selector?: string;
+};
+type FormSubmitGoal = {
+    type: 'form_submit';
+};
+type CompositeGoal = {
+    type: 'composite';
+    all: GoalConfig[];
+};
+type GoalConfig = ScrollDepthGoal | ClickGoal | FormSubmitGoal | CompositeGoal;
+type AdaptiveProps = {
+    id: string;
+    variants: Record<string, ReactNode>;
+    goal: string | GoalConfig;
+    /**
+     * When true, renders nothing during SSR and before client hydration.
+     * Use when you cannot pass `initialAssignments` and prefer a blank slot over
+     * a hydration mismatch. Tradeoff: minor CLS on first paint.
+     */
+    clientOnly?: boolean;
+};
+declare function AdaptiveImpl(props: AdaptiveProps): JSX.Element | null;
+/** Re-renders only when the chosen variant changes. */
+declare const Adaptive: react.MemoExoticComponent<typeof AdaptiveImpl>;
+
+declare global {
+    interface Window {
+        __sentient_overrides?: Record<string, string>;
+    }
+}
+type AssignmentState = {
+    variantId: string | null;
+    isLoading: boolean;
+};
+/**
+ * Returns a sticky variant assignment for a component.
+ *
+ * First render reads the local SDK cache; if empty, falls back to a
+ * deterministic default and asynchronously calls `/v1/assign`. The server
+ * picks the actual variant via ε-greedy and the result replaces the fallback
+ * on the next render. Subsequent paints read synchronously from cache —
+ * no flicker, no loading state after first paint.
+ */
+declare function useAssignment(componentId: string, variantIds: string[]): AssignmentState;
+
+/** Per-component weights store with isolated subscriptions. */
+type VariantWeight = {
+    variantId: string;
+    pulls: number;
+    avgReward: number;
+};
+type ComponentWeights = {
+    componentId: string;
+    variants: VariantWeight[];
+    updatedAt: number;
+};
+type Listener = (weights: ComponentWeights) => void;
+/**
+ * Subscribes a listener to a single component. Returns an unsubscribe function.
+ * Updates to other components never trigger this listener.
+ */
+declare function subscribe(componentId: string, cb: Listener): () => void;
+/**
+ * Replaces the weights for a component and notifies only that component's
+ * subscribers.
+ */
+declare function update(componentId: string, weights: ComponentWeights): void;
+/**
+ * Returns the latest known weights for a component, or null if none seen.
+ */
+declare function getWeights(componentId: string): ComponentWeights | null;
+
+export { Adaptive, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FormSubmitGoal, type GoalConfig, type ScrollDepthGoal, type SsrFallback, type VariantWeight, getWeights, subscribe as subscribeWeights, update as updateWeights, useAssignment, useInitialAssignments, useSentient };