outlit-sdk

Integrate Outlit SDK for customer context for agents. Triggers when users need to add Outlit to any web framework (React, Next.js, Vue, Nuxt, Svelte, Angular, Astro), server runtime (Node.js, Express, Fastify), desktop app (Tauri, Electron), or need help with Outlit event tracking, user identity, consent management, analytics migration, activation events, billing lifecycle, or troubleshooting existing Outlit installations.

# Outlit SDK Integration

Decision-tree-driven guide for integrating Outlit customer journey tracking. Detects what it can from the codebase, asks only what it must, and links to official docs for implementation details.

## Branching Check

Before anything else, check if Outlit is already installed:

1. Look for `@outlit/browser`, `@outlit/node`, or `outlit` (Rust crate) in `package.json` or `Cargo.toml`
2. If **not installed** -> go to [Phase 1: Quick Connect](#phase-1-quick-connect)
3. If **already installed** -> go to [Already Installed](#already-installed)

## Already Installed

Ask the user what they need help with:

- **Add event tracking** -> Run detection, then go to [Decision 7: Event Tracking](#decision-7-event-tracking). Fetch the relevant framework doc from the [Doc URL Map](#doc-url-map) for implementation patterns.
- **Add/change auth integration** -> Run detection, then go to [Decision 3: Auth & Identity](#decision-3-auth--identity). Fetch the framework doc and [identity resolution](https://docs.outlit.ai/concepts/identity-resolution) doc.
- **Add consent management** -> Go to [Decision 2: Consent Stance](#decision-2-consent-stance). Fetch the framework doc's consent section.
- **Add server-side tracking** -> Go to [Decision 1: App Type & SDK](#decision-1-app-type--sdk-package) for the server package, then fetch the [Node.js](https://docs.outlit.ai/tracking/server/nodejs) or [Rust](https://docs.outlit.ai/tracking/server/rust) doc.
- **Add billing/Stripe integration** -> Go to [Decision 6: Billing Integration](#decision-6-billing-integration). Fetch the [customer journey](https://docs.outlit.ai/concepts/customer-journey) doc.
- **Add activation tracking** -> Go to [Decision 5: Activation Event](#decision-5-activation-event). Fetch the [customer journey](https://docs.outlit.ai/concepts/customer-journey) doc.
- **Migrate from other analytics** -> Run detection, then go to [Decision 4: Existing Analytics](#decision-4-existing-analytics-strategy).
- **Debug/troubleshoot** -> Go to [Troubleshooting](#troubleshooting).

## Phase 1: Quick Connect

Goal: get events flowing in ~2 minutes so the user sees "Connected" on their Outlit onboarding screen. Zero user decisions required.

### Step 1: Detect Framework & Package Manager

Use glob/grep to check:

- **Framework:** Check `package.json` dependencies for `next`, `vue`, `nuxt`, `react`, `svelte`, `@sveltejs/kit`, `@angular/core`, `astro`, `express`, `fastify`. Check for `Cargo.toml` with `tauri` or `outlit`.
- **Package manager:** Check for `bun.lockb` (bun), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `package-lock.json` (npm). Use the first match found.

### Step 2: Install SDK

Based on detected framework:

- Browser app (React, Next.js, Vue, Nuxt, Svelte, Angular, Astro) -> `@outlit/browser`
- Server app (Express, Fastify, Node.js) -> `@outlit/node`
- Tauri -> `outlit` Rust crate via `cargo add outlit`
- Electron -> `@outlit/browser`

Install using the detected package manager.

### Step 3: Add Public Key

Ask the user for their Outlit public key. They get it from **Outlit dashboard -> Settings -> Website Tracking** or from the onboarding screen.

Add to environment variables with the correct framework prefix:

| Framework | Env var |
|-----------|---------|
| Next.js | `NEXT_PUBLIC_OUTLIT_KEY` |
| Vite (Vue, Svelte, React+Vite) | `VITE_OUTLIT_KEY` |
| Create React App | `REACT_APP_OUTLIT_KEY` |
| Nuxt | `NUXT_PUBLIC_OUTLIT_KEY` |
| Angular | Add to `environment.ts` |
| Astro | `PUBLIC_OUTLIT_KEY` |
| Server apps | `OUTLIT_KEY` |

### Step 4: Minimal Setup

Fetch the framework-specific doc from the [Doc URL Map](#doc-url-map) and implement only the minimal setup — provider/init with just the `publicKey`, no auth, no consent, no custom events.

For React-based frameworks this means wrapping the app with `OutlitProvider`. For Vue it means installing the `OutlitPlugin`. For server apps it means creating an Outlit instance.

### Step 5: Verify Connection

Tell the user to:

1. Run their dev server
2. Open the app in a browser
3. Check the Outlit onboarding screen for the **"Connected"** badge
4. Or check DevTools -> Network for requests to `app.outlit.ai/api/i/v1/...` returning 200

Once connected, ask: **"Events are flowing. Ready to set up the full integration?"**

If yes -> continue to Phase 2. If no -> they can come back later (the skill will detect the existing install).

## Phase 2: Full Integration

Run the full detection first, then walk through each decision.

### Full Detection

Use grep/glob to detect all of the following before starting the decision tree:

| Signal | How to detect |
|--------|--------------|
| Auth provider | Deps: `@clerk/nextjs`, `@clerk/clerk-react`, `next-auth`, `@auth/core`, `@supabase/auth-helpers-nextjs`, `@supabase/ssr`, `@auth0/auth0-react`, `@auth0/nextjs-auth0`, `firebase`, `@firebase/auth` |
| Billing provider | Deps: `stripe`, `@stripe/stripe-js`, `@paddle/paddle-js`, `chargebee` |
| Existing analytics | Deps: `posthog-js`, `@posthog/node`, `@amplitude/analytics-browser`, `@amplitude/analytics-node`, `mixpanel-browser`, `@segment/analytics-next`, `@segment/analytics-node` |
| Analytics abstraction | Grep for files named `analytics.ts`, `analytics.js`, `tracking.ts`, `tracking.js` in `lib/`, `utils/`, `helpers/`, `services/` that import 2+ analytics libraries |
| EU/consent signals | Deps: `cookiebot`, `@onetrust/*`, `cookie-consent`, or grep for existing consent/cookie banner components |
| App type | Deps: `@tauri-apps/api`, `electron`, `react-native` |
| Activation patterns | Grep for onboarding routes/components, "first" resource creation handlers, invite flows |

Present a summary of what was detected to the user before proceeding.

### Decision 1: App Type & SDK Package

Auto-resolved from Phase 1 detection. If hybrid (e.g., Next.js with API routes that need server tracking), install both `@outlit/browser` and `@outlit/node`.

- Electron -> `@outlit/browser`
- Tauri -> `outlit` Rust crate
- React Native -> `@outlit/browser` (uses fingerprint instead of cookies)

### Decision 2: Consent Stance

| Detection | Recommendation |
|-----------|---------------|
| Existing CMP/cookie banner library | `autoTrack: false`, integrate with their existing CMP's consent callback to call `enableTracking()` |
| EU signals but no CMP | `autoTrack: false`, mention they need a consent solution but don't build one unless asked |
| No EU signals | `autoTrack: true` — simpler, uses cookies immediately |

**Always explain the tradeoff:** `autoTrack: true` starts tracking with cookies immediately. `autoTrack: false` waits until `enableTracking()` is called after user consent.

Fetch the relevant framework doc for consent implementation patterns.

### Decision 3: Auth & Identity

| Detection | Recommendation |
|-----------|---------------|
| React/Vue with OutlitProvider/OutlitPlugin | Pass `user` prop with `{ email, userId }` after auth resolves. No manual `identify()` needed. |
| Vanilla JS / script tag | Call `outlit.identify({ email, userId })` client-side right after auth completes |
| Server-only (Node/Rust) | Call `outlit.identify()` server-side for event attribution |

**Critical:** Client-side `identify()` (or the `user` prop) links the anonymous cookie/visitorId to a real person. This must happen after the auth flow completes. Server-side `identify()` is for attributing server events to a known user, but doesn't link browsing history.

If an auth provider was detected, fetch the framework doc and the [identity resolution](https://docs.outlit.ai/concepts/identity-resolution) doc for the specific auth provider pattern.

### Decision 4: Existing Analytics Strategy

| Detection | Recommendation |
|-----------|---------------|
| Existing analytics abstraction (e.g., `lib/analytics.ts` wrapping PostHog + Amplitude) | Add Outlit as another provider inside the existing abstraction |
| Scattered direct calls (e.g., `posthog.capture()` in 15 files) | Tell the user: "I fo