Outlit

Outlit SDK

Outlit helps customer-success teams protect and grow long-tail revenue. It connects customer data, monitors for churn risk and expansion opportunities, and brings attention items with supporting evidence to your team.

Start with the product guides for guided setup and your first attention item. For programmatic access, use the developer and agent guide.

This repository contains the public SDK and developer integration packages for Outlit: browser, server, CLI, tool contract, and Pi packages for sending customer signals to Outlit and querying customer context from agent workflows. It is not the hosted remote MCP server implementation; use the canonical Outlit-owned discovery endpoints below for MCP, API, and agent metadata.

Packages

This monorepo contains these packages under the @outlit scope:

• [@outlit/core](./packages/core) - Core SDK functionality and base client
• [@outlit/browser](./packages/browser) - Browser-specific SDK with automatic page view tracking
• [@outlit/node](./packages/node) - Node.js SDK for server-side event tracking
• [@outlit/cli](./packages/cli) - CLI for Outlit customer intelligence
• [@outlit/tools](./packages/tools) - Customer intelligence tool contracts and client helpers for API and agent integrations
• [@outlit/pi](./packages/pi) - Pi package with Outlit customer intelligence tools and skill guidance

Agent and Crawler Discovery

Use these canonical resources for citations, schema-driven clients, and agent setup instead of copying generated specs or server metadata into this repository:

The hosted MCP server and OAuth metadata live on mcp.outlit.ai; this SDK repo is the public package and developer integration surface.

Installation

Choose the package that matches the integration surface:

Tracking SDK examples:

# For browser applications

npm install @outlit/browser

For Node.js applications

npm install @outlit/node

For custom implementations

npm install @outlit/core

Quick Start

Browser

import { Outlit } from '@outlit/browser'

const outlit = new Outlit({ publicKey: 'pk_xxx', trackPageviews: true, trackForms: true, })

// Identify a user outlit.user.identify({ email: 'user@example.com', traits: { name: 'John Doe' }, customerId: 'cust_123', // Your app's account/workspace/customer ID customerTraits: { plan: 'pro' }, })

// Track events outlit.track('button_clicked', { button_id: 'signup', page: '/homepage', })

// Track meaningful product activity. Core derives lifecycle stages from // ordinary events, including your selected activation event. outlit.track('onboarding_completed', { flow: 'self_serve' })

Using the singleton API

import { init, track, user } from '@outlit/browser'

// Initialize once at app startup init({ publicKey: 'pk_xxx' })

// Then use anywhere track('page_viewed', { page: '/home' }) user().identify({ email: 'user@example.com', customerId: 'cust_123', // Your app's account/workspace/customer ID }) track('subscription_upgraded', { plan: 'pro' })

Using with React

import { OutlitProvider, useOutlit } from '@outlit/browser/react'

// Wrap your app function App() { return (

) }

// Use in components function MyComponent() { const { track } = useOutlit()

return ( track('onboarding_completed')}> Click me

) }

Node.js

import { Outlit } from '@outlit/node'

const outlit = new Outlit({ publicKey: 'pk_xxx', })

// Track server-side events (requires identity) outlit.track({ customerId: 'cust_123', // Your app's account/workspace/customer ID eventName: 'api_request', properties: { endpoint: '/api/users', method: 'GET', status: 200, }, }) // customerId-only track events are valid immediately. // When you later call identify() with the same customerId and an email, // Outlit can link that account/workspace to the customer resolved from email.

// Identify a user outlit.user.identify({ email: 'user@example.com', traits: { plan: 'pro' }, customerId: 'cust_123', // Your app's account/workspace/customer ID customerTraits: { plan: 'pro' }, })

// Track ordinary product events. Billing status comes from verified // integrations such as Stripe, not authoritative SDK commands. outlit.track({ customerId: 'cust_123', eventName: 'subscription_upgraded', properties: { plan: 'pro' }, })

