@pageflock/analytics 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -127,9 +127,25 @@ No-code events work too: `<button data-track="Signup" data-track-plan="pro">`.
127
127
  | `autoEvents` | `boolean` | `false` | Also track outbound link clicks, file downloads and 404 pages, like `s.auto.js`. |
128
128
  | `hashRouting` | `boolean` | `false` | Count `#hash` changes as page views, for hash-routed apps. |
129
129
  | `beforeSend` | `(event: AnalyticsEvent) => AnalyticsEvent \| null` | none | Change an event before it is sent, or return `null` to drop it. |
130
+ | `mask` | `string[]` | none | Route patterns, such as `/projects/[id]`, reported in place of the paths they match. See [Masking URLs](#masking-urls). |
130
131
  | `debug` | `boolean` | `false` | Log every event to the console, including on localhost. |
131
132
 
132
- `site`, `endpoint`, `autoEvents` and `hashRouting` are read when tracking starts. `beforeSend` and `debug` can change on later renders.
133
+ `site`, `endpoint`, `autoEvents` and `hashRouting` are read when tracking starts. `beforeSend`, `mask` and `debug` can change on later renders.
134
+
135
+ ### Masking URLs
136
+
137
+ Paths often carry data that belongs to your users: a project's name, an order number, an invite token. Pass the routes that hold it as `mask`, and each page view and event on a matching path is reported as the route pattern instead, so `/projects/acme-launch/settings` arrives as `/projects/[id]/settings`, and so does the `path` of a 404 event. The real path never leaves the browser, and the dashboard groups every project under one row.
138
+
139
+ ```tsx
140
+ <Analytics
141
+ site="SITE_ID"
142
+ mask={["/projects/[id]", "/projects/[id]/settings", "/docs/[...slug]"]}
143
+ />
144
+ ```
145
+
146
+ Patterns use file-router syntax: `[name]` matches one segment, `[...name]` one or more, and `[[...name]]` zero or more. When several match, the most specific wins, so `/projects/new` beats `/projects/[id]`. Paths that match no pattern are sent as they are. The query string is kept, since Pageflock only stores UTM tags and the parameters you allow from it.
147
+
148
+ `beforeSend` runs first and sees the real URL, so it can still drop pages by their path. List only the dynamic routes; static paths have nothing to hide.
133
149
 
134
150
  ### Self-hosting
135
151
 
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  inject
3
- } from "./chunk-6IXYXMX6.js";
3
+ } from "./chunk-UXUNZ35R.js";
4
4
 
5
5
  // src/react.ts
6
6
  import { useEffect } from "react";
@@ -138,6 +138,89 @@ var init = ({
138
138
  return tracker;
139
139
  };
140
140
 
141
+ // src/mask.ts
142
+ var OPTIONAL_REST = /^\[\[\.\.\..+\]\]$/u;
143
+ var REST = /^\[\.\.\..+\]$/u;
144
+ var DYNAMIC = /^\[.+\]$/u;
145
+ var split = (path) => path.split("/").filter(Boolean);
146
+ var parseSegment = (segment) => {
147
+ if (OPTIONAL_REST.test(segment)) {
148
+ return { kind: "rest", optional: true };
149
+ }
150
+ if (REST.test(segment)) {
151
+ return { kind: "rest", optional: false };
152
+ }
153
+ if (DYNAMIC.test(segment)) {
154
+ return { kind: "dynamic" };
155
+ }
156
+ return { kind: "static", value: segment };
157
+ };
158
+ var parse = (pattern) => ({
159
+ pattern,
160
+ segments: split(pattern).map(parseSegment)
161
+ });
162
+ var decode = (part) => {
163
+ try {
164
+ return decodeURIComponent(part);
165
+ } catch {
166
+ return part;
167
+ }
168
+ };
169
+ var matches = (segments, parts, at = 0, index = 0) => {
170
+ const segment = segments[at];
171
+ if (!segment) {
172
+ return index === parts.length;
173
+ }
174
+ if (segment.kind === "rest") {
175
+ return segment.optional || index < parts.length;
176
+ }
177
+ const part = parts[index];
178
+ if (part === void 0) {
179
+ return false;
180
+ }
181
+ if (segment.kind === "static" && segment.value !== decode(part)) {
182
+ return false;
183
+ }
184
+ return matches(segments, parts, at + 1, index + 1);
185
+ };
186
+ var RANK = { static: 0, dynamic: 1, rest: 2 };
187
+ var bySpecificity = (a, b) => {
188
+ const length = Math.max(a.segments.length, b.segments.length);
189
+ for (let index = 0; index < length; index += 1) {
190
+ const left = a.segments[index];
191
+ const right = b.segments[index];
192
+ if (!(left && right)) {
193
+ return left ? -1 : 1;
194
+ }
195
+ const difference = RANK[left.kind] - RANK[right.kind];
196
+ if (difference !== 0) {
197
+ return difference;
198
+ }
199
+ }
200
+ return 0;
201
+ };
202
+ var createMasker = (patterns) => {
203
+ const masks = patterns.map(parse).sort(bySpecificity);
204
+ return (href) => {
205
+ if (masks.length === 0) {
206
+ return href;
207
+ }
208
+ let url;
209
+ try {
210
+ url = new URL(href);
211
+ } catch {
212
+ return href;
213
+ }
214
+ const parts = split(url.pathname);
215
+ const mask = masks.find(({ segments }) => matches(segments, parts));
216
+ if (!mask) {
217
+ return href;
218
+ }
219
+ url.pathname = mask.pattern;
220
+ return url.href;
221
+ };
222
+ };
223
+
141
224
  // src/index.ts
142
225
  var LOG_PREFIX = "[pageflock]";
143
226
  var pageflockGlobal = () => globalThis;
@@ -146,8 +229,32 @@ var current;
146
229
  var log = (message, event) => {
147
230
  console.info(`${LOG_PREFIX} ${message}`, event);
148
231
  };
232
+ var masker;
233
+ var currentMasker = () => {
234
+ const patterns = current?.mask ?? [];
235
+ const key = patterns.join("\n");
236
+ if (masker?.key !== key) {
237
+ masker = { key, apply: createMasker(patterns) };
238
+ }
239
+ return masker.apply;
240
+ };
241
+ var applyMask = (event) => {
242
+ if (!event) {
243
+ return event;
244
+ }
245
+ const mask = currentMasker();
246
+ const url = mask(event.url);
247
+ const path = event.props?.path;
248
+ if (event.name === "404" && typeof path === "string") {
249
+ const masked = new URL(mask(new URL(path, url).href)).pathname;
250
+ return { ...event, url, props: { ...event.props, path: masked } };
251
+ }
252
+ return { ...event, url };
253
+ };
149
254
  var beforeSend = (event) => {
150
- const result = current?.beforeSend ? current.beforeSend(event) : event;
255
+ const result = applyMask(
256
+ current?.beforeSend ? current.beforeSend(event) : event
257
+ );
151
258
  if (current?.debug) {
152
259
  log(result ? event.name : `${event.name} (dropped)`, result ?? event);
153
260
  }
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  inject,
3
3
  track
4
- } from "./chunks/chunk-6IXYXMX6.js";
4
+ } from "./chunks/chunk-UXUNZ35R.js";
5
5
  export {
6
6
  inject,
7
7
  track
package/dist/next.js CHANGED
@@ -1,10 +1,10 @@
1
1
  "use client";
2
2
  import {
3
3
  Analytics
4
- } from "./chunks/chunk-AYI42IVX.js";
4
+ } from "./chunks/chunk-5NKMGFKF.js";
5
5
  import {
6
6
  track
7
- } from "./chunks/chunk-6IXYXMX6.js";
7
+ } from "./chunks/chunk-UXUNZ35R.js";
8
8
  export {
9
9
  Analytics,
10
10
  track
package/dist/react.js CHANGED
@@ -1,10 +1,10 @@
1
1
  "use client";
2
2
  import {
3
3
  Analytics
4
- } from "./chunks/chunk-AYI42IVX.js";
4
+ } from "./chunks/chunk-5NKMGFKF.js";
5
5
  import {
6
6
  track
7
- } from "./chunks/chunk-6IXYXMX6.js";
7
+ } from "./chunks/chunk-UXUNZ35R.js";
8
8
  export {
9
9
  Analytics,
10
10
  track
@@ -24,12 +24,19 @@ export interface AnalyticsOptions {
24
24
  * return null to drop it. Use it to strip tokens from URLs or skip pages.
25
25
  */
26
26
  beforeSend?: (event: AnalyticsEvent) => AnalyticsEvent | null;
27
+ /**
28
+ * Route patterns, such as `/projects/[id]` or `/docs/[...slug]`, reported
29
+ * in place of the paths they match, so ids, slugs and names in URLs never
30
+ * leave the browser. The most specific match wins.
31
+ * Applied to every event after `beforeSend`.
32
+ */
33
+ mask?: readonly string[];
27
34
  /** Log every event to the console, including on localhost where nothing is sent. */
28
35
  debug?: boolean;
29
36
  }
30
37
  /**
31
38
  * Starts tracking and records the first page view. Safe to call more than
32
- * once: later calls only update `beforeSend` and `debug`. Does nothing on the
39
+ * once: later calls only update `beforeSend`, `mask` and `debug`. Does nothing on the
33
40
  * server, or when the Pageflock script tag is already on the page.
34
41
  */
35
42
  export declare const inject: (options: AnalyticsOptions) => void;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * URL masks: route patterns such as `/projects/[id]` that stand in for the
3
+ * real path, so ids, slugs and names in URLs never leave the browser.
4
+ *
5
+ * Segments in a pattern are a literal (`settings`), one dynamic segment
6
+ * (`[id]`), one or more (`[...path]`) or zero or more (`[[...path]]`), the
7
+ * same syntax as file-based routers.
8
+ */
9
+ /**
10
+ * Builds a function that turns a full URL into the URL to report: the first
11
+ * matching pattern replaces the path, and the query and fragment are kept.
12
+ * A URL that matches no pattern is returned unchanged.
13
+ */
14
+ export declare const createMasker: (patterns: readonly string[]) => (href: string) => string;
@@ -13,6 +13,7 @@ export declare const Analytics: import("vue").DefineComponent<import("vue").Extr
13
13
  hashRouting: BooleanConstructor;
14
14
  debug: BooleanConstructor;
15
15
  beforeSend: PropType<AnalyticsOptions["beforeSend"]>;
16
+ mask: PropType<AnalyticsOptions["mask"]>;
16
17
  }>, () => null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
