@celigo/api-specs 0.2.162 → 0.2.164

package/dist/tool.yml

@@ -2426,8 +2426,11 @@ paths:
         input, and its `response` stage holds the saved records. Remove `mockOutput` from the export
         to call the source again. `POST /v1/tools/{_id}/invoke` neither reads nor writes it. Imports
         never send; each returns its saved `mockResponse`, or a placeholder response when none is
-        saved (see `mockResponse` on imports). A second test run started while one is still running
-        is refused with `test_run_not_allowed`.
+        saved (see `mockResponse` on imports). A test run is keyed by the request's `triggeredAt`:
+        one sent with a `triggeredAt` that an earlier test run of the tool already used is refused
+        with 400 `test_run_not_allowed` ("Cannot run the test tool when it is already in the running
+        state."), even after that run has finished. Runs with different `triggeredAt` values run at
+        the same time, each returning its own result.
 
         Test runs are a separate, short-lived history from normal runs — capture
         any follow-up step or log details soon after the run completes.
@@ -2463,6 +2466,13 @@ paths:
                     the tool's saved `input.mockInput` — when this key is
                     absent, the input step receives an empty record.
                   additionalProperties: true
+                triggeredAt:
+                  type: string
+                  format: date-time
+                  description: |-
+                    Identifies the test run; send the current time. A value an earlier
+                    test run of the tool already used is refused with 400
+                    `test_run_not_allowed`.
               additionalProperties: true
               x-celigo-ai-guidance:
                 - 'Always wrap the test input as {"input": {...}} — a bare input object is ignored and the input step receives an empty record, which fails with tool_input_schema_validation_failed when the tool''s input schema has required fields.'
@@ -2554,7 +2564,8 @@ paths:
           description: |-
             The run was refused before any step ran. A Tool with no steps fails with
             `tool_empty_router`, and one whose branches don't all merge back with
-            `tool_dangling_branch`; re-running the same document fails the same way.
+            `tool_dangling_branch`; re-running the same document fails the same way. A
+            `triggeredAt` an earlier test run already used fails with `test_run_not_allowed`.
           content:
             application/json:
               schema:
@@ -3576,7 +3587,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
@@ -3624,7 +3636,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.
@@ -3702,7 +3714,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
@@ -4656,7 +4671,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
@@ -4704,7 +4720,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.
@@ -4782,7 +4798,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
@@ -6197,10 +6216,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
@@ -13767,6 +13787,12 @@ components:
               Avoid bare ``{{{jsonSerialize record}}}`` with no wrapper — leave the field undefined instead.
               Also avoid wrapping a single post-mapped scalar field in ``jsonSerialize`` (e.g.
               ``{{{jsonSerialize record.<scalar>}}}``) — that pattern is brittle.
+            - |-
+              In a JSON body, write a string value with double braces inside the quotes
+              (``"{{record.name}}"``): double braces JSON-escape the value at run time, with no HTML
+              escaping. Triple braces insert the raw text, so a value holding a double quote,
+              backslash, newline or tab fails that record with 422 ``invalid_json`` before anything
+              is sent.
             - |-
               Every request context carries two data roots: ``data`` — the list of records in
               the request, always present (Pattern B) — and ONE shape-specific root that follows
@@ -13896,10 +13922,12 @@ components:
               is almost certainly the "leave body undefined" case (the
               destination just wants the mapped record as JSON) or Pattern C
               (use ``{{sku}}`` / ``{{quantity}}`` directly without
-              ``jsonSerialize`` inside a per-message envelope).  Plain
-              ``{{{record.<field>}}}`` WITHOUT ``jsonSerialize`` is fine for
-              embedding a scalar into a string literal; the anti-pattern is
-              specifically the ``jsonSerialize`` wrap.
+              ``jsonSerialize`` inside a per-message envelope).  To embed a
+              scalar in a JSON string literal, use double braces inside the
+              quotes (``"{{record.<field>}}"``) WITHOUT ``jsonSerialize``;
+              triple braces there fail on a quote, backslash, newline or tab
+              in the value. The anti-pattern is specifically the
+              ``jsonSerialize`` wrap.
             - |-
               ## Multipart/form-data uploads are a different body contract
 
@@ -16701,8 +16729,10 @@ components:
                   `extract` to pick the column when the query returns multiple.
                   Inject values from the incoming record with Handlebars and the
                   `record.` prefix — double braces for strings, which the platform
-                  quotes and escapes, and triple braces for numbers:
-                  `SELECT id FROM users WHERE email = {{record.email}}`.
+                  quotes, escaping their apostrophes, and triple braces for numbers:
+                  `SELECT id FROM users WHERE email = {{record.email}}`. On Snowflake
+                  the quoting leaves backslashes, which Snowflake reads as escape
+                  sequences (see `query`).
               extract:
                 type: string
                 description: |
