@objectstack/client 1.0.10 → 1.0.12

package/src/client.hono.test.ts

@@ -33,23 +33,23 @@ describe('ObjectStackClient (with Hono Server)', () => {
                     const ql = kernel.getService<any>('objectql'); // Use 'objectql' service name for clarity
                     if (method === 'create') {
                         const res = await ql.insert(params.object, params.data);
-                        // Ensure we return the full object including input data + ID
-                        return { ...params.data, ...res };
+                        const record = { ...params.data, ...res };
+                        return { object: params.object, id: record.id || record._id, record };
                     }
                     // Params from HttpDispatcher: { object, id, ...query }
                     if (method === 'get') {
-                        // Ensure we search by 'id' explicitly for InMemoryDriver
-                        return ql.findOne(params.object, { where: { id: params.id } });
+                        const record = await ql.findOne(params.object, { where: { id: params.id } });
+                        return record ? { object: params.object, id: params.id, record } : null;
                     }
                     // Params from HttpDispatcher: { object, filters }
                     if (method === 'query') {
-                        // HttpDispatcher passes filters as simple object (map)
-                        // ObjectQL expects { filter, select, sort, ... }
-                        const data = await ql.find(params.object, { filter: params.filters });
-                        // HttpDispatcher expects { data, count }
-                        return { data, count: data.length };
+                        const records = await ql.find(params.object, { filter: params.filters });
+                        return { object: params.object, records, total: records.length };
+                    }
+                    if (method === 'find') {
+                        const records = await ql.find(params.object, { filter: params.filters });
+                        return { object: params.object, records, total: records.length };
                     }
-                    if (method === 'find') return ql.find(params.object, { filter: params.filters });
                 }
                 
                 if (service === 'metadata') {
@@ -101,44 +101,49 @@ describe('ObjectStackClient (with Hono Server)', () => {
         if (kernel) await kernel.shutdown();
     });
 
-    it('should connect to hono server', async () => {
+    it('should connect to hono server and discover endpoints', async () => {
         const client = new ObjectStackClient({ baseUrl });
         await client.connect();
         
-        // Client creates URL like ${baseUrl}/api/v1
-        expect(client).toBeDefined();
+        // Client should have populated discovery info
+        expect(client['discoveryInfo']).toBeDefined();
+        
+        // Verify endpoints from valid discovery response
+        // Standard: /api/v1/data, /api/v1/meta, etc.
+        const endpoints = client['discoveryInfo']!.routes;
+        expect(endpoints.data).toContain('/api/v1/data');
+        expect(endpoints.metadata).toContain('/api/v1/meta');
+        expect(endpoints.auth).toContain('/api/v1/auth');
     });
 
     it('should create and retrieve data via hono', async () => {
         const client = new ObjectStackClient({ baseUrl });
         await client.connect();
 
-        // Create
+        // Create — Spec: CreateDataResponse = { object, id, record }
         const createdResponse = await client.data.create('customer', {
             name: 'Hono User',
             email: 'hono@example.com'
         });
         
-        expect(createdResponse.success).toBe(true);
-        expect(createdResponse.data.name).toBe('Hono User');
-        expect(createdResponse.data.id).toBeDefined();
-
-        // Retrieve
-        const retrievedResponse = await client.data.get('customer', createdResponse.data.id);
-        expect(retrievedResponse.success).toBe(true);
-        expect(retrievedResponse.data.name).toBe('Hono User');
+        expect(createdResponse.record.name).toBe('Hono User');
+        expect(createdResponse.id).toBeDefined();
+
+        // Retrieve — Spec: GetDataResponse = { object, id, record }
+        const retrievedResponse = await client.data.get('customer', createdResponse.id);
+        expect(retrievedResponse.record.name).toBe('Hono User');
     });
 
     it('should find data via hono', async () => {
         const client = new ObjectStackClient({ baseUrl });
         await client.connect();
 
+        // Spec: FindDataResponse = { object, records, total? }
         const resultsResponse = await client.data.find('customer', {
             where: { name: 'Hono User' }
         });
 
-        expect(resultsResponse.success).toBe(true);
-        expect(resultsResponse.data.length).toBeGreaterThan(0);
-        expect(resultsResponse.data[0].name).toBe('Hono User');
+        expect(resultsResponse.records.length).toBeGreaterThan(0);
+        expect(resultsResponse.records[0].name).toBe('Hono User');
     });
 });

package/src/client.msw.test.ts

@@ -39,17 +39,22 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
                     const ql = kernel.getService<any>('objectql');
                     if (method === 'create') {
                          const res = await ql.insert(params.object, params.data);
-                         return { ...params.data, ...res };
+                         const record = { ...params.data, ...res };
+                         return { object: params.object, id: record.id || record._id, record };
                     }
                     if (method === 'get') {
                         // Ensure we search by 'id' explicitly for InMemoryDriver
-                        return ql.findOne(params.object, { where: { id: params.id } });
+                        const record = await ql.findOne(params.object, { where: { id: params.id } });
+                        return record ? { object: params.object, id: params.id, record } : null;
                     }
                     if (method === 'query') {
-                        const data = await ql.find(params.object, { filter: params.filters });
-                        return { data, count: data.length };
+                        const records = await ql.find(params.object, { filter: params.filters });
+                        return { object: params.object, records, total: records.length };
+                    }
+                    if (method === 'find') {
+                        const records = await ql.find(params.object, { filter: params.filters });
+                        return { object: params.object, records, total: records.length };
                     }
-                    if (method === 'find') return ql.find(params.object, { filter: params.filters });
                 }
                 
                 if (service === 'metadata') {
@@ -91,7 +96,7 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
                     version: '1.0.0',
                     routes: {
                         data: '/api/v1/data',
-                        metadata: '/api/v1/metadata',
+                        metadata: '/api/v1/meta',
                         auth: '/api/v1/auth'
                     },
                     capabilities: ['data', 'metadata'],
@@ -99,7 +104,7 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
                 });
             }),
             
-            http.get('http://127.0.0.1/api/v1/metadata/object/:name', async ({ params }) => {
+            http.get('http://127.0.0.1/api/v1/meta/object/:name', async ({ params }) => {
                  try {
                      const res = await (kernel as any).broker.call('metadata.getObject', { objectName: params.name });
                      return HttpResponse.json({ success: true, data: res });
@@ -162,37 +167,44 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
         const client = new ObjectStackClient({ baseUrl: BASE_URL });
         await client.connect();
 
-        const customerRes = await client.meta.getItem('object', 'customer');
-        expect(customerRes.success).toBe(true);
-        expect(customerRes.data.name).toBe('customer');
+        // Spec: GetMetaItemResponse = { type, name, item }
+        const customerRes: any = await client.meta.getItem('object', 'customer');
+        expect(customerRes).toBeDefined();
+        // After unwrapResponse, we get the protocol-level response
+        // The manual handler wraps as { success, data: schema }, so unwrap yields the schema
+        const schema = customerRes.item || customerRes;
+        expect(schema.name).toBe('customer');
     });
 
     it('should find data records', async () => {
         const client = new ObjectStackClient({ baseUrl: BASE_URL });
         await client.connect();
 
+        // Spec: FindDataResponse = { object, records, total? }
         const resultsRes = await client.data.find('customer');
-        expect(resultsRes.success).toBe(true);
-        expect(resultsRes.data.length).toBe(2);
-        expect(resultsRes.data[0].name).toBe('Alice');
+        expect(resultsRes.records).toBeDefined();
+        expect(resultsRes.records.length).toBe(2);
+        expect(resultsRes.records[0].name).toBe('Alice');
     });
 
     it('should get single record', async () => {
         const client = new ObjectStackClient({ baseUrl: BASE_URL });
         await client.connect();
 
+        // Spec: GetDataResponse = { object, id, record }
         const recordRes = await client.data.get('customer', '101');
-        expect(recordRes.success).toBe(true);
-        expect(recordRes.data.name).toBe('Alice');
+        expect(recordRes.record).toBeDefined();
+        expect(recordRes.record.name).toBe('Alice');
     });
 
     it('should create record', async () => {
         const client = new ObjectStackClient({ baseUrl: BASE_URL });
         await client.connect();
 
+        // Spec: CreateDataResponse = { object, id, record }
         const newRecordRes = await client.data.create('customer', { name: 'Charlie' });
-        expect(newRecordRes.success).toBe(true);
-        expect(newRecordRes.data.name).toBe('Charlie');
-        expect(newRecordRes.data.id).toBeDefined();
+        expect(newRecordRes.record).toBeDefined();
+        expect(newRecordRes.record.name).toBe('Charlie');
+        expect(newRecordRes.id).toBeDefined();
     });
 });

package/src/client.test.ts

@@ -46,7 +46,7 @@ describe('ObjectStackClient', () => {
         });
 
         const result = await client.meta.getTypes();
-        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/metadata', expect.any(Object));
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta', expect.any(Object));
         expect(result.types).toEqual(['object', 'plugin', 'view']);
     });
 
