@owlmeans/web-log 0.2.0-alpha.0 → 0.2.0

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
@@ -1,19 +1,19 @@
1
1
  # @owlmeans/web-log
2
2
 
3
- Consent-gated analytics plugins for `@owlmeans/log` in the browser. Application code logs a business
4
- event once with `{ analytics: 'event.name' }`; the plugins registered here decide where it goes —
5
- `gtmAnalyticsPlugin` pushes it onto `window.dataLayer` for a tag manager, `consentedAnalyticsPlugin`
6
- hands it to any sender you supply — and both send only while the visitor has granted the analytics
7
- consent category. A web app uses it whenever it counts events in GTM or another analytics system.
8
- It does not load the tag manager script (that is `@owlmeans/web-gtm`), does not record consent (that
9
- is `@owlmeans/consent` and the `@owlmeans/web-consent` UI) and is not a logger: the calls themselves
10
- are `@owlmeans/log`. The `web-log` skill covers this package; the `logging` skill sets the policy for
11
- log lines and analytics events.
3
+ The consent gate for analytics in the browser: `consentedAnalyticsPlugin` turns any sender into a
4
+ `@owlmeans/log` plugin that sends an event only while the visitor has granted a consent category.
5
+ Application code logs a business event once with `{ analytics: 'event.name' }`; the plugins
6
+ registered decide where it goes. A web app uses it for an analytics system of its own (a beacon, a
7
+ first-party endpoint); a tag vendor's package builds its sink on it (connect's `@owlmeans/web-gtm`:
8
+ `gtmAnalyticsPlugin`, the tag-manager queue). It names no analytics vendor, loads no tag, does not
9
+ record consent (that is `@owlmeans/consent` and the `@owlmeans/web-consent` UI) and is not a logger:
10
+ the calls themselves are `@owlmeans/log`. The `web-log` skill covers this package; the `logging`
11
+ skill sets the policy for log lines and analytics events.
12
12
 
13
13
  ## Installation
14
14
 
15
15
  ```bash
16
- bun add @owlmeans/web-log@^0.2.0-alpha.0
16
+ bun add @owlmeans/web-log@^0.2.0
17
17
  ```
18
18
 
19
19
  ## Concepts
@@ -21,10 +21,11 @@ bun add @owlmeans/web-log@^0.2.0-alpha.0
21
21
  - **Analytics as a call option** — `log.info(message, data, { analytics })` from `@owlmeans/log`
22
22
  delivers an `AnalyticsEvent` to every registered plugin's `track`. A string names the event; with
23
23
  `analytics: true` the name is `options.event`, else the message.
