@aglyn/aglyn 1.19.0 → 1.20.1

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.
Files changed (33) hide show
  1. package/package.json +11 -11
  2. package/src/lib/app-utils/analytics-events.d.ts +44 -0
  3. package/src/lib/app-utils/analytics-events.js +226 -21
  4. package/src/lib/app-utils/analytics-events.js.map +1 -1
  5. package/src/lib/app-utils/analytics-link-clicks.js +3 -4
  6. package/src/lib/app-utils/analytics-link-clicks.js.map +1 -1
  7. package/src/lib/app-utils/crm.d.ts +80 -1
  8. package/src/lib/app-utils/crm.js +136 -5
  9. package/src/lib/app-utils/crm.js.map +1 -1
  10. package/src/lib/app-utils/docs-help-sections.generated.js +1 -1
  11. package/src/lib/app-utils/docs-help-sections.generated.js.map +1 -1
  12. package/src/lib/app-utils/docs-help.generated.d.ts +1 -1
  13. package/src/lib/app-utils/docs-help.generated.js +5 -1
  14. package/src/lib/app-utils/docs-help.generated.js.map +1 -1
  15. package/src/lib/app-utils/docs-index.generated.js +26 -12
  16. package/src/lib/app-utils/docs-index.generated.js.map +1 -1
  17. package/src/lib/app-utils/error-beacon.d.ts +8 -0
  18. package/src/lib/app-utils/error-beacon.js +11 -0
  19. package/src/lib/app-utils/error-beacon.js.map +1 -1
  20. package/src/lib/plugin-manager/feature-plugins.d.ts +8 -0
  21. package/src/lib/plugin-manager/feature-plugins.js.map +1 -1
  22. package/src/lib/plugin-manager/first-party-plugins.generated.d.ts +6 -0
  23. package/src/lib/plugin-manager/first-party-plugins.generated.js +20 -0
  24. package/src/lib/plugin-manager/first-party-plugins.generated.js.map +1 -1
  25. package/src/lib/plugin-manager/plugin-scope-sharing.d.ts +22 -0
  26. package/src/lib/plugin-manager/plugin-scope-sharing.js +21 -1
  27. package/src/lib/plugin-manager/plugin-scope-sharing.js.map +1 -1
  28. package/src/lib/plugin-manager/plugin-site-exclusions.d.ts +107 -0
  29. package/src/lib/plugin-manager/plugin-site-exclusions.js +169 -0
  30. package/src/lib/plugin-manager/plugin-site-exclusions.js.map +1 -0
  31. package/src/lib/plugin-manager/plugin-site-resources.d.ts +19 -0
  32. package/src/lib/plugin-manager/plugin-site-resources.js +2 -0
  33. package/src/lib/plugin-manager/plugin-site-resources.js.map +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aglyn/aglyn",
3
- "version": "1.19.0",
3
+ "version": "1.20.1",
4
4
  "license": "Apache-2.0",
5
5
  "homepage": "https://aglyn.com",
6
6
  "repository": {
@@ -37,16 +37,16 @@
37
37
  "./package.json": "./package.json"
38
38
  },
