@qmuse/appwrite-runtime-sdk 1.0.4 → 1.0.5-dev.1

package/README.md

@@ -1,98 +1,490 @@
-# QMuse Appwrite Runtime SDK
+# @qmuse/appwrite-runtime-sdk
 
-浏览器端 QMuse Appwrite Runtime SDK。应用仍在 `src/services/appwrite.ts` 创建唯一的 Appwrite `Client`、`Account` 和 `TablesDB`，本包负责 Runtime 配置、Session 协调、单次 401 刷新和带审计字段保护的 TablesDB CRUD。
+QMuse 应用访问 Appwrite 的运行时 SDK，提供统一的运行时初始化、用户 Session 管理和 TablesDB 数据操作能力。
 
-## 使用
+SDK 支持两类应用：
+
+| 应用类型       | 接入方式                         | 适用平台                     |
+| -------------- | -------------------------------- | ---------------------------- |
+| React Web 应用 | 配合 Appwrite Web SDK 创建客户端 | 浏览器、QMuse H5 预览        |
+| Taro 应用      | 使用 SDK 提供的跨端客户端        | H5、支付宝小程序、微信小程序 |
+
+## 安装
+
+```bash
+npm install @qmuse/appwrite-runtime-sdk appwrite@24.1.1
+```
+
+在本地仓库联调 SDK 时，可以在应用的 `package.json` 中引用源码包：
+
+```json
+{
+  "dependencies": {
+    "@qmuse/appwrite-runtime-sdk": "file:../../appwrite-runtime-sdk",
+    "appwrite": "24.1.1"
+  }
+}
+```
+
+## 运行时上下文
+
+React 和 Taro 应用都需要向 SDK 提供以下 QMuse 运行时信息：
+
+```ts
+interface QmuseRuntimeContext {
+  appId: string;
+  env: 'dev' | 'prod';
+  domain: string;
+}
+```
+
+| 字段     | 说明                                                      |
+| -------- | --------------------------------------------------------- |
+| `appId`  | 当前 QMuse 应用 ID                                        |
+| `env`    | 当前运行环境                                              |
+| `domain` | QMuse Runtime 服务域名，例如 `https://appio-pre.qmuse.cn` |
+
+用户信息通过 `getQmuseLoginUserId()` 单独提供。已登录时返回 QMuse 用户 ID，未登录时返回 `null`。
+
+`appVersionId` 不是运行时初始化或 Appwrite Custom Token 所需参数，不需要注入或传给 SDK。
+
+## React 应用
+
+React Web 应用使用 Appwrite Web SDK 提供的 `Client`、`Account` 和 `TablesDB`。
+
+### 1. 声明宿主环境
+
+在项目的全局类型文件中声明 QMuse 注入的环境：
 
 ```ts
-import { Account, Client, TablesDB } from 'appwrite';
-import { createQmuseAppwriteRuntime } from '@alipay/appwrite-runtime-sdk';
+// src/types/global.d.ts
+interface Window {
+  __MUSE__: {
+    appId: string;
+    env: 'dev' | 'prod';
+    domain: string;
+  };
+  __TERN__?: {
+    user?: {
+      clientUser?: {
+        userId?: string;
+      };
+    };
+  };
+}
+```
 
