@celigo/api-specs 0.2.176 → 0.2.178

package/dist/export.yml

@@ -5608,31 +5608,37 @@ components:
           description: |-
             Selects which files are processed: files matching the filter criteria are exported,
             and non-matching files are skipped entirely before processing begins. Filterable
-            fields come from each file's metadata — most providers expose filename, filesize,
-            and lastmodified (e.g. ["endswith", ["string", ["extract", "filename"]], ".csv"]).
+            fields come from each file's listing entry: the name as `fileName`, the size as
+            `filesize`, and the modified time as `lastModifiedTime` on FTP, SFTP and S3 or
+            `modifiedTime` on cloud-storage folders (`http.type: "file"`)
+            (e.g. ["endswith", ["string", ["extract", "fileName"]], ".csv"]). There is no
+            `lastmodified` key.
           allOf:
             - $ref: '#/components/schemas/Filter'
           x-celigo-ai-guidance:
             - |-
               ## AVAILABLE FILTER FIELDS
 
-              The specific fields available for file filtering are the contained in the `fileMeta` property. 
+              The fields a file filter reads are on each file's listing entry, before the file is
+              downloaded. They are not the records' `fileMeta`, though some names match.
 
               ### Common Filter Fields
 
               These are the most commonly available fields across most file providers:
 
-              1. **filename**: The name of the file (with extension)
+              1. **fileName**: The name of the file (with extension)
                 - Example filter: Match files with specific extensions or naming patterns
-                - Usage: `["endswith", ["string", ["extract", "filename"]], ".csv"]`
+                - Usage: `["endswith", ["string", ["extract", "fileName"]], ".csv"]`
 
               2. **filesize**: The size of the file in bytes
                 - Example filter: Skip files that are too large or too small
                 - Usage: `["lessthan", ["number", ["extract", "filesize"]], 1000000]`
 
-              3. **lastmodified**: The last modification timestamp of the file
+              3. **lastModifiedTime** (FTP, SFTP, S3) or **modifiedTime** (cloud-storage folders): The
+                 last modification timestamp of the file. There is no `lastmodified` key.
                 - Example filter: Process only files created/modified within a specific date range
-                - Usage: `["greaterthan", ["epochtime", ["extract", "lastmodified"]], 1672531200000]` (2023-01-01T00:00:00Z in epoch milliseconds)
+                - Usage (FTP, SFTP, S3): `["greaterthan", ["epochtime", ["extract", "lastModifiedTime"]], 1672531200000]` (2023-01-01T00:00:00Z in epoch milliseconds)
+                - Usage (cloud-storage folders): `["greaterthan", ["epochtime", ["extract", "modifiedTime"]], 1672531200000]`
         backupPath:
           type: string
           description: Path where backup copies of source files are stored before processing.
@@ -6636,7 +6642,10 @@ components:
             - async_helper
         once:
           type: object
-          description: Callback configuration for once exports, used to mark records as exported in the source system after successful processing.
+          description: |-
+            Callback configuration for once exports, used to mark records as exported in the source system after successful processing.
+            Called only while the export's `type` is `once`: an export with no `type` keeps a saved `once` and never calls it, so every
+            run reads every record again (live-verified 2026-10-22).
           properties:
             relativeURI:
               type: string

package/dist/flow.yml

@@ -7208,7 +7208,10 @@ components:
                 - retry
                 - bulk_retry
               x-enumDescriptions:
-                export: A child job for an export step within a flow run.
+                export: |-
+                  A child job for an export step within a flow run: the flow's source export, or a
+                  lookup step (an export with `isLookup`), whose job counts the pages it looked up in
+                  `numPagesProcessed`.
                 import: A child job for an import step within a flow run.
                 flow: A parent flow-run job that orchestrates the full pipeline.
                 retry: A retry of a single failed record from a previous job.
@@ -7438,8 +7441,9 @@ components:
               type: integer
               readOnly: true
               description: |-