39
39
  "dependencies": {
40
- "@aglyn/shared-data-enums": "1.19.0",
41
- "@aglyn/shared-data-mdi": "1.19.0",
42
- "@aglyn/shared-data-types": "1.19.0",
43
- "@aglyn/shared-util-email": "1.19.0",
44
- "@aglyn/shared-util-first-touch": "1.19.0",
45
- "@aglyn/shared-util-http": "1.19.0",
46
- "@aglyn/shared-util-logger": "1.19.0",
47
- "@aglyn/shared-util-timestamp": "1.19.0",
48
- "@aglyn/shared-util-tools": "1.19.0",
49
- "@aglyn/shared-util-vendor": "1.19.0",
40
+ "@aglyn/shared-data-enums": "1.20.1",
41
+ "@aglyn/shared-data-mdi": "1.20.1",
42
+ "@aglyn/shared-data-types": "1.20.1",
43
+ "@aglyn/shared-util-email": "1.20.1",
44
+ "@aglyn/shared-util-first-touch": "1.20.1",
45
+ "@aglyn/shared-util-http": "1.20.1",
46
+ "@aglyn/shared-util-logger": "1.20.1",
47
+ "@aglyn/shared-util-timestamp": "1.20.1",
48
+ "@aglyn/shared-util-tools": "1.20.1",
49
+ "@aglyn/shared-util-vendor": "1.20.1",
50
50
  "@data-driven-forms/react-form-renderer": "^4.2.0",
51
51
  "@msgpack/msgpack": "^3.1.3",
52
52
  "@types/unist": "^3.0.3",
@@ -556,6 +556,50 @@ export declare function resetAnalyticsTransport(): void;
556
556
  * value, or the editor promises a length the delivery quietly shortens.
557
557
  */
558
558
  export declare const ANALYTICS_PARAM_MAX_LENGTH = 100;
559
+ /**
560
+ * The params GA4 lets run past {@link ANALYTICS_PARAM_MAX_LENGTH}, at GA4's
561
+ * own documented limits ("Analytics collection limits", Google Analytics
562
+ * Help 9267744): `page_location` 1,000 characters, `page_referrer` 420,
563
+ * `page_title` 300.
564
+ *
565
+ * A page URL is the value most likely to be long for a good reason: a
566
+ * landing URL with its `utm_*` tags and a `gclid` routinely runs past 100,
567
+ * and cutting it there dropped exactly the attribution the query is kept
568
+ * for. A URL's length is measured as it is sent, already URL-encoded, which
569
+ * is how GA4 measures it.
570
+ */
571
+ export declare const ANALYTICS_PARAM_MAX_LENGTH_BY_KEY: Readonly<Record<string, number>>;
572
+ /**
573
+ * Query parameters a URL value loses on its way into an event, matched
574
+ * case-insensitively. Everything else in the query is kept, in the order the
575
+ * URL spelled it: `utm_*`, `gclid`, `ref`, `plan`, `tab`, filters.
576
+ *
577
+ * ## Why a denylist
578
+ *
579
+ * URLs used to be reduced to origin + pathname, because a few console links
580
+ * put personal data or a credential in the query. That also threw away the
581
+ * campaign tags on the session-starting `page_view`: a visitor who scanned a
582
+ * QR code for `/signup?utm_source=event&utm_medium=qr&utm_campaign=trailer-left`
583
+ * reached GA4 as a bare `/signup`, with no campaign. The fix is to remove
584
+ * the parameters that were the reason for stripping, and only those. Each
585
+ * entry below names where that parameter comes from.
586
+ *
587
+ * {@link isSensitiveQueryValue} is the backstop for a parameter nobody
588
+ * listed: a value shaped like an address, a phone number or a token is
589
+ * dropped whatever its name.
590
+ */
591
+ export declare const ANALYTICS_DENIED_URL_PARAMS: ReadonlySet<string>;
592
+ /**
593
+ * Campaign tags, which the phone and token shapes below never apply to. A
594
+ * click id IS an opaque token — that is what it is for — and a Google Ads
595
+ * campaign id is a bare run of digits; the backstop would drop exactly the
596
+ * attribution this URL is kept for. The address test still applies to them.
597
+ *
598
+ * The first three are the first-touch capture's `FIRST_TOUCH_CLICK_IDS`,
599
+ * spelled out rather than imported for the same bundle reason as `_ft` above;
600
+ * `analytics-events.spec.ts` fails if that list gains an id this one lacks.
601
+ */
602
+ export declare const ANALYTICS_AD_CLICK_ID_PARAMS: ReadonlySet<string>;
559
603
  /**
560
604
  * Strip anything identity-bearing from an event payload. Exported so
561
605
  * `analytics-events.spec.ts` can assert the guarantee directly rather than
@@ -68,11 +68,12 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
68
68
  * Every payload passes through {@link sanitizeEventParams} before it reaches a
69
69
  * transport: an exact-key denylist drops the identity-bearing params someone
70
70
  * will eventually add by reflex (`email`, `org_name`, `first_name`, ...), any
71
- * value that looks like an email address drops its key entirely, URLs are
72
- * reduced to origin + pathname so query strings can never smuggle a token or
73
- * an address, and strings are length-capped. The console separately sets a
74
- * `user_id` — that is an opaque Firebase uid and is the one identifier GA is
75
- * allowed to hold.
71
+ * value that looks like an email address drops its key entirely, a URL keeps
72
+ * its query minus the parameters that carry personal data or a credential
73
+ * ({@link ANALYTICS_DENIED_URL_PARAMS}, plus any value shaped like an address,
74
+ * a phone number or a token), and strings are length-capped. The console
75
+ * separately sets a `user_id` — that is an opaque Firebase uid and is the one
76
+ * identifier GA is allowed to hold.
76
77
  *
77
78
  * Sanitizing here rather than at each call site is the point: a new call site
78
79
  * cannot forget.
@@ -193,26 +194,230 @@ let configuredTransport = null;
193
194
  * — the truncation point and the affordance that describes it have to be one
194
195
  * value, or the editor promises a length the delivery quietly shortens.
195
196
  */ export const ANALYTICS_PARAM_MAX_LENGTH = 100;
196
- function scrubValue(value) {
197
- let candidate = value;
198
- if (/^https?:\/\//i.test(candidate)) {
197
+ /**
198
+ * The params GA4 lets run past {@link ANALYTICS_PARAM_MAX_LENGTH}, at GA4's
199
+ * own documented limits ("Analytics collection limits", Google Analytics
200
+ * Help 9267744): `page_location` 1,000 characters, `page_referrer` 420,
201
+ * `page_title` 300.
202
+ *
203
+ * A page URL is the value most likely to be long for a good reason: a
204
+ * landing URL with its `utm_*` tags and a `gclid` routinely runs past 100,
205
+ * and cutting it there dropped exactly the attribution the query is kept
206
+ * for. A URL's length is measured as it is sent, already URL-encoded, which
207
+ * is how GA4 measures it.
208
+ */ export const ANALYTICS_PARAM_MAX_LENGTH_BY_KEY = {
209
+ page_location: 1000,
210
+ page_referrer: 420,
211
+ page_title: 300
212
+ };
213
+ /** The longest value `key` may carry: its GA4 limit, or the general 100. */ function maxLengthFor(key) {
214
+ return Object.prototype.hasOwnProperty.call(ANALYTICS_PARAM_MAX_LENGTH_BY_KEY, key) ? ANALYTICS_PARAM_MAX_LENGTH_BY_KEY[key] : ANALYTICS_PARAM_MAX_LENGTH;
215
+ }
216
+ /**
217
+ * Query parameters a URL value loses on its way into an event, matched
218
+ * case-insensitively. Everything else in the query is kept, in the order the
219
+ * URL spelled it: `utm_*`, `gclid`, `ref`, `plan`, `tab`, filters.
220
+ *
221
+ * ## Why a denylist
222
+ *
223
+ * URLs used to be reduced to origin + pathname, because a few console links
224
+ * put personal data or a credential in the query. That also threw away the
225
+ * campaign tags on the session-starting `page_view`: a visitor who scanned a
226
+ * QR code for `/signup?utm_source=event&utm_medium=qr&utm_campaign=trailer-left`
227
+ * reached GA4 as a bare `/signup`, with no campaign. The fix is to remove
228
+ * the parameters that were the reason for stripping, and only those. Each
229
+ * entry below names where that parameter comes from.
230
+ *
231
+ * {@link isSensitiveQueryValue} is the backstop for a parameter nobody
232
+ * listed: a value shaped like an address, a phone number or a token is
233
+ * dropped whatever its name.
234
+ */ export const ANALYTICS_DENIED_URL_PARAMS = new Set([
235
+ // Every identity key an event param may not carry is refused as a query
236
+ // parameter too: `email`, `name`, `phone`, `address`, `org_name`, ….
237
+ // `/sso?email=` is set by `apps/console/app/auth/native/page.tsx`, and a
238
+ // tenant's `/api/email/confirm?email=` link by `email-unsubscribe-link.ts`.
239
+ ...DENIED_PARAM_KEYS,
240
+ // The address the native app hands `/auth/native` to forward to `/sso`.
241
+ 'login_hint',
242
+ // Stripe Checkout's prefilled address.
243
+ 'customer_email',
244
+ // Firebase email action links: `/verify-email` and `/reset-password` arrive
245
+ // with `?mode=…&oobCode=…&apiKey=…&continueUrl=…`. The code is a one-time
246
+ // credential; `continueUrl` is a whole URL that can carry its own query.
247
+ 'oobcode',
248
+ 'apikey',
249
+ 'continueurl',
250
+ // The cross-domain sign-in hand-off, `/auth/handoff/continue?handoff={rid}`
251
+ // (`apps/console/app/auth/handoff/start/route.ts`).
252
+ 'handoff',
253
+ // The sealed first-touch record a link to another of our hosts carries
254
+ // (`FIRST_TOUCH_HANDOFF_PARAM` in `@aglyn/shared-util-first-touch`, spelled
255
+ // out here because importing that module ships its whole runtime on every
256
+ // published page; `analytics-events.spec.ts` holds the two equal).
257
+ '_ft',
258
+ // Native app sign-in: `/auth/native?challenge=…&state=…`, and the `code`
259
+ // `api/auth/native-handoff/authorize` returns.
260
+ 'challenge',
261
+ 'code_challenge',
262
+ 'state',
263
+ 'code',
264
+ 'nonce',
265
+ // Bearer credentials in a URL: the names the personal-data export strips
266
+ // from a URL (`personal-data-export.ts`), plus the sign-in tokens.
267
+ 'token',
268
+ 'access_token',
269
+ 'id_token',
270
+ 'idtoken',
271
+ 'refresh_token',
272
+ 'customtoken',
273
+ 'auth',
274
+ 'authorization',
275
+ 'api_key',
276
+ 'key',
277
+ 'sig',
278
+ 'signature',
279
+ 'secret',
280
+ 'password',
281
+ 'downloadtoken',
282
+ 'session',
283
+ // Stripe Checkout's return, `?session_id={CHECKOUT_SESSION_ID}`.
284
+ 'session_id',
285
+ // Invite ids. Console invites need no link today (they are accepted on
286
+ // sign-in), so these are listed for the day one carries the id in a URL.
287
+ 'invite',
288
+ 'inviteid',
289
+ 'invite_id'
290
+ ]);
291
+ /**
292
+ * Campaign tags, which the phone and token shapes below never apply to. A
293
+ * click id IS an opaque token — that is what it is for — and a Google Ads
294
+ * campaign id is a bare run of digits; the backstop would drop exactly the
295
+ * attribution this URL is kept for. The address test still applies to them.
296
+ *
297
+ * The first three are the first-touch capture's `FIRST_TOUCH_CLICK_IDS`,
298
+ * spelled out rather than imported for the same bundle reason as `_ft` above;
299
+ * `analytics-events.spec.ts` fails if that list gains an id this one lacks.
300
+ */ export const ANALYTICS_AD_CLICK_ID_PARAMS = new Set([
301
+ 'gclid',
302
+ 'fbclid',
303
+ 'msclkid',
304
+ 'gbraid',
305
+ 'wbraid',
306
+ 'gad_source',
307
+ 'gad_campaignid'
308
+ ]);
309
+ const PHONE_SHAPED = /^\+?[\d\s().-]+$/;
310
+ const JWT_SHAPED = /^[\w-]{8,}\.[\w-]{8,}\.[\w-]+$/;
311
+ const OPAQUE_RUN = /[A-Za-z0-9_-]{32,}/g;
312
+ function looksLikePhone(value) {
313
+ const trimmed = value.trim();
314
+ if (!PHONE_SHAPED.test(trimmed)) return false;
315
+ const digits = trimmed.replace(/\D/g, '').length;
316
+ return digits >= 10 && digits <= 15;
317
+ }
318
+ /**
319
+ * A JWT, or a run of 32+ URL-safe characters that mixes cases and digits or
320
+ * is all hex. A slug is lowercase words, so a long one is not caught.
321
+ */ function looksLikeToken(value) {
322
+ var _value_match;
323
+ if (JWT_SHAPED.test(value)) return true;
324
+ for (const run of (_value_match = value.match(OPAQUE_RUN)) != null ? _value_match : []){
325
+ if (/^[0-9a-f]+$/.test(run)) return true;
326
+ if (/[a-z]/.test(run) && /[A-Z]/.test(run) && /\d/.test(run)) return true;
327
+ }
328
+ return false;
329
+ }
330
+ /** Whether a decoded query value may not reach GA, whatever its name. */ function isSensitiveQueryValue(key, value) {
331
+ if (EMAIL_SHAPED.test(value)) return true;
332
+ if (key.startsWith('utm_') || ANALYTICS_AD_CLICK_ID_PARAMS.has(key)) return false;
333
+ return looksLikePhone(value) || looksLikeToken(value);
334
+ }
335
+ function decodeQueryPart(part) {
336
+ return decodeURIComponent(part.replace(/\+/g, ' '));
337
+ }
338
+ /**
339
+ * The query parameters of `search` that may reach GA, each as the URL spelled
340
+ * it. A value that is itself a URL or a same-site path (`continue=/x?…`) has
341
+ * its own query filtered by the same rules, so a credential cannot ride in
342
+ * one level down.
343
+ */ function keptQueryParts(search, depth) {
344
+ const kept = [];
345
+ for (const part of search.replace(/^\?/, '').split('&')){
346
+ if (!part) continue;
347
+ const cut = part.indexOf('=');
348
+ const rawKey = cut < 0 ? part : part.slice(0, cut);
349
+ const rawValue = cut < 0 ? '' : part.slice(cut + 1);
350
+ let key;
351
+ let value;
199
352
  try {
200
- const url = new URL(candidate);
201
- // Origin + pathname only: a query string is where a session token, a
202
- // signup email or a Stripe id ends up, and none of them belong in GA.
203
- candidate = `${url.origin}${url.pathname}`;
353
+ key = decodeQueryPart(rawKey).toLowerCase();
354
+ value = decodeQueryPart(rawValue);
204
355
  } catch (unused) {
205
- return null;
356
+ continue;
206
357
  }
358
+ if (ANALYTICS_DENIED_URL_PARAMS.has(key)) continue;
359
+ const nested = depth < 3 ? reduceNestedUrl(value, depth + 1) : value;
360
+ if (nested === null) continue;
361
+ if (isSensitiveQueryValue(key, nested)) continue;
362
+ kept.push(nested === value ? part : `${rawKey}=${encodeURIComponent(nested)}`);
207
363
  }
208
- // AFTER the URL reduction, not before. A page URL routinely carries an
364
+ return kept;
365
+ }
366
+ /** A URL or same-site path value with its query filtered; other values as given. */ function reduceNestedUrl(value, depth) {
367
+ const isPath = value.startsWith('/') && !value.startsWith('//');
368
+ if (!isPath && !/^https?:\/\//i.test(value)) return value;
369
+ let url;
370
+ try {
371
+ url = new URL(value, 'https://placeholder.invalid');
372
+ } catch (unused) {
373
+ return null;
374
+ }
375
+ const query = keptQueryParts(url.search, depth).join('&');
376
+ const base = isPath ? url.pathname : `${url.origin}${url.pathname}`;
377
+ return query ? `${base}?${query}` : base;
378
+ }
379
+ /**
380
+ * Reduce an `http(s)` URL for GA: origin + pathname, plus every query
381
+ * parameter that is not denied (see {@link ANALYTICS_DENIED_URL_PARAMS}), in
382
+ * the URL's own order and spelling. The fragment is dropped. Null when the
383
+ * path itself carries an address.
384
+ *
385
+ * The result fits `maxLength`. A parameter that would run past it is left
386
+ * out whole, never cut in half, so a truncated value never reaches a report
387
+ * as if it were a real one; later, shorter parameters can still fit. A path
388
+ * already over the limit is cut to it, as before.
389
+ */ function reduceUrlForAnalytics(url, maxLength = ANALYTICS_PARAM_MAX_LENGTH) {
390
+ const base = `${url.origin}${url.pathname}`;
391
+ // AFTER the query is set aside, not before. A page URL routinely carries an
209
392
  // address in its query (`?email=…` on a prefilled signup link), and testing
210
- // the raw string would throw the whole URL away for PII that the reduction
211
- // was about to remove — losing the legitimate page dimension to protect
212
- // something already protected. Testing the REDUCED value still catches an
213
- // address embedded in the path itself, which the reduction keeps.
214
- if (EMAIL_SHAPED.test(candidate)) return null;
215
- return candidate.slice(0, ANALYTICS_PARAM_MAX_LENGTH);
393
+ // the raw string would throw the whole URL away for PII that the query
394
+ // filter is about to remove — losing the legitimate page dimension to
395
+ // protect something already protected. Testing the path still catches an
396
+ // address embedded in it.
397
+ if (EMAIL_SHAPED.test(base)) return null;
398
+ if (base.length >= maxLength) return base.slice(0, maxLength);
399
+ let reduced = base;
400
+ for (const part of keptQueryParts(url.search, 0)){
401
+ const next = `${reduced}${reduced === base ? '?' : '&'}${part}`;
402
+ if (next.length <= maxLength) reduced = next;
403
+ }
404
+ return reduced;
405
+ }
406
+ function scrubValue(value, maxLength) {
407
+ if (/^https?:\/\//i.test(value)) {
408
+ try {
409
+ // The query keeps everything but the parameters that carry personal
410
+ // data or a credential, so a session-starting `page_view` still names
411
+ // its campaign. Every kept value was tested for an address already, so
412
+ // the whole-string test below is not run on the result: a harmless
413
+ // `@team` beside a `.` elsewhere in the query would read as one.
414
+ return reduceUrlForAnalytics(new URL(value), maxLength);
415
+ } catch (unused) {
416
+ return null;
417
+ }
418
+ }
419
+ if (EMAIL_SHAPED.test(value)) return null;
420
+ return value.slice(0, maxLength);
216
421
  }
217
422
  /**
218
423
  * Strip anything identity-bearing from an event payload. Exported so
@@ -225,7 +430,7 @@ function scrubValue(value) {
225
430
  if (DENIED_PARAM_KEYS.has(key.toLowerCase())) continue;
226
431
  if (value === undefined || value === null) continue;
227
432
  if (typeof value === 'string') {
228
- const scrubbed = scrubValue(value);
433
+ const scrubbed = scrubValue(value, maxLengthFor(key));
229
434
  if (scrubbed === null || scrubbed === '') continue;
230
435
  safe[key] = scrubbed;
231
436
  continue;