feat: add well-known capabilities to API discovery

ROADMAP.md

@@ -223,6 +223,9 @@ Strengthen discovery capabilities for frontend intelligent adaptation.
 | Localization info (locale, timezone) | ✅ | `api/discovery.zod.ts` |
 | Custom metadata extensions | ✅ | `api/discovery.zod.ts` |
 | Capabilities declaration (comments, automation, search, cron, files, analytics) | ✅ | `api/discovery.zod.ts` → `capabilities` with hierarchical descriptors |
+| Well-known capabilities (feed, comments, automation, cron, search, export, chunkedUpload) | ✅ | `api/discovery.zod.ts` → `WellKnownCapabilitiesSchema`, `protocol.zod.ts` → `GetDiscoveryResponseSchema.capabilities` |
+| Dynamic capabilities population from registered services | ✅ | `objectql/protocol.ts` → `getDiscovery()` builds capabilities from service registry |
+| Client SDK `capabilities` getter | ✅ | `client/index.ts` → `ObjectStackClient.capabilities` |
 | Per-service version info | ✅ | `api/discovery.zod.ts` → `ServiceInfoSchema.version` |
 | Rate limit & quota disclosure | ✅ | `api/discovery.zod.ts` → `ServiceInfoSchema.rateLimit` |
 | OpenAPI/GraphQL schema discovery endpoint | ✅ | `api/discovery.zod.ts` → `DiscoverySchema.schemaDiscovery` |

packages/client/src/client.test.ts

@@ -786,4 +786,44 @@ describe('ObjectStackClient.automation', () => {
             expect.objectContaining({ method: 'POST' }),
         );
     });
+
+    // ==========================================
+    // capabilities getter
+    // ==========================================
+
+    it('should return undefined capabilities before connect', () => {
+        const client = new ObjectStackClient({ baseUrl: 'http://localhost:3000' });
+        expect(client.capabilities).toBeUndefined();
+    });
+
+    it('should expose capabilities after connect', async () => {
+        const caps = {
+            feed: true,
+            comments: true,
+            automation: false,
+            cron: false,
+            search: true,
+            export: false,
+            chunkedUpload: false,
+        };
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                version: 'v1',
+                apiName: 'ObjectStack API',
+                capabilities: caps,
+            }),
+        });
+
+        const client = new ObjectStackClient({
+            baseUrl: 'http://localhost:3000',
+            fetch: fetchMock,
+        });
+
+        await client.connect();
+        expect(client.capabilities).toBeDefined();
+        expect(client.capabilities!.feed).toBe(true);
+        expect(client.capabilities!.automation).toBe(false);
+        expect(client.capabilities!.search).toBe(true);
+    });
 });

packages/client/src/index.ts

@@ -86,6 +86,7 @@ import {
   GetChangelogResponse,
   SubscribeResponse,
   UnsubscribeResponse,
+  WellKnownCapabilities,
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
 
@@ -255,6 +256,15 @@ export class ObjectStackClient {
     }
   }
 
+  /**
+   * Well-known capability flags discovered from the server.
+   * Returns undefined if the client has not yet connected or the server
+   * did not include capabilities in its discovery response.
+   */
+  get capabilities(): WellKnownCapabilities | undefined {
+    return this.discoveryInfo?.capabilities;
+  }
+
   /**
    * Metadata Operations
    */
@@ -1747,4 +1757,5 @@ export type {
   GetChangelogResponse,
   SubscribeResponse,
   UnsubscribeResponse,
+  WellKnownCapabilities,
 } from '@objectstack/spec/api';

packages/objectql/src/protocol-discovery.test.ts

@@ -137,17 +137,77 @@ describe('ObjectStackProtocolImplementation - Dynamic Service Discovery', () =>
     expect(discovery.services.analytics.route).toBe('/api/v1/analytics');
   });
 
