@celigo/api-specs 0.2.177 → 0.2.179

package/dist/export.yml

@@ -8025,11 +8025,13 @@ components:
           It defines how data is extracted from Salesforce,
           either through queries or real-time events.
         - |-
-          Always set `type` on new Salesforce exports (`soql` or `distributed`) —
-          the form always writes it. It is absent only from legacy real-time
-          exports created before the field existed, and file/byId retrievals
-          (`id` + `sObjectType`, no `soql` object) carry `type: soql` without a
-          `soql` object.
+          Set `type` on every Salesforce export you create (`soql` or `distributed`).
+          Never read its absence on an existing export as a defect: a listener saved
+          from the integrator.io form carries no `salesforce.type` and the platform
+          fires it without the field, and file/byId retrievals (`id` + `sObjectType`,
+          no `soql` object) carry `type: soql` without a `soql` object. A listener
+          that never creates a job is diagnosed from `distributed` (below), not from
+          this field.
         - |-
           ## SALESFORCE EXPORT MODES
 
@@ -8061,8 +8063,10 @@ components:
             Required fields: type, soql.query
             Optional fields: api, includeDeletedRecords, bulk (when api="bulk")
 
-          - For Distributed exports (type="distributed"):
-            Required fields: type, distributed configuration
+          - For Distributed exports (real-time listeners):
+            Set type="distributed" with the distributed object and sObjectType when creating one.
+            A listener saved from the integrator.io form carries the distributed object and
+            sObjectType with no type, and the platform fires it — a valid listener, not a missing field.
             Optional fields: distributed.referencedFields, distributed.qualifier
 
           - For Blob exports (when export.type="blob"):
@@ -8078,7 +8082,10 @@ components:
 
               This field determines the core operating mode of the Salesforce export:
 
-              - REQUIRED for all Salesforce exports
+              - Set it on every Salesforce export you create; a listener saved from the
+                integrator.io form carries none and the platform fires it without the
+                field, so an absent `type` beside a `distributed` object is the normal
+                shape of a form-saved listener, not a missing setting
               - Controls which additional configuration objects must be provided
               - Affects how the export appears and functions in the flow builder UI
               - Cannot be changed after creation without significant reconfiguration
@@ -8573,7 +8580,7 @@ components:
                 - SELECT Id, Name, (SELECT Id, FirstName, LastName FROM Contacts) FROM Account
         distributed:
           type: object
-          description: Real-time listener configuration; required when `type` is `distributed` and not used otherwise. Records reach the flow only when an Apex trigger on `sObjectType` in the connected org calls the Celigo package (`integrator_da__.RealTimeExporter.processExport()`) — no scheduling or manual execution is involved. Integration Apps create their triggers at installation; for a custom flow the customer deploys the trigger in Salesforce, starting from the code the export page shows under Required trigger.
+          description: 'Real-time listener configuration — the object that makes an export a listener. Set it, with `type: distributed`, when creating one; a listener saved from the integrator.io form carries it with no `type`, and the platform fires it either way. Not used on SOQL or file exports. Records reach the flow only when an Apex trigger on `sObjectType` in the connected org calls the Celigo package (`integrator_da__.RealTimeExporter.processExport()`) — no scheduling or manual execution is involved. Integration Apps create their triggers at installation; for a custom flow the customer deploys the trigger in Salesforce, starting from the code the export page shows under Required trigger.'
           x-celigo-ai-guidance:
             - |-
               After creating a listener on a custom flow, relay what the Help Center's "Listen for real-time data
@@ -8588,6 +8595,12 @@ components:
               Help Center's trigger requirement in the connected org: an active Apex trigger on the object whose
               code calls `integrator_da__.RealTimeExporter`, and the Celigo package reachable through the
               connection (`GET /v1/connections/{_id}/distributed`, documented in this spec set).
+            - |-
+              Two things are never why a listener does not fire. The export preview cannot run a listener:
+              it validates the body as a SOQL export and answers 422 `missing_required_field` for
+              `soql.query` (and for `type` when the listener carries none) before the connection is used,
+              so a failed preview is expected, not a configuration defect. And an absent `salesforce.type`
+              is the normal shape of a listener saved from the integrator.io form (see `type`).
           properties:
             referencedFields:
               type:

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

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
@@ -33039,11 +33046,13 @@ components:
           It defines how data is extracted from Salesforce,
           either through queries or real-time events.
         - |-
