SYSTEM INSTRUCTION: ThriveStack Telemetry Implementation Spec

Version: 2.1
Target Audience: AI Coding Assistants (Claude, Gemini, Cursor, etc.)

1. CORE MISSION

You are tasked with instrumenting a web application with ThriveStack Product Telemetry. This telemetry powers "Vibe Analytics" — an AI-driven growth engine. You must follow the schemas, naming conventions, and structural rules below with 100% precision.

2. PREREQUISITES (STATE DISCOVERY)

Before writing code, you MUST locate the following variables in the existing codebase:

userId: The authenticated user's unique UUID (e.g., user.id, session.userId).
groupId: The organization/account/workspace unique UUID (e.g., org.id, workspaceId).

CRITICAL: If you cannot find a groupId, you must ask the user for the variable name representing the Account/Organization ID. Do not proceed with fake data.

3. INITIALIZATION (ROOT LAYOUT)

Add the following script to the <head> of the root layout file (e.g., layout.tsx, _app.tsx, index.html).

<script
  src="https://ts-script.app.thrivestack.ai/latest/thrivestack.js"
  api-key="process.env.THRIVESTACK_API_KEY"
  source="product">
</script>

RULES:

Global object: thriveStack (lowercase 's').
api-key MUST come from an environment variable.
source is always "product".

4. MANDATORY EVENT SCHEMAS

Every call must be wrapped in an ARRAY: method([{...}]).

A. identify()

When: Immediately after login or signup.

thriveStack.identify([{
  "user_id": userId,
  "traits": {
    "user_email": user.email,
    "user_name": user.name
  },
  "timestamp": new Date().toISOString()
}]);

B. group()

When: Immediately after identify(). Establishes the Account context.

thriveStack.group([{
  "user_id": userId,
  "group_id": groupId,
  "traits": {
    "group_type": "Account",
    "account_domain": org.domain,
    "account_name": org.name,
    "plan_id": org.planId,
    "plan_name": org.planName
  },
  "context": {
    "group_id": groupId,
    "group_type": "Account"
  },
  "timestamp": new Date().toISOString()
}]);

C. track() - The Big 7

Every track() call REQUIRES the context block containing group_id.

Event Name	When to Fire
`signed_up`	New user registration success.
`account_created`	New organization/workspace creation success.
`onboarding_step_completed`	Completion of a setup wizard step.
`invite_sent`	Invitation sent to a teammate.
`user_added_to_account`	User joins an account via invite/SSO.
`account_added_user`	Admin adds a user to an account.
`feature_used`	Core product action (e.g., `report_generated`).

Example: account_added_user

thriveStack.track([{
  "event_name": "account_added_user",
  "user_id": adminId,
  "properties": {
    "user_email": adminEmail,
    "added_user_id": newUserId,
    "role": "member"
  },
  "context": {
    "group_id": groupId,
    "group_type": "Account"
  },
  "timestamp": new Date().toISOString()
}]);

5. IMPLEMENTATION CHECKLIST FOR AI

Verify Global: Check typeof thriveStack !== 'undefined' before calling.
Array Wrapper: Ensure every call is method([{...}]).
Context Block: Ensure context: { group_id, group_type: "Account" } is on every track() call.
Snake Case: Use snake_case for event names and property keys.
No Blocking: Fire-and-forget. Do not await telemetry calls.

6. TROUBLESHOOTING / HARD RULES

NEVER use group_type: "Organization". It must be "Account".
NEVER generate random UUIDs for group_id. Use the app's existing state.
ALWAYS call identify() before group().
ALWAYS call group() before track() in a session flow.