outseta

Outseta の概要

Outseta は、CRM、認証、請求、カスタマーサポートを統合した、SaaS 創業者向けのオールインワン運用システムです。SaaS 製品の「ビジネスロジック」を担うよう設計されており、開発者は「機能ロジック」に集中できます。

コアアーキテクチャ

1. リレーショナルデータモデル（B2B を優先）

Outseta の CRM は、チームベースの SaaS を標準でサポートするように構成されています。

• Person： Uid で識別される個々のユーザーです。
• Account： 企業またはチームのエンティティです。サブスクリプションと請求はここに紐づきます。
• PersonAccount： Person と Account を関連付ける中間エンティティです。これにより、1 人のユーザーが複数の組織に所属するような複雑な関係を扱えます。
• 信頼できる唯一の情報源： アイデンティティと支払い状況の主要な信頼できる情報源として Outseta を扱ってください。

2. 認証とセキュリティ

• JWT（JSON Web Token）： Outseta はセッション管理に JWT を使用します。Outseta 固有のクレームには名前空間が付いています。sub は Person の Uid で、outseta:accountUid、outseta:planUid、outseta:isPrimary はアカウント／プランのコンテキストを示します。PersonUid／AccountUid／planUid クレームはありません。プランによるアクセス制御には、outseta:planUid を読み取ってください。
• 検証： Outseta の JWKS（JSON Web Key Set） を使用して、サーバー側でトークンを検証してください。キーは /.well-known/jwks から直接取得します。このエンドポイントは固定されているため、署名キーはここから直接読み取ってください（トークンを検証するだけなら、ディスカバリーのラウンドトリップは不要です）。これとは別に、Outseta をサインイン（OIDC）プロバイダーとして統合する場合は、エンドポイントをハードコードせず、/.well-known/openid-configuration から（authorization_endpoint／token_endpoint／userinfo_endpoint／jwks_uri）を検出してください。
• アクセス制限付きコンテンツ： Outseta スクリプトで data-o-* 属性を使用すると、ユーザーのサブスクリプションプランまたはログイン状態に応じて UI 要素を自動的に表示／非表示にできます。

統合パターン

フロントエンド（React）

このツールキットの React テンプレートをコピーするのではなく、公式の @outseta/react パッケージを使用してください。

npm install @outseta/react

OutsetaProvider をレンダリングする前に、アプリのシェルで Outseta のスクリプトを読み込んでください。

<script>
  var o_options = {
    domain: "your-company.outseta.com",
    // Include the widget modules you render: auth, profile, support, emailList, leadCapture.
    load: "auth,profile,support,emailList,leadCapture,nocode",
  };
</script>
<script src="https://cdn.outseta.com/outseta.min.js" data-options="o_options"></script>

認証状態、ウィジェット、アクセス制限付きルート、アドオン購入フローには、パッケージのエクスポートを使用してください。

import {
  OutsetaProvider,
  ProtectedRoute,
  PurchaseAddonButton,
  useOutseta,
} from "@outseta/react";

function Header() {
  const { user, isLoading, openLogin, openSignup, openProfile, logout } = useOutseta();

  if (isLoading) return null;

  return user ? (
    <>
      <button onClick={() => openProfile({ tab: "profile" })}>Profile</button>
      <button onClick={logout}>Logout</button>
    </>
  ) : (
    <>
      <button onClick={() => openSignup()}>Sign up</button>
      <button onClick={() => openLogin()}>Login</button>
    </>
  );
}

export function App() {
  return (
    <OutsetaProvider>
      <Header />
      <ProtectedRoute plans={["plan_uid"]}>
        <PremiumFeature />
      </ProtectedRoute>
      <PurchaseAddonButton addonUid="addon_uid">Buy add-on</PurchaseAddonButton>
    </OutsetaProvider>
  );
}

@outseta/react のエクスポート：

