@owlmeans/web-log 0.1.18-rc.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 ADDED
@@ -0,0 +1,15 @@
1
+ <!-- owlmeans:agent-guidance:start -->
2
+ ## Agent guidance
3
+
4
+ This package ships embedded agent skills under `agent-meta/`. After installing your
5
+ `@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
6
+ your project's skill store (`.agents/skills/`):
7
+
8
+ ```sh
9
+ npx @owlmeans/agent-skills@^0.1.18-rc.47
10
+ ```
11
+
12
+ The embedded files are version-matched to this package release. Do not edit them
13
+ directly — they are regenerated on each publish. To contribute guidance edits,
14
+ open a PR against the source monorepo.
15
+ <!-- owlmeans:agent-guidance:end -->
@@ -0,0 +1,16 @@
1
+ {
2
+ "schemaVersion": 2,
3
+ "package": "@owlmeans/web-log",
4
+ "version": "0.1.18-rc.0",
5
+ "generatedAt": "2026-10-03T20:03:44.511Z",
6
+ "canonicalRepo": "https://github.com/owlmeans/common",
7
+ "entries": [
8
+ {
9
+ "kind": "skill",
10
+ "name": "web-log",
11
+ "category": "package-specific",
12
+ "file": "skills/web-log/SKILL.md",
13
+ "canonicalPath": ".agents/skills/web-log/SKILL.md"
14
+ }
15
+ ]
16
+ }
@@ -0,0 +1,42 @@
1
+ ---
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.
4
+ user-invocable: false
5
+ ---
6
+ <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
7
+
8
+ # @owlmeans/web-log
9
+
10
+ **Layer:** Web (depends on `@owlmeans/log` and `@owlmeans/consent`)
11
+ **Install:** `"@owlmeans/web-log": "^0.1.18-rc.0"` in `dependencies`
12
+
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.
15
+
16
+ ```ts
17
+ import { addLogPlugin, logger } from '@owlmeans/log'
18
+ import { gtmAnalyticsPlugin } from '@owlmeans/web-log'
19
+
20
+ addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created', 'sign_in'] })) // once, at startup
21
+
22
+ logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
23
+ // → window.dataLayer.push({ event: 'project.created', kind: 'web' }) — if analytics consent is granted
24
+ ```
25
+
26
+ ## Consent
27
+
28
+ `consentedAnalyticsPlugin(send, options)` sends only while `isConsented(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.
33
+
34
+ | Option | Meaning |
35
+ |---|---|
36
+ | `name` | plugin name (a second plugin of the name replaces the first) |
37
+ | `category` | the consent category required; default analytics |
38
+ | `allow` | event names it sends; absent means all |
39
+ | `map(event)` | reshape the payload; return `undefined` to drop the event |
40
+
41
+ The default payload is `{ event, ...data }` (a non-object `data` becomes `value`). A second analytics
42
+ system is a second `consentedAnalyticsPlugin(send, { name })` — each plugin filters for itself.
@@ -0,0 +1,32 @@
1
+ import type { AnalyticsEvent, LogPlugin } from '@owlmeans/log';
2
+ export interface ConsentedAnalyticsOptions {
3
+ /** Plugin name; a second plugin of the same name replaces the first. */
4
+ name?: string;
5
+ /** The consent category that must be granted. Default: analytics. */
6
+ category?: string;
7
+ /** Event names this plugin sends. Absent means every event. */
8
+ allow?: string[];
9
+ /** Reshape an event; return `undefined` to drop it. */
10
+ map?: (event: AnalyticsEvent) => Record<string, unknown> | undefined;
11
+ }
12
+ /**
13
+ * An analytics plugin that sends only while a consent category is granted.
14
+ *
15
+ * An event arriving without consent is DROPPED, never queued: a tag manager replays everything
16
+ * already waiting in its queue when it loads, so a held event would be sent after a later grant —
17
+ * for a moment the visitor never agreed to be measured in.
18
+ */
19
+ export declare const consentedAnalyticsPlugin: (send: (payload: Record<string, unknown>) => void, options?: ConsentedAnalyticsOptions) => LogPlugin;
20
+ export interface DataLayerWindow {
21
+ dataLayer?: unknown[];
22
+ }
23
+ /**
24
+ * The tag-manager sink: pushes `{ event, ...data }` onto `window.dataLayer`, consent permitting.
25
+ *
26
+ * ```ts
27
+ * addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created'] }))
28
+ * logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
29
+ * ```
30
+ */
31
+ export declare const gtmAnalyticsPlugin: (options?: ConsentedAnalyticsOptions) => LogPlugin;
32
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9D,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;AAWD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,SAC7B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,YAAW,yBAAyB,KACnF,SAcD,CAAA;AAEF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,aAAa,yBAAyB,KAAQ,SAQ5C,CAAA"}
package/build/index.js ADDED
@@ -0,0 +1,48 @@
1
+ import { CONSENT_ANALYTICS, isConsented } from '@owlmeans/consent';
2
+ /** What the plugin sends by default: the event name and its flat data. */
3
+ const defaultPayload = (event) => {
4
+ const data = event.data;
5
+ const flat = data != null && typeof data === 'object' && !Array.isArray(data)
6
+ ? data
7
+ : data !== undefined ? { value: data } : {};
8
+ return { event: event.event, ...flat };
9
+ };
10
+ /**
11
+ * An analytics plugin that sends only while a consent category is granted.
12
+ *
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 —
15
+ * for a moment the visitor never agreed to be measured in.
16
+ */
17
+ export const consentedAnalyticsPlugin = (send, options = {}) => ({
18
+ name: options.name ?? 'web-analytics',
19
+ track: event => {
20
+ if (options.allow != null && !options.allow.includes(event.event)) {
21
+ return;
22
+ }
23
+ if (!isConsented(options.category ?? CONSENT_ANALYTICS)) {
24
+ return;
25
+ }
26
+ const payload = (options.map ?? defaultPayload)(event);
27
+ if (payload != null) {
28
+ send(payload);
29
+ }
30
+ },
31
+ });
32
+ /**
33
+ * The tag-manager sink: pushes `{ event, ...data }` onto `window.dataLayer`, consent permitting.
34
+ *
35
+ * ```ts
36
+ * addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created'] }))
37
+ * logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
38
+ * ```
39
+ */
40
+ export const gtmAnalyticsPlugin = (options = {}) => consentedAnalyticsPlugin(payload => {
41
+ if (typeof window === 'undefined') {
42
+ return;
43
+ }
44
+ const win = window;
45
+ win.dataLayer = win.dataLayer ?? [];
46
+ win.dataLayer.push(payload);
47
+ }, { name: 'gtm', ...options });
48
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAclE,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,WAAW,CAAC,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC,EAAE,CAAC;YACxD,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;AAMF;;;;;;;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/package.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "@owlmeans/web-log",
3
+ "version": "0.1.18-rc.0",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "scripts": {
7
+ "build": "tsc -b",
8
+ "dev": "sleep 2 && nodemon -e ts,json --watch src --exec \"tsc -p ./tsconfig.json\"",
9
+ "watch": "tsc -b -w --preserveWatchOutput --pretty",
10
+ "test": "bun test ./tests"
11
+ },
12
+ "main": "build/index.js",
13
+ "module": "build/index.js",
14
+ "types": "build/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "import": "./build/index.js",
18
+ "require": "./build/index.js",
19
+ "default": "./build/index.js",
20
+ "module": "./build/index.js",
21
+ "types": "./build/index.d.ts"
22
+ }
23
+ },
24
+ "dependencies": {
25
+ "@owlmeans/consent": "^0.1.18-rc.9",
26
+ "@owlmeans/log": "^0.1.18-rc.0"
27
+ },
28
+ "devDependencies": {
29
+ "@owlmeans/dep-config": "workspace:*",
30
+ "@types/bun": "^1.4.0",
31
+ "nodemon": "^3.1.14",
32
+ "typescript": "^7.0.2"
33
+ },
34
+ "publishConfig": {
35
+ "access": "public"
36
+ }
37
+ }
package/src/index.ts ADDED
@@ -0,0 +1,69 @@
1
+ import { CONSENT_ANALYTICS, isConsented } from '@owlmeans/consent'
2
+ import type { AnalyticsEvent, LogPlugin } from '@owlmeans/log'
3
+
4
+ export interface ConsentedAnalyticsOptions {
5
+ /** Plugin name; a second plugin of the same name replaces the first. */
6
+ name?: string
7
+ /** The consent category that must be granted. Default: analytics. */
8
+ category?: string
9
+ /** Event names this plugin sends. Absent means every event. */
10
+ allow?: string[]
11
+ /** Reshape an event; return `undefined` to drop it. */
12
+ map?: (event: AnalyticsEvent) => Record<string, unknown> | undefined
13
+ }
14
+
15
+ /** What the plugin sends by default: the event name and its flat data. */
16
+ const defaultPayload = (event: AnalyticsEvent): Record<string, unknown> => {
17
+ const data = event.data
18
+ const flat = data != null && typeof data === 'object' && !Array.isArray(data)
19
+ ? data as Record<string, unknown>
20
+ : data !== undefined ? { value: data } : {}
21
+ return { event: event.event, ...flat }
22
+ }
23
+
24
+ /**
25
+ * An analytics plugin that sends only while a consent category is granted.
26
+ *
27
+ * An event arriving without consent is DROPPED, never queued: a tag manager replays everything
28
+ * already waiting in its queue when it loads, so a held event would be sent after a later grant —
29
+ * for a moment the visitor never agreed to be measured in.
30
+ */
31
+ export const consentedAnalyticsPlugin = (
32
+ send: (payload: Record<string, unknown>) => void, options: ConsentedAnalyticsOptions = {}
33
+ ): LogPlugin => ({
34
+ name: options.name ?? 'web-analytics',
35
+ track: event => {
36
+ if (options.allow != null && !options.allow.includes(event.event)) {
37
+ return
38
+ }
39
+ if (!isConsented(options.category ?? CONSENT_ANALYTICS)) {
40
+ return
41
+ }
42
+ const payload = (options.map ?? defaultPayload)(event)
43
+ if (payload != null) {
44
+ send(payload)
45
+ }
46
+ },
47
+ })
48
+
49
+ export interface DataLayerWindow {
50
+ dataLayer?: unknown[]
51
+ }
52
+
53
+ /**
54
+ * The tag-manager sink: pushes `{ event, ...data }` onto `window.dataLayer`, consent permitting.
55
+ *
56
+ * ```ts
57
+ * addLogPlugin(gtmAnalyticsPlugin({ allow: ['project.created'] }))
58
+ * logger('projects').info('Created', { kind: 'web' }, { analytics: 'project.created' })
59
+ * ```
60
+ */
61
+ export const gtmAnalyticsPlugin = (options: ConsentedAnalyticsOptions = {}): LogPlugin =>
62
+ consentedAnalyticsPlugin(payload => {
63
+ if (typeof window === 'undefined') {
64
+ return
65
+ }
66
+ const win = window as unknown as DataLayerWindow
67
+ win.dataLayer = win.dataLayer ?? []
68
+ win.dataLayer.push(payload)
69
+ }, { name: 'gtm', ...options })
@@ -0,0 +1,65 @@
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
+ })
package/tsconfig.json ADDED
@@ -0,0 +1,11 @@
1
+ {
2
+ "extends": [
3
+ "@owlmeans/dep-config/tsconfig.base.json"
4
+ ],
5
+ "compilerOptions": {
6
+ "lib": ["ESNext", "DOM"],
7
+ "rootDir": "./src/",
8
+ "outDir": "./build/"
9
+ },
10
+ "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
11
+ }