@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 +39 -51
- package/agent-meta/manifest.json +2 -2
- package/agent-meta/skills/web-log/SKILL.md +16 -11
- package/build/consented.d.ts +4 -3
- package/build/consented.d.ts.map +1 -1
- package/build/consented.js +4 -3
- package/build/consented.js.map +1 -1
- package/build/index.d.ts +0 -1
- package/build/index.d.ts.map +1 -1
- package/build/index.js +0 -1
- package/build/index.js.map +1 -1
- package/build/types.d.ts +0 -3
- package/build/types.d.ts.map +1 -1
- package/package.json +4 -4
- package/src/consented.ts +4 -3
- package/src/index.ts +0 -2
- package/src/types.ts +0 -4
- package/tests/consented.spec.ts +94 -0
- package/build/gtobserver.d.ts +0 -12
- package/build/gtobserver.d.ts.map +0 -1
- package/build/gtobserver.js +0 -18
- package/build/gtobserver.js.map +0 -1
- package/src/gtobserver.ts +0 -21
- package/tests/gtobserver.spec.ts +0 -65
package/README.md
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
# @owlmeans/web-log
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
is `@owlmeans/consent` and the `@owlmeans/web-consent` UI) and is not a logger:
|
|
10
|
-
are `@owlmeans/log`. The `web-log` skill covers this package; the `logging`
|
|
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
|
|
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** —
|
|
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
|
|
27
|
-
|
|
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
|
|
36
|
+
### 1. Register a sink at startup
|
|
36
37
|
|
|
37
38
|
```typescript
|
|
38
39
|
import { addLogPlugin } from '@owlmeans/log'
|
|
39
|
-
import {
|
|
40
|
+
import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
|
|
40
41
|
|
|
41
|
-
addLogPlugin(
|
|
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:
|
|
53
|
-
// without it: nothing is
|
|
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.
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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 |
|
|
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` | `'
|
|
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
|
|
112
|
-
|
|
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
|
|
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
|
-
-
|
|
121
|
-
|
|
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) —
|
|
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
|
|
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
|
package/agent-meta/manifest.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 3,
|
|
3
3
|
"package": "@owlmeans/web-log",
|
|
4
|
-
"version": "0.2.0
|
|
5
|
-
"generatedAt": "2026-11-
|
|
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
|
|
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
|
|
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 {
|
|
19
|
+
import { consentedAnalyticsPlugin } from '@owlmeans/web-log'
|
|
19
20
|
|
|
20
|
-
addLogPlugin(
|
|
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
|
-
// →
|
|
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
|
|
30
|
-
everything already waiting in
|
|
31
|
-
grant — in a window the visitor never agreed to be measured in. The load of
|
|
32
|
-
separately (`@owlmeans/
|
|
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 |
|
package/build/consented.d.ts
CHANGED
|
@@ -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
|
|
7
|
-
* already waiting in
|
|
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;
|
package/build/consented.d.ts.map
CHANGED
|
@@ -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
|
|
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"}
|
package/build/consented.js
CHANGED
|
@@ -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
|
|
14
|
-
* already waiting in
|
|
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 = {}) => ({
|
package/build/consented.js.map
CHANGED
|
@@ -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
|
|
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
package/build/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
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
package/build/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
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
|
package/build/types.d.ts.map
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
36
|
-
"@owlmeans/log": "^0.2.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
|
|
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
|
|
18
|
-
* already waiting in
|
|
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
package/src/types.ts
CHANGED
|
@@ -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
|
+
})
|
package/build/gtobserver.d.ts
DELETED
|
@@ -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"}
|
package/build/gtobserver.js
DELETED
|
@@ -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
|
package/build/gtobserver.js.map
DELETED
|
@@ -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 })
|
package/tests/gtobserver.spec.ts
DELETED
|
@@ -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
|
-
})
|