@celigo/api-specs 0.2.148 → 0.2.149

package/dist/export.yml

@@ -16405,8 +16405,11 @@ components:
                 filter, before the page is sent to downstream steps; commonly used to flatten
                 structures, drop unwanted records, or add computed fields. It receives the page as
                 `options.data` (with `errors`, `pageIndex`, `configuration` and `settings`) and returns
-                `{data, errors, abort, newErrorsAndRetryData}`. An exception thrown here fails every
-                record on that page, each with its own retry data, and later pages still run.
+                `{data, errors, abort, newErrorsAndRetryData}`. Return that object, not the array: a
+                hook that returns `options.data` itself, or a filtered copy, drops the page without an
+                error, and the run completes with 0 records, 0 errors and 0 pages. An exception thrown
+                here fails every record on that page, each with its own retry data, and later pages
+                still run.
               properties:
                 function:
                   type: string

package/dist/flow.yml

@@ -4226,7 +4226,10 @@ components:
           type: string
           description: |-
             Cron expression for this specific generator, overriding the flow's main schedule.
-            When omitted, the generator inherits the flow's schedule.
+            When omitted, the generator inherits the flow's schedule. It is read in the flow's
+            `timezone`, and a flow with no flow-level `schedule` still runs on it. PATCH reaches
+            the flow-level `/schedule` and `/timezone` but not this field, so changing it is a full
+            update of the flow.
           examples:
             - '? 5 0,6,12,18 ? * *'
             - '? 30 2 ? * *'
@@ -4236,6 +4239,10 @@ components:
               - Overrides the flow's main schedule for this generator
               - Allows different data sources to refresh at different intervals
               - Useful for sources with varying update frequencies
+            - |-
+              Check for one before rescheduling a flow: a flow-level `schedule` change succeeds
+              but leaves a generator that has its own `schedule` running at its old times. Change
+              the generator's `schedule` instead, with a PUT of the whole flow.
         skipRetries:
           type: boolean
           default: false
@@ -4650,7 +4657,16 @@ components:
             Filter criteria that determines which records match this branch.
 
             Only used when the router's `routeRecordsUsing` is `input_filters`.
-            Records matching these criteria will be routed to this branch.
+            Records matching these criteria will be routed to this branch. A branch
+            without an `inputFilter` matches every record, so under
+            `first_matching_branch` the catch-all branch goes last.
+
+            Send `version` and `rules` directly on `inputFilter` — not inside the
+            `{type: "expression", expression: {...}}` wrapper that export and import
+            filters use. A wrapped filter is saved without an error, but the branch is
+            stored with no `inputFilter` and takes every record.
+          x-celigo-ai-guidance:
+            - Read the flow back after saving a branching router and check that each filtered branch still has its `inputFilter`; a filter sent in the export-filter wrapper is dropped on save without an error.
           properties:
             version:
               type: string
@@ -4679,6 +4695,11 @@ components:
                 logical operators (`and`, `or`, `not`), field access (`extract`, `settings`)
                 and type conversions (`string`, `number`, `boolean`, `epochtime`).
 
+                Every `extract` must be wrapped in a type conversion. A bare
+                `["extract", "<field>"]` is refused when the flow is saved, with 422 "Field
+                operation extract must be called by a Type Conversion Operation but was called
+                by equals." (the message names the operator that held it).
+
                 Example — route records whose `isDeleted` field is the string "false":
                 ```json
                 ["equals", ["string", ["extract", "isDeleted"]], "false"]
@@ -4782,7 +4803,7 @@ components:
           examples:
             - first_matching_branch
           x-celigo-ai-guidance:
-            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config`.
+            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config` ("Either both the routeRecordsTo and routeRecordsUsing fields or none of them should be defined on the router.").
             - Leave both unset on a one-branch pass-through router (the steps before the first branching router, or a merge point). Setting them there still runs, but Flow Builder shows a router node with one branch and no rules. A router with neither field and more than one branch is rejected with 422 `invalid_flow_router_branch`.
         routeRecordsUsing:
           type: string
@@ -5432,7 +5453,9 @@ components:
         Writable flow fields shared by the request and response schemas.
 
         Use `pageProcessors` for simple linear flows or `routers` for conditional branching — never
-        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`.
+        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`
+        ("Either routers or pageProcessors should be present in the flow configuration and not both.").
+        Turning a linear flow into a branching one moves its top-level steps into the branches.
         The same import can be a step only once per flow: a second `pageProcessors` entry with its
         `_importId`, in the same array or another branch, fails with 422 `invalid_flow` ("… already
         included as a pageProcessor"). The `schedule` field uses Celigo's 6-field cron format (not
@@ -5491,7 +5514,15 @@ components:
               Build `schedule` as a Celigo 6-field cron:
               `? minute hour day-of-month month day-of-week`.
               The seconds field is always `?`; day-of-month is usually `?`, month `*`,
-              and day-of-week `*` (or specific days, 0=Sun..6=Sat).
+              and day-of-week `*` (or specific days, 0=Sun..6=Sat — weekdays are `1-5`,
+              `1,2,3,4,5` or `MON-FRI`; `2-6` is Tuesday to Saturday).
+            - |-
+              The hours are read in the flow's `timezone`. Keep a user's local times as
+              they are and set their IANA zone; never convert them to UTC, which is an hour
+              off for half the year in a zone with daylight saving and shifts them twice
+              when paired with the local `timezone`. Before changing when a flow runs, read
+              `pageGenerators[]`: a generator with its own `schedule` keeps it after a
+              flow-level change.
             - |-
               Disabling a flow does not bypass schedule validation: POST, PUT, and PATCH
               all reject free text or a sub-minute expression (`not a cron`, `* * * * * *`)
@@ -5526,7 +5557,10 @@ components:
           type:
             - string
             - 'null'
-          description: IANA timezone for the schedule (e.g. `America/New_York`). Defaults to UTC.
+          description: |-
+            IANA timezone for the schedule (e.g. `America/New_York`). Defaults to UTC. The flow's
+            `schedule` and each page generator's own `schedule` are read in this timezone; a page
+            generator has no timezone of its own.
           examples:
             - America/New_York
             - Europe/London

package/dist/import.yml

@@ -16408,7 +16408,11 @@ components:
                 - script
               description: |-
                 Hook that runs on each page of records before the import's mappings are applied.
-                Commonly used to reshape or filter records ahead of mapping.
+                Commonly used to reshape or filter records ahead of mapping. Its changes shape only
+                the request this import sends: the next step receives the record as it arrived here,
+                plus whatever this step's response mapping merges back. A value later steps need
+                belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
+                the flow, or in the later import's own `preMap`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -16430,7 +16434,8 @@ components:
               description: |-
                 Hook that runs after the import's mappings are applied but before records are sent
                 to the destination system. Commonly used for adjustments that need the mapped
-                (destination-shaped) record.
+                (destination-shaped) record. Like `preMap`, its changes shape only the request this
+                import sends; the next step never sees them.
               x-celigo-ai-guidance:
                 - |-
                   Post-map JavaScript hook — runs once per page AFTER the
@@ -16453,7 +16458,11 @@ components:
               description: |-
                 Hook that runs after the destination system responds, with access to both the
                 submitted records and the destination's responses. Commonly used to inspect results
-                or adjust the response data passed downstream.
+                or adjust the response data passed downstream. Each `options.responseData` entry is
+                one submitted record's result, in order: `statusCode`, `errors` (`{code, message,
+                source}`, empty on success), `ignored`, `id`, and `_json` — the destination's parsed
+                response body, where its own error detail sits (`_headers` holds the response
+                headers).
               x-celigo-ai-guidance:
                 - |-
                   Post-submit JavaScript hook — runs AFTER each batch of

package/dist/tool.yml

@@ -25289,7 +25289,11 @@ components:
                 - script
               description: |-
                 Hook that runs on each page of records before the import's mappings are applied.
-                Commonly used to reshape or filter records ahead of mapping.
+                Commonly used to reshape or filter records ahead of mapping. Its changes shape only
+                the request this import sends: the next step receives the record as it arrived here,
+                plus whatever this step's response mapping merges back. A value later steps need
+                belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
+                the flow, or in the later import's own `preMap`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -25311,7 +25315,8 @@ components:
               description: |-
                 Hook that runs after the import's mappings are applied but before records are sent
                 to the destination system. Commonly used for adjustments that need the mapped
-                (destination-shaped) record.
+                (destination-shaped) record. Like `preMap`, its changes shape only the request this
+                import sends; the next step never sees them.
               x-celigo-ai-guidance:
                 - |-
                   Post-map JavaScript hook — runs once per page AFTER the
@@ -25334,7 +25339,11 @@ components:
               description: |-
                 Hook that runs after the destination system responds, with access to both the
                 submitted records and the destination's responses. Commonly used to inspect results
-                or adjust the response data passed downstream.
+                or adjust the response data passed downstream. Each `options.responseData` entry is
+                one submitted record's result, in order: `statusCode`, `errors` (`{code, message,
+                source}`, empty on success), `ignored`, `id`, and `_json` — the destination's parsed
+                response body, where its own error detail sits (`_headers` holds the response
+                headers).
               x-celigo-ai-guidance:
                 - |-
                   Post-submit JavaScript hook — runs AFTER each batch of
@@ -37412,8 +37421,11 @@ components:
                 filter, before the page is sent to downstream steps; commonly used to flatten
                 structures, drop unwanted records, or add computed fields. It receives the page as
                 `options.data` (with `errors`, `pageIndex`, `configuration` and `settings`) and returns
-                `{data, errors, abort, newErrorsAndRetryData}`. An exception thrown here fails every
-                record on that page, each with its own retry data, and later pages still run.
+                `{data, errors, abort, newErrorsAndRetryData}`. Return that object, not the array: a
+                hook that returns `options.data` itself, or a filtered copy, drops the page without an
+                error, and the run completes with 0 records, 0 errors and 0 pages. An exception thrown
+                here fails every record on that page, each with its own retry data, and later pages
+                still run.
               properties:
                 function:
                   type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.148",
+  "version": "0.2.149",
   "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": "c5f16e90",
+		"iasCommit": "4808eca1",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {