@owlmeans/web-log 0.1.18-rc.2 → 0.1.18-rc.4

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,3 +1,133 @@
1
+ # @owlmeans/web-log
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.
12
+
13
+ ## Installation
14
+
15
+ ```bash
16
+ bun add @owlmeans/web-log@^0.1.18-rc.4
17
+ ```
18
+
19
+ ## Concepts
20
+
21
+ - **Analytics as a call option** — `log.info(message, data, { analytics })` from `@owlmeans/log`
22
+ delivers an `AnalyticsEvent` to every registered plugin's `track`. A string names the event; with
23
+ `analytics: true` the name is `options.event`, else the message.
24
+ - **Consent gate** — a plugin built here checks `consentStore.granted(category)` (default
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.
28
+ - **Payload** — by default `{ event, ...data }`; a non-object `data` becomes `{ value }`. `map`
29
+ replaces the shape per plugin.
30
+ - **One plugin per sink** — each analytics system is its own named plugin with its own allow-list.
31
+ Registering a plugin with an existing name replaces the earlier one.
32
+
33
+ ## Usage
34
+
35
+ ### 1. Register the tag-manager sink at startup
36
+
37
+ ```typescript
38
+ import { addLogPlugin } from '@owlmeans/log'
39
+ import { gtmAnalyticsPlugin } from '@owlmeans/web-log'
40
+
41
+ addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created', 'sign_in'] }))
42
+ ```
43
+
44
+ ### 2. Emit an event from application code
45
+
46
+ ```typescript
47
+ import { logger } from '@owlmeans/log'
48
+
49
+ const log = logger('projects')
50
+
51
+ 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
54
+
55
+ // count it without writing a console line
56
+ log.info('Signed in', undefined, { analytics: 'sign_in', console: false })
57
+ ```
58
+
59
+ A call without `analytics` never reaches the plugins' `track`, whatever its level.
60
+
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
+
66
+ ```typescript
67
+ import { addLogPlugin } from '@owlmeans/log'
68
+ import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
69
+
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'] }))
87
+ ```
88
+
89
+ ## API
90
+
91
+ | Symbol | Kind | Purpose |
92
+ |---|---|---|
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
+ | `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 |
97
+
98
+ ### `ConsentedAnalyticsOptions`
99
+
100
+ | Field | Default | Meaning |
101
+ |---|---|---|
102
+ | `name` | `'gtm'` / `'web-analytics'` | Plugin name; a second plugin of the same name replaces the first |
103
+ | `category` | `CONSENT_ANALYTICS` | Consent category that must be granted at send time |
104
+ | `allow` | every event | Event names this plugin sends |
105
+ | `map(event)` | `{ event, ...data }` | Reshape an `AnalyticsEvent`; return `undefined` to drop it |
106
+
107
+ The order of checks per event is: allow-list, consent, `map`, send.
108
+
109
+ ## Common pitfalls
110
+
111
+ - Do not call `window.dataLayer.push` from components — log the event and let the plugin apply the
112
+ consent gate.
113
+ - Plugins only implement `track`: a log line without the `analytics` option is never sent. The log
114
+ level does not filter analytics, and `console: false` only silences the console sink.
115
+ - 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.
118
+ - Never put personal content into analytics `data` — `@owlmeans/log` redacts known secret keys, but
119
+ 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.
122
+
123
+ ## Related packages
124
+
125
+ - [`@owlmeans/log`](../log) — `logger`, `addLogPlugin`, `LogPlugin`, `AnalyticsEvent`
126
+ - [`@owlmeans/consent`](../consent) — `consentStore` and the consent category constants
127
+ - [`@owlmeans/web-gtm`](../web-gtm) — loads the tag manager with consent mode
128
+ - [`@owlmeans/web-consent`](../web-consent) — the consent banner and preferences UI
129
+ - [`@owlmeans/viable-log`](../viable-log) — the analytics plugin for apps generated by viable
130
+
1
131
  <!-- owlmeans:agent-guidance:start -->
2
132
  ## Agent guidance
3
133
 
@@ -6,7 +136,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
6
136
  your project's skill store (`.agents/skills/`):
7
137
 
8
138
  ```sh
9
- npx @owlmeans/agent-skills@^0.1.18-rc.49
139
+ npx @owlmeans/agent-skills@^0.1.18-rc.57
10
140
  ```
11
141
 
12
142
  The embedded files are version-matched to this package release. Do not edit them
@@ -1,8 +1,8 @@
1
1
  {
2
- "schemaVersion": 2,
2
+ "schemaVersion": 3,
3
3
  "package": "@owlmeans/web-log",
4
- "version": "0.1.18-rc.2",
5
- "generatedAt": "2026-10-05T21:03:06.397Z",
4
+ "version": "0.1.18-rc.4",
5
+ "generatedAt": "2026-10-20T23:19:58.628Z",
6
6
  "canonicalRepo": "https://github.com/owlmeans/common",
7
7
  "entries": [
8
8
  {
@@ -8,7 +8,7 @@ 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.1.18-rc.2"` in `dependencies`
11
+ **Install:** `"@owlmeans/web-log": "^0.1.18-rc.4"` in `dependencies`
12
12
 
13
13
  The browser half of "analytics are plugins" — see `/log` for the call parameters. A page logs a
14
14
  business event once; which systems hear it is the set of plugins registered.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@owlmeans/web-log",
3
- "version": "0.1.18-rc.2",
3
+ "version": "0.1.18-rc.4",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -22,8 +22,8 @@
22
22
  }
23
23
  },
24
24
  "dependencies": {
25
- "@owlmeans/consent": "^0.1.18-rc.11",
26
- "@owlmeans/log": "^0.1.18-rc.2"
25
+ "@owlmeans/consent": "^0.1.18-rc.12",
26
+ "@owlmeans/log": "^0.1.18-rc.4"
27
27
  },
28
28
  "devDependencies": {
29
29
  "@owlmeans/dep-config": "workspace:*",