• 認証／ユーザー状態には、OutsetaProvider と useOutseta を使用します。
• ヘッドレス認証／プロフィールコンポーネント：AuthEmbed、AuthButton、LoginButton、SignupButton、ProfileEmbed、ProfileButton、LogoutButton、ProtectedRoute、AuthCta、UpgradeCta、PurchaseAddonButton。
• ヘッドレスのサポート、メーリングリスト、リード獲得用コンポーネント：SupportEmbed、SupportButton、EmailListEmbed、EmailListButton、EmailListForm、LeadCaptureEmbed、LeadCaptureButton。
• Outseta REST API にアクセスするための createClient と、生成済みのバニラ React データフック。

生成された API フックには、外部のデータ取得ライブラリやプロバイダーは必要ありません。マウント時にデータを取得し、refetch を公開します。また、コンポーネント間のキャッシュ、リクエストの重複排除、バックグラウンドでの再取得は意図的に提供していません。ユーザーの bearer accessToken を使用してブラウザー API クライアントを作成し、各フックの request オプションにクライアントを渡してください。

import { createClient, useAccountGetAllAccounts } from "@outseta/react";

const client = createClient({
  subdomain: "your-company",
  accessToken,
});

const { data, error, isLoading, refetch } = useAccountGetAllAccounts(undefined, {
  request: client,
});

Outseta API キーの認証情報をブラウザーコードで公開しないでください。

フロントエンド（ノーコード／ローコードおよびプレーン HTML）

• マジックスクリプト： Outseta ドメイン用に o_options を定義し、アプリのシェルに <script src="https://cdn.outseta.com/outseta.min.js" data-options="o_options"></script> を含めてください。
• ウィジェット： データ属性（例：data-o-auth="1"）またはグローバルオブジェクト Outseta を使ってウィジェットを起動します。
• ライフサイクルイベント： Outseta.on('event', callback) を使用して、ログイン、ログアウト、プロフィールの更新に応答します。
• アクセス制限付きコンテンツ： Outseta スクリプトで data-o-* 属性（例：data-o-anonymous="1"、data-o-authenticated="1"）を使用すると、ユーザーのサブスクリプションプランまたはログイン状態に応じて UI 要素を自動的に表示／非表示にできます。React アプリでは、より信頼性の高い SPA の動作を実現するため、@outseta/react の状態とコンポーネントを優先してください。

バックエンド（Node.js）

このツールキットの Node.js テンプレートをコピーする代わりに、公式の @outseta/node-sdk パッケージを使用してください。

npm install @outseta/node-sdk

このパッケージは、サーバーサイド API クライアント、JWT の検証、Webhook 署名の検証、Express の Webhook ルート、ユーザーアクセストークンの生成、従量課金に対応するヘルパーをエクスポートします。

import {
  createClient,
  createOutsetaWebhookHandler,
  generateAccessToken,
  outsetaWebhookTextParserOptions,
  trackUsage,
  verifyJwt,
} from "@outseta/node-sdk";
import express from "express";

const adminClient = createClient({
  subdomain: process.env.OUTSETA_SUBDOMAIN!,
  apiKey: process.env.OUTSETA_API_KEY!,
  apiSecret: process.env.OUTSETA_API_SECRET!,
});

const payload = await verifyJwt(userAccessToken, {
  subdomain: process.env.OUTSETA_SUBDOMAIN!,
});

const generatedToken = await generateAccessToken(adminClient, "[email protected]");

await trackUsage(adminClient, {
  accountUid: "account_uid",
  addOnUid: "addon_uid",
  amount: 1,
});

const app = express();
app.post(
  "/outseta/webhook",
  express.text(outsetaWebhookTextParserOptions),
  createOutsetaWebhookHandler({
    signingKey: process.env.OUTSETA_WEBHOOK_SIGNING_KEY!,
    async onWebhook(payload) {
      // Handle Activity Notification payload.
    },
  }),
);

バックエンドに関する重要な注意事項：

• API キーの認証情報はサーバー上でのみ使用してください。
• ユーザー単位のサーバーリクエストには、{ subdomain, accessToken } を指定してクライアントを作成してください。
• Webhook 署名は、正確な未加工のリクエスト本文に対して検証してください。Express では、createOutsetaWebhookHandler の前に Webhook ルートで express.text(outsetaWebhookTextParserOptions) を使用してください。
• 生成された REST API 関数をすべて使用する場合は、@outseta/api-client を使用し、必要に応じて withClient(client) で SDK クライアントを渡してください。

