QMuse Appwrite Runtime SDK

浏览器端 QMuse Appwrite Runtime SDK。应用仍在 src/services/appwrite.ts 创建唯一的 Appwrite Client、Account 和 TablesDB，本包负责 Runtime 配置、Session 协调、单次 401 刷新和带审计字段保护的 TablesDB CRUD。

使用

import { Account, Client, TablesDB } from 'appwrite';
import { createQmuseAppwriteRuntime } from '@alipay/appwrite-runtime-sdk';

export const client = new Client();
export const account = new Account(client);
export const tablesDB = new TablesDB(client);

const runtime = createQmuseAppwriteRuntime({
  client,
  account,
  tablesDB,
  getMuseRuntime: () => window.__MUSE__,
  getQmuseLoginUserId: () => {
    const userId = window.__TERN__?.user?.clientUser?.userId;
    return typeof userId === 'string' && userId.trim() ? userId : null;
  },
});

export const initAppwrite = runtime.init;
export const getAppwriteClients = runtime.getClients;
export const createQmuseRow = runtime.createRow;
export const updateQmuseRow = runtime.updateRow;

createQmuseAppwriteRuntime() 返回的实例应在 src/services/appwrite.ts 中作为模块级单例复用。实例创建后会立即异步初始化；initAppwrite() 返回同一个共享 Promise，getAppwriteClients() 和所有 CRUD 也会等待该初始化。SDK 会在内部观察每个公开方法返回的 Promise，因此忽略后台初始化或数据调用不会产生影响应用运行的全局 unhandledrejection；显式等待仍会收到同一个 Promise 的原始错误，初始化失败后下一次调用可以重试。

工厂创建阶段不因缺少 fetch 或 Runtime 配置异常同步抛错；这类问题会进入共享初始化 Promise。异步审计链路中的 Runtime 读取、URL 构造和请求错误也不会改变 CRUD 结果。

getCurrentAppwriteUser() 同样是异步方法，使用时需要 await；它会先等待共享初始化，不会在调用阶段同步抛错。

内部结构

• src/runtime.ts：稳定的工厂入口。
• src/runtime/QmuseAppwriteRuntime.ts：公开 API 装配与 TablesDB CRUD 编排。
• src/runtime/AppwriteSessionCoordinator.ts：Runtime 配置、Session 状态机和 401 刷新。
• src/runtime/MutationAuditReporter.ts：非阻塞 mutation 安全审计。
• src/runtime/rowData.ts：业务字段过滤与审计数据脱敏。
• src/runtime/utils.ts：HTTP 错误、fetch 延迟解析和 Promise rejection 观察。

不要在页面、hook 或业务服务中直接创建 Appwrite SDK 实例，或绕过 createRow / updateRow 写入审计字段。

新增、更新和删除会由 SDK 内置地异步上报最小审计事件；上报不阻塞 CRUD，也不向业务代码暴露 hook、开关或 API Key。SDK 不上传业务 data、custom-token 或 Session。项目内置的 Appwrite 事件云函数仍负责成功 mutation 的可靠服务端审计与重试；浏览器侧上报只用于补充安全信号。

Badges

准备工作

• 安装 nodejs
• 使用最新版本的 tnpm

开发

# 安装依赖
$ tnpm install

# 构建与检查
$ npm run build
$ npm run lint
$ npm test

发布

该 SDK 不发布为海兔资产；构建、测试和公网 npm 发布均使用独立工具链。

公网 @qmuse 包

先在 package.json 设定未发布的正式语义化版本，再执行：

npm run publish:public

脚本会先询问发布 tag，直接回车默认发布到 dev，也可以输入 latest。它会验证 npmjs 登录态、检查版本是否已存在，并运行 CI 与构建。确认后，它只在发布期间把包名临时改为 @qmuse/appwrite-runtime-sdk，退出时恢复本地 package.json。

首次正式发布建议先选择 dev 验证；确认无误后，可直接再次执行脚本并选择 latest，或移动 latest tag：

npm dist-tag add @qmuse/appwrite-runtime-sdk@<version> latest --registry https://registry.npmjs.org/