@astroscope/relay 0.0.0-stage → 1.0.1

package/dist/shared-D281USsp.js

@@ -0,0 +1,106 @@
+// src/shared.ts
+/**
+* The request header the browser's consent travels in: the names of the consented destinations,
+* comma-separated. The bus writes it onto every same-origin fetch, the middleware reads it.
+*/
+const RELAY_CONSENT_HEADER = "x-relay-consent";
+/** the attribute of an element whose click tracks the event serialized into it */
+const RELAY_TRACK_ATTRIBUTE = "data-track";
+const MAX_CONSENT_NAMES = 32;
+const DESTINATION_NAME = /^[\w-]{1,64}$/;
+/** the header value: the names of the consented destinations, empty when none */
+function serializeConsent(consent) {
+	return Object.keys(consent).filter((name) => consent[name] === true && DESTINATION_NAME.test(name)).join(",");
+}
+/** the record from an untrusted header value: unknown names are dropped, a missing header is nothing consented */
+function parseConsent(raw) {
+	if (!raw) return {};
+	const names = raw.split(",").map((name) => name.trim()).filter((name) => DESTINATION_NAME.test(name)).slice(0, MAX_CONSENT_NAMES);
+	return Object.fromEntries(names.map((name) => [name, true]));
+}
+/**
+* One of the site's events: a function that turns the site's own objects into the payloads of the
+* destinations the event is meant for, under the key that identifies it in a `data-track`
+* attribute and in logs. One export per event, so an island bundles only the events
+* it tracks and an event only an action imports never reaches the browser; the key is the export's
+* name.
+*/
+function defineEvent(key, create) {
+	const build = (...args) => {
+		const { id, ...event } = create(...args);
+		return id === void 0 ? {
+			key,
+			event
+		} : {
+			key,
+			id,
+			event
+		};
+	};
+	return Object.assign(build, { key });
+}
+function isDomainEvent(input) {
+	const candidate = input;
+	return typeof candidate.key === "string" && typeof candidate.event === "object" && candidate.event !== null;
+}
+/** the payloads and, for a defined one, its key and own id */
+function toTracked(input) {
+	return isDomainEvent(input) ? {
+		event: input.event,
+		key: input.key,
+		id: input.id
+	} : {
+		event: input,
+		key: void 0,
+		id: void 0
+	};
+}
+/** a plain object with the right shape, from untrusted json (an attribute, the queue, storage) */
+function isTrackInput(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const candidate = value;
+	if (candidate.key === void 0 && candidate.event === void 0) return true;
+	return isDomainEvent(candidate);
+}
+/** the value of the `data-track` attribute of an element whose click tracks the event */
+function trackAttribute(input) {
+	return JSON.stringify(input);
+}
+/** the payload of a destination in an event, `undefined` when the event is not meant for it */
+function payloadOf(event, name) {
+	return event[name];
+}
+/** whether this runs in a browser: a runtime check, so the built package works outside vite too */
+function isBrowser() {
+	return typeof window !== "undefined" && typeof document !== "undefined";
+}
+/** a fresh event id: a uuid; `randomUUID` needs a secure context, random bytes do not */
+function createEventId() {
+	if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
+	bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+	bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+const MAX_ID_LENGTH = 64;
+const EVENT_ID = /^[\w.:-]+$/;
+/** a usable event id from an untrusted value: non-empty, printable, bounded */
+function isEventId(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= MAX_ID_LENGTH && EVENT_ID.test(value);
+}
+/** the id an event fires under: its own when it carries a usable one (an order number), else a fresh one */
+function eventIdOf(own) {
+	return isEventId(own) ? own : createEventId();
+}
+/**
+* Why an event does not fire under the id it came with, for the log of whoever tracked it: the
+* other side reports the conversion under the own id, so a replaced one counts twice.
+*/
+function unusableEventId(own, id) {
+	if (own === void 0 || isEventId(own)) return void 0;
+	return `event id ${JSON.stringify(own)} is not usable (1 to ${MAX_ID_LENGTH} of A-Z, a-z, 0-9, _ . : -), the event fires under ${id} instead`;
+}
+export { isBrowser as a, payloadOf as c, trackAttribute as d, unusableEventId as f, eventIdOf as i, serializeConsent as l, RELAY_TRACK_ATTRIBUTE as n, isTrackInput as o, defineEvent as r, parseConsent as s, RELAY_CONSENT_HEADER as t, toTracked as u };
+
+//# sourceMappingURL=shared-D281USsp.js.map

package/dist/shared-D281USsp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-D281USsp.js","names":[],"sources":["../src/shared.ts"],"sourcesContent":["// imported by the server, the client and the destination entries — no node or astro runtime imports here\n\n/**\n * The request header the browser's consent travels in: the names of the consented destinations,\n * comma-separated. The bus writes it onto every same-origin fetch, the middleware reads it.\n */\nexport const RELAY_CONSENT_HEADER = 'x-relay-consent';\n\n/** the attribute of an element whose click tracks the event serialized into it */\nexport const RELAY_TRACK_ATTRIBUTE = 'data-track';\n\n/** what the visitor allowed, by destination name */\nexport type ConsentRecord = Readonly<Record<string, boolean>>;\n\nconst MAX_CONSENT_NAMES = 32;\nconst DESTINATION_NAME = /^[\\w-]{1,64}$/;\n\n/** the header value: the names of the consented destinations, empty when none */\nexport function serializeConsent(consent: ConsentRecord): string {\n  return Object.keys(consent)\n    .filter((name) => consent[name] === true && DESTINATION_NAME.test(name))\n    .join(',');\n}\n\n/** the record from an untrusted header value: unknown names are dropped, a missing header is nothing consented */\nexport function parseConsent(raw: string | null | undefined): ConsentRecord {\n  if (!raw) return {};\n\n  const names = raw\n    .split(',')\n    .map((name) => name.trim())\n    .filter((name) => DESTINATION_NAME.test(name))\n    .slice(0, MAX_CONSENT_NAMES);\n\n  return Object.fromEntries(names.map((name) => [name, true]));\n}\n\n/**\n * The answer for one destination: `undefined` as long as the cmp has not read the stored choice yet\n * — not \"no\", but \"not known\", so events wait in memory instead of being dropped.\n */\nexport type ConsentAnswer = boolean | undefined;\n\n/**\n * Where the bus asks whether the visitor allowed a destination: a cmp adapter (`ccm19()`), or three\n * members of your own. It covers exactly the registered names — `names` and `of` make the type\n * invariant in them — so a destination without an answer is a type error.\n */\nexport type ConsentSource<N extends string = string> = {\n  /** the registered destination names */\n  names: readonly N[];\n  /** whether the visitor allowed the destination */\n  of: (name: N) => ConsentAnswer;\n  /** destinations needing no consent: taken before the cmp has answered, not in the record */\n  free?: readonly N[] | undefined;\n  /** called once with the re-check: hook it to the cmp's change event, so a choice on this page delivers at once */\n  watch?: ((notify: () => void) => void) | undefined;\n};\n\n/**\n * The destinations an event can carry a payload for, by name: the package's destination entries and a\n * site's own add theirs through module augmentation of `@astroscope/relay`, so every event\n * definition is checked against the payload the destination takes. `id`, `key` and `event` are\n * reserved names.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- filled by augmentation\nexport interface RelayDestinations {}\n\nexport type DestinationName = keyof RelayDestinations & string;\n\n/** the parameters of an event as a destination's builder takes them */\nexport type RelayParams = Record<string, unknown>;\n\n/** an event on the bus: the payload for each destination it is meant for, built by the destination's own builders */\nexport type RelayEvent = { [N in DestinationName]?: RelayDestinations[N] | undefined };\n\n/**\n * An event a site defined: the definition's key, optionally the id it fires under (an order\n * number, so every destination counts a conversion once, on both sides), and the payloads it built.\n */\nexport type DomainEvent<E extends RelayEvent = RelayEvent> = {\n  key: string;\n  id?: string | undefined;\n  event: E;\n};\n\n/** what a definition returns: the payloads, and the id where the site's data has one */\nexport type DefinedPayloads = RelayEvent & { id?: string | undefined };\n\n/** what `track()`, `<Track>` and `data-track` take: a defined event or a plain one */\nexport type TrackInput = RelayEvent | DomainEvent;\n\n/** a defined event: builds the event from the site's own arguments and carries its key */\nexport type EventDefinition<\n  Args extends unknown[] = unknown[],\n  E extends RelayEvent = RelayEvent,\n  K extends string = string,\n> = ((...args: Args) => DomainEvent<E>) & {\n  readonly key: K;\n};\n\n/**\n * One of the site's events: a function that turns the site's own objects into the payloads of the\n * destinations the event is meant for, under the key that identifies it in a `data-track`\n * attribute and in logs. One export per event, so an island bundles only the events\n * it tracks and an event only an action imports never reaches the browser; the key is the export's\n * name.\n */\nexport function defineEvent<const K extends string, Args extends unknown[], E extends DefinedPayloads>(\n  key: K,\n  create: (...args: Args) => E,\n): EventDefinition<Args, Omit<E, 'id'>, K> {\n  const build = (...args: Args): DomainEvent<Omit<E, 'id'>> => {\n    const { id, ...event } = create(...args);\n\n    return id === undefined ? { key, event } : { key, id, event };\n  };\n\n  return Object.assign(build, { key });\n}\n\nexport function isDomainEvent(input: TrackInput): input is DomainEvent {\n  const candidate = input as Partial<DomainEvent>;\n\n  return typeof candidate.key === 'string' && typeof candidate.event === 'object' && candidate.event !== null;\n}\n\n/** the payloads and, for a defined one, its key and own id */\nexport function toTracked(input: TrackInput): { event: RelayEvent; key: string | undefined; id: string | undefined } {\n  return isDomainEvent(input)\n    ? { event: input.event, key: input.key, id: input.id }\n    : { event: input, key: undefined, id: undefined };\n}\n\n/** a plain object with the right shape, from untrusted json (an attribute, the queue, storage) */\nexport function isTrackInput(value: unknown): value is TrackInput {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n\n  const candidate = value as Partial<DomainEvent>;\n\n  if (candidate.key === undefined && candidate.event === undefined) return true;\n\n  return isDomainEvent(candidate as TrackInput);\n}\n\n/** the value of the `data-track` attribute of an element whose click tracks the event */\nexport function trackAttribute(input: TrackInput): string {\n  return JSON.stringify(input);\n}\n\n/** the payload of a destination in an event, `undefined` when the event is not meant for it */\nexport function payloadOf(event: RelayEvent, name: string): unknown {\n  return (event as Record<string, unknown>)[name];\n}\n\n/** what a destination knows about an event besides its payload */\nexport type EventMeta = {\n  id: string;\n  /** epoch milliseconds of the track call */\n  at: number;\n  /** the key of the definition the event came from, `undefined` for a plain event */\n  key?: string | undefined;\n};\n\n/** `track()`, the same in the browser and on the server: puts the event on the bus, returns its id */\nexport type TrackFunction = (input: TrackInput) => string;\n\n/** whether this runs in a browser: a runtime check, so the built package works outside vite too */\nexport function isBrowser(): boolean {\n  return typeof window !== 'undefined' && typeof document !== 'undefined';\n}\n\n/** a fresh event id: a uuid; `randomUUID` needs a secure context, random bytes do not */\nexport function createEventId(): string {\n  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();\n\n  const bytes = crypto.getRandomValues(new Uint8Array(16));\n\n  bytes[6] = ((bytes[6] ?? 0) & 0x0F) | 0x40;\n  bytes[8] = ((bytes[8] ?? 0) & 0x3F) | 0x80;\n\n  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');\n\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;\n}\n\nconst MAX_ID_LENGTH = 64;\nconst EVENT_ID = /^[\\w.:-]+$/;\n\n/** a usable event id from an untrusted value: non-empty, printable, bounded */\nexport function isEventId(value: unknown): value is string {\n  return typeof value === 'string' && value.length > 0 && value.length <= MAX_ID_LENGTH && EVENT_ID.test(value);\n}\n\n/** the id an event fires under: its own when it carries a usable one (an order number), else a fresh one */\nexport function eventIdOf(own: string | undefined): string {\n  return isEventId(own) ? own : createEventId();\n}\n\n/**\n * Why an event does not fire under the id it came with, for the log of whoever tracked it: the\n * other side reports the conversion under the own id, so a replaced one counts twice.\n */\nexport function unusableEventId(own: unknown, id: string): string | undefined {\n  if (own === undefined || isEventId(own)) return undefined;\n\n  return `event id ${JSON.stringify(own)} is not usable (1 to ${MAX_ID_LENGTH} of A-Z, a-z, 0-9, _ . : -), the event fires under ${id} instead`;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,136 @@
 {
   "name": "@astroscope/relay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Consent-aware event relay for Astro",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.browser.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./track": {
+      "types": "./dist/server/track.d.ts",
+      "browser": "./dist/client/track.js",
+      "default": "./dist/server/track.js"
+    },
+    "./registry": {
+      "types": "./dist/server/registry.d.ts",
+      "import": "./dist/server/registry.js"
+    },
+    "./middleware": {
+      "types": "./dist/server/middleware-entrypoint.d.ts",
+      "import": "./dist/server/middleware-entrypoint.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./astro": {
+      "import": "./src/astro/index.ts"
+    },
+    "./ga4": {
+      "types": "./dist/ga4/index.d.ts",
+      "import": "./dist/ga4/index.js"
+    },
+    "./gtm": {
+      "types": "./dist/gtm/index.d.ts",
+      "import": "./dist/gtm/index.js"
+    },
+    "./matomo": {
+      "types": "./dist/matomo/index.d.ts",
+      "import": "./dist/matomo/index.js"
+    },
+    "./ccm19": {
+      "types": "./dist/ccm19/index.d.ts",
+      "import": "./dist/ccm19/index.js"
+    },
+    "./awin": {
+      "types": "./dist/awin/index.d.ts",
+      "import": "./dist/awin/index.js"
+    },
+    "./openai": {
+      "types": "./dist/openai/index.d.ts",
+      "import": "./dist/openai/index.js"
+    },
+    "./openai/server": {
+      "types": "./dist/openai/server.d.ts",
+      "import": "./dist/openai/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/astro"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entwico/astroscope",
+    "directory": "packages/relay"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "analytics",
+    "consent",
+    "tracking",
+    "ga4",
+    "awin",
+    "ccm19",
+    "matomo",
+    "conversions",
+    "actions",
+    "gtm",
+    "middleware"
+  ],
+  "author": "admin@entwico.com",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/entwico/astroscope/issues"
+  },
+  "homepage": "https://github.com/entwico/astroscope/tree/main/packages/relay#readme",
+  "dependencies": {
+    "@entwico/dash": "^1.3.0"
+  },
+  "devDependencies": {
+    "@astroscope/node": "^4.2.0",
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "astro": "^7.4.4",
+    "happy-dom": "^21.0.4",
+    "react": "^19.3.1",
+    "tsdown": "^0.23.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "peerDependencies": {
+    "@astroscope/node": "^4.2.0",
+    "astro": "^7.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --cache",
+    "lint:fix": "eslint src --fix"
+  }
 }

package/src/astro/Track.astro

@@ -0,0 +1,16 @@
+---
+import { type TrackInput, inlineTrack } from '@astroscope/relay';
+
+/**
+ * Tracks an event from server-rendered html: an inline push into the queue the bus drains when it
+ * installs, or straight onto the bus when it is already there. Use it for what the page shows
+ * (`view_item`, `view_item_list`), where no island is involved.
+ */
+type Props = {
+  event: TrackInput;
+};
+
+const { event } = Astro.props;
+---
+
+<Fragment set:html={`<script>${inlineTrack(event)}</script>`} />

package/src/astro/index.ts

@@ -0,0 +1 @@
+export { default as Track } from './Track.astro';