// Flush events before shutdown await outlit.flush()

Features

• Modern TypeScript - Full TypeScript support with type definitions
• Tree-shakeable - Optimized bundle size with dual ESM/CJS exports
• Event Queueing - Automatic batching and flushing of events
• Multi-platform - Separate packages for browser and Node.js
• Auto-tracking - Automatic page view tracking in browser
• Middleware Support - Easy integration with Express and similar frameworks
• Persistent Identity - User and anonymous ID persistence
• High Performance - Minimal overhead and efficient batching
• Type Safe - Full TypeScript support with strict types

Examples

• [Pi agents](./examples/pi-agents) - Build customer intelligence agents in Pi with @outlit/pi

Development

This project uses a modern monorepo setup with the following tools:

• [Bun](https://bun.sh/) - Fast all-in-one JavaScript runtime and package manager
• [Turbo](https://turbo.build/) - Build system for monorepo orchestration
• [TypeScript](https://www.typescriptlang.org/) - Type-safe JavaScript
• [tsup](https://tsup.egoist.dev/) - Fast TypeScript bundler
• [Biome](https://biomejs.dev/) - Fast linter and formatter
• [Playwright](https://playwright.dev/) - End-to-end testing
• [Changesets](https://github.com/changesets/changesets) - Version management and changelogs

Setup

# Install dependencies

bun install

Build all packages

bun run build

Run tests

bun run test

Lint code

bun run lint

Type check

bun run typecheck

Format code

bun run format

Project Structure

outlit-sdk/

├── .github/workflows/ # CI/CD workflows ├── examples/ │ └── pi-agents/ # Example Pi agents using @outlit/pi ├── packages/ │ ├── browser/ # Browser SDK with React bindings │ ├── cli/ # Outlit CLI │ ├── core/ # Shared types and utilities │ ├── node/ # Node.js SDK │ ├── pi/ # Pi package for Outlit tools │ ├── tools/ # Customer intelligence tool contracts │ └── typescript-config/ # Shared TypeScript configs ├── package.json # Root package with workspace config ├── bun.lock # Bun lockfile ├── turbo.json # Turbo build configuration └── biome.json # Biome linter/formatter config

Creating a Changeset

When making changes that should be released, create a changeset:

bunx changeset

This will prompt you to:

1. Select which packages are affected
2. Choose the version bump type (patch, minor, major)
3. Write a description of the change

The changeset file will be committed with your PR and used to generate changelogs on release.

CI/CD

Workflows

• CI (ci.yml) - Runs on PRs: lint, typecheck, build, test
• Release (release.yml) - Runs on main: publish canary to npm + CDN, create version PR or publish stable releases
• Verify CDN Auth (verify-cdn-auth.yml) - Manual only: checks Workload Identity Federation exchange and CDN read access; the optional verify_write input writes then deletes one tiny test object under __compliance_checks/

Stable releases are intentionally separate from SDK source merges. See docs/release-coordination.md for the Version Packages checklist and the required Core-production-before-stable-SDK order for coordinated contracts.

Required Secrets

For maintainers setting up the repository:

CDN deploys authenticate to Google Cloud via Workload Identity Federation instead of a stored service account key. Maintainers configure these repository variables:

Creating NPM_TOKEN

1. Go to npmjs.com and sign in
2. Navigate to Access Tokens → Generate New Token → Granular Access Token
3. Set permissions: Read and write for @outlit packages
4. Copy the token and add as NPM_TOKEN secret in GitHub

Creating the GCP Workload Identity setup

1. Go to Google Cloud Console
2. Navigate to IAM & Admin → Service Accounts
3. Use the deploy service account (github-actions-cdn-deploy)
4. Grant "Storage Object Admin" role on the cdn.outlit.ai bucket
5. Create a dedicated Workload Identity Pool for this repo with an OIDC provider for GitHub (issuer `https://token.actions.githubusercontent.