-export const client = new Client();
-export const account = new Account(client);
-export const tablesDB = new TablesDB(client);
+### 2. 创建应用级单例
+
+在统一的服务模块中创建 Runtime，并向业务代码导出所需方法：
+
+```ts
+// src/services/appwrite.ts
+import {
+  Account,
+  Client,
+  ID,
+  Permission,
+  Query,
+  Role,
+  TablesDB,
+} from 'appwrite';
+import {
+  createQmuseAppwriteRuntime,
+  type AppwriteAccountLike,
+  type Models,
+  type QmuseRuntimeContext,
+} from '@qmuse/appwrite-runtime-sdk';
+
+const client = new Client();
+const account = new Account(client);
+const tablesDB = new TablesDB(client);
+
+function getMuseRuntime(): QmuseRuntimeContext {
+  return window.__MUSE__;
+}
+
+function getQmuseLoginUserId(): string | null {
+  const userId = window.__TERN__?.user?.clientUser?.userId;
+  return typeof userId === 'string' && userId.trim() ? userId : null;
+}
+
+const runtimeAccount: AppwriteAccountLike = {
+  get: () => account.get(),
+  getSession: (input) => account.getSession(input),
+  deleteSession: async (input) => {
+    await account.deleteSession(input);
+  },
+  createAnonymousSession: () => account.createAnonymousSession(),
+  createSession: (input) => account.createSession(input),
+};
 
 const runtime = createQmuseAppwriteRuntime({
   client,
-  account,
+  account: runtimeAccount,
   tablesDB,
-  getMuseRuntime: () => window.__MUSE__,
-  getQmuseLoginUserId: () => {
-    const userId = window.__TERN__?.user?.clientUser?.userId;
-    return typeof userId === 'string' && userId.trim() ? userId : null;
+  getMuseRuntime,
+  getQmuseLoginUserId,
+});
+
+export const initAppwrite = runtime.init;
+export const getAppwriteClients = runtime.getClients;
+export const getCurrentAppwriteUser = runtime.getCurrentUser;
+export const refreshAppwriteSession = runtime.refreshSession;
+export const listQmuseRows = runtime.listRows;
+export const getQmuseRow = runtime.getRow;
+export const createQmuseRow = runtime.createRow;
+export const updateQmuseRow = runtime.updateRow;
+export const deleteQmuseRow = runtime.deleteRow;
+
+export type { Models };
+export { ID, Permission, Query, Role };
+```
+
+每个应用只创建一个 Runtime 实例。页面、Hook 和其他业务服务统一复用该模块导出的方法。
+
+### 3. 初始化应用
+
+在渲染 React 根节点前完成初始化：
+
+```tsx
+// src/main.tsx
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import { initAppwrite } from './services/appwrite';
+
+async function bootstrap() {
+  await initAppwrite();
+  createRoot(document.getElementById('root')!).render(<App />);
+}
+
+bootstrap().catch((error) => {
+  console.error('Appwrite initialization failed', error);
+});
+```
+
+### 4. 在 React 组件中读取数据
+
+```tsx
+import { useEffect, useState } from 'react';
+import { listQmuseRows, Query, type Models } from './services/appwrite';
+
+type TodoRow = Models.Row & {
+  title: string;
+  completed: boolean;
+};
+
+export function TodoList() {
+  const [rows, setRows] = useState<TodoRow[]>([]);
+
+  useEffect(() => {
+    listQmuseRows<TodoRow>({
+      tableId: 'todos',
+      queries: [Query.orderDesc('$createdAt')],
+      limit: 20,
+    })
+      .then((result) => setRows(result.rows))
+      .catch((error) => console.error('Failed to load todos', error));
+  }, []);
+
+  return (
+    <ul>
+      {rows.map((row) => (
+        <li key={row.$id}>{row.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Taro 项目
+
+Taro 项目通过 `createPortableAppwriteClients()` 使用同一套 Runtime API。该方式适用于 Taro H5、支付宝小程序和微信小程序。
+
+### 1. 配置跨端环境变量
+
+在 Taro 的 `.env.development` 和 `.env.production` 中按目标环境配置：
+
+```dotenv
+TARO_APP_QMUSE_APP_ID=3789326422662181
+TARO_APP_QMUSE_RUNTIME_ENV=dev
+TARO_APP_QMUSE_RUNTIME_DOMAIN=https://appio-pre.qmuse.cn
+```
+
+补充环境变量类型：
+
+```ts
+// types/global.d.ts
+interface QMuseRuntimeConfig {
+  appId: string;
+  env: 'dev' | 'prod';
+  domain: string;
+}
+
+declare namespace NodeJS {
+  interface ProcessEnv {
+    TARO_APP_QMUSE_APP_ID: string;
+    TARO_APP_QMUSE_RUNTIME_ENV: 'dev' | 'prod';
+    TARO_APP_QMUSE_RUNTIME_DOMAIN: string;
+  }
+}
+```
+
+### 2. 读取固定运行时配置
+
+```ts
+// src/runtime/qmuse.ts
+import type { QmuseRuntimeContext } from '@qmuse/appwrite-runtime-sdk';
+
+const runtimeConfig: QmuseRuntimeContext = Object.freeze({
+  appId: process.env.TARO_APP_QMUSE_APP_ID,
+  env: process.env.TARO_APP_QMUSE_RUNTIME_ENV,
+  domain: process.env.TARO_APP_QMUSE_RUNTIME_DOMAIN,
+});
+
+export function getMuseRuntimeConfig(): QmuseRuntimeContext {
+  return runtimeConfig;
+}
+```
+
+使用 `TARO_APP_*` 环境变量可以让 Taro 在 dev 和 build 命令中为 H5、支付宝和微信产物使用同一套注入方式。
+
+### 3. 提供跨端请求与存储
+
+H5 可以使用浏览器 `fetch`，小程序端需要将 `Taro.request` 适配为 SDK 接收的 `fetch` 接口：
+
+```ts
+// src/services/platform.ts
+import Taro from '@tarojs/taro';
+
+function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
+  if (!headers) return {};
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  if ('forEach' in headers && typeof headers.forEach === 'function') {
+    const result: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  }
+  return Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [key, String(value)]),
+  );
+}
+
+const taroFetch = async (
+  input: RequestInfo | URL,
+  init: RequestInit = {},
+): Promise<Response> => {
+  const url = typeof input === 'string' ? input : input.toString();
+  const result = await Taro.request({
+    url,
+    method: (init.method || 'GET').toUpperCase() as keyof Taro.request.Method,
+    header: normalizeHeaders(init.headers),
+    data: typeof init.body === 'string' ? init.body : undefined,
+    dataType: 'text',
+    responseType: 'text',
+  });
+  const text =
+    typeof result.data === 'string'
+      ? result.data
+      : JSON.stringify(result.data ?? '');
+  const responseHeaders = new Map(
+    Object.entries(result.header || {}).map(([key, value]) => [
+      key.toLowerCase(),
+      String(value),
+    ]),
+  );
+
+  return {
+    ok: result.statusCode >= 200 && result.statusCode < 300,
+    status: result.statusCode,
+    headers: {
+      get: (name: string) => responseHeaders.get(name.toLowerCase()) ?? null,
+    },
+    text: async () => text,
+  } as Response;
+};
+
+export const platformFetch: typeof globalThis.fetch = ((input, init) => {
+  if (process.env.TARO_ENV === 'h5' && typeof globalThis.fetch === 'function') {
+    return globalThis.fetch(input, init);
+  }
+  return taroFetch(input, init);
+}) as typeof globalThis.fetch;
+
+export const platformStorage = {
+  getItem(key: string): string | null {
+    const value = Taro.getStorageSync(key);
+    return typeof value === 'string' && value ? value : null;
+  },
+  setItem(key: string, value: string): void {
+    Taro.setStorageSync(key, value);
   },
+  removeItem(key: string): void {
+    Taro.removeStorageSync(key);
+  },
+};
+```
+
+### 4. 创建 Taro Runtime 单例
+
+```ts
+// src/services/appwrite.ts
+import { ID, Permission, Query, Role } from 'appwrite';
+import {
+  createPortableAppwriteClients,
+  createQmuseAppwriteRuntime,
+  type Models,
+} from '@qmuse/appwrite-runtime-sdk';
+import { getMuseRuntimeConfig } from '../runtime/qmuse';
+import { platformFetch, platformStorage } from './platform';
+
+function getQmuseLoginUserId(): string | null {
+  return null;
+}
+
+const clients = createPortableAppwriteClients({
+  fetch: platformFetch,
+  storage: platformStorage,
+});
+
+const runtime = createQmuseAppwriteRuntime({
+  ...clients,
+  getMuseRuntime: getMuseRuntimeConfig,
+  getQmuseLoginUserId,
+  fetch: platformFetch,
 });
 
 export const initAppwrite = runtime.init;
 export const getAppwriteClients = runtime.getClients;
