@faststats/react 0.7.0 → 0.8.1

package/README.md

@@ -2,3 +2,41 @@
 
 > [!IMPORTANT]
 > This repository is in early development and not intended for production use.
+
+The React provider owns one explicit browser SDK instance. Components access
+that instance through hooks rather than process-wide functions.
+
+```tsx
+"use client";
+
+import { Analytics, useTrack } from "@faststats/react";
+
+export function App() {
+	return <Analytics siteKey="site_123" />;
+}
+
+export function UpgradeButton() {
+	const track = useTrack();
+	return <button onClick={() => track("upgrade_clicked")}>Upgrade</button>;
+}
+```
+
+Extensions are available from tree-shakeable React subpath exports:
+
+```tsx
+"use client";
+
+import { Analytics } from "@faststats/react";
+import { errorTracking } from "@faststats/react/error";
+import { sessionReplay } from "@faststats/react/replay";
+import { webVitals } from "@faststats/react/web-vitals";
+
+export function FastStats() {
+	return (
+		<Analytics
+			siteKey="site_123"
+			extensions={[errorTracking(), webVitals(), sessionReplay()]}
+		/>
+	);
+}
+```

package/dist/error.d.ts

@@ -0,0 +1,2 @@
+import { ErrorTrackingExtensionOptions, errorTracking } from "@faststats/web/error";
+export { type ErrorTrackingExtensionOptions, errorTracking };

package/dist/error.js

@@ -0,0 +1,3 @@
+"use client";
+import { errorTracking } from "@faststats/web/error";
+export { errorTracking };

package/dist/index.d.ts

@@ -1,29 +1,16 @@
-import { ConsentMode, FeatureFlagEvaluation, FeatureFlagEvaluation as FeatureFlagEvaluation$1, IdentifyOptions, PendingBehavior, WebAnalyticsOptions, WebAnalyticsOptions as WebAnalyticsOptions$1, getInstance, identify, identify as identify$1, logout, logout as logout$1, optIn, optIn as optIn$1, optOut, optOut as optOut$1, reportError, setConsentMode, setConsentMode as setConsentMode$1, trackEvent, trackEvent as trackEvent$1 } from "@faststats/web";
-
+import { AnalyticsExtension, ConsentMode, ConsentMode as ConsentMode$1, IdentifyOptions, IdentifyOptions as IdentifyOptions$1, IdentifyUser, WebAnalytics, WebAnalyticsOptions, WebAnalyticsOptions as WebAnalyticsOptions$1 } from "@faststats/web";
 //#region src/analytics.d.ts
 type AnalyticsProps = WebAnalyticsOptions$1;
 declare function Analytics(props: AnalyticsProps): null;
 //#endregion
 //#region src/hooks.d.ts
-declare function useTrack(): typeof trackEvent$1;
-declare function useEvent(name: string, extra?: Record<string, unknown>): () => void;
-declare function useIdentify(): typeof identify$1;
-declare function useLogout(): typeof logout$1;
-declare function useConsentMode(): typeof setConsentMode$1;
-declare function useOptIn(): typeof optIn$1;
-declare function useOptOut(): typeof optOut$1;
+declare function useAnalytics(): WebAnalytics | null;
+declare function useTrack(): (name: string, properties?: Record<string, unknown>) => void | undefined;
+declare function useEvent(name: string, properties?: Record<string, unknown>): () => void;
+declare function useIdentify(): (userOrExternalId: IdentifyUser | string, email?: string, options?: IdentifyOptions$1) => Promise<boolean>;
+declare function useLogout(): (resetAnonymousIdentity?: boolean) => void | undefined;
+declare function useConsentMode(): (mode: ConsentMode$1) => void | undefined;
+declare function useOptIn(): () => void | undefined;
+declare function useOptOut(): () => void | undefined;
 //#endregion
-//#region src/use-flag.d.ts
-type UseFlagOptions = {
-  attributes?: Record<string, unknown>;
-  externalId?: string;
-  skip?: boolean;
-};
-type UseFlagResult = FeatureFlagEvaluation$1 & {
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => void;
-};
-declare function useFlag(flagKey: string, options?: UseFlagOptions): UseFlagResult;
-//#endregion
-export { Analytics, type AnalyticsProps, type ConsentMode, type FeatureFlagEvaluation, type IdentifyOptions, type PendingBehavior, type UseFlagOptions, type UseFlagResult, type WebAnalyticsOptions, getInstance, identify, logout, optIn, optOut, reportError, setConsentMode, trackEvent, useConsentMode, useEvent, useFlag, useIdentify, useLogout, useOptIn, useOptOut, useTrack };
+export { Analytics, type AnalyticsExtension, type AnalyticsProps, type ConsentMode, type IdentifyOptions, type WebAnalyticsOptions, useAnalytics, useConsentMode, useEvent, useIdentify, useLogout, useOptIn, useOptOut, useTrack };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use client";
-import { WebAnalytics, getInstance, getInstance as getInstance$1, identify, identify as identify$1, logout, logout as logout$1, optIn, optIn as optIn$1, optOut, optOut as optOut$1, reportError, setConsentMode, setConsentMode as setConsentMode$1, trackEvent, trackEvent as trackEvent$1 } from "@faststats/web";
-import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { WebAnalytics } from "@faststats/web";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 //#region src/instance.ts
 let instance = null;
 const listeners = /* @__PURE__ */ new Set();