17
18
  site: {
18
19
  type: StringConstructor;
@@ -23,6 +24,7 @@ export declare const Analytics: import("vue").DefineComponent<import("vue").Extr
23
24
  hashRouting: BooleanConstructor;
24
25
  debug: BooleanConstructor;
25
26
  beforeSend: PropType<AnalyticsOptions["beforeSend"]>;
27
+ mask: PropType<AnalyticsOptions["mask"]>;
26
28
  }>> & Readonly<{}>, {
27
29
  autoEvents: boolean;
28
30
  hashRouting: boolean;
package/dist/vue.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  inject,
3
3
  track
4
- } from "./chunks/chunk-6IXYXMX6.js";
4
+ } from "./chunks/chunk-UXUNZ35R.js";
5
5
 
6
6
  // src/vue.ts
7
7
  import { defineComponent, onMounted } from "vue";
@@ -13,7 +13,8 @@ var Analytics = defineComponent({
13
13
  autoEvents: Boolean,
14
14
  hashRouting: Boolean,
15
15
  debug: Boolean,
16
- beforeSend: Function
16
+ beforeSend: Function,
17
+ mask: Array
17
18
  },
18
19
  setup(props) {
19
20
  onMounted(() => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pageflock/analytics",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Pageflock analytics for React, Next.js, Vue and any bundled site: cookieless, under 2 KB.",
5
5
  "keywords": [
6
6
  "analytics",
@@ -59,7 +59,7 @@
59
59
  "typescript": "7.0.2",
60
60
  "vitest": "5.1.0",
61
61
  "vue": "3.5.45",
62
- "@pageflock/tracker": "0.1.1"
62
+ "@pageflock/tracker": "0.1.2"
63
63
  },
64
64
  "peerDependencies": {
65
65
  "react": ">=18",