-  it('should not return capabilities field (removed — use services instead)', async () => {
+  it('should return capabilities field populated from registered services', async () => {
     const mockServices = new Map<string, any>();
     mockServices.set('workflow', {});
 
     protocol = new ObjectStackProtocolImplementation(engine, () => mockServices);
     const discovery = await protocol.getDiscovery();
 
-    // capabilities field should no longer exist in the response
-    const keys = Object.keys(discovery);
-    expect(keys).not.toContain('capabilities');
-    // Use services to check availability instead
+    // capabilities field should now exist in the response
+    expect(discovery.capabilities).toBeDefined();
+    // workflow is registered but doesn't map to a well-known capability directly
     expect(discovery.services.workflow.enabled).toBe(true);
+    // All well-known capabilities should be false since workflow doesn't map to any
+    expect(discovery.capabilities!.feed).toBe(false);
+    expect(discovery.capabilities!.comments).toBe(false);
+    expect(discovery.capabilities!.automation).toBe(false);
+    expect(discovery.capabilities!.cron).toBe(false);
+    expect(discovery.capabilities!.search).toBe(false);
+    expect(discovery.capabilities!.export).toBe(false);
+    expect(discovery.capabilities!.chunkedUpload).toBe(false);
+  });
+
+  it('should set all capabilities to false when no services are registered', async () => {
+    protocol = new ObjectStackProtocolImplementation(engine);
+    const discovery = await protocol.getDiscovery();
+
+    expect(discovery.capabilities).toBeDefined();
+    expect(discovery.capabilities!.feed).toBe(false);
+    expect(discovery.capabilities!.comments).toBe(false);
+    expect(discovery.capabilities!.automation).toBe(false);
+    expect(discovery.capabilities!.cron).toBe(false);
+    expect(discovery.capabilities!.search).toBe(false);
+    expect(discovery.capabilities!.export).toBe(false);
+    expect(discovery.capabilities!.chunkedUpload).toBe(false);
+  });
+
+  it('should dynamically set capabilities based on registered services', async () => {
+    const mockServices = new Map<string, any>();
+    mockServices.set('feed', {});
+    mockServices.set('automation', {});
+    mockServices.set('search', {});
+    mockServices.set('file-storage', {});
+
+    protocol = new ObjectStackProtocolImplementation(engine, () => mockServices);
+    const discovery = await protocol.getDiscovery();
+
+    expect(discovery.capabilities!.feed).toBe(true);
+    expect(discovery.capabilities!.comments).toBe(true);
+    expect(discovery.capabilities!.automation).toBe(true);
+    expect(discovery.capabilities!.cron).toBe(false);
+    expect(discovery.capabilities!.search).toBe(true);
+    expect(discovery.capabilities!.export).toBe(true);
+    expect(discovery.capabilities!.chunkedUpload).toBe(true);
+  });
+
+  it('should enable cron capability when job service is registered', async () => {
+    const mockServices = new Map<string, any>();
+    mockServices.set('job', {});
+
+    protocol = new ObjectStackProtocolImplementation(engine, () => mockServices);
+    const discovery = await protocol.getDiscovery();
+
+    expect(discovery.capabilities!.cron).toBe(true);
+  });
+
+  it('should enable export capability when queue service is registered', async () => {
+    const mockServices = new Map<string, any>();
+    mockServices.set('queue', {});
+
+    protocol = new ObjectStackProtocolImplementation(engine, () => mockServices);
+    const discovery = await protocol.getDiscovery();
+
+    expect(discovery.capabilities!.export).toBe(true);
   });
 });

packages/objectql/src/protocol.ts

@@ -8,7 +8,7 @@ import type {
     UpdateManyDataRequest,
     DeleteManyDataRequest
 } from '@objectstack/spec/api';
-import type { MetadataCacheRequest, MetadataCacheResponse, ServiceInfo, ApiRoutes } from '@objectstack/spec/api';
+import type { MetadataCacheRequest, MetadataCacheResponse, ServiceInfo, ApiRoutes, WellKnownCapabilities } from '@objectstack/spec/api';
 import type { IFeedService } from '@objectstack/spec/contracts';
 
 // We import SchemaRegistry directly since this class lives in the same package
@@ -150,11 +150,23 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             ...optionalRoutes,
         };
 
+        // Build well-known capabilities from registered services
+        const capabilities: WellKnownCapabilities = {
+            feed: registeredServices.has('feed'),
+            comments: registeredServices.has('feed'),
+            automation: registeredServices.has('automation'),
+            cron: registeredServices.has('job'),
+            search: registeredServices.has('search'),
+            export: registeredServices.has('automation') || registeredServices.has('queue'),
+            chunkedUpload: registeredServices.has('file-storage'),
+        };
+
         return {
             version: '1.0',
             apiName: 'ObjectStack API',
             routes,
             services,
+            capabilities,
         };
     }
 

packages/spec/src/api/discovery.test.ts

@@ -3,9 +3,11 @@ import {
   DiscoverySchema,
   ApiRoutesSchema,
   ServiceInfoSchema,
+  WellKnownCapabilitiesSchema,
   type DiscoveryResponse,
   type ApiRoutes,
   type ServiceInfo,
+  type WellKnownCapabilities,
 } from './discovery.zod';
 
 describe('ApiRoutesSchema', () => {
@@ -683,3 +685,64 @@ describe('DiscoverySchema (schemaDiscovery field)', () => {
     expect(discovery.schemaDiscovery?.graphql).toBeUndefined();
   });
 });
+
+// ==========================================
+// WellKnownCapabilitiesSchema
+// ==========================================
+
+describe('WellKnownCapabilitiesSchema', () => {
+  it('should accept all capabilities enabled', () => {
+    const caps: WellKnownCapabilities = {
+      feed: true,
+      comments: true,
+      automation: true,
+      cron: true,
+      search: true,
+      export: true,
+      chunkedUpload: true,
+    };
+    expect(() => WellKnownCapabilitiesSchema.parse(caps)).not.toThrow();
+  });
+
+  it('should accept all capabilities disabled', () => {
+    const caps = WellKnownCapabilitiesSchema.parse({
+      feed: false,
+      comments: false,
+      automation: false,
+      cron: false,
+      search: false,
+      export: false,
+      chunkedUpload: false,
+    });
+    expect(caps.feed).toBe(false);
+    expect(caps.chunkedUpload).toBe(false);
+  });
+
+  it('should reject missing required fields', () => {
+    expect(() => WellKnownCapabilitiesSchema.parse({ feed: true })).toThrow();
+    expect(() => WellKnownCapabilitiesSchema.parse({})).toThrow();
+  });
+
+  it('should reject non-boolean values', () => {
+    expect(() => WellKnownCapabilitiesSchema.parse({
+      feed: 'yes',
+      comments: true,
+      automation: true,
+      cron: true,
+      search: true,
+      export: true,
+      chunkedUpload: true,
+    })).toThrow();
+  });
+
+  it('should have .describe() annotations on all fields', () => {
+    const shape = WellKnownCapabilitiesSchema.shape;
+    expect(shape.feed.description).toBeDefined();
+    expect(shape.comments.description).toBeDefined();
+    expect(shape.automation.description).toBeDefined();
+    expect(shape.cron.description).toBeDefined();
+    expect(shape.search.description).toBeDefined();
+    expect(shape.export.description).toBeDefined();
+    expect(shape.chunkedUpload.description).toBeDefined();
+  });
+});

packages/spec/src/api/discovery.zod.ts

@@ -146,6 +146,30 @@ export const DiscoverySchema = z.object({
   metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'),
 });
 
