@objectstack/spec 0.6.1 → 0.7.2

package/dist/automation/sync.zod.d.ts

@@ -1,13 +1,42 @@
 import { z } from 'zod';
 /**
- * Data Sync Protocol
+ * Data Sync Protocol - LEVEL 1: Simple Synchronization
  *
  * Inspired by Salesforce Connect, Segment Sync, and Census Reverse ETL.
  *
+ * **Positioning in 3-Layer Architecture:**
+ * - **L1: Simple Sync** (THIS FILE) - Business users - Sync Salesforce to Sheets
+ * - **L2: ETL Pipeline** (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse
+ * - **L3: Enterprise Connector** (integration/connector.zod.ts) - System integrators - Full SAP integration
+ *
  * Data sync provides bidirectional or unidirectional data synchronization
  * between ObjectStack and external systems, maintaining data consistency
  * across platforms.
  *
+ * **SCOPE: Simple field mappings only. NO complex transformations.**
+ * For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (Level 2).
+ *
+ * ## When to Use This Layer
+ *
+ * **Use Simple Sync when:**
+ * - Syncing 1:1 fields between two systems
+ * - Simple field transformations (uppercase, cast, etc.)
+ * - No complex logic required
+ * - Business users need to configure integrations
+ *
+ * **Examples:**
+ * - Salesforce Contact ↔ Google Sheets
+ * - HubSpot Company ↔ CRM Account
+ * - Shopify Orders → Accounting System
+ *
+ * **When to upgrade:**
+ * - Need multi-source joins → Use {@link file://./etl.zod.ts | ETL Pipeline}
+ * - Need complex authentication/webhooks → Use {@link file://../integration/connector.zod.ts | Enterprise Connector}
+ * - Need aggregations or data warehousing → Use {@link file://./etl.zod.ts | ETL Pipeline}
+ *
+ * @see {@link file://./etl.zod.ts} for Level 2 (data engineering)
+ * @see {@link file://../integration/connector.zod.ts} for Level 3 (enterprise integration)
+ *
  * ## Use Cases
  *
  * 1. **CRM Integration**
@@ -68,49 +97,13 @@ export type SyncMode = z.infer<typeof SyncModeSchema>;
 export declare const ConflictResolutionSchema: z.ZodEnum<["source_wins", "destination_wins", "latest_wins", "manual", "merge"]>;
 export type ConflictResolution = z.infer<typeof ConflictResolutionSchema>;
 /**
- * Field Mapping Schema
+ * Field Mapping for Data Sync
+ *
+ * Uses the canonical field mapping protocol from shared/mapping.zod.ts
+ * for simple 1:1 field transformations.
  *
- * Maps fields between source and destination systems.
+ * @see {@link FieldMappingSchema} for the base field mapping schema
  */
-export declare const FieldMappingSchema: z.ZodObject<{
-    /**
-     * Source field name
-     */
-    sourceField: z.ZodString;
-    /**
-     * Destination field name
-     */
-    destinationField: z.ZodString;
-    /**
-     * Transformation formula
-     * JavaScript expression to transform the value
-     *
-     * @example "value.toUpperCase()"
-     * @example "new Date(value).toISOString()"
-     */
-    transform: z.ZodOptional<z.ZodString>;
-    /**
-     * Default value if source is null/undefined
-     */
-    default: z.ZodOptional<z.ZodAny>;
-    /**
-     * Whether to sync null values
-     */
-    syncNull: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    sourceField: string;
-    destinationField: string;
-    syncNull: boolean;
-    default?: any;
-    transform?: string | undefined;
-}, {
-    sourceField: string;
-    destinationField: string;
-    default?: any;
-    transform?: string | undefined;
-    syncNull?: boolean | undefined;
-}>;
-export type FieldMapping = z.infer<typeof FieldMappingSchema>;
 /**
  * Data Source Configuration
  */
