react-fathom 0.1.10 → 0.2.0

package/src/next/NextFathomProviderApp.test.tsx

@@ -0,0 +1,154 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { render, screen } from '@testing-library/react'
+
+import { NextFathomProviderApp } from './NextFathomProviderApp'
+
+// Mock FathomProvider and NextFathomTrackViewApp
+vi.mock('../FathomProvider', () => ({
+  FathomProvider: ({
+    children,
+    siteId,
+    clientOptions,
+  }: {
+    children: React.ReactNode
+    siteId?: string
+    clientOptions?: unknown
+  }) => (
+    <div
+      data-testid="fathom-provider"
+      data-site-id={siteId}
+      data-client-options={JSON.stringify(clientOptions)}
+    >
+      {children}
+    </div>
+  ),
+}))
+
+vi.mock('./NextFathomTrackViewApp', () => ({
+  NextFathomTrackViewApp: ({
+    disableAutoTrack,
+  }: {
+    disableAutoTrack?: boolean
+  }) => (
+    <div
+      data-testid="track-view-app"
+      data-disable-auto-track={disableAutoTrack}
+    >
+      TrackViewApp
+    </div>
+  ),
+}))
+
+describe('NextFathomProviderApp', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should render FathomProvider and NextFathomTrackViewApp with children', () => {
+    render(
+      <NextFathomProviderApp siteId="TEST_SITE_ID">
+        <div>Test Content</div>
+      </NextFathomProviderApp>,
+    )
+
+    expect(screen.getByTestId('fathom-provider')).toBeInTheDocument()
+    expect(screen.getByTestId('fathom-provider')).toHaveAttribute(
+      'data-site-id',
+      'TEST_SITE_ID',
+    )
+    expect(screen.getByTestId('track-view-app')).toBeInTheDocument()
+    expect(screen.getByText('Test Content')).toBeInTheDocument()
+  })
+
+  it('should pass siteId to FathomProvider', () => {
+    render(
+      <NextFathomProviderApp siteId="MY_SITE_ID">
+        <div>Content</div>
+      </NextFathomProviderApp>,
+    )
+
+    expect(screen.getByTestId('fathom-provider')).toHaveAttribute(
+      'data-site-id',
+      'MY_SITE_ID',
+    )
+  })
+
+  it('should pass disableAutoTrack to NextFathomTrackViewApp', () => {
+    render(
+      <NextFathomProviderApp siteId="TEST_SITE_ID" disableAutoTrack>
+        <div>Content</div>
+      </NextFathomProviderApp>,
+    )
+
+    expect(screen.getByTestId('track-view-app')).toHaveAttribute(
+      'data-disable-auto-track',
+      'true',
+    )
+  })
+
+  it('should default disableAutoTrack to false', () => {
+    render(
+      <NextFathomProviderApp siteId="TEST_SITE_ID">
+        <div>Content</div>
+      </NextFathomProviderApp>,
+    )
+
+    expect(screen.getByTestId('track-view-app')).toHaveAttribute(
+      'data-disable-auto-track',
+      'false',
+    )
+  })
+
+  it('should pass clientOptions to FathomProvider', () => {
+    const clientOptions = { honorDNT: true, spa: 'auto' }
+
+    render(
+      <NextFathomProviderApp
+        siteId="TEST_SITE_ID"
+        clientOptions={clientOptions}
+      >
+        <div>Content</div>
+      </NextFathomProviderApp>,
+    )
+
+    const provider = screen.getByTestId('fathom-provider')
+    const options = JSON.parse(
+      provider.getAttribute('data-client-options') || '{}',
+    )
+    expect(options).toEqual(clientOptions)
+  })
+
+  it('should pass all FathomProvider props except children and disableAutoTrack', () => {
+    render(
+      <NextFathomProviderApp
+        siteId="TEST_SITE_ID"
+        defaultPageviewOptions={{ referrer: 'https://example.com' }}
+        defaultEventOptions={{ id: 'test' }}
+      >
+        <div>Content</div>
+      </NextFathomProviderApp>,
+    )
+
+    expect(screen.getByTestId('fathom-provider')).toBeInTheDocument()
+    expect(screen.getByText('Content')).toBeInTheDocument()
+  })
+
+  it('should have displayName', () => {
+    expect(NextFathomProviderApp.displayName).toBe('NextFathomProviderApp')
+  })
+
+  it('should render multiple children correctly', () => {
+    render(
+      <NextFathomProviderApp siteId="TEST_SITE_ID">
+        <div>Child 1</div>
+        <div>Child 2</div>
+      </NextFathomProviderApp>,
+    )
+
+    expect(screen.getByText('Child 1')).toBeInTheDocument()
+    expect(screen.getByText('Child 2')).toBeInTheDocument()
+  })
+})