24
- - **Consent gate** — a plugin built here checks `consentStore.granted(category)` (default
24
+ - **Consent gate** — the plugin checks `consentStore.granted(category)` (default
25
25
  `CONSENT_ANALYTICS`, `'analytics'`) on every event.
26
- - **Drop, never queue** — an event that arrives without consent is discarded. A tag manager replays
27
- its queue when it loads, so a held event would be sent for a moment the visitor never agreed to.
26
+ - **Drop, never queue** — an event that arrives without consent is discarded. A tag queue replays
27
+ everything waiting in it when its tag loads, so a held event would be sent for a moment the
28
+ visitor never agreed to.
28
29
  - **Payload** — by default `{ event, ...data }`; a non-object `data` becomes `{ value }`. `map`
29
30
  replaces the shape per plugin.
30
31
  - **One plugin per sink** — each analytics system is its own named plugin with its own allow-list.
@@ -32,13 +33,16 @@ bun add @owlmeans/web-log@^0.2.0-alpha.0
32
33
 
33
34
  ## Usage
34
35
 
35
- ### 1. Register the tag-manager sink at startup
36
+ ### 1. Register a sink at startup
36
37
 
37
38
  ```typescript
38
39
  import { addLogPlugin } from '@owlmeans/log'
39
- import { gtmAnalyticsPlugin } from '@owlmeans/web-log'
40
+ import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
40
41
 
41
- addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created', 'sign_in'] }))
42
+ addLogPlugin(consentedAnalyticsPlugin(
43
+ payload => navigator.sendBeacon('/metrics', JSON.stringify(payload)),
44
+ { name: 'beacon', allow: ['project.created', 'sign_in'] },
45
+ ))
42
46
  ```
43
47
 
44
48
  ### 2. Emit an event from application code
@@ -49,8 +53,8 @@ import { logger } from '@owlmeans/log'
49
53
  const log = logger('projects')
50
54
 
51
55
  log.info('Created', { kind: 'web' }, { analytics: 'project.created' })
52
- // with analytics consent: window.dataLayer.push({ event: 'project.created', kind: 'web' })
53
- // without it: nothing is pushed, now or after a later grant
56
+ // with analytics consent: the sink receives { event: 'project.created', kind: 'web' }
57
+ // without it: nothing is sent, now or after a later grant
54
58
 
55
59
  // count it without writing a console line
56
60
  log.info('Signed in', undefined, { analytics: 'sign_in', console: false })
@@ -58,48 +62,33 @@ log.info('Signed in', undefined, { analytics: 'sign_in', console: false })
58
62
 
59
63
  A call without `analytics` never reaches the plugins' `track`, whatever its level.
60
64
 
61
- ### 3. Add a second analytics system
62
-
63
- `consentedAnalyticsPlugin` is the same gate over any sender. Give it a distinct `name` so it does not
64
- replace the GTM plugin.
65
+ ### 3. Reshape, filter, gate on another category
65
66
 
66
67
  ```typescript
68
+ import { CONSENT_MARKETING } from '@owlmeans/consent'
67
69
  import { addLogPlugin } from '@owlmeans/log'
68
70
  import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
69
71
 
70
- addLogPlugin(consentedAnalyticsPlugin(
71
- payload => navigator.sendBeacon('/metrics', JSON.stringify(payload)),
72
- {
73
- name: 'beacon',
74
- allow: ['subscription.started'],
75
- map: event => ({ name: event.event, scope: event.scope, at: event.time }),
76
- }
77
- ))
78
- ```
79
-
80
- ### 4. Gate on a different consent category
81
-
82
- ```typescript
83
- import { CONSENT_MARKETING } from '@owlmeans/consent'
84
- import { gtmAnalyticsPlugin } from '@owlmeans/web-log'
85
-
86
- addLogPlugin(gtmAnalyticsPlugin({ name: 'gtm-ads', category: CONSENT_MARKETING, allow: ['purchase'] }))
72
+ addLogPlugin(consentedAnalyticsPlugin(sendToAds, {
73
+ name: 'ads',
74
+ category: CONSENT_MARKETING,
75
+ allow: ['purchase'],
76
+ map: event => ({ name: event.event, scope: event.scope, at: event.time }),
77
+ }))
87
78
  ```
88
79
 
89
80
  ## API
90
81
 
91
82
  | Symbol | Kind | Purpose |
92
83
  |---|---|---|
93
- | `gtmAnalyticsPlugin(options?)` | function → `LogPlugin` | Consent-gated sink pushing onto `window.dataLayer` (created when missing); name `'gtm'` unless overridden; no-op outside a browser |
94
84
  | `consentedAnalyticsPlugin(send, options?)` | function → `LogPlugin` | Consent-gated sink calling `send(payload)`; name `'web-analytics'` unless overridden |
95
- | `ConsentedAnalyticsOptions` | type | Options of both factories (below) |
96
- | `DataLayerWindow` | type | `{ dataLayer?: unknown[] }` — the window shape the GTM sink writes to |
85
+ | `ConsentedAnalyticsOptions` | type | Its options (below) |
97
86
 
98
87
  ### `ConsentedAnalyticsOptions`
99
88
 
100
89
  | Field | Default | Meaning |
101
90
  |---|---|---|
102
- | `name` | `'gtm'` / `'web-analytics'` | Plugin name; a second plugin of the same name replaces the first |
91
+ | `name` | `'web-analytics'` | Plugin name; a second plugin of the same name replaces the first |
103
92
  | `category` | `CONSENT_ANALYTICS` | Consent category that must be granted at send time |
104
93
  | `allow` | every event | Event names this plugin sends |
105
94
  | `map(event)` | `{ event, ...data }` | Reshape an `AnalyticsEvent`; return `undefined` to drop it |
@@ -108,23 +97,22 @@ The order of checks per event is: allow-list, consent, `map`, send.
108
97
 
109
98
  ## Common pitfalls
110
99
 
111
- - Do not call `window.dataLayer.push` from components — log the event and let the plugin apply the
112
- consent gate.
100
+ - Do not call an analytics API from components — log the event and let a plugin apply the consent
101
+ gate.
113
102
  - Plugins only implement `track`: a log line without the `analytics` option is never sent. The log
114
103
  level does not filter analytics, and `console: false` only silences the console sink.
115
104
  - Events emitted before consent is granted are lost by design; do not add your own buffer in `send`.
116
- - Two `gtmAnalyticsPlugin` calls with the default name leave only the last one registered — pass
117
- `name` for each extra plugin.
105
+ - Two plugins with the default name leave only the last one registered — pass `name` for each.
118
106
  - Never put personal content into analytics `data` — `@owlmeans/log` redacts known secret keys, but
119
107
  user text and e-mail addresses are the caller's responsibility.
120
- - Loading the GTM script is separate: this package only feeds `dataLayer`; `@owlmeans/web-gtm` loads
121
- the tag and signals consent mode.
108
+ - The tag-manager sink that used to live here is connect's `@owlmeans/web-gtm`
109
+ (`gtmAnalyticsPlugin`, same options and behaviour), built on this gate.
122
110
 
123
111
  ## Related packages
124
112
 
125
113
  - [`@owlmeans/log`](../log) — `logger`, `addLogPlugin`, `LogPlugin`, `AnalyticsEvent`
126
114
  - [`@owlmeans/consent`](../consent) — `consentStore` and the consent category constants
127
- - [`@owlmeans/web-gtm`](https://github.com/owlmeans/connect/tree/main/packages/web-gtm) (OwlMeans connect) — loads the tag manager with consent mode
115
+ - [`@owlmeans/web-gtm`](https://github.com/owlmeans/connect/tree/main/packages/web-gtm) (OwlMeans connect) — the tag-manager sink over this gate, and the tag itself
128
116
  - [`@owlmeans/web-consent`](../web-consent) — the consent banner and preferences UI
129
117
  - [`@owlmeans/viable-log`](../viable-log) — the analytics plugin for apps generated by viable
130
118
 
@@ -136,7 +124,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
136
124
  your project's skill store (`.agents/skills/`):
137
125
 
138
126
  ```sh
139
- npx @owlmeans/agent-skills@^0.2.0-alpha.0
127
+ npx @owlmeans/agent-skills@^0.2.0
140
128
  ```
141
129
 
142
130
  The embedded files are version-matched to this package release. Do not edit them
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schemaVersion": 3,
3
3
  "package": "@owlmeans/web-log",
4
- "version": "0.2.0-alpha.0",
5
- "generatedAt": "2026-11-09T19:44:59.513Z",
4
+ "version": "0.2.0",
5
+ "generatedAt": "2026-11-15T13:38:38.707Z",
6
6
  "canonicalRepo": "https://github.com/owlmeans/common",
7
7
  "entries": [
8
8
  {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: web-log
3
- description: How to use @owlmeans/web-log — the consent-gated analytics plugins for @owlmeans/log in a browser. gtmAnalyticsPlugin pushes `log` calls that carry an analytics option onto window.dataLayer for a tag manager, and only while analytics consent is granted (an event without consent is dropped, never queued); consentedAnalyticsPlugin is the same gate over any sender. Auto-invoked when sending analytics or tag-manager events from application code, importing gtmAnalyticsPlugin or consentedAnalyticsPlugin, or wiring a second analytics system next to GTM.
3
+ description: How to use @owlmeans/web-log — the consent gate for analytics plugins of @owlmeans/log in a browser. consentedAnalyticsPlugin wraps any sender so `log` calls that carry an analytics option are sent only while a consent category is granted (an event without consent is dropped, never queued); a tag vendor's sink is built on it in the vendor's package (connect's web-gtm gtmAnalyticsPlugin). Auto-invoked when sending analytics events from application code, importing consentedAnalyticsPlugin, or wiring an analytics system of your own.
4
4
  user-invocable: false
5
5
  ---
6
6
  <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,32 +8,37 @@ user-invocable: false
8
8
  # @owlmeans/web-log
9
9
 
10
10
  **Layer:** Web (depends on `@owlmeans/log` and `@owlmeans/consent`)
11
- **Install:** `"@owlmeans/web-log": "^0.2.0-alpha.0"` in `dependencies`
11
+ **Install:** `"@owlmeans/web-log": "^0.2.0"` in `dependencies`
12
12
 
13
13
  The browser half of "analytics are plugins" — see `/log` for the call parameters. A page logs a
14
- business event once; which systems hear it is the set of plugins registered.
14
+ business event once; which systems hear it is the set of plugins registered. This package names no
15
+ analytics vendor: it is the consent gate every sink is built on.
15
16
 
16
17
  ```ts
17
18
  import { addLogPlugin, logger } from '@owlmeans/log'
18
- import { gtmAnalyticsPlugin } from '@owlmeans/web-log'
19
+ import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
19
20
 
20
- addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created', 'sign_in'] })) // once, at startup
21
+ addLogPlugin(consentedAnalyticsPlugin(payload => sendToMetrics(payload), { name: 'metrics' })) // once, at startup
21
22
 
22
23
  logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
23
- // → window.dataLayer.push({ event: 'project.created', kind: 'web' }) — if analytics consent is granted
24
+ // → sendToMetrics({ event: 'project.created', kind: 'web' }) — if analytics consent is granted
24
25
  ```
25
26
 
27
+ The tag-manager sink (`window.dataLayer`) is connect's `@owlmeans/web-gtm`: `gtmAnalyticsPlugin`, the
28
+ same options over this gate, named `'gtm'`. It moved there from this package on the 0.2 line; import
29
+ it from `@owlmeans/web-gtm` (`/web-gtm`).
30
+
26
31
  ## Consent
27
32
 
28
33
  `consentedAnalyticsPlugin(send, options)` sends only while `consentStore.granted(options.category ?? 'analytics')`
29
- (`@owlmeans/consent`). **An event without consent is dropped, never queued**: a tag manager replays
30
- everything already waiting in its queue when it loads, so a held event would be sent after a later
31
- grant — in a window the visitor never agreed to be measured in. The load of the tag itself is gated
32
- separately (`@owlmeans/web-gtm`'s `'basic'` mode); this gates the events.
34
+ (`@owlmeans/consent`). **An event without consent is dropped, never queued**: a tag queue replays
35
+ everything already waiting in it when its tag loads, so a held event would be sent after a later
36
+ grant — in a window the visitor never agreed to be measured in. The load of a tag itself is gated
37
+ separately (`@owlmeans/consent`'s `consentTrackingHelper.consentGateScript`); this gates the events.
33
38
 
34
39
  | Option | Meaning |
35
40
  |---|---|
36
- | `name` | plugin name (a second plugin of the name replaces the first) |
41
+ | `name` | plugin name (a second plugin of the name replaces the first); default `'web-analytics'` |
37
42
  | `category` | the consent category required; default analytics |
38
43
  | `allow` | event names it sends; absent means all |
39
44
  | `map(event)` | reshape the payload; return `undefined` to drop the event |
@@ -1,10 +1,11 @@
1
1
  import type { LogPlugin } from '@owlmeans/log';
2
2
  import type { ConsentedAnalyticsOptions } from './types.js';
3
3
  /**
4
- * An analytics plugin that sends only while a consent category is granted.
4
+ * An analytics plugin that sends only while a consent category is granted — the gate every
5
+ * analytics sink is built on; `send` is the sink (a tag package's queue, a beacon of your own).
5
6
  *
6
- * An event arriving without consent is DROPPED, never queued: a tag manager replays everything
7
- * already waiting in its queue when it loads, so a held event would be sent after a later grant —
7
+ * An event arriving without consent is DROPPED, never queued: a tag queue replays everything
8
+ * already waiting in it when its tag loads, so a held event would be sent after a later grant —
8
9
  * for a moment the visitor never agreed to be measured in.
9
10
  */
10
11
  export declare const consentedAnalyticsPlugin: (send: (payload: Record<string, unknown>) => void, options?: ConsentedAnalyticsOptions) => LogPlugin;
@@ -1 +1 @@
1
- {"version":3,"file":"consented.d.ts","sourceRoot":"","sources":["../src/consented.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAW3D;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,SAC7B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,YAAW,yBAAyB,KACnF,SAcD,CAAA"}
1
+ {"version":3,"file":"consented.d.ts","sourceRoot":"","sources":["../src/consented.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAW3D;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,SAC7B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,YAAW,yBAAyB,KACnF,SAcD,CAAA"}
@@ -8,10 +8,11 @@ const defaultPayload = (event) => {
8
8
  return { event: event.event, ...flat };
9
9
  };
10
10
  /**
11
- * An analytics plugin that sends only while a consent category is granted.
11
+ * An analytics plugin that sends only while a consent category is granted — the gate every
12
+ * analytics sink is built on; `send` is the sink (a tag package's queue, a beacon of your own).
12
13
  *
13
- * An event arriving without consent is DROPPED, never queued: a tag manager replays everything
14
- * already waiting in its queue when it loads, so a held event would be sent after a later grant —
14
+ * An event arriving without consent is DROPPED, never queued: a tag queue replays everything
15
+ * already waiting in it when its tag loads, so a held event would be sent after a later grant —
15
16
  * for a moment the visitor never agreed to be measured in.
16
17
  */
17
18
  export const consentedAnalyticsPlugin = (send, options = {}) => ({
@@ -1 +1 @@
1
- {"version":3,"file":"consented.js","sourceRoot":"","sources":["../src/consented.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAInE,0EAA0E;AAC1E,MAAM,cAAc,GAAG,CAAC,KAAqB,EAA2B,EAAE;IACxE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACvB,MAAM,IAAI,GAAG,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAC3E,CAAC,CAAC,IAA+B;QACjC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7C,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,IAAI,EAAE,CAAA;AACxC,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,IAAgD,EAAE,OAAO,GAA8B,EAAE,EAC9E,EAAE,CAAC,CAAC;IACf,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,eAAe;IACrC,KAAK,EAAE,KAAK,CAAC,EAAE;QACb,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAClE,OAAM;QACR,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC,EAAE,CAAC;YACjE,OAAM;QACR,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,cAAc,CAAC,CAAC,KAAK,CAAC,CAAA;QACtD,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,CAAA;QACf,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}
1
+ {"version":3,"file":"consented.js","sourceRoot":"","sources":["../src/consented.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAInE,0EAA0E;AAC1E,MAAM,cAAc,GAAG,CAAC,KAAqB,EAA2B,EAAE;IACxE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACvB,MAAM,IAAI,GAAG,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAC3E,CAAC,CAAC,IAA+B;QACjC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7C,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,IAAI,EAAE,CAAA;AACxC,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,IAAgD,EAAE,OAAO,GAA8B,EAAE,EAC9E,EAAE,CAAC,CAAC;IACf,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,eAAe;IACrC,KAAK,EAAE,KAAK,CAAC,EAAE;QACb,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAClE,OAAM;QACR,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC,EAAE,CAAC;YACjE,OAAM;QACR,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,cAAc,CAAC,CAAC,KAAK,CAAC,CAAA;QACtD,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,CAAA;QACf,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}
package/build/index.d.ts CHANGED
@@ -1,4 +1,3 @@
1
1
  export type * from './types.js';
2
2
  export * from './consented.js';
3
- export * from './gtobserver.js';
4
3
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,gBAAgB,CAAA"}
package/build/index.js CHANGED
@@ -1,3 +1,2 @@
1
1
  export * from './consented.js';
2
- export * from './gtobserver.js';
3
2
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAA"}
package/build/types.d.ts CHANGED
@@ -9,7 +9,4 @@ export interface ConsentedAnalyticsOptions {
9
9
  /** Reshape an event; return `undefined` to drop it. */
10
10
  map?: (event: AnalyticsEvent) => Record<string, unknown> | undefined;
11
11
  }
12
- export interface DataLayerWindow {
13
- dataLayer?: unknown[];
14
- }
15
12
  //# sourceMappingURL=types.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,uDAAuD;IACvD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CACrE;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;CACtB"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,uDAAuD;IACvD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CACrE"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@owlmeans/web-log",
3
- "version": "0.2.0-alpha.0",
3
+ "version": "0.2.0",
4
4
  "license": "MIT",
5
5
  "homepage": "https://owlmeans.com/docs/",
6
6
  "repository": {
@@ -32,11 +32,11 @@
32
32
  }
33
33
  },
34
34
  "dependencies": {
35
- "@owlmeans/consent": "^0.2.0-alpha.0",
36
- "@owlmeans/log": "^0.2.0-alpha.0"
35
+ "@owlmeans/consent": "^0.2.0",
36
+ "@owlmeans/log": "^0.2.0"
37
37
  },
38
38
  "devDependencies": {
39
- "@owlmeans/dep-config": "^0.2.0-alpha.0",
39
+ "@owlmeans/dep-config": "^0.2.0",
40
40
  "@types/bun": "^1.4.4",
41
41
  "nodemon": "^3.1.14",
42
42
  "typescript": "^7.0.2"
package/src/consented.ts CHANGED
@@ -12,10 +12,11 @@ const defaultPayload = (event: AnalyticsEvent): Record<string, unknown> => {
12
12
  }
13
13
 
14
14
  /**
15
- * An analytics plugin that sends only while a consent category is granted.
15
+ * An analytics plugin that sends only while a consent category is granted — the gate every
16
+ * analytics sink is built on; `send` is the sink (a tag package's queue, a beacon of your own).
16
17
  *
17
- * An event arriving without consent is DROPPED, never queued: a tag manager replays everything
18
- * already waiting in its queue when it loads, so a held event would be sent after a later grant —
18
+ * An event arriving without consent is DROPPED, never queued: a tag queue replays everything
19
+ * already waiting in it when its tag loads, so a held event would be sent after a later grant —
19
20
  * for a moment the visitor never agreed to be measured in.
20
21
  */
21
22
  export const consentedAnalyticsPlugin = (
package/src/index.ts CHANGED
@@ -1,4 +1,2 @@
1
-
2
1
  export type * from './types.js'
3
2
  export * from './consented.js'
4
- export * from './gtobserver.js'
package/src/types.ts CHANGED
@@ -10,7 +10,3 @@ export interface ConsentedAnalyticsOptions {
10
10
  /** Reshape an event; return `undefined` to drop it. */
11
11
  map?: (event: AnalyticsEvent) => Record<string, unknown> | undefined
12
12
  }
13
-
14
- export interface DataLayerWindow {
15
- dataLayer?: unknown[]
16
- }
@@ -0,0 +1,94 @@
1
+ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
2
+ import { CONSENT_MARKETING, consentStore } from '@owlmeans/consent'
3
+ import { addLogPlugin, logger, resetLog } from '@owlmeans/log'
4
+ import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
5
+
6
+ let granted: string[] = []
7
+ const original = consentStore.granted
8
+
9
+ beforeEach(() => {
10
+ resetLog()
11
+ granted = []
12
+ consentStore.granted = key => granted.includes(key)
13
+ })
14
+
15
+ afterEach(() => {
16
+ consentStore.granted = original
17
+ resetLog()
18
+ })
19
+
20
+ describe('@owlmeans/web-log', () => {
21
+ test('drops an event while analytics consent is missing — it is never queued', () => {
22
+ const sent: Record<string, unknown>[] = []
23
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload)))
24
+ logger('ui').info('x', { a: 1 }, { analytics: 'page_view' })
25
+ expect(sent).toEqual([])
26
+ granted = ['analytics']
27
+ expect(sent).toEqual([])
28
+ })
29
+
30
+ test('sends {event, ...data} once consent is granted', () => {
31
+ granted = ['analytics']
32
+ const sent: Record<string, unknown>[] = []
33
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload)))
34
+ logger('ui').info('x', { plan: 'pro' }, { analytics: 'subscription.started' })
35
+ expect(sent).toEqual([{ event: 'subscription.started', plan: 'pro' }])
36
+ })
37
+
38
+ test('a non-object datum travels as value', () => {
39
+ granted = ['analytics']
40
+ const sent: Record<string, unknown>[] = []
41
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload)))
42
+ logger('ui').info('x', 3, { analytics: 'count' })
43
+ expect(sent).toEqual([{ event: 'count', value: 3 }])
44
+ })
45
+
46
+ test('ignores plain console calls', () => {
47
+ granted = ['analytics']
48
+ const sent: Record<string, unknown>[] = []
49
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload)))
50
+ logger('ui').info('just a line')
51
+ expect(sent).toEqual([])
52
+ })
53
+
54
+ test('the category is configurable', () => {
55
+ granted = ['analytics']
56
+ const sent: Record<string, unknown>[] = []
57
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload), { category: CONSENT_MARKETING }))
58
+ logger('ui').info('x', undefined, { analytics: 'purchase' })
59
+ expect(sent).toEqual([])
60
+ granted = ['analytics', CONSENT_MARKETING]
61
+ logger('ui').info('x', undefined, { analytics: 'purchase' })
62
+ expect(sent).toEqual([{ event: 'purchase' }])
63
+ })
64
+
65
+ test('allow-list and map shape what is sent', () => {
66
+ granted = ['analytics']
67
+ const sent: Record<string, unknown>[] = []
68
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload), {
69
+ allow: ['keep'], map: event => ({ name: event.event, scope: event.scope }),
70
+ }))
71
+ logger('ui').info('a', undefined, { analytics: 'keep' })
72
+ logger('ui').info('b', undefined, { analytics: 'skip' })
73
+ expect(sent).toEqual([{ name: 'keep', scope: 'ui' }])
74
+ })
75
+
76
+ test('a map returning undefined drops the event', () => {
77
+ granted = ['analytics']
78
+ const sent: unknown[] = []
79
+ addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload), { map: () => undefined }))
80
+ logger('ui').info('a', undefined, { analytics: true })
81
+ expect(sent).toEqual([])
82
+ })
83
+
84
+ test('a second plugin of the same name replaces the first', () => {
85
+ granted = ['analytics']
86
+ const first: unknown[] = []
87
+ const second: unknown[] = []
88
+ addLogPlugin(consentedAnalyticsPlugin(payload => first.push(payload), { name: 'sink' }))
89
+ addLogPlugin(consentedAnalyticsPlugin(payload => second.push(payload), { name: 'sink' }))
90
+ logger('ui').info('a', undefined, { analytics: 'e' })
91
+ expect(first).toEqual([])
92
+ expect(second).toEqual([{ event: 'e' }])
93
+ })
94
+ })
@@ -1,12 +0,0 @@
1
- import type { LogPlugin } from '@owlmeans/log';
2
- import type { ConsentedAnalyticsOptions } from './types.js';
3
- /**
4
- * The tag-manager sink: pushes `{ event, ...data }` onto `window.dataLayer`, consent permitting.
5
- *
6
- * ```ts
7
- * addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created'] }))
8
- * logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
9
- * ```
10
- */
11
- export declare const gtmAnalyticsPlugin: (options?: ConsentedAnalyticsOptions) => LogPlugin;
12
- //# sourceMappingURL=gtobserver.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"gtobserver.d.ts","sourceRoot":"","sources":["../src/gtobserver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,KAAK,EAAE,yBAAyB,EAAmB,MAAM,YAAY,CAAA;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,aAAa,yBAAyB,KAAQ,SAQ5C,CAAA"}
@@ -1,18 +0,0 @@
1
- import { consentedAnalyticsPlugin } from './consented.js';
2
- /**
3
- * The tag-manager sink: pushes `{ event, ...data }` onto `window.dataLayer`, consent permitting.
4
- *
5
- * ```ts
6
- * addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created'] }))
7
- * logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
8
- * ```
9
- */
10
- export const gtmAnalyticsPlugin = (options = {}) => consentedAnalyticsPlugin(payload => {
11
- if (typeof window === 'undefined') {
12
- return;
13
- }
14
- const win = window;
15
- win.dataLayer = win.dataLayer ?? [];
16
- win.dataLayer.push(payload);
17
- }, { name: 'gtm', ...options });
18
- //# sourceMappingURL=gtobserver.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"gtobserver.js","sourceRoot":"","sources":["../src/gtobserver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAGzD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAO,GAA8B,EAAE,EAAa,EAAE,CACvF,wBAAwB,CAAC,OAAO,CAAC,EAAE;IACjC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,MAAoC,CAAA;IAChD,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,EAAE,CAAA;IACnC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAC7B,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA"}
package/src/gtobserver.ts DELETED
@@ -1,21 +0,0 @@
1
- import type { LogPlugin } from '@owlmeans/log'
2
- import { consentedAnalyticsPlugin } from './consented.js'
3
- import type { ConsentedAnalyticsOptions, DataLayerWindow } from './types.js'
4
-
5
- /**
6
- * The tag-manager sink: pushes `{ event, ...data }` onto `window.dataLayer`, consent permitting.
7
- *
8
- * ```ts
9
- * addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created'] }))
10
- * logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
11
- * ```
12
- */
13
- export const gtmAnalyticsPlugin = (options: ConsentedAnalyticsOptions = {}): LogPlugin =>
14
- consentedAnalyticsPlugin(payload => {
15
- if (typeof window === 'undefined') {
16
- return
17
- }
18
- const win = window as unknown as DataLayerWindow
19
- win.dataLayer = win.dataLayer ?? []
20
- win.dataLayer.push(payload)
21
- }, { name: 'gtm', ...options })
@@ -1,65 +0,0 @@
1
- import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
2
- import { consentStore } from '@owlmeans/consent'
3
- import { addLogPlugin, logger, resetLog } from '@owlmeans/log'
4
- import { consentedAnalyticsPlugin, gtmAnalyticsPlugin } from '@owlmeans/web-log'
5
-
6
- const win = globalThis as unknown as { window?: { dataLayer?: unknown[] } }
7
-
8
- let granted = false
9
- const original = consentStore.granted
10
-
11
- beforeEach(() => {
12
- resetLog()
13
- win.window = {}
14
- granted = false
15
- consentStore.granted = () => granted
16
- })
17
-
18
- afterEach(() => {
19
- consentStore.granted = original
20
- delete win.window
21
- resetLog()
22
- })
23
-
24
- describe('@owlmeans/web-log', () => {
25
- test('drops an event while analytics consent is missing — it is never queued', () => {
26
- addLogPlugin(gtmAnalyticsPlugin())
27
- logger('ui').info('x', { a: 1 }, { analytics: 'page_view' })
28
- expect(win.window?.dataLayer).toBeUndefined()
29
- granted = true
30
- expect(win.window?.dataLayer).toBeUndefined()
31
- })
32
-
33
- test('pushes {event, ...data} to the dataLayer once consent is granted', () => {
34
- granted = true
35
- addLogPlugin(gtmAnalyticsPlugin())
36
- logger('ui').info('x', { plan: 'pro' }, { analytics: 'subscription.started' })
37
- expect(win.window?.dataLayer).toEqual([{ event: 'subscription.started', plan: 'pro' }])
38
- })
39
-
40
- test('ignores plain console calls', () => {
41
- granted = true
42
- addLogPlugin(gtmAnalyticsPlugin())
43
- logger('ui').info('just a line')
44
- expect(win.window?.dataLayer).toBeUndefined()
45
- })
46
-
47
- test('allow-list and map shape what is sent', () => {
48
- granted = true
49
- const sent: Record<string, unknown>[] = []
50
- addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload), {
51
- allow: ['keep'], map: event => ({ name: event.event, scope: event.scope }),
52
- }))
53
- logger('ui').info('a', undefined, { analytics: 'keep' })
54
- logger('ui').info('b', undefined, { analytics: 'skip' })
55
- expect(sent).toEqual([{ name: 'keep', scope: 'ui' }])
56
- })
57
-
58
- test('a map returning undefined drops the event', () => {
59
- granted = true
60
- const sent: unknown[] = []
61
- addLogPlugin(consentedAnalyticsPlugin(payload => sent.push(payload), { map: () => undefined }))
62
- logger('ui').info('a', undefined, { analytics: true })
63
- expect(sent).toEqual([])
64
- })
65
- })