-                Number of records skipped, by a filter or by an import's ignore-existing or ignore-missing
-                rule. Records an import's filter skips count in that import's child job; records an export's
+                Number of records skipped: by a filter, by an import's ignore-existing or ignore-missing
+                rule, by an import's preMap hook that returned no data for the record, or by a lookup step's
+                input filter (the record continues without the lookup's data). Records an import's filter skips count in that import's child job; records an export's
                 output filter drops count in the export's child job, whose `numSuccess` then counts only the
                 records that passed (an export that read 6 records and dropped 3 reads `numSuccess` 3,
                 `numIgnore` 3; live-verified 2026-10-22). Filtered records raise no error.
@@ -7466,7 +7470,10 @@ components:
             numPagesProcessed:
               type: integer
               readOnly: true
-              description: Number of pages processed by downstream imports.
+              description: |-
+                Number of pages processed by downstream steps: imports and lookup steps. A source export's
+                child job reads 0, a lookup step's and an import's count the pages they processed, and a
+                parent flow job sums its children.
               examples:
                 - 10
             oIndex:
@@ -8080,11 +8087,13 @@ components:
           enum:
             - success
             - error
-            - ignored
+            - ignore
           x-enumDescriptions:
             success: The record was processed successfully at this step.
             error: The record encountered an error during processing.
-            ignored: The record was skipped by a filter or routing rule.
+            ignore: |-
+              The step skipped the record: its filter, a preMap hook that returned no data for the
+              record, or an ignore-existing or ignore-missing rule. `stage` names which.
         timeTaken:
           type: integer
           description: Milliseconds spent at this step for this record.
@@ -8106,8 +8115,14 @@ components:
             Pipeline stage at which this step entry was recorded. Observed values include `apiCall`
             (the adaptor invocation itself). Useful for filtering metadata responses when a step has
             multiple stage entries across a single record's pass.
+
+            On an entry with `status: ignore`, the stage that skipped the record, recorded even on a run
+            logged at `basic` (whose stage data is empty): `inputFilter` for the step's filter,
+            `preMapHook` for a preMap hook that returned no data for the record, and an empty string for
+            an ignore-existing rule.
           examples:
             - apiCall
+            - inputFilter
     ExecutionLogMetadataResponse:
       type: object
       description: |-

package/dist/import.yml

@@ -1811,7 +1811,7 @@ components:
             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.
             A field the record lacks, or a `{{lookup.<name>}}` whose lookup found nothing, fails that record before anything is sent, with `handlebars_template_parse_error` (source `application`, classification `parse`): `Failed to generate request url from template: <URL>. Details: "<field>" not defined in the model.` That is missing data, not template syntax, and a retry of the same record fails the same way: send records that may lack the destination id through a composite UPDATE/CREATE import (`existingExtract`), or skip them with `ignoreMissing` and `ignoreExtract`.
-            A field that holds an empty string or null is defined: it renders empty, and the request is sent without the value.
+            A field that holds an empty string renders empty, and the request is sent without the value. A field that holds null renders the text `null` (a URI of `/orders/{{record.id}}` is sent as `/orders/null`), and a field under an object that is null fails the record like a missing one (`"<field>" not defined in null`).
           x-celigo-ai-guidance:
             - '**CRITICAL: This MUST be an array of strings, NOT an object.**'
             - |-
@@ -1998,7 +1998,14 @@ components:
               (``"{{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.
+              is sent. Double braces write a null value -- a null field, or any field under an
+              object that is null -- as the text ``null``, so ``"{{record.customer.name}}"`` sends
+              the string "null" (triple braces rendered ``{{{record.customer.name}}}`` empty,
+              whether ``customer`` or its ``name`` was null). Guard a nullable field with
+              ``{{#if record.customer.name}}{{record.customer.name}}{{/if}}`` or
+              ``{{#if record.customer}}{{record.customer.name}}{{/if}}``: both render empty for a
+              null field and for a null object. The Handlebars processor renders the unguarded null
+              empty, so judge it by an import preview or a run.
             - |-
               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
@@ -5418,7 +5425,7 @@ components:
               - bulk_load
           x-enumDescriptions:
             INSERT: Legacy value for insert operations; use bulk_insert or per_record instead.
-            UPDATE: Legacy value for update operations; use per_record instead.
+            UPDATE: Legacy value for update operations; use per_page or per_record instead.
             bulk_insert: Batch INSERT via multi-row VALUES clause for efficient bulk data loading.
             per_record: Execute one SQL statement per record, giving full control over individual record SQL.
             per_page: Execute one SQL statement per page (batch) of records.
@@ -5428,7 +5435,7 @@ components:
           description: |-
             Execution strategy for the SQL operation, which determines the required companion field: per_record, per_page, and first_page require `query`; bulk_insert requires `bulkInsert`; bulk_load requires `bulkLoad`.
             Prefer the highest-performance type the operation supports: bulk_load (Snowflake, Google BigQuery, Microsoft SQL Server on a cloud connection, Azure Synapse and Amazon Redshift — handles INSERT, upsert via `bulkLoad.primaryKeys`, and custom merge or ignore-existing logic via `bulkLoad.overrideMergeQuery`), then bulk_insert for pure INSERTs, then per_page, then per_record only when the logic cannot be expressed as a batch operation.
-            For UPDATE, UPSERT, or ignore-existing logic on databases without bulk_load support, use per_page or per_record with `query` — bulk_insert has no duplicate-checking logic.
+            For UPDATE, UPSERT, or ignore-existing logic on databases without bulk_load support, use per_page or per_record with `query` — bulk_insert has no duplicate-checking logic. Prefer per_page when the statement can loop `batch_of_records`, and use per_record when the SQL can't be written as one batch statement.
             Set a single value; do not combine types or use the legacy INSERT and UPDATE values.
             per_page statements render against the whole batch (`batch_of_records`) rather than a single record — loop with `{{#each batch_of_records}}...{{record.fieldName}}...{{/each}}`, with the same quoting as `query` (double braces for strings, triple for numbers).
 
@@ -5490,9 +5497,10 @@ components:
               ### UPDATE Operation
               Prompt: "Update inventory counts"
               ```json
-              "queryType": ["per_record"],
-              "query": ["UPDATE inventory SET qty = {{{record.qty}}} WHERE sku = {{record.sku}}"]
+              "queryType": ["per_page"],
+              "query": ["{{#each batch_of_records}}UPDATE inventory SET qty = {{{record.qty}}} WHERE sku = {{record.sku}};{{/each}}"]
               ```
+              Use `"queryType": ["per_record"]` with `"query": ["UPDATE inventory SET qty = {{{record.qty}}} WHERE sku = {{record.sku}}"]` when the SQL can't be written as one batch statement.
 
               ### Run Once Per Page
               Prompt: "Execute this stored procedure for each page of results"
@@ -5510,7 +5518,7 @@ components:
           type: object
           description: |-
             Configuration for batch INSERTs via a multi-row VALUES clause; required when queryType is `["bulk_insert"]` and must not be set otherwise.
-            Only suited to pure INSERTs — for UPDATE, UPSERT, or ignore-existing/skip-duplicates logic, use queryType `["per_record"]` with the `query` field instead.
+            Only suited to pure INSERTs — for UPDATE or UPSERT, use queryType `["per_page"]` (a statement that loops `batch_of_records`) or `["per_record"]` with the `query` field instead, and for ignore-existing/skip-duplicates logic `["per_record"]`.
           x-celigo-ai-guidance:
             - |-
               **CRITICAL: This object is ONLY used when `queryType` is `["bulk_insert"]`.**
@@ -5520,7 +5528,7 @@ components:
               - Pure INSERT operation with NO ignoreExisting/duplicate checking
 
               ❌ **DO NOT SET THIS** when:
-              - `queryType` is `["per_record"]` (use `query` field instead)
+              - `queryType` is `["per_page"]` or `["per_record"]` (use the `query` field instead)
               - Operation involves UPDATE, UPSERT, or ignoreExisting logic
 
               If the prompt mentions "ignore existing", "skip duplicates", or "match on field",

package/dist/job.yml

@@ -1341,7 +1341,10 @@ components:
                 - retry
                 - bulk_retry
               x-enumDescriptions:
-                export: A child job for an export step within a flow run.
+                export: |-
+                  A child job for an export step within a flow run: the flow's source export, or a
+                  lookup step (an export with `isLookup`), whose job counts the pages it looked up in
+                  `numPagesProcessed`.
                 import: A child job for an import step within a flow run.
                 flow: A parent flow-run job that orchestrates the full pipeline.
                 retry: A retry of a single failed record from a previous job.
@@ -1571,8 +1574,9 @@ components:
               type: integer
               readOnly: true
               description: |-
-                Number of records skipped, by a filter or by an import's ignore-existing or ignore-missing
-                rule. Records an import's filter skips count in that import's child job; records an export's
+                Number of records skipped: by a filter, by an import's ignore-existing or ignore-missing
+                rule, by an import's preMap hook that returned no data for the record, or by a lookup step's
+                input filter (the record continues without the lookup's data). Records an import's filter skips count in that import's child job; records an export's
                 output filter drops count in the export's child job, whose `numSuccess` then counts only the
                 records that passed (an export that read 6 records and dropped 3 reads `numSuccess` 3,
                 `numIgnore` 3; live-verified 2026-10-22). Filtered records raise no error.
@@ -1599,7 +1603,10 @@ components:
             numPagesProcessed:
               type: integer
               readOnly: true
-              description: Number of pages processed by downstream imports.
+              description: |-
+                Number of pages processed by downstream steps: imports and lookup steps. A source export's
+                child job reads 0, a lookup step's and an import's count the pages they processed, and a
+                parent flow job sums its children.
               examples:
                 - 10
             oIndex:

package/dist/processor.yml

@@ -1177,6 +1177,14 @@ paths:
         (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&`);
         triple braces insert it unchanged. A `timestamp` with no time zone renders in UTC.
 
+        A null value, or a field under an object that is null, renders empty here. An HTTP import
+        escapes values its own way, at run time and in the import preview: in its JSON body a
+        double-brace value that is null, or under a null object, is written as the text `null`
+        (triple braces rendered `{{{record.customer.name}}}` empty, whether `customer` or its `name`
+        was null); in its relative URI a null field is sent as the text
+        `null`, and a field under a null object fails the record before anything is sent. Check a
+        nullable field with an import preview, not here.
+
         An unknown helper is refused with 422. `GET /v1/processors` lists helpers under the handlebars
         entry's `helperFunctions`, but that list is not complete: `eq` and `truncateWords`, for
         example, render although it omits them, so render a doubtful helper once here before relying

package/dist/tool.yml

@@ -13668,7 +13668,7 @@ components:
             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.
             A field the record lacks, or a `{{lookup.<name>}}` whose lookup found nothing, fails that record before anything is sent, with `handlebars_template_parse_error` (source `application`, classification `parse`): `Failed to generate request url from template: <URL>. Details: "<field>" not defined in the model.` That is missing data, not template syntax, and a retry of the same record fails the same way: send records that may lack the destination id through a composite UPDATE/CREATE import (`existingExtract`), or skip them with `ignoreMissing` and `ignoreExtract`.
-            A field that holds an empty string or null is defined: it renders empty, and the request is sent without the value.
+            A field that holds an empty string renders empty, and the request is sent without the value. A field that holds null renders the text `null` (a URI of `/orders/{{record.id}}` is sent as `/orders/null`), and a field under an object that is null fails the record like a missing one (`"<field>" not defined in null`).
           x-celigo-ai-guidance:
             - '**CRITICAL: This MUST be an array of strings, NOT an object.**'
             - |-
@@ -13855,7 +13855,14 @@ components:
               (``"{{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.
+              is sent. Double braces write a null value -- a null field, or any field under an
+              object that is null -- as the text ``null``, so ``"{{record.customer.name}}"`` sends
+              the string "null" (triple braces rendered ``{{{record.customer.name}}}`` empty,
+              whether ``customer`` or its ``name`` was null). Guard a nullable field with
+              ``{{#if record.customer.name}}{{record.customer.name}}{{/if}}`` or
+              ``{{#if record.customer}}{{record.customer.name}}{{/if}}``: both render empty for a
+              null field and for a null object. The Handlebars processor renders the unguarded null
+              empty, so judge it by an import preview or a run.
             - |-
               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
@@ -16996,7 +17003,7 @@ components:
               - bulk_load
           x-enumDescriptions:
             INSERT: Legacy value for insert operations; use bulk_insert or per_record instead.
-            UPDATE: Legacy value for update operations; use per_record instead.
+            UPDATE: Legacy value for update operations; use per_page or per_record instead.
             bulk_insert: Batch INSERT via multi-row VALUES clause for efficient bulk data loading.
             per_record: Execute one SQL statement per record, giving full control over individual record SQL.
             per_page: Execute one SQL statement per page (batch) of records.
@@ -17006,7 +17013,7 @@ components:
           description: |-
             Execution strategy for the SQL operation, which determines the required companion field: per_record, per_page, and first_page require `query`; bulk_insert requires `bulkInsert`; bulk_load requires `bulkLoad`.
             Prefer the highest-performance type the operation supports: bulk_load (Snowflake, Google BigQuery, Microsoft SQL Server on a cloud connection, Azure Synapse and Amazon Redshift — handles INSERT, upsert via `bulkLoad.primaryKeys`, and custom merge or ignore-existing logic via `bulkLoad.overrideMergeQuery`), then bulk_insert for pure INSERTs, then per_page, then per_record only when the logic cannot be expressed as a batch operation.
-            For UPDATE, UPSERT, or ignore-existing logic on databases without bulk_load support, use per_page or per_record with `query` — bulk_insert has no duplicate-checking logic.
+            For UPDATE, UPSERT, or ignore-existing logic on databases without bulk_load support, use per_page or per_record with `query` — bulk_insert has no duplicate-checking logic. Prefer per_page when the statement can loop `batch_of_records`, and use per_record when the SQL can't be written as one batch statement.
             Set a single value; do not combine types or use the legacy INSERT and UPDATE values.
             per_page statements render against the whole batch (`batch_of_records`) rather than a single record — loop with `{{#each batch_of_records}}...{{record.fieldName}}...{{/each}}`, with the same quoting as `query` (double braces for strings, triple for numbers).
 
@@ -17068,9 +17075,10 @@ components:
               ### UPDATE Operation
               Prompt: "Update inventory counts"
               ```json
-              "queryType": ["per_record"],
-              "query": ["UPDATE inventory SET qty = {{{record.qty}}} WHERE sku = {{record.sku}}"]
+              "queryType": ["per_page"],
+              "query": ["{{#each batch_of_records}}UPDATE inventory SET qty = {{{record.qty}}} WHERE sku = {{record.sku}};{{/each}}"]
               ```
+              Use `"queryType": ["per_record"]` with `"query": ["UPDATE inventory SET qty = {{{record.qty}}} WHERE sku = {{record.sku}}"]` when the SQL can't be written as one batch statement.
 
               ### Run Once Per Page
               Prompt: "Execute this stored procedure for each page of results"
@@ -17088,7 +17096,7 @@ components:
           type: object
           description: |-
             Configuration for batch INSERTs via a multi-row VALUES clause; required when queryType is `["bulk_insert"]` and must not be set otherwise.
-            Only suited to pure INSERTs — for UPDATE, UPSERT, or ignore-existing/skip-duplicates logic, use queryType `["per_record"]` with the `query` field instead.
+            Only suited to pure INSERTs — for UPDATE or UPSERT, use queryType `["per_page"]` (a statement that loops `batch_of_records`) or `["per_record"]` with the `query` field instead, and for ignore-existing/skip-duplicates logic `["per_record"]`.
           x-celigo-ai-guidance:
             - |-
               **CRITICAL: This object is ONLY used when `queryType` is `["bulk_insert"]`.**
@@ -17098,7 +17106,7 @@ components:
               - Pure INSERT operation with NO ignoreExisting/duplicate checking
 
               ❌ **DO NOT SET THIS** when:
-              - `queryType` is `["per_record"]` (use `query` field instead)
+              - `queryType` is `["per_page"]` or `["per_record"]` (use the `query` field instead)
               - Operation involves UPDATE, UPSERT, or ignoreExisting logic
 
               If the prompt mentions "ignore existing", "skip duplicates", or "match on field",
@@ -30621,31 +30629,37 @@ components:
           description: |-
             Selects which files are processed: files matching the filter criteria are exported,
             and non-matching files are skipped entirely before processing begins. Filterable
-            fields come from each file's metadata — most providers expose filename, filesize,
-            and lastmodified (e.g. ["endswith", ["string", ["extract", "filename"]], ".csv"]).
+            fields come from each file's listing entry: the name as `fileName`, the size as
+            `filesize`, and the modified time as `lastModifiedTime` on FTP, SFTP and S3 or
+            `modifiedTime` on cloud-storage folders (`http.type: "file"`)
+            (e.g. ["endswith", ["string", ["extract", "fileName"]], ".csv"]). There is no
+            `lastmodified` key.
           allOf:
             - $ref: '#/components/schemas/Filter'
           x-celigo-ai-guidance:
             - |-
               ## AVAILABLE FILTER FIELDS
 
-              The specific fields available for file filtering are the contained in the `fileMeta` property. 
+              The fields a file filter reads are on each file's listing entry, before the file is
+              downloaded. They are not the records' `fileMeta`, though some names match.
 
               ### Common Filter Fields
 
               These are the most commonly available fields across most file providers:
 
-              1. **filename**: The name of the file (with extension)
+              1. **fileName**: The name of the file (with extension)
                 - Example filter: Match files with specific extensions or naming patterns
-                - Usage: `["endswith", ["string", ["extract", "filename"]], ".csv"]`
+                - Usage: `["endswith", ["string", ["extract", "fileName"]], ".csv"]`
 
               2. **filesize**: The size of the file in bytes
                 - Example filter: Skip files that are too large or too small
                 - Usage: `["lessthan", ["number", ["extract", "filesize"]], 1000000]`
 
-              3. **lastmodified**: The last modification timestamp of the file
+              3. **lastModifiedTime** (FTP, SFTP, S3) or **modifiedTime** (cloud-storage folders): The
+                 last modification timestamp of the file. There is no `lastmodified` key.
                 - Example filter: Process only files created/modified within a specific date range
-                - Usage: `["greaterthan", ["epochtime", ["extract", "lastmodified"]], 1672531200000]` (2023-01-01T00:00:00Z in epoch milliseconds)
+                - Usage (FTP, SFTP, S3): `["greaterthan", ["epochtime", ["extract", "lastModifiedTime"]], 1672531200000]` (2023-01-01T00:00:00Z in epoch milliseconds)
+                - Usage (cloud-storage folders): `["greaterthan", ["epochtime", ["extract", "modifiedTime"]], 1672531200000]`
         backupPath:
           type: string
           description: Path where backup copies of source files are stored before processing.
@@ -31649,7 +31663,10 @@ components:
             - async_helper
         once:
           type: object
-          description: Callback configuration for once exports, used to mark records as exported in the source system after successful processing.
+          description: |-
+            Callback configuration for once exports, used to mark records as exported in the source system after successful processing.
+            Called only while the export's `type` is `once`: an export with no `type` keeps a saved `once` and never calls it, so every
+            run reads every record again (live-verified 2026-10-22).
           properties:
             relativeURI:
               type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.176",
+  "version": "0.2.178",
   "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": "06b10943",
+		"iasCommit": "d78b4324",
 		"generatedAt": "2026-10-22"
 	},
 	"roots": {