@probat/react 0.4.4 → 0.4.6

package/dist/index.d.mts

@@ -4,14 +4,18 @@ interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
      *  assignment (consistent across devices) and attached to all events. */
     customerId?: string;
-    /** Base URL for the Probat API. Defaults to https://gushi.onrender.com */
+    /** Base URL for the Probat API. Defaults to https://api.probat.app */
     host?: string;
+    /** Publishable API key for authenticating SDK requests (probat_pk_...) */
+    apiKey?: string;
     /**
      * Bootstrap assignments to avoid flash on first render.
      * Map of experiment id → variant key.
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
+    /** Automatically send $session_start/$session_end lifecycle events. */
+    trackSessionLifecycle?: boolean;
     children: React$1.ReactNode;
 }
 
@@ -69,6 +73,8 @@ interface UseTrackBaseOptions {
     experimentId: string;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
     componentInstanceId?: string;
+    /** Whether the variant assignment has been resolved. When false, all tracking is suppressed. */
+    resolved?: boolean;
     /** Auto-track impressions (default true) */
     impression?: boolean;
     /** Auto-track clicks (default true) */
@@ -144,10 +150,38 @@ interface UseExperimentReturn {
  * Resolves the variant assignment for an experiment.
  * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
  *
- * Priority: bootstrap > localStorage cache > fetchDecision.
+ * Priority: __probat_force URL param > bootstrap > localStorage cache > fetchDecision.
  */
 declare function useExperiment(id: string, options?: UseExperimentOptions): UseExperimentReturn;
 
+declare const PROBAT_ENV_DEV: "dev";
+declare const PROBAT_ENV_PROD: "prod";
+type ProbatEnvironment = typeof PROBAT_ENV_DEV | typeof PROBAT_ENV_PROD;
+type ProbatEventType = "$experiment_exposure" | "$experiment_click" | "$pageview" | "$pageleave" | "$session_start" | "$session_end" | "$goal_reached" | "$feature_interaction" | string;
+interface StructuredEventProperties {
+    distinct_id: string;
+    session_id: string;
+    $page_url: string;
+    $pathname: string;
+    $referrer: string;
+    captured_at: string;
+    environment: ProbatEnvironment;
+    source: "react-sdk" | "react-native-sdk";
+    $session_sequence: number;
+    $session_start_at: string;
+    experiment_id?: string;
+    variant_key?: string;
+    component_instance_id?: string;
+    $funnel_id?: string;
+    $funnel_step?: number;
+    [key: string]: unknown;
+}
+interface StructuredEvent {
+    event: ProbatEventType;
+    environment: ProbatEnvironment;
+    properties: StructuredEventProperties;
+}
+
 interface UseProbatMetricsReturn {
     /**
      * Send a custom event with arbitrary properties.
@@ -159,7 +193,9 @@ interface UseProbatMetricsReturn {
      * capture("purchase", { revenue: 42, currency: "USD" });
      * ```
      */
-    capture: (event: string, properties?: Record<string, unknown>) => void;
+    capture: (event: ProbatEventType, properties?: Record<string, unknown>) => void;
+    captureGoal: (funnelId: string, funnelStep: number, properties?: Record<string, unknown>) => void;
+    captureFeatureInteraction: (interactionName: string, properties?: Record<string, unknown>) => void;
 }
 /**
  * Minimal metrics hook. Provides a single `capture(event, props)` function
@@ -171,20 +207,21 @@ interface DecisionResponse {
     variant_key: string;
 }
 interface MetricPayload {
-    event: string;
-    environment: "dev" | "prod";
-    properties: Record<string, unknown>;
+    event: ProbatEventType;
+    environment: ProbatEnvironment;
+    properties: StructuredEventProperties;
 }
 /**
  * Fetch the variant assignment for an experiment.
  * Returns the variant key string (e.g. "control", "ai_v1").
  * Deduplicates concurrent calls for the same experiment.
  */
-declare function fetchDecision(host: string, experimentId: string, distinctId: string): Promise<string>;
+declare function fetchDecision(host: string, experimentId: string, distinctId: string, apiKey?: string): Promise<string>;
 /**
  * Fire-and-forget metric send. Never throws.
  */
-declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
+declare function sendMetric(host: string, event: ProbatEventType, properties: Record<string, unknown>, apiKey?: string): void;
+declare function flushMetrics(host: string, forceBeacon?: boolean, apiKey?: string): void;
 
 /**
  * Factory that creates a typed context + hook pair for passing a variantKey
@@ -212,4 +249,4 @@ declare function createExperimentContext(experimentId: string): {
     useVariantKey: () => string;
 };
 
-export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackCustomerOptions, type UseTrackExplicitOptions, type UseTrackOptions, createExperimentContext, fetchDecision, sendMetric, useExperiment, useProbatMetrics, useTrack };
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, PROBAT_ENV_DEV, PROBAT_ENV_PROD, type ProbatEnvironment, type ProbatEventType, ProbatProviderClient, type ProbatProviderProps, type StructuredEvent, type StructuredEventProperties, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackCustomerOptions, type UseTrackExplicitOptions, type UseTrackOptions, createExperimentContext, fetchDecision, flushMetrics, sendMetric, useExperiment, useProbatMetrics, useTrack };

package/dist/index.d.ts

@@ -4,14 +4,18 @@ interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
      *  assignment (consistent across devices) and attached to all events. */
     customerId?: string;
-    /** Base URL for the Probat API. Defaults to https://gushi.onrender.com */
+    /** Base URL for the Probat API. Defaults to https://api.probat.app */
     host?: string;
+    /** Publishable API key for authenticating SDK requests (probat_pk_...) */
+    apiKey?: string;
     /**
      * Bootstrap assignments to avoid flash on first render.
      * Map of experiment id → variant key.
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
+    /** Automatically send $session_start/$session_end lifecycle events. */
+    trackSessionLifecycle?: boolean;
     children: React$1.ReactNode;
 }
 
@@ -69,6 +73,8 @@ interface UseTrackBaseOptions {
     experimentId: string;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
     componentInstanceId?: string;
+    /** Whether the variant assignment has been resolved. When false, all tracking is suppressed. */
+    resolved?: boolean;
     /** Auto-track impressions (default true) */
     impression?: boolean;
     /** Auto-track clicks (default true) */
@@ -144,10 +150,38 @@ interface UseExperimentReturn {
  * Resolves the variant assignment for an experiment.
  * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
  *
- * Priority: bootstrap > localStorage cache > fetchDecision.
+ * Priority: __probat_force URL param > bootstrap > localStorage cache > fetchDecision.
  */
 declare function useExperiment(id: string, options?: UseExperimentOptions): UseExperimentReturn;
 
+declare const PROBAT_ENV_DEV: "dev";
+declare const PROBAT_ENV_PROD: "prod";
+type ProbatEnvironment = typeof PROBAT_ENV_DEV | typeof PROBAT_ENV_PROD;
+type ProbatEventType = "$experiment_exposure" | "$experiment_click" | "$pageview" | "$pageleave" | "$session_start" | "$session_end" | "$goal_reached" | "$feature_interaction" | string;
+interface StructuredEventProperties {
+    distinct_id: string;
+    session_id: string;
+    $page_url: string;
+    $pathname: string;
+    $referrer: string;
+    captured_at: string;
+    environment: ProbatEnvironment;
+    source: "react-sdk" | "react-native-sdk";
+    $session_sequence: number;
+    $session_start_at: string;
+    experiment_id?: string;
+    variant_key?: string;
+    component_instance_id?: string;
+    $funnel_id?: string;
+    $funnel_step?: number;
+    [key: string]: unknown;
+}
+interface StructuredEvent {
+    event: ProbatEventType;
+    environment: ProbatEnvironment;
+    properties: StructuredEventProperties;
+}
+
 interface UseProbatMetricsReturn {
     /**
      * Send a custom event with arbitrary properties.
@@ -159,7 +193,9 @@ interface UseProbatMetricsReturn {
      * capture("purchase", { revenue: 42, currency: "USD" });
      * ```
      */
-    capture: (event: string, properties?: Record<string, unknown>) => void;
+    capture: (event: ProbatEventType, properties?: Record<string, unknown>) => void;
+    captureGoal: (funnelId: string, funnelStep: number, properties?: Record<string, unknown>) => void;
+    captureFeatureInteraction: (interactionName: string, properties?: Record<string, unknown>) => void;
 }
 /**
  * Minimal metrics hook. Provides a single `capture(event, props)` function
@@ -171,20 +207,21 @@ interface DecisionResponse {
     variant_key: string;
 }
 interface MetricPayload {
-    event: string;
-    environment: "dev" | "prod";
-    properties: Record<string, unknown>;
+    event: ProbatEventType;
+    environment: ProbatEnvironment;
+    properties: StructuredEventProperties;
 }
 /**
  * Fetch the variant assignment for an experiment.
  * Returns the variant key string (e.g. "control", "ai_v1").
  * Deduplicates concurrent calls for the same experiment.
  */
-declare function fetchDecision(host: string, experimentId: string, distinctId: string): Promise<string>;
+declare function fetchDecision(host: string, experimentId: string, distinctId: string, apiKey?: string): Promise<string>;
 /**
  * Fire-and-forget metric send. Never throws.
  */
-declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
+declare function sendMetric(host: string, event: ProbatEventType, properties: Record<string, unknown>, apiKey?: string): void;
+declare function flushMetrics(host: string, forceBeacon?: boolean, apiKey?: string): void;
 
 /**
  * Factory that creates a typed context + hook pair for passing a variantKey
@@ -212,4 +249,4 @@ declare function createExperimentContext(experimentId: string): {
     useVariantKey: () => string;
 };
 
-export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackCustomerOptions, type UseTrackExplicitOptions, type UseTrackOptions, createExperimentContext, fetchDecision, sendMetric, useExperiment, useProbatMetrics, useTrack };
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, PROBAT_ENV_DEV, PROBAT_ENV_PROD, type ProbatEnvironment, type ProbatEventType, ProbatProviderClient, type ProbatProviderProps, type StructuredEvent, type StructuredEventProperties, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackCustomerOptions, type UseTrackExplicitOptions, type UseTrackOptions, createExperimentContext, fetchDecision, flushMetrics, sendMetric, useExperiment, useProbatMetrics, useTrack };