@qmuse/appwrite-runtime-sdk 1.0.1 → 1.0.3-dev.1

package/README.md

@@ -29,6 +29,21 @@ 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 的可靠服务端审计与重试；浏览器侧上报只用于补充安全信号。

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { createQmuseAppwriteRuntime } from './runtime';
-export type { AppwriteAccountLike, AppwriteClientLike, AppwriteError, AppwriteRuntimeConfig, AppwriteSession, AppwriteTablesDBLike, AppwriteUser, BusinessRowData, QmuseAppwriteClients, QmuseAppwriteRuntimeOptions, QmuseEnvironment, QmuseRuntimeContext, } from './types';
+export type { AppwriteAccountLike, AppwriteClientLike, AppwriteError, AppwriteRuntimeConfig, AppwriteSession, AppwriteTablesDBLike, AppwriteUser, BusinessRowData, CreateRowInput, DeleteRowInput, GetRowInput, ListRowsInput, QmuseAppwriteClients, QmuseAppwriteRuntimeApi, QmuseAppwriteRuntimeOptions, QmuseEnvironment, QmuseRuntimeContext, UpdateRowInput, } from './types';

package/dist/runtime/AppwriteSessionCoordinator.d.ts

@@ -0,0 +1,29 @@
+import type { AppwriteUser, QmuseAppwriteRuntimeOptions } from '../types';
+export declare class AppwriteSessionCoordinator {
+    private readonly options;
+    private readonly request;
+    private readonly state;
+    private initPromise;
+    private sessionSyncPromise;
+    private refreshPromise;
+    constructor(options: QmuseAppwriteRuntimeOptions, request: typeof globalThis.fetch);
+    init(): Promise<void>;
+    getDatabaseId(): Promise<string>;
+    getCurrentUser(): Promise<AppwriteUser>;
+    requireCurrentUser(): AppwriteUser;
+    refreshSession(): Promise<void>;
+    withSessionRetry<T>(operation: () => Promise<T>): Promise<T>;
+    private getMuseRuntime;
+    private requireRuntimeConfig;
+    private clearCurrentSession;
+    private loadRuntimeConfig;
+    private cacheCurrentSession;
+    private tryCacheCurrentSession;
+    private deleteCurrentSession;
+    private ensureAnonymousSession;
+    private requestCustomToken;
+    private ensureAuthenticatedSession;
+    private coordinateSession;
+    private synchronizeSession;
+    private initialize;
+}