+/**
+ * Well-Known Capabilities Schema
+ * Flat boolean flags for quick feature detection by clients (ObjectUI).
+ * Each flag indicates whether the backend supports a specific capability.
+ * Clients can use these to show/hide UI elements without probing individual endpoints.
+ */
+export const WellKnownCapabilitiesSchema = z.object({
+  /** Whether the backend supports Feed / Chatter API */
+  feed: z.boolean().describe('Whether the backend supports Feed / Chatter API'),
+  /** Whether the backend supports comments (a subset of Feed) */
+  comments: z.boolean().describe('Whether the backend supports comments (a subset of Feed)'),
+  /** Whether the backend supports Automation CRUD (flows, triggers) */
+  automation: z.boolean().describe('Whether the backend supports Automation CRUD (flows, triggers)'),
+  /** Whether the backend supports cron scheduling */
+  cron: z.boolean().describe('Whether the backend supports cron scheduling'),
+  /** Whether the backend supports full-text search */
+  search: z.boolean().describe('Whether the backend supports full-text search'),
+  /** Whether the backend supports async export */
+  export: z.boolean().describe('Whether the backend supports async export'),
+  /** Whether the backend supports chunked (multipart) uploads */
+  chunkedUpload: z.boolean().describe('Whether the backend supports chunked (multipart) uploads'),
+}).describe('Well-known capability flags for frontend intelligent adaptation');
+
+export type WellKnownCapabilities = z.infer<typeof WellKnownCapabilitiesSchema>;
 export type DiscoveryResponse = z.infer<typeof DiscoverySchema>;
 export type ApiRoutes = z.infer<typeof ApiRoutesSchema>;
 export type ServiceInfo = z.infer<typeof ServiceInfoSchema>;

packages/spec/src/api/protocol.test.ts

@@ -319,3 +319,51 @@ describe('ObjectStack Protocol', () => {
   });
 
 });
+
+// ==========================================
+// GetDiscoveryResponseSchema — capabilities
+// ==========================================
+import { GetDiscoveryResponseSchema } from './protocol.zod';
+
+describe('GetDiscoveryResponseSchema (capabilities)', () => {
+  it('should accept response with well-known capabilities', () => {
+    const result = GetDiscoveryResponseSchema.safeParse({
+      version: 'v1',
+      apiName: 'ObjectStack API',
+      capabilities: {
+        feed: true,
+        comments: true,
+        automation: false,
+        cron: false,
+        search: true,
+        export: false,
+        chunkedUpload: true,
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.capabilities?.feed).toBe(true);
+      expect(result.data.capabilities?.automation).toBe(false);
+    }
+  });
+
+  it('should accept response without capabilities (optional)', () => {
+    const result = GetDiscoveryResponseSchema.safeParse({
+      version: 'v1',
+      apiName: 'ObjectStack API',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.capabilities).toBeUndefined();
+    }
+  });
+
+  it('should reject capabilities with missing fields', () => {
+    const result = GetDiscoveryResponseSchema.safeParse({
+      version: 'v1',
+      apiName: 'ObjectStack API',
+      capabilities: { feed: true },
+    });
+    expect(result.success).toBe(false);
+  });
+});

packages/spec/src/api/protocol.zod.ts

@@ -2,7 +2,7 @@
 
 import { z } from 'zod';
 import { ViewSchema } from '../ui/view.zod';
-import { ApiRoutesSchema, ServiceInfoSchema } from './discovery.zod';
+import { ApiRoutesSchema, ServiceInfoSchema, WellKnownCapabilitiesSchema } from './discovery.zod';
 import { BatchUpdateRequestSchema, BatchUpdateResponseSchema, BatchOptionsSchema } from './batch.zod';
 import { MetadataCacheRequestSchema, MetadataCacheResponseSchema } from './http-cache.zod';
 import { QuerySchema } from '../data/query.zod';
@@ -129,6 +129,7 @@ export const GetDiscoveryResponseSchema = z.object({
   apiName: z.string().describe('API name'),
   routes: ApiRoutesSchema.optional().describe('Available endpoint paths'),
   services: z.record(z.string(), ServiceInfoSchema).optional().describe('Per-service availability map'),
+  capabilities: WellKnownCapabilitiesSchema.optional().describe('Well-known capability flags for frontend adaptation'),
 });
 
 /**