@refraction-ui/react 0.7.0 → 0.9.0

package/dist/internal/analytics-sink-posthog/replay.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @refraction-ui/analytics-sink-posthog/replay
+ *
+ * OPTIONAL, lazy session-replay (rrweb, via `posthog-js`).
+ *
+ * Hard guarantees this module exists to enforce:
+ *
+ *  1. **Off by default.** Nothing in the main `@refraction-ui/analytics-sink-posthog`
+ *     entry imports this file, so it (and `posthog-js`, and rrweb) are fully
+ *     tree-shaken out of any bundle that does not explicitly import it.
+ *  2. **Never on the event path.** Replay is not an `AnalyticsSink`. It does
+ *     not see, transform, or block canonical envelopes. `track`/`identify`/…
+ *     keep flowing through the sink even if replay never starts or fails.
+ *  3. **Privacy/consent gated.** `startSessionReplay` refuses to start unless
+ *     a consent predicate returns true, and re-checks it; `stop()` tears the
+ *     recorder down. Masking defaults are maximally private.
+ *  4. **Lazy.** `posthog-js` is `import()`-ed only when `startSessionReplay`
+ *     is actually called.
+ *
+ * This is a thin controller around `posthog-js`'s built-in rrweb session
+ * recording — we do not bundle rrweb ourselves.
+ */
+/** Minimal structural view of the `posthog-js` replay surface. */
+interface PostHogReplay {
+    init(apiKey: string, options: Record<string, unknown>): void;
+    startSessionRecording(): void;
+    stopSessionRecording(): void;
+    sessionRecordingStarted?(): boolean;
+}
+interface SessionReplayOptions {
+    /** PostHog project API key. */
+    apiKey: string;
+    /** PostHog API host. Default `https://us.i.posthog.com`. */
+    host?: string;
+    /**
+     * Consent predicate. Replay starts ONLY when this returns `true`, and is
+     * re-checked by `enforceConsent()`. There is no default-allow: if omitted,
+     * replay is treated as NOT consented and will not start.
+     */
+    hasConsent?: () => boolean;
+    /**
+     * rrweb masking. Defaults are maximally private: all text + all inputs
+     * masked. Override deliberately and document the privacy review.
+     */
+    maskAllText?: boolean;
+    maskAllInputs?: boolean;
+    /** Extra `posthog-js` session_recording options (advanced). */
+    recordingOptions?: Record<string, unknown>;
+    /**
+     * Injected loader (testing / custom bundling). Defaults to a lazy
+     * `import('posthog-js')`.
+     */
+    loadPostHog?: () => Promise<{
+        default: PostHogReplay;
+    } | PostHogReplay>;
+}
+/** Handle returned by {@link startSessionReplay}. */
+interface SessionReplayHandle {
+    /** True if the rrweb recorder is currently running. */
+    readonly recording: boolean;
+    /**
+     * Re-evaluate the consent predicate. If consent was revoked, recording is
+     * stopped. Call this from your consent-change handler.
+     */
+    enforceConsent(): void;
+    /** Stop recording and release the recorder. Idempotent. */
+    stop(): void;
+}
+/**
+ * Start PostHog/rrweb session replay. Resolves to a handle, or to a
+ * non-recording handle if consent is not granted (it never throws on the
+ * consent path — replay simply does not start).
+ *
+ * `posthog-js` is dynamically imported here and nowhere else.
+ */
+declare function startSessionReplay(options: SessionReplayOptions): Promise<SessionReplayHandle>;
+
+export { type SessionReplayHandle, type SessionReplayOptions, startSessionReplay };

package/dist/internal/react-analytics/index.d.cts

@@ -1,6 +1,10 @@
 import * as React from 'react';
 import { Analytics, AnalyticsContext, AnalyticsProperties, CallOptions } from '../analytics/index.cjs';
 export { Analytics, AnalyticsConfig, AnalyticsContext, AnalyticsEvent, AnalyticsEventType, AnalyticsProperties, AnalyticsSink, CallOptions, createAnalytics } from '../analytics/index.cjs';
+export { ConsentState, GA4ClientSdkOptions, GA4ConsentBridge, GA4HttpOptions, GA4SinkOptions, GtagFn, createGA4ClientSdkSink, createGA4HttpSink, createGA4Sink } from '../analytics-sink-ga4/index.cjs';
+export { AppInsightsLike, AppInsightsSinkMode, AppInsightsSinkOptions, ClientSdkOptions, HttpOptions, createAppInsightsSink } from '../analytics-sink-app-insights/index.cjs';
+export { PostHogClientSdkSinkOptions, PostHogHttpSinkOptions, PostHogSinkMode, PostHogSinkOptions, createPostHogClientSdkSink, createPostHogHttpSink, createPostHogSink } from '../analytics-sink-posthog/index.cjs';
+export { SessionReplayHandle, SessionReplayOptions, startSessionReplay } from '../analytics-sink-posthog/replay.cjs';
 
 interface AnalyticsProviderProps {
     children: React.ReactNode;

package/dist/internal/react-analytics/index.d.ts

@@ -1,6 +1,10 @@
 import * as React from 'react';
 import { Analytics, AnalyticsContext, AnalyticsProperties, CallOptions } from '../analytics/index.js';
 export { Analytics, AnalyticsConfig, AnalyticsContext, AnalyticsEvent, AnalyticsEventType, AnalyticsProperties, AnalyticsSink, CallOptions, createAnalytics } from '../analytics/index.js';
+export { ConsentState, GA4ClientSdkOptions, GA4ConsentBridge, GA4HttpOptions, GA4SinkOptions, GtagFn, createGA4ClientSdkSink, createGA4HttpSink, createGA4Sink } from '../analytics-sink-ga4/index.js';
+export { AppInsightsLike, AppInsightsSinkMode, AppInsightsSinkOptions, ClientSdkOptions, HttpOptions, createAppInsightsSink } from '../analytics-sink-app-insights/index.js';
+export { PostHogClientSdkSinkOptions, PostHogHttpSinkOptions, PostHogSinkMode, PostHogSinkOptions, createPostHogClientSdkSink, createPostHogHttpSink, createPostHogSink } from '../analytics-sink-posthog/index.js';
+export { SessionReplayHandle, SessionReplayOptions, startSessionReplay } from '../analytics-sink-posthog/replay.js';
 
 interface AnalyticsProviderProps {
     children: React.ReactNode;

package/dist/internal/react-logger/index.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { Telemetry, TelemetryConfig, LogContext, Logger, Span } from '../logger/index.cjs';
-export { LogContext, LogLevel, LogRecord, Logger, Span, SpanRecord, Telemetry, TelemetryConfig, TelemetryEnv, TelemetrySink } from '../logger/index.cjs';
+export { LogContext, LogLevel, LogRecord, Logger, Span, SpanRecord, Telemetry, TelemetryConfig, TelemetryEnv, TelemetrySink, createConsoleSink, createFaroSink, createTelemetry } from '../logger/index.cjs';
 
 interface TelemetryContextValue {
     /** The root telemetry instance (a logger bound to the empty root context). */
@@ -21,7 +21,11 @@ interface TelemetryProviderProps extends TelemetryConfig {
 declare function TelemetryProvider({ children, ...config }: TelemetryProviderProps): React.FunctionComponentElement<React.ProviderProps<TelemetryContextValue | null>>;
 /**
  * useTelemetry — access the root telemetry instance.
- * Must be used within <TelemetryProvider>.
+ *
+ * If called outside a <TelemetryProvider> it does NOT throw: it returns a
+ * shared no-op telemetry (a dev-only warn-once hint is emitted so the missing
+ * provider is discoverable). This lets components instrumented with
+ * useLogger/useSpan/useTelemetry render safely without a provider.
  */
 declare function useTelemetry(): Telemetry;
 /**

package/dist/internal/react-logger/index.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { Telemetry, TelemetryConfig, LogContext, Logger, Span } from '../logger/index.js';
-export { LogContext, LogLevel, LogRecord, Logger, Span, SpanRecord, Telemetry, TelemetryConfig, TelemetryEnv, TelemetrySink } from '../logger/index.js';
+export { LogContext, LogLevel, LogRecord, Logger, Span, SpanRecord, Telemetry, TelemetryConfig, TelemetryEnv, TelemetrySink, createConsoleSink, createFaroSink, createTelemetry } from '../logger/index.js';
 
 interface TelemetryContextValue {
     /** The root telemetry instance (a logger bound to the empty root context). */
@@ -21,7 +21,11 @@ interface TelemetryProviderProps extends TelemetryConfig {
 declare function TelemetryProvider({ children, ...config }: TelemetryProviderProps): React.FunctionComponentElement<React.ProviderProps<TelemetryContextValue | null>>;
 /**
  * useTelemetry — access the root telemetry instance.
- * Must be used within <TelemetryProvider>.
+ *
+ * If called outside a <TelemetryProvider> it does NOT throw: it returns a
+ * shared no-op telemetry (a dev-only warn-once hint is emitted so the missing
+ * provider is discoverable). This lets components instrumented with
+ * useLogger/useSpan/useTelemetry render safely without a provider.
  */
 declare function useTelemetry(): Telemetry;
 /**