Add API contract schemas for CRUD and bulk operations

Introduces contract.zod.ts with Zod schemas for standard API request and response payloads, including create, update, delete, get, list, and bulk operations. Also exports these contracts from the package entry point for SDK and documentation generation.

Author: hotlong

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

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { QuerySchema } from './query.zod';
+
+// ==========================================
+// 1. Base Envelopes
+// ==========================================
+
+export const ApiErrorSchema = z.object({
+  code: z.string().describe('Error code (e.g. validation_error)'),
+  message: z.string().describe('Readable error message'),
+  details: z.any().optional().describe('Additional error context (e.g. field validation errors)'),
+});
+
+export const BaseResponseSchema = z.object({
+  success: z.boolean().describe('Operation success status'),
+  error: ApiErrorSchema.optional().describe('Error details if success is false'),
+  meta: z.object({
+    timestamp: z.string(),
+    duration: z.number().optional(),
+    requestId: z.string().optional(),
+    traceId: z.string().optional(),
+  }).optional().describe('Response metadata'),
+});
+
+// ==========================================
+// 2. Request Payloads (Inputs)
+// ==========================================
+
+export const RecordDataSchema = z.record(z.any()).describe('Key-value map of record data');
+
+/**
+ * Standard Create Request
+ */
+export const CreateRequestSchema = z.object({
+  data: RecordDataSchema.describe('Record data to insert'),
+});
+
+/**
+ * Standard Update Request
+ */
+export const UpdateRequestSchema = z.object({
+  data: RecordDataSchema.describe('Partial record data to update'),
+});
+
+/**
+ * Standard Bulk Request
+ */
+export const BulkRequestSchema = z.object({
+  records: z.array(RecordDataSchema).describe('Array of records to process'),
+  allOrNone: z.boolean().default(true).describe('If true, rollback entire transaction on any failure'),
+});
+
+/**
+ * Export Request
+ */
+export const ExportRequestSchema = QuerySchema.extend({
+  format: z.enum(['csv', 'json', 'xlsx']).default('csv'),
+});
+
+// ==========================================
+// 3. Response Payloads (Outputs)
+// ==========================================
+
+/**
+ * Single Record Response (Get/Create/Update)
+ */
+export const SingleRecordResponseSchema = BaseResponseSchema.extend({
+  data: RecordDataSchema.describe('The requested or modified record'),
+});
+
+/**
+ * List/Query Response
+ */
+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'),
+    hasMore: z.boolean().describe('Are there more pages?'),
+  }).describe('Pagination info'),
+});
+
+/**
+ * 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(),
+});
+
+/**
+ * Bulk Operation Response
+ */
+export const BulkResponseSchema = BaseResponseSchema.extend({
+  data: z.array(ModificationResultSchema).describe('Results for each item in the batch'),
+});
+
+/**
+ * Delete Response
+ */
+export const DeleteResponseSchema = BaseResponseSchema.extend({
+  id: z.string().describe('ID of the deleted record'),
+});
+
+// ==========================================
+// 4. API Contract Registry
+// ==========================================
+
+/**
+ * Standard API Contracts map
+ * Used for generating SDKs and Documentation
+ */
+export const ApiContracts = {
+  create: {
+    input: CreateRequestSchema,
+    output: SingleRecordResponseSchema
+  },
+  update: {
+    input: UpdateRequestSchema,
+    output: SingleRecordResponseSchema
+  },
+  delete: {
+    input: z.object({}), // usually just ID in URL
+    output: DeleteResponseSchema
+  },
+  get: {
+    input: z.object({}), // usually just ID in URL
+    output: SingleRecordResponseSchema
+  },
+  list: {
+    input: QuerySchema,
+    output: ListRecordResponseSchema
+  },
+  bulk_create: {
+    input: BulkRequestSchema,
+    output: BulkResponseSchema
+  },
+  bulk_update: {
+    input: BulkRequestSchema,
+    output: BulkResponseSchema
+  },
+  bulk_delete: {
+    input: z.object({ ids: z.array(z.string()) }),
+    output: BulkResponseSchema
+  }
+};

packages/spec/src/index.ts

@@ -18,6 +18,7 @@ export * from './data/flow.zod';
 export * from './data/dataset.zod';
 export * from './data/query.zod';
 export * from './data/mapping.zod';
+export * from './data/contract.zod';
 
 // AI Protocol (Agent, RAG)
 export * from './ai/agent.zod';