@@ -177,42 +170,105 @@ export declare const DataDestinationConfigSchema: z.ZodObject<{
      * Maps source fields to destination fields
      */
     mapping: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodString>, z.ZodArray<z.ZodObject<{
-        /**
-         * Source field name
-         */
-        sourceField: z.ZodString;
-        /**
-         * Destination field name
-         */
-        destinationField: z.ZodString;
-        /**
-         * Transformation formula
-         * JavaScript expression to transform the value
-         *
-         * @example "value.toUpperCase()"
-         * @example "new Date(value).toISOString()"
-         */
-        transform: z.ZodOptional<z.ZodString>;
-        /**
-         * Default value if source is null/undefined
-         */
-        default: z.ZodOptional<z.ZodAny>;
-        /**
-         * Whether to sync null values
-         */
-        syncNull: z.ZodDefault<z.ZodBoolean>;
+        source: z.ZodString;
+        target: z.ZodString;
+        transform: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"constant">;
+            value: z.ZodAny;
+        }, "strip", z.ZodTypeAny, {
+            type: "constant";
+            value?: any;
+        }, {
+            type: "constant";
+            value?: any;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"cast">;
+            targetType: z.ZodEnum<["string", "number", "boolean", "date"]>;
+        }, "strip", z.ZodTypeAny, {
+            type: "cast";
+            targetType: "string" | "number" | "boolean" | "date";
+        }, {
+            type: "cast";
+            targetType: "string" | "number" | "boolean" | "date";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"lookup">;
+            table: z.ZodString;
+            keyField: z.ZodString;
+            valueField: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: "lookup";
+            table: string;
+            keyField: string;
+            valueField: string;
+        }, {
+            type: "lookup";
+            table: string;
+            keyField: string;
+            valueField: string;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"javascript">;
+            expression: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: "javascript";
+            expression: string;
+        }, {
+            type: "javascript";
+            expression: string;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"map">;
+            mappings: z.ZodRecord<z.ZodString, z.ZodAny>;
+        }, "strip", z.ZodTypeAny, {
+            type: "map";
+            mappings: Record<string, any>;
+        }, {
+            type: "map";
+            mappings: Record<string, any>;
+        }>]>>;
+        defaultValue: z.ZodOptional<z.ZodAny>;
     }, "strip", z.ZodTypeAny, {
-        sourceField: string;
-        destinationField: string;
-        syncNull: boolean;
-        default?: any;
-        transform?: string | undefined;
+        source: string;
+        target: string;
+        transform?: {
+            type: "constant";
+            value?: any;
+        } | {
+            type: "cast";
+            targetType: "string" | "number" | "boolean" | "date";
+        } | {
+            type: "lookup";
+            table: string;
+            keyField: string;
+            valueField: string;
+        } | {
+            type: "javascript";
+            expression: string;
+        } | {
+            type: "map";
+            mappings: Record<string, any>;
+        } | undefined;
+        defaultValue?: any;
     }, {
-        sourceField: string;
-        destinationField: string;
-        default?: any;
-        transform?: string | undefined;
-        syncNull?: boolean | undefined;
+        source: string;
+        target: string;
+        transform?: {
+            type: "constant";
+            value?: any;
+        } | {
+            type: "cast";
+            targetType: "string" | "number" | "boolean" | "date";
+        } | {
+            type: "lookup";
+            table: string;
+            keyField: string;
+            valueField: string;
+        } | {
+            type: "javascript";
+            expression: string;
+        } | {
+            type: "map";
+            mappings: Record<string, any>;
+        } | undefined;
+        defaultValue?: any;
     }>, "many">]>>;
     /**
      * External resource identifier
@@ -227,11 +283,27 @@ export declare const DataDestinationConfigSchema: z.ZodObject<{
     operation: "insert" | "update" | "delete" | "upsert" | "sync";
     object?: string | undefined;
     mapping?: Record<string, string> | {
-        sourceField: string;
-        destinationField: string;
-        syncNull: boolean;
-        default?: any;
-        transform?: string | undefined;
+        source: string;
+        target: string;
+        transform?: {
+            type: "constant";
+            value?: any;
+        } | {
+            type: "cast";
+            targetType: "string" | "number" | "boolean" | "date";
+        } | {
+            type: "lookup";
+            table: string;
+            keyField: string;
+            valueField: string;
+        } | {
+            type: "javascript";
+            expression: string;
+        } | {
+            type: "map";
+            mappings: Record<string, any>;
+        } | undefined;
+        defaultValue?: any;
     }[] | undefined;
     connectorInstanceId?: string | undefined;
     externalResource?: string | undefined;
@@ -240,11 +312,27 @@ export declare const DataDestinationConfigSchema: z.ZodObject<{
     operation: "insert" | "update" | "delete" | "upsert" | "sync";
     object?: string | undefined;
     mapping?: Record<string, string> | {
-        sourceField: string;
-        destinationField: string;
-        default?: any;
-        transform?: string | undefined;
-        syncNull?: boolean | undefined;
+        source: string;
+        target: string;
+        transform?: {
+            type: "constant";
+            value?: any;
+        } | {
+            type: "cast";
+            targetType: "string" | "number" | "boolean" | "date";
+        } | {
+            type: "lookup";
+            table: string;
+            keyField: string;
+            valueField: string;
+        } | {
+            type: "javascript";
+            expression: string;
+        } | {
+            type: "map";
+            mappings: Record<string, any>;
+        } | undefined;
+        defaultValue?: any;
     }[] | undefined;
     connectorInstanceId?: string | undefined;
     externalResource?: string | undefined;
@@ -334,42 +422,105 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
          * Maps source fields to destination fields
          */
         mapping: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodString>, z.ZodArray<z.ZodObject<{
-            /**
-             * Source field name
-             */
-            sourceField: z.ZodString;
-            /**
-             * Destination field name
-             */
-            destinationField: z.ZodString;
-            /**
-             * Transformation formula
-             * JavaScript expression to transform the value
-             *
-             * @example "value.toUpperCase()"
-             * @example "new Date(value).toISOString()"
-             */
-            transform: z.ZodOptional<z.ZodString>;
-            /**
-             * Default value if source is null/undefined
-             */
-            default: z.ZodOptional<z.ZodAny>;
-            /**
-             * Whether to sync null values
-             */
-            syncNull: z.ZodDefault<z.ZodBoolean>;
+            source: z.ZodString;
+            target: z.ZodString;
+            transform: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+                type: z.ZodLiteral<"constant">;
+                value: z.ZodAny;
+            }, "strip", z.ZodTypeAny, {
+                type: "constant";
+                value?: any;
+            }, {
+                type: "constant";
+                value?: any;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"cast">;
+                targetType: z.ZodEnum<["string", "number", "boolean", "date"]>;
+            }, "strip", z.ZodTypeAny, {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            }, {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"lookup">;
+                table: z.ZodString;
+                keyField: z.ZodString;
+                valueField: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            }, {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"javascript">;
+                expression: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                type: "javascript";
+                expression: string;
+            }, {
+                type: "javascript";
+                expression: string;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"map">;
+                mappings: z.ZodRecord<z.ZodString, z.ZodAny>;
+            }, "strip", z.ZodTypeAny, {
+                type: "map";
+                mappings: Record<string, any>;
+            }, {
+                type: "map";
+                mappings: Record<string, any>;
+            }>]>>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
         }, "strip", z.ZodTypeAny, {
-            sourceField: string;
-            destinationField: string;
-            syncNull: boolean;
-            default?: any;
-            transform?: string | undefined;
+            source: string;
+            target: string;
+            transform?: {
+                type: "constant";
+                value?: any;
+            } | {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            } | {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            } | {
+                type: "javascript";
+                expression: string;
+            } | {
+                type: "map";
+                mappings: Record<string, any>;
+            } | undefined;
+            defaultValue?: any;
         }, {
-            sourceField: string;
-            destinationField: string;
-            default?: any;
-            transform?: string | undefined;
-            syncNull?: boolean | undefined;
+            source: string;
+            target: string;
+            transform?: {
+                type: "constant";
+                value?: any;
+            } | {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            } | {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            } | {
+                type: "javascript";
+                expression: string;
+            } | {
+                type: "map";
+                mappings: Record<string, any>;
+            } | undefined;
+            defaultValue?: any;
         }>, "many">]>>;
         /**
          * External resource identifier
@@ -384,11 +535,27 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         operation: "insert" | "update" | "delete" | "upsert" | "sync";
         object?: string | undefined;
         mapping?: Record<string, string> | {
-            sourceField: string;
-            destinationField: string;
-            syncNull: boolean;
-            default?: any;
-            transform?: string | undefined;
+            source: string;
+            target: string;
+            transform?: {
+                type: "constant";
+                value?: any;
+            } | {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            } | {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            } | {
+                type: "javascript";
+                expression: string;
+            } | {
+                type: "map";
+                mappings: Record<string, any>;
+            } | undefined;
+            defaultValue?: any;
         }[] | undefined;
         connectorInstanceId?: string | undefined;
         externalResource?: string | undefined;
@@ -397,11 +564,27 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         operation: "insert" | "update" | "delete" | "upsert" | "sync";
         object?: string | undefined;
         mapping?: Record<string, string> | {
-            sourceField: string;
-            destinationField: string;
-            default?: any;
-            transform?: string | undefined;
-            syncNull?: boolean | undefined;
+            source: string;
+            target: string;
+            transform?: {
+                type: "constant";
+                value?: any;
+            } | {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            } | {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            } | {
+                type: "javascript";
+                expression: string;
+            } | {
+                type: "map";
+                mappings: Record<string, any>;
+            } | undefined;
+            defaultValue?: any;
         }[] | undefined;
         connectorInstanceId?: string | undefined;
         externalResource?: string | undefined;
@@ -533,11 +716,11 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         retainLogsForDays: z.ZodDefault<z.ZodNumber>;
         trackChanges: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        logLevel: "error" | "info" | "none" | "debug" | "warn";
+        logLevel: "error" | "info" | "none" | "warn" | "debug";
         retainLogsForDays: number;
         trackChanges: boolean;
     }, {
-        logLevel?: "error" | "info" | "none" | "debug" | "warn" | undefined;
+        logLevel?: "error" | "info" | "none" | "warn" | "debug" | undefined;
         retainLogsForDays?: number | undefined;
         trackChanges?: boolean | undefined;
     }>>;
@@ -550,8 +733,6 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
      */
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
-    enabled: boolean;
     source: {
         object?: string | undefined;
         fields?: string[] | undefined;
@@ -559,24 +740,42 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         connectorInstanceId?: string | undefined;
         externalResource?: string | undefined;
     };