@@ -65,7 +65,7 @@ describe('ObjectStackClient', () => {
         });
 
         const result = await client.meta.getItems('object');
-        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/metadata/object', expect.any(Object));
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta/object', expect.any(Object));
         expect(result.type).toBe('object');
         expect(result.items).toHaveLength(2);
     });
@@ -85,7 +85,7 @@ describe('ObjectStackClient', () => {
         });
 
         const result = await client.meta.getItem('object', 'customer');
-        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/metadata/object/customer', expect.any(Object));
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta/object/customer', expect.any(Object));
         expect(result.name).toBe('customer');
     });
 });

package/src/index.ts

@@ -56,8 +56,46 @@ export interface QueryOptions {
 }
 
 export interface PaginatedResult<T = any> {
-  value: T[];
-  count: number;
+  /** @deprecated Use `records` — aligned with FindDataResponseSchema */
+  value?: T[];
+  /** Spec-compliant: array of matching records */
+  records: T[];
+  /** @deprecated Use `total` — aligned with FindDataResponseSchema */
+  count?: number;
+  /** Total number of matching records (if requested) */
+  total?: number;
+  /** The object name */
+  object?: string;
+  /** Whether more records are available */
+  hasMore?: boolean;
+}
+
+/** Spec: GetDataResponseSchema */
+export interface GetDataResult<T = any> {
+  object: string;
+  id: string;
+  record: T;
+}
+
+/** Spec: CreateDataResponseSchema */
+export interface CreateDataResult<T = any> {
+  object: string;
+  id: string;
+  record: T;
+}
+
+/** Spec: UpdateDataResponseSchema */
+export interface UpdateDataResult<T = any> {
+  object: string;
+  id: string;
+  record: T;
+}
+
+/** Spec: DeleteDataResponseSchema */
+export interface DeleteDataResult {
+  object: string;
+  id: string;
+  deleted: boolean;
 }
 
 export interface StandardError {
@@ -114,7 +152,8 @@ export class ObjectStackClient {
         this.logger.debug('Probing .well-known discovery', { url: wellKnownUrl });
         const res = await this.fetchImpl(wellKnownUrl);
         if (res.ok) {
-          data = await res.json();
+          const body = await res.json();
+          data = body.data || body;
           this.logger.debug('Discovered via .well-known');
         }
       } catch (e) {
@@ -129,7 +168,8 @@ export class ObjectStackClient {
         if (!res.ok) {
            throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
         }
-        data = await res.json();
+        const body = await res.json();
+        data = body.data || body;
       }
 
       if (!data) {
@@ -162,17 +202,22 @@ export class ObjectStackClient {
     getTypes: async (): Promise<GetMetaTypesResponse> => {
         const route = this.getRoute('metadata');
         const res = await this.fetch(`${this.baseUrl}${route}`);
-        return res.json();
+        return this.unwrapResponse<GetMetaTypesResponse>(res);
     },
 
     /**
      * Get all items of a specific metadata type
      * @param type - Metadata type name (e.g., 'object', 'plugin')
+     * @param options - Optional filters (e.g., packageId to scope by package)
      */
-    getItems: async (type: string): Promise<GetMetaItemsResponse> => {
+    getItems: async (type: string, options?: { packageId?: string }): Promise<GetMetaItemsResponse> => {
         const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}`);
-        return res.json();
+        const params = new URLSearchParams();
+        if (options?.packageId) params.set('package', options.packageId);
+        const qs = params.toString();
+        const url = `${this.baseUrl}${route}/${type}${qs ? `?${qs}` : ''}`;
+        const res = await this.fetch(url);
+        return this.unwrapResponse<GetMetaItemsResponse>(res);
     },
 
     /**
@@ -183,7 +228,7 @@ export class ObjectStackClient {
     getObject: async (name: string) => {
         const route = this.getRoute('metadata');
         const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`);
-        return res.json();
+        return this.unwrapResponse(res);
     },
 
     /**
@@ -194,7 +239,7 @@ export class ObjectStackClient {
     getItem: async (type: string, name: string) => {
         const route = this.getRoute('metadata');
         const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`);
-        return res.json();
+        return this.unwrapResponse(res);
     },
 
     /**
@@ -209,7 +254,7 @@ export class ObjectStackClient {
             method: 'PUT',
             body: JSON.stringify(item)
         });
-        return res.json();
+        return this.unwrapResponse(res);
     },
     
     /**
@@ -260,7 +305,7 @@ export class ObjectStackClient {
     getView: async (object: string, type: 'list' | 'form' = 'list') => {
         const route = this.getRoute('ui');
         const res = await this.fetch(`${this.baseUrl}${route}/view/${object}?type=${type}`);
-        return res.json();
+        return this.unwrapResponse(res);
     }
   };
 
@@ -322,6 +367,97 @@ export class ObjectStackClient {
     }
   };
 
+  /**
+   * Package Management Services
+   * 
+   * Manages the lifecycle of installed packages.
+   * A package (ManifestSchema) is the unit of installation.
+   * An app (AppSchema) is a UI navigation definition within a package.
+   * A package may contain 0, 1, or many apps, or be a pure functionality plugin.
+   * 
+   * Endpoints:
+   * - GET    /packages               → list installed packages
+   * - GET    /packages/:id           → get package details  
+   * - POST   /packages               → install a package
+   * - DELETE  /packages/:id           → uninstall a package
+   * - PATCH  /packages/:id/enable    → enable a package
+   * - PATCH  /packages/:id/disable   → disable a package
+   */
+  packages = {
+    /**
+     * List all installed packages with optional filters.
+     */
+    list: async (filters?: { status?: string; type?: string; enabled?: boolean }) => {
+        const route = this.getRoute('packages');
+        const params = new URLSearchParams();
+        if (filters?.status) params.set('status', filters.status);
+        if (filters?.type) params.set('type', filters.type);
+        if (filters?.enabled !== undefined) params.set('enabled', String(filters.enabled));
+        const qs = params.toString();
+        const url = `${this.baseUrl}${route}${qs ? '?' + qs : ''}`;
+        const res = await this.fetch(url);
+        return this.unwrapResponse<{ packages: any[]; total: number }>(res);
+    },
+
+    /**
+     * Get a specific installed package by its ID (reverse domain identifier).
+     */
+    get: async (id: string) => {
+        const route = this.getRoute('packages');
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}`);
+        return this.unwrapResponse<{ package: any }>(res);
+    },
+
+    /**
+     * Install a new package from its manifest.
+     */
+    install: async (manifest: any, options?: { settings?: Record<string, any>; enableOnInstall?: boolean }) => {
+        const route = this.getRoute('packages');
+        const res = await this.fetch(`${this.baseUrl}${route}`, {
+            method: 'POST',
+            body: JSON.stringify({
+                manifest,
+                settings: options?.settings,
+                enableOnInstall: options?.enableOnInstall,
+            }),
+        });
+        return this.unwrapResponse<{ package: any; message?: string }>(res);
+    },
+
+    /**
+     * Uninstall a package by its ID.
+     */
+    uninstall: async (id: string) => {
+        const route = this.getRoute('packages');
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        });
+        return this.unwrapResponse<{ id: string; success: boolean; message?: string }>(res);
+    },
+
+    /**
+     * Enable a disabled package.
+     */
+    enable: async (id: string) => {
+        const route = this.getRoute('packages');
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}/enable`, {
+            method: 'PATCH',
+        });
+        return this.unwrapResponse<{ package: any; message?: string }>(res);
+    },
+
+    /**
+     * Disable an installed package.
+     */
+    disable: async (id: string) => {
+        const route = this.getRoute('packages');
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}/disable`, {
+            method: 'PATCH',
+        });
+        return this.unwrapResponse<{ package: any; message?: string }>(res);
+    },
+  };
+
   /**
    * Authentication Services
    */
@@ -435,7 +571,7 @@ export class ObjectStackClient {
         method: 'POST',
         body: JSON.stringify(query)
       });
-      return res.json();
+      return this.unwrapResponse<PaginatedResult<T>>(res);
     },
 
     find: async <T = any>(object: string, options: QueryOptions = {}): Promise<PaginatedResult<T>> => {
@@ -486,22 +622,22 @@ export class ObjectStackClient {
         }
 
         const res = await this.fetch(`${this.baseUrl}${route}/${object}?${queryParams.toString()}`);
-        return res.json();
+        return this.unwrapResponse<PaginatedResult<T>>(res);
     },
 
-    get: async <T = any>(object: string, id: string): Promise<T> => {
+    get: async <T = any>(object: string, id: string): Promise<GetDataResult<T>> => {
         const route = this.getRoute('data');
         const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`);
-        return res.json();
+        return this.unwrapResponse<GetDataResult<T>>(res);
     },
 
