Getting started
Install the package and emit your first correctly typed event.
Install
The package is published to GitHub Packages under the @kigo-digital scope, so
your project needs an .npmrc that points the scope at it:
@kigo-digital:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}Then:
npm install @kigo-digital/augeo-eventsFor the in-progress contract ahead of the last stable release:
npm install @kigo-digital/augeo-events@betaEmit an event
import type { AugeoEventOf } from "@kigo-digital/augeo-events";
const event: AugeoEventOf<"com.augeo.ui.component.viewed"> = {
spec: "augeo.event",
specversion: "1.0",
id: crypto.randomUUID(),
type: "com.augeo.ui.component.viewed",
typeversion: 1,
time: Date.now(),
class: "observed",
source: { surface: "product_card", instanceId: "pc_1f2a" },
correlation: {},
data: {
occurrence: { componentName: "product_card", exposureMs: 1204 },
context: { augds: { surface: "product_card", instanceId: "pc_1f2a" } },
},
};Four things the type system will refuse:
// An unregistered name.
const a: AugeoEventOf<"com.augeo.ui.action.invented"> = {
/* ... */
};
// The wrong class for a name — ui.component.viewed is observed.
const b: AugeoEventOf<"com.augeo.ui.component.viewed"> = {
class: "measured" /* ... */,
};
// A field from a different occurrence.
const c = { componentName: "product_card", exposureMs: 1, firstTokenMs: 740 };
// A missing required field — exposureMs is required here.
const d = { componentName: "product_card" };That last one matters more than it looks. Emitting an unregistered name is a compile error rather than a row that quietly appears in a warehouse three weeks later.
Consume events
Switch on type and the payload narrows with it:
import type { AnyAugeoEvent } from "@kigo-digital/augeo-events";
function handle(event: AnyAugeoEvent): string {
switch (event.type) {
case "com.augeo.ui.component.viewed":
return `viewed for ${event.data.occurrence.exposureMs}ms`;
case "com.augeo.preference.declared":
return `${event.data.occurrence.labels.length} labels in ${event.data.occurrence.taxonomy}`;
default:
return event.type;
}
}What you may write
The envelope is not a free-for-all. Each layer writes only what it can honestly know.
A design system MAY write spec, specversion, id, type, typeversion,
time, class, source, data.occurrence, data.context.augds, a
correlation.effectId it minted for its own effect, and a correlation.slotId
for a slot it declared.
It MUST NOT write subject, any other correlation field, or any other context
namespace. It cannot honestly know them, and the layer above will fill them in.
Three identities, not one
Routinely confused, and the confusion is expensive:
| Field | Addresses | Scope |
|---|---|---|
subject | the placement a component rendered into | one region, many subjects |
correlation.effectId | one attempt at a mutation | one attempt |
data.occurrence.subjectKey | the thing being written to | stable across attempts |
Reading subject as the subject folds every effect in one placement together, so
a member who failed to save two different rewards from the same slot would be
shown one failure.
Entry points
| Import | Holds |
|---|---|
@kigo-digital/augeo-events | types, the name union, registry data |
@kigo-digital/augeo-events/registry | the registry data and its lookups alone |
@kigo-digital/augeo-events/validate | the Zod schemas and the validators |
@kigo-digital/augeo-events/schemas | every JSON Schema document |
@kigo-digital/augeo-events/analytics/core | destination mapping and CloudEvents conversion, no writers |
@kigo-digital/augeo-events/analytics/gtag | piggyback gtag writer |
@kigo-digital/augeo-events/analytics/gtm | piggyback dataLayer writer |
@kigo-digital/augeo-events/analytics/custom | host-supplied writer |
The validators and the schemas are opt-in, so a design system that only needs to
emit correctly typed events ships neither. Destination writers are a separate
opt-in: import /analytics/core from a widget that must not contain gtag.
How mapping and piggyback writes work is in Destination analytics.
Zod is the only runtime dependency, and it is reachable only through
/validate. The root, /registry, and /analytics/core entries import it not
at all.