@@ -16750,10 +16780,11 @@ components:
           description: |-
             SQL statements to execute; required when queryType is `["per_record"]`, `["per_page"]`, or `["first_page"]`, and typically contains a single statement.
             Each element is a complete SQL statement as a plain string — never a single bare string and never an array of objects (objects cause a Cast error).
-            Inject values from the incoming record with Handlebars using the `record.` prefix: double braces for strings and dates (`{{record.name}}`; the platform quotes and escapes the value) and triple braces for numbers (`{{{record.quantity}}}`).
+            Inject values from the incoming record with Handlebars using the `record.` prefix: double braces for strings and dates (`{{record.name}}`; the platform quotes the value and escapes its apostrophes) and triple braces for numbers (`{{{record.quantity}}}`).
             Rendering is strict: a reference the render model cannot resolve (a bare `{{name}}` without prefix, or `record.*` when the arriving record is a grouped array) fails the step with `cannot_evaluate_handlebars` — it does not render an empty value.
             `record` and `rows` are aliases chosen by the arriving data's shape: an object record binds `record` (`rows` undefined); a grouped array-record (e.g. upstream `groupByFields`) binds `rows` (`record` undefined) — address grouped rows as `{{rows.0.field}}` or iterate `{{#each rows}}`.
-            Double braces (`{{record.field}}`) output the value wrapped in single quotes with embedded quotes doubled, while triple braces output it raw; block helpers such as `{{#each}}` and `{{#if}}` use double braces as normal.
+            Double braces (`{{record.field}}`) output a string value wrapped in single quotes with embedded quotes doubled, while triple braces output it raw; block helpers such as `{{#each}}` and `{{#if}}` use double braces as normal. In Snowflake queries a JSON number or boolean renders bare under double braces too (observed in export queries).
+            On Snowflake, the quoting leaves backslashes, which Snowflake reads as escape sequences: a double-brace value holding a backslash arrives changed, and `PARSE_JSON({{jsonSerialize …}})` fails on a double quote or line break in the data (observed in export queries). Pass such values in a dollar-quoted constant with triple braces (`$${{{record.field}}}$$`), which Snowflake reads as is, but only when the value can't contain `$$`: a `$$` in it ends the constant, and the rest is read as SQL.
           x-celigo-ai-guidance:
             - |-
               Use Handlebars to inject values from incoming records.
@@ -16781,14 +16812,18 @@ components:
               - **Double-brace `{{record.field}}` vs. triple-brace `{{{record.field}}}`
                 is a QUOTING CHOICE, not a syntax rule.** In RDBMS context the
                 platform's Handlebars renderer treats double-brace specially: it
-                auto-wraps the value as a SQL string literal (single-quoted, with
-                embedded quotes escaped).  Triple-brace emits the raw value with
-                no quoting.
+                wraps a string value as a SQL string literal (single-quoted, with
+                its apostrophes escaped), and in Snowflake export queries a number
+                or boolean rendered bare, whether a JSON value or a numeric
+                helper's result (`{{add 2 3}}`). Triple-brace emits the raw value
+                with no quoting. In the same queries the wrapping was also seen on
+                string helper output (`dateFormat`, `jsonSerialize`) and on
+                `{{this}}` inside `{{#each}}`.
 
                 - `{{record.name}}`    →  `'Alice'` (auto-single-quoted, embedded `'` doubled to `''`)
-                - `{{{record.name}}}`  →  `Alice`   (raw, no quoting — you must add your own)
-                - `{{record.qty}}`     →  `'5'`     (numbers are also string-wrapped under double-brace)
-                - `{{{record.qty}}}`   →  `5`       (numeric literal — what you usually want for INT columns)
+                - `{{{record.name}}}`  →  `Alice`   (raw — never wrap it in single quotes of your own: the first apostrophe in the data ends the literal)
+                - `{{record.qty}}`     →  `'5'` when `qty` arrives as the string `"5"`; a JSON number rendered bare in Snowflake export queries
+                - `{{{record.qty}}}`   →  `5`       (numeric literal either way — what you usually want for INT columns)
 
                 Pick by what the SQL needs at that slot:
 
@@ -16798,8 +16833,21 @@ components:
                 | Numeric column value (INT, DECIMAL, ...) | `{{{record.field}}}`    |
                 | Stored procedure raw arg (already typed) | `{{{record.field}}}`    |
                 | Identifier (table/column name)           | `{{{record.field}}}`    |