-    create: async <T = any>(object: string, data: Partial<T>): Promise<T> => {
+    create: async <T = any>(object: string, data: Partial<T>): Promise<CreateDataResult<T>> => {
         const route = this.getRoute('data');
         const res = await this.fetch(`${this.baseUrl}${route}/${object}`, {
             method: 'POST',
             body: JSON.stringify(data)
         });
-        return res.json();
+        return this.unwrapResponse<CreateDataResult<T>>(res);
     },
 
     createMany: async <T = any>(object: string, data: Partial<T>[]): Promise<T[]> => {
@@ -510,16 +646,16 @@ export class ObjectStackClient {
             method: 'POST',
             body: JSON.stringify(data)
         });
-        return res.json();
+        return this.unwrapResponse<T[]>(res);
     },
 
-    update: async <T = any>(object: string, id: string, data: Partial<T>): Promise<T> => {
+    update: async <T = any>(object: string, id: string, data: Partial<T>): Promise<UpdateDataResult<T>> => {
         const route = this.getRoute('data');
         const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`, {
             method: 'PATCH',
             body: JSON.stringify(data)
         });
-        return res.json();
+        return this.unwrapResponse<UpdateDataResult<T>>(res);
     },
 
     /**
@@ -532,7 +668,7 @@ export class ObjectStackClient {
             method: 'POST',
             body: JSON.stringify(request)
         });
-        return res.json();
+        return this.unwrapResponse<BatchUpdateResponse>(res);
     },
 
     /**
@@ -553,15 +689,15 @@ export class ObjectStackClient {
             method: 'POST',
             body: JSON.stringify(request)
         });
-        return res.json();
+        return this.unwrapResponse<BatchUpdateResponse>(res);
     },
 
-    delete: async (object: string, id: string): Promise<{ success: boolean }> => {
+    delete: async (object: string, id: string): Promise<DeleteDataResult> => {
         const route = this.getRoute('data');
         const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`, {
             method: 'DELETE'
         });
-        return res.json();
+        return this.unwrapResponse<DeleteDataResult>(res);
     },
 
     /**
@@ -577,7 +713,7 @@ export class ObjectStackClient {
              method: 'POST',
              body: JSON.stringify(request)
         });
-        return res.json();
+        return this.unwrapResponse<BatchUpdateResponse>(res);
     }
   };
 
@@ -594,6 +730,23 @@ export class ObjectStackClient {
     return Array.isArray(filter);
   }
 
+  /**
+   * Unwrap the standard REST API response envelope.
+   * The HTTP layer wraps responses as `{ success: boolean, data: T, meta? }`
+   * (see BaseResponseSchema in contract.zod.ts).
+   * This method strips the envelope and returns the inner `data` payload
+   * so callers receive the spec-level type (e.g. GetMetaTypesResponse).
+   */
+  private async unwrapResponse<T>(res: Response): Promise<T> {
+    const body = await res.json();
+    // If the body has a `success` flag it's a BaseResponse envelope
+    if (body && typeof body.success === 'boolean' && 'data' in body) {
+      return body.data as T;
+    }
+    // Already unwrapped or non-standard
+    return body as T;
+  }
+
   private async fetch(url: string, options: RequestInit = {}): Promise<Response> {
     this.logger.debug('HTTP request', { 
       method: options.method || 'GET',
@@ -654,9 +807,9 @@ export class ObjectStackClient {
 
   /**
    * Get the conventional route path for a given API endpoint type
-   * ObjectStack uses standard conventions: /api/v1/data, /api/v1/metadata, /api/v1/ui
+   * ObjectStack uses standard conventions: /api/v1/data, /api/v1/meta, /api/v1/ui
    */
-  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'hub' | 'storage' | 'automation'): string {
+  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'hub' | 'storage' | 'automation' | 'packages'): string {
     // 1. Use discovered routes if available
     // Note: Spec uses 'endpoints', mapped dynamically
     if (this.discoveryInfo?.endpoints && (this.discoveryInfo.endpoints as any)[type]) {
@@ -664,16 +817,16 @@ export class ObjectStackClient {
     }
 
     // 2. Fallback to conventions
-    // Note: HttpDispatcher expects /metadata, not /meta
     const routeMap: Record<string, string> = {
       data: '/api/v1/data',
-      metadata: '/api/v1/metadata',
+      metadata: '/api/v1/meta',
       ui: '/api/v1/ui',
       auth: '/api/v1/auth',
       analytics: '/api/v1/analytics',
       hub: '/api/v1/hub',
       storage: '/api/v1/storage',
-      automation: '/api/v1/automation'
+      automation: '/api/v1/automation',
+      packages: '/api/v1/packages',
     };
     
     return routeMap[type] || `/api/v1/${type}`;