+export const getCurrentAppwriteUser = runtime.getCurrentUser;
+export const refreshAppwriteSession = runtime.refreshSession;
+export const listQmuseRows = runtime.listRows;
+export const getQmuseRow = runtime.getRow;
 export const createQmuseRow = runtime.createRow;
 export const updateQmuseRow = runtime.updateRow;
+export const deleteQmuseRow = runtime.deleteRow;
+
+export type { Models };
+export { ID, Permission, Query, Role };
 ```
 
-`createQmuseAppwriteRuntime()` 返回的实例应在 `src/services/appwrite.ts` 中作为模块级单例复用。实例创建后会立即异步初始化；`initAppwrite()` 返回同一个共享 Promise，`getAppwriteClients()` 和所有 CRUD 也会等待该初始化。SDK 会在内部观察每个公开方法返回的 Promise，因此忽略后台初始化或数据调用不会产生影响应用运行的全局 `unhandledrejection`；显式等待仍会收到同一个 Promise 的原始错误，初始化失败后下一次调用可以重试。
+### 5. 在 Taro 应用启动时初始化
 
-工厂创建阶段不因缺少 `fetch` 或 Runtime 配置异常同步抛错；这类问题会进入共享初始化 Promise。异步审计链路中的 Runtime 读取、URL 构造和请求错误也不会改变 CRUD 结果。
+```tsx
+// src/app.tsx
+import type { PropsWithChildren } from 'react';
+import { useLaunch } from '@tarojs/taro';
+import { initAppwrite } from './services/appwrite';
 
-`getCurrentAppwriteUser()` 同样是异步方法，使用时需要 `await`；它会先等待共享初始化，不会在调用阶段同步抛错。
+export default function App({ children }: PropsWithChildren) {
+  useLaunch(() => {
+    initAppwrite().catch((error) => {
+      console.error('Appwrite initialization failed', error);
+    });
+  });
 
-### 内部结构
+  return children;
+}
+```
 
-- `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 观察。
+业务页面和服务可以直接复用与 React 应用相同的 CRUD 方法。
 
-不要在页面、hook 或业务服务中直接创建 Appwrite SDK 实例，或绕过 `createRow` / `updateRow` 写入审计字段。
+## 数据操作
 
-新增、更新和删除会由 SDK 内置地异步上报最小审计事件；上报不阻塞 CRUD，也不向业务代码暴露 hook、开关或 API Key。SDK 不上传业务 data、custom-token 或 Session。项目内置的 Appwrite 事件云函数仍负责成功 mutation 的可靠服务端审计与重试；浏览器侧上报只用于补充安全信号。
+### 查询列表
 
-## Badges
+```ts
+const result = await listQmuseRows<TodoRow>({
+  tableId: 'todos',
+  queries: [Query.equal('completed', false)],
+  limit: 20,
+  cursor: previousPageLastRowId,
+});
+```
 
