@celigo/api-specs 0.2.65 → 0.2.67

package/dist/api.yml

@@ -6307,6 +6307,23 @@ components:
             Controls the UI form layout for configuring this connection. Determines which
             fields are shown and how they are organized in the Celigo UI.
             For programmatic creation, http is the most common choice.
+          x-celigo-ai-guidance:
+            - |-
+              The value selects a form, not a protocol: a plain `http` connection sends GraphQL requests
+              identically. What `graph_ql` adds is the GraphQL editing experience — the connection form
+              authors the ping as Query / Operation name / Variables fields compiled into `http.ping.body`,
+              and every export and import on the connection gets a Form view toggle between the GraphQL
+              editor (Query / Operation name / Variables) and the raw HTTP form.
+            - |-
+              A `graph_ql` connection's `baseURI` should be the GraphQL endpoint itself
+              (`https://host/graphql`, `https://<store>.myshopify.com/admin/api/<version>/graphql.json`):
+              the GraphQL export and import forms have no relative URI field.
+            - |-
+              The connection form offers no control to change this value on a connection without an HTTP
+              connector, and connections cannot be cloned through the API. A user who wants the GraphQL
+              editor for steps that live on an `http` connection needs a new `graph_ql` connection (same
+              base URI and auth, credentials re-entered) with the steps re-pointed to it — this is the
+              setup to recommend, not a product gap.
           x-lowercase: true
           examples:
             - http
@@ -7188,6 +7205,12 @@ components:
             API within the linked HTTP connector that this connection targets, for connectors that
             publish more than one API. Only meaningful together with `_httpConnectorId`; an id that is
             not one of that connector's APIs is dropped on save, not rejected.
+          x-celigo-ai-guidance:
+            - |-
+              The connector catalog flags GraphQL APIs with `isGraphQL`. The API bound here is inherited
+              by every export and import created on the connection — the step form's API type control
+              is disabled once a connection is selected — so a connector's GraphQL editor requires a
+              connection bound to its GraphQL API, not a per-step setting.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4d
         _httpConnectorVersionId:

package/dist/connection.yml

@@ -4632,6 +4632,23 @@ components:
             Controls the UI form layout for configuring this connection. Determines which
             fields are shown and how they are organized in the Celigo UI.
             For programmatic creation, http is the most common choice.
+          x-celigo-ai-guidance:
+            - |-
+              The value selects a form, not a protocol: a plain `http` connection sends GraphQL requests
+              identically. What `graph_ql` adds is the GraphQL editing experience — the connection form
+              authors the ping as Query / Operation name / Variables fields compiled into `http.ping.body`,
+              and every export and import on the connection gets a Form view toggle between the GraphQL
+              editor (Query / Operation name / Variables) and the raw HTTP form.
+            - |-
+              A `graph_ql` connection's `baseURI` should be the GraphQL endpoint itself
+              (`https://host/graphql`, `https://<store>.myshopify.com/admin/api/<version>/graphql.json`):
+              the GraphQL export and import forms have no relative URI field.
+            - |-
+              The connection form offers no control to change this value on a connection without an HTTP
+              connector, and connections cannot be cloned through the API. A user who wants the GraphQL
+              editor for steps that live on an `http` connection needs a new `graph_ql` connection (same
+              base URI and auth, credentials re-entered) with the steps re-pointed to it — this is the
+              setup to recommend, not a product gap.
           x-lowercase: true
           examples:
             - http
@@ -5513,6 +5530,12 @@ components:
             API within the linked HTTP connector that this connection targets, for connectors that
             publish more than one API. Only meaningful together with `_httpConnectorId`; an id that is
             not one of that connector's APIs is dropped on save, not rejected.
+          x-celigo-ai-guidance:
+            - |-
+              The connector catalog flags GraphQL APIs with `isGraphQL`. The API bound here is inherited
+              by every export and import created on the connection — the step form's API type control
+              is disabled once a connection is selected — so a connector's GraphQL editor requires a
+              connection bound to its GraphQL API, not a per-step setting.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4d
         _httpConnectorVersionId:

package/dist/enduser.yml

