Hướng dẫn Thiết lập

Hướng dẫn này bao gồm mọi thứ bạn cần để đi từ số không đến một tích hợp Imbrace SDK hoạt động — cài đặt, môi trường, thông tin xác thực và ghi đè URL dịch vụ.

Yêu cầu Hệ thống

Yêu cầu	Phiên bản tối thiểu
Node.js	18.0.0+
npm	8.0.0+
Python	3.9+
pip	23.0+

Cài đặt

TypeScript
Python

Từ npm registry:

npm install @imbrace/sdk
# hoặc
yarn add @imbrace/sdk
# hoặc
pnpm add @imbrace/sdk

Monorepo / phát triển cục bộ:

# Bước 1 — cài đặt phụ thuộc và xây dựng
cd ts
npm install
npm run build

# Bước 2 (tùy chọn) — liên kết toàn cục để sử dụng trong dự án khác trên cùng máy
npm link

Sau đó trong dự án bên ngoài của bạn:

npm link @imbrace/sdk

Xác minh:

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

Từ PyPI:

pip install imbrace
# hoặc
uv add imbrace

Monorepo / phát triển cục bộ (chế độ editable):

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

Cờ [dev] cài đặt: pytest, pytest-asyncio, pytest-httpx, ruff, mypy.

Xác minh:

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

Môi trường

Tên	URL Gateway	Sử dụng khi
`develop`	`https://app-gateway.dev.imbrace.co`	Phát triển nội bộ
`sandbox`	`https://app-gateway.sandbox.imbrace.co`	Kiểm thử tích hợp
`stable`	`https://app-gatewayv2.imbrace.co`	Production (mặc định)

Chuyển đổi môi trường qua tùy chọn constructor env, hoặc ghi đè URL trực tiếp bằng baseUrl:

TypeScript
Python

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

client = ImbraceClient(env="sandbox")

Cấu hình Thông tin Xác thực

Tạo tệp `.env`

SDK không tự động đọc biến môi trường — bạn truyền thông tin xác thực trực tiếp vào constructor. Tệp .env là một quy ước người dùng để lưu trữ bí mật; sử dụng dotenv hoặc trình tải env của framework để đọc chúng.

# Thông tin xác thực
IMBRACE_API_KEY=your_api_key_here
IMBRACE_ACCESS_TOKEN=your_jwt_token_here

# ID Tổ chức — được gửi với mọi yêu cầu
IMBRACE_ORGANIZATION_ID=your_org_id_here

# Tùy chọn: ghi đè URL gateway trực tiếp
IMBRACE_GATEWAY_URL=https://app-gatewayv2.imbrace.co

Lấy API Key

Xem Hướng dẫn lấy API Key để biết hướng dẫn đầy đủ.

Khởi tạo Client

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

// Phía máy chủ — API Key
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env:            "stable",
});

// Phía client — Access Token (ví dụ: từ lần đăng nhập trước, hoặc token bạn tự lưu)
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env:         "stable",
});

// Đăng nhập bằng mật khẩu (POST /v1/login/sign_in) — phổ biến nhất cho ứng dụng end-user.
// Trả về { token: "login_acc_...", organizations: [...] } trong một lần gọi; chọn một
// bằng selectOrganization() và SDK sẽ đổi sang acc_ token gắn với tổ chức đó.
const anon = new ImbraceClient({ env: "stable" });
const { organizations } = await anon.login("user@example.com", "password");
await anon.selectOrganization(organizations[0].id);

// Luồng đăng nhập OTP (thay thế — cho UX dùng email-OTP thay vì mật khẩu)
await anon.requestOtp("user@example.com");
await anon.loginWithOtp("user@example.com", "123456");
// Token được lưu tự động trên client

import os
from imbrace import ImbraceClient

# Phía máy chủ — API Key
client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
)

# Phía client — Access Token
client = ImbraceClient(
    access_token="eyJhbGci...",
    organization_id="org_xxx",
)

# Đăng nhập bằng mật khẩu (POST /platform/v1/login/authenticate) — phổ biến nhất cho ứng dụng end-user.
# login() trả về danh sách tổ chức; chọn 1 rồi select_organization() đổi token
# login_acc_ ngắn hạn lấy token acc_ gắn theo tổ chức.
anon = ImbraceClient(env="stable")
res = anon.login("user@example.com", "password")
anon.select_organization(res["organizations"][0]["organization_id"])

# Luồng đăng nhập OTP (thay thế — cho UX dùng email-OTP thay vì mật khẩu)
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)

Cài đặt CLI

# Cài đặt toàn cục
npm install -g @imbrace/cli

# Đăng nhập để bắt đầu
imbrace login --api-key api_xxx...

Xem Cài đặt CLI để biết các phương pháp cài đặt thay thế và Lệnh CLI để biết tài liệu tham khảo lệnh đầy đủ.

Ghi đè URL Dịch vụ

Sử dụng khi một microservice chạy ở địa chỉ khác (ví dụ: dev cục bộ, staging chuyên dụng).

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",
    },
)

Tất cả các key dịch vụ hợp lệ:

Python key	TypeScript key	Dịch vụ
`gateway`	`gateway`	App Gateway
`platform`	`platform`	Dịch vụ Platform
`channel_service`	`channelService`	Dịch vụ Channel
`data_board`	`dataBoard`	Data Board
`backend`	`backend`	Monolith cũ (`/v1/backend`) — dùng cho đăng nhập xác thực, template và một số route chưa được tách ra
`ips`	`ips`	Dịch vụ IPS
`ai`	`ai`	Dịch vụ AI
`marketplaces`	`marketplaces`	Dịch vụ Marketplace
`file_service`	`fileService`	Dịch vụ File
`message_suggestion`	`messageSuggestion`	Dịch vụ Message Suggestion
`predict`	`predict`	Dịch vụ Predict
`workflow_engine`	`workflowEngine`	Workflows
`ai_agent`	`aiAgent`	Dịch vụ AI Agent

Khắc phục sự cố

`Cannot find package '@imbrace/sdk'`

Gói chưa được liên kết. Chạy lại từ ts:

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

`ERR_MODULE_NOT_FOUND` cho tệp trong `dist/`

Gói chưa được xây dựng:

cd ts && npm run build

`ModuleNotFoundError: No module named 'imbrace'`

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

`401 Unauthorized`

API Key đã hết hạn hoặc không hợp lệ. Tạo key mới từ Imbrace Dashboard hoặc xem hướng dẫn API Key.

`UserWarning: ImbraceClient: no credentials provided`

Không có api_key hoặc access_token nào được truyền. Nếu cố ý (ví dụ: luồng chỉ đăng nhập), bỏ qua cảnh báo này. Nếu không, hãy kiểm tra tệp .env của bạn.