@@ -20,7 +20,7 @@ function setInstance(wa) {
 //#endregion
 //#region src/analytics.tsx
 const SDK_NAME = "@faststats/react";
-const SDK_VERSION = "0.7.0";
+const SDK_VERSION = "0.8.1";
 function Analytics(props) {
 	const ownedRef = useRef(null);
 	const propsRef = useRef(props);
@@ -28,11 +28,6 @@ function Analytics(props) {
 	useEffect(() => {
 		if (typeof window === "undefined") return;
 		if (ownedRef.current) return;
-		const existing = getInstance$1();
-		if (existing) {
-			setInstance(existing);
-			return () => setInstance(null);
-		}
 		const wa = new WebAnalytics({
 			...propsRef.current,
 			sdkName: SDK_NAME,
@@ -40,6 +35,7 @@ function Analytics(props) {
 		});
 		ownedRef.current = wa;
 		setInstance(wa);
+		wa.start();
 		return () => {
 			if (ownedRef.current === wa) {
 				wa.destroy();
@@ -49,108 +45,53 @@ function Analytics(props) {
 		};
 	}, []);
 	useEffect(() => {
-		const consentMode = props.consent?.mode;
+		const consentMode = props.consent;
 		if (consentMode === void 0) return;
 		ownedRef.current?.setConsentMode(consentMode);
-	}, [props.consent?.mode]);
+	}, [props.consent]);
 	return null;
 }
 //#endregion
 //#region src/hooks.ts
+function useAnalytics() {
+	return useSyncExternalStore(subscribeToInstance, getInstanceSnapshot, () => null);
+}
 function useTrack() {
-	return trackEvent$1;
+	const analytics = useAnalytics();
+	return useCallback((name, properties) => analytics?.track(name, properties), [analytics]);
 }
-function useEvent(name, extra) {
+function useEvent(name, properties) {
+	const track = useTrack();
 	return useCallback(() => {
-		trackEvent$1(name, extra ?? {});
-	}, [name, extra]);
+		track(name, properties);
+	}, [
+		name,
+		properties,
+		track
+	]);
 }
 function useIdentify() {
-	return identify$1;
+	const analytics = useAnalytics();
+	return useCallback((userOrExternalId, email, options) => {
+		if (!analytics) return Promise.resolve(false);
+		return typeof userOrExternalId === "string" ? analytics.identify(userOrExternalId, email, options) : analytics.identify(userOrExternalId);
+	}, [analytics]);
 }
 function useLogout() {
-	return logout$1;
+	const analytics = useAnalytics();
+	return useCallback((resetAnonymousIdentity = true) => analytics?.logout(resetAnonymousIdentity), [analytics]);
 }
 function useConsentMode() {
-	return setConsentMode$1;
+	const analytics = useAnalytics();
+	return useCallback((mode) => analytics?.setConsentMode(mode), [analytics]);
 }
 function useOptIn() {
-	return optIn$1;
+	const setConsentMode = useConsentMode();
+	return useCallback(() => setConsentMode("granted"), [setConsentMode]);
 }
 function useOptOut() {
-	return optOut$1;
-}
-//#endregion
-//#region src/use-flag.ts
-const defaultState = {
-	value: "false",
-	isLoading: false,
-	error: null
-};
-let hasWarnedAboutMissingInstance = false;
-function useFlag(flagKey, options) {
-	const wa = useSyncExternalStore(subscribeToInstance, getInstanceSnapshot, () => null);
-	const attributes = options?.attributes;
-	const externalId = options?.externalId;
-	const skip = options?.skip ?? false;
-	const [state, setState] = useState({
-		...defaultState,
-		isLoading: !skip
-	});
-	const abortRef = useRef(null);
-	const fetchFlag = useCallback(() => {
-		abortRef.current?.abort();
-		abortRef.current = null;
-		if (skip || !wa) {
-			if (!skip && !wa && !hasWarnedAboutMissingInstance && true) {
-				hasWarnedAboutMissingInstance = true;
-				console.warn("[faststats/react] useFlag requires an active <Analytics /> instance.");
-			}
-			setState(defaultState);
-			return;
-		}
-		const ac = new AbortController();
-		abortRef.current = ac;
-		setState({
-			...defaultState,
-			isLoading: true
-		});
-		wa.checkFeatureFlag(flagKey, attributes, {
-			externalId,
-			signal: ac.signal
-		}).then((result) => {
-			if (ac.signal.aborted) return;
-			setState({
-				...result,
-				isLoading: false,
-				error: null
-			});
-		}).catch((e) => {
-			if (ac.signal.aborted) return;
-			const err = e instanceof Error ? e : new Error(String(e));
-			if (err.name === "AbortError") return;
-			setState({
-				...defaultState,
-				error: err
-			});
-		});
-	}, [
-		wa,
-		flagKey,
-		attributes,
-		externalId,
-		skip
-	]);
-	useEffect(() => {
-		fetchFlag();
-		return () => {
-			abortRef.current?.abort();
-		};
-	}, [fetchFlag]);
-	return {
-		...state,
-		refetch: fetchFlag
-	};
+	const setConsentMode = useConsentMode();
+	return useCallback(() => setConsentMode("denied"), [setConsentMode]);
 }
 //#endregion
-export { Analytics, getInstance, identify, logout, optIn, optOut, reportError, setConsentMode, trackEvent, useConsentMode, useEvent, useFlag, useIdentify, useLogout, useOptIn, useOptOut, useTrack };
+export { Analytics, useAnalytics, useConsentMode, useEvent, useIdentify, useLogout, useOptIn, useOptOut, useTrack };

package/dist/outbound-links.d.ts

@@ -0,0 +1,2 @@
+import { outboundLinks } from "@faststats/web/outbound-links";
+export { outboundLinks };

package/dist/outbound-links.js

@@ -0,0 +1,3 @@
+"use client";
+import { outboundLinks } from "@faststats/web/outbound-links";
+export { outboundLinks };

package/dist/replay.d.ts

@@ -0,0 +1,2 @@
+import { SessionReplayExtensionOptions, sessionReplay } from "@faststats/web/replay";
+export { type SessionReplayExtensionOptions, sessionReplay };

package/dist/replay.js

@@ -0,0 +1,3 @@
+"use client";
+import { sessionReplay } from "@faststats/web/replay";
+export { sessionReplay };

package/dist/web-vitals.d.ts

@@ -0,0 +1,2 @@
+import { WebVitalsExtensionOptions, webVitals } from "@faststats/web/web-vitals";
+export { type WebVitalsExtensionOptions, webVitals };

package/dist/web-vitals.js

@@ -0,0 +1,3 @@
+"use client";
+import { webVitals } from "@faststats/web/web-vitals";
+export { webVitals };

package/package.json

@@ -4,7 +4,7 @@
 		"type": "git",
 		"url": "https://github.com/faststats-dev/faststats-javascript.git"
 	},
-	"version": "0.7.0",
+	"version": "0.8.1",
 	"type": "module",
 	"main": "./dist/index.js",
 	"module": "./dist/index.js",
@@ -18,6 +18,26 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
 			"default": "./dist/index.js"
+		},
+		"./outbound-links": {
+			"types": "./dist/outbound-links.d.ts",
+			"import": "./dist/outbound-links.js",
+			"default": "./dist/outbound-links.js"
+		},
+		"./error": {
+			"types": "./dist/error.d.ts",
+			"import": "./dist/error.js",
+			"default": "./dist/error.js"
+		},
+		"./web-vitals": {
+			"types": "./dist/web-vitals.d.ts",
+			"import": "./dist/web-vitals.js",
+			"default": "./dist/web-vitals.js"
+		},
+		"./replay": {
+			"types": "./dist/replay.d.ts",
+			"import": "./dist/replay.js",
+			"default": "./dist/replay.js"
 		}
 	},
 	"files": [
@@ -31,13 +51,13 @@
 		"react": ">=18"
 	},
 	"dependencies": {
-		"@faststats/web": "^0.7.0"
+		"@faststats/web": "^0.8.1"
 	},
 	"devDependencies": {
-		"@types/node": "^25.9.3",
-		"@types/react": "^19.0.0",
-		"react": "^19.0.0",
-		"tsdown": "^0.22.3",
+		"@types/node": "^26.2.0",
+		"@types/react": "^19.2.18",
+		"react": "^19.2.8",
+		"tsdown": "^0.22.14",
 		"typescript": "^6.0.3"
 	}
 }