@celigo/api-specs 0.2.66 → 0.2.68

package/dist/api.yml

@@ -2708,6 +2708,15 @@ components:
       description: |-
         Conditional routing within a builder-mode API. Unlike flows, APIs only
         support `first_matching_branch` routing.
+
+        A router comes in two shapes, told apart by whether `routeRecordsTo` and
+        `routeRecordsUsing` are set: a **branching router** sets both and has two or
+        more branches, each taking the requests its `inputFilter` (or the router's
+        `script`) matches — the node you see in the API builder; a **pass-through
+        router** sets neither and has exactly one branch that every request goes
+        straight through — not drawn, it holds the steps before the first branching
+        router and merges branches back into shared steps (branches rejoin only by
+        pointing `nextRouterId` at the same router).
       properties:
         id:
           type: string
@@ -2727,10 +2736,15 @@ components:
             - first_matching_branch
           x-enumDescriptions:
             first_matching_branch: Routes the request to the first branch whose criteria match.
-          description: Routing strategy. APIs only support `first_matching_branch`.
-          default: first_matching_branch
+          description: |-
+            Routing strategy; APIs only support `first_matching_branch`. Set together with
+            `routeRecordsUsing` on a branching router; leave both unset on a one-branch
+            pass-through router.
           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`.
+            - 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 the 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
           enum:
@@ -2739,10 +2753,13 @@ components:
           x-enumDescriptions:
             input_filters: Evaluate routing criteria using declarative filter expressions.
             script: Evaluate routing criteria using a custom JavaScript function.
-          description: Method used to evaluate routing criteria.
-          default: input_filters
+          description: |-
+            How a branching router decides which branch a request matches. Set together with
+            `routeRecordsTo`; leave both unset on a one-branch pass-through router.
           examples:
             - input_filters
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsTo` together on every router that decides between branches, and leave both unset on a one-branch pass-through router; the rejections for a half-set pair or a multi-branch pass-through are listed on `routeRecordsTo`.
         script:
           type: object
           description: |

package/dist/export.yml

@@ -5954,9 +5954,25 @@ components:
         with their defaults when they are omitted.
       x-celigo-ai-guidance:
         - |-
-          Send `type: "stream"` together with this object, as the listener form always does; the
-          save also succeeds without `type`, so nothing catches the omission at save time. Sending
-          this object without `adaptorType` is enough for the server to infer `TopicExport`.
+          Send `type: "stream"` together with this object, as the listener form always does. The
+          save also succeeds without `type`, and the listener then runs as a batch export: its flow
+          never starts when a message is published, a manual run re-reads every retained message
+          without committing a position, and `GET /v1/topics/{_id}/exports/{_exportId}/offsets`
+          reports `hasCursor: false`. `PATCH` cannot add the type afterwards (`/type` is not a
+          whitelisted property): `PUT` the full document with `type: "stream"`, then disable and
+          enable the flow. Sending this object without `adaptorType` is enough for the server to
+          infer `TopicExport`.
+        - |-
+          The subscription is created when the listener's flow goes from disabled to enabled (a
+          `PATCH` or `PUT` that changes `disabled`); the first run after a publish follows within
+          about a minute. A flow created with `disabled: false` in one request has not subscribed,
+          and a save that leaves `disabled` unchanged (a rename) does not subscribe it — toggle the
+          flow. Under `startPosition: latest`, messages published before the subscription exists
+          are skipped. A disabled flow keeps its position and resumes from it when enabled again.
+        - |-
+          A topic listener cannot be a lookup: `isLookup: true` with `type: "stream"` fails the save
+          with 422 `not_supported` ("Lookup functionality is not available for Stream Export"), and a
+          lookup-shaped TopicExport saved without `type` never runs.
         - |-
           Never add a `_connectionId`: the server then validates the document as that connection's
           adaptor instead (an http connection fails with 422 missing_required_field "http subschema
@@ -16358,6 +16374,12 @@ components:
             response for the record, up to 5 MB, so `pageSize` does not limit or extend what a lookup
             returns. A lookup that must return more than that is better modeled as a standalone
             export step.
+          x-celigo-ai-guidance:
+            - |-
+              Not supported together with `type: "stream"`: a topic listener (`adaptorType:
+              TopicExport`) with `isLookup: true` fails the save with 422 `not_supported`
+              ("Lookup functionality is not available for Stream Export"). Enrich from a topic by
+              listening to it in its own flow.
           examples:
             - true
             - false

package/dist/flow.yml

@@ -4356,14 +4356,11 @@ components:
         name:
           type: string
           description: |
-            Unique name for this branch within the router.
-
-            Used for:
-            - Identification in logs and monitoring
-            - Reference in custom routing scripts
-            - Display in the UI
-
-            Should be descriptive of the branch's purpose or criteria.
+            Label for the branch, unique within the router. On a branching router it is shown on
+            the Flow Builder canvas, appears in logs, and is the value a routing script returns to
+            pick the branch — make it describe the branch's purpose. The single branch of a
+            pass-through router has no visible label; the server stores an empty string when the
+            name is omitted.
           examples:
             - enterprise_customers
             - high_priority
@@ -4385,7 +4382,7 @@ components:
           description: |
             Filter criteria that determines which records match this branch.
 
-            Only used when the router's routeRecordsUsing="inputFilter".
+            Only used when the router's `routeRecordsUsing` is `input_filters`.
             Records matching these criteria will be routed to this branch.
           properties:
             version:
@@ -4468,15 +4465,19 @@ components:
             the server when omitted; a client-supplied value is kept as-is.
           examples:
             - El8lWTezixy
-      required:
-        - name
     Router:
       type: object
       description: |
-        Configuration for conditional routing that directs records to different processing branches.
-
-        Routers evaluate each record against defined criteria and route them to appropriate branches
-        for specialized processing. This enables complex business logic and conditional workflows.
+        Directs records into branches. A router comes in two shapes, told apart by whether
+        `routeRecordsTo` and `routeRecordsUsing` are set: a **branching router** sets both and has two
+        or more branches, each taking the records its `inputFilter` (or the router's `script`)
+        matches — the router node you see in Flow Builder; a **pass-through router** sets neither and
+        has exactly one branch that every record goes straight through — not drawn in Flow Builder,
+        it is the joint that holds the steps before the first branching router and that merges
+        branches back into shared steps (branches rejoin only by pointing `nextRouterId` at the same
+        router). A flow with no branching needs no routers — its steps go in top-level
+        `pageProcessors` — unless it is abstract (`isAbstract`), where top-level `pageProcessors` are
+        rejected and the chain sits in one pass-through router.
       properties:
         id:
           type: string
@@ -4499,28 +4500,35 @@ components:
             - Order Status Router
         routeRecordsTo:
           type: string
-          description: Strategy for routing records to branches.
+          description: |-
+            How many branches a record may continue down. Set together with `routeRecordsUsing` on a
+            branching router; leave both unset on a one-branch pass-through router.
           enum:
             - first_matching_branch
             - all_matching_branches
           x-enumDescriptions:
             first_matching_branch: Routes each record to only the first branch whose criteria match.
             all_matching_branches: Routes each record to every branch whose criteria match, creating copies.
-          default: first_matching_branch
           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`.
+            - 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
-          description: Method used to evaluate routing criteria.
+          description: |-
+            How a branching router decides which branch a record matches. Set together with
+            `routeRecordsTo`; leave both unset on a one-branch pass-through router.
           enum:
             - input_filters
             - script
           x-enumDescriptions:
             input_filters: Evaluate routing criteria using declarative filter expressions.
             script: Evaluate routing criteria using a custom JavaScript function.
-          default: input_filters
           examples:
             - input_filters
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsTo` together on every router that decides between branches, and leave both unset on a one-branch pass-through router; the rejections for a half-set pair or a multi-branch pass-through are listed on `routeRecordsTo`.
         script:
           type: object
           description: |
@@ -5271,8 +5279,19 @@ components:
         routers:
           type: array
           description: |-
-            Routing configurations that direct records to conditional branches. Mutually exclusive with
-            top-level `pageProcessors` — use one or the other, not both.
+            Routers that direct records into branches. Mutually exclusive with top-level
+            `pageProcessors` — a flow with no branching uses `pageProcessors` and no routers at all,
+            except an abstract flow (`isAbstract`), which rejects top-level `pageProcessors` and so
+            holds even a linear chain in a pass-through router. A router comes in two shapes: a
+            **branching router** sets both `routeRecordsTo` and `routeRecordsUsing` and has two or
+            more branches (the router node you see in Flow Builder); a **pass-through router** sets
+            neither, has exactly one branch, and is not drawn — it is the invisible joint that holds
+            the steps before the first branching router (they cannot sit in top-level
+            `pageProcessors` once routers exist) and that merges branches back into shared steps.
+          x-celigo-ai-guidance:
+            - No branching on a non-abstract flow → leave `routers` out and put the steps in top-level `pageProcessors`. No branching on an abstract flow → one pass-through router holding the chain (top-level `pageProcessors` are rejected with 422 `abstract_flow_invalid_fields`).
+            - Steps before the first branching router go in a one-branch pass-through router at `routers[0]` with neither `routeRecordsTo` nor `routeRecordsUsing` set, chained to the branching router with `branches[0].nextRouterId`. Branches that rejoin point `nextRouterId` at one shared pass-through router.
+            - A one-branch router with BOTH routing fields set still runs, but Flow Builder draws it as a router node with a single branch and no rules — the pass-through shape (neither field) is the one that stays hidden.
           items:
             $ref: '#/components/schemas/Router'
         _exportId:
@@ -5385,8 +5404,9 @@ components:
             Marks this as an abstract (multi-instance) flow — a reusable template that cannot be
             executed directly. Instance flows reference it via `_abstractFlowId` and provide `overrides`.
 
-            Constraints: top-level `pageProcessors` are not allowed (use `routers`), cannot reference
-            another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
+            Constraints: top-level `pageProcessors` are not allowed (use `routers` — a linear chain
+            sits in one pass-through router with neither routing field set), cannot reference another
+            abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
           examples:
             - true
             - false

package/dist/import.yml

@@ -8352,6 +8352,16 @@ components:
           from it. Never add a `_connectionId`: the server then validates the document as that
           connection's adaptor instead (an http connection fails with 422 missing_required_field
           "http subschema not defined").
+        - |-
+          Without a mapping, each message is the record as the step received it. With
+          `oneToMany: true` and `pathToMany`, every element of that array is published as its own
+          message and the rest of the parent record rides inside each one under `_PARENT` (the parent
+          without the array); a mapping reshapes the message instead.
+        - |-
+          Publishing is not limited to flows. Verified surfaces: a flow step; an API step (the API
+          invoked at `POST /apis/{version}/{relativeURI}`); a Tool reached through a `ToolImport`
+          step in a flow; and `POST /v1/imports/{_id}/invoke` with `{"data": [record, ...]}`. A flow
+          or API test run (`/test/run`) publishes nothing — import steps are mocked there.
       properties:
         _topicId:
           type: string

package/dist/tool.yml

@@ -5785,6 +5785,15 @@ components:
         Unlike flows, tools only support "first_matching_branch" routing strategy.
         Branches can chain to other routers or use the special "outputRouter"
         terminal sink to exit the tool and return results.
+
+        A router comes in two shapes, told apart by whether `routeRecordsTo` and
+        `routeRecordsUsing` are set: a **branching router** sets both and has two or
+        more branches, each taking the inputs its `inputFilter` (or the router's
+        `script`) matches — the node you see in the Tool builder; a **pass-through
+        router** sets neither and has exactly one branch that every input goes
+        straight through — not drawn, it holds the steps before the first branching
+        router and merges branches back into shared steps (branches rejoin only by
+        pointing `nextRouterId` at the same router).
       x-celigo-ai-guidance:
         - |-
           Set `routeRecordsTo` and `routeRecordsUsing` together or omit both — a router with
@@ -5820,8 +5829,13 @@ components:
           description: |
             Routing strategy. Tools only support "first_matching_branch",
             which routes to the first branch whose criteria match the input.
+            Set together with `routeRecordsUsing` on a branching router; leave
+            both unset on a one-branch pass-through router.
           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`.
+            - 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 the 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
           enum:
@@ -5831,12 +5845,12 @@ components:
             input_filters: Evaluate routing criteria using declarative filter expressions.
             script: Evaluate routing criteria using a custom JavaScript function.
           description: |
-            Method used to evaluate routing criteria.
-
-            - **input_filters**: Use declarative filter expressions on each branch
-            - **script**: Use a custom JavaScript function to determine the branch
+            How a branching router decides which branch an input matches. Set together
+            with `routeRecordsTo`; leave both unset on a one-branch pass-through router.
           examples:
             - input_filters
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsTo` together on every router that decides between branches, and leave both unset on a one-branch pass-through router; the rejections for a half-set pair or a multi-branch pass-through are listed on `routeRecordsTo`.
         script:
           type: object
           description: |
@@ -18628,6 +18642,16 @@ components:
           from it. Never add a `_connectionId`: the server then validates the document as that
           connection's adaptor instead (an http connection fails with 422 missing_required_field
           "http subschema not defined").
+        - |-
+          Without a mapping, each message is the record as the step received it. With
+          `oneToMany: true` and `pathToMany`, every element of that array is published as its own
+          message and the rest of the parent record rides inside each one under `_PARENT` (the parent
+          without the array); a mapping reshapes the message instead.
+        - |-
+          Publishing is not limited to flows. Verified surfaces: a flow step; an API step (the API
+          invoked at `POST /apis/{version}/{relativeURI}`); a Tool reached through a `ToolImport`
+          step in a flow; and `POST /v1/imports/{_id}/invoke` with `{"data": [record, ...]}`. A flow
+          or API test run (`/test/run`) publishes nothing — import steps are mocked there.
       properties:
         _topicId:
           type: string
@@ -28985,9 +29009,25 @@ components:
         with their defaults when they are omitted.
       x-celigo-ai-guidance:
         - |-
-          Send `type: "stream"` together with this object, as the listener form always does; the
-          save also succeeds without `type`, so nothing catches the omission at save time. Sending
-          this object without `adaptorType` is enough for the server to infer `TopicExport`.
+          Send `type: "stream"` together with this object, as the listener form always does. The
+          save also succeeds without `type`, and the listener then runs as a batch export: its flow
+          never starts when a message is published, a manual run re-reads every retained message
+          without committing a position, and `GET /v1/topics/{_id}/exports/{_exportId}/offsets`
+          reports `hasCursor: false`. `PATCH` cannot add the type afterwards (`/type` is not a
+          whitelisted property): `PUT` the full document with `type: "stream"`, then disable and
+          enable the flow. Sending this object without `adaptorType` is enough for the server to
+          infer `TopicExport`.
+        - |-
+          The subscription is created when the listener's flow goes from disabled to enabled (a
+          `PATCH` or `PUT` that changes `disabled`); the first run after a publish follows within
+          about a minute. A flow created with `disabled: false` in one request has not subscribed,
+          and a save that leaves `disabled` unchanged (a rename) does not subscribe it — toggle the
+          flow. Under `startPosition: latest`, messages published before the subscription exists
+          are skipped. A disabled flow keeps its position and resumes from it when enabled again.
+        - |-
+          A topic listener cannot be a lookup: `isLookup: true` with `type: "stream"` fails the save
+          with 422 `not_supported` ("Lookup functionality is not available for Stream Export"), and a
+          lookup-shaped TopicExport saved without `type` never runs.
         - |-
           Never add a `_connectionId`: the server then validates the document as that connection's
           adaptor instead (an http connection fails with 422 missing_required_field "http subschema
@@ -36327,6 +36367,12 @@ components:
             response for the record, up to 5 MB, so `pageSize` does not limit or extend what a lookup
             returns. A lookup that must return more than that is better modeled as a standalone
             export step.
+          x-celigo-ai-guidance:
+            - |-
+              Not supported together with `type: "stream"`: a topic listener (`adaptorType:
+              TopicExport`) with `isLookup: true` fails the save with 422 `not_supported`
+              ("Lookup functionality is not available for Stream Export"). Enrich from a topic by
+              listening to it in its own flow.
           examples:
             - true
             - false

package/dist/topic.yml

@@ -1636,6 +1636,9 @@ components:
             from `offset`. False when the export has never consumed the topic, when its last committed
             position has expired from the stream, or when it does not listen to this topic at all — a
             listener without a cursor starts from its own `topic.startPosition` (`latest` or `earliest`).
+            A listener whose flow is disabled keeps its position; a listener saved without
+            `type: "stream"`, or whose flow has not been enabled since the listener was saved, has
+            never subscribed and reports false.
           examples:
             - true
             - false
@@ -1644,7 +1647,8 @@ components:
           minimum: -1
           description: |-
             Zero-based position of the next message the export will read. `-1` when `hasCursor` is
-            false.
+            false. The position counts from the start of the stream, so while no message has expired
+            the retained message count minus `offset` is the listener's backlog.
           examples:
             - 1287
             - -1

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "0b009b6",
-		"generatedAt": "2026-09-30"
+		"iasCommit": "d5f4380",
+		"generatedAt": "2026-10-01"
 	},
 	"roots": {
 		"aiagent": 133,