@@ -3645,6 +3645,23 @@ components:
             Controls the UI form layout for configuring this connection. Determines which
             fields are shown and how they are organized in the Celigo UI.
             For programmatic creation, http is the most common choice.
+          x-celigo-ai-guidance:
+            - |-
+              The value selects a form, not a protocol: a plain `http` connection sends GraphQL requests
+              identically. What `graph_ql` adds is the GraphQL editing experience — the connection form
+              authors the ping as Query / Operation name / Variables fields compiled into `http.ping.body`,
+              and every export and import on the connection gets a Form view toggle between the GraphQL
+              editor (Query / Operation name / Variables) and the raw HTTP form.
+            - |-
+              A `graph_ql` connection's `baseURI` should be the GraphQL endpoint itself
+              (`https://host/graphql`, `https://<store>.myshopify.com/admin/api/<version>/graphql.json`):
+              the GraphQL export and import forms have no relative URI field.
+            - |-
+              The connection form offers no control to change this value on a connection without an HTTP
+              connector, and connections cannot be cloned through the API. A user who wants the GraphQL
+              editor for steps that live on an `http` connection needs a new `graph_ql` connection (same
+              base URI and auth, credentials re-entered) with the steps re-pointed to it — this is the
+              setup to recommend, not a product gap.
           x-lowercase: true
           examples:
             - http
@@ -4526,6 +4543,12 @@ components:
             API within the linked HTTP connector that this connection targets, for connectors that
             publish more than one API. Only meaningful together with `_httpConnectorId`; an id that is
             not one of that connector's APIs is dropped on save, not rejected.
+          x-celigo-ai-guidance:
+            - |-
+              The connector catalog flags GraphQL APIs with `isGraphQL`. The API bound here is inherited
+              by every export and import created on the connection — the step form's API type control
+              is disabled once a connection is selected — so a connector's GraphQL editor requires a
+              connection bound to its GraphQL API, not a per-step setting.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4d
         _httpConnectorVersionId:

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
@@ -6156,6 +6172,24 @@ components:
             Authoring mode of the HTTP request form. Controls which editor the UI presents
             (standard HTTP, legacy REST, GraphQL, or connector-assistant driven) and how the
             request fields are interpreted. When omitted, the standard HTTP form is used.
+          x-celigo-ai-guidance:
+            - |-
+              The value changes only the editor, never the request: the same `http.body` is sent
+              identically under `http` and `graph_ql`, and the value can be changed on an existing
+              export without touching the body.
+            - |-
+              The GraphQL form reads `http.body` as the JSON envelope `{"query", "operationName",
+              "variables"}` and shows each member in its own editor, recompiling the envelope on save
+              (`http.paging.body` likewise from its paging fields). A body that is not parseable JSON at
+              rest — Handlebars block helpers outside a string value — renders every field EMPTY in that
+              form, so keep templated variables inside a JSON string value:
+              `"variables": "{\"after\": {{#if export.http.paging.token}}\"{{export.http.paging.token}}\"{{else}}null{{/if}}}"`.
+            - |-
+              The GraphQL form has no relative URI field: the connection `baseURI` is expected to be the
+              GraphQL endpoint (a saved `relativeURI` still applies but is not shown). Create GraphQL
+              exports on a `graph_ql` connection — that is the setup where the form offers the Form view
+              toggle between the GraphQL editor and the raw HTTP form; a `graph_ql` export on an `http`
+              connection works but cannot be switched back in the UI.
           examples:
             - http
             - graph_ql
@@ -6344,6 +6378,11 @@ components:
             - |-
               The body content must match the format specified in the requestMediaType field (JSON,
               XML, etc.).
