@celigo/api-specs 0.2.51 → 0.2.53

package/dist/export.yml

@@ -920,7 +920,17 @@ components:
         When grouping is used, the export's page size determines the maximum number of groups per page, not individual
         records. Note that effective grouping typically requires that records with the same group field values appear
         together in the export data.
+
+        Not a webhook listener feature: on a `webhook` export the platform applies it only within each page, after
+        the request has been paged, and only to adjacent rows — the field is not offered for listeners in the UI.
       x-celigo-ai-guidance:
+        - |-
+          Never set this on a webhook listener to keep a request's rows together —
+          the listener pages the request's records at ``pageSize`` FIRST and then
+          merges only adjacent same-key rows inside each page, so rows that cross a
+          page boundary still arrive as separate records and unsorted rows are not
+          grouped at all. Keep a listener's request together by having the sender
+          post an object (one record) or by raising the listener's ``pageSize``.
         - |-
           A grouped record's wire shape is a BARE ARRAY of the grouped rows
           (``[{row}, {row}]``) — there is no ``rows`` key on the record
@@ -2045,7 +2055,10 @@ components:
             - csv
         pathToRecords:
           type: string
-          description: JSON path into the incoming payload to the array of records to emit; when omitted, the whole payload is emitted as a single record.
+          description: JSON path into an object payload to the array whose elements become the records. When omitted, a top-level JSON array is emitted as one record per element and an object payload is emitted as a single record.
+          x-celigo-ai-guidance:
+            - 'Set this only when the records sit inside an object (`{"data": {"items": [...]}}` → `data.items`). A sender that already posts a top-level array needs nothing here; a sender that posts an object with no path configured delivers exactly one record per request — the whole object — which is also the way to make one request one record on purpose.'
+            - 'Records are paged per request at the export''s `pageSize` (default 20) before any hook, filter, or downstream step runs: a 25-element array is a page of 20 records followed by a page of 5, and a `preSavePage` hook receives one page (up to `pageSize` records) per call. A hook that groups rows by order therefore groups only the rows on the same page — an order whose rows span two pages comes out as two grouped records, the second after the first was already processed. To keep a request''s rows together, have the sender wrap them in an object (one record, rows under `record.<path>`) or raise `pageSize` above the largest request — never `groupByFields`, which the listener applies per page after paging.'
           examples:
             - events
             - data.items
@@ -16242,6 +16255,8 @@ components:
             record as one response, capped at 5 MB in total, so the value does not change how many
             results a lookup returns; a result set larger than that belongs in a standalone export
             step. In a test run or preview the value also caps the records fetched (default 20).
+            On a webhook listener the records of each incoming request are paged separately, before
+            any hook or downstream step runs.
           default: 20
           examples:
             - 100

package/dist/import.yml

@@ -1605,7 +1605,17 @@ components:
           description: Internal flag indicating the import was built with the legacy REST form rather than the unified HTTP framework. Set by the form; not configured directly.
         strictHandlebarEvaluation:
           type: boolean
-          description: When true, handlebars expressions that reference a missing field raise an error instead of rendering an empty string, surfacing mapping mistakes early rather than sending blank values.
+          description: Intended to make handlebars expressions that reference a missing field raise an error instead of rendering an empty string. In live runs on an HTTP import it does not have that effect on `http.body` templates or mapping expressions — an undefined path still renders empty and the record succeeds with the flag true — and `relativeURI` / `headers[].value` templates already fail on an undefined path regardless of this flag. Not a safeguard against a wrong template root or a misspelled path.
+          x-celigo-ai-guidance:
+            - |-
+              Do not rely on this flag to catch a mis-rooted or misspelled path. Live-verified
+              2026-09-24 on an HTTP import in real flow runs with the flag ``true``: an undefined
+              ``{{record.<field>}}`` in ``http.body`` and an undefined ``{{<field>}}`` in a mapping
+              expression both rendered empty and the record succeeded — the same outcome as with
+              the flag ``false`` or unset. Relative URI and header templates fail on an undefined
+              path regardless of this flag. To catch a wrong root, check the template against the
+              record's shape (``record`` for an object, ``rows`` for a grouped record,
+              ``batch_of_records`` when ``batchSize`` exceeds 1) before saving.
         formType:
           type: string
           enum:
@@ -1734,8 +1744,17 @@ components:
           description: |-
             Maximum number of records submitted per HTTP request, which affects throughput and API rate limiting.
             REST services typically send one record per request; raise it only for batch endpoints or RPC/XML services that accept multiple records, consulting the target API documentation for the optimal value.
+            Above 1, the body, relative URI, and header templates render once per request against `batch_of_records` — each entry carrying that record as `record` (or `rows` for a grouped record) — and a root-level `record` or `rows` is undefined.
 
             The default varies by API.
+          x-celigo-ai-guidance:
+            - |-
+              A batched import's templates iterate ``{{#each batch_of_records}}`` and address
+              ``this.record.<field>`` (``this.rows.0.<field>`` for grouped records), or iterate
+              the bare records as ``{{#each data}}``; a ``{{record.<field>}}`` left at the root
+              renders empty in the body and fails the request in a relative URI or header. With
+              the default batch size the shape root is ``record`` / ``rows``, ``data`` holds that
+              one record, and ``batch_of_records`` is undefined.
           examples:
             - 1
             - 10
@@ -1830,6 +1849,7 @@ components:
             For composite (upsert) imports, the array is positionally aligned with method and requestType, and existingExtract decides the index used at runtime: the UPDATE index when its field has a value, the CREATE index when it is empty or missing.
             Reference the existing record ID in the UPDATE URI with `{{{data.0.fieldName}}}` (triple braces with the data.0 prefix).
             Use separate array elements per operation rather than `{{#if}}` conditionals inside a single URI.
+            URI templates render strictly: a path that is undefined on the record — such as `record.<field>` on a grouped record, whose root is `rows` — fails the request instead of rendering empty.
           x-celigo-ai-guidance:
             - '**CRITICAL: This MUST be an array of strings, NOT an object.**'
             - |-
@@ -1999,6 +2019,23 @@ 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.
+            - |-
+              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
+              the record entering the step. An object record is ``record``; a GROUPED record (an
+              array of rows — a ``groupByFields`` export, file key columns, a NetSuite grouped
+              saved search) is ``rows`` (``{{rows.0.<field>}}``, ``{{#each rows}}``,
+              ``{{{jsonSerialize rows}}}``) and ``record.*`` is undefined on it; when
+              ``batchSize`` exceeds 1 the shape root is ``batch_of_records`` and neither ``record``
+              nor ``rows`` exists at the top level. Inside ``data`` a grouped record is itself an
+              array element (``{{#each data}}{{#each this}}…{{/each}}{{/each}}``). An object record
+              that carries its own ``rows`` field is still ``record`` — ``{{#each record.rows}}``.
+              Here an undefined path renders empty — and ``strictHandlebarEvaluation: true`` does
+              not change that (live-verified 2026-09-24 in real flow runs: an undefined
+              ``{{record.<field>}}`` in the body rendered empty and the record succeeded); in
+              ``relativeURI`` and ``headers[].value`` templates an undefined path always fails the
+              request — a wrong root there is a runtime failure, not a blank. Verify the body's
+              root against the record shape; no flag will catch it.
             - |-
               ## LEAVE UNDEFINED for the most common case
 
@@ -2074,10 +2111,11 @@ components:
               (the default) the root carries ``record`` (an object record —
               or the fanned-out child on a ``oneToMany`` import) or ``rows``
               (a grouped/array record), and ``data`` is the one-element list
-              of records in the request; with ``batchSize`` > 1 the root
-              carries ``batch_of_records`` (one ``{record: …}`` item per
-              record in the request) and ``data`` (the bare records), and
-              ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
+              of records in the request (a grouped record is that element,
+              itself an array); with ``batchSize`` > 1 the root carries
+              ``batch_of_records`` (one ``{record: …}`` item per object
+              record, ``{rows: […]}`` for a grouped record) and ``data`` (the
+              bare records), and ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
               ``batch_of_records`` appear — children are batched after
               fan-out under the same rule.
 
@@ -2359,7 +2397,7 @@ components:
                 description: Name of the HTTP header to include with each import request.
               value:
                 type: string
-                description: Value sent for the header. Supports handlebars expressions rendered against the pre-mapped record.
+                description: Value sent for the header. Supports handlebars expressions rendered against the pre-mapped record, with the same data roots as the body (`record` / `rows` / `batch_of_records`, plus `data`); an undefined path fails the request rather than rendering empty.
                 x-celigo-agent:
                   - handlebars
                 x-celigo-handlebars-context: pre-mapped

package/dist/tool.yml

@@ -12125,7 +12125,17 @@ components:
           description: Internal flag indicating the import was built with the legacy REST form rather than the unified HTTP framework. Set by the form; not configured directly.
         strictHandlebarEvaluation:
           type: boolean
-          description: When true, handlebars expressions that reference a missing field raise an error instead of rendering an empty string, surfacing mapping mistakes early rather than sending blank values.
+          description: Intended to make handlebars expressions that reference a missing field raise an error instead of rendering an empty string. In live runs on an HTTP import it does not have that effect on `http.body` templates or mapping expressions — an undefined path still renders empty and the record succeeds with the flag true — and `relativeURI` / `headers[].value` templates already fail on an undefined path regardless of this flag. Not a safeguard against a wrong template root or a misspelled path.
+          x-celigo-ai-guidance:
+            - |-
+              Do not rely on this flag to catch a mis-rooted or misspelled path. Live-verified
+              2026-09-24 on an HTTP import in real flow runs with the flag ``true``: an undefined
+              ``{{record.<field>}}`` in ``http.body`` and an undefined ``{{<field>}}`` in a mapping
+              expression both rendered empty and the record succeeded — the same outcome as with
+              the flag ``false`` or unset. Relative URI and header templates fail on an undefined
+              path regardless of this flag. To catch a wrong root, check the template against the
+              record's shape (``record`` for an object, ``rows`` for a grouped record,
+              ``batch_of_records`` when ``batchSize`` exceeds 1) before saving.
         formType:
           type: string
           enum:
@@ -12254,8 +12264,17 @@ components:
           description: |-
             Maximum number of records submitted per HTTP request, which affects throughput and API rate limiting.
             REST services typically send one record per request; raise it only for batch endpoints or RPC/XML services that accept multiple records, consulting the target API documentation for the optimal value.
+            Above 1, the body, relative URI, and header templates render once per request against `batch_of_records` — each entry carrying that record as `record` (or `rows` for a grouped record) — and a root-level `record` or `rows` is undefined.
 
             The default varies by API.
+          x-celigo-ai-guidance:
+            - |-
+              A batched import's templates iterate ``{{#each batch_of_records}}`` and address
+              ``this.record.<field>`` (``this.rows.0.<field>`` for grouped records), or iterate
+              the bare records as ``{{#each data}}``; a ``{{record.<field>}}`` left at the root
+              renders empty in the body and fails the request in a relative URI or header. With
+              the default batch size the shape root is ``record`` / ``rows``, ``data`` holds that
+              one record, and ``batch_of_records`` is undefined.
           examples:
             - 1
             - 10
@@ -12350,6 +12369,7 @@ components:
             For composite (upsert) imports, the array is positionally aligned with method and requestType, and existingExtract decides the index used at runtime: the UPDATE index when its field has a value, the CREATE index when it is empty or missing.
             Reference the existing record ID in the UPDATE URI with `{{{data.0.fieldName}}}` (triple braces with the data.0 prefix).
             Use separate array elements per operation rather than `{{#if}}` conditionals inside a single URI.
+            URI templates render strictly: a path that is undefined on the record — such as `record.<field>` on a grouped record, whose root is `rows` — fails the request instead of rendering empty.
           x-celigo-ai-guidance:
             - '**CRITICAL: This MUST be an array of strings, NOT an object.**'
             - |-
@@ -12519,6 +12539,23 @@ 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.
+            - |-
+              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
+              the record entering the step. An object record is ``record``; a GROUPED record (an
+              array of rows — a ``groupByFields`` export, file key columns, a NetSuite grouped
+              saved search) is ``rows`` (``{{rows.0.<field>}}``, ``{{#each rows}}``,
+              ``{{{jsonSerialize rows}}}``) and ``record.*`` is undefined on it; when
+              ``batchSize`` exceeds 1 the shape root is ``batch_of_records`` and neither ``record``
+              nor ``rows`` exists at the top level. Inside ``data`` a grouped record is itself an
+              array element (``{{#each data}}{{#each this}}…{{/each}}{{/each}}``). An object record
+              that carries its own ``rows`` field is still ``record`` — ``{{#each record.rows}}``.
+              Here an undefined path renders empty — and ``strictHandlebarEvaluation: true`` does
+              not change that (live-verified 2026-09-24 in real flow runs: an undefined
+              ``{{record.<field>}}`` in the body rendered empty and the record succeeded); in
+              ``relativeURI`` and ``headers[].value`` templates an undefined path always fails the
+              request — a wrong root there is a runtime failure, not a blank. Verify the body's
+              root against the record shape; no flag will catch it.
             - |-
               ## LEAVE UNDEFINED for the most common case
 
@@ -12594,10 +12631,11 @@ components:
               (the default) the root carries ``record`` (an object record —
               or the fanned-out child on a ``oneToMany`` import) or ``rows``
               (a grouped/array record), and ``data`` is the one-element list
-              of records in the request; with ``batchSize`` > 1 the root
-              carries ``batch_of_records`` (one ``{record: …}`` item per
-              record in the request) and ``data`` (the bare records), and
-              ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
+              of records in the request (a grouped record is that element,
+              itself an array); with ``batchSize`` > 1 the root carries
+              ``batch_of_records`` (one ``{record: …}`` item per object
+              record, ``{rows: […]}`` for a grouped record) and ``data`` (the
+              bare records), and ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
               ``batch_of_records`` appear — children are batched after
               fan-out under the same rule.
 
@@ -12879,7 +12917,7 @@ components:
                 description: Name of the HTTP header to include with each import request.
               value:
                 type: string
-                description: Value sent for the header. Supports handlebars expressions rendered against the pre-mapped record.
+                description: Value sent for the header. Supports handlebars expressions rendered against the pre-mapped record, with the same data roots as the body (`record` / `rows` / `batch_of_records`, plus `data`); an undefined path fails the request rather than rendering empty.
                 x-celigo-agent:
                   - handlebars
                 x-celigo-handlebars-context: pre-mapped
@@ -24293,7 +24331,17 @@ components:
         When grouping is used, the export's page size determines the maximum number of groups per page, not individual
         records. Note that effective grouping typically requires that records with the same group field values appear
         together in the export data.
+
+        Not a webhook listener feature: on a `webhook` export the platform applies it only within each page, after
+        the request has been paged, and only to adjacent rows — the field is not offered for listeners in the UI.
       x-celigo-ai-guidance:
+        - |-
+          Never set this on a webhook listener to keep a request's rows together —
+          the listener pages the request's records at ``pageSize`` FIRST and then
+          merges only adjacent same-key rows inside each page, so rows that cross a
+          page boundary still arrive as separate records and unsorted rows are not
+          grouped at all. Keep a listener's request together by having the sender
+          post an object (one record) or by raising the listener's ``pageSize``.
         - |-
           A grouped record's wire shape is a BARE ARRAY of the grouped rows
           (``[{row}, {row}]``) — there is no ``rows`` key on the record
@@ -25418,7 +25466,10 @@ components:
             - csv
         pathToRecords:
           type: string
-          description: JSON path into the incoming payload to the array of records to emit; when omitted, the whole payload is emitted as a single record.
+          description: JSON path into an object payload to the array whose elements become the records. When omitted, a top-level JSON array is emitted as one record per element and an object payload is emitted as a single record.
+          x-celigo-ai-guidance:
+            - 'Set this only when the records sit inside an object (`{"data": {"items": [...]}}` → `data.items`). A sender that already posts a top-level array needs nothing here; a sender that posts an object with no path configured delivers exactly one record per request — the whole object — which is also the way to make one request one record on purpose.'
+            - 'Records are paged per request at the export''s `pageSize` (default 20) before any hook, filter, or downstream step runs: a 25-element array is a page of 20 records followed by a page of 5, and a `preSavePage` hook receives one page (up to `pageSize` records) per call. A hook that groups rows by order therefore groups only the rows on the same page — an order whose rows span two pages comes out as two grouped records, the second after the first was already processed. To keep a request''s rows together, have the sender wrap them in an object (one record, rows under `record.<path>`) or raise `pageSize` above the largest request — never `groupByFields`, which the listener applies per page after paging.'
           examples:
             - events
             - data.items
@@ -36136,6 +36187,8 @@ components:
             record as one response, capped at 5 MB in total, so the value does not change how many
             results a lookup returns; a result set larger than that belongs in a standalone export
             step. In a test run or preview the value also caps the records fetched (default 20).
+            On a webhook listener the records of each incoming request are paged separately, before
+            any hook or downstream step runs.
           default: 20
           examples:
             - 100

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "f59fb30",
+		"iasCommit": "5cccadb",
 		"generatedAt": "2026-09-24"
 	},
 	"roots": {