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 支付客户端。一个 Agent 注册收款地址并请求 USDC 支付；付款 Agent 使用自己的密钥在本地签名并完成结算。密钥绝不会离开调用方。网络为 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 开发者资源

在 primitive.dev 上进行开发所需的一切资源。这里是面向 AI Agent 的电子邮件 API：

• 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