@svadmin/appwrite 0.3.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@svadmin/appwrite",
+  "version": "0.3.0",
+  "description": "Appwrite adapters — DataProvider, AuthProvider, LiveProvider for svadmin",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src/**/*"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@svadmin/core": "^0.3.0",
+    "appwrite": ">=14.0.0"
+  },
+  "keywords": ["svadmin", "appwrite", "data-provider", "auth-provider", "live-provider"],
+  "license": "MIT",
+  "author": "zuohuadong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zuohuadong/svadmin.git"
+  },
+  "homepage": "https://github.com/zuohuadong/svadmin#readme",
+  "bugs": {
+    "url": "https://github.com/zuohuadong/svadmin/issues"
+  }
+}

package/src/appwrite.test.ts

@@ -0,0 +1,227 @@
+// @svadmin/appwrite — Unit Tests
+import { describe, test, expect, mock } from 'bun:test';
+import { createAppwriteDataProvider } from './data-provider';
+import { createAppwriteAuthProvider } from './auth-provider';
+import { createAppwriteLiveProvider } from './live-provider';
+
+// ─── Mock Appwrite Databases ────────────────────────────────
+
+function createMockDatabases() {
+  return {
+    listDocuments: mock(async (_db: string, _col: string, _q?: string[]) => ({
+      documents: [{ $id: '1', name: 'Test' }, { $id: '2', name: 'Test2' }],
+      total: 2,
+    })),
+    getDocument: mock(async (_db: string, _col: string, _id: string) => ({
+      $id: _id, name: 'Test',
+    })),
+    createDocument: mock(async (_db: string, _col: string, _docId: string, data: Record<string, unknown>) => ({
+      $id: 'new-1', ...data,
+    })),
+    updateDocument: mock(async (_db: string, _col: string, _docId: string, data: Record<string, unknown>) => ({
+      $id: _docId, ...data,
+    })),
+    deleteDocument: mock(async () => {}),
+  };
+}
+
+// ─── Mock Appwrite Account ──────────────────────────────────
+
+function createMockAccount(overrides: Record<string, unknown> = {}) {
+  return {
+    createEmailPasswordSession: mock(async () => ({ $id: 'session-1' })),
+    deleteSession: mock(async () => {}),
+    get: mock(async () => ({ $id: 'user-1', name: 'Admin', email: 'admin@test.com', prefs: {} })),
+    create: mock(async () => ({ $id: 'user-2' })),
+    createRecovery: mock(async () => ({})),
+    updatePassword: mock(async () => ({})),
+    ...overrides,
+  };
+}
+
+// ─── DataProvider Tests ─────────────────────────────────────
+
+describe('Appwrite DataProvider', () => {
+  test('getList returns data with total', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    const result = await dp.getList({ resource: 'posts' });
+    expect(result.data).toHaveLength(2);
+    expect(result.total).toBe(2);
+    expect(db.listDocuments).toHaveBeenCalledTimes(1);
+  });
+
+  test('getList passes pagination as queries', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    await dp.getList({ resource: 'posts', pagination: { current: 2, pageSize: 5 } });
+    const queries = db.listDocuments.mock.calls[0][2] as string[];
+    expect(queries).toContain('limit(5)');
+    expect(queries).toContain('offset(5)');
+  });
+
+  test('getList passes sorters as queries', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    await dp.getList({ resource: 'posts', sorters: [{ field: 'name', order: 'desc' }] });
+    const queries = db.listDocuments.mock.calls[0][2] as string[];
+    expect(queries.some((q: string) => q.includes('orderDesc'))).toBe(true);
+  });
+
+  test('getList passes filters as queries', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    await dp.getList({ resource: 'posts', filters: [{ field: 'status', operator: 'eq', value: 'active' }] });
+    const queries = db.listDocuments.mock.calls[0][2] as string[];
+    expect(queries.some((q: string) => q.includes('equal'))).toBe(true);
+  });
+
+  test('getOne returns single record', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    const result = await dp.getOne({ resource: 'posts', id: '1' });
+    expect(result.data).toHaveProperty('$id', '1');
+  });
+
+  test('create returns new record', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    const result = await dp.create({ resource: 'posts', variables: { name: 'New Post' } });
+    expect(result.data).toHaveProperty('name', 'New Post');
+  });
+
+  test('update returns updated record', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    const result = await dp.update({ resource: 'posts', id: '1', variables: { name: 'Updated' } });
+    expect(result.data).toHaveProperty('name', 'Updated');
+  });
+
+  test('deleteOne calls deleteDocument', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    await dp.deleteOne({ resource: 'posts', id: '1' });
+    expect(db.deleteDocument).toHaveBeenCalledTimes(1);
+  });
+
+  test('getMany fetches by ids', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    const result = await dp.getMany!({ resource: 'posts', ids: ['1', '2'] });
+    expect(result.data).toHaveLength(2);
+  });
+
+  test('deleteMany deletes each id', async () => {
+    const db = createMockDatabases();
+    const dp = createAppwriteDataProvider({ databases: db, databaseId: 'main' });
+    await dp.deleteMany!({ resource: 'posts', ids: ['1', '2'] });
+    expect(db.deleteDocument).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ─── AuthProvider Tests ─────────────────────────────────────
+
+describe('Appwrite AuthProvider', () => {
+  test('login success', async () => {
+    const account = createMockAccount();
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.login({ email: 'admin@test.com', password: 'pass' });
+    expect(result.success).toBe(true);
+    expect(result.redirectTo).toBe('/');
+  });
+
+  test('login failure', async () => {
+    const account = createMockAccount({
+      createEmailPasswordSession: mock(async () => { throw new Error('Invalid credentials'); }),
+    });
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.login({ email: 'bad', password: 'bad' });
+    expect(result.success).toBe(false);
+    expect(result.error?.message).toBe('Invalid credentials');
+  });
+
+  test('logout success', async () => {
+    const account = createMockAccount();
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.logout();
+    expect(result.success).toBe(true);
+    expect(result.redirectTo).toBe('/login');
+  });
+
+  test('check returns authenticated', async () => {
+    const account = createMockAccount();
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.check();
+    expect(result.authenticated).toBe(true);
+  });
+
+  test('check returns not authenticated on error', async () => {
+    const account = createMockAccount({
+      get: mock(async () => { throw new Error('Unauthorized'); }),
+    });
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.check();
+    expect(result.authenticated).toBe(false);
+  });
+
+  test('getIdentity returns user', async () => {
+    const account = createMockAccount();
+    const auth = createAppwriteAuthProvider({ account });
+    const identity = await auth.getIdentity();
+    expect(identity).not.toBeNull();
+    expect(identity!.name).toBe('Admin');
+    expect(identity!.email).toBe('admin@test.com');
+  });
+
+  test('register success', async () => {
+    const account = createMockAccount();
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.register!({ email: 'new@test.com', password: 'pass123' });
+    expect(result.success).toBe(true);
+  });
+
+  test('onError with 401', async () => {
+    const account = createMockAccount();
+    const auth = createAppwriteAuthProvider({ account });
+    const result = await auth.onError!(new Error('401 Unauthorized'));
+    expect(result.logout).toBe(true);
+  });
+});
+
+// ─── LiveProvider Tests ─────────────────────────────────────
+
+describe('Appwrite LiveProvider', () => {
+  test('subscribe calls client.subscribe with correct channel', () => {
+    const unsubFn = mock(() => {});
+    const mockClient = {
+      subscribe: mock((_channels: string, _cb: unknown) => unsubFn),
+    };
+    const lp = createAppwriteLiveProvider({ client: mockClient, databaseId: 'main' });
+    const cb = mock(() => {});
+    const unsub = lp.subscribe({ resource: 'posts', callback: cb });
+
+    expect(mockClient.subscribe).toHaveBeenCalledTimes(1);
+    const channel = mockClient.subscribe.mock.calls[0][0];
+    expect(channel).toBe('databases.main.collections.posts.documents');
+
+    unsub();
+    expect(unsubFn).toHaveBeenCalledTimes(1);
+  });
+
+  test('subscribe maps create event to INSERT', () => {
+    let handler: ((payload: unknown) => void) | null = null;
+    const mockClient = {
+      subscribe: mock((_channels: string, cb: (payload: unknown) => void) => {
+        handler = cb;
+        return () => {};
+      }),
+    };
+    const lp = createAppwriteLiveProvider({ client: mockClient, databaseId: 'main' });
+    const cb = mock(() => {});
+    lp.subscribe({ resource: 'posts', callback: cb });
+
+    handler!({ events: ['databases.main.collections.posts.documents.*.create'], payload: { $id: '1' } });
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb.mock.calls[0][0].type).toBe('INSERT');
+  });
+});

package/src/auth-provider.ts

@@ -0,0 +1,111 @@
+// @svadmin/appwrite — Appwrite AuthProvider
+import type { AuthProvider, Identity, AuthActionResult, CheckResult } from '@svadmin/core';
+
+interface AppwriteAuthOptions {
+  /** Appwrite Account instance */
+  account: unknown; // Appwrite.Account
+}
+
+// Duck-typed Appwrite Account interface
+interface AppwriteAccount {
+  createEmailPasswordSession: (email: string, password: string) => Promise<Record<string, unknown>>;
+  deleteSession: (sessionId: string) => Promise<void>;
+  get: () => Promise<{ $id: string; name: string; email: string; prefs?: Record<string, unknown> }>;
+  create: (userId: string, email: string, password: string, name?: string) => Promise<Record<string, unknown>>;
+  createRecovery: (email: string, url: string) => Promise<Record<string, unknown>>;
+  updatePassword: (password: string, oldPassword?: string) => Promise<Record<string, unknown>>;
+}
+
+/**
+ * Create an AuthProvider backed by Appwrite Account.
+ *
+ * Usage:
+ * ```ts
+ * import { Account, Client } from 'appwrite';
+ * import { createAppwriteAuthProvider } from '@svadmin/appwrite';
+ *
+ * const client = new Client().setEndpoint('https://cloud.appwrite.io/v1').setProject('PROJECT_ID');
+ * const account = new Account(client);
+ * const authProvider = createAppwriteAuthProvider({ account });
+ * ```
+ */
+export function createAppwriteAuthProvider(options: AppwriteAuthOptions): AuthProvider {
+  const account = options.account as AppwriteAccount;
+
+  return {
+    async login({ email, password }: Record<string, unknown>): Promise<AuthActionResult> {
+      try {
+        await account.createEmailPasswordSession(email as string, password as string);
+        return { success: true, redirectTo: '/' };
+      } catch (err) {
+        return { success: false, error: { message: (err as Error).message } };
+      }
+    },
+
+    async logout(): Promise<AuthActionResult> {
+      try {
+        await account.deleteSession('current');
+        return { success: true, redirectTo: '/login' };
+      } catch (err) {
+        return { success: false, error: { message: (err as Error).message } };
+      }
+    },
+
+    async check(): Promise<CheckResult> {
+      try {
+        await account.get();
+        return { authenticated: true };
+      } catch {
+        return { authenticated: false, redirectTo: '/login', logout: true };
+      }
+    },
+
+    async getIdentity(): Promise<Identity | null> {
+      try {
+        const user = await account.get();
+        return {
+          id: user.$id,
+          name: user.name || user.email.split('@')[0],
+          email: user.email,
+          avatar: user.prefs?.avatar as string | undefined,
+        };
+      } catch {
+        return null;
+      }
+    },
+
+    async register({ email, password, name }: Record<string, unknown>): Promise<AuthActionResult> {
+      try {
+        await account.create('unique()', email as string, password as string, name as string | undefined);
+        return { success: true, redirectTo: '/login' };
+      } catch (err) {
+        return { success: false, error: { message: (err as Error).message } };
+      }
+    },
+
+    async forgotPassword({ email }: Record<string, unknown>): Promise<AuthActionResult> {
+      try {
+        await account.createRecovery(email as string, `${globalThis.location?.origin ?? ''}/update-password`);
+        return { success: true };
+      } catch (err) {
+        return { success: false, error: { message: (err as Error).message } };
+      }
+    },
+
+    async updatePassword({ password, oldPassword }: Record<string, unknown>): Promise<AuthActionResult> {
+      try {
+        await account.updatePassword(password as string, oldPassword as string | undefined);
+        return { success: true, redirectTo: '/' };
+      } catch (err) {
+        return { success: false, error: { message: (err as Error).message } };
+      }
+    },
+
+    async onError(error: unknown): Promise<{ redirectTo?: string; logout?: boolean }> {
+      if (error instanceof Error && (error.message.includes('401') || error.message.includes('unauthorized'))) {
+        return { redirectTo: '/login', logout: true };
+      }
+      return {};
+    },
+  };
+}

package/src/data-provider.ts

@@ -0,0 +1,138 @@
+// @svadmin/appwrite — Appwrite DataProvider
+// Maps svadmin CRUD operations to Appwrite SDK
+
+import type {
+  DataProvider, GetListParams, GetListResult, GetOneParams, GetOneResult,
+  CreateParams, CreateResult, UpdateParams, UpdateResult, DeleteParams, DeleteResult,
+  GetManyParams, GetManyResult, DeleteManyParams, DeleteManyResult, BaseRecord,
+} from '@svadmin/core';
+
+interface AppwriteProviderOptions {
+  /** Appwrite Databases instance */
+  databases: unknown; // Appwrite.Databases
+  /** Database ID */
+  databaseId: string;
+}
+
+// Duck-typed Appwrite SDK interfaces to avoid hard dependency
+interface AppwriteDatabases {
+  listDocuments: (dbId: string, collectionId: string, queries?: string[]) => Promise<{ documents: Record<string, unknown>[]; total: number }>;
+  getDocument: (dbId: string, collectionId: string, docId: string) => Promise<Record<string, unknown>>;
+  createDocument: (dbId: string, collectionId: string, docId: string, data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  updateDocument: (dbId: string, collectionId: string, docId: string, data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  deleteDocument: (dbId: string, collectionId: string, docId: string) => Promise<void>;
+}
+
+/**
+ * Map svadmin CrudOperator to Appwrite Query string.
+ * Uses Appwrite's query builder format: Query.equal('field', value)
+ */
+function mapFilter(field: string, operator: string, value: unknown): string | null {
+  switch (operator) {
+    case 'eq': return `equal("${field}", ${JSON.stringify(value)})`;
+    case 'ne': return `notEqual("${field}", ${JSON.stringify(value)})`;
+    case 'lt': return `lessThan("${field}", ${JSON.stringify(value)})`;
+    case 'gt': return `greaterThan("${field}", ${JSON.stringify(value)})`;
+    case 'lte': return `lessThanEqual("${field}", ${JSON.stringify(value)})`;
+    case 'gte': return `greaterThanEqual("${field}", ${JSON.stringify(value)})`;
+    case 'contains': return `search("${field}", ${JSON.stringify(value)})`;
+    case 'in': return `equal("${field}", ${JSON.stringify(value)})`;
+    case 'null': return `isNull("${field}")`;
+    case 'nnull': return `isNotNull("${field}")`;
+    case 'between': {
+      const [min, max] = value as [unknown, unknown];
+      return `between("${field}", ${JSON.stringify(min)}, ${JSON.stringify(max)})`;
+    }
+    default: return null;
+  }
+}
+
+/**
+ * Create a DataProvider backed by Appwrite.
+ *
+ * Usage:
+ * ```ts
+ * import { Databases, Client } from 'appwrite';
+ * import { createAppwriteDataProvider } from '@svadmin/appwrite';
+ *
+ * const client = new Client().setEndpoint('https://cloud.appwrite.io/v1').setProject('PROJECT_ID');
+ * const databases = new Databases(client);
+ * const dataProvider = createAppwriteDataProvider({ databases, databaseId: 'main' });
+ * ```
+ */
+export function createAppwriteDataProvider(options: AppwriteProviderOptions): DataProvider {
+  const { databases, databaseId } = options;
+  const db = databases as AppwriteDatabases;
+
+  return {
+    getApiUrl: () => 'appwrite',
+
+    async getList<TData extends BaseRecord = BaseRecord>(params: GetListParams): Promise<GetListResult<TData>> {
+      const { resource, pagination, sorters, filters } = params;
+      const queries: string[] = [];
+
+      if (pagination?.current && pagination?.pageSize) {
+        const offset = (pagination.current - 1) * pagination.pageSize;
+        queries.push(`limit(${pagination.pageSize})`);
+        queries.push(`offset(${offset})`);
+      }
+
+      if (sorters?.length) {
+        for (const sort of sorters) {
+          queries.push(sort.order === 'asc'
+            ? `orderAsc("${sort.field}")`
+            : `orderDesc("${sort.field}")`
+          );
+        }
+      }
+
+      if (filters?.length) {
+        for (const filter of filters) {
+          const q = mapFilter(filter.field, filter.operator, filter.value);
+          if (q) queries.push(q);
+        }
+      }
+
+      const result = await db.listDocuments(databaseId, resource, queries);
+      return {
+        data: result.documents as TData[],
+        total: result.total,
+      };
+    },
+
+    async getOne<TData extends BaseRecord = BaseRecord>(params: GetOneParams): Promise<GetOneResult<TData>> {
+      const doc = await db.getDocument(databaseId, params.resource, String(params.id));
+      return { data: doc as TData };
+    },
+
+    async create<TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateParams<TVariables>): Promise<CreateResult<TData>> {
+      const doc = await db.createDocument(databaseId, params.resource, 'unique()', params.variables as Record<string, unknown>);
+      return { data: doc as TData };
+    },
+
+    async update<TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateParams<TVariables>): Promise<UpdateResult<TData>> {
+      const doc = await db.updateDocument(databaseId, params.resource, String(params.id), params.variables as Record<string, unknown>);
+      return { data: doc as TData };
+    },
+
+    async deleteOne<TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteParams<TVariables>): Promise<DeleteResult<TData>> {
+      await db.deleteDocument(databaseId, params.resource, String(params.id));
+      return { data: { id: params.id } as unknown as TData };
+    },
+
+    async getMany<TData extends BaseRecord = BaseRecord>(params: GetManyParams): Promise<GetManyResult<TData>> {
+      const queries = [`equal("$id", ${JSON.stringify(params.ids.map(String))})`];
+      const result = await db.listDocuments(databaseId, params.resource, queries);
+      return { data: result.documents as TData[] };
+    },
+
+    async deleteMany<TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteManyParams<TVariables>): Promise<DeleteManyResult<TData>> {
+      const results: unknown[] = [];
+      for (const id of params.ids) {
+        await db.deleteDocument(databaseId, params.resource, String(id));
+        results.push({ id });
+      }
+      return { data: results as TData[] };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// @svadmin/appwrite — Appwrite adapters
+
+export { createAppwriteDataProvider } from './data-provider';
+export { createAppwriteAuthProvider } from './auth-provider';
+export { createAppwriteLiveProvider } from './live-provider';

package/src/live-provider.ts

@@ -0,0 +1,61 @@
+// @svadmin/appwrite — Appwrite LiveProvider (Realtime)
+import type { LiveProvider, LiveEvent } from '@svadmin/core';
+
+interface AppwriteLiveOptions {
+  /** Appwrite Client instance (must have realtime support) */
+  client: unknown; // Appwrite.Client
+  /** Database ID for document subscriptions */
+  databaseId: string;
+}
+
+// Duck-typed Appwrite realtime interface
+interface AppwriteClient {
+  subscribe: (channels: string | string[], callback: (payload: AppwriteRealtimePayload) => void) => { (): void };
+}
+
+interface AppwriteRealtimePayload {
+  events: string[];
+  payload: Record<string, unknown>;
+}
+
+/**
+ * Map Appwrite realtime events to svadmin LiveEvent types.
+ */
+function mapEventType(events: string[]): LiveEvent['type'] {
+  const eventStr = events.join(',');
+  if (eventStr.includes('.create')) return 'INSERT';
+  if (eventStr.includes('.update')) return 'UPDATE';
+  if (eventStr.includes('.delete')) return 'DELETE';
+  return 'UPDATE';
+}
+
+/**
+ * Create a LiveProvider backed by Appwrite Realtime.
+ *
+ * Usage:
+ * ```ts
+ * import { Client } from 'appwrite';
+ * import { createAppwriteLiveProvider } from '@svadmin/appwrite';
+ *
+ * const client = new Client().setEndpoint('https://cloud.appwrite.io/v1').setProject('PROJECT_ID');
+ * const liveProvider = createAppwriteLiveProvider({ client, databaseId: 'main' });
+ * ```
+ */
+export function createAppwriteLiveProvider(options: AppwriteLiveOptions): LiveProvider {
+  const client = options.client as AppwriteClient;
+  const { databaseId } = options;
+
+  return {
+    subscribe({ resource, callback }) {
+      const channel = `databases.${databaseId}.collections.${resource}.documents`;
+      const unsubscribe = client.subscribe(channel, (response) => {
+        callback({
+          type: mapEventType(response.events),
+          resource,
+          payload: response.payload,
+        });
+      });
+      return unsubscribe;
+    },
+  };
+}