From 1cbe0026a5624f2bc092c4ef9527809d90f67b95 Mon Sep 17 00:00:00 2001
From: Nick Amoscato <nick@amoscato.com>
Date: Wed, 7 May 2025 14:29:27 -0400
Subject: [PATCH 1/3] Add TypeScript definitions

---
 README.npm.md            |   5 ++
 count.d.ts               | 146 +++++++++++++++++++++++++++++++++++++++
 package.json             |  30 ++++++++
 tpl/help/countjs-host.md |   2 +
 4 files changed, 183 insertions(+)
 create mode 100644 README.npm.md
 create mode 100644 count.d.ts
 create mode 100644 package.json

diff --git a/README.npm.md b/README.npm.md
new file mode 100644
index 00000000..c66a3bc2
--- /dev/null
+++ b/README.npm.md
@@ -0,0 +1,5 @@
+# GoatCounter
+
+This package contains the source of [GoatCounter's](https://www.goatcounter.com/) `count.js` and its corresponding TypeScript definitions.
+
+It facilitates [self-hosting](https://www.goatcounter.com/help/countjs-host) but does not intend to be imported as a conventional module.
diff --git a/count.d.ts b/count.d.ts
new file mode 100644
index 00000000..a5447a2d
--- /dev/null
+++ b/count.d.ts
@@ -0,0 +1,146 @@
+interface Window {
+	/**
+	 * GoatCounter JavaScript API
+	 *
+	 * @see https://www.goatcounter.com/help/js
+	 */
+	goatcounter:
+		| (GoatCounter.Settings &
+				GoatCounter.DataParameters &
+				GoatCounter.Methods)
+		| undefined;
+}
+
+declare namespace GoatCounter {
+	/**
+	 * Settings that can be defined via:
+	 *
+	 * - `window.goatcounter` object, declared _before_ loading `count.js`
+	 * - `<script>` tag `data-goatcounter-settings` attribute (will override settings in `window.goatcounter`)
+	 */
+	interface Settings {
+		/** Don’t do anything on page load, for cases where you want to call `count()` manually. Also won’t bind events. */
+		no_onload?: boolean;
+		/** Don’t bind events. */
+		no_events?: boolean;
+		/** Allow requests from local addresses (`localhost`, `192.168.0.0`, etc.) for testing the integration locally. */
+		allow_local?: boolean;
+		/** Allow requests when the page is loaded in a frame or iframe. */
+		allow_frame?: boolean;
+		/** Customize the endpoint for sending pageviews to (overrides the URL in `data-goatcounter`). Only useful if you have `no_onload`. */
+		endpoint?: string;
+	}
+
+	interface DataParameters {
+		/**
+		 * Page path (without domain) or event name.
+		 *
+		 * Default is the value of `<link rel="canonical">` if it exists, or
+		 * `location.pathname + location.search`.
+		 *
+		 * Alternatively, a callback that takes the default value and
+		 * returns a new value. No pageview is sent if the callback returns
+		 * `null`.
+		 *
+		 * @see https://www.goatcounter.com/help/modify
+		 */
+		path?: string | ((defaultValue: string) => string | null);
+
+		/**
+		 * Human-readable title.
+		 *
+		 * Default is `document.title`.
+		 *
+		 * Alternatively, a callback that takes the default value and
+		 * returns a new value.
+		 */
+		title?: string | ((defaultValue: string) => string);
+
+		/**
+		 * Where the user came from; can be an URL (`https://example.com`)
+		 * or any string (`June Newsletter`).
+		 *
+		 * Default is the `Referer` header.
+		 *
+		 * Alternatively, a callback that takes the default value and
+		 * returns a new value.
+		 */
+		referrer?: string | ((defaultValue: string) => string);
+
+		/**
+		 * Treat the path as an event, rather than a URL.
+		 */
+		event?: boolean;
+	}
+
+	interface Methods {
+		/**
+		 * Send a pageview or event to GoatCounter.
+		 *
+		 * @param vars merged in to the global `window.goatcounter`, if it exists
+		 */
+		count(vars?: DataParameters): void;
+
+		/**
+		 * Get URL to send to the server.
+		 *
+		 * @param vars merged in to the global `window.goatcounter`, if it exists
+		 */
+		url(vars?: DataParameters): string | undefined;
+
+		/**
+		 * Determine if this request should be filtered.
+		 *
+		 * This will filter some bots, pre-render requests, frames (unless
+		 * `allow_frame` is set), and local requests (unless `allow_local`
+		 * is set).
+		 *
+		 * @returns string with the reason or `false`
+		 */
+		filter(): string | false;
+
+		/**
+		 * Bind a click event to every element with `data-goatcounter-click`.
+		 *
+		 * Called on page load unless `no_onload` or `no_events` is set. You
+		 * may need to call this manually if you insert elements after the
+		 * page loads.
+		 *
+		 * @see https://www.goatcounter.com/help/events
+		 */
+		bind_events(): void;
+
+		/**
+		 * Get a single query parameter from the current page’s URL.
+		 *
+		 * @returns `undefined` if the parameter doesn’t exist.
+		 */
+		get_query(name: string): string | undefined;
+
+		/**
+		 * Display a page’s view count by appending an HTML document or image.
+		 *
+		 * @see https://www.goatcounter.com/help/visitor-counter
+		 */
+		visit_count(opt?: VisitCountOptions): void;
+	}
+
+	interface VisitCountOptions {
+		/** HTML selector to append to, can use CSS selectors as accepted by `querySelector()`. Default is `body`. */
+		append?: string;
+		/** Output type. Default is `html`. */
+		type?: "html" | "svg" | "png";
+		/** Path to display; normally this is detected from the URL, but you can override it. */
+		path?: string;
+		/** Don’t display “by GoatCounter” branding */
+		no_branding?: boolean;
+		/** HTML attributes to set or override for the element, only when type is `html`. */
+		attr?: Record<string, string>;
+		/** Extra CSS styling for HTML or SVG; only when `type` is `html` or `svg`. */
+		style?: string;
+		/** Start date; default is to include everything. As `year-month-day` or `week`, `month`, `year` for this period ago. */
+		start?: string;
+		/** End date; default is to include everything. As `year-month-day`. */
+		end?: string;
+	}
+}
diff --git a/package.json b/package.json
new file mode 100644
index 00000000..3f120d1a
--- /dev/null
+++ b/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "goatcounter",
+  "version": "4.0.0",
+  "description": "Easy web analytics. No tracking of personal data.",
+  "keywords": [
+	"go",
+	"golang",
+	"analytics"
+  ],
+  "main": "public/count.js",
+  "types": "count.d.ts",
+  "scripts": {
+    "prepack": "cp README.md git.README.md && mv README.npm.md README.md",
+	"postpack": "mv README.md README.npm.md && mv git.README.md README.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arp242/goatcounter.git"
+  },
+  "author": "Martin Tournoij <martin@arp242.net>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/arp242/goatcounter/issues"
+  },
+  "homepage": "https://www.goatcounter.com",
+  "files": [
+	"public/count.js",
+	"count.d.ts"
+  ]
+}
diff --git a/tpl/help/countjs-host.md b/tpl/help/countjs-host.md
index 17fbbda5..2b306d38 100644
--- a/tpl/help/countjs-host.md
+++ b/tpl/help/countjs-host.md
@@ -7,6 +7,8 @@ inside `<script>` tags. You won’t get any new features or other updates, but t
 To host `count.js` somewhere else just copy it from https://gc.zgo.at/count.js
 and adjust the URL in `src`.
 
+For convenience, the script is also published as an [npm package](https://www.npmjs.com/package/goatcounter) which can be copied into a public directory during your application's build process.
+
 If you include it in the page's body then be sure to include the
 `data-goatcounter` attribute on the script tag, or set `goatcounter.endpoint` so
 GoatCounter knows where to send the pageviews to:

From f4cb121d53d8de66c8d35705f84da04dad8adf09 Mon Sep 17 00:00:00 2001
From: Nick Amoscato <nick@amoscato.com>
Date: Fri, 23 May 2025 21:31:37 -0400
Subject: [PATCH 2/3] Fix inconsistent package.json spacing

---
 .gitignore   |  3 +++
 package.json | 12 ++++++------
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index b5373b17..d2fd908e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,3 +24,6 @@
 
 # Dev log
 /.dev.log
+
+# npm manifest
+package-lock.json
diff --git a/package.json b/package.json
index 3f120d1a..ae1ec9de 100644
--- a/package.json
+++ b/package.json
@@ -3,15 +3,15 @@
   "version": "4.0.0",
   "description": "Easy web analytics. No tracking of personal data.",
   "keywords": [
-	"go",
-	"golang",
-	"analytics"
+    "go",
+    "golang",
+    "analytics"
   ],
   "main": "public/count.js",
   "types": "count.d.ts",
   "scripts": {
     "prepack": "cp README.md git.README.md && mv README.npm.md README.md",
-	"postpack": "mv README.md README.npm.md && mv git.README.md README.md"
+    "postpack": "mv README.md README.npm.md && mv git.README.md README.md"
   },
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
   },
   "homepage": "https://www.goatcounter.com",
   "files": [
-	"public/count.js",
-	"count.d.ts"
+    "public/count.js",
+    "count.d.ts"
   ]
 }

