Outlit

Outlit SDK

Outlit は、カスタマーサクセスチームがロングテール収益を守り、拡大できるよう支援します。顧客データを接続して、解約リスクや拡大の機会を監視し、根拠を添えた注目項目をチームに提示します。

ガイド付きセットアップと最初の注目項目については、製品ガイドをご覧ください。プログラムによるアクセスについては、開発者およびエージェント向けガイドをご利用ください。

このリポジトリには、Outlit の公開 SDK および開発者向け統合パッケージ（ブラウザー、サーバー、CLI、ツールコントラクト、Pi）が含まれています。これらのパッケージを使用して、顧客シグナルを Outlit に送信し、エージェントのワークフローから顧客のコンテキストを照会できます。ホスト型リモート MCP サーバーの実装は含まれていません。MCP、API、エージェントのメタデータには、以下の Outlit が管理する正規の検出エンドポイントをご利用ください。

パッケージ

このモノレポには、@outlit スコープで次のパッケージが含まれています。

• @outlit/core - SDK のコア機能と基本クライアント
• @outlit/browser - ページビューを自動追跡するブラウザー向け SDK
• @outlit/node - サーバー側イベント追跡用の Node.js SDK
• @outlit/cli - Outlit の顧客インテリジェンス用 CLI
• @outlit/tools - API およびエージェント統合用の顧客インテリジェンスツールのコントラクトとクライアントヘルパー
• @outlit/pi - Outlit の顧客インテリジェンスツールとスキルガイダンスを備えた Pi パッケージ

エージェントおよびクローラー向けの検出情報

生成された仕様やサーバーのメタデータをこのリポジトリにコピーする代わりに、引用、スキーマ駆動のクライアント、エージェントのセットアップには、以下の正規リソースをご利用ください。

サーフェス	正規 URL	用途
ドキュメント	https://docs.outlit.ai	製品ガイドに加え、SDK、CLI、API、MCP、顧客コンテキストのドキュメント
エージェント向けドキュメントインデックス	https://docs.outlit.ai/llms.txt	ドキュメントページの機械可読なマップ
製品リソースインデックス	https://www.outlit.ai/llms.txt	SDK パッケージ、ドキュメント、API コントラクト、MCP、CLI、Pi、スキルのエージェント向けマップ
OpenAPI 仕様	https://docs.outlit.ai/openapi.json	公開 API および取り込みサーフェスの正規 OpenAPI コントラクト
API カタログ	https://www.outlit.ai/.well-known/api-catalog	API、MCP、OAuth、ドキュメント、サポートの検出用リンクセット
AI カタログ	https://www.outlit.ai/.well-known/ai-catalog.json	Outlit API、MCP、スキル、SDK リソースのエージェント型リソース検出カタログ
MCP Registry の掲載情報	https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.outlit/outlit	ai.outlit/outlit の公式 MCP Registry 検索ページ
MCP サーバーのメタデータ	https://mcp.outlit.ai/.well-known/mcp/server.json	ホスト型リモート MCP サーバーのランタイムメタデータ
MCP サーバーカード	https://mcp.outlit.ai/.well-known/mcp/server-card.json	ホスト型リモート MCP サーバーのランタイム検出カード
MCP ドキュメント	https://docs.outlit.ai/ai-integrations/mcp	ワークスペース URL と OAuth を使用してリモート MCP クライアントを接続する方法
エージェントスキル	https://docs.outlit.ai/ai-integrations/skills	公式 outlit および outlit-sdk スキルのインストールガイド

ホスト型 MCP サーバーと OAuth のメタデータは mcp.outlit.ai にあります。この SDK リポジトリは、公開パッケージと開発者向け統合のサーフェスです。

インストール

連携先に合ったパッケージを選択してください。

パッケージ	インストール	使用場面
@outlit/browser	npm install @outlit/browser	ブラウザーアプリ、React、Next.js、Vue、Nuxt、SvelteKit、Angular、Astro、スクリプトタグによるトラッキング
@outlit/node	npm install @outlit/node	Node.js サーバー、API ルート、ジョブ、Webhook、CLI、デスクトップのメインプロセス、ネイティブ JavaScript ランタイム
@outlit/core	npm install @outlit/core	ブラウザーや Node のランタイムヘルパーを必要としない、低レベルのカスタム SDK 実装
@outlit/cli	npm install -g @outlit/cli	Outlit の顧客インテリジェンスやセットアップのワークフローにターミナルからアクセスする場合
@outlit/tools	npm install @outlit/tools	型付けされた Outlit ツールゲートウェイのコントラクトとクライアントヘルパーを必要とするカスタム API またはエージェントの連携
@outlit/pi	npm install @outlit/pi	Outlit の顧客インテリジェンスツールとスキルガイダンスを必要とする Pi エージェント
Rust crate	cargo add outlit	Rust バックエンド、CLI、Tauri バックエンド

トラッキング SDK の例：

# For browser applications
npm install @outlit/browser

# For Node.js applications
npm install @outlit/node

# For custom implementations
npm install @outlit/core

クイックスタート

ブラウザー

import { Outlit } from '@outlit/browser'

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

// Identify a user
outlit.user.identify({
  email: '[email protected]',
  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' })

シングルトン 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: '[email protected]',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
})
track('subscription_upgraded', { plan: 'pro' })

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: '[email protected]',
  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()

機能

