@celigo/api-specs 0.2.51 → 0.2.52

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

@@ -1734,8 +1734,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 +1839,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 +2009,21 @@ 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 by default (``strictHandlebarEvaluation`` is the
+              documented switch to raise instead); in ``relativeURI`` and ``headers[].value``
+              templates an undefined path always fails the request — a wrong root there is a
+              runtime failure, not a blank.
             - |-
               ## LEAVE UNDEFINED for the most common case
 
@@ -2074,10 +2099,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 +2385,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

@@ -12254,8 +12254,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 +12359,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 +12529,21 @@ 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 by default (``strictHandlebarEvaluation`` is the
+              documented switch to raise instead); in ``relativeURI`` and ``headers[].value``
+              templates an undefined path always fails the request — a wrong root there is a
+              runtime failure, not a blank.
             - |-
               ## LEAVE UNDEFINED for the most common case
 
@@ -12594,10 +12619,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 +12905,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 +24319,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 +25454,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 +36175,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.52",
   "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": "b5bc8d2",
 		"generatedAt": "2026-09-24"
 	},
 	"roots": {