├── .circleci
    └── config.yml
├── .gitignore
├── .prettierrc
├── CHANGELOG.md
├── LICENSE
├── README.md
├── package-lock.json
├── package.json
├── src
    └── index.ts
├── test
    └── index.test.js
└── tsconfig.json


/.circleci/config.yml:
--------------------------------------------------------------------------------
 1 | version: 2
 2 | jobs:
 3 |   build:
 4 |     docker:
 5 |       - image: cimg/node:lts
 6 |     working_directory: ~/repo
 7 | 
 8 |     steps:
 9 |       - checkout
10 |       - restore_cache:
11 |           keys:
12 |             - v1-dependencies-{{ checksum "package.json" }}
13 |             - v1-dependencies-
14 |       - run: npm install
15 |       - save_cache:
16 |           paths:
17 |             - node_modules
18 |           key: v1-dependencies-{{ checksum "package.json" }}
19 |       - run: npm run lint
20 |       - run: npm run test
21 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | node_modules
3 | dist
4 | types
5 | 


--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 |   "singleQuote": true
3 | }
4 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Changelog
 2 | 
 3 | ## 3.7.2
 4 | 
 5 | - Fix type declarations ([#63](https://github.com/derrickreimer/fathom-client/pull/61))
 6 | 
 7 | ## 3.7.1
 8 | 
 9 | - Reconfigure ESM and CJS exports ([#61](https://github.com/derrickreimer/fathom-client/pull/61))
10 | 
11 | ## 3.7.0
12 | 
13 | - Make the `load` function idempotent
14 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2019 Derrick Reimer
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Fathom Client [![CircleCI](https://circleci.com/gh/derrickreimer/fathom-client.svg?style=svg)](https://circleci.com/gh/derrickreimer/fathom-client)
  2 | 
  3 | This library is a JavaScript client for [Fathom Analytics](https://usefathom.com/).
  4 | 
  5 | - **Asynchronous script loading.** We provide a `load` function that will asynchronously inject the Fathom `<script>` tag (great for single-page app environments).
  6 | - **`import`-able tracking functions.** We provide tracking functions (`trackPageview` and `trackEvent`) that you can import and safely call anywhere (even if the Fathom script has not yet finished loading).
  7 | 
  8 | ---
  9 | 
 10 | Maintained with ♥️ by the [SavvyCal](https://savvycal.com/?utm_source=github&utm_medium=oss&utm_campaign=fathom-client) team
 11 | 
 12 | ## Installation
 13 | 
 14 | Run the following to install in your project:
 15 | 
 16 | ```
 17 | npm install fathom-client
 18 | ```
 19 | 
 20 | ## Motivation
 21 | 
 22 | The standard installation flow for Fathom is to drop their snippet on your page, which will automatically load the library and track a pageview. This approach works great for server-rendered sites with full page refreshes, but gets tricky when:
 23 | 
 24 | - Routing happens on the client-side (e.g. an SPA)
 25 | - The DOM is abstracted away (e.g. Next.js)
 26 | 
 27 | This library provides an interface you can use to orchestrate Fathom calls at various points in your page lifecycle:
 28 | 
 29 | ```js
 30 | import * as Fathom from 'fathom-client';
 31 | 
 32 | // Upon initial page load...
 33 | Fathom.load('MY_FATHOM_ID');
 34 | 
 35 | // In the route changed event handler...
 36 | const onRouteChangeComplete = () => {
 37 |   Fathom.trackPageview();
 38 | };
 39 | 
 40 | // In an event handler where a goal is achieved...
 41 | const onSignUp = () => {
 42 |   Fathom.trackEvent('Sign Up');
 43 | };
 44 | ```
 45 | 
 46 | ## API Reference
 47 | 
 48 | ### `load(siteId: string, opts?: object)`
 49 | 
 50 | Injects the Fathom script into the DOM and loads the script asynchronously.
 51 | 
 52 | #### Arguments
 53 | 
 54 | - `siteId` - The site ID provided in the Fathom UI.
 55 | - `opts` - An Object of options:
 56 |   - `auto` - When `false`, skips automatically tracking page views on script load (defaults to `true`).
 57 |   - `honorDNT` - When `true`, honors the [DNT header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/DNT) in the visitor's browser
 58 |   - `canonical` - When `false`, ignores the canonical tag if present (defaults to `true`).
 59 |   - `spa` - Accepts one of the following values: `auto`, `history`, or `hash` (see [advanced docs](https://usefathom.com/support/tracking-advanced)).
 60 | 
 61 | #### Example
 62 | 
 63 | ```js
 64 | import { load } from 'fathom-client';
 65 | 
 66 | load('MY_FATHOM_ID', {
 67 |   // Add options here
 68 | });
 69 | ```
 70 | 
 71 | ### `trackPageview(opts?: object)`
 72 | 
 73 | Tracks a pageview.
 74 | 
 75 | #### Arguments
 76 | 
 77 | - `opts` - An Object of options:
 78 |   - `url` - When set, overrides `window.location`.
 79 |   - `referrer` - When set, overrides `document.referrer`.
 80 | 
 81 | #### Example
 82 | 
 83 | ```js
 84 | import { trackPageview } from 'fathom-client';
 85 | 
 86 | trackPageview();
 87 | ```
 88 | 
 89 | ### `trackEvent(eventName: string, opts?: object)`
 90 | 
 91 | Tracks an event.
 92 | 
 93 | See [Creating and using events](https://usefathom.com/docs/features/events).
 94 | 
 95 | #### Arguments
 96 | 
 97 | - `eventName` - This can be nearly anything you want. Avoid special chars and emojis.
 98 | - `opts` - An Object of options:
 99 |   - `_site_id` - The Fathom site ID.
100 |   - `_value` - The value of the event (in cents).
101 | 
102 | #### Example
103 | 
104 | ```js
105 | import { trackEvent } from 'fathom-client';
106 | 
107 | trackEvent('checkout completed', { _value: 100 });
108 | ```
109 | 
110 | ### `trackGoal(code: string, cents: number)`
111 | 
112 | Tracks a goal. **This is now deprecated, see `trackEvent` instead**.
113 | 
114 | #### Arguments
115 | 
116 | - `code` - the code provided in the Fathom UI.
117 | - `cents` - the value of the goal conversion.
118 | 
119 | #### Example
120 | 
121 | ```js
122 | import { trackGoal } from 'fathom-client';
123 | 
124 | trackGoal('MY_GOAL_CODE', 100);
125 | ```
126 | 
127 | ### `enableTrackingForMe()`
128 | 
129 | Enables tracking for the current visitor.
130 | 
131 | See https://usefathom.com/docs/features/exclude.
132 | 
133 | #### Arguments
134 | 
135 | None.
136 | 
137 | #### Example
138 | 
139 | ```js
140 | import { enableTrackingForMe } from 'fathom-client';
141 | 
142 | enableTrackingForMe();
143 | ```
144 | 
145 | ### `blockTrackingForMe()`
146 | 
147 | Blocks tracking for the current visitor.
148 | 
149 | See https://usefathom.com/docs/features/exclude.
150 | 
151 | #### Arguments
152 | 
153 | None.
154 | 
155 | #### Example
156 | 
157 | ```js
158 | import { blockTrackingForMe } from 'fathom-client';
159 | 
160 | blockTrackingForMe();
161 | ```
162 | 
163 | ### `isTrackingEnabled()`
164 | 
165 | Checks if tracking is enabled for the current visitor.
166 | 
167 | See https://usefathom.com/docs/features/exclude.
168 | 
169 | #### Arguments
170 | 
171 | None.
172 | 
173 | #### Returns
174 | 
175 | Boolean.
176 | 
177 | #### Example
178 | 
179 | ```js
180 | import { isTrackingEnabled } from 'fathom-client';
181 | 
182 | const check = isTrackingEnabled(); // `true` by default
183 | ```
184 | 
185 | ### `setSite(id: string)`
186 | 
187 | Sets the site ID for tracking (overrides the ID used when loading Fathom).
188 | 
189 | #### Arguments
190 | 
191 | - `id` - The site ID provided in the Fathom UI.
192 | 
193 | #### Example
194 | 
195 | ```js
196 | import { load, setSite } from 'fathom-client';
197 | 
198 | load('MY_FATHOM_ID');
199 | 
200 | setSite('A_DIFFERENT_FATHOM_ID');
201 | ```
202 | 
203 | ## Allowed Domains
204 | 
205 | Manage your allowed domains within your Fathom site's Firewall settings. Doing so enables the usage of wildcards (e.g., \*.example.com). See https://usefathom.com/docs/script/firewall#allowed
206 | 
207 | The `includedDomains` and `excludedDomains` options, while deprecated, are still supported to ensure backward compatibility.
208 | 
209 | ## Usage
210 | 
211 | This library is JavaScript framework-agnostic. Below are some usage examples with popular frameworks.
212 | 
213 | ### Next.js
214 | 
215 | #### Using `pages` directory (v12 and older)
216 | 
217 | > If you are using the latest Next.js beta with the `app` directory, see the modified instructions below.
218 | 
219 | Create an `_app.js` file in your `pages` directory, [like this](https://nextjs.org/docs#custom-app):
220 | 
221 | ```jsx
222 | import React, { useEffect } from 'react';
223 | import Router from 'next/router';
224 | import * as Fathom from 'fathom-client';
225 | 
226 | // Record a pageview when route changes
227 | Router.events.on('routeChangeComplete', (as, routeProps) => {
228 |   if (!routeProps.shallow) {
229 |     Fathom.trackPageview();
230 |   }
231 | });
232 | 
233 | function App({ Component, pageProps }) {
234 |   // Initialize Fathom when the app loads
235 |   useEffect(() => {
236 |     Fathom.load('MY_FATHOM_ID', {
237 |       // Add options here
238 |     });
239 |   }, []);
240 | 
241 |   return <Component {...pageProps} />;
242 | }
243 | 
244 | export default App;
245 | ```
246 | 
247 | #### Using the experimental `app` directory (v13)
248 | 
249 | Create a `Fathom` client component:
250 | 
251 | ```tsx
252 | // Fathom.tsx
253 | 'use client';
254 | 
255 | import { load, trackPageview } from 'fathom-client';
256 | import { useEffect, Suspense } from 'react';
257 | import { usePathname, useSearchParams } from 'next/navigation';
258 | 
259 | function TrackPageView() {
260 |   const pathname = usePathname();
261 |   const searchParams = useSearchParams();
262 | 
263 |   // Load the Fathom script on mount
264 |   useEffect(() => {
265 |     load('MY_FATHOM_ID', {
266 |       auto: false
267 |     });
268 |   }, []);
269 | 
270 |   // Record a pageview when route changes
271 |   useEffect(() => {
272 |     if (!pathname) return;
273 | 
274 |     trackPageview({
275 |       url: pathname + searchParams?.toString(),
276 |       referrer: document.referrer
277 |     });
278 |   }, [pathname, searchParams]);
279 | 
280 |   return null;
281 | }
282 | 
283 | export default function Fathom() {
284 |   return (
285 |     <Suspense fallback={null}>
286 |       <TrackPageView />
287 |     </Suspense>
288 |   );
289 | }
290 | ```
291 | 
292 | Note that we explicitly pass the `url` to `trackPageview` to avoid race conditions that occur when we allow the Fathom script to infer the URL from the browser.
293 | 
294 | Then, add the client component to your root `layout.tsx` file:
295 | 
296 | ```tsx
297 | // layout.tsx
298 | 
299 | import Fathom from './Fathom';
300 | 
301 | export default function RootLayout({ children }: { children: ReactNode }) {
302 |   return (
303 |     <html lang="en">
304 |       <head></head>
305 |       <body>
306 |         <Fathom />
307 |         {children}
308 |       </body>
309 |     </html>
310 |   );
311 | }
312 | ```
313 | 
314 | ## Upgrading to 3.x
315 | 
316 | The 3.0 release comes with a new way to load Fathom:
317 | 
318 | ```diff
319 | - Fathom.load();
320 | - Fathom.setSiteId('MY_FATHOM_ID');
321 | + Fathom.load('MY_FATHOM_ID');
322 | ```
323 | 
324 | The `load` function also accepts an object of options:
325 | 
326 | ```js
327 | Fathom.load('MY_FATHOM_ID', {
328 |   // Add options here
329 | });
330 | ```
331 | 
332 | See [advanced options for tracking](https://usefathom.com/support/tracking-advanced).
333 | 
334 | ## Releasing
335 | 
336 | Run the following to publish a new version:
337 | 
338 | ```bash
339 | npm run release
340 | ```
341 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "fathom-client",
 3 |   "version": "3.7.2",
 4 |   "description": "A simple wrapper around the Fathom Analytics library",
 5 |   "keywords": [
 6 |     "analytics"
 7 |   ],
 8 |   "homepage": "https://github.com/derrickreimer/fathom-client",
 9 |   "bugs": {
10 |     "url": "https://github.com/derrickreimer/fathom-client/issues"
11 |   },
12 |   "repository": {
13 |     "type": "git",
14 |     "url": "https://github.com/derrickreimer/fathom-client.git"
15 |   },
16 |   "license": "MIT",
17 |   "author": "Derrick Reimer",
18 |   "files": [
19 |     "dist",
20 |     "types"
21 |   ],
22 |   "type": "module",
23 |   "module": "dist/fathom-client.esm.js",
24 |   "main": "dist/fathom-client.cjs",
25 |   "exports": {
26 |     "types": {
27 |       "import": "./types/index.d.ts",
28 |       "require": "./types/index.d.cts"
29 |     },
30 |     "import": "./dist/fathom-client.esm.js",
31 |     "require": "./dist/fathom-client.cjs"
32 |   },
33 |   "types": "types/index.d.ts",
34 |   "scripts": {
35 |     "build": "npm run build:types && npm run build:cjs && npm run build:esm",
36 |     "build:cjs": "esbuild src/index.ts --bundle --format=cjs --outfile=dist/fathom-client.cjs",
37 |     "build:esm": "esbuild src/index.ts --bundle --format=esm --outfile=dist/fathom-client.esm.js",
38 |     "build:types": "tsc --emitDeclarationOnly && cp ./types/index.d.ts ./types/index.d.cts",
39 |     "lint": "npx tsc --noEmit && npx prettier src -c",
40 |     "prepare": "npm run build",
41 |     "test": "npm run build && jest",
42 |     "release": "np"
43 |   },
44 |   "jest": {
45 |     "resetMocks": false,
46 |     "setupFiles": [
47 |       "jest-localstorage-mock"
48 |     ]
49 |   },
50 |   "devDependencies": {
51 |     "esbuild": "^0.25.0",
52 |     "jest": "^29.7.0",
53 |     "jest-environment-jsdom": "^29.7.0",
54 |     "jest-localstorage-mock": "^2.4.21",
55 |     "np": "^10.0.5",
56 |     "prettier": "^3.3.2",
57 |     "typescript": "^5.4.5"
58 |   },
59 |   "np": {
60 |     "yarn": false
61 |   }
62 | }
63 | 


--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
  1 | export interface Fathom {
  2 |   blockTrackingForMe: () => void;
  3 |   enableTrackingForMe: () => void;
  4 |   trackPageview: (opts?: PageViewOptions) => void;
  5 |   trackGoal: (code: string, cents: number) => void;
  6 |   trackEvent: (eventName: string, opts?: EventOptions) => void;
  7 |   setSite: (id: string) => void;
  8 | }
  9 | 
 10 | /**
 11 |  * @see https://usefathom.com/docs/script/script-advanced#api
 12 |  */
 13 | export type PageViewOptions = {
 14 |   url?: string;
 15 |   referrer?: string;
 16 | };
 17 | 
 18 | /**
 19 |  * @see https://usefathom.com/docs/features/events
 20 |  */
 21 | export type EventOptions = {
 22 |   _value?: number;
 23 |   _site_id?: string;
 24 | };
 25 | 
 26 | /**
 27 |  * @see https://usefathom.com/support/tracking-advanced
 28 |  */
 29 | export type LoadOptions = {
 30 |   url?: string;
 31 |   auto?: boolean;
 32 |   honorDNT?: boolean;
 33 |   canonical?: boolean;
 34 |   includedDomains?: string[];
 35 |   excludedDomains?: string[];
 36 |   spa?: 'auto' | 'history' | 'hash';
 37 | };
 38 | 
 39 | type FathomCommand =
 40 |   | { type: 'trackPageview'; opts: PageViewOptions | undefined }
 41 |   | { type: 'trackGoal'; code: string; cents: number }
 42 |   | { type: 'trackEvent'; eventName: string; opts: EventOptions | undefined }
 43 |   | { type: 'blockTrackingForMe' }
 44 |   | { type: 'enableTrackingForMe' }
 45 |   | { type: 'setSite'; id: string };
 46 | 
 47 | declare global {
 48 |   interface Window {
 49 |     fathom?: Fathom;
 50 | 
 51 |     /** @internal */
 52 |     __fathomClientQueue: FathomCommand[];
 53 |     /** @internal */
 54 |     __fathomIsLoading?: boolean;
 55 |   }
 56 | }
 57 | 
 58 | /**
 59 |  * Enqueues a command to dispatch to fathom when the library is loaded.
 60 |  *
 61 |  * @param command - A set of arguments to dispatch to fathom later.
 62 |  */
 63 | const enqueue = (command: FathomCommand): void => {
 64 |   window.__fathomClientQueue = window.__fathomClientQueue || [];
 65 |   window.__fathomClientQueue.push(command);
 66 | };
 67 | 
 68 | /**
 69 |  * Flushes the command queue.
 70 |  */
 71 | const flushQueue = (): void => {
 72 |   window.__fathomIsLoading = false;
 73 |   window.__fathomClientQueue = window.__fathomClientQueue || [];
 74 | 
 75 |   window.__fathomClientQueue.forEach((command) => {
 76 |     switch (command.type) {
 77 |       case 'trackPageview':
 78 |         trackPageview(command.opts);
 79 |         return;
 80 | 
 81 |       case 'trackGoal':
 82 |         trackGoal(command.code, command.cents);
 83 |         return;
 84 | 
 85 |       case 'trackEvent':
 86 |         trackEvent(command.eventName, command.opts);
 87 |         return;
 88 | 
 89 |       case 'enableTrackingForMe':
 90 |         enableTrackingForMe();
 91 |         return;
 92 | 
 93 |       case 'blockTrackingForMe':
 94 |         blockTrackingForMe();
 95 |         return;
 96 | 
 97 |       case 'setSite':
 98 |         setSite(command.id);
 99 |         return;
100 |     }
101 |   });
102 | 
103 |   window.__fathomClientQueue = [];
104 | };
105 | 
106 | /**
107 |  * Loops through list of domains and warns if they start with http, https,
108 |  * http://, etc... as this does not work with the Fathom script.
109 |  *
110 |  * @param domains - List of domains to check
111 |  */
112 | const checkDomainsAndWarn = (domains: string[]): void => {
113 |   const regex = /(https?)(?=:|\/|$)/; // matches http or https followed by
114 |   // either a : or /
115 |   domains.forEach((domain) => {
116 |     if (regex.exec(domain) !== null)
117 |       console.warn(
118 |         `The include domain ${domain} might fail to work as intended as it begins with a transfer protocol (http://, https://). Consider removing the protocol portion of the string.`,
119 |       );
120 |   });
121 | };
122 | 
123 | /**
124 |  * Loads the Fathom script.
125 |  *
126 |  * @param siteId - the id for the Fathom site.
127 |  * @param opts - advanced tracking options (https://usefathom.com/support/tracking-advanced)
128 |  */
129 | export const load = (siteId: string, opts?: LoadOptions): void => {
130 |   if (window.__fathomIsLoading || window.fathom) return;
131 | 
132 |   // Mark that fathom is loading, so that we can prevent a race condition if
133 |   // `load` is called again BEFORE the fathom script finishes initializing (and
134 |   // so before `window.fathom` is actually defined)
135 |   window.__fathomIsLoading = true;
136 | 
137 |   let tracker = document.createElement('script');
138 | 
139 |   let firstScript =
140 |     document.getElementsByTagName('script')[0] ||
141 |     document.querySelector('body');
142 | 
143 |   tracker.id = 'fathom-script';
144 |   tracker.async = true;
145 |   tracker.setAttribute('data-site', siteId);
146 |   tracker.src =
147 |     opts && opts.url ? opts.url : 'https://cdn.usefathom.com/script.js';
148 | 
149 |   if (opts) {
150 |     if (opts.auto !== undefined)
151 |       tracker.setAttribute('data-auto', `${opts.auto}`);
152 |     if (opts.honorDNT !== undefined)
153 |       tracker.setAttribute('data-honor-dnt', `${opts.honorDNT}`);
154 |     if (opts.canonical !== undefined)
155 |       tracker.setAttribute('data-canonical', `${opts.canonical}`);
156 |     if (opts.includedDomains) {
157 |       checkDomainsAndWarn(opts.includedDomains);
158 |       tracker.setAttribute(
159 |         'data-included-domains',
160 |         opts.includedDomains.join(','),
161 |       );
162 |     }
163 |     if (opts.excludedDomains) {
164 |       checkDomainsAndWarn(opts.excludedDomains);
165 |       tracker.setAttribute(
166 |         'data-excluded-domains',
167 |         opts.excludedDomains.join(','),
168 |       );
169 |     }
170 |     if (opts.spa) tracker.setAttribute('data-spa', opts.spa);
171 |   }
172 |   tracker.onload = flushQueue;
173 |   firstScript.parentNode.insertBefore(tracker, firstScript);
174 | };
175 | 
176 | /**
177 |  * Tracks a pageview.
178 |  *
179 |  * @param opts - An optional `url` or `referrer` to override auto-detected values.
180 |  */
181 | export const trackPageview = (opts?: PageViewOptions): void => {
182 |   if (window.fathom) {
183 |     if (opts) {
184 |       window.fathom.trackPageview(opts);
185 |     } else {
186 |       window.fathom.trackPageview();
187 |     }
188 |   } else {
189 |     enqueue({ type: 'trackPageview', opts });
190 |   }
191 | };
192 | 
193 | /**
194 |  * Tracks a goal.
195 |  *
196 |  * @param code - The goal ID.
197 |  * @param cents - The value in cents.
198 |  * @deprecated If you are using this to track an existing goal, however, it will continue to work.
199 |  * @see https://usefathom.com/docs/features/events
200 |  */
201 | export const trackGoal = (code: string, cents: number) => {
202 |   if (window.fathom) {
203 |     window.fathom.trackGoal(code, cents);
204 |   } else {
205 |     enqueue({ type: 'trackGoal', code, cents });
206 |   }
207 | };
208 | 
209 | /**
210 |  * Tracks a dynamic event.
211 |  *
212 |  * @param eventName - This can be nearly anything you want. Avoid special chars and emojis.
213 |  * @param opts - A collection of options.
214 |  * @param opts._site_id - The site ID (optional).
215 |  * @param opts._value - The value in cents (optional).
216 |  * @see https://usefathom.com/docs/features/events
217 |  */
218 | export const trackEvent = (eventName: string, opts?: EventOptions) => {
219 |   if (window.fathom) {
220 |     window.fathom.trackEvent(eventName, opts);
221 |   } else {
222 |     enqueue({ type: 'trackEvent', eventName, opts });
223 |   }
224 | };
225 | 
226 | /**
227 |  * Blocks tracking for the current visitor.
228 |  *
229 |  * @see https://usefathom.com/docs/features/exclude
230 |  */
231 | export const blockTrackingForMe = (): void => {
232 |   if (window.fathom) {
233 |     window.fathom.blockTrackingForMe();
234 |   } else {
235 |     enqueue({ type: 'blockTrackingForMe' });
236 |   }
237 | };
238 | 
239 | /**
240 |  * Enables tracking for the current visitor.
241 |  *
242 |  * @see https://usefathom.com/docs/features/exclude
243 |  */
244 | export const enableTrackingForMe = (): void => {
245 |   if (window.fathom) {
246 |     window.fathom.enableTrackingForMe();
247 |   } else {
248 |     enqueue({ type: 'enableTrackingForMe' });
249 |   }
250 | };
251 | 
252 | /**
253 |  * Checks if tracking is enabled for the current visitor.
254 |  */
255 | export const isTrackingEnabled = (): boolean => {
256 |   const preferenceStorage: string | null = localStorage.getItem(
257 |     'blockFathomTracking',
258 |   );
259 |   return preferenceStorage !== null ? preferenceStorage !== 'true' : true;
260 | };
261 | 
262 | /**
263 |  * Sets the Site ID.
264 |  *
265 |  * @param id - The new site ID.
266 |  */
267 | export const setSite = (id: string): void => {
268 |   if (window.fathom) {
269 |     window.fathom.setSite(id);
270 |   } else {
271 |     enqueue({ type: 'setSite', id });
272 |   }
273 | };
274 | 


--------------------------------------------------------------------------------
/test/index.test.js:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * @jest-environment jsdom
  3 |  */
  4 | 
  5 | const Fathom = require('../dist/fathom-client');
  6 | 
  7 | const fathomStub = () => {
  8 |   return {
  9 |     setSite: jest.fn(),
 10 |     trackPageview: jest.fn(),
 11 |     trackGoal: jest.fn(),
 12 |     trackEvent: jest.fn(),
 13 |     blockTrackingForMe: jest.fn(),
 14 |     enableTrackingForMe: jest.fn()
 15 |   };
 16 | };
 17 | 
 18 | beforeEach(() => {
 19 |   window.fathom = undefined;
 20 |   delete window.__fathomIsLoading;
 21 |   delete window.__fathomClientQueue;
 22 | });
 23 | 
 24 | describe('load', () => {
 25 |   beforeEach(() => {
 26 |     // reset the script node before each test
 27 |     const script = document.getElementById('fathom-script');
 28 |     if (script) script.remove();
 29 |   });
 30 | 
 31 |   it('injects the Fathom script', () => {
 32 |     const firstScript = document.createElement('script');
 33 |     document.body.appendChild(firstScript);
 34 |     Fathom.load('id');
 35 | 
 36 |     const fathomScript = document.getElementById('fathom-script');
 37 |     expect(fathomScript?.src).toBe('https://cdn.usefathom.com/script.js');
 38 |   });
 39 | 
 40 |   it('skips injecting the script if already loaded or currently loading', () => {
 41 |     // simulate the script already being loaded
 42 |     Fathom.load('id');
 43 |     // ↓
 44 |     window.fathom = fathomStub();
 45 | 
 46 |     const firstScript = document.createElement('script');
 47 |     document.body.appendChild(firstScript);
 48 |     Fathom.load('id');
 49 | 
 50 |     const fathomScripts = Array.from(
 51 |       document.getElementsByTagName('script')
 52 |     ).filter(s => {
 53 |       return s.src == 'https://cdn.usefathom.com/script.js';
 54 |     });
 55 | 
 56 |     expect(fathomScripts.length).toBe(1);
 57 | 
 58 |     // simulate 'onload' firing
 59 |     const fathomScript = document.getElementById('fathom-script');
 60 |     fathomScript?.dispatchEvent(new Event('load'));
 61 | 
 62 |     expect(window.__fathomIsLoading).toBe(false);
 63 |   });
 64 | 
 65 |   it('injects the Fathom script with options', () => {
 66 |     const firstScript = document.createElement('script');
 67 |     document.body.appendChild(firstScript);
 68 |     Fathom.load('abcde123', {
 69 |       url: 'https://bobheadxi.dev/fathom.js',
 70 |       auto: false,
 71 |       includedDomains: ['bobheadxi.dev']
 72 |     });
 73 | 
 74 |     const fathomScript = document.getElementById('fathom-script');
 75 |     expect(fathomScript?.src).toBe('https://bobheadxi.dev/fathom.js');
 76 |     expect(fathomScript?.getAttribute('data-included-domains')).toBe(
 77 |       'bobheadxi.dev'
 78 |     );
 79 |     expect(fathomScript?.getAttribute('data-auto')).toBe('false');
 80 |     expect(fathomScript?.getAttribute('data-honor-dnt')).toBe(null);
 81 |   });
 82 | 
 83 |   it('runs the queue after load', () => {
 84 |     Fathom.trackPageview();
 85 | 
 86 |     const firstScript = document.createElement('script');
 87 |     document.body.appendChild(firstScript);
 88 | 
 89 |     Fathom.load('id');
 90 |     // ↓
 91 |     window.fathom = fathomStub();
 92 | 
 93 |     // simulate 'onload' firing
 94 |     const fathomScript = document.getElementById('fathom-script');
 95 |     fathomScript?.dispatchEvent(new Event('load'));
 96 | 
 97 |     expect(window.fathom.trackPageview.mock.calls.length).toBe(1);
 98 |   });
 99 | 
100 |   it('warns when loading include domains which are not bare domains', () => {
101 |     window.console = {
102 |       warn: jest.fn()
103 |     };
104 | 
105 |     const firstScript = document.createElement('script');
106 |     document.body.appendChild(firstScript);
107 |     Fathom.load('abcde123', {
108 |       url: 'https://bobheadxi.dev/fathom.js',
109 |       auto: false,
110 |       includedDomains: ['https://bobheadxi.dev']
111 |     });
112 | 
113 |     expect(window.console.warn).toHaveBeenCalledWith(
114 |       'The include domain https://bobheadxi.dev might fail to work as intended as it begins with a transfer protocol (http://, https://). Consider removing the protocol portion of the string.'
115 |     );
116 |   });
117 | });
118 | 
119 | describe('trackPageview', () => {
120 |   it('enqueues the operation if fathom is not loaded', () => {
121 |     Fathom.trackPageview();
122 |     expect(window.__fathomClientQueue).toStrictEqual([
123 |       { type: 'trackPageview', opts: undefined }
124 |     ]);
125 |   });
126 | 
127 |   it('calls the fathom function if loaded', () => {
128 |     return new Promise(resolve => {
129 |       window.fathom = {
130 |         trackPageview: (...args) => {
131 |           expect(args).toStrictEqual([]);
132 |           resolve();
133 |         },
134 |         trackGoal: jest.fn(),
135 |         trackEvent: jest.fn()
136 |       };
137 | 
138 |       Fathom.trackPageview();
139 |     });
140 |   });
141 | 
142 |   it('calls the fathom function with arguments if loaded', () => {
143 |     return new Promise(resolve => {
144 |       window.fathom = {
145 |         trackPageview: (...args) => {
146 |           expect(args).toStrictEqual([{ url: 'https://bobheadxi.dev' }]);
147 |           resolve();
148 |         },
149 |         trackGoal: jest.fn(),
150 |         trackEvent: jest.fn()
151 |       };
152 | 
153 |       Fathom.trackPageview({ url: 'https://bobheadxi.dev' });
154 |     });
155 |   });
156 | });
157 | 
158 | describe('trackGoal', () => {
159 |   it('enqueues the operation if fathom is not loaded', () => {
160 |     Fathom.trackGoal('Sign Up', 0);
161 |     expect(window.__fathomClientQueue).toStrictEqual([
162 |       { type: 'trackGoal', code: 'Sign Up', cents: 0 }
163 |     ]);
164 |   });
165 | 
166 |   it('calls the fathom function if loaded', () => {
167 |     return new Promise(resolve => {
168 |       window.fathom = {
169 |         trackPageview: jest.fn(),
170 |         trackGoal: (...args) => {
171 |           expect(args).toStrictEqual(['Sign Up', 0]);
172 |           resolve();
173 |         }
174 |       };
175 | 
176 |       Fathom.trackGoal('Sign Up', 0);
177 |     });
178 |   });
179 | });
180 | 
181 | describe('trackEvent', () => {
182 |   it('enqueues the operation if fathom is not loaded', () => {
183 |     Fathom.trackEvent('dynamic event test', { _value: 0 });
184 |     expect(window.__fathomClientQueue).toStrictEqual([
185 |       {
186 |         type: 'trackEvent',
187 |         eventName: 'dynamic event test',
188 |         opts: { _value: 0 }
189 |       }
190 |     ]);
191 |   });
192 | 
193 |   it('calls the fathom function if loaded', () => {
194 |     return new Promise(resolve => {
195 |       window.fathom = {
196 |         trackPageview: jest.fn(),
197 |         trackEvent: (...args) => {
198 |           expect(args).toStrictEqual(['dynamic event test', { _value: 0 }]);
199 |           resolve();
200 |         }
201 |       };
202 | 
203 |       Fathom.trackEvent('dynamic event test', {
204 |         _value: 0
205 |       });
206 |     });
207 |   });
208 | });
209 | 
210 | describe('enableTrackingForMe', () => {
211 |   it('enqueues the operation if fathom is not loaded', () => {
212 |     Fathom.enableTrackingForMe();
213 |     expect(window.__fathomClientQueue).toStrictEqual([
214 |       { type: 'enableTrackingForMe' }
215 |     ]);
216 |   });
217 | 
218 |   it('calls the fathom function if loaded', () => {
219 |     return new Promise(resolve => {
220 |       window.fathom = {
221 |         trackPageview: jest.fn(),
222 |         enableTrackingForMe: () => {
223 |           resolve();
224 |         }
225 |       };
226 | 
227 |       Fathom.enableTrackingForMe();
228 |     });
229 |   });
230 | });
231 | 
232 | describe('blockTrackingForMe', () => {
233 |   it('enqueues the operation if fathom is not loaded', () => {
234 |     Fathom.blockTrackingForMe();
235 |     expect(window.__fathomClientQueue).toStrictEqual([
236 |       { type: 'blockTrackingForMe' }
237 |     ]);
238 |   });
239 | 
240 |   it('calls the fathom function if loaded', () => {
241 |     return new Promise(resolve => {
242 |       window.fathom = {
243 |         trackPageview: jest.fn(),
244 |         blockTrackingForMe: () => {
245 |           resolve();
246 |         }
247 |       };
248 | 
249 |       Fathom.blockTrackingForMe();
250 |     });
251 |   });
252 | });
253 | 
254 | describe('isTrackingEnabled', () => {
255 |   beforeEach(() => localStorage.clear);
256 |   const key = 'blockFathomTracking';
257 | 
258 |   it("returns `true` if the localStorage value doesn't exist", () => {
259 |     const response = Fathom.isTrackingEnabled();
260 |     expect(localStorage.getItem).toHaveBeenLastCalledWith(key);
261 |     expect(response).toBe(true);
262 |   });
263 |   it("returns `false` when the localStorage value contains string 'true'", () => {
264 |     localStorage.setItem(key, 'true');
265 | 
266 |     const response = Fathom.isTrackingEnabled();
267 |     expect(localStorage.getItem).toHaveBeenLastCalledWith(key);
268 |     expect(response).toBe(false);
269 |   });
270 |   it("treats localStorage values other than 'true' as non-truthy", () => {
271 |     localStorage.setItem(key, 'function nonsense(){ return "noodle"; }');
272 | 
273 |     const response = Fathom.isTrackingEnabled();
274 |     expect(localStorage.getItem).toHaveBeenLastCalledWith(key);
275 |     expect(response).toBe(true);
276 |   });
277 | });
278 | 
279 | describe('setSite', () => {
280 |   it('enqueues the operation if fathom is not loaded', () => {
281 |     Fathom.setSite('NEW_ID');
282 |     expect(window.__fathomClientQueue).toStrictEqual([
283 |       { type: 'setSite', id: 'NEW_ID' }
284 |     ]);
285 |   });
286 | 
287 |   it('calls the fathom function if loaded', () => {
288 |     return new Promise(resolve => {
289 |       window.fathom = {
290 |         setSite: id => {
291 |           expect(id).toStrictEqual('NEW_ID');
292 |           resolve();
293 |         }
294 |       };
295 | 
296 |       Fathom.setSite('NEW_ID');
297 |     });
298 |   });
299 | });
300 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "lib": ["DOM", "DOM.Iterable", "ES2020"],
 4 |     "target": "ES2020",
 5 |     "declaration": true,
 6 |     "declarationDir": "types",
 7 |     "strict": true,
 8 |     "isolatedModules": true,
 9 |     "strictNullChecks": false,
10 |     "moduleResolution": "Node"
11 |   },
12 |   "include": ["src/**/*"],
13 |   "exclude": ["node_modules", "dist"]
14 | }
15 | 


--------------------------------------------------------------------------------