{
  "markdown": "# Outlit SDK\n\nOutlit is the real-time understanding of every customer, the infrastructure agents use to automate customer operations.\n\nThis 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.\n\n## Packages\n\nThis monorepo contains these packages under the `@outlit` scope:\n\n- **[@outlit/core](./packages/core)** - Core SDK functionality and base client\n- **[@outlit/browser](./packages/browser)** - Browser-specific SDK with automatic page view tracking\n- **[@outlit/node](./packages/node)** - Node.js SDK for server-side event tracking\n- **[@outlit/cli](./packages/cli)** - CLI for Outlit customer intelligence\n- **[@outlit/tools](./packages/tools)** - Customer intelligence tool contracts and client helpers for API and agent integrations\n- **[@outlit/pi](./packages/pi)** - Pi package with Outlit customer intelligence tools and skill guidance\n\n## Agent and Crawler Discovery\n\nUse these canonical resources for citations, schema-driven clients, and agent setup instead of copying generated specs or server metadata into this repository:\n\n| Surface | Canonical URL | Purpose |\n|---------|---------------|---------|\n| Developer docs | <https://docs.outlit.ai> | SDK, CLI, API, MCP, and customer context documentation |\n| Docs index for agents | <https://docs.outlit.ai/llms.txt> | Machine-readable map of documentation pages |\n| Product resource index | <https://www.outlit.ai/llms.txt> | Agent-facing map of SDK packages, docs, API contracts, MCP, CLI, Pi, and skills |\n| OpenAPI spec | <https://docs.outlit.ai/openapi.json> | Canonical OpenAPI contract for public API and ingest surfaces |\n| API catalog | <https://www.outlit.ai/.well-known/api-catalog> | Linkset for API, MCP, OAuth, docs, and support discovery |\n| AI catalog | <https://www.outlit.ai/.well-known/ai-catalog.json> | Agentic Resource Discovery catalog for Outlit API, MCP, skills, and SDK resources |\n| MCP Registry listing | <https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.outlit/outlit> | Official MCP Registry search surface for `ai.outlit/outlit` |\n| MCP server metadata | <https://mcp.outlit.ai/.well-known/mcp/server.json> | Runtime metadata for the hosted remote MCP server |\n| MCP server card | <https://mcp.outlit.ai/.well-known/mcp/server-card.json> | Runtime discovery card for the hosted remote MCP server |\n| MCP docs | <https://docs.outlit.ai/ai-integrations/mcp> | Connect remote MCP clients with workspace URLs and OAuth |\n| Agent skills | <https://docs.outlit.ai/ai-integrations/skills> | Official `outlit` and `outlit-sdk` skill installation guidance |\n\nThe hosted MCP server and OAuth metadata live on `mcp.outlit.ai`; this SDK repo is the public package and developer integration surface.\n\n## Installation\n\nChoose the package that matches the integration surface:\n\n| Package | Install | Use when |\n|---------|---------|----------|\n| `@outlit/browser` | `npm install @outlit/browser` | Browser apps, React, Next.js, Vue, Nuxt, SvelteKit, Angular, Astro, and script-tag tracking |\n| `@outlit/node` | `npm install @outlit/node` | Node.js servers, API routes, jobs, webhooks, CLIs, desktop main processes, and native JavaScript runtimes |\n| `@outlit/core` | `npm install @outlit/core` | Lower-level custom SDK implementations that do not need browser or Node runtime helpers |\n| `@outlit/cli` | `npm install -g @outlit/cli` | Terminal access to Outlit customer intelligence and setup workflows |\n| `@outlit/tools` | `npm install @outlit/tools` | Custom API or agent integrations that need typed Outlit tool gateway contracts and client helpers |\n| `@outlit/pi` | `npm install @outlit/pi` | Pi agents that need Outlit customer intelligence tools and skill guidance |\n| Rust crate | `cargo add outlit` | Rust backends, CLIs, and Tauri backends |\n\nTracking SDK examples:\n\n```bash\n# For browser applications\nnpm install @outlit/browser\n\n# For Node.js applications\nnpm install @outlit/node\n\n# For custom implementations\nnpm install @outlit/core\n```\n\n## Quick Start\n\n### Browser\n\n```typescript\nimport { Outlit } from '@outlit/browser'\n\nconst outlit = new Outlit({\n  publicKey: 'pk_xxx',\n  trackPageviews: true,\n  trackForms: true,\n})\n\n// Identify a user\noutlit.user.identify({\n  email: 'user@example.com',\n  traits: { name: 'John Doe' },\n  customerId: 'cust_123', // Your app's account/workspace/customer ID\n  customerTraits: { plan: 'pro' },\n})\n\n// Track events\noutlit.track('button_clicked', {\n  button_id: 'signup',\n  page: '/homepage',\n})\n\n// Track meaningful product activity. Core derives lifecycle stages from\n// ordinary events, including your selected activation event.\noutlit.track('onboarding_completed', { flow: 'self_serve' })\n```\n\n#### Using the singleton API\n\n```typescript\nimport { init, track, user } from '@outlit/browser'\n\n// Initialize once at app startup\ninit({ publicKey: 'pk_xxx' })\n\n// Then use anywhere\ntrack('page_viewed', { page: '/home' })\nuser().identify({\n  email: 'user@example.com',\n  customerId: 'cust_123', // Your app's account/workspace/customer ID\n})\ntrack('subscription_upgraded', { plan: 'pro' })\n```\n\n#### Using with React\n\n```tsx\nimport { OutlitProvider, useOutlit } from '@outlit/browser/react'\n\n// Wrap your app\nfunction App() {\n  return (\n    <OutlitProvider publicKey=\"pk_xxx\">\n      <MyComponent />\n    </OutlitProvider>\n  )\n}\n\n// Use in components\nfunction MyComponent() {\n  const { track } = useOutlit()\n  \n  return (\n    <button onClick={() => track('onboarding_completed')}>\n      Click me\n    </button>\n  )\n}\n```\n\n### Node.js\n\n```typescript\nimport { Outlit } from '@outlit/node'\n\nconst outlit = new Outlit({\n  publicKey: 'pk_xxx',\n})\n\n// Track server-side events (requires identity)\noutlit.track({\n  customerId: 'cust_123', // Your app's account/workspace/customer ID\n  eventName: 'api_request',\n  properties: {\n    endpoint: '/api/users',\n    method: 'GET',\n    status: 200,\n  },\n})\n// `customerId`-only track events are valid immediately.\n// When you later call identify() with the same customerId and an email,\n// Outlit can link that account/workspace to the customer resolved from email.\n\n// Identify a user\noutlit.user.identify({\n  email: 'user@example.com',\n  traits: { plan: 'pro' },\n  customerId: 'cust_123', // Your app's account/workspace/customer ID\n  customerTraits: { plan: 'pro' },\n})\n\n// Track ordinary product events. Billing status comes from verified\n// integrations such as Stripe, not authoritative SDK commands.\noutlit.track({\n  customerId: 'cust_123',\n  eventName: 'subscription_upgraded',\n  properties: { plan: 'pro' },\n})\n\n// Flush events before shutdown\nawait outlit.flush()\n```\n\n## Features\n\n- **Modern TypeScript** - Full TypeScript support with type definitions\n- **Tree-shakeable** - Optimized bundle size with dual ESM/CJS exports\n- **Event Queueing** - Automatic batching and flushing of events\n- **Multi-platform** - Separate packages for browser and Node.js\n- **Auto-tracking** - Automatic page view tracking in browser\n- **Middleware Support** - Easy integration with Express and similar frameworks\n- **Persistent Identity** - User and anonymous ID persistence\n- **High Performance** - Minimal overhead and efficient batching\n- **Type Safe** - Full TypeScript support with strict types\n\n## Examples\n\n- **[Pi agents](./examples/pi-agents)** - Build customer intelligence agents in Pi with `@outlit/pi`\n\n## Development\n\nThis project uses a modern monorepo setup with the following tools:\n\n- **[Bun](https://bun.sh/)** - Fast all-in-one JavaScript runtime and package manager\n- **[Turbo](https://turbo.build/)** - Build system for monorepo orchestration\n- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript\n- **[tsup](https://tsup.egoist.dev/)** - Fast TypeScript bundler\n- **[Biome](https://biomejs.dev/)** - Fast linter and formatter\n- **[Playwright](https://playwright.dev/)** - End-to-end testing\n- **[Changesets](https://github.com/changesets/changesets)** - Version management and changelogs\n\n### Setup\n\n```bash\n# Install dependencies\nbun install\n\n# Build all packages\nbun run build\n\n# Run tests\nbun run test\n\n# Lint code\nbun run lint\n\n# Type check\nbun run typecheck\n\n# Format code\nbun run format\n```\n\n### Project Structure\n\n```\noutlit-sdk/\n├── .github/workflows/   # CI/CD workflows\n├── examples/\n│   └── pi-agents/       # Example Pi agents using @outlit/pi\n├── packages/\n│   ├── browser/         # Browser SDK with React bindings\n│   ├── cli/             # Outlit CLI\n│   ├── core/            # Shared types and utilities\n│   ├── node/            # Node.js SDK\n│   ├── pi/              # Pi package for Outlit tools\n│   ├── tools/           # Customer intelligence tool contracts\n│   └── typescript-config/  # Shared TypeScript configs\n├── package.json         # Root package with workspace config\n├── bun.lock             # Bun lockfile\n├── turbo.json           # Turbo build configuration\n└── biome.json           # Biome linter/formatter config\n```\n\n### Creating a Changeset\n\nWhen making changes that should be released, create a changeset:\n\n```bash\nbunx changeset\n```\n\nThis will prompt you to:\n1. Select which packages are affected\n2. Choose the version bump type (patch, minor, major)\n3. Write a description of the change\n\nThe changeset file will be committed with your PR and used to generate changelogs on release.\n\n## CI/CD\n\n### Workflows\n\n- **CI** (`ci.yml`) - Runs on PRs: lint, typecheck, build, test\n- **Release** (`release.yml`) - Runs on main: publish canary to npm + CDN, create version PR or publish stable releases\n\nStable releases are intentionally separate from SDK source merges. See\n[`docs/release-coordination.md`](docs/release-coordination.md) for the Version Packages checklist\nand the required Core-production-before-stable-SDK order for coordinated contracts.\n\n### Required Secrets\n\nFor maintainers setting up the repository:\n\n| Secret | Description |\n|--------|-------------|\n| `NPM_TOKEN` | npm access token with publish permission for `@outlit` scope |\n| `GCP_CREDENTIALS` | Service account JSON key with Storage Object Admin on `cdn.outlit.ai` bucket |\n\n#### Creating NPM_TOKEN\n\n1. Go to [npmjs.com](https://www.npmjs.com/) and sign in\n2. Navigate to Access Tokens → Generate New Token → Granular Access Token\n3. Set permissions: Read and write for `@outlit` packages\n4. Copy the token and add as `NPM_TOKEN` secret in GitHub\n\n#### Creating GCP_CREDENTIALS\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Navigate to IAM & Admin → Service Accounts\n3. Create a new service account (e.g., `github-actions-deployer`)\n4. Grant \"Storage Object Admin\" role on the `cdn.outlit.ai` bucket\n5. Create a JSON key for the service account\n6. Copy the entire JSON content and add as `GCP_CREDENTIALS` secret in GitHub\n\n### CDN Deployment\n\nThe browser SDK IIFE bundle is deployed to Google Cloud Storage:\n\n| Path | Description |\n|------|-------------|\n| `/canary/outlit.js` | Latest from main branch (5 min cache) |\n| `/stable/outlit.js` | Latest stable release (1 year cache) |\n| `/v{version}/outlit.js` | Immutable versioned release (1 year cache) |\n\n**npm tags:**\n\n| Tag | Description |\n|-----|-------------|\n| `latest` | Stable release (`npm install @outlit/browser`) |\n| `canary` | Latest from main (`npm install @outlit/browser@canary`) |\n\nManual deployment (requires gcloud CLI):\n```bash\ncd packages/browser && bun run deploy:canary   # Deploy to canary\ncd packages/browser && bun run deploy:stable   # Deploy to stable (requires confirmation)\ncd packages/browser && bun run deploy:version  # Deploy versioned release\n```\n\n## Documentation\n\n- [Developer docs](https://docs.outlit.ai)\n- [Browser SDK](https://docs.outlit.ai/tracking/browser/npm)\n- [Node.js SDK](https://docs.outlit.ai/tracking/server/nodejs)\n- [Rust SDK](https://docs.outlit.ai/tracking/server/rust)\n- [API reference](https://docs.outlit.ai/api-reference/introduction)\n- [OpenAPI spec](https://docs.outlit.ai/openapi.json)\n- [MCP integration](https://docs.outlit.ai/ai-integrations/mcp)\n- [Agent skills](https://docs.outlit.ai/ai-integrations/skills)\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\nApache-2.0 - see [LICENSE](./LICENSE) for details.\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/OutlitAI/outlit-sdk/issues)\n- Docs: [Documentation](https://docs.outlit.ai)\n",
  "bytes": 12597,
  "sha": "3e3fb6f61f0ba5d4ba1a8e22bc8df928ebda26c1fc2478b808649d8fc4e7b094",
  "repo_slug": "outlitai/outlit-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_outlit_outlit_51b55254/readme"
}