refactor(web): integrate @objectstack/client SDK for data and metadata API

- Replace custom api.ts fetch wrapper with @objectstack/client singleton
- Align types/metadata.ts FieldType with @objectstack/spec (42 field types)
- Align AppDefinition with spec: name/label/active instead of id/name/status
- Refactor use-metadata.ts to use client.meta.* with mock fallback
- Refactor use-records.ts to use client.data.* with mock fallback
- Update FieldRenderer to support lookup, master_detail, multiselect, tags, etc.
- Update all pages/components for spec-aligned AppDefinition properties
- Update mock-data.ts to use spec-aligned types
- Update tests for new AppDefinition shape
- Update APPS_WEB_ROADMAP.md to reflect @objectstack/client usage

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

APPS_WEB_ROADMAP.md

@@ -130,7 +130,7 @@ interface AppDefinition {
 
 | Deliverable | File(s) | Description |
 |---|---|---|
-| API client | `src/lib/api.ts` | Typed fetch wrapper for `/api/v1/*` |
+| API client | `src/lib/api.ts` | `@objectstack/client` SDK with mock fallback |
 | Metadata types | `src/types/metadata.ts` | TypeScript interfaces for objects, fields, apps |
 | Metadata hooks | `src/hooks/use-metadata.ts` | TanStack Query hooks: `useAppObjects`, `useObjectDefinition` |
 | Record hooks | `src/hooks/use-records.ts` | TanStack Query hooks: `useRecords`, `useRecord`, mutations |
@@ -197,32 +197,31 @@ interface AppDefinition {
 
 ## 5. API Contract
 
-### Metadata Endpoints
+The frontend uses the official `@objectstack/client` SDK to interact with the server.
 
-```
-GET /api/v1/metadata/objects                → { objects: ObjectDefinition[] }
-GET /api/v1/metadata/objects/:name          → { object: ObjectDefinition }
-GET /api/v1/metadata/apps                   → { apps: AppDefinition[] }
-GET /api/v1/metadata/apps/:appId            → { app: AppDefinition }
-```
-
-### Data Endpoints
+### Client SDK Usage
 
-```
-GET    /api/v1/data/:objectName             → { records: Record[], total: number, page: number }
-GET    /api/v1/data/:objectName/:id         → { record: Record }
-POST   /api/v1/data/:objectName             → { record: Record }
-PATCH  /api/v1/data/:objectName/:id         → { record: Record }
-DELETE /api/v1/data/:objectName/:id         → { success: true }
-```
-
-### Query Parameters (List)
-
-```
-?page=1&pageSize=20&sort=name&order=asc&search=keyword&filter[status]=active
+```typescript
+import { ObjectStackClient } from '@objectstack/client';
+
+const client = new ObjectStackClient({ baseUrl: '/api/v1' });
+
+// Metadata
+client.meta.getObject('lead')           // → ObjectDefinition
+client.meta.getItems('object')          // → { type: 'object', items: ObjectDefinition[] }
+client.meta.getItems('app')             // → { type: 'app', items: AppDefinition[] }
+client.meta.getItem('app', 'crm')       // → AppDefinition
+
+// Data
+client.data.find('lead', { top: 20 })   // → { records: T[], total: number }
+client.data.get('lead', 'lead-001')     // → { record: T }
+client.data.create('lead', { ... })      // → { record: T }
+client.data.update('lead', 'id', { })    // → { record: T }
+client.data.delete('lead', 'id')         // → { deleted: true }
 ```
 
-> **Note**: Until the server implements these endpoints, the frontend uses mock data with the same interface. The API layer (`src/lib/api.ts`) abstracts this so switching to real endpoints requires zero page-level changes.
+> When the server is unreachable, hooks fall back to mock data from `lib/mock-data.ts`.
+> This allows the UI to be developed independently of the backend.
 
 ---
 
@@ -238,7 +237,7 @@ apps/web/src/
 │   └── metadata.ts                  # Object, Field, App type definitions
 │
 ├── lib/
-│   ├── api.ts                       # Fetch wrapper for /api/v1/*
+│   ├── api.ts                       # @objectstack/client SDK singleton
 │   ├── auth-client.ts               # Better-Auth client
 │   ├── app-registry.ts              # App registry (mock → API)
 │   ├── mock-data.ts                 # Mock metadata & records for dev

apps/web/package.json

@@ -12,6 +12,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@objectstack/client": "1.1.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-select": "^2.2.6",

apps/web/src/__tests__/lib/mock-data.test.ts

@@ -13,9 +13,9 @@ describe('mock-data', () => {
     it('returns the CRM app definition', () => {
       const app = getMockAppDefinition('crm');
       expect(app).toBeDefined();
-      expect(app?.name).toBe('CRM');
+      expect(app?.label).toBe('CRM');
       expect(app?.objects).toContain('lead');
-      expect(app?.category).toBe('business');
+      expect(app?.active).toBe(true);
     });
 
     it('returns undefined for unknown app', () => {
@@ -73,10 +73,10 @@ describe('mock-data', () => {
   describe('data consistency', () => {
     it('all app objects reference existing object definitions', () => {
       for (const app of mockAppDefinitions) {
-        for (const objName of app.objects) {
+        for (const objName of (app.objects ?? [])) {
           expect(
             mockObjectDefinitions[objName],
-            `App "${app.id}" references undefined object "${objName}"`,
+            `App "${app.name}" references undefined object "${objName}"`,
           ).toBeDefined();
         }
       }

apps/web/src/components/layouts/AppLayout.tsx

@@ -24,15 +24,15 @@ import { useAppDefinition, useObjectDefinition } from '@/hooks/use-metadata';
 /** Helper: resolve an object name to its plural label for the sidebar. */
 function ObjectNavLabel({ objectName }: { objectName: string }) {
   const { data: objectDef } = useObjectDefinition(objectName);
-  return <span>{objectDef?.pluralLabel ?? objectName}</span>;
+  return <span>{objectDef?.pluralLabel ?? objectDef?.label ?? objectName}</span>;
 }
 
 export function AppLayout() {
   const { pathname } = useLocation();
   const { appId } = useParams();
 
   const { data: appDef } = useAppDefinition(appId);
-  const appName = appDef?.name ?? appId ?? 'App';
+  const appName = appDef?.label ?? appId ?? 'App';
   const objectNames = appDef?.objects ?? [];
 
   return (

apps/web/src/components/records/FieldRenderer.tsx

@@ -20,8 +20,10 @@ export function FieldRenderer({ field, value }: FieldRendererProps) {
 
   switch (field.type) {
     case 'boolean':
+    case 'toggle':
       return <span>{value ? 'Yes' : 'No'}</span>;
 
+    case 'date':
     case 'datetime': {
       const date = new Date(String(value));
       if (isNaN(date.getTime())) return <span>{String(value)}</span>;
@@ -52,7 +54,8 @@ export function FieldRenderer({ field, value }: FieldRendererProps) {
     case 'number':
       return <span>{new Intl.NumberFormat().format(Number(value))}</span>;
 
-    case 'select': {
+    case 'select':
+    case 'radio': {
       const option = field.options?.find((o) => o.value === value);
       return (
         <Badge variant="outline" className="font-normal">
@@ -61,6 +64,24 @@ export function FieldRenderer({ field, value }: FieldRendererProps) {
       );
     }
 
+    case 'multiselect':
+    case 'checkboxes':
+    case 'tags': {
+      const values = Array.isArray(value) ? value : [value];
+      return (
+        <div className="flex flex-wrap gap-1">
+          {values.map((v) => {
+            const opt = field.options?.find((o) => o.value === v);
+            return (
+              <Badge key={String(v)} variant="outline" className="font-normal">
+                {opt?.label ?? String(v)}
+              </Badge>
+            );
+          })}
+        </div>
+      );
+    }
+
     case 'email':
       return (
         <a
@@ -93,10 +114,14 @@ export function FieldRenderer({ field, value }: FieldRendererProps) {
         </a>
       );
 
-    case 'reference':
+    case 'lookup':
+    case 'master_detail':
       return <span className="text-muted-foreground">{String(value)}</span>;
 
     case 'textarea':
+    case 'markdown':
+    case 'richtext':
+    case 'html':
       return (
         <span className="line-clamp-2" title={String(value)}>
           {String(value)}

apps/web/src/components/records/RecordTable.tsx

@@ -29,13 +29,13 @@ export function RecordTable({ objectDef, records, basePath }: RecordTableProps)
     Object.keys(objectDef.fields).filter((k) => k !== 'id' && !objectDef.fields[k].readonly);
 
   const columns = columnNames
-    .map((name) => objectDef.fields[name])
-    .filter(Boolean);
+    .map((name) => ({ ...objectDef.fields[name], name }))
+    .filter((f) => f.type);
 
   if (records.length === 0) {
     return (
       <div className="flex flex-col items-center justify-center rounded-lg border border-dashed py-12">
-        <p className="text-lg font-medium">No {objectDef.pluralLabel.toLowerCase()} yet</p>
+        <p className="text-lg font-medium">No {(objectDef.pluralLabel ?? objectDef.label ?? 'records').toLowerCase()} yet</p>
         <p className="text-sm text-muted-foreground">
           Records will appear here once they are created.
         </p>
@@ -49,7 +49,7 @@ export function RecordTable({ objectDef, records, basePath }: RecordTableProps)
         <TableHeader>
           <TableRow>
             {columns.map((col) => (
-              <TableHead key={col.name}>{col.label}</TableHead>
+              <TableHead key={col.name}>{col.label ?? col.name}</TableHead>
             ))}
           </TableRow>
         </TableHeader>

apps/web/src/hooks/use-metadata.ts

@@ -1,22 +1,30 @@
 /**
  * TanStack Query hooks for fetching object and app metadata.
  *
- * Uses mock data in development. When the server metadata endpoints
- * are available, swap the queryFn to call `apiFetch` instead.
+ * Uses the official @objectstack/client SDK to fetch from the server.
+ * Falls back to mock data when the server is unreachable so the UI
+ * can be developed without a running backend.
  */
 
 import { useQuery } from '@tanstack/react-query';
 import type { AppDefinition, ObjectDefinition } from '@/types/metadata';
+import { objectStackClient } from '@/lib/api';
 import { getMockAppDefinition, getMockObjectDefinition, mockAppDefinitions } from '@/lib/mock-data';
 
 // ── App metadata ────────────────────────────────────────────────
 
 export function useAppDefinition(appId: string | undefined) {
   return useQuery<AppDefinition | undefined>({
     queryKey: ['metadata', 'app', appId],
-    queryFn: () => {
-      // TODO: replace with apiFetch<AppDefinition>(`/metadata/apps/${appId}`)
-      return Promise.resolve(appId ? getMockAppDefinition(appId) : undefined);
+    queryFn: async () => {
+      if (!appId) return undefined;
+      try {
+        const result = await objectStackClient.meta.getItem('app', appId);
+        if (result) return result as AppDefinition;
+      } catch {
+        // Server unreachable — use mock data
+      }
+      return getMockAppDefinition(appId);
     },
     enabled: !!appId,
   });
@@ -25,9 +33,14 @@ export function useAppDefinition(appId: string | undefined) {
 export function useAppList() {
   return useQuery<AppDefinition[]>({
     queryKey: ['metadata', 'apps'],
-    queryFn: () => {
-      // TODO: replace with apiFetch<AppDefinition[]>('/metadata/apps')
-      return Promise.resolve(mockAppDefinitions);
+    queryFn: async () => {
+      try {
+        const result = await objectStackClient.meta.getItems('app');
+        if (result?.items?.length) return result.items as AppDefinition[];
+      } catch {
+        // Server unreachable — use mock data
+      }
+      return mockAppDefinitions;
     },
   });
 }
@@ -37,9 +50,15 @@ export function useAppList() {
 export function useObjectDefinition(objectName: string | undefined) {
   return useQuery<ObjectDefinition | undefined>({
     queryKey: ['metadata', 'object', objectName],
-    queryFn: () => {
-      // TODO: replace with apiFetch<ObjectDefinition>(`/metadata/objects/${objectName}`)
-      return Promise.resolve(objectName ? getMockObjectDefinition(objectName) : undefined);
+    queryFn: async () => {
+      if (!objectName) return undefined;
+      try {
+        const result = await objectStackClient.meta.getObject(objectName);
+        if (result) return result as ObjectDefinition;
+      } catch {
+        // Server unreachable — use mock data
+      }
+      return getMockObjectDefinition(objectName);
     },
     enabled: !!objectName,
   });

apps/web/src/hooks/use-records.ts

@@ -1,12 +1,13 @@
 /**
  * TanStack Query hooks for CRUD record operations.
  *
- * Uses mock data in development. When the server data endpoints
- * are available, swap the queryFn to call `apiFetch` instead.
+ * Uses the official @objectstack/client SDK to fetch from the server.
+ * Falls back to mock data when the server is unreachable.
  */
 
 import { useQuery } from '@tanstack/react-query';
 import type { RecordData, RecordListResponse } from '@/types/metadata';
+import { objectStackClient } from '@/lib/api';
 import { getMockRecords, getMockRecord } from '@/lib/mock-data';
 
 // ── Record list ─────────────────────────────────────────────────
@@ -20,17 +21,26 @@ interface UseRecordsOptions {
 export function useRecords({ objectName, page = 1, pageSize = 20 }: UseRecordsOptions) {
   return useQuery<RecordListResponse>({
     queryKey: ['records', objectName, page, pageSize],
-    queryFn: () => {
-      // TODO: replace with apiFetch<RecordListResponse>(`/data/${objectName}?page=${page}&pageSize=${pageSize}`)
-      const all = objectName ? getMockRecords(objectName) : [];
+    queryFn: async () => {
+      if (!objectName) return { records: [], total: 0, page, pageSize };
+      try {
+        const result = await objectStackClient.data.find(objectName, {
+          top: pageSize,
+          skip: (page - 1) * pageSize,
+        });
+        return {
+          records: result.records ?? [],
+          total: result.total ?? result.records?.length ?? 0,
+          page,
+          pageSize,
+        };
+      } catch {
+        // Server unreachable — use mock data
+      }
+      const all = getMockRecords(objectName);
       const start = (page - 1) * pageSize;
       const records = all.slice(start, start + pageSize);
-      return Promise.resolve({
-        records,
-        total: all.length,
-        page,
-        pageSize,
-      });
+      return { records, total: all.length, page, pageSize };
     },
     enabled: !!objectName,
   });
@@ -46,10 +56,15 @@ interface UseRecordOptions {
 export function useRecord({ objectName, recordId }: UseRecordOptions) {
   return useQuery<RecordData | undefined>({
     queryKey: ['record', objectName, recordId],
-    queryFn: () => {
-      // TODO: replace with apiFetch<RecordData>(`/data/${objectName}/${recordId}`)
-      if (!objectName || !recordId) return Promise.resolve(undefined);
-      return Promise.resolve(getMockRecord(objectName, recordId));
+    queryFn: async () => {
+      if (!objectName || !recordId) return undefined;
+      try {
+        const result = await objectStackClient.data.get(objectName, recordId);
+        if (result?.record) return result.record as RecordData;
+      } catch {
+        // Server unreachable — use mock data
+      }
+      return getMockRecord(objectName, recordId);
     },
     enabled: !!objectName && !!recordId,
   });