• モダンな TypeScript - 型定義による TypeScript の完全なサポート
• ツリーシェイク可能 - ESM/CJS のデュアルエクスポートによりバンドルサイズを最適化
• イベントのキューイング - イベントを自動的にバッチ処理してフラッシュ
• マルチプラットフォーム - ブラウザー用と Node.js 用の個別パッケージ
• 自動トラッキング - ブラウザーでページビューを自動トラッキング
• ミドルウェアのサポート - Express などのフレームワークと簡単に連携
• ID の永続化 - ユーザー ID と匿名 ID を永続化
• 高パフォーマンス - オーバーヘッドを最小限に抑え、効率的にバッチ処理
• 型安全 - 厳密な型による TypeScript の完全なサポート

例

• Pi エージェント - @outlit/pi を使って Pi で顧客インテリジェンスエージェントを構築

開発

このプロジェクトでは、次のツールを使用するモダンなモノレポ構成を採用しています。

• Bun - 高速なオールインワン JavaScript ランタイム兼パッケージマネージャー
• Turbo - モノレポのオーケストレーション用ビルドシステム
• TypeScript - 型安全な JavaScript
• tsup - 高速な TypeScript バンドラー
• Biome - 高速なリンター兼フォーマッター
• Playwright - エンドツーエンドテスト
• Changesets - バージョン管理と変更履歴

セットアップ

# 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

プロジェクト構成

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

Changeset の作成

リリース対象となる変更を加えた場合は、changeset を作成してください。

bunx changeset

次の操作が求められます。

1. 影響を受けるパッケージを選択する
2. バージョンの更新種別（patch、minor、major）を選択する
3. 変更内容を記述する

changeset ファイルは PR とともにコミットされ、リリース時の変更履歴の生成に使用されます。

CI/CD

ワークフロー

• CI（ci.yml）- PR で実行：lint、typecheck、build、test
• リリース（release.yml）- main で実行：canary を npm と CDN に公開し、バージョン PR を作成するか、安定版を公開
• CDN 認証の検証（verify-cdn-auth.yml）- 手動実行のみ：Workload Identity Federation の交換と CDN の読み取りアクセスを確認します。省略可能な verify_write 入力を指定すると、__compliance_checks/ 配下に小さなテストオブジェクトを 1 つ書き込み、その後削除します

安定版リリースは、意図的に SDK のソース変更のマージとは切り離されています。協調したコントラクトにおける Version Packages のチェックリストと、Core の本番反映を安定版 SDK より先に行う必要がある順序については、 docs/release-coordination.md を参照してください。

必要なシークレット

リポジトリをセットアップするメンテナー向け：

シークレット	説明
NPM_TOKEN	@outlit スコープへの公開権限を持つ npm アクセストークン

CDN へのデプロイでは、保存されたサービスアカウントキーの代わりに Workload Identity Federation を使用して Google Cloud に認証します。メンテナーは、リポジトリの変数を設定します。

変数	説明
GCP_WORKLOAD_IDENTITY_PROVIDER	WIF プロバイダーの完全なリソース名（projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>）
GCP_SERVICE_ACCOUNT	cdn.outlit.ai バケットに対する Storage Object Admin 権限を持つデプロイ用サービスアカウントのメールアドレス

NPM_TOKEN の作成

1. npmjs.com にアクセスしてサインインします
2. Access Tokens → Generate New Token → Granular Access Token の順に移動します
3. 権限を設定します：@outlit パッケージへの読み取りおよび書き込み
4. トークンをコピーし、GitHub の NPM_TOKEN シークレットとして追加します

GCP Workload Identity のセットアップ

1. Google Cloud Console にアクセスします
2. IAM & Admin → Service Accounts の順に移動します
3. デプロイ用サービスアカウント（github-actions-cdn-deploy）を使用します
4. cdn.outlit.ai バケットに「Storage Object Admin」ロールを付与します
5. このリポジトリ専用の Workload Identity Pool を作成し、GitHub 用の OIDC プロバイダーを設定します（issuer は https://token.actions.githubusercontent.com）。属性条件で、このリポジトリの不変 ID と、refs/heads/main 上の release／verify-cdn-auth ワークフローに制限します
6. プールの attribute.repository_id principalSet に、サービスアカウント上で roles/iam.workloadIdentityUser を付与します
7. リポジトリ変数として GCP_WORKLOAD_IDENTITY_PROVIDER と GCP_SERVICE_ACCOUNT を追加します

サービスアカウントキー JSON は作成も GitHub への保存も行いません。

CDN デプロイ

ブラウザー SDK の IIFE バンドルは Google Cloud Storage にデプロイされます。

パス	説明
/canary/outlit.js	main ブランチの最新バージョン（5 分間キャッシュ）
/stable/outlit.js	最新の安定版リリース（1 年間キャッシュ）
/v{version}/outlit.js	不変のバージョン付きリリース（1 年間キャッシュ）

npm タグ：

タグ	説明
latest	安定版リリース（npm install @outlit/browser）
canary	main の最新バージョン（npm install @outlit/browser@canary）

手動デプロイ（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

ドキュメント

• 開発者向けドキュメント
• ブラウザー SDK
• Node.js SDK
• Rust SDK
• API リファレンス
• OpenAPI 仕様
• MCP 連携
• エージェントスキル

貢献

皆さまからの貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

Apache-2.0 — 詳細についてはLICENSEをご覧ください。

サポート

• 問題の報告：GitHub Issues
• ドキュメント：ドキュメント