Outlit SDK

Outlit is the real-time understanding of every customer, the infrastructure agents use to automate customer operations.

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 - Core SDK functionality and base client
• @outlit/browser - Browser-specific SDK with automatic page view tracking
• @outlit/node - Node.js SDK for server-side event tracking
• @outlit/cli - CLI for Outlit customer intelligence
• @outlit/tools - Customer intelligence tool contracts and client helpers for API and agent integrations
• @outlit/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 (
    <OutlitProvider publicKey="pk_xxx">
      <MyComponent />
    </OutlitProvider>
  )
}

// Use in components
function MyComponent() {
  const { track } = useOutlit()
  
  return (
    <button onClick={() => track('onboarding_completed')}>
      Click me
    </button>
  )
}

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 - Build customer intelligence agents in Pi with @outlit/pi

Development

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

• Bun - Fast all-in-one JavaScript runtime and package manager
• Turbo - Build system for monorepo orchestration
• TypeScript - Type-safe JavaScript
• tsup - Fast TypeScript bundler
• Biome - Fast linter and formatter
• Playwright - End-to-end testing
• 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

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:

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 GCP_CREDENTIALS

1. Go to Google Cloud Console
2. Navigate to IAM & Admin → Service Accounts
3. Create a new service account (e.g., github-actions-deployer)
4. Grant "Storage Object Admin" role on the cdn.outlit.ai bucket
5. Create a JSON key for the service account
6. Copy the entire JSON content and add as GCP_CREDENTIALS secret in GitHub

CDN Deployment

The browser SDK IIFE bundle is deployed to Google Cloud Storage:

npm tags:

Manual deployment (requires gcloud CLI):

cd packages/browser && bun run deploy:canary   # Deploy to canary
cd packages/browser && bun run deploy:stable   # Deploy to stable (requires confirmation)
cd packages/browser && bun run deploy:version  # Deploy versioned release

Documentation

• Developer docs
• Browser SDK
• Node.js SDK
• Rust SDK
• API reference
• OpenAPI spec
• MCP integration
• Agent skills

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Apache-2.0 - see LICENSE for details.

Support

• Issues: GitHub Issues
• Docs: Documentation