From 9b86465dd4d0c417aeeaded28e68e46bb8194004 Mon Sep 17 00:00:00 2001
From: Nick Amoscato <nick@amoscato.com>
Date: Sat, 31 May 2025 15:28:24 -0400
Subject: [PATCH 3/3] Expand documentation

---
 .gitignore               | 10 ----------
 README.npm.md            | 36 +++++++++++++++++++++++++++++++++++-
 tpl/help/countjs-host.md |  2 +-
 tpl/help/js.md           | 19 +++++++++++++++++++
 4 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/.gitignore b/.gitignore
index d2fd908e..ffdd6593 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,15 +15,5 @@
 # Never store certificates.
 *.pem
 
-# Default acme-secrets.
-/acme-secrets
-
-# Coverage reports
-/coverage
-/coverage.*
-
-# Dev log
-/.dev.log
-
 # npm manifest
 package-lock.json
diff --git a/README.npm.md b/README.npm.md
index c66a3bc2..ef1bc44a 100644
--- a/README.npm.md
+++ b/README.npm.md
@@ -2,4 +2,38 @@
 
 This package contains the source of [GoatCounter's](https://www.goatcounter.com/) `count.js` and its corresponding TypeScript definitions.
 
-It facilitates [self-hosting](https://www.goatcounter.com/help/countjs-host) but does not intend to be imported as a conventional module.
+## Installation
+
+```bash
+npm install goatcounter
+```
+
+## Usage
+
+This package facilitates [self-hosting](https://www.goatcounter.com/help/countjs-host) and/or provides TypeScript definitions. It does not intend to be imported as a conventional module.
+
+### Self-Hosting
+
+1. Programmatically copy `./node_modules/goatcounter/public/count.js` to a public webroot directory during your application's build process.
+
+2. Reference the script via relative URL:
+
+    ```html
+    <script
+        data-goatcounter="https://MYCODE.goatcounter.com/count"
+        async
+        src="/count.js"
+    ></script>
+    ```
+
+### TypeScript
+
+To extend the global `Window` interface with a typed `goatcounter` property, configure TSConfig [`types`](https://www.typescriptlang.org/tsconfig/#types):
+
+```json
+{
+    "compilerOptions": {
+        "types": ["goatcounter"]
+    }
+}
+```
diff --git a/tpl/help/countjs-host.md b/tpl/help/countjs-host.md
index 2b306d38..7090eba5 100644
--- a/tpl/help/countjs-host.md
+++ b/tpl/help/countjs-host.md
@@ -7,7 +7,7 @@ inside `<script>` tags. You won’t get any new features or other updates, but t
 To host `count.js` somewhere else just copy it from https://gc.zgo.at/count.js
 and adjust the URL in `src`.
 
-For convenience, the script is also published as an [npm package](https://www.npmjs.com/package/goatcounter) which can be copied into a public directory during your application's build process.
+For convenience, the script is also published as an [npm package](https://www.npmjs.com/package/goatcounter). Once installed, it can be programmatically copied from `./node_modules/goatcounter/public/count.js` to a public webroot directory during your application's build process.
 
 If you include it in the page's body then be sure to include the
 `data-goatcounter` attribute on the script tag, or set `goatcounter.endpoint` so
diff --git a/tpl/help/js.md b/tpl/help/js.md
index ab806e15..01fc3c21 100644
--- a/tpl/help/js.md
+++ b/tpl/help/js.md
@@ -157,3 +157,22 @@ Note there is also a *Campaign Parameters* setting, which is probably easier for
 most people. This is just if you want to get the campaign on only some pages, or
 want to do some more advanced filtering (such as only including your own
 campaigns).
+
+TypeScript
+----------
+
+An [npm package](https://www.npmjs.com/package/goatcounter) contains `count.js` and its corresponding TypeScript definitions.
+
+To extend the global `Window` interface with a typed `goatcounter` property:
+
+1. Install package:
+
+        npm install goatcounter
+
+2. Configure TSConfig [`types`](https://www.typescriptlang.org/tsconfig/#types):
+
+        {
+            "compilerOptions": {
+                "types": ["goatcounter"]
+            }
+        }