Docs
文档目录

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 Keyagentbase-node-sdk
建项目 / 发 Key / 平台注册 / 组织与账单等治理自动化Console SDK(另有 java / python / go 同名页)Console Session 或短期 JWTagentbase-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);

5 分钟上手(浏览器)

  1. 安装:npm install agentbase-web-sdk@2.12.0 --save-exact。

  2. 用上文代码初始化,并在项目 Overview → Platforms 注册你的 Web 域名(否则 CORS 403,见平台登记)。

  3. 注册并登录,拿到用户 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 = 未登录/会话失效,按未登录处理
  1. 以用户身份读写数据(受行级权限约束,见权限模型):

const rows = await tablesDB.listRows('app-db', 'tasks', [Query.equal('done', false)]);

完整可运行的各功能点写法见 ../examples/javascript.md。

认证装载(用户 Session 的来源)

方式装载调用说明
Email/Passwordaccount.create() 注册 + account.createEmailPasswordSession()Session 落 Cookie,后续自动携带
OAuth 2.0account.createOAuth2Session({ provider, success, failure })浏览器重定向;Provider / 回调配置见 ../authentication.md
Magic URL / PhonecreateMagicURLToken / 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。

错误模型

功能面映射表(客户端可用面)

功能域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)
组织管理、账单、组织 KeyConsole SDK / Console UI(../organization.md)
桶 / 表结构基线配置服务端下发基线;客户端只消费

使用要点与边界

示例指引