+            - |-
+              A GraphQL request is this field holding the stringified JSON envelope `{"query":
+              "<document>", "operationName": "...", "variables": ...}` whatever `formType` says;
+              `variables` may be an object or a JSON-encoded string, and a templated variables value
+              must stay inside a string so the body remains parseable JSON at rest (see `formType`).
             - |-
               You can use handlebars expressions to create dynamic content:
               ```
@@ -16335,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

@@ -1636,6 +1636,18 @@ components:
             - |-
               Use `assistant_graphql` as the default value if there is a connector available
               for the system and the connector supports GraphQL.
+            - |-
+              The value selects the editor only. Each `http.body[]` entry stays a template STRING — a
+              stringified `{"query", "operationName", "variables"}` envelope, one per operation for the
+              update/create pair (`http.body[0]` / `http.body[1]`); never an object entry, which is stored
+              as-is and does not render. The GraphQL form parses that string to show each member in its
+              own field and re-stringifies it on save; an entry that is not parseable JSON at rest renders
+              those fields empty, so keep templated variables inside a JSON string value.
+            - |-
+              Create GraphQL imports on a `graph_ql` connection (or a connector connection bound to its
+              GraphQL API): that setup offers the Form view toggle between the GraphQL editor and the
+              raw HTTP form, and the GraphQL form has no relative URI field — the connection `baseURI`
+              is expected to be the GraphQL endpoint.
           examples:
             - assistant
             - http
@@ -8340,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/mcp-server.yml

@@ -5455,6 +5455,23 @@ components:
             Controls the UI form layout for configuring this connection. Determines which
             fields are shown and how they are organized in the Celigo UI.
             For programmatic creation, http is the most common choice.
+          x-celigo-ai-guidance:
+            - |-
+              The value selects a form, not a protocol: a plain `http` connection sends GraphQL requests
+              identically. What `graph_ql` adds is the GraphQL editing experience — the connection form
+              authors the ping as Query / Operation name / Variables fields compiled into `http.ping.body`,
+              and every export and import on the connection gets a Form view toggle between the GraphQL
+              editor (Query / Operation name / Variables) and the raw HTTP form.
+            - |-
+              A `graph_ql` connection's `baseURI` should be the GraphQL endpoint itself
+              (`https://host/graphql`, `https://<store>.myshopify.com/admin/api/<version>/graphql.json`):
+              the GraphQL export and import forms have no relative URI field.
+            - |-
+              The connection form offers no control to change this value on a connection without an HTTP
+              connector, and connections cannot be cloned through the API. A user who wants the GraphQL
+              editor for steps that live on an `http` connection needs a new `graph_ql` connection (same
+              base URI and auth, credentials re-entered) with the steps re-pointed to it — this is the
+              setup to recommend, not a product gap.
           x-lowercase: true
           examples:
             - http
@@ -6336,6 +6353,12 @@ components:
             API within the linked HTTP connector that this connection targets, for connectors that
             publish more than one API. Only meaningful together with `_httpConnectorId`; an id that is
             not one of that connector's APIs is dropped on save, not rejected.
+          x-celigo-ai-guidance:
+            - |-
+              The connector catalog flags GraphQL APIs with `isGraphQL`. The API bound here is inherited
+              by every export and import created on the connection — the step form's API type control
+              is disabled once a connection is selected — so a connector's GraphQL editor requires a
+              connection bound to its GraphQL API, not a per-step setting.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4d
         _httpConnectorVersionId:

package/dist/tool.yml

@@ -8056,6 +8056,23 @@ components:
             Controls the UI form layout for configuring this connection. Determines which
             fields are shown and how they are organized in the Celigo UI.
             For programmatic creation, http is the most common choice.
+          x-celigo-ai-guidance:
+            - |-
+              The value selects a form, not a protocol: a plain `http` connection sends GraphQL requests
+              identically. What `graph_ql` adds is the GraphQL editing experience — the connection form
+              authors the ping as Query / Operation name / Variables fields compiled into `http.ping.body`,
+              and every export and import on the connection gets a Form view toggle between the GraphQL
+              editor (Query / Operation name / Variables) and the raw HTTP form.
+            - |-
+              A `graph_ql` connection's `baseURI` should be the GraphQL endpoint itself
+              (`https://host/graphql`, `https://<store>.myshopify.com/admin/api/<version>/graphql.json`):
+              the GraphQL export and import forms have no relative URI field.
+            - |-
+              The connection form offers no control to change this value on a connection without an HTTP
+              connector, and connections cannot be cloned through the API. A user who wants the GraphQL
+              editor for steps that live on an `http` connection needs a new `graph_ql` connection (same
+              base URI and auth, credentials re-entered) with the steps re-pointed to it — this is the
+              setup to recommend, not a product gap.
           x-lowercase: true
           examples:
             - http
