設定指南

本指南涵蓋從零到運作 Imbrace SDK 整合所需的一切 — 安裝、環境、憑證和服務 URL 覆蓋。

系統需求

需求	最低版本
Node.js	18.0.0+
npm	8.0.0+
Python	3.9+
pip	23.0+

安裝

TypeScript
Python

從 npm 註冊表安裝：

npm install @imbrace/sdk
# or
yarn add @imbrace/sdk
# or
pnpm add @imbrace/sdk

單一倉儲 / 本機開發：

# 步驟 1 — 安裝相依套件並建置
cd ts
npm install
npm run build

# 步驟 2（可選）— 全域連結以在同一台機器上的另一個專案中使用
npm link

然後在您的外部專案中：

npm link @imbrace/sdk

驗證：

import { ImbraceClient } from "@imbrace/sdk";
console.log("SDK loaded:", typeof ImbraceClient); // 'function'

從 PyPI 安裝：

pip install imbrace
# or
uv add imbrace

單一倉儲 / 本機開發（editable 模式）：

cd py
pip install -e ".[dev]"

[dev] 標誌會安裝：pytest、pytest-asyncio、pytest-httpx、ruff、mypy。

驗證：

from imbrace import ImbraceClient
print("SDK loaded:", ImbraceClient)

環境

名稱	閘道 URL	使用時機
`develop`	`https://app-gateway.dev.imbrace.co`	內部開發
`sandbox`	`https://app-gateway.sandbox.imbrace.co`	整合測試
`stable`	`https://app-gatewayv2.imbrace.co`	生產環境（預設）

透過建構函式選項 env 切換環境，或直接使用 baseUrl 覆蓋 URL：

TypeScript
Python

const client = new ImbraceClient({ env: "sandbox" });

client = ImbraceClient(env="sandbox")

設定憑證

建立 `.env` 檔案

SDK 不會自動讀取環境變數 — 您直接在建構函式中傳遞憑證。.env 檔案是用於儲存秘密的使用者慣例；請使用 dotenv 或您框架的環境變數載入器來讀取它們。

# 憑證
IMBRACE_API_KEY=your_api_key_here
IMBRACE_ACCESS_TOKEN=your_jwt_token_here

# 組織 ID — 隨每個請求傳送
IMBRACE_ORGANIZATION_ID=your_org_id_here

# 可選：直接覆蓋閘道 URL
IMBRACE_GATEWAY_URL=https://app-gatewayv2.imbrace.co

取得 API 金鑰

完整說明請參閱取得 API 金鑰。

初始化用戶端

import { ImbraceClient } from "@imbrace/sdk";

// 伺服器端 — API 金鑰
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env:            "stable",
});

// 用戶端 — 存取權杖（例如來自先前的登入，或您自己儲存的 token）
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env:         "stable",
});

// 密碼登入（POST /v1/login/sign_in）— 終端使用者應用最常見的方式。
// 在一次呼叫中傳回 { token: "login_acc_...", organizations: [...] }；
// 用 selectOrganization() 選擇其中一個，SDK 會自動切換為該組織的 acc_ token。
const anon = new ImbraceClient({ env: "stable" });
const { organizations } = await anon.login("user@example.com", "password");
await anon.selectOrganization(organizations[0].id);

// OTP 登入流程（替代方案 — 用 email-OTP 體驗取代密碼）
await anon.requestOtp("user@example.com");
await anon.loginWithOtp("user@example.com", "123456");
// 權杖自動儲存在用戶端上

import os
from imbrace import ImbraceClient

# 伺服器端 — API 金鑰
client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
)

# 用戶端 — 存取權杖
client = ImbraceClient(
    access_token="eyJhbGci...",
    organization_id="org_xxx",
)

# 密碼登入（POST /platform/v1/login/authenticate）— 終端使用者應用最常見的方式。
# login() 回傳使用者所屬的組織；選擇其一後用 select_organization()
# 將短期 login_acc_ token 換成綁定組織的 acc_ token。
anon = ImbraceClient(env="stable")
res = anon.login("user@example.com", "password")
anon.select_organization(res["organizations"][0]["organization_id"])

# OTP 登入流程（替代方案 — 用 email-OTP 體驗取代密碼）
anon.request_otp("user@example.com")
anon.login_with_otp("user@example.com", "123456")

from imbrace import AsyncImbraceClient

async def main():
    async with AsyncImbraceClient(api_key="api_...") as client:
        me = await client.platform.get_me()
        print(me)

CLI 安裝

# 全域安裝
npm install -g @imbrace/cli

# 登入以開始使用
imbrace login --api-key api_xxx...

有關其他安裝方法，請參閱 CLI 安裝；有關完整的指令參考，請參閱 CLI 指令。

覆蓋服務 URL

當微服務執行在不同的位址時使用（例如本機開發、專用暫存環境）。

TypeScript
Python

const client = new ImbraceClient({
  env: "develop",
  services: {
    aiAgent: "http://localhost:4000/ai-agent",
    dataBoard: "http://localhost:3001/data-board",
    channelService: "http://localhost:3002/channel-service",
  },
});

client = ImbraceClient(
    env="develop",
    services={
        "ai_agent":       "http://localhost:4000/ai-agent",
        "data_board":     "http://localhost:3001/data-board",
        "channel_service":"http://localhost:3002/channel-service",
    },
)

所有有效的服務鍵名：

Python 鍵名	TypeScript 鍵名	服務
`gateway`	`gateway`	App Gateway
`platform`	`platform`	Platform 服務
`channel_service`	`channelService`	Channel 服務
`data_board`	`dataBoard`	Data Board
`backend`	`backend`	舊版單體（`/v1/backend`）— 用於身分驗證登入、範本，以及少數尚未拆分出去的路由
`ips`	`ips`	IPS 服務
`ai`	`ai`	AI 服務
`marketplaces`	`marketplaces`	Marketplace 服務
`file_service`	`fileService`	檔案服務
`message_suggestion`	`messageSuggestion`	訊息建議服務
`predict`	`predict`	Predict 服務
`workflow_engine`	`workflowEngine`	工作流程
`ai_agent`	`aiAgent`	AI Agent 服務

疑難排解

`Cannot find package '@imbrace/sdk'`

套件未連結。從 ts 重新執行：

npm link
cd /path/to/your-project && npm link @imbrace/sdk

`ERR_MODULE_NOT_FOUND` 指向 `dist/` 中的檔案

套件尚未建置：

cd ts && npm run build

`ModuleNotFoundError: No module named 'imbrace'`

cd py && pip install -e ".[dev]"

`401 Unauthorized`

API 金鑰已過期或無效。請從 Imbrace Dashboard 產生新的金鑰，或參閱 API 金鑰指南。

`UserWarning: ImbraceClient: no credentials provided`

未傳遞 api_key 或 access_token。如果是有意的（例如僅登入流程），請忽略此警告。否則請檢查您的 .env 檔案。