-[![TNPM version][tnpm-image]][tnpm-url]
-[![TNPM downloads][tnpm-downloads-image]][tnpm-url]
-![install-node 20](https://hitu.alipay.com/badge/tnpm?title=install-node&value=20)
+### 查询单行
 
-[tnpm-image]: https://npm.alibaba-inc.com/badge/v/@alipay/appwrite-runtime-sdk.svg
-[tnpm-url]: https://npm.alibaba-inc.com/package/@alipay/appwrite-runtime-sdk
-[tnpm-downloads-image]: https://npm.alibaba-inc.com/badge/d/@alipay/appwrite-runtime-sdk.svg
+```ts
+const row = await getQmuseRow<TodoRow>({
+  tableId: 'todos',
+  rowId: 'todo_001',
+});
+```
 
----
+### 新增
 
-## 准备工作
+```ts
+const row = await createQmuseRow<TodoRow>({
+  tableId: 'todos',
+  data: {
+    title: 'Read the SDK documentation',
+    completed: false,
+  },
+});
+```
 
-- 安装 [nodejs](https://nodejs.org/en/)
-- 使用最新版本的 [tnpm](http://web.npm.alibaba-inc.com/)
+不传 `rowId` 时由 SDK 生成唯一 ID。
 
-## 开发
+### 更新
 
-```bash
-# 安装依赖
-$ tnpm install
+```ts
+await updateQmuseRow<TodoRow>({
+  tableId: 'todos',
+  rowId: 'todo_001',
+  data: { completed: true },
+});
+```
 
-# 构建与检查
-$ npm run build
-$ npm run lint
-$ npm test
+### 删除
+
+```ts
+await deleteQmuseRow({
+  tableId: 'todos',
+  rowId: 'todo_001',
+});
 ```
 
-## 发布
+## 公开 API
+
+| API                | 返回值                          | 用途                                     |
+| ------------------ | ------------------------------- | ---------------------------------------- |
+| `init()`           | `Promise<void>`                 | 初始化 Runtime 和当前用户 Session        |
+| `getClients()`     | `Promise<QmuseAppwriteClients>` | 获取已配置的客户端及 `databaseId`        |
+| `getCurrentUser()` | `Promise<AppwriteUser>`         | 获取当前 Appwrite 用户                   |
+| `refreshSession()` | `Promise<void>`                 | 主动同步 QMuse 登录态和 Appwrite Session |
+| `listRows()`       | `Promise<Models.RowList<Row>>`  | 分页查询表数据                           |
+| `getRow()`         | `Promise<Row>`                  | 查询单行数据                             |
+| `createRow()`      | `Promise<Row>`                  | 新增数据                                 |
+| `updateRow()`      | `Promise<Row>`                  | 更新数据                                 |
+| `deleteRow()`      | `Promise<void>`                 | 删除数据                                 |
 
-该 SDK 不发布为海兔资产；构建、测试和公网 npm 发布均使用独立工具链。
+所有公开方法都是异步方法。页面和业务服务应使用 `await` 或显式处理 Promise 错误。
 
-### 公网 `@qmuse` 包
+## 接入约束
 
-先在 `package.json` 设定未发布的正式语义化版本，再执行：
+- 每个应用只创建一个 `createQmuseAppwriteRuntime()` 实例。
+- React 应用使用 Appwrite Web SDK 客户端；Taro 应用使用 `createPortableAppwriteClients()`。
+- H5、支付宝小程序和微信小程序必须使用相同的 `appId`、`env` 和 `domain` 配置来源。
+- React 应用的 `getQmuseLoginUserId()` 只返回有效的用户 ID 或 `null`；Taro 应用固定返回 `null`。
+- 业务代码通过 Runtime 的 CRUD 方法读写数据，不直接拼接 Appwrite HTTP 接口。
+
+## SDK 开发
 
 ```bash
-npm run publish:public
+tnpm install
+npm run lint
+npm test
+npm run build
 ```
 
-脚本会先询问发布 tag，直接回车默认发布到 `dev`，也可以输入 `latest`。它会验证 npmjs 登录态、检查版本是否已存在，并运行 CI 与构建。确认后，它只在发布期间把包名临时改为 `@qmuse/appwrite-runtime-sdk`，退出时恢复本地 `package.json`。
+## 发布
 
-首次正式发布建议先选择 `dev` 验证；确认无误后，可直接再次执行脚本并选择 `latest`，或移动 `latest` tag：
+先在 `package.json` 中设置未发布的语义化版本，然后执行：
 
 ```bash
-npm dist-tag add @qmuse/appwrite-runtime-sdk@<version> latest --registry https://registry.npmjs.org/
+npm run publish:public
 ```
+
+发布脚本默认使用 `dev` tag，也可以选择 `latest`。正式发布前应确保 lint、测试和构建全部通过。

package/dist/index.d.ts

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

package/dist/index.js

@@ -1 +1,2 @@
-export { createQmuseAppwriteRuntime } from "./runtime";
+export { createQmuseAppwriteRuntime } from "./runtime";
+export { createPortableAppwriteClients } from "./portable";

package/dist/portable.d.ts

@@ -0,0 +1,6 @@
+import type { AppwriteAccountLike, AppwriteClientLike, AppwriteTablesDBLike, PortableAppwriteClientsOptions } from './types';
+export declare function createPortableAppwriteClients(options: PortableAppwriteClientsOptions): {
+    client: AppwriteClientLike;
+    account: AppwriteAccountLike;
+    tablesDB: AppwriteTablesDBLike;
+};

package/dist/portable.js

@@ -0,0 +1,379 @@
+import _regeneratorRuntime from "@babel/runtime/helpers/esm/regeneratorRuntime";
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import _createClass from "@babel/runtime/helpers/esm/createClass";
+import _classCallCheck from "@babel/runtime/helpers/esm/classCallCheck";
+import _assertThisInitialized from "@babel/runtime/helpers/esm/assertThisInitialized";
+import _inherits from "@babel/runtime/helpers/esm/inherits";
+import _createSuper from "@babel/runtime/helpers/esm/createSuper";
+import _wrapNativeSuper from "@babel/runtime/helpers/esm/wrapNativeSuper";
+import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+var PortableAppwriteError = /*#__PURE__*/function (_Error) {
+  _inherits(PortableAppwriteError, _Error);
+  var _super = _createSuper(PortableAppwriteError);
+  function PortableAppwriteError(_ref) {
+    var _this;
+    var message = _ref.message,
+      code = _ref.code,
+      type = _ref.type,
+      response = _ref.response;
+    _classCallCheck(this, PortableAppwriteError);
+    _this = _super.call(this, message);
+    _defineProperty(_assertThisInitialized(_this), "code", void 0);
+    _defineProperty(_assertThisInitialized(_this), "type", void 0);
+    _defineProperty(_assertThisInitialized(_this), "response", void 0);
+    _this.name = 'PortableAppwriteError';
+    _this.code = code;
+    _this.type = type;
+    _this.response = response;
+    return _this;
+  }
+  return _createClass(PortableAppwriteError);
+}( /*#__PURE__*/_wrapNativeSuper(Error));
+function isRecord(value) {
+  return Boolean(value) && _typeof(value) === 'object' && !Array.isArray(value);
+}
+function appendQuery(entries, key, value) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach(function (item, index) {
+      return appendQuery(entries, "".concat(key, "[").concat(index, "]"), item);
+    });
+    return;
+  }
+  entries.push("".concat(encodeURIComponent(key), "=").concat(encodeURIComponent(String(value))));
+}
+function createRequestUrl(endpoint, path, query) {
+  var url = "".concat(endpoint).concat(path);
+  var entries = [];
+  Object.entries(query || {}).forEach(function (_ref2) {
+    var _ref3 = _slicedToArray(_ref2, 2),
+      key = _ref3[0],
+      value = _ref3[1];
+    return appendQuery(entries, key, value);
+  });
+  if (entries.length === 0) {
+    return url;
+  }
+  return "".concat(url).concat(url.includes('?') ? '&' : '?').concat(entries.join('&'));
+}
+var PortableAppwriteClient = /*#__PURE__*/function () {
+  function PortableAppwriteClient(options) {
+    _classCallCheck(this, PortableAppwriteClient);
+    _defineProperty(this, "config", {
+      endpoint: '',
+      projectId: ''
+    });
+    _defineProperty(this, "memoryFallbackCookies", null);
+    this.options = options;
+  }
+  _createClass(PortableAppwriteClient, [{
+    key: "setEndpoint",
+    value: function setEndpoint(endpoint) {
+      if (!endpoint) {
+        throw new TypeError('Appwrite endpoint is required');
+      }
+      this.config.endpoint = endpoint.replace(/\/$/, '');
+      return this;
+    }
+  }, {
+    key: "setProject",
+    value: function setProject(projectId) {
+      if (!projectId) {
+        throw new TypeError('Appwrite projectId is required');
+      }
+      this.config.projectId = projectId;
+      this.memoryFallbackCookies = this.readStoredFallbackCookies();
+      return this;
+    }
+  }, {
+    key: "call",
+    value: function () {
+      var _call = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(_ref4) {
+        var _data;
+        var method, path, query, body, url, headers, fallbackCookies, response, responseText, data, error, nextFallbackCookies;
+        return _regeneratorRuntime().wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              method = _ref4.method, path = _ref4.path, query = _ref4.query, body = _ref4.body;
+              this.assertConfigured();
+              url = createRequestUrl(this.config.endpoint, path, query);
+              headers = {
+                'X-Appwrite-Project': this.config.projectId
+              };
+              fallbackCookies = this.getFallbackCookies();
+              if (fallbackCookies) {
+                headers['X-Fallback-Cookies'] = fallbackCookies;
+              }
+              if (body) {
+                headers['Content-Type'] = 'application/json';
+              }
+              _context.next = 9;
+              return this.options.fetch(url, _objectSpread({
+                method: method,
+                credentials: 'include',
+                headers: headers
+              }, body ? {
+                body: JSON.stringify(body)
+              } : {}));
+            case 9:
+              response = _context.sent;
+              _context.next = 12;
+              return response.text();
+            case 12:
+              responseText = _context.sent;
+              data = undefined;
+              if (responseText) {
+                try {
+                  data = JSON.parse(responseText);
+                } catch (_unused) {
+                  data = {
+                    message: responseText
+                  };
+                }
+              }
+              if (response.ok) {
+                _context.next = 18;
+                break;
+              }
+              error = isRecord(data) ? data : {};
+              throw new PortableAppwriteError({
+                message: typeof error.message === 'string' ? error.message : "Appwrite request failed: ".concat(response.status),
+                code: response.status,
+                type: typeof error.type === 'string' ? error.type : undefined,
+                response: responseText || undefined
+              });
+            case 18:
+              nextFallbackCookies = response.headers.get('X-Fallback-Cookies');
+              if (nextFallbackCookies) {
+                this.setFallbackCookies(nextFallbackCookies);
+              }
+              return _context.abrupt("return", (_data = data) !== null && _data !== void 0 ? _data : {});
+            case 21:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee, this);
+      }));
+      function call(_x) {
+        return _call.apply(this, arguments);
+      }
+      return call;
+    }()
+  }, {
+    key: "clearFallbackCookies",
+    value: function clearFallbackCookies() {
+      this.memoryFallbackCookies = null;
+      var storage = this.options.storage;
+      if (storage && this.config.projectId) {
+        storage.removeItem(this.getStorageKey());
+      }
+    }
+  }, {
+    key: "assertConfigured",
+    value: function assertConfigured() {
+      if (!this.config.endpoint || !this.config.projectId) {
+        throw new Error('Portable Appwrite client is not initialized');
+      }
+    }
+  }, {
+    key: "getStorageKey",
+    value: function getStorageKey() {
+      var prefix = this.options.storageKeyPrefix || 'qmuse:appwrite:session';
+      return "".concat(prefix, ":").concat(this.config.projectId);
+    }
+  }, {
+    key: "readStoredFallbackCookies",
+    value: function readStoredFallbackCookies() {
+      if (!this.options.storage || !this.config.projectId) {
+        return null;
+      }
+      var stored = this.options.storage.getItem(this.getStorageKey());
+      return typeof stored === 'string' && stored ? stored : null;
+    }
+  }, {
+    key: "getFallbackCookies",
+    value: function getFallbackCookies() {
+      return this.memoryFallbackCookies || this.readStoredFallbackCookies();
+    }
+  }, {
+    key: "setFallbackCookies",
+    value: function setFallbackCookies(value) {
+      var _this$options$storage;
+      this.memoryFallbackCookies = value;
+      (_this$options$storage = this.options.storage) === null || _this$options$storage === void 0 || _this$options$storage.setItem(this.getStorageKey(), value);
+    }
+  }]);
+  return PortableAppwriteClient;
+}();
+var PortableAccount = /*#__PURE__*/function () {
+  function PortableAccount(client) {
+    _classCallCheck(this, PortableAccount);
+    this.client = client;
+  }
+  _createClass(PortableAccount, [{
+    key: "get",
+    value: function get() {
+      return this.client.call({
+        method: 'GET',
+        path: '/account'
+      });
+    }
+  }, {
+    key: "getSession",
+    value: function getSession(_ref5) {
+      var sessionId = _ref5.sessionId;
+      return this.client.call({
+        method: 'GET',
+        path: "/account/sessions/".concat(sessionId)
+      });
+    }
+  }, {
+    key: "deleteSession",
+    value: function () {
+      var _deleteSession = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee2(_ref6) {
+        var sessionId;
+        return _regeneratorRuntime().wrap(function _callee2$(_context2) {
+          while (1) switch (_context2.prev = _context2.next) {
+            case 0:
+              sessionId = _ref6.sessionId;
+              _context2.prev = 1;
+              _context2.next = 4;
+              return this.client.call({
+                method: 'DELETE',
+                path: "/account/sessions/".concat(sessionId)
+              });
+            case 4:
+              _context2.prev = 4;
+              this.client.clearFallbackCookies();
+              return _context2.finish(4);
+            case 7:
+            case "end":
+              return _context2.stop();
+          }
+        }, _callee2, this, [[1,, 4, 7]]);
+      }));
+      function deleteSession(_x2) {
+        return _deleteSession.apply(this, arguments);
+      }
+      return deleteSession;
+    }()
+  }, {
+    key: "createAnonymousSession",
+    value: function createAnonymousSession() {
+      return this.client.call({
+        method: 'POST',
+        path: '/account/sessions/anonymous'
+      });
+    }
+  }, {
+    key: "createSession",
+    value: function createSession(_ref7) {
+      var userId = _ref7.userId,
+        secret = _ref7.secret;
+      return this.client.call({
+        method: 'POST',
+        path: '/account/sessions/token',
+        body: {
+          userId: userId,
+          secret: secret
+        }
+      });
+    }
+  }]);
+  return PortableAccount;
+}();
+var PortableTablesDB = /*#__PURE__*/function () {
+  function PortableTablesDB(client) {
+    _classCallCheck(this, PortableTablesDB);
+    this.client = client;
+  }
+  _createClass(PortableTablesDB, [{
+    key: "listRows",
+    value: function listRows(_ref8) {
+      var databaseId = _ref8.databaseId,
+        tableId = _ref8.tableId,
+        queries = _ref8.queries;
+      return this.client.call({
+        method: 'GET',
+        path: this.rowsPath(databaseId, tableId),
+        query: {
+          queries: queries
+        }
+      });
+    }
+  }, {
+    key: "getRow",
+    value: function getRow(_ref9) {
+      var databaseId = _ref9.databaseId,
+        tableId = _ref9.tableId,
+        rowId = _ref9.rowId;
+      return this.client.call({
+        method: 'GET',
+        path: "".concat(this.rowsPath(databaseId, tableId), "/").concat(encodeURIComponent(rowId))
+      });
+    }
+  }, {
+    key: "createRow",
+    value: function createRow(_ref10) {
+      var databaseId = _ref10.databaseId,
+        tableId = _ref10.tableId,
+        rowId = _ref10.rowId,
+        data = _ref10.data,
+        permissions = _ref10.permissions;
+      return this.client.call({
+        method: 'POST',
+        path: this.rowsPath(databaseId, tableId),
+        body: {
+          rowId: rowId,
+          data: data,
+          permissions: permissions
+        }
+      });
+    }
+  }, {
+    key: "updateRow",
+    value: function updateRow(_ref11) {
+      var databaseId = _ref11.databaseId,
+        tableId = _ref11.tableId,
+        rowId = _ref11.rowId,
+        data = _ref11.data;
+      return this.client.call({
+        method: 'PATCH',
+        path: "".concat(this.rowsPath(databaseId, tableId), "/").concat(encodeURIComponent(rowId)),
+        body: {
+          data: data
+        }
+      });
+    }
+  }, {
+    key: "deleteRow",
+    value: function deleteRow(_ref12) {
+      var databaseId = _ref12.databaseId,
+        tableId = _ref12.tableId,
+        rowId = _ref12.rowId;
+      return this.client.call({
+        method: 'DELETE',
+        path: "".concat(this.rowsPath(databaseId, tableId), "/").concat(encodeURIComponent(rowId))
+      });
+    }
+  }, {
+    key: "rowsPath",
+    value: function rowsPath(databaseId, tableId) {
+      return "/tablesdb/".concat(encodeURIComponent(databaseId), "/tables/").concat(encodeURIComponent(tableId), "/rows");
+    }
+  }]);
+  return PortableTablesDB;
+}();
+export function createPortableAppwriteClients(options) {
+  var client = new PortableAppwriteClient(options);
+  return {
+    client: client,
+    account: new PortableAccount(client),
+    tablesDB: new PortableTablesDB(client)
+  };
+}

package/dist/runtime/AppwriteSessionCoordinator.js

@@ -5,7 +5,7 @@ import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 import _classCallCheck from "@babel/runtime/helpers/esm/classCallCheck";
 import _createClass from "@babel/runtime/helpers/esm/createClass";
 import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
-import { createResponseError, getErrorCode, isRecord, readResponsePayload } from "./utils";
+import { createResponseError, getErrorCode, isRecord, readResponsePayload, resolveRuntimeUrl } from "./utils";
 export var AppwriteSessionCoordinator = /*#__PURE__*/function () {
   function AppwriteSessionCoordinator(options, request) {
     _classCallCheck(this, AppwriteSessionCoordinator);
@@ -209,7 +209,7 @@ export var AppwriteSessionCoordinator = /*#__PURE__*/function () {
             case 0:
               runtime = this.getMuseRuntime();
               _context6.next = 3;
-              return this.request(new URL('/runtime/appwrite/config', runtime.domain).toString(), {
+              return this.request(resolveRuntimeUrl('/runtime/appwrite/config', runtime.domain), {
                 method: 'POST',
                 credentials: 'include',
                 headers: {
@@ -380,31 +380,24 @@ export var AppwriteSessionCoordinator = /*#__PURE__*/function () {
           while (1) switch (_context10.prev = _context10.next) {
             case 0:
               forceReplace = _args10.length > 0 && _args10[0] !== undefined ? _args10[0] : false;
-              if (this.state.currentUser) {
-                _context10.next = 4;
-                break;
-              }
-              _context10.next = 4;
-              return this.tryCacheCurrentSession();
-            case 4:
               if (!(!forceReplace && this.state.currentUser && this.state.currentSessionProvider === 'anonymous')) {
-                _context10.next = 7;
+                _context10.next = 4;
                 break;
               }
               this.state.confirmedQmuseUserId = null;
               return _context10.abrupt("return");
-            case 7:
-              _context10.next = 9;
+            case 4:
+              _context10.next = 6;
               return this.deleteCurrentSession();
-            case 9:
-              _context10.next = 11;
+            case 6:
+              _context10.next = 8;
               return this.options.account.createAnonymousSession();
-            case 11:
-              _context10.next = 13;
+            case 8:
+              _context10.next = 10;
               return this.cacheCurrentSession();
-            case 13:
+            case 10:
               this.state.confirmedQmuseUserId = null;
-            case 14:
+            case 11:
             case "end":
               return _context10.stop();
           }
@@ -426,7 +419,7 @@ export var AppwriteSessionCoordinator = /*#__PURE__*/function () {
               runtime = this.getMuseRuntime();
               config = this.requireRuntimeConfig();
               _context11.next = 4;
-              return this.request(new URL(config.authTokenEndpoint, runtime.domain).toString(), {
+              return this.request(resolveRuntimeUrl(config.authTokenEndpoint, runtime.domain), {
                 method: 'POST',
                 credentials: 'include',
                 headers: {
@@ -434,7 +427,6 @@ export var AppwriteSessionCoordinator = /*#__PURE__*/function () {
                 },
                 body: JSON.stringify({
                   appId: runtime.appId,
-                  appVersionId: runtime.appVersionId,
                   env: runtime.env,
                   projectId: config.projectId
                 })
@@ -493,34 +485,27 @@ export var AppwriteSessionCoordinator = /*#__PURE__*/function () {
           while (1) switch (_context12.prev = _context12.next) {
             case 0:
               qmuseUserId = _ref2.qmuseUserId, userId = _ref2.userId, secret = _ref2.secret, _ref2$forceReplace = _ref2.forceReplace, forceReplace = _ref2$forceReplace === void 0 ? false : _ref2$forceReplace;
-              if (this.state.currentUser) {
-                _context12.next = 4;
-                break;
-              }
-              _context12.next = 4;
-              return this.tryCacheCurrentSession();
-            case 4:
               if (!(!forceReplace && this.state.currentUser && this.state.currentSessionProvider !== 'anonymous' && this.state.currentUser.$id === userId)) {
-                _context12.next = 7;
+                _context12.next = 4;
                 break;
               }
               this.state.confirmedQmuseUserId = qmuseUserId;
               return _context12.abrupt("return");
-            case 7:
-              _context12.next = 9;
+            case 4:
+              _context12.next = 6;
               return this.deleteCurrentSession();
-            case 9:
-              _context12.next = 11;
+            case 6:
+              _context12.next = 8;
               return this.options.account.createSession({
                 userId: userId,
                 secret: secret
               });
-            case 11:
-              _context12.next = 13;
+            case 8:
+              _context12.next = 10;
               return this.cacheCurrentSession();
-            case 13:
+            case 10:
               this.state.confirmedQmuseUserId = qmuseUserId;
-            case 14:
+            case 11:
             case "end":
               return _context12.stop();
           }

package/dist/runtime/MutationAuditReporter.js

@@ -3,7 +3,7 @@ import _regeneratorRuntime from "@babel/runtime/helpers/esm/regeneratorRuntime";
 import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 import _classCallCheck from "@babel/runtime/helpers/esm/classCallCheck";
 import _createClass from "@babel/runtime/helpers/esm/createClass";
-import { getErrorCode } from "./utils";
+import { getErrorCode, resolveRuntimeUrl } from "./utils";
 export var MutationAuditReporter = /*#__PURE__*/function () {
   function MutationAuditReporter(request, getMuseRuntime) {
     _classCallCheck(this, MutationAuditReporter);
@@ -73,7 +73,7 @@ export var MutationAuditReporter = /*#__PURE__*/function () {
         var runtime = this.getMuseRuntime();
         globalThis.setTimeout(function () {
           try {
-            void Promise.resolve(_this.request(new URL('/api/runtime/appwrite/mutation-events', runtime.domain).toString(), {
+            void Promise.resolve(_this.request(resolveRuntimeUrl('/api/runtime/appwrite/mutation-events', runtime.domain), {
               method: 'POST',
               credentials: 'include',
               keepalive: true,

package/dist/runtime/utils.d.ts

@@ -8,6 +8,7 @@ export declare function createResponseError({ payload, status, fallbackMessage,
 }): Error;
 export declare function readResponsePayload(response: Response): Promise<Record<string, unknown> | null>;
 export declare function createFetchRequest(configuredFetch?: typeof globalThis.fetch): typeof globalThis.fetch;
+export declare function resolveRuntimeUrl(pathOrUrl: string, domain: string): string;
 type PublicPromiseOperation = (...args: never[]) => Promise<unknown>;
 export declare function observePublicPromise<TOperation extends PublicPromiseOperation>(operation: TOperation): TOperation;
 export {};

package/dist/runtime/utils.js

@@ -8,8 +8,19 @@ export function getErrorCode(error) {
   if (!isRecord(error)) {
     return null;
   }
-  var code = Number(error.code);
-  return Number.isFinite(code) ? code : null;
+  var response = isRecord(error.response) ? error.response : null;
+  var candidates = [error.code, error.status, error.statusCode, response === null || response === void 0 ? void 0 : response.status, response === null || response === void 0 ? void 0 : response.statusCode];
+  for (var _i = 0, _candidates = candidates; _i < _candidates.length; _i++) {
+    var candidate = _candidates[_i];
+    if (candidate === undefined || candidate === null || candidate === '') {
+      continue;
+    }
+    var code = Number(candidate);
+    if (Number.isFinite(code)) {
+      return code;
+    }
+  }
+  return null;
 }
 export function createResponseError(_ref) {
   var _payload$code, _payload$type;
@@ -57,6 +68,14 @@ export function createFetchRequest(configuredFetch) {
     return fetchImplementation(input, init);
   };
 }
+export function resolveRuntimeUrl(pathOrUrl, domain) {
+  if (/^https?:\/\//i.test(pathOrUrl)) {
+    return pathOrUrl;
+  }
+  var origin = domain.replace(/\/+$/, '');
+  var path = pathOrUrl.replace(/^\/+/, '');
+  return "".concat(origin, "/").concat(path);
+}
 export function observePublicPromise(operation) {
   return function () {
     var promise = operation.apply(void 0, arguments);

package/dist/types.d.ts

@@ -3,7 +3,6 @@ export type { Models } from 'appwrite';
 export type QmuseEnvironment = 'dev' | 'prod';
 export interface QmuseRuntimeContext {
     appId: string;
-    appVersionId: string;
     env: QmuseEnvironment;
     domain: string;
 }
@@ -27,6 +26,16 @@ export interface AppwriteClientLike {
     setEndpoint(endpoint: string): AppwriteClientLike;
     setProject(projectId: string): AppwriteClientLike;
 }
+export interface AppwriteRuntimeStorage {
+    getItem(key: string): string | null | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface PortableAppwriteClientsOptions {
+    fetch: typeof globalThis.fetch;
+    storage?: AppwriteRuntimeStorage;
+    storageKeyPrefix?: string;
+}
 export interface AppwriteAccountLike {
     get(): Promise<AppwriteUser>;
     getSession(input: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmuse/appwrite-runtime-sdk",
-  "version": "1.0.4",
+  "version": "1.0.5-dev.1",
   "description": "QMuse Appwrite browser runtime SDK",
   "repository": {
     "type": "git",