-                | JSON literal (`PARSE_JSON`/JSONB)      | `{{jsonSerialize record.subobject}}` (renders the JSON as a quoted string) |
-
+                | JSON literal, Snowflake (`PARSE_JSON`)   | `PARSE_JSON($${{{jsonSerialize record.subobject}}}$$)` (a dollar-quoted constant, read as is; only for data that can't contain `$$`, which ends it) |
+                | JSON literal, PostgreSQL (`JSONB`)       | `{{jsonSerialize record.subobject}}` (renders the JSON as a quoted string; not yet verified on PostgreSQL) |
+
+              - **Snowflake reads backslashes as escapes.** The double-brace
+                quoting doubles embedded apostrophes but leaves backslashes, and
+                Snowflake interprets backslash sequences inside a single-quoted
+                literal: a value holding `C:\temp` arrives with a tab in it, with
+                no error, and `PARSE_JSON({{jsonSerialize …}})` fails with
+                `Error parsing JSON` whenever a string in the object holds a double
+                quote or a line break, because `jsonSerialize` escapes those with
+                backslashes (observed in export queries). For values that can hold
+                these characters, use a dollar-quoted constant with triple braces
+                (`$${{{record.field}}}$$`), which Snowflake reads as is, but only
+                when the value can't contain `$$`: a `$$` in it ends the constant,
+                and the rest is read as SQL.
               - **Block helpers** (`{{#each}}`, `{{#if}}`, `{{/each}}`,
                 `{{#unless}}`) use double braces as normal — they emit no value.
               - **Nested fields**: `{{record.properties.email}}` (auto-quoted)
@@ -16813,7 +16861,7 @@ components:
               - UPSERT (MySQL): `["INSERT INTO users (id, name) VALUES ({{{record.id}}}, {{record.name}}) ON DUPLICATE KEY UPDATE name = {{record.name}}"]`
               - MERGE (Snowflake): `["MERGE INTO target USING (SELECT {{record.email}} AS email) AS src ON target.email = src.email WHEN MATCHED THEN UPDATE SET name = {{record.name}}"]`
               - Stored procedure (raw args): `["call netsuite.transformation_data_import({{record.record_type}}, 20)"]`
-              - JSON literal column (Snowflake VARIANT): `["INSERT INTO events (payload) SELECT PARSE_JSON({{jsonSerialize record.financialEvents}})"]`
+              - JSON literal column (Snowflake VARIANT; the data must not contain `$$`): `["INSERT INTO events (payload) SELECT PARSE_JSON($${{{jsonSerialize record.financialEvents}}}$$)"]`
               - Per-page batch (different Handlebars context — see `queryType: per_page` below): `["{{#each batch_of_records}}UPDATE staging SET done=1 WHERE id={{{this.record.id}}};{{/each}}"]`
           examples:
             - - INSERT INTO orders (id, total) VALUES ({{{record.id}}}, {{{record.total}}})
@@ -21194,7 +21242,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:
@@ -22585,7 +22633,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:
@@ -24156,13 +24204,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
@@ -24173,9 +24222,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:
@@ -24938,7 +24987,10 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: connectors
-          description: Connector this import was created from, set when the import is part of an installed integration app.
+          description: |-
+            Connector this import was created from, set when the import is part of an installed
+            integration app. The app's install sets it: a create that sends it is refused with 403
+            ("Cannot create an Integration App resource").
           examples:
             - 60a2c4e6f321d800129a1a3c
         adaptorType:
@@ -25480,7 +25532,8 @@ components:
           description: |-
             Custom JavaScript hooks that run at fixed points in the import lifecycle for
             transformations, validation, and custom result handling beyond what configuration alone
-            can express.
+            can express. A hook name not listed here (an export's `preSavePage`, for example) is
+            dropped on save without an error, so read `hooks` back after saving.
           x-celigo-ai-guidance:
             - |-
               JavaScript hook references attached to lifecycle stages of the import.
@@ -26445,11 +26498,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
@@ -26474,7 +26527,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
@@ -36499,10 +36551,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}}"
           }
@@ -36575,6 +36629,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
@@ -37708,6 +37780,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

package/dist/tradingpartnerconnector.yml

@@ -447,7 +447,9 @@ paths:
     delete:
       x-internal: false
       summary: Delete a trading partner connector
-      description: Soft-deletes a trading partner connector.
+      description: |-
+        Deletes a trading partner connector. The recycle bin doesn't take trading partner
+        connectors, so there is no route to restore a deleted one.
       operationId: deleteTradingPartnerConnector
       tags:
         - Trading Partner Connectors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.162",
+  "version": "0.2.164",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [