@celigo/api-specs 0.2.66 → 0.2.67

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/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

@@ -18628,6 +18628,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 +28995,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 +36353,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.67",
   "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": "f9e33ad",
+		"generatedAt": "2026-10-01"
 	},
 	"roots": {
 		"aiagent": 133,