-    batchSize: number;
-    direction: "push" | "pull" | "bidirectional";
+    enabled: boolean;
+    name: string;
     destination: {
         operation: "insert" | "update" | "delete" | "upsert" | "sync";
         object?: string | undefined;
         mapping?: Record<string, string> | {
-            sourceField: string;
-            destinationField: string;
-            syncNull: boolean;
-            default?: any;
-            transform?: string | undefined;
+            source: string;
+            target: string;
+            transform?: {
+                type: "constant";
+                value?: any;
+            } | {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            } | {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            } | {
+                type: "javascript";
+                expression: string;
+            } | {
+                type: "map";
+                mappings: Record<string, any>;
+            } | undefined;
+            defaultValue?: any;
         }[] | undefined;
         connectorInstanceId?: string | undefined;
         externalResource?: string | undefined;
         matchKey?: string[] | undefined;
     };
-    syncMode: "full" | "incremental" | "realtime";
+    batchSize: number;
+    direction: "push" | "pull" | "bidirectional";
     conflictResolution: "merge" | "manual" | "source_wins" | "destination_wins" | "latest_wins";
+    syncMode: "full" | "realtime" | "incremental";
     validation?: {
         custom?: {
             message: string;
@@ -589,17 +788,17 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
     tags?: string[] | undefined;
     label?: string | undefined;
     description?: string | undefined;
+    retry?: {
+        backoffMs: number;
+        maxAttempts: number;
+    } | undefined;
     metadata?: Record<string, any> | undefined;
     schedule?: string | undefined;
     audit?: {
-        logLevel: "error" | "info" | "none" | "debug" | "warn";
+        logLevel: "error" | "info" | "none" | "warn" | "debug";
         retainLogsForDays: number;
         trackChanges: boolean;
     } | undefined;
-    retry?: {
-        backoffMs: number;
-        maxAttempts: number;
-    } | undefined;
     changeTrackingField?: string | undefined;
     errorHandling?: {
         onValidationError: "log" | "skip" | "fail";
@@ -612,7 +811,6 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         compressionEnabled: boolean;
     } | undefined;
 }, {
-    name: string;
     source: {
         object?: string | undefined;
         fields?: string[] | undefined;
@@ -620,15 +818,32 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         connectorInstanceId?: string | undefined;
         externalResource?: string | undefined;
     };
+    name: string;
     destination: {
         operation: "insert" | "update" | "delete" | "upsert" | "sync";
         object?: string | undefined;
         mapping?: Record<string, string> | {
-            sourceField: string;
-            destinationField: string;
-            default?: any;
-            transform?: string | undefined;
-            syncNull?: boolean | undefined;
+            source: string;
+            target: string;
+            transform?: {
+                type: "constant";
+                value?: any;
+            } | {
+                type: "cast";
+                targetType: "string" | "number" | "boolean" | "date";
+            } | {
+                type: "lookup";
+                table: string;
+                keyField: string;
+                valueField: string;
+            } | {
+                type: "javascript";
+                expression: string;
+            } | {
+                type: "map";
+                mappings: Record<string, any>;
+            } | undefined;
+            defaultValue?: any;
         }[] | undefined;
         connectorInstanceId?: string | undefined;
         externalResource?: string | undefined;
@@ -643,25 +858,25 @@ export declare const DataSyncConfigSchema: z.ZodObject<{
         required?: string[] | undefined;
         unique?: string[] | undefined;
     } | undefined;
+    enabled?: boolean | undefined;
     tags?: string[] | undefined;
     label?: string | undefined;
     description?: string | undefined;
-    enabled?: boolean | undefined;
+    retry?: {
+        backoffMs?: number | undefined;
+        maxAttempts?: number | undefined;
+    } | undefined;
+    batchSize?: number | undefined;
     metadata?: Record<string, any> | undefined;
     schedule?: string | undefined;
+    direction?: "push" | "pull" | "bidirectional" | undefined;
+    conflictResolution?: "merge" | "manual" | "source_wins" | "destination_wins" | "latest_wins" | undefined;
     audit?: {
-        logLevel?: "error" | "info" | "none" | "debug" | "warn" | undefined;
+        logLevel?: "error" | "info" | "none" | "warn" | "debug" | undefined;
         retainLogsForDays?: number | undefined;
         trackChanges?: boolean | undefined;
     } | undefined;
-    batchSize?: number | undefined;
-    direction?: "push" | "pull" | "bidirectional" | undefined;
-    syncMode?: "full" | "incremental" | "realtime" | undefined;
-    retry?: {
-        backoffMs?: number | undefined;
-        maxAttempts?: number | undefined;
-    } | undefined;
-    conflictResolution?: "merge" | "manual" | "source_wins" | "destination_wins" | "latest_wins" | undefined;
+    syncMode?: "full" | "realtime" | "incremental" | undefined;
     changeTrackingField?: string | undefined;
     errorHandling?: {
         onValidationError?: "log" | "skip" | "fail" | undefined;
@@ -765,19 +980,19 @@ export declare const SyncExecutionResultSchema: z.ZodObject<{
      */
     logs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    status: "partial" | "running" | "failed" | "pending" | "completed" | "cancelled";
+    status: "partial" | "pending" | "completed" | "failed" | "running" | "cancelled";
     id: string;
     startedAt: string;
     syncName: string;
     durationMs?: number | undefined;
     completedAt?: string | undefined;
-    logs?: string[] | undefined;
     errors?: {
         message: string;
         code?: string | undefined;
         field?: string | undefined;
         recordId?: string | undefined;
     }[] | undefined;
+    logs?: string[] | undefined;
     stats?: {
         recordsErrored: number;
         recordsProcessed: number;
@@ -789,19 +1004,19 @@ export declare const SyncExecutionResultSchema: z.ZodObject<{
         conflictsResolved: number;
     } | undefined;
 }, {
-    status: "partial" | "running" | "failed" | "pending" | "completed" | "cancelled";
+    status: "partial" | "pending" | "completed" | "failed" | "running" | "cancelled";
     id: string;
     startedAt: string;
     syncName: string;
     durationMs?: number | undefined;
     completedAt?: string | undefined;
-    logs?: string[] | undefined;
     errors?: {
         message: string;
         code?: string | undefined;
         field?: string | undefined;
         recordId?: string | undefined;
     }[] | undefined;
+    logs?: string[] | undefined;
     stats?: {
         recordsErrored?: number | undefined;
         recordsProcessed?: number | undefined;