Augeo AI Docs
Events Dictionary

Destination analytics

Map augeo.event onto destination names and piggyback writers.

What this package does not do

@kigo-digital/augeo-events fires no events. It holds no identity. It does not decide where events are sent. That charter is load-bearing: a dictionary that called gtag('config') or PostHog.init() would mint a second tracker beside the one the host already loaded.

What it does ship is the destination binding: a mapping from a registered augeo.event onto a destination event name plus params, plus optional pure writers that assume the host already initialized the tag. Subscribe, consent, and fan-out live in the implementing SDK, not here.

Entry points

ImportHolds
@kigo-digital/augeo-events/analytics/coremapping, CloudEvents conversion, denylist — no destination writers
@kigo-digital/augeo-events/analytics/gtagcreateGtagAdapter
@kigo-digital/augeo-events/analytics/gtmcreateGtmAdapter
@kigo-digital/augeo-events/analytics/customcreateCustomAdapter
@kigo-digital/augeo-events/analyticsall of the above

Import /analytics/core from a widget bundle that must not contain gtag. Import a writer only from the host (or an SDK entry the IIFE does not load). Importing /analytics pulls the writers into that graph.

Look up a destination name

The vendor-neutral lookup is destinationEventFor. Registry field ga4 is still the source of the default name; ga4EventFor is a published alias of the same function.

import { destinationEventFor, ga4EventFor } from "@kigo-digital/augeo-events/analytics/core";

destinationEventFor("com.augeo.engagement.cart.item.added"); // "add_to_cart"
destinationEventFor("com.augeo.ui.action.pressed"); // null — observed, no projection
ga4EventFor("com.augeo.engagement.cart.item.added") ===
  destinationEventFor("com.augeo.engagement.cart.item.added");

null is an answer: that name is not forwarded. Do not invent a destination event for it. Observed ui.* names are in this set on purpose.

The default projection for every registered name is on Destination names. A host overlay can rename a row; that page is the default, not a ceiling. The same lookup is on the published package:

import { destinationEventFor } from "@kigo-digital/augeo-events/analytics/core";

destinationEventFor("com.augeo.engagement.item.viewed"); // "theo_item_impression"

A per-item impression is not GA4 view_item. view_item belongs to engagement.item.detail.viewed. Projecting a card someone scrolled past onto view_item made it indistinguishable from a product they opened.

engagement.cart.item.updated follows the sign of the quantity delta when both item.quantity and previousQuantity are present: a decrease maps to remove_from_cart, otherwise the registry default (add_to_cart). GA4 has no quantity-change event; the canonical stream still keeps add and update as separate names.

Map an event

applyMapping takes the compact envelope, an optional host overlay, and an optional identity callback. Registry defaults first, overlay last. Only keys the mapping named leave.

import { applyMapping } from "@kigo-digital/augeo-events/analytics/core";

const result = applyMapping(event);
if (!result.ok) {
  // "mapped_drop" | "direct_identifier_blocked" | "forbidden_key"
  return;
}
result.mapped.event; // destination event name
result.mapped.params; // only mapped scalars
result.mapped.items; // ItemRef → GA4 items[], when present
result.mapped.kind; // "standard" | "custom" | "none"

A host overlay renames the destination event and adds params. It does not invent a parallel catalog of augeo.event names.

const overlay = {
  allowDirectIdentifiers: ["userId"],
  events: {
    "com.augeo.engagement.cart.item.added": {
      event: "theo_add_to_cart",
      params: {
        placement_type: { from: "context.storefront.attribution" },
        catalog_id: { from: "context.storefront.catalogId" },
        member_key: { identity: "userId" },
        product_id: { from: "data.occurrence.item.id" },
      },
    },
  },
};

applyMapping(event, overlay, { userId: () => hostMemberId });

from is a dot-path on the compact envelope. A path starting context. is read as data.context.. { const: value } writes a literal. { identity: "userId" } calls the host callback only if allowDirectIdentifiers includes userId.

The overlay chooses the destination param name. This package never bakes a host-specific key such as prysm_user_id into the mapping. That name belongs in the host overlay, not the library.

Setting event: null drops the name. Unmapped keys do not travel.

PDP guidance projection

Rewards Hub owns the PDP UI component and host integration. The AI integration defines the event/integration contract and owns contextual Chat wiring, semantic measurement and backend intake. Rewards Hub implements against that contract using the existing event system. Native facts must conform to the registered profile; a different mapping requires an explicit AI-owned contract revision. Design-system provenance applies only to design-system reuse. The event bus carries no question text or labels. The host integration supplies those privately to the existing local contextual Chat operation. These recipes neither build a standalone PDP SDK nor start a Chat turn.

Four measured names already have destination events: theo_launcher_viewed, theo_prompt_selected, theo_turn_requested and theo_turn_admission_reported. On source.surface pdp_guidance, applyMapping also fills scalar params for that recipe. The same names on any other surface keep the name-only default. Observed ui.* inputs, including the native chip press, still have no default projection. Registration does not enable a layer, grant consent, configure forwarding, or select an account, warehouse, collector or provider.

Only those scalars leave. Missing and blank values are omitted. The nested prompt-presentation item is not turned into an ecommerce items array. programId and placementId are included when the envelope already has them. causationId, a known conversationId, and turnId on a request or outcome are included only as correlation mirrors. Product id, question text and URL are not used as subject and do not authorize the write.

participantRef is not a default param. An overlay may map that opaque value only as participant_ref. That mapping does not call DestinationIdentity.userId. userId stays blocked for this composition even if the overlay sets allowDirectIdentifiers.

An overlay that reads question or seed text, a prompt label, a member or identity id, rewardsAuthorityFingerprint, a token, email, profile data, an exact balance, a product snapshot, attributes, title, price, a URL, a selector, PdpHostScope, or an object bag fails with forbidden_key. Renaming the destination key, or writing the path as context.* instead of data.context.*, does not bypass that. A native chip press that carries prompt presentation is held to the same rule, so its label cannot leave through a host-chosen param.

Destination keyWhen it is set
event_id, source_surface, presentation, prompt-set and item scalars, causation_idall four measured names, omitting a missing causation id
placement_id, program_idwhen resolved
exposure_mslauncher impression
prompt_id, prompt_type, prompt_source, position, presentation, gesture_keychoice, request and outcome
client_turn_idrequest and outcome, when the turn is known
conversation_idwhen the thread is known
admission_status, plus admission_disposition and user_message_id or outcome_codeadmission outcome; the unused branch is omitted

Identity stays on the destination, not the envelope

Three different things get collapsed. Keep them apart.

SurfaceWhat it may carry
Compact augeo.event (Layer 1)opaque theo.participantRef only — no email, phone, name, card, or raw member id
Destination params (Layer 3)only keys the overlay mapped, plus items from ItemRef when the kind is standard
Host identity callbacka user id for the destination, never copied onto augeo.event

{ identity: "userId" } without allowDirectIdentifiers: ["userId"] fails closed (direct_identifier_blocked). PDP guidance never resolves userId, even when the overlay opts in. That hatch does not unlock email, phone, card, person name, or billing address. Those destination keys are refused even when the overlay names them (forbidden_key).

participantRef is not a drop-in for a host profile id. It is a hash of the SDK's API user, minted by the SDK. If a destination report already joins on a host profile id, the host supplies that id through the mapping, on Layer 3 only.

CloudEvents conversion

Compact form is what the browser bus carries. CloudEvents 1.0 is the form at the SDK boundary and up. The conversion is total for the compact fields this package knows about:

import { toCloudEvent, fromCloudEvent } from "@kigo-digital/augeo-events/analytics/core";

const cloud = toCloudEvent(event);
const compact = fromCloudEvent(cloud);

source.surface and source.instanceId are URI-encoded as path components so a value containing / round-trips. Promoted CloudEvents attributes (eventclass, programid, family, origin) still mirror data.context.theo and must not contradict it.

Writers (piggyback only)

A writer calls a tag the host already initialized. It does not insert a script, does not call gtag('config'), and does not create window.dataLayer.

import { applyMapping, toCloudEvent } from "@kigo-digital/augeo-events/analytics/core";
import { createGtagAdapter } from "@kigo-digital/augeo-events/analytics/gtag";

const adapter = createGtagAdapter({ gtag: window.gtag });
if (!adapter.ready?.()) {
  // destination_not_ready — do not inject gtag.js from here
}

const mapped = applyMapping(event, overlay, identity);
if (!mapped.ok) return;
adapter.send({
  event,
  cloudEvent: toCloudEvent(event),
  mapped: mapped.mapped,
});
WriterCallIf the tag is missing
createGtagAdaptergtag('event', name, params)send throws destination_not_ready
createGtmAdapterdataLayer.push({ event, ...params })buffers up to 50 dispatches on that adapter instance
createCustomAdapterthe function you passedwhatever you implement

Do not enable gtag and GTM writers together on a page that already uses gtag directly. One destination, one writer.

A custom writer is how PostHog, Mixpanel, Amplitude, Matomo, Plausible, Fathom, Adobe Analytics, Piwik PRO, or an ad platform is added today: same AnalyticsAdapter shape, your send. Built-in loaders that call vendor.init() are out of this package on purpose.

DestinationDeclineReason includes consent_withheld, disabled, lifecycle, and adapter_error because the SDK runtime uses those codes. This package does not read cookies, does not guess a CMP, and does not subscribe to augeo.event. If consent is omitted at the SDK, that means the host tag already handled it (piggyback). If consent is provided there, the SDK gates on it.