react-fathom 0.1.11 → 0.2.0

package/types/components/TrackVisible.d.ts

@@ -30,7 +30,7 @@ export interface TrackVisibleProps extends EventOptions {
  *
  * @example
  * ```tsx
- * <TrackVisible eventName="section-viewed" section="hero">
+ * <TrackVisible eventName="section-viewed" _value={1}>
  *   <HeroSection />
  * </TrackVisible>
  * ```

package/types/hooks/useTrackOnClick.d.ts

@@ -24,7 +24,7 @@ export interface UseTrackOnClickOptions extends EventOptions {
  * function Button() {
  *   const handleClick = useTrackOnClick({
  *     eventName: 'button-click',
- *     id: 'signup-button',
+ *     _value: 100, // Optional: value in cents
  *     callback: (e) => {
  *       console.log('Button clicked!')
  *       // Your custom logic here

package/types/hooks/useTrackOnVisible.d.ts

@@ -28,7 +28,7 @@ export interface UseTrackOnVisibleOptions extends EventOptions {
  * function Section() {
  *   const ref = useTrackOnVisible({
  *     eventName: 'section-viewed',
- *     section: 'hero',
+ *     _value: 1, // Optional: value in cents
  *     callback: (entry) => {
  *       console.log('Section is visible!', entry.isIntersecting)
  *       // Your custom logic here

package/types/index.d.ts

@@ -2,4 +2,5 @@ export * from './FathomContext';
 export * from './FathomProvider';
 export * from './hooks';
 export * from './components';
+export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA"}

package/types/native/FathomWebView.d.ts

@@ -0,0 +1,59 @@
+import React from 'react';
+import type { EventOptions, PageViewOptions, LoadOptions } from '../types';
+export interface FathomWebViewRef {
+    trackPageview: (opts?: PageViewOptions) => void;
+    trackEvent: (eventName: string, opts?: EventOptions) => void;
+    trackGoal: (code: string, cents: number) => void;
+    blockTrackingForMe: () => void;
+    enableTrackingForMe: () => void;
+    isReady: () => boolean;
+}
+export interface FathomWebViewProps {
+    /**
+     * Your Fathom Analytics site ID
+     */
+    siteId: string;
+    /**
+     * Options passed to fathom.load()
+     */
+    loadOptions?: LoadOptions;
+    /**
+     * Custom domain for Fathom script (if using custom domains feature)
+     * @default 'cdn.usefathom.com'
+     */
+    scriptDomain?: string;
+    /**
+     * Called when the Fathom script has loaded and is ready
+     */
+    onReady?: () => void;
+    /**
+     * Called when an error occurs loading the script
+     */
+    onError?: (error: string) => void;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Hidden WebView component that loads and manages the Fathom Analytics script.
+ *
+ * This component renders an invisible WebView that loads the official Fathom
+ * tracking script, allowing React Native apps to use Fathom's full functionality.
+ *
+ * @example
+ * ```tsx
+ * const fathomRef = useRef<FathomWebViewRef>(null)
+ *
+ * <FathomWebView
+ *   ref={fathomRef}
+ *   siteId="ABCDEFGH"
+ *   onReady={() => console.log('Fathom ready!')}
+ * />
+ *
+ * // Later, track events:
+ * fathomRef.current?.trackPageview({ url: '/home' })
+ * ```
+ */
+export declare const FathomWebView: React.ForwardRefExoticComponent<FathomWebViewProps & React.RefAttributes<FathomWebViewRef>>;
+//# sourceMappingURL=FathomWebView.d.ts.map

package/types/native/FathomWebView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FathomWebView.d.ts","sourceRoot":"","sources":["../../src/native/FathomWebView.tsx"],"names":[],"mappings":"AAAA,OAAO,KAMN,MAAM,OAAO,CAAA;AAId,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAC/C,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5D,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,mBAAmB,EAAE,MAAM,IAAI,CAAA;IAC/B,OAAO,EAAE,MAAM,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAEjC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,6FAgNzB,CAAA"}

package/types/native/NativeFathomProvider.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { NativeFathomProviderProps } from './types';
+/**
+ * A convenience provider for React Native apps that uses a hidden WebView
+ * to load the official Fathom Analytics script.
+ *
+ * This approach ensures full compatibility with Fathom's tracking by using
+ * their official JavaScript client, while providing a native React API.
+ *
+ * @example
+ * ```tsx
+ * import { NativeFathomProvider } from 'react-fathom/native'
+ *
+ * function App() {
+ *   return (
+ *     <NativeFathomProvider
+ *       siteId="YOUR_SITE_ID"
+ *       debug={__DEV__}
+ *       trackAppState
+ *     >
+ *       <YourApp />
+ *     </NativeFathomProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * This component renders a hidden WebView that loads Fathom's tracking script.
+ * Events are queued until the WebView is ready, then automatically flushed.
+ *
+ * The WebView approach is used because Fathom Analytics does not currently
+ * provide a public API for server-side or mobile event tracking. This ensures
+ * your analytics are recorded correctly using Fathom's official client.
+ */
+export declare const NativeFathomProvider: React.FC<NativeFathomProviderProps>;
+//# sourceMappingURL=NativeFathomProvider.d.ts.map

package/types/native/NativeFathomProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeFathomProvider.d.ts","sourceRoot":"","sources":["../../src/native/NativeFathomProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkD,MAAM,OAAO,CAAA;AAMtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAcxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CA4DpE,CAAA"}

package/types/native/createWebViewClient.d.ts

@@ -0,0 +1,51 @@
+import type { FathomClient } from '../types';
+import type { FathomWebViewRef } from './FathomWebView';
+export interface WebViewClientOptions {
+    /**
+     * Enable debug logging (default: false)
+     */
+    debug?: boolean;
+    /**
+     * Enable offline event queuing (default: true)
+     * When enabled, events are queued if the WebView isn't ready yet
+     */
+    enableQueue?: boolean;
+    /**
+     * Maximum number of events to queue (default: 100)
+     */
+    maxQueueSize?: number;
+}
+/**
+ * Creates a Fathom client that communicates with a FathomWebView component.
+ *
+ * This client queues commands until the WebView is ready, then flushes them.
+ * It implements the standard FathomClient interface for compatibility with
+ * the FathomProvider component.
+ *
+ * @example
+ * ```tsx
+ * import { createWebViewClient, FathomWebView } from 'react-fathom/native'
+ *
+ * function App() {
+ *   const webViewRef = useRef<FathomWebViewRef>(null)
+ *   const client = useMemo(
+ *     () => createWebViewClient(() => webViewRef.current, { debug: __DEV__ }),
+ *     []
+ *   )
+ *
+ *   return (
+ *     <FathomProvider client={client} siteId="YOUR_SITE_ID">
+ *       <FathomWebView ref={webViewRef} siteId="YOUR_SITE_ID" />
+ *       <YourApp />
+ *     </FathomProvider>
+ *   )
+ * }
+ * ```
+ */
+export interface WebViewFathomClient extends FathomClient {
+    processQueue: () => number;
+    getQueueLength: () => number;
+    setWebViewReady: () => void;
+}
+export declare function createWebViewClient(getWebViewRef: () => FathomWebViewRef | null | undefined, options?: WebViewClientOptions): WebViewFathomClient;
+//# sourceMappingURL=createWebViewClient.d.ts.map

package/types/native/createWebViewClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWebViewClient.d.ts","sourceRoot":"","sources":["../../src/native/createWebViewClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA8C,MAAM,UAAU,CAAA;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,YAAY,EAAE,MAAM,MAAM,CAAA;IAC1B,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,eAAe,EAAE,MAAM,IAAI,CAAA;CAC5B;AAED,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,gBAAgB,GAAG,IAAI,GAAG,SAAS,EACxD,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CA+MrB"}

package/types/native/index.d.ts

@@ -0,0 +1,10 @@
+export { FathomWebView, type FathomWebViewRef, type FathomWebViewProps } from './FathomWebView';
+export { createWebViewClient, type WebViewFathomClient, type WebViewClientOptions } from './createWebViewClient';
+export { NativeFathomProvider } from './NativeFathomProvider';
+export { FathomProvider } from '../FathomProvider';
+export { useFathom } from '../hooks/useFathom';
+export { useAppStateTracking } from './useAppStateTracking';
+export { useNavigationTracking } from './useNavigationTracking';
+export type { NativeFathomProviderProps, UseNavigationTrackingOptions, UseAppStateTrackingOptions, FathomClient, EventOptions, LoadOptions, PageViewOptions, } from './types';
+export type { FathomContextInterface, FathomProviderProps, } from '../types';
+//# sourceMappingURL=index.d.ts.map

package/types/native/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/native/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC/F,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAGhH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAG/D,YAAY,EACV,yBAAyB,EACzB,4BAA4B,EAC5B,0BAA0B,EAE1B,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,UAAU,CAAA"}

package/types/native/types.d.ts

@@ -0,0 +1,125 @@
+import type { MutableRefObject } from 'react';
+import type { FathomClient, EventOptions, LoadOptions, PageViewOptions } from '../types';
+import type { WebViewFathomClient } from './createWebViewClient';
+/**
+ * Options for the NativeFathomProvider component
+ */
+export interface NativeFathomProviderProps {
+    /**
+     * Your Fathom Analytics site ID
+     */
+    siteId: string;
+    /**
+     * Options passed to fathom.load() in the WebView
+     */
+    loadOptions?: LoadOptions;
+    /**
+     * Custom domain for Fathom script (if using Fathom's custom domains feature)
+     * @default 'cdn.usefathom.com'
+     */
+    scriptDomain?: string;
+    /**
+     * Default options merged into all trackPageview calls
+     */
+    defaultPageviewOptions?: PageViewOptions;
+    /**
+     * Default options merged into all trackEvent calls
+     */
+    defaultEventOptions?: EventOptions;
+    /**
+     * Enable automatic app state tracking (foreground/background)
+     * Tracks 'app-foreground' and 'app-background' events
+     * @default false
+     */
+    trackAppState?: boolean;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Called when the Fathom script has loaded and is ready
+     */
+    onReady?: () => void;
+    /**
+     * Called when an error occurs loading the script
+     */
+    onError?: (error: string) => void;
+    /**
+     * A ref that will be populated with the WebView-based Fathom client instance.
+     * This allows the parent component that composes the provider to access
+     * the client directly, since it cannot use useFathom() (context only flows
+     * downward to children).
+     *
+     * The client is a WebViewFathomClient which extends FathomClient with
+     * additional methods for queue management.
+     *
+     * @example
+     * ```tsx
+     * import { NativeFathomProvider, WebViewFathomClient } from 'react-fathom/native'
+     *
+     * function App() {
+     *   const clientRef = useRef<WebViewFathomClient>(null);
+     *
+     *   const handleDeepLink = (url: string) => {
+     *     clientRef.current?.trackEvent('deep_link', { _url: url });
+     *   };
+     *
+     *   return (
+     *     <NativeFathomProvider siteId="..." clientRef={clientRef}>
+     *       <YourApp />
+     *     </NativeFathomProvider>
+     *   );
+     * }
+     * ```
+     */
+    clientRef?: MutableRefObject<WebViewFathomClient | null>;
+    /**
+     * Children to render
+     */
+    children: React.ReactNode;
+}
+/**
+ * Options for the useNavigationTracking hook
+ */
+export interface UseNavigationTrackingOptions {
+    /**
+     * React Navigation navigation container ref
+     */
+    navigationRef: React.RefObject<any>;
+    /**
+     * Transform the route name before tracking (e.g., add prefixes)
+     */
+    transformRouteName?: (routeName: string) => string;
+    /**
+     * Filter which routes should be tracked (return false to skip)
+     */
+    shouldTrackRoute?: (routeName: string, params?: Record<string, any>) => boolean;
+    /**
+     * Include route params in the tracked URL
+     */
+    includeParams?: boolean;
+}
+/**
+ * Options for the useAppStateTracking hook
+ */
+export interface UseAppStateTrackingOptions {
+    /**
+     * Event name for when the app comes to foreground (default: 'app-foreground')
+     */
+    foregroundEventName?: string;
+    /**
+     * Event name for when the app goes to background (default: 'app-background')
+     */
+    backgroundEventName?: string;
+    /**
+     * Additional event options to include with app state events
+     */
+    eventOptions?: EventOptions;
+    /**
+     * Callback when app state changes
+     */
+    onStateChange?: (state: 'active' | 'background' | 'inactive') => void;
+}
+export type { FathomClient, EventOptions, LoadOptions, PageViewOptions };
+//# sourceMappingURL=types.d.ts.map

package/types/native/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/native/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAA;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACxF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,sBAAsB,CAAC,EAAE,eAAe,CAAA;IAExC;;OAEG;IACH,mBAAmB,CAAC,EAAE,YAAY,CAAA;IAElC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAA;IAExD;;OAEG;IACH,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IAEnC;;OAEG;IACH,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;IAElD;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAA;IAE/E;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAE5B;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAE5B;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,YAAY,GAAG,UAAU,KAAK,IAAI,CAAA;CACtE;AAGD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,CAAA"}

package/types/native/useAppStateTracking.d.ts

@@ -0,0 +1,25 @@
+import type { UseAppStateTrackingOptions } from './types';
+/**
+ * Hook that tracks app state changes (foreground/background) as Fathom events.
+ *
+ * This is useful for understanding user engagement patterns and session behavior.
+ *
+ * @example
+ * ```tsx
+ * import { useAppStateTracking } from 'react-fathom/native'
+ *
+ * function App() {
+ *   useAppStateTracking({
+ *     foregroundEventName: 'app-resumed',
+ *     backgroundEventName: 'app-paused',
+ *     onStateChange: (state) => {
+ *       console.log('App state:', state)
+ *     },
+ *   })
+ *
+ *   return <YourApp />
+ * }
+ * ```
+ */
+export declare function useAppStateTracking(options?: UseAppStateTrackingOptions): void;
+//# sourceMappingURL=useAppStateTracking.d.ts.map

package/types/native/useAppStateTracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAppStateTracking.d.ts","sourceRoot":"","sources":["../../src/native/useAppStateTracking.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,QAqC3E"}

package/types/native/useNavigationTracking.d.ts

@@ -0,0 +1,30 @@
+import type { UseNavigationTrackingOptions } from './types';
+/**
+ * Hook that tracks screen navigation as pageviews using React Navigation.
+ *
+ * This integrates with React Navigation's navigation container to automatically
+ * track screen changes as Fathom pageviews.
+ *
+ * @example
+ * ```tsx
+ * import { NavigationContainer } from '@react-navigation/native'
+ * import { useNavigationTracking } from 'react-fathom/native'
+ *
+ * function App() {
+ *   const navigationRef = useNavigationContainerRef()
+ *
+ *   useNavigationTracking({
+ *     navigationRef,
+ *     transformRouteName: (name) => `/screens/${name}`,
+ *   })
+ *
+ *   return (
+ *     <NavigationContainer ref={navigationRef}>
+ *       <Navigator />
+ *     </NavigationContainer>
+ *   )
+ * }
+ * ```
+ */
+export declare function useNavigationTracking(options: UseNavigationTrackingOptions): void;
+//# sourceMappingURL=useNavigationTracking.d.ts.map

package/types/native/useNavigationTracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavigationTracking.d.ts","sourceRoot":"","sources":["../../src/native/useNavigationTracking.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,QAgJ1E"}

package/types/types.d.ts

@@ -1,5 +1,6 @@
-import type { PropsWithChildren } from 'react';
+import type { MutableRefObject, PropsWithChildren } from 'react';
 import type { EventOptions, LoadOptions, PageViewOptions } from 'fathom-client';
+export type { EventOptions, LoadOptions, PageViewOptions };
 export interface FathomClient {
     blockTrackingForMe: () => void;
     enableTrackingForMe: () => void;
@@ -11,20 +12,44 @@ export interface FathomClient {
     isTrackingEnabled: () => boolean;
 }
 export interface FathomContextInterface {
-    blockTrackingForMe?: () => void;
-    enableTrackingForMe?: () => void;
-    isTrackingEnabled?: () => boolean;
-    load?: (siteId: string, options?: LoadOptions) => void;
-    setSite?: (siteId: string) => void;
-    trackPageview?: (options?: PageViewOptions) => void;
-    trackEvent?: (eventName: string, options?: EventOptions) => void;
-    trackGoal?: (code: string, cents: number) => void;
+    blockTrackingForMe: () => void;
+    enableTrackingForMe: () => void;
+    isTrackingEnabled: () => boolean;
+    load: (siteId: string, options?: LoadOptions) => void;
+    setSite: (siteId: string) => void;
+    trackPageview: (options?: PageViewOptions) => void;
+    trackEvent: (eventName: string, options?: EventOptions) => void;
+    trackGoal: (code: string, cents: number) => void;
     client?: FathomClient;
     defaultPageviewOptions?: PageViewOptions;
     defaultEventOptions?: EventOptions;
 }
 export interface FathomProviderProps extends PropsWithChildren {
     client?: FathomClient;
+    /**
+     * A ref that will be populated with the resolved Fathom client instance.
+     * This allows the parent component that composes the provider to access
+     * the client directly, since it cannot use useFathom() (context only flows
+     * downward to children).
+     *
+     * @example
+     * ```tsx
+     * function App() {
+     *   const clientRef = useRef<FathomClient>(null);
+     *
+     *   const handleDeepLink = (url: string) => {
+     *     clientRef.current?.trackEvent('deep_link', { _url: url });
+     *   };
+     *
+     *   return (
+     *     <FathomProvider siteId="..." clientRef={clientRef}>
+     *       <YourApp />
+     *     </FathomProvider>
+     *   );
+     * }
+     * ```
+     */
+    clientRef?: MutableRefObject<FathomClient | null>;
     clientOptions?: LoadOptions;
     siteId?: string;
     defaultPageviewOptions?: PageViewOptions;

package/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE/E,MAAM,WAAW,YAAY;IAC3B,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,mBAAmB,EAAE,MAAM,IAAI,CAAA;IAC/B,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5D,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IACrD,iBAAiB,EAAE,MAAM,OAAO,CAAA;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC/B,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAA;IAChC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAA;IACjC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IACtD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IACnD,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IAChE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,sBAAsB,CAAC,EAAE,eAAe,CAAA;IACxC,mBAAmB,CAAC,EAAE,YAAY,CAAA;CACnC;AAED,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,aAAa,CAAC,EAAE,WAAW,CAAA;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sBAAsB,CAAC,EAAE,eAAe,CAAA;IACxC,mBAAmB,CAAC,EAAE,YAAY,CAAA;CACnC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAEhE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAG/E,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,CAAA;AAE1D,MAAM,WAAW,YAAY;IAC3B,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,mBAAmB,EAAE,MAAM,IAAI,CAAA;IAC/B,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5D,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IACrD,iBAAiB,EAAE,MAAM,OAAO,CAAA;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,mBAAmB,EAAE,MAAM,IAAI,CAAA;IAC/B,iBAAiB,EAAE,MAAM,OAAO,CAAA;IAChC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IACrD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAClD,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IAC/D,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,sBAAsB,CAAC,EAAE,eAAe,CAAA;IACxC,mBAAmB,CAAC,EAAE,YAAY,CAAA;CACnC;AAED,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IACjD,aAAa,CAAC,EAAE,WAAW,CAAA;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sBAAsB,CAAC,EAAE,eAAe,CAAA;IACxC,mBAAmB,CAAC,EAAE,YAAY,CAAA;CACnC"}