Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

16.0 KB
Raw Blame
/**
 * Payload shared by the generic entity lifecycle events (`create_entity`,
 * `update_entity`, `delete_entity`, `share_entity`).
 *
 * Only the identifying fields are structured; any event-specific context
 * (e.g. `hasDueDate` on task creation, `newProjectId` on a move) rides along
 * as unstructured extra properties instead of minting a new event type.
 */
export type EntityEventPayload = {
  /**
   * Coarse entity/block type: 'md' | 'task' | 'snippet' | 'code' | 'canvas' |
   * 'chat' | 'project' | 'channel' | 'email' | 'document' | ... Open-ended on
   * purpose — different layers know the entity at different granularities.
   */
  entityType: string;
  entityId?: string;
  /** UI surface the action originated from (e.g. 'launcher', 'mobile_dock'). */
  source?: string;
} & Record<string, unknown>;

/** A normalized reason selected before deleting an account. */
export type AccountDeletionReason =
  | 'not_using_enough'
  | 'missing_features'
  | 'difficult_to_use'
  | 'bugs_or_performance'
  | 'too_expensive'
  | 'prefer_another_product'
  | 'privacy_or_security_concerns'
  | 'other';

export type AppEvents = {
  // --- Acquisition & auth -------------------------------------------------
  /**
   * Account creation, browser side (GA only). The authoritative PostHog
   * `sign_up` is emitted server-side from the create-user webhook; the
   * browser fires this GA event plus the ad conversions when the backend
   * flags the session via the `signed_up=true` redirect param. See
   * signupCompletion.ts.
   */
  sign_up: Record<string, unknown>;
  /** Signup intent: user clicked a sign-up CTA (pre-redirect, may not convert). */
  sign_up_click: { method?: string } & Record<string, unknown>;
  login: Record<string, unknown>; // payload - include link status
  sign_out: Record<string, unknown>;
  account_deletion_feedback: {
    reason: AccountDeletionReason | 'not_provided';
    feedback?: string;
  };
  login_from_onboarding: Record<string, unknown>;
  mobile_web_welcome_viewed: Record<string, unknown>;
  mobile_web_signup_sent_viewed: Record<string, unknown>;

  // --- Interactive tutorial (optional; decoupled from acquisition) ---------
  tutorial_started: { isFirstTime: boolean };
  tutorial_step: {
    id: string;
    index: number;
    state: 'viewed' | 'completed' | 'skipped';
  };
  tutorial_completed: { isFirstTime: boolean };
  tutorial_skipped: Record<string, unknown>;

  // --- Onboarding v4 (the full-screen /onboarding stepper) -----------------
  /** A GTM invite welcome page resolved its link (`/invite?token=`). */
  gtm_invite_opened: { status: string };
  /** The recipient pressed Continue on the welcome page. */
  gtm_invite_continue: { authenticated: boolean };
  /** An account was attributed to an invite link and granted its offer. */
  gtm_invite_redeemed: { link_id: string; promo_code: string };
  /** The plan step showed the free-month offer instead of the picker. */
  gtm_invite_offer_viewed: { link_id: string; promo_code: string };
  /** Staff created an invite link in the internal portal. */
  gtm_invite_link_created: { link_id: string };
  /**
   * Flow entered. `signup_method` is inferred from the inbox state at
   * entry: a Google signup arrives with its inbox already linked, an
   * email-code signup with none. `entry_step` is the step shown first:
   * a checkout return, saved progress, a `?step` link, or welcome.
   */
  onboarding_v4_started: {
    signup_method: 'google' | 'email_code';
    entry_step: string;
  };
  /** One per step transition: viewed on entry, completed/skipped on exit. */
  onboarding_v4_step: {
    step: string;
    index: number;
    state: 'viewed' | 'completed' | 'skipped';
  };
  /** A connect-inbox row was clicked (OAuth may still be abandoned). */
  onboarding_v4_email_connect_clicked: { slot: string };
  /** An inbox finished linking while onboarding. */
  onboarding_v4_email_connected: { connected_count: number };
  /** A connector completed OAuth from its step. */
  onboarding_v4_connector_connected: { connector: string };
  /** What happened on the team step. */
  onboarding_v4_team: {
    action:
      | 'created'
      | 'joined_invite'
      | 'already_on_team'
      | 'invite_link_copied'
      | 'referrals_sent'
      | 'referral_link_copied';
    invites_sent?: number;
    /** Same-domain teammates the step pre-added to the invite list. */
    invites_prefilled?: number;
    /** How many of those the user removed before creating the team. */
    invites_removed?: number;
    used_domain_suggestion?: boolean;
    /** Whether people on the work domain may join. */
    allow_domain_join?: boolean;
    /** Whether the domain notice was requested; only with domain join. */
    notify_domain?: boolean;
  };
  /**
   * The flow finished (free, premium, or plan skipped) with a rollup of
   * everything connected along the way.
   */
  onboarding_v4_completed: {
    plan: 'free' | 'premium' | 'max';
    plan_skipped: boolean;
    emails_connected: number;
    connectors_connected: string[];
  };
  /** A @macro.com account used the staff Bypass button; `step` is where. */
  onboarding_v4_bypassed: { step: string };

  subscription_start: Record<string, unknown>;
  subscription_cancel: Record<string, unknown>;
  subscription_success: Record<string, unknown>;

  sidebar_click: Record<string, unknown>;
  notifications_toggled: Record<string, unknown>;

  share_menu_open: { blockType: string };

  copy_share_link: Record<string, unknown>;
  download: Record<string, unknown>;
  comment_create: { blockType: string };
  comment_update: { blockType: string };
  comment_delete: { blockType: string };
  upload_file: {
    fileType?: string;
    fileName?: string;
    fileSize?: number;
    destination: 'dss' | 'static';
    folder?: boolean;
  };
  upload_error: {
    type: string;
    destination?: 'dss' | 'static';
  };

  command_menu_open: { from: string };
  command_menu_use: { itemType: string };
  create_menu_open: { from: string };
  hotkey_use: Record<string, unknown>;
  mentions_menu_use: { itemType: string };
  snippets_menu_use: Record<string, unknown>;
  /** `side` is where a split opened beside another; absent, it opened at the end. */
  split_created: { from: string; side?: 'left' | 'right' | 'above' | 'below' };

  // --- Entity lifecycle ----------------------------------------------------
  // Fired at data-layer chokepoints (core/util/create.ts, FileList
  // itemOperations, property-save mutations, share/forward flows, BlockLoader)
  // so every UI surface is covered without per-surface instrumentation.
  /**
   * An entity was opened in a split (md, task, pdf, chat, email, channel,
   * canvas, code, project, company, contact, ...). Fired from BlockLoader on
   * successful load; nested blocks and preview-panel peeks are excluded.
   * Route-owned detail views fire it themselves: documents from
   * FileDetailLoadGate, channels from ChannelDetail, calls and PRs from their
   * detail views. Blocks without an open history row fire it only when they
   * set `openAnalyticsEnabled` (database); calendar does not, since it loads
   * one fixed id and `open_view` already counts it.
   */
  open_entity: EntityEventPayload;
  /**
   * A top-level view was opened (soup list views like inbox/mail/documents/
   * tasks/channels, plus home, search, and the compose views). Fired from the
   * split-layout component registry.
   */
  open_view: { viewId: string } & Record<string, unknown>;
  /**
   * Agent sessions report create, rename (`update_entity`) and delete as
   * `entityType: 'agent'`, the type their `open_entity` carries. The retired
   * AI chat reported `chat`; count both for AI conversations over time.
   */
  create_entity: EntityEventPayload;
  update_entity: EntityEventPayload & {
    /** Which property changed: 'name' | 'parent_project' | 'status' | ... */
    property: string;
  };
  delete_entity: EntityEventPayload & { deleteType?: 'soft' | 'permanent' };
  share_entity: EntityEventPayload & {
    shareMethod?:
      | 'public_link'
      | 'team_link'
      | 'channel'
      | 'forward'
      | 'attachment_public'
      | (string & {});
    linkShare?: 'PUBLIC' | 'TEAM';
  };

  task_copy_branch_name: Record<string, unknown>;

  theme_changed: { themeId: string };

  /**
   * A message sent to AI, with `attachmentCount` files. `surface` is 'chat'
   * for the legacy AI chat and 'agent' for an accepted agent-session prompt
   * (AgentSession.sendPrompt), which also carries `agentSessionId`,
   * `agentId`, `newSession`, `submitSurface` and `queued`. Events before the
   * agent tracking have no `surface`.
   */
  ai_message_sent: Record<string, unknown>;
  /**
   * A file added to the legacy AI chat's input, on upload or drop. Agent
   * sessions report attachments as `ai_message_sent.attachmentCount` instead.
   */
  ai_attachment_add: Record<string, unknown>;
  /** A paid user opened Stripe Checkout for an AI credit pack. */
  ai_credits_checkout_start: { amountCents: number };
  /** A payer changed their AI usage billing (overage) settings. */
  ai_overage_updated: { enabled: boolean; limitCents: number };
  /** An existing subscriber moved between Premium and Max. */
  plan_changed: { plan: 'premium' | 'max'; from?: string };

  /**
   * An email the user sent, counted once when the outbox accepts it. Undo
   * does not retract it. Older events have no properties.
   */
  email_message_sent: { isReply: boolean };
  /**
   * How the inbox-link OAuth callback ended. `already_connected` is a plain add
   * whose account chooser returned an inbox the user already had; `connected`
   * still covers reconnects and calendar upgrades of an existing inbox.
   */
  email_link_callback_result: {
    outcome:
      | 'connected'
      | 'already_connected'
      | 'already_initialized'
      | 'shared_inbox_conflict'
      | 'payment_required'
      | 'no_gmail_grant'
      | 'gmail_not_granted'
      | 'failed'
      | 'exception'
      | 'missing_link_id';
  };

  channel_message_sent: Record<string, unknown>;
  channel_messages_load: {
    channelId: string;
    path: 'full';
    reason: 'no_cache' | 'cache_not_at_latest' | 'load_around' | 'revalidate';
  };
  channel_reaction: {
    emoji: string;
    action: 'add' | 'remove';
  };

  // In-product tutorial videos (the pinned row at the top of an inbox).
  tutorial_video: {
    /** `macro-<id>` for each id in features/video-tutorials/core/tutorial-id.ts. */
    tutorial:
      | 'macro-mail'
      | 'macro-home'
      | 'macro-chat'
      | 'macro-tasks'
      | 'macro-docs'
      | 'macro-drive'
      | 'macro-crm'
      | 'macro-calendar'
      | 'macro-calls'
      | 'macro-agents'
      | 'macro-github'
      | 'macro-scheduling'
      | 'macro-whatsapp';
    /** `support_clicked`: the dialog's "Talk to us" link under the video. */
    action: 'opened' | 'played' | 'dismissed' | 'support_clicked';
  };

  // --- Calls ---------------------------------------------------------------
  // Frontend call interactions only. Recordings, transcripts and summaries
  // are produced server-side and send no PostHog events yet; the call service
  // publishes them only to Kafka (`call.recording_ready`, `call.record_summarized`).
  call_action: {
    action:
      | 'join_clicked'
      | 'started'
      | 'joined'
      | 'left'
      | 'screen_share_toggled';
    channelId: string;
    callId?: string;
    /** On `left`: seconds since this client joined the call. */
    secondsInCall?: number;
  } & Record<string, unknown>;
  // Mic audio-processing state transitions (noise suppression attach /
  // detach / fallback). `constraintMismatch` flags engines that report
  // different track settings than were requested (mode changes that silently
  // no-oped); `sampleRate` <= 16000 indicates a Bluetooth HFP capture path.
  call_audio_processing: {
    event: string;
    channelId: string;
    preferredMode: string;
    activeMode: string;
    constraintMismatch: boolean;
  } & Record<string, unknown>;
  // Per-call summary of remote-audio decode health, flushed at room teardown.
  // High concealment alongside clean capture-side state points a "muddled
  // voices" report at the network/playback leg, not noise suppression.
  call_audio_receiver_stats: {
    channelId: string;
    callId?: string;
    sampledIntervals: number;
    badIntervals: number;
    maxConcealmentRate: number;
  } & Record<string, unknown>;

  block_pdf_definition_open: Record<string, unknown>;
  block_pdf_section_open: Record<string, unknown>;

  // --- Databases -----------------------------------------------------------
  /** A committed ops batch wrote rows of a database (grid, board, forms). */
  database_rows_edited: {
    databaseId: string;
    insertedRows: number;
    updatedRows: number;
    deletedRows: number;
  };
  /**
   * A database grid read its view: once when a view opens (a view switch
   * included) and once per filter or sort change that settles for a second.
   * Refreshes, live updates and layout edits are not counted. `host` tells a
   * database's own page from a grid embedded in a document or a form's
   * responses; only `block` opens are database opens.
   */
  database_query_run: {
    databaseId: string;
    tableId: string;
    viewId: string;
    host: 'block' | 'document' | 'form';
    trigger: 'open' | 'query_change';
    /** Top-level filter conditions; 0 when unfiltered. */
    filterConditions: number;
    sortKeys: number;
  };

  // --- Calendar ------------------------------------------------------------
  calendar_event_created: {
    eventId: string;
    attendees: number;
    recurring: boolean;
    macroCall: boolean;
    conference: boolean;
  };
  calendar_event_rsvp: {
    response: 'accepted' | 'declined' | 'tentative';
    scope: 'all' | 'this_event';
  };

  // --- Notifications -------------------------------------------------------
  /**
   * A notification was opened: from the app's lists and stacks (`in_app`), a
   * browser notification, a native iOS, Android or macOS notification tap
   * (`native_push`, counted once its navigation applies; `macro_device` tells
   * the platforms apart), or a home recommendation that opens through its
   * notification (`home_recommendation`, not a notification-driven open).
   */
  notification_opened: {
    source: 'in_app' | 'browser_push' | 'native_push' | 'home_recommendation';
    notificationType: string;
    entityType: string;
  };

  // --- Search --------------------------------------------------------------
  /**
   * One service search per settled query: a query whose results stay
   * unreplaced for 1.5s, or the last one when the surface closes. Refetches
   * and later pages of the same query are not counted; no query text is sent.
   */
  search_performed: {
    /** View id ('search', 'email', 'tasks', ...), 'home', or 'mobile_search'. */
    surface: string;
    matchType: 'exact' | 'partial';
    /** First page only: '0' | '1-9' | '10-49' | '50+'. */
    resultCount: string;
  };

  // --- CRM -----------------------------------------------------------------
  crm_company_created: { companyId: string };
  crm_contact_created: { companyId?: string; contactId: string };
  /**
   * A committed pipeline write: inserted rows are entries added, updated
   * rows include stage moves and other cell edits.
   */
  crm_pipeline_entries_edited: {
    pipelineId: string;
    recordType?: 'company' | 'contact' | 'generic';
    /** The pipeline editor or the record page's pipeline cards. */
    surface: 'pipeline' | 'record';
    insertedRows: number;
    updatedRows: number;
    deletedRows: number;
  };

  // --- Routines ------------------------------------------------------------
  // Client-side until the scheduled_action service reports to PostHog;
  // scheduled and event-triggered runs are not counted yet.
  routine_created: {
    routineId?: string;
    source: 'new' | 'duplicate';
    triggerType: string;
    /** A single agent's model or agent, or `steps` for a routine with steps. */
    targetKind?: 'agent' | 'model' | 'steps';
  };
  /** A manual Run now the server accepted, not the run's outcome. */
  routine_run: {
    routineId: string;
    trigger: 'manual';
    targetKind?: 'agent' | 'model' | 'steps';
  };
};

export type AppEventNames = keyof AppEvents;