Augeo AI Docs
Events Dictionary

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-events

For the in-progress contract ahead of the last stable release:

npm install @kigo-digital/augeo-events@beta

Emit 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:

FieldAddressesScope
subjectthe placement a component rendered intoone region, many subjects
correlation.effectIdone attempt at a mutationone attempt
data.occurrence.subjectKeythe thing being written tostable 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

ImportHolds
@kigo-digital/augeo-eventstypes, the name union, registry data
@kigo-digital/augeo-events/registrythe registry data and its lookups alone
@kigo-digital/augeo-events/validatethe Zod schemas and the validators
@kigo-digital/augeo-events/schemasevery JSON Schema document
@kigo-digital/augeo-events/analytics/coredestination mapping and CloudEvents conversion, no writers
@kigo-digital/augeo-events/analytics/gtagpiggyback gtag writer
@kigo-digital/augeo-events/analytics/gtmpiggyback dataLayer writer
@kigo-digital/augeo-events/analytics/customhost-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.