# @oshun/analytics

Typed analytics event APIs for OSHUN shell and domain surfaces.

## Includes

- Strongly typed OSHUN event dictionary and payload contracts
- `AnalyticsClient` with context propagation and sink fan-out
- Sink interfaces for identify/track/flush lifecycle
- In-memory sink for tests and local development
- **V1 customer event taxonomy** (`customer-taxonomy.ts`) — canonical,
  machine-readable definition of every customer-surface event for OSHUN V1. See
  [docs/releases/v1/specs/customer-event-taxonomy.md](../../../docs/releases/v1/specs/customer-event-taxonomy.md)
  for the human-readable companion.
- **V1 admin event taxonomy** (`admin-taxonomy.ts`) — canonical,
  machine-readable definition of every admin/operator-surface event for OSHUN
  V1. See
  [docs/releases/v1/specs/admin-event-taxonomy.md](../../../docs/releases/v1/specs/admin-event-taxonomy.md)
  for the human-readable companion.
- **V1 assistant event taxonomy** (`assistant-taxonomy.ts`) — canonical,
  machine-readable definition of every assistant interaction, memory state
  (Iris), grounding state (Sophia), persona identity (Lilith), and AI disclosure
  (ADR-0060) event for OSHUN V1. See
  [docs/releases/v1/specs/assistant-event-taxonomy.md](../../../docs/releases/v1/specs/assistant-event-taxonomy.md)
  for the human-readable companion.
- **V1 flows event taxonomy** (`flows-taxonomy.ts`) — canonical,
  machine-readable definition of every cross-cutting review, moderation, appeal,
  and incident-flow event for OSHUN V1, covering customer-facing appeal
  lifecycle, moderation/review outcome delivery, customer incident
  communications, status-page activity, SLA breach/recovery, and cross-workspace
  handoffs. See
  [docs/releases/v1/specs/flows-event-taxonomy.md](../../../docs/releases/v1/specs/flows-event-taxonomy.md)
  for the human-readable companion.
- **V1 release event taxonomy** (`release-taxonomy.ts`) — canonical,
  machine-readable definition of every model intake, ModelCard/ModelVersion
  lifecycle, model promotion gate, evaluation run, ProvenanceBundle, rights
  inspection / takedown, media generation, media release, and admin
  release-readiness event for OSHUN V1. See
  [docs/releases/v1/specs/release-event-taxonomy.md](../../../docs/releases/v1/specs/release-event-taxonomy.md)
  for the human-readable companion.
- **V1 customer KPI dashboard manifest** (`dashboards-customer-kpi.ts`) —
  canonical, machine-readable definition of the activation, retention,
  cross-domain usage, and continuity dashboards mandated by V1-OBS-006. Each
  metric references events in the customer taxonomy; tests lock the manifest
  against ADR-0006 KPI parity. See
  [docs/releases/v1/reports/customer-kpi-dashboards.md](../../../docs/releases/v1/reports/customer-kpi-dashboards.md)
  for the human-readable companion.
- **V1 Nisaba dashboard manifest** (`dashboards-nisaba.ts`) — canonical,
  machine-readable definition of the Nisaba adoption and cross-domain attachment
  dashboards mandated by V1-OBS-007. See
  [docs/releases/v1/reports/nisaba-dashboards.md](../../../docs/releases/v1/reports/nisaba-dashboards.md)
  for the human-readable companion.
- **V1 assistant dashboard manifest** (`dashboards-assistant.ts`) — canonical,
  machine-readable definition of the assistant quality and disclosure compliance
  dashboards mandated by V1-OBS-008. See
  [docs/releases/v1/reports/assistant-dashboards.md](../../../docs/releases/v1/reports/assistant-dashboards.md)
  for the human-readable companion.
- **V1 structured tracing manifest** (`tracing-manifest.ts`) — canonical,
  machine-readable definition of the V1 trace span families, propagation
  channels, and shared attribute conventions across the shell, BFF, Sophia,
  Iris, Psyche, Lilith, and Isis. See
  [docs/releases/v1/specs/tracing-manifest.md](../../../docs/releases/v1/specs/tracing-manifest.md)
  for the human-readable companion.

## Nx Targets

- `pnpm nx run @oshun/analytics:build`
- `pnpm nx run @oshun/analytics:lint`
- `pnpm nx run @oshun/analytics:typecheck`
- `pnpm nx run @oshun/analytics:test`