# Arial canonical event taxonomy v0.0.4

## Rules

1. Canonical only. If a canonical event below fits, use it.
2. For product-specific action, emit `feature.used` with an agent-chosen `feature_id` (stable, workspace-local) and the right `feature_role`.
3. Never emit PII in event properties (no email, name, billing details).
4. Target metrics for experiments must be canonical event names.

Canonical object vocabulary: user, account, session, page, onboarding, activation, feature, trial, plan, checkout, subscription, experiment, error, support.
Any event name outside the canonical set is rejected at ingest.

## Sources

Each event declares allowed sources (client / server). Ingest enforces. When two are listed, the precedence wins at dedup.

## Events

### user.signed_up
A new user created an account.
Sources: client, server (wins)
Properties:
  method: enum(google|github|email|sso)
  referrer?: string

### user.signed_in
An existing user authenticated.
Sources: client, server (wins)
Properties:
  method: enum(google|github|email|sso)

### user.signed_out
A user ended their session intentionally.
Sources: client
Properties: (none)

### user.invited
A workspace invite was sent. Carries invite_id, never email.
Sources: server
Properties:
  invite_id: string
  role: enum(owner|admin|member|viewer)

### user.invite_accepted
An invited user accepted and joined a workspace.
Sources: server
Properties:
  invite_id: string

### account.created
A new workspace / tenant account was created.
Sources: client, server (wins)
Properties:
  plan_id?: string

### account.member_added
A user was added to an existing account.
Sources: server
Properties:
  added_user_id: string
  role: enum(owner|admin|member|viewer)

### account.member_removed
A user was removed from an existing account.
Sources: server
Properties:
  removed_user_id: string

### onboarding.step_completed
An ordered onboarding step was finished.
Sources: client
Properties:
  step_id: string
  step_index: integer >= 0
  total_steps?: integer >= 0

### onboarding.completed
The full onboarding flow was finished.
Sources: client
Properties:
  total_steps: integer >= 0
  duration_ms?: integer >= 0

### onboarding.abandoned
Onboarding was exited before completion.
Sources: client
Properties:
  last_step_id: string
  step_index: integer >= 0

### activation.reached
The workspace's declared 'aha' moment fired for this user.
Sources: client, server (wins)
Properties:
  trigger_event: string

### session.started
A new user session began.
Sources: client
Properties: (none)

### session.ended
A user session ended; carries duration and event count.
Sources: client
Properties:
  duration_ms: integer >= 0
  event_count: integer >= 0

### page.viewed
A page or screen was viewed.
Sources: client
Properties:
  path: string
  title?: string
  referrer?: string

### feature.used
A product feature was used. feature_id is a stable, workspace-local identifier the agent chooses; feature_role classifies the feature for cross-workspace comparison.
Sources: client
Properties:
  feature_id: string
  feature_role: enum(activation|core|growth|monetisation|retention|other)
  outcome: enum(success|error|abandoned)

### feature.first_used
A user used a product feature for the first time. Same id/role shape as feature.used.
Sources: client
Properties:
  feature_id: string
  feature_role: enum(activation|core|growth|monetisation|retention|other)

### trial.started
A trial subscription began.
Sources: server
Properties:
  plan_id: string
  trial_duration_days: integer >= 0

### trial.ended
A trial ended; outcome distinguishes converted vs expired vs canceled.
Sources: server
Properties:
  plan_id: string
  outcome: enum(converted|expired|canceled)

### plan.viewed
Pricing or upgrade surface was viewed. Use surface to identify which.
Sources: client
Properties:
  plan_id?: string
  surface: enum(pricing_page|upgrade_modal|billing_settings|other)

### checkout.started
A user opened the checkout flow.
Sources: client
Properties:
  plan_id: string
  amount_native_minor: integer >= 0
  currency: enum(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|SEK|NZD|MXN|SGD|HKD|NOK|KRW|TRY|RUB|INR|BRL|ZAR|DKK|PLN|TWD|THB|MYR|IDR|PHP|CZK|HUF|ILS|CLP|AED|COP|SAR|VND|ARS|EGP)
  interval: enum(one_time|monthly|quarterly|annually)

### checkout.completed
Server-confirmed purchase. Carries native amount + currency + interval.
Sources: server
Properties:
  plan_id: string
  amount_native_minor: integer >= 0
  currency: enum(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|SEK|NZD|MXN|SGD|HKD|NOK|KRW|TRY|RUB|INR|BRL|ZAR|DKK|PLN|TWD|THB|MYR|IDR|PHP|CZK|HUF|ILS|CLP|AED|COP|SAR|VND|ARS|EGP)
  interval: enum(one_time|monthly|quarterly|annually)
  payment_provider: enum(stripe|paddle|chargebee|other)
  provider_customer_id?: string

### checkout.abandoned
Checkout was exited before completion. Records the last step reached.
Sources: client
Properties:
  plan_id?: string
  step: enum(plan_selection|billing_details|payment|confirmation)

### subscription.created
A new paid subscription was created.
Sources: server
Properties:
  subscription_id: string
  plan_id: string
  amount_native_minor: integer >= 0
  currency: enum(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|SEK|NZD|MXN|SGD|HKD|NOK|KRW|TRY|RUB|INR|BRL|ZAR|DKK|PLN|TWD|THB|MYR|IDR|PHP|CZK|HUF|ILS|CLP|AED|COP|SAR|VND|ARS|EGP)
  interval: enum(one_time|monthly|quarterly|annually)

### subscription.upgraded
A subscription moved to a higher-priced plan. Records previous and new plan ids.
Sources: server
Properties:
  subscription_id: string
  previous_plan_id: string
  new_plan_id: string
  amount_native_minor_delta: integer
  currency: enum(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|SEK|NZD|MXN|SGD|HKD|NOK|KRW|TRY|RUB|INR|BRL|ZAR|DKK|PLN|TWD|THB|MYR|IDR|PHP|CZK|HUF|ILS|CLP|AED|COP|SAR|VND|ARS|EGP)

### subscription.downgraded
A subscription moved to a lower-priced plan. Records previous and new plan ids.
Sources: server
Properties:
  subscription_id: string
  previous_plan_id: string
  new_plan_id: string
  amount_native_minor_delta: integer
  currency: enum(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|SEK|NZD|MXN|SGD|HKD|NOK|KRW|TRY|RUB|INR|BRL|ZAR|DKK|PLN|TWD|THB|MYR|IDR|PHP|CZK|HUF|ILS|CLP|AED|COP|SAR|VND|ARS|EGP)

### subscription.canceled
A subscription was canceled. Records reason and effective date.
Sources: server
Properties:
  subscription_id: string
  plan_id: string
  reason?: enum(user_initiated|payment_failed|admin|other)
  effective_at?: string(datetime)

### subscription.renewed
A recurring billing period renewed successfully.
Sources: server
Properties:
  subscription_id: string
  plan_id: string
  amount_native_minor: integer >= 0
  currency: enum(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|SEK|NZD|MXN|SGD|HKD|NOK|KRW|TRY|RUB|INR|BRL|ZAR|DKK|PLN|TWD|THB|MYR|IDR|PHP|CZK|HUF|ILS|CLP|AED|COP|SAR|VND|ARS|EGP)
  interval: enum(one_time|monthly|quarterly|annually)

### experiment.exposed
A user was exposed to a variant of an experiment. The conversion outcome is derived at readout time by checking whether the experiment's canonical target metric fired for the same actor within the conversion window — there is no separate experiment.converted event.
Sources: client (wins), server
Properties:
  experiment_id: string
  variant_id: string

### error.encountered
A user-facing error was observed. message is workspace-local; never PII.
Sources: client, server
Properties:
  surface: enum(client|server|integration)
  severity: enum(debug|info|warning|error|critical)
  error_code?: string
  message?: string

### support.contacted
A user contacted support via any channel.
Sources: client
Properties:
  channel: enum(chat|email|phone|form|other)
  topic?: string

## Context

Every event envelope carries a context object. SDKs populate most fields; ingest derives lifecycle_stage and referrer_domain.

arial_event_id: string(uuid)
arial_timestamp: string(datetime)
arial_taxonomy_version: string
arial_sdk_version: string
arial_workspace_id: string
user_id: string | null
anonymous_id: string
session_id: string
account_id: string | null
platform: enum(web|ios|android|server)
device_type?: enum(desktop|mobile|tablet|server)
url?: string
user_agent?: string
referrer_domain?: string
utm_source?: string
utm_medium?: string
utm_campaign?: string
utm_term?: string
utm_content?: string
experiment_assignments?: map<string, string>
lifecycle_stage?: enum(anonymous|signed_up|activated|paying|churned)

## Enums

eventSources: client, server
featureRoles: activation, core, growth, monetisation, retention, other
currencies: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, SEK, NZD, MXN, SGD, HKD, NOK, KRW, TRY, RUB, INR, BRL, ZAR, DKK, PLN, TWD, THB, MYR, IDR, PHP, CZK, HUF, ILS, CLP, AED, COP, SAR, VND, ARS, EGP
intervals: one_time, monthly, quarterly, annually
deviceTypes: desktop, mobile, tablet, server
lifecycleStages: anonymous, signed_up, activated, paying, churned