|
| 1 | +interface Window { |
| 2 | + /** |
| 3 | + * GoatCounter JavaScript API |
| 4 | + * |
| 5 | + * @see https://www.goatcounter.com/help/js |
| 6 | + */ |
| 7 | + goatcounter: |
| 8 | + | (GoatCounter.Settings & |
| 9 | + GoatCounter.DataParameters & |
| 10 | + GoatCounter.Methods) |
| 11 | + | undefined; |
| 12 | +} |
| 13 | + |
| 14 | +declare namespace GoatCounter { |
| 15 | + /** |
| 16 | + * Settings that can be defined via: |
| 17 | + * |
| 18 | + * - `window.goatcounter` object, declared _before_ loading `count.js` |
| 19 | + * - `<script>` tag `data-goatcounter-settings` attribute (will override settings in `window.goatcounter`) |
| 20 | + */ |
| 21 | + interface Settings { |
| 22 | + /** Don’t do anything on page load, for cases where you want to call `count()` manually. Also won’t bind events. */ |
| 23 | + no_onload?: boolean; |
| 24 | + /** Don’t bind events. */ |
| 25 | + no_events?: boolean; |
| 26 | + /** Allow requests from local addresses (`localhost`, `192.168.0.0`, etc.) for testing the integration locally. */ |
| 27 | + allow_local?: boolean; |
| 28 | + /** Allow requests when the page is loaded in a frame or iframe. */ |
| 29 | + allow_frame?: boolean; |
| 30 | + /** Customize the endpoint for sending pageviews to (overrides the URL in `data-goatcounter`). Only useful if you have `no_onload`. */ |
| 31 | + endpoint?: string; |
| 32 | + } |
| 33 | + |
| 34 | + interface DataParameters { |
| 35 | + /** |
| 36 | + * Page path (without domain) or event name. |
| 37 | + * |
| 38 | + * Default is the value of `<link rel="canonical">` if it exists, or |
| 39 | + * `location.pathname + location.search`. |
| 40 | + * |
| 41 | + * Alternatively, a callback that takes the default value and |
| 42 | + * returns a new value. No pageview is sent if the callback returns |
| 43 | + * `null`. |
| 44 | + * |
| 45 | + * @see https://www.goatcounter.com/help/modify |
| 46 | + */ |
| 47 | + path?: string | ((defaultValue: string) => string | null); |
| 48 | + |
| 49 | + /** |
| 50 | + * Human-readable title. |
| 51 | + * |
| 52 | + * Default is `document.title`. |
| 53 | + * |
| 54 | + * Alternatively, a callback that takes the default value and |
| 55 | + * returns a new value. |
| 56 | + */ |
| 57 | + title?: string | ((defaultValue: string) => string); |
| 58 | + |
| 59 | + /** |
| 60 | + * Where the user came from; can be an URL (`https://example.com`) |
| 61 | + * or any string (`June Newsletter`). |
| 62 | + * |
| 63 | + * Default is the `Referer` header. |
| 64 | + * |
| 65 | + * Alternatively, a callback that takes the default value and |
| 66 | + * returns a new value. |
| 67 | + */ |
| 68 | + referrer?: string | ((defaultValue: string) => string); |
| 69 | + |
| 70 | + /** |
| 71 | + * Treat the path as an event, rather than a URL. |
| 72 | + */ |
| 73 | + event?: boolean; |
| 74 | + } |
| 75 | + |
| 76 | + interface Methods { |
| 77 | + /** |
| 78 | + * Send a pageview or event to GoatCounter. |
| 79 | + * |
| 80 | + * @param vars merged in to the global `window.goatcounter`, if it exists |
| 81 | + */ |
| 82 | + count(vars?: DataParameters): void; |
| 83 | + |
| 84 | + /** |
| 85 | + * Get URL to send to the server. |
| 86 | + * |
| 87 | + * @param vars merged in to the global `window.goatcounter`, if it exists |
| 88 | + */ |
| 89 | + url(vars?: DataParameters): string | undefined; |
| 90 | + |
| 91 | + /** |
| 92 | + * Determine if this request should be filtered. |
| 93 | + * |
| 94 | + * This will filter some bots, pre-render requests, frames (unless |
| 95 | + * `allow_frame` is set), and local requests (unless `allow_local` |
| 96 | + * is set). |
| 97 | + * |
| 98 | + * @returns string with the reason or `false` |
| 99 | + */ |
| 100 | + filter(): string | false; |
| 101 | + |
| 102 | + /** |
| 103 | + * Bind a click event to every element with `data-goatcounter-click`. |
| 104 | + * |
| 105 | + * Called on page load unless `no_onload` or `no_events` is set. You |
| 106 | + * may need to call this manually if you insert elements after the |
| 107 | + * page loads. |
| 108 | + * |
| 109 | + * @see https://www.goatcounter.com/help/events |
| 110 | + */ |
| 111 | + bind_events(): void; |
| 112 | + |
| 113 | + /** |
| 114 | + * Get a single query parameter from the current page’s URL. |
| 115 | + * |
| 116 | + * @returns `undefined` if the parameter doesn’t exist. |
| 117 | + */ |
| 118 | + get_query(name: string): string | undefined; |
| 119 | + |
| 120 | + /** |
| 121 | + * Display a page’s view count by appending an HTML document or image. |
| 122 | + * |
| 123 | + * @see https://www.goatcounter.com/help/visitor-counter |
| 124 | + */ |
| 125 | + visit_count(opt?: VisitCountOptions): void; |
| 126 | + } |
| 127 | + |
| 128 | + interface VisitCountOptions { |
| 129 | + /** HTML selector to append to, can use CSS selectors as accepted by `querySelector()`. Default is `body`. */ |
| 130 | + append?: string; |
| 131 | + /** Output type. Default is `html`. */ |
| 132 | + type?: "html" | "svg" | "png"; |
| 133 | + /** Path to display; normally this is detected from the URL, but you can override it. */ |
| 134 | + path?: string; |
| 135 | + /** Don’t display “by GoatCounter” branding */ |
| 136 | + no_branding?: boolean; |
| 137 | + /** HTML attributes to set or override for the element, only when type is `html`. */ |
| 138 | + attr?: Record<string, string>; |
| 139 | + /** Extra CSS styling for HTML or SVG; only when `type` is `html` or `svg`. */ |
| 140 | + style?: string; |
| 141 | + /** Start date; default is to include everything. As `year-month-day` or `week`, `month`, `year` for this period ago. */ |
| 142 | + start?: string; |
| 143 | + /** End date; default is to include everything. As `year-month-day`. */ |
| 144 | + end?: string; |
| 145 | + } |
| 146 | +} |
0 commit comments