primitive

Primitive SDK

Primitive SDK のモノレポです。

Primitive は、インバウンドおよびアウトバウンドのメールプラットフォームです。SDK は、次のシンプルなデフォルトのワークフローを中心に構成されています。

1. インバウンドメールを受信する
2. 正規化されたメールオブジェクトを調べる
3. 同期的に送信、返信、または転送する

SDK

SDK	インストール先	README
Node.js	npm install @primitivedotdev/sdk	sdk-node/README.md
Python	pip install primitivedotdev	sdk-python/README.md
Go	go get github.com/primitivedotdev/sdks/sdk-go/v2@latest	sdk-go/README.md

デフォルトの API 構成

各 SDK の基本的な使い方は次のとおりです。

• receive(...) でインバウンドメールを受信する
• client(...) でアウトバウンドクライアントを作成する
• send(...) で新しいメールを送信する
• reply(...) でスレッドに返信する
• forward(...) でメッセージを転送する

Node.js での最終的な形は次のとおりです。

import primitive from "@primitivedotdev/sdk";

const client = primitive.client({
  apiKey: process.env.PRIMITIVE_API_KEY!,
});

export async function POST(req: Request) {
  const email = await primitive.receive(req, {
    secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
  });

  await client.reply(email, "Thank you for your email.");

  return Response.json({ ok: true });
}

x402 決済

各 SDK には、ノンカストディアル型の x402 決済クライアントも含まれています。あるエージェントが支払い先アドレスを登録して USDC 決済をリクエストし、支払う側のエージェントが自身のキーを使ってローカルで署名し、決済します。キーが呼び出し元の外部に出ることはありません。ネットワークは base と base-sepolia で、金額はトークンの最小単位です（USDC は小数点以下 6 桁のため、"10000" は 0.01 USDC です）。実行可能な例については、各 SDK の README（sdk-node、sdk-python、sdk-go）の「x402 payments」セクションを参照してください。同じフローは、CLI の primitive payments コマンドグループからターミナルで実行することもできます。

高度な機能

高度なユースケース向けに、低レベル API と生成された API も引き続き利用できます。

• Webhook の検証／解析ヘルパー
• 生成された HTTP API パッケージ
• Primitive Memories のキーと値の操作
• OpenAPI エクスポート
• コントラクトツール
• 生の MIME 解析ヘルパー
• CLI

SDK の更新後も、こうした拡張機能は引き続き利用できますが、主要なドキュメントでは上記のインバウンド／アウトバウンド自動化フローに焦点を当てています。

リポジトリ構成

sdks/
  .github/workflows/
  openapi/
  json-schema/
  sdk-go/
  sdk-node/
  sdk-python/
  test-fixtures/

開発

ルートの Makefile を主なタスク実行インターフェイスとして使用してください。

make node-generate python-generate go-generate
make check
make build
make shared-check

Makefile は各 SDK のネイティブコマンドをラップしています。必要に応じて、各 SDK のディレクトリから直接実行することもできます。

cd sdk-node && pnpm typecheck && pnpm test
cd sdk-python && uv sync --dev && uv run pytest && uv run ruff check . && uv run basedpyright
cd sdk-go && go test ./... && go test -run TestSharedCompatibilityFixtures ./...

ドキュメント

• docs/architecture.md には、リポジトリのアーキテクチャとパッケージ構成が記載されています
• docs/schema-generation.md には、スキーマ／コード生成のフローが記載されています
• docs/repo-model.md には、モノレポのタスクモデルが記載されています
• RELEASE.md には、リリース手順が記載されています

Primitive 開発者向けリソース

AI エージェント向けメール API primitive.dev 上で開発するための情報をまとめています。

• Primitive API ドキュメント — docs.primitive.dev/docs（REST リファレンス：/docs/api）
• Primitive OpenAPI 仕様 — primitive.dev/openapi.json
• Primitive 認証ガイド — /docs/auth
• Primitive Webhook — /docs/endpoints
• Primitive MCP サーバー（Claude と ChatGPT のコネクター）— /docs/connectors
• Primitive CLI — npm install -g primitive
• 開発者向けリソースの全インデックス — primitive.dev/developers