-          Always set `type` on new Salesforce exports (`soql` or `distributed`) —
-          the form always writes it. It is absent only from legacy real-time
-          exports created before the field existed, and file/byId retrievals
-          (`id` + `sObjectType`, no `soql` object) carry `type: soql` without a
-          `soql` object.
+          Set `type` on every Salesforce export you create (`soql` or `distributed`).
+          Never read its absence on an existing export as a defect: a listener saved
+          from the integrator.io form carries no `salesforce.type` and the platform
+          fires it without the field, and file/byId retrievals (`id` + `sObjectType`,
+          no `soql` object) carry `type: soql` without a `soql` object. A listener
+          that never creates a job is diagnosed from `distributed` (below), not from
+          this field.
         - |-
           ## SALESFORCE EXPORT MODES
 
@@ -33075,8 +33084,10 @@ components:
             Required fields: type, soql.query
             Optional fields: api, includeDeletedRecords, bulk (when api="bulk")
 
-          - For Distributed exports (type="distributed"):
-            Required fields: type, distributed configuration
+          - For Distributed exports (real-time listeners):
+            Set type="distributed" with the distributed object and sObjectType when creating one.
+            A listener saved from the integrator.io form carries the distributed object and
+            sObjectType with no type, and the platform fires it — a valid listener, not a missing field.
             Optional fields: distributed.referencedFields, distributed.qualifier
 
           - For Blob exports (when export.type="blob"):
@@ -33092,7 +33103,10 @@ components:
 
               This field determines the core operating mode of the Salesforce export:
 
-              - REQUIRED for all Salesforce exports
+              - Set it on every Salesforce export you create; a listener saved from the
+                integrator.io form carries none and the platform fires it without the
+                field, so an absent `type` beside a `distributed` object is the normal
+                shape of a form-saved listener, not a missing setting
               - Controls which additional configuration objects must be provided
               - Affects how the export appears and functions in the flow builder UI
               - Cannot be changed after creation without significant reconfiguration
@@ -33587,7 +33601,7 @@ components:
                 - SELECT Id, Name, (SELECT Id, FirstName, LastName FROM Contacts) FROM Account
         distributed:
           type: object
-          description: Real-time listener configuration; required when `type` is `distributed` and not used otherwise. Records reach the flow only when an Apex trigger on `sObjectType` in the connected org calls the Celigo package (`integrator_da__.RealTimeExporter.processExport()`) — no scheduling or manual execution is involved. Integration Apps create their triggers at installation; for a custom flow the customer deploys the trigger in Salesforce, starting from the code the export page shows under Required trigger.
+          description: 'Real-time listener configuration — the object that makes an export a listener. Set it, with `type: distributed`, when creating one; a listener saved from the integrator.io form carries it with no `type`, and the platform fires it either way. Not used on SOQL or file exports. Records reach the flow only when an Apex trigger on `sObjectType` in the connected org calls the Celigo package (`integrator_da__.RealTimeExporter.processExport()`) — no scheduling or manual execution is involved. Integration Apps create their triggers at installation; for a custom flow the customer deploys the trigger in Salesforce, starting from the code the export page shows under Required trigger.'
           x-celigo-ai-guidance:
             - |-
               After creating a listener on a custom flow, relay what the Help Center's "Listen for real-time data
@@ -33602,6 +33616,12 @@ components:
               Help Center's trigger requirement in the connected org: an active Apex trigger on the object whose
               code calls `integrator_da__.RealTimeExporter`, and the Celigo package reachable through the
               connection (`GET /v1/connections/{_id}/distributed`, documented in this spec set).
+            - |-
+              Two things are never why a listener does not fire. The export preview cannot run a listener:
+              it validates the body as a SOQL export and answers 422 `missing_required_field` for
+              `soql.query` (and for `type` when the listener carries none) before the connection is used,
+              so a failed preview is expected, not a configuration defect. And an absent `salesforce.type`
+              is the normal shape of a listener saved from the integrator.io form (see `type`).
           properties:
             referencedFields:
               type:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.177",
+  "version": "0.2.179",
   "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": "35c59e78",
+		"iasCommit": "9951106d",
 		"generatedAt": "2026-10-22"
 	},
 	"roots": {