react-fathom 0.1.10 → 0.2.0

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/next/NextFathomProviderApp.client.d.ts

@@ -0,0 +1,3 @@
+export { NextFathomProviderApp } from './NextFathomProviderApp';
+export type { NextFathomProviderAppProps } from './NextFathomProviderApp';
+//# sourceMappingURL=NextFathomProviderApp.client.d.ts.map

package/types/next/NextFathomProviderApp.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NextFathomProviderApp.client.d.ts","sourceRoot":"","sources":["../../src/next/NextFathomProviderApp.client.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAC/D,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAA"}

package/types/next/NextFathomProviderApp.d.ts

@@ -1,6 +1,40 @@
 import React from 'react';
-import type { NextFathomProviderProps } from './types';
-declare const NextFathomProviderApp: React.FC<NextFathomProviderProps>;
-export default NextFathomProviderApp;
-export { NextFathomProviderApp };
+import type { FathomProviderProps } from '../types';
+export interface NextFathomProviderAppProps extends Omit<FathomProviderProps, 'children'> {
+    /**
+     * Disable automatic pageview tracking on route changes
+     * @default false
+     */
+    disableAutoTrack?: boolean;
+    /**
+     * Child components to render
+     */
+    children: React.ReactNode;
+}
+/**
+ * Client component wrapper that combines FathomProvider and NextFathomTrackViewApp
+ * for easy integration in Next.js App Router layouts.
+ *
+ * This component is marked with 'use client' and can be used directly in Server Components
+ * like the root layout.tsx file.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { NextFathomProviderApp } from 'react-fathom/next'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <NextFathomProviderApp siteId="YOUR_SITE_ID">
+ *           {children}
+ *         </NextFathomProviderApp>
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ */
+export declare const NextFathomProviderApp: React.FC<NextFathomProviderAppProps>;
 //# sourceMappingURL=NextFathomProviderApp.d.ts.map

package/types/next/NextFathomProviderApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NextFathomProviderApp.d.ts","sourceRoot":"","sources":["../../src/next/NextFathomProviderApp.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkD,MAAM,OAAO,CAAA;AAOtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAGtD,QAAA,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAyF5D,CAAA;AAID,eAAe,qBAAqB,CAAA;AACpC,OAAO,EAAE,qBAAqB,EAAE,CAAA"}
+{"version":3,"file":"NextFathomProviderApp.d.ts","sourceRoot":"","sources":["../../src/next/NextFathomProviderApp.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAGnD,MAAM,WAAW,0BAA2B,SAAQ,IAAI,CACtD,mBAAmB,EACnB,UAAU,CACX;IACC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;OAEG;IACH,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CAWtE,CAAA"}

package/types/next/index.d.ts

@@ -1,5 +1,6 @@
 export * from './NextFathomTrackViewPages';
 export * from './NextFathomTrackViewApp';
+export * from './NextFathomProviderApp';
 export * from './compositions/withPagesRouter';
 export * from './compositions/withAppRouter';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/next/index.ts"],"names":[],"mappings":"AACA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AAGxC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,8BAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/next/index.ts"],"names":[],"mappings":"AACA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AAGxC,cAAc,yBAAyB,CAAA;AAGvC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,8BAA8B,CAAA"}

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"}