@@ -8937,6 +8954,12 @@ components:
             API within the linked HTTP connector that this connection targets, for connectors that
             publish more than one API. Only meaningful together with `_httpConnectorId`; an id that is
             not one of that connector's APIs is dropped on save, not rejected.
+          x-celigo-ai-guidance:
+            - |-
+              The connector catalog flags GraphQL APIs with `isGraphQL`. The API bound here is inherited
+              by every export and import created on the connection — the step form's API type control
+              is disabled once a connection is selected — so a connector's GraphQL editor requires a
+              connection bound to its GraphQL API, not a per-step setting.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4d
         _httpConnectorVersionId:
@@ -12158,6 +12181,18 @@ components:
             - |-
               Use `assistant_graphql` as the default value if there is a connector available
               for the system and the connector supports GraphQL.
+            - |-
+              The value selects the editor only. Each `http.body[]` entry stays a template STRING — a
+              stringified `{"query", "operationName", "variables"}` envelope, one per operation for the
+              update/create pair (`http.body[0]` / `http.body[1]`); never an object entry, which is stored
+              as-is and does not render. The GraphQL form parses that string to show each member in its
+              own field and re-stringifies it on save; an entry that is not parseable JSON at rest renders
+              those fields empty, so keep templated variables inside a JSON string value.
+            - |-
+              Create GraphQL imports on a `graph_ql` connection (or a connector connection bound to its
+              GraphQL API): that setup offers the Form view toggle between the GraphQL editor and the
+              raw HTTP form, and the GraphQL form has no relative URI field — the connection `baseURI`
+              is expected to be the GraphQL endpoint.
           examples:
             - assistant
             - http
@@ -18593,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
@@ -28950,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
@@ -29152,6 +29213,24 @@ components:
             Authoring mode of the HTTP request form. Controls which editor the UI presents
             (standard HTTP, legacy REST, GraphQL, or connector-assistant driven) and how the
             request fields are interpreted. When omitted, the standard HTTP form is used.
+          x-celigo-ai-guidance:
+            - |-
+              The value changes only the editor, never the request: the same `http.body` is sent
+              identically under `http` and `graph_ql`, and the value can be changed on an existing
+              export without touching the body.
+            - |-
+              The GraphQL form reads `http.body` as the JSON envelope `{"query", "operationName",
+              "variables"}` and shows each member in its own editor, recompiling the envelope on save
+              (`http.paging.body` likewise from its paging fields). A body that is not parseable JSON at
+              rest — Handlebars block helpers outside a string value — renders every field EMPTY in that
+              form, so keep templated variables inside a JSON string value:
+              `"variables": "{\"after\": {{#if export.http.paging.token}}\"{{export.http.paging.token}}\"{{else}}null{{/if}}}"`.
+            - |-
+              The GraphQL form has no relative URI field: the connection `baseURI` is expected to be the
+              GraphQL endpoint (a saved `relativeURI` still applies but is not shown). Create GraphQL
+              exports on a `graph_ql` connection — that is the setup where the form offers the Form view
+              toggle between the GraphQL editor and the raw HTTP form; a `graph_ql` export on an `http`
+              connection works but cannot be switched back in the UI.
           examples:
             - http
             - graph_ql
@@ -29340,6 +29419,11 @@ components:
             - |-
               The body content must match the format specified in the requestMediaType field (JSON,
               XML, etc.).
+            - |-
+              A GraphQL request is this field holding the stringified JSON envelope `{"query":
+              "<document>", "operationName": "...", "variables": ...}` whatever `formType` says;
+              `variables` may be an object or a JSON-encoded string, and a templated variables value
+              must stay inside a string so the body remains parseable JSON at rest (see `formType`).
             - |-
               You can use handlebars expressions to create dynamic content:
               ```
@@ -36269,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.65",
+  "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": "d4b9f7a",
-		"generatedAt": "2026-09-30"
+		"iasCommit": "f9e33ad",
+		"generatedAt": "2026-10-01"
 	},
 	"roots": {
 		"aiagent": 133,