@celigo/api-specs 0.2.162 → 0.2.164

package/dist/ai-agent.yml

@@ -1299,7 +1299,7 @@ components:
                           description: Property names the model must include in the structured output.
                           items:
                             type: string
-                        additionalproperties:
+                        additionalProperties:
                           type: boolean
                           description: When true, the structured output may include properties beyond those defined in `properties`.
                     schema:
@@ -2343,7 +2343,8 @@ components:
             fields. There is no separate `date` enum value.
 
             **Complex Types (require additional configuration)**
-            - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+            - `object`: Creates a nested object from child mappings in the 'mappings' array, or
+              copies a whole object with `extract` (one or the other, not both)
 
             **Array Types**
             - `stringarray`: Array of strings
@@ -2391,7 +2392,7 @@ components:
             string: Text values; converts other types to their string representation.
             number: Numeric values; attempts conversion from strings.
             boolean: True/false values; converts truthy/falsy values.
-            object: Nested object that requires child mappings in the `mappings` array.
+            object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
             stringarray: Array of string values.
             numberarray: Array of numeric values.
             booleanarray: Array of boolean values.
@@ -2469,7 +2470,10 @@ components:
             - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
             - The system maintains this context even in deeply nested mappings
             - For object mappings without child mappings, extract should return a complete object
-            - When both extract and mappings are defined for objects, extract is applied first
+            - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+              both: a row with both fails with 422 (`"extract" should not be present if
+              "mappings" field is present`). A `buildArrayHelper` entry is different: there
+              `extract` and `mappings` work together.
             - The root is the record as it arrives: an object record roots at `$.field`; a
               grouped record (an array of rows — grouped exports, file key columns, NetSuite
               grouped saved searches) roots at the array, so its rows are addressed as
@@ -3423,7 +3427,8 @@ components:
               fields. There is no separate `date` enum value.
 
               **Complex Types (require additional configuration)**
-              - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+              - `object`: Creates a nested object from child mappings in the 'mappings' array, or
+                copies a whole object with `extract` (one or the other, not both)
 
               **Array Types**
               - `stringarray`: Array of strings
@@ -3471,7 +3476,7 @@ components:
               string: Text values; converts other types to their string representation.
               number: Numeric values; attempts conversion from strings.
               boolean: True/false values; converts truthy/falsy values.
-              object: Nested object that requires child mappings in the `mappings` array.
+              object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
               stringarray: Array of string values.
               numberarray: Array of numeric values.
               booleanarray: Array of boolean values.
@@ -3549,7 +3554,10 @@ components:
               - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
               - The system maintains this context even in deeply nested mappings
               - For object mappings without child mappings, extract should return a complete object
-              - When both extract and mappings are defined for objects, extract is applied first
+              - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+                both: a row with both fails with 422 (`"extract" should not be present if
+                "mappings" field is present`). A `buildArrayHelper` entry is different: there
+                `extract` and `mappings` work together.
               - The root is the record as it arrives: an object record roots at `$.field`; a
                 grouped record (an array of rows — grouped exports, file key columns, NetSuite
                 grouped saved searches) roots at the array, so its rows are addressed as
@@ -5628,10 +5636,11 @@ components:
                       ALWAYS reference the `record` root regardless of
                       `inputContext` — only JSONPath anchoring flips.
                     - |-
-                      In `envelope` mode a `modify` transform merges its mapped
-                      fields into `record` and keeps the rest of the envelope
-                      around it; a `create` transform returns only the mapped
-                      fields, as a bare record.
+                      In `envelope` mode the output is still a bare record: a
+                      `modify` transform returns the record with its mapped
+                      fields merged in (no `record` wrapper, no `job` or
+                      `settings` keys), and a `create` transform returns only
+                      the mapped fields.
                     - |-
                       Emit `inputContext` explicitly on new v2 transforms:
                       unset is read as `record`, but stating it makes the

package/dist/asynchelper.yml

@@ -552,7 +552,8 @@ components:
             fields. There is no separate `date` enum value.
 
             **Complex Types (require additional configuration)**
-            - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+            - `object`: Creates a nested object from child mappings in the 'mappings' array, or
+              copies a whole object with `extract` (one or the other, not both)
 
             **Array Types**
             - `stringarray`: Array of strings
@@ -600,7 +601,7 @@ components:
             string: Text values; converts other types to their string representation.
             number: Numeric values; attempts conversion from strings.
             boolean: True/false values; converts truthy/falsy values.
-            object: Nested object that requires child mappings in the `mappings` array.
+            object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
             stringarray: Array of string values.
             numberarray: Array of numeric values.
             booleanarray: Array of boolean values.
@@ -678,7 +679,10 @@ components:
             - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
             - The system maintains this context even in deeply nested mappings
             - For object mappings without child mappings, extract should return a complete object
-            - When both extract and mappings are defined for objects, extract is applied first
+            - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+              both: a row with both fails with 422 (`"extract" should not be present if
+              "mappings" field is present`). A `buildArrayHelper` entry is different: there
+              `extract` and `mappings` work together.
             - The root is the record as it arrives: an object record roots at `$.field`; a
               grouped record (an array of rows — grouped exports, file key columns, NetSuite
               grouped saved searches) roots at the array, so its rows are addressed as
@@ -1632,7 +1636,8 @@ components:
               fields. There is no separate `date` enum value.
 
               **Complex Types (require additional configuration)**
-              - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+              - `object`: Creates a nested object from child mappings in the 'mappings' array, or
+                copies a whole object with `extract` (one or the other, not both)
 
               **Array Types**
               - `stringarray`: Array of strings
@@ -1680,7 +1685,7 @@ components:
               string: Text values; converts other types to their string representation.
               number: Numeric values; attempts conversion from strings.
               boolean: True/false values; converts truthy/falsy values.
-              object: Nested object that requires child mappings in the `mappings` array.
+              object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
               stringarray: Array of string values.
               numberarray: Array of numeric values.
               booleanarray: Array of boolean values.
@@ -1758,7 +1763,10 @@ components:
               - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
               - The system maintains this context even in deeply nested mappings
               - For object mappings without child mappings, extract should return a complete object
-              - When both extract and mappings are defined for objects, extract is applied first
+              - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+                both: a row with both fails with 422 (`"extract" should not be present if
+                "mappings" field is present`). A `buildArrayHelper` entry is different: there
+                `extract` and `mappings` work together.
               - The root is the record as it arrives: an object record roots at `$.field`; a
                 grouped record (an array of rows — grouped exports, file key columns, NetSuite
                 grouped saved searches) roots at the array, so its rows are addressed as
@@ -3173,10 +3181,11 @@ components:
                       ALWAYS reference the `record` root regardless of
                       `inputContext` — only JSONPath anchoring flips.
                     - |-
-                      In `envelope` mode a `modify` transform merges its mapped
-                      fields into `record` and keeps the rest of the envelope
-                      around it; a `create` transform returns only the mapped
-                      fields, as a bare record.
+                      In `envelope` mode the output is still a bare record: a
+                      `modify` transform returns the record with its mapped
+                      fields merged in (no `record` wrapper, no `job` or
+                      `settings` keys), and a `create` transform returns only
+                      the mapped fields.
                     - |-
                       Emit `inputContext` explicitly on new v2 transforms:
                       unset is read as `record`, but stating it makes the

package/dist/audit.yml

@@ -145,7 +145,7 @@ paths:
               script: Script resource for custom JavaScript hooks.
               ssoclient: SSO client configuration resource.
               stack: Stack resource for on-premise or Lambda execution environments.
-              supportshare: Support share access grant resource.
+              supportshare: Celigo Support access grant, made in the integrator.io UI. The API has no support-share route, so these audit entries are its only API view.
               sync: Sync resource.
               tool: Tool resource for reusable building blocks.
               topic: Event Streams topic resource.
@@ -577,7 +577,7 @@ paths:
               script: Script resource for custom JavaScript hooks.
               ssoclient: SSO client configuration resource.
               stack: Stack resource for on-premise or Lambda execution environments.
-              supportshare: Support share access grant resource.
+              supportshare: Celigo Support access grant, made in the integrator.io UI. The API has no support-share route, so these audit entries are its only API view.
               sync: Sync resource.
               tool: Tool resource for reusable building blocks.
               topic: Event Streams topic resource.
@@ -1513,7 +1513,7 @@ components:
             script: Script resource for custom JavaScript hooks.
             ssoclient: SSO client configuration resource.
             stack: Stack resource for on-premise or Lambda execution environments.
-            supportshare: Support share access grant resource.
+            supportshare: Celigo Support access grant, made in the integrator.io UI. The API has no support-share route, so these audit entries are its only API view.
             sync: Sync resource.
             tool: Tool resource for reusable building blocks.
             topic: Event Streams topic resource.
@@ -1720,7 +1720,7 @@ components:
               script: Script resource for custom JavaScript hooks.
               ssoclient: SSO client configuration resource.
               stack: Stack resource for on-premise or Lambda execution environments.
-              supportshare: Support share access grant resource.
+              supportshare: Celigo Support access grant, made in the integrator.io UI. The API has no support-share route, so these audit entries are its only API view.
               sync: Sync resource.
               tool: Tool resource for reusable building blocks.
               topic: Event Streams topic resource.
@@ -1943,7 +1943,7 @@ components:
             script: Script resource for custom JavaScript hooks.
             ssoclient: SSO client configuration resource.
             stack: Stack resource for on-premise or Lambda execution environments.
-            supportshare: Support share access grant resource.
+            supportshare: Celigo Support access grant, made in the integrator.io UI. The API has no support-share route, so these audit entries are its only API view.
             sync: Sync resource.
             tool: Tool resource for reusable building blocks.
             topic: Event Streams topic resource.

package/dist/export.yml

@@ -628,16 +628,19 @@ paths:
         - Exports
       summary: Invoke an export and return its data
       description: |-
-        Runs an existing export end-to-end and returns the fetched data (or errors)
+        Runs an existing export end-to-end and returns its records (or errors)
         synchronously. Unlike `POST /v1/flows/{_id}/run`, which starts a full flow
         job, this endpoint invokes a **single export** in isolation and returns the
-        raw result directly in the response body.
+        result directly in the response body.
 
         The request body is optional — pass `{}` or omit the body entirely for
         exports that require no input. Some adaptor types accept a `data` array in
         the body to supply input records.
 
-        On success, the response contains the export's fetched data. On
+        On success, the response contains the records as the export hands them
+        on: after its transform, output filter and preSavePage hook, so records
+        come back in their final shape and records the filter or hook drops aren't
+        returned. On
         application-level failure (e.g. the source system is unreachable), the
         endpoint still returns a successful HTTP status with the errors in an
         `errors` array — higher-level error codes are reserved for request-level
@@ -688,7 +691,8 @@ paths:
       responses:
         '200':
           description: |-
-            Export completed. The response contains either the fetched data or an
+            Export completed. The response contains either the export's records
+            (after its transform, output filter and preSavePage hook) or an
             `errors` array if the export encountered application-level failures
             (connection timeout, file not found, etc.). Always inspect for errors
             even on 200.
@@ -1340,11 +1344,11 @@ components:
     Once:
       type: object
       description: |-
-        Configures flag-based exports that process each record exactly once. Required when the
-        export's type is "once"; omit for other export types. Each run retrieves records where the
-        tracking boolean field is false, then sets that field to true after successful processing so
-        later runs skip them; if a run fails, the flags are left unchanged and the records are
-        retried automatically on the next run.
+        Configures flag-based exports that skip records an earlier run already processed. Required
+        when the export's type is "once"; omit for other export types. Each run retrieves records
+        where the tracking boolean field is false, then sets that field to true after successful
+        processing so later runs skip them; if a run fails, the flags are left unchanged and the
+        records are retried automatically on the next run.
       x-celigo-ai-guidance:
         - |-
           This object is REQUIRED when the export's type field is set to "once" and should
@@ -1369,7 +1373,6 @@ components:
               - One-time migrations where data should not be duplicated
               - Processing queues where records are marked as "processed"
               - Compliance scenarios requiring audit trails of exported records
-              - Implementing exactly-once delivery semantics
         - |-
           4. Error handling behavior:
               - If the export fails, the boolean fields remain unchanged
@@ -11872,10 +11875,12 @@ components:
 
         **Delta exports (type: "delta")**
         For delta/incremental exports, do NOT populate a `delta` object inside `rdbms`.
-        Instead, use `{{lastExportDateTime}}` or `{{currentExportDateTime}}` directly in the query:
+        Instead, use `{{lastExportDateTime}}` or `{{currentExportDateTime}}` directly in the query, and
+        set the export's top-level `delta.startDate`: without it the first run's window is empty.
         ```json
         {
           "type": "delta",
+          "delta": { "startDate": "2026-01-01T00:00:00.000Z" },
           "rdbms": {
             "query": "SELECT * FROM customers WHERE updatedAt > {{lastExportDateTime}}"
           }
@@ -11948,6 +11953,24 @@ components:
             only — real-time stream listeners (`type` is `stream`) have no SQL query. For delta exports,
             reference {{lastExportDateTime}}/{{currentExportDateTime}} directly in the query rather
             than configuring a separate delta object.
+
+            Double braces render a string as a quoted SQL literal with its apostrophes escaped, and
+            triple braces insert a value raw. Observed in Snowflake queries:
+
+            - String helper output (`dateFormat`, `jsonSerialize`) and both delta variables are
+              quoted the same way; a number or boolean renders bare, whether it is a JSON value or a
+              numeric helper's result (`{{add 2 3}}` renders `5`).
+            - In a run, {{lastExportDateTime}} and {{currentExportDateTime}} arrive as quoted ISO 8601
+              UTC literals with milliseconds (`'2026-01-15T00:00:00.000Z'`), or in `delta.dateFormat`
+              when it is set: add no quotes of your own, and don't parse them with a format mask
+              written for another format.
+            - A preview of an unsaved export document renders both as empty, unquoted text, so a
+              delta query fails to compile there unless the document carries both in `postData`.
+            - The quoting leaves backslashes, which Snowflake reads as escape sequences, so a
+              double-brace value holding a backslash arrives changed. Pass such a value in a
+              dollar-quoted constant with triple braces (`$${{{record.field}}}$$`), which Snowflake
+              reads as is, but only when it can't contain `$$`: a `$$` ends the constant, and the rest
+              is read as SQL.
           x-celigo-ai-guidance:
             - |-
               This field contains the SQL SELECT statement that will be executed to fetch data
@@ -12495,7 +12518,8 @@ components:
             fields. There is no separate `date` enum value.
 
             **Complex Types (require additional configuration)**
-            - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+            - `object`: Creates a nested object from child mappings in the 'mappings' array, or
+              copies a whole object with `extract` (one or the other, not both)
 
             **Array Types**
             - `stringarray`: Array of strings
@@ -12543,7 +12567,7 @@ components:
             string: Text values; converts other types to their string representation.
             number: Numeric values; attempts conversion from strings.
             boolean: True/false values; converts truthy/falsy values.
-            object: Nested object that requires child mappings in the `mappings` array.
+            object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
             stringarray: Array of string values.
             numberarray: Array of numeric values.
             booleanarray: Array of boolean values.
@@ -12621,7 +12645,10 @@ components:
             - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
             - The system maintains this context even in deeply nested mappings
             - For object mappings without child mappings, extract should return a complete object
-            - When both extract and mappings are defined for objects, extract is applied first
+            - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+              both: a row with both fails with 422 (`"extract" should not be present if
+              "mappings" field is present`). A `buildArrayHelper` entry is different: there
+              `extract` and `mappings` work together.
             - The root is the record as it arrives: an object record roots at `$.field`; a
               grouped record (an array of rows — grouped exports, file key columns, NetSuite
               grouped saved searches) roots at the array, so its rows are addressed as
@@ -13575,7 +13602,8 @@ components:
               fields. There is no separate `date` enum value.
 
               **Complex Types (require additional configuration)**
-              - `object`: Creates a nested object. REQUIRES child mappings in the 'mappings' array
+              - `object`: Creates a nested object from child mappings in the 'mappings' array, or
+                copies a whole object with `extract` (one or the other, not both)
 
               **Array Types**
               - `stringarray`: Array of strings
@@ -13623,7 +13651,7 @@ components:
               string: Text values; converts other types to their string representation.
               number: Numeric values; attempts conversion from strings.
               boolean: True/false values; converts truthy/falsy values.
-              object: Nested object that requires child mappings in the `mappings` array.
+              object: Nested object built from child `mappings`, or copied whole with `extract` (not both).
               stringarray: Array of string values.
               numberarray: Array of numeric values.
               booleanarray: Array of boolean values.
@@ -13701,7 +13729,10 @@ components:
               - JSON path patterns ALWAYS execute from the TOP-LEVEL root of the input record
               - The system maintains this context even in deeply nested mappings
               - For object mappings without child mappings, extract should return a complete object
-              - When both extract and mappings are defined for objects, extract is applied first
+              - An `object` row takes `extract` (to copy a whole object) or child `mappings`, not
+                both: a row with both fails with 422 (`"extract" should not be present if
+                "mappings" field is present`). A `buildArrayHelper` entry is different: there
+                `extract` and `mappings` work together.
               - The root is the record as it arrives: an object record roots at `$.field`; a
                 grouped record (an array of rows — grouped exports, file key columns, NetSuite
                 grouped saved searches) roots at the array, so its rows are addressed as
@@ -15116,10 +15147,11 @@ components:
                       ALWAYS reference the `record` root regardless of
                       `inputContext` — only JSONPath anchoring flips.
                     - |-
-                      In `envelope` mode a `modify` transform merges its mapped
-                      fields into `record` and keeps the rest of the envelope
-                      around it; a `create` transform returns only the mapped
-                      fields, as a bare record.
+                      In `envelope` mode the output is still a bare record: a
+                      `modify` transform returns the record with its mapped
+                      fields merged in (no `record` wrapper, no `job` or
+                      `settings` keys), and a `create` transform returns only
+                      the mapped fields.
                     - |-
                       Emit `inputContext` explicitly on new v2 transforms:
                       unset is read as `record`, but stating it makes the
@@ -16523,6 +16555,8 @@ components:
           description: |-
             Custom JavaScript hooks that run at fixed points in the export lifecycle for
             transformations, validation, and filtering beyond what configuration alone can express.
+            A hook name not listed here (an import's `preMap`, for example) is dropped on save
+            without an error, so read `hooks` back after saving.
           properties:
             preSavePage:
               type: object
@@ -17470,11 +17504,14 @@ components:
               type: object
               description: |-
                 Delta window for this preview. Without it, a document preview renders
-                `{{lastExportDateTime}}` and `{{currentExportDateTime}}` as empty strings (observed on
-                HTTP and RDBMS exports), so the preview doesn't reflect the export's delta window. On an
-                HTTP export these strings are substituted exactly as given; other adaptors weren't
-                checked. On an export without `delta.dateFormat`, a real run renders both as ISO 8601 UTC
-                with milliseconds, so pass them in that form to preview the request such a run would send.
+                `{{lastExportDateTime}}` and `{{currentExportDateTime}}` empty, so the preview doesn't
+                reflect the export's delta window: an HTTP request gets empty strings, and an RDBMS
+                query gets empty, unquoted text, so a delta query fails to parse (observed on Snowflake;
+                `delta.startDate` doesn't set them either). With it, an HTTP export inserts each value
+                exactly as given, and an RDBMS query receives each wrapped in single quotes
+                (`'2026-01-15T00:00:00.000Z'`, observed on Snowflake); other adaptors weren't checked.
+                On an export without `delta.dateFormat`, a real run renders both as ISO 8601 UTC with
+                milliseconds, so pass them in that form to preview the request such a run would send.
               properties:
                 currentExportDateTime:
                   type: string

package/dist/guardrail.yml

@@ -997,7 +997,7 @@ components:
                           description: Property names the stored JSON Schema marks as required.
                           items:
                             type: string
-                        additionalproperties:
+                        additionalProperties:
                           type: boolean
                           description: Whether the stored JSON Schema allows properties beyond those in `properties`.
                     schema:
@@ -1938,13 +1938,14 @@ components:
           type: string
           description: |
             Source expression. Accepts:
-            - JSONPath starting with `$.` (e.g. `$.customer.firstName`).
+            - A dot path from the record root (e.g. `email`, `address.city`), read from the
+              incoming record. A path that matches no field writes nothing.
             - Handlebars template (contains `{{`) for concatenation /
               formatting / conditional logic (e.g.
               `{{record.firstName}} {{record.lastName}}`).
-            - A literal string (any value not starting with `$.` and not
-              containing `{{`) — treated as a hardcoded value.
 
+            A `$.` JSONPath (the Mapper 2.0 `mappings` syntax) reads nothing here, and a bare
+            string is read as a field path, not a constant: set constants in `hardCodedValue`.
             Omit when using `hardCodedValue`.
           examples:
             - address.city
@@ -1955,9 +1956,9 @@ components:
           description: Static value written to `generate` instead of extracting from the source record.
           x-celigo-ai-guidance:
             - |-
-              Static value written verbatim. Equivalent to setting ``extract``
-              to a literal string; choose whichever reads more clearly. Mutually
-              exclusive with ``extract``.
+              Static value written verbatim. Use it for every constant: a bare
+              string in ``extract`` is read as a field path. Mutually exclusive
+              with ``extract``.
         dataType:
           type: string
           enum:

package/dist/iclient.yml

@@ -318,8 +318,9 @@ paths:
       x-internal: false
       summary: Update an iClient
       description: |-
-        Replaces an iClient. All mutable fields must be provided — omitted
-        fields are reset to defaults. Secrets returned as `"******"` can be
+        Replaces an existing iClient; create one with `POST /v1/iclients`. All
+        mutable fields must be provided — omitted fields are reset to defaults.
+        Secrets returned as `"******"` can be
         sent back as-is to keep the existing value, except a Google service
         account: every update must include the full JSON key. An Azure
         service principal keeps its stored `clientSecret` or `certificate`