@probat/react 0.4.5 → 0.4.6

package/dist/index.d.mts

@@ -4,9 +4,9 @@ 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;
-    /** API key for authenticating SDK requests (probat_sk_...) */
+    /** Publishable API key for authenticating SDK requests (probat_pk_...) */
     apiKey?: string;
     /**
      * Bootstrap assignments to avoid flash on first render.
@@ -14,6 +14,8 @@ interface ProbatProviderProps {
      * 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;
 }
 
@@ -148,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.
@@ -163,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
@@ -175,9 +207,9 @@ 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.
@@ -188,7 +220,8 @@ declare function fetchDecision(host: string, experimentId: string, distinctId: s
 /**
  * Fire-and-forget metric send. Never throws.
  */
-declare function sendMetric(host: string, event: string, properties: Record<string, unknown>, apiKey?: string): 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
@@ -216,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,9 +4,9 @@ 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;
-    /** API key for authenticating SDK requests (probat_sk_...) */
+    /** Publishable API key for authenticating SDK requests (probat_pk_...) */
     apiKey?: string;
     /**
      * Bootstrap assignments to avoid flash on first render.
@@ -14,6 +14,8 @@ interface ProbatProviderProps {
      * 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;
 }
 
@@ -148,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.
@@ -163,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
@@ -175,9 +207,9 @@ 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.
@@ -188,7 +220,8 @@ declare function fetchDecision(host: string, experimentId: string, distinctId: s
 /**
  * Fire-and-forget metric send. Never throws.
  */
-declare function sendMetric(host: string, event: string, properties: Record<string, unknown>, apiKey?: string): 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
@@ -216,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 };