Web(用户 Session)
面向浏览器 / 移动端前端的 SDK:以用户 Session 身份调用项目功能。Client SDK 目前仅 JavaScript(Web)一个语言面,npm 坐标 agentbase-web-sdk@2.12.0(安装见 ../integration.md)。本页写选型、初始化、认证装载、错误模型与功能面映射;功能点正文在功能轴文档。
三类 SDK 怎么选
| 你在写什么 | 用哪个 | 凭据 | npm 包 |
|---|---|---|---|
| 浏览器 / 移动端前端,终端用户操作自己的数据 | Client SDK(本页) | 用户 Session(Cookie,自动携带) | agentbase-web-sdk |
| Node 后端 / Worker / CLI,以项目身份读写全量数据 | Server SDK(另有 java / python / go 同名页) | 项目 API Key | agentbase-node-sdk |
| 建项目 / 发 Key / 平台注册 / 组织与账单等治理自动化 | Console SDK(另有 java / python / go 同名页) | Console Session 或短期 JWT | agentbase-console-sdk |
前端只放用户 Session;API Key 与一切密钥只存服务端。
初始化:setEndpoint + setProject
import { Client, Account, TablesDB } from 'agentbase-web-sdk';
const client = new Client()
.setEndpoint('https://<host>/v1') // 环境规范见 ../environment.md
.setProject('<PROJECT_ID>'); // 应用项目 ID,不是 'console'
export const account = new Account(client);
export const tablesDB = new TablesDB(client);两个 set 都是必填:endpoint 决定环境(托管 SIT / 正式 / 自托管),project 决定资源归属与 CORS 校验上下文。
页面 origin(hostname)必须已在项目的 Platform 注册,否则
Invalid URI/ CORS 403(见 ../overview.md)。组织相关调用(项目治理)另需
client.setOrganization(canonicalTeamId)声明组织头。
5 分钟上手(浏览器)
安装:
npm install agentbase-web-sdk@2.12.0 --save-exact。用上文代码初始化,并在项目 Overview → Platforms 注册你的 Web 域名(否则 CORS 403,见平台登记)。
注册并登录,拿到用户 Session:
import { ID, Query } from 'agentbase-web-sdk';
await account.create({ userId: ID.unique(), email, password, name }); // 仅注册一次
await account.createEmailPasswordSession({ email, password });
const me = await account.get(); // 抛 401 = 未登录/会话失效,按未登录处理以用户身份读写数据(受行级权限约束,见权限模型):
const rows = await tablesDB.listRows('app-db', 'tasks', [Query.equal('done', false)]);完整可运行的各功能点写法见 ../examples/javascript.md。
认证装载(用户 Session 的来源)
| 方式 | 装载调用 | 说明 |
|---|---|---|
| Email/Password | account.create() 注册 + account.createEmailPasswordSession() | Session 落 Cookie,后续自动携带 |
| OAuth 2.0 | account.createOAuth2Session({ provider, success, failure }) | 浏览器重定向;Provider / 回调配置见 ../authentication.md |
| Magic URL / Phone | createMagicURLToken / createPhoneToken → createSession / updatePhoneSession | 回调页取 userId + secret |
| 匿名 | account.createAnonymousSession() | 游客身份,可无损转正 |
| Custom Token | 服务端 users.createToken → account.createSession({ userId, secret }) | 自有账号体系 |
| JWT(出站) | account.createJWT() | 交给可信后端代调用,不是前端装载方式 |
Session 恢复三层机制:Cookie(a_session_<projectId>)→ x-appwrite-session header → x-fallback-cookies(localStorage)。跨域 <img> 等无法设 header 的场景全部不可用,需 Blob URL 或 File Token(../storage.md)。会话管理见 ../profile.md。
错误模型
所有失败抛
AgentbaseException:code为 HTTP 状态码(400 / 401 / 403 / 404 / 409 / 413 / 429…),type为服务端错误类型(如user_unauthorized、storage_file_not_found、route_not_found),并附原始响应体。典型语义:
401:未登录 / Session 失效 / Client SDK 行级权限越界(
hasRole约束)。404 在存储
fileSecurity下可能是权限不足而非不存在——先查权限(../storage.md)。409 冲突(ID / 邮箱已存在、删除状态冲突);413 配额超限;429 限流。
前端约定:
account.get()失败按未登录处理并跳转登录;不要吞异常或用?? 0掩盖缺失数据(用量聚合的quantity: null必须按缺失展示)。
功能面映射表(客户端可用面)
| 功能域 | Client SDK service | 正文与边界 |
|---|---|---|
| 账号认证(全谱 + MFA) | Account | ../authentication.md |
| 账号资料 / 会话 / 偏好 | Account | ../profile.md |
| 当前账号 quota 上限 | Account.getQuotaLimits() / updateQuotaLimits() / deleteQuotaLimits() / listLimitsProjects();仅账号级,不含项目 quota 或 /limits 治理 | ../limits.md |
| 库表行读写(用户 Session 下受权限约束) | TablesDB / Databases(旧文档面) | ../databases.md、../permissions.md |
| 查询构造 | Query | ../databases.md |
| 对象存储(上传 / 下载 / 预览 URL) | Storage | ../storage.md |
| 函数触发(需 execute 权限) | Functions | ../functions.md |
| 团队(自己所在团队与成员) | Teams | ../teams.md |
| 实时订阅 | Realtime + Channel(Channel.tablesdb(db).table(t).row(r)、Channel.files()、账号频道) | 订阅行 / 文件 / 账号变更;subscribe(...) 返回句柄 close();频道是构造器不是函数字符串 |
| 组织项目治理(Owner) | Projects(listInactiveByOrganization 等 4 方法) | ../project-governance.md;需 Owner Session + setOrganization |
| 记忆数据面 | Memory | 用户自己被授权的记忆读写;管理面不在客户端 |
| LLM / AI 数据面 | LlmGateway、AiGateway、KnowledgeBases | 终端用户数据面子集;不得持有 Gateway Key / Provider 凭据 |
| 其他 | Avatars、Locale、Graphql | 通用工具与查询面 |
客户端边界(不可用面)
| 不可用 | 原因 / 替代 |
|---|---|
用户管理(users.list、改他人资料、labels) | 管理面专属,走 Server SDK(../users.md) |
File Token 签发(Tokens) | 需 API Key;由 Function / 后端签发短链 |
| 平台注册 / OAuth Provider 配置 / API Key 管理 | Console Session 面或管理 API Key(../overview.md) |
| 行 / 文件上给别人授权 | Client SDK hasRole 约束;用 Function 代理(../permissions.md) |
| 组织管理、账单、组织 Key | Console SDK / Console UI(../organization.md) |
| 桶 / 表结构基线配置 | 服务端下发基线;客户端只消费 |
使用要点与边界
不要把 API Key、JWT、Provider Secret、Gateway Key 放进前端代码或构建变量;前端只持用户 Session。
客户端建行省略
permissions以获得创建者默认权限;updateRow传权限是全量替换(../permissions.md)。Realtime 与 REST 共用权限模型:订阅不到 = 权限不可见,不是连接问题。
多环境(SIT / 正式)各用各的项目与 Platform 注册;endpoint 与 project 必须同环境。
示例指引
JavaScript(Web)完整调用写法:../examples/javascript.md