feat: enhance API schemas with additional fields for error handling, pagination, and rate limiting

Author: hotlong

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

@@ -8,7 +8,9 @@ import { QuerySchema } from '../data/query.zod';
 export const ApiErrorSchema = z.object({
   code: z.string().describe('Error code (e.g. validation_error)'),
   message: z.string().describe('Readable error message'),
+  category: z.string().optional().describe('Error category (e.g. validation, authorization)'),
   details: z.any().optional().describe('Additional error context (e.g. field validation errors)'),
+  requestId: z.string().optional().describe('Request ID for tracking'),
 });
 
 export const BaseResponseSchema = z.object({
@@ -74,20 +76,31 @@ export const SingleRecordResponseSchema = BaseResponseSchema.extend({
 export const ListRecordResponseSchema = BaseResponseSchema.extend({
   data: z.array(RecordDataSchema).describe('Array of matching records'),
   pagination: z.object({
-    total: z.number().describe('Total matching records count'),
-    limit: z.number().describe('Page size'),
-    offset: z.number().describe('Page offset'),
+    total: z.number().optional().describe('Total matching records count'),
+    limit: z.number().optional().describe('Page size'),
+    offset: z.number().optional().describe('Page offset'),
+    cursor: z.string().optional().describe('Cursor for next page'),
+    nextCursor: z.string().optional().describe('Next cursor for pagination'),
     hasMore: z.boolean().describe('Are there more pages?'),
   }).describe('Pagination info'),
 });
 
+/**
+ * ID Request (Get/Delete)
+ */
+export const IdRequestSchema = z.object({
+  id: z.string().describe('Record ID'),
+});
+
 /**
  * Modification Result (for Batch/Bulk operations)
  */
 export const ModificationResultSchema = z.object({
   id: z.string().optional().describe('Record ID if processed'),
   success: z.boolean(),
   errors: z.array(ApiErrorSchema).optional(),
+  index: z.number().optional().describe('Index in original request'),
+  data: z.any().optional().describe('Result data (e.g. created record)'),
 });
 
 /**
@@ -111,11 +124,11 @@ export const DeleteResponseSchema = BaseResponseSchema.extend({
 /**
  * Standard API Contracts map
  * Used for generating SDKs and Documentation
- */
-export const ApiContracts = {
-  create: {
-    input: CreateRequestSchema,
-    output: SingleRecordResponseSchema
+ */IdRequestSchema,
+    output: DeleteResponseSchema
+  },
+  get: {
+    input: IdRequestSchema,
   },
   update: {
     input: UpdateRequestSchema,

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

@@ -213,6 +213,9 @@ export const GraphQLQueryConfigSchema = z.object({
     type: z.enum(['offset', 'cursor', 'relay']).default('offset').describe('Pagination style'),
     defaultLimit: z.number().int().min(1).default(20).describe('Default page size'),
     maxLimit: z.number().int().min(1).default(100).describe('Maximum page size'),
+    cursors: z.object({
+      field: z.string().default('id').describe('Field to use for cursor pagination'),
+    }).optional(),
   }).optional().describe('Pagination configuration'),
 
   /** Field selection */

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

@@ -94,9 +94,10 @@ export const RealtimeEventSchema = z.object({
   type: z.string().describe('Event type (e.g., record.created, record.updated)'),
   object: z.string().optional().describe('Object name the event relates to'),
   action: RealtimeAction.optional().describe('Action performed'),
-  payload: z.any().describe('Event payload data'),
+  payload: z.record(z.string(), z.any()).describe('Event payload data'),
   timestamp: z.string().datetime().describe('ISO 8601 datetime when event occurred'),
   userId: z.string().optional().describe('User who triggered the event'),
+  sessionId: z.string().optional().describe('Session identifier'),
 });
 
 export type RealtimeEvent = z.infer<typeof RealtimeEventSchema>;

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { HttpMethod } from '../shared/http.zod';
+import { HttpMethod, RateLimitConfigSchema } from '../shared/http.zod';
 import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 
 /**
@@ -374,6 +374,12 @@ export const ApiEndpointRegistrationSchema = z.object({
   /** Response definitions */
   responses: z.array(ApiResponseSchema).optional().default([]).describe('Possible responses'),
 
+  /** Rate Limiting */
+  rateLimit: RateLimitConfigSchema.optional().describe('Endpoint specific rate limiting'),
+
+  /** Security Requirements */
+  security: z.array(z.record(z.string(), z.array(z.string()))).optional().describe('Security requirements (e.g. [{"bearerAuth": []}])'),
+  
   /**
    * Required Permissions (RBAC Integration)
    * 

packages/spec/src/api/rest-server.zod.ts

@@ -45,7 +45,7 @@ export const RestApiConfigSchema = z.object({
   /**
    * API version identifier
    */
-  version: z.string().default('v1').describe('API version (e.g., v1, v2, 2024-01)'),
+  version: z.string().regex(/^[a-zA-Z0-9_\-\.]+$/).default('v1').describe('API version (e.g., v1, v2, 2024-01)'),
 
   /**
    * Base path for all API routes