package/src/next/NextFathomProviderApp.tsx

@@ -0,0 +1,62 @@
+'use client'
+
+import React from 'react'
+
+import { FathomProvider } from '../FathomProvider'
+import type { FathomProviderProps } from '../types'
+import { NextFathomTrackViewApp } from './NextFathomTrackViewApp'
+
+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 const NextFathomProviderApp: React.FC<NextFathomProviderAppProps> = ({
+  children,
+  disableAutoTrack = false,
+  ...fathomProviderProps
+}) => {
+  return (
+    <FathomProvider {...fathomProviderProps}>
+      <NextFathomTrackViewApp disableAutoTrack={disableAutoTrack} />
+      {children}
+    </FathomProvider>
+  )
+}
+
+NextFathomProviderApp.displayName = 'NextFathomProviderApp'

package/src/next/index.ts

@@ -2,6 +2,9 @@
 export * from './NextFathomTrackViewPages'
 export * from './NextFathomTrackViewApp'
 
+// Convenience provider components for easy setup
+export * from './NextFathomProviderApp'
+
 // Convenience compositions for easy setup
 export * from './compositions/withPagesRouter'
 export * from './compositions/withAppRouter'

package/src/types.ts

@@ -1,7 +1,10 @@
-import type { PropsWithChildren } from 'react'
+import type { MutableRefObject, PropsWithChildren } from 'react'
 
 import type { EventOptions, LoadOptions, PageViewOptions } from 'fathom-client'
 
+// Re-export fathom-client types for convenience
+export type { EventOptions, LoadOptions, PageViewOptions }
+
 export interface FathomClient {
   blockTrackingForMe: () => void
   enableTrackingForMe: () => void
@@ -14,14 +17,14 @@ export interface FathomClient {
 }
 
 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
@@ -29,6 +32,30 @@ export interface FathomContextInterface {
 
 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/FathomContext.d.ts

@@ -1,3 +1,3 @@
 import type { FathomContextInterface } from './types';
-export declare const FathomContext: import("react").Context<Partial<FathomContextInterface>>;
+export declare const FathomContext: import("react").Context<FathomContextInterface>;
 //# sourceMappingURL=FathomContext.d.ts.map

package/types/FathomContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FathomContext.d.ts","sourceRoot":"","sources":["../src/FathomContext.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAErD,eAAO,MAAM,aAAa,0DAAqD,CAAA"}
+{"version":3,"file":"FathomContext.d.ts","sourceRoot":"","sources":["../src/FathomContext.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AA8BrD,eAAO,MAAM,aAAa,iDACkC,CAAA"}

package/types/FathomProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FathomProvider.d.ts","sourceRoot":"","sources":["../src/FathomProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAsD,MAAM,OAAO,CAAA;AAM1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAElD,QAAA,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CA4GjD,CAAA;AAID,OAAO,EAAE,cAAc,EAAE,CAAA"}
+{"version":3,"file":"FathomProvider.d.ts","sourceRoot":"","sources":["../src/FathomProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAsD,MAAM,OAAO,CAAA;AAM1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAElD,QAAA,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAoHjD,CAAA;AAID,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/types/components/TrackClick.d.ts

@@ -30,7 +30,7 @@ export interface TrackClickProps extends EventOptions {
  *
  * @example
  * ```tsx
- * <TrackClick eventName="cta-clicked" id="hero-cta">
+ * <TrackClick eventName="cta-clicked" _value={100}>
  *   <button>Get Started</button>
  * </TrackClick>
  * ```

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