feat(analytics): implement analytics API protocol and schemas for query execution and metadata discovery

Author: hotlong

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

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { AnalyticsQuerySchema, CubeSchema } from '../data/analytics.zod';
+import { BaseResponseSchema } from './contract.zod';
+
+/**
+ * Analytics API Protocol
+ * 
+ * Defines the HTTP interface for the Semantic Layer.
+ * Provides endpoints for executing analytical queries and discovering metadata.
+ */
+
+// ==========================================
+// 1. API Endpoints
+// ==========================================
+
+export const AnalyticsEndpoint = z.enum([
+  '/api/v1/analytics/query', // Execute analysis
+  '/api/v1/analytics/meta',  // Discover cubes/metrics
+  '/api/v1/analytics/sql',   // Dry-run SQL generation
+]);
+
+// ==========================================
+// 2. Query Execution
+// ==========================================
+
+/**
+ * Query Request Body
+ */
+export const AnalyticsQueryRequestSchema = z.object({
+  query: AnalyticsQuerySchema.describe(' The analytic query definition'),
+  cube: z.string().describe('Target cube name'),
+  format: z.enum(['json', 'csv', 'xlsx']).default('json').describe('Response format'),
+});
+
+/**
+ * Query Response (JSON)
+ */
+export const AnalyticsResultResponseSchema = BaseResponseSchema.extend({
+  data: z.object({
+    rows: z.array(z.record(z.string(), z.any())).describe('Result rows'),
+    fields: z.array(z.object({
+      name: z.string(),
+      type: z.string(),
+    })).describe('Column metadata'),
+    sql: z.string().optional().describe('Executed SQL (if debug enabled)'),
+  }),
+});
+
+// ==========================================
+// 3. Metadata Discovery
+// ==========================================
+
+/**
+ * Meta Response
+ * Returns available cubes, metrics, and dimensions.
+ */
+export const AnalyticsMetadataResponseSchema = BaseResponseSchema.extend({
+  data: z.object({
+    cubes: z.array(CubeSchema).describe('Available cubes'),
+  }),
+});
+
+// ==========================================
+// 4. SQL Dry-Run
+// ==========================================
+
+export const AnalyticsSqlResponseSchema = BaseResponseSchema.extend({
+  data: z.object({
+    sql: z.string(),
+    params: z.array(z.any()),
+  }),
+});

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

@@ -9,6 +9,7 @@ export const ApiCapabilitiesSchema = z.object({
   search: z.boolean().default(false),
   websockets: z.boolean().default(false),
   files: z.boolean().default(true),
+  analytics: z.boolean().default(false).describe('Is the Analytics/BI engine enabled?'),
 });
 
 /**
@@ -32,6 +33,9 @@ export const ApiRoutesSchema = z.object({
   /** Base URL for File/Storage operations */
   storage: z.string().optional().describe('e.g. /api/storage'),
 
+  /** Base URL for Analytics/BI operations */
+  analytics: z.string().optional().describe('e.g. /api/analytics'),
+
   /** GraphQL Endpoint (if enabled) */
   graphql: z.string().optional().describe('e.g. /graphql'),
 });

packages/spec/src/api/index.ts

@@ -26,6 +26,7 @@ export * from './rest-server.zod';
 export * from './hub.zod';
 export * from './registry.zod';
 export * from './documentation.zod';
+export * from './analytics.zod';
 
 // Legacy interface export (deprecated)
 // export type { IObjectStackProtocol } from './protocol';