REST API

• サーバー間通信、カスタムオンボーディング、または管理タスクに使用します。
• ベース URL：https://your-domain.outseta.com/api/v1/

REST API を参照してください。

開発者向けの主要な概念

• Uid： Outseta 内のあらゆるエンティティを識別する一意の ID です。ローカルデータベース（例：Convex）では、これを外部キーとして使用してください。
• Account Stage： 顧客のライフサイクルにおける段階（例：トライアル中、有効、支払期限超過、キャンセル済み）を追跡します。
• Embeds： Outseta がオーバーレイウィジェット（サインアップ、ログイン、プロフィール、ヘルプデスク）を指す用語です。

MCP サーバー

Outseta MCP サーバー（https://agent.outseta.com/mcp、OAuth ログイン）は、最新のドキュメントに基づいた連携を可能にし、実際のアカウントデータを確認または変更できます。3 つのツールを提供します。

ツール	ネットワーク	用途
bash	なし	ナレッジベース（/root/docs/kb）と REST API リファレンス（/root/docs/api）を検索する
javascript_read	アカウント API への GET/HEAD	ユーザー、アカウント、サブスクリプション、プラン、メールリストを読み取る。書き込みを検証する
javascript_write	アカウント API への POST/PUT/PATCH	レコードを作成および更新する。writeSummary が必要です。DELETE は利用できません。

調査ワークフロー

1. 概念と手順：grep -ril "<term>" /root/docs/kb を実行し、記事を読んでください。ワークスペースのパスではなく、フロントマターに記載された sourceArticleUrl を引用してください。
2. REST の規約：/root/docs/api/README.md では、Authorization: Outseta {key}:{secret} 方式、items/metadata のリストエンベロープ、0 から始まるページインデックスとしての offset、limit の上限（100、子フィールドを要求する場合は 25）、フィルタリング演算子、Webhook アクティビティの一覧について説明しています。
3. エンドポイントの詳細：エンドポイントごとに 1 つのページがあります。例：/root/docs/api/crm--person-getallpeople.md。**Client call：**の行には、JavaScript ツールで使用する生成関数と引数の順序が記載されています。正確な型は /root/outseta.d.ts にあります。ファイル全体を読むのではなく、grep で検索してください。

アカウント操作

import { createClient, personGetAllPeople, personUpdatePerson } from "/root/outseta.js";

const client = createClient(); // uses the MCP session's auth
const { items, metadata } = (
  await personGetAllPeople({ Email: "[email protected]", fields: "Uid,Email,LastName" }, { client })
).data;

// javascript_write only, with a writeSummary such as "Set LastName to Hopper on person <Uid>":
await personUpdatePerson(items[0].Uid, { LastName: "Hopper" }, { client });

• client("/api/v1/...") より、生成された関数を優先してください。{ client } は常に最後の options 引数に指定します。
• 読み取ってから書き込んでください。変更対象の正確なレコードを照会し、対象範囲をユーザーに示してから、一括または取り消せない書き込みを行う前に確認してください。
• MCP から削除することはできません。REST の DELETE エンドポイントまたは Outseta の UI を案内してください。

埋め込み例（純粋な JS/HTML のみ）

これらのテンプレートは、React を使わない連携やローコード連携向けに、このツールキット内に残されています。

• ログイン： 標準のログインウィジェットです。login.html を参照してください。
• サインアップ： デフォルト値を任意で指定できる登録ウィジェットです。signup.html を参照してください。
• プロフィール： ユーザープロフィールとサブスクリプションを管理します。profile.html を参照してください。
• ログアウト： ログアウトボタンとリンクのパターンです。logout.html を参照してください。
• リード獲得： カスタムのリード獲得フォームです。leadcapture.html を参照してください。
• メールリスト： メールリスト登録フォームです。emaillist.html を参照してください。
• サポート： サポートチケットとナレッジベースの連携です。support.html を参照してください。