@uipath/maestro-builder-sdk 6.11.4 → 6.11.6

package/dist/core/byoa.js

@@ -0,0 +1,98 @@
+/**
+ * core/byoa — connector events that only fire on a BYOA connection (#848).
+ *
+ * BYOA is "bring your own app": an Integration Service connection created with
+ * the customer's own OAuth app. Some event objects need one — Slack
+ * `message-received-in-slack` is a webhook the customer's Slack app delivers,
+ * so on a standard connection the trigger deploys, validates, and never fires.
+ *
+ * Only a live call can tell a BYOA connection from a standard one, and `registry
+ * prepare` makes it: on an event whose facts say BYOA it lists the tenant's BYOA
+ * connections, refuses a connection that is not among them, and records one
+ * that is under `byoa[<event node type>][<connection id>]` in
+ * `connectors-local/resolutions.json`. This module is the offline half: the
+ * record's shape, and the one condition `check` reports and `compile` throws
+ * when a BYOA event's bound connection carries no record — typically because
+ * the connection was bound by preparing an ACTION of the same connector, which
+ * checks nothing about BYOA. `check` stays offline: it checks that the live
+ * check happened, never the tenant.
+ *
+ * No `node:fs` here — `check` and `serialize` import this module, and the file
+ * read lives in `lookup-store.ts` beside the ledger's other reader.
+ */
+import { GUID_RE } from './binding-messages.js';
+import { prepareCommand } from './cli-spelling.js';
+/** The diagnostic code, in `check` and on the error `serialize` throws. */
+export const EVENT_BYOA_UNVERIFIED = 'EVENT_BYOA_UNVERIFIED';
+/**
+ * The key an event's record is stored under: the WAIT form of the node type,
+ * the form `prepare` stores an event's overlay and lookup rows under, whichever
+ * role (`onEvent` or `waitForEvent`) the flow uses it in.
+ */
+export function byoaLedgerKey(connectorKey, event) {
+    return `uipath.connector.event.${connectorKey}.${event}`;
+}
+/** The record for `connectionId` under `nodeType`, matching the id case-insensitively. */
+export function byoaRecordFor(ledger, nodeType, connectionId) {
+    const perEvent = ledger?.[nodeType];
+    if (!perEvent || typeof perEvent !== 'object')
+        return undefined;
+    const wanted = connectionId.toLowerCase();
+    for (const [id, record] of Object.entries(perEvent)) {
+        if (id.toLowerCase() === wanted && record && typeof record === 'object' && record.byoa === true)
+            return record;
+    }
+    return undefined;
+}
+/** What `compile` throws for the refusal; `code` lets the CLI print it as `✗ [CODE]`. */
+export class ByoaRefusal extends Error {
+    code = EVENT_BYOA_UNVERIFIED;
+    constructor(message) {
+        super(message);
+        this.name = 'ByoaRefusal';
+    }
+}
+/** An all-zero GUID: a placeholder no tenant issues (compile's CONNECTION_STUB). */
+const STUB_GUID_RE = /^0{8}-0{4}-0{4}-0{4}-/;
+/**
+ * Why a BYOA-only event cannot be trusted to fire on its bound connection, or
+ * `undefined` when there is nothing to refuse. The ONE condition behind
+ * `check`'s EVENT_BYOA_UNVERIFIED error and `compile`'s refusal, so the two
+ * cannot disagree.
+ *
+ * Refuses when the event's facts say BYOA and the connection resolves to a real
+ * connection id with no `byoa` record for this event. Silent when:
+ *
+ * - the facts are unknown or say no BYOA;
+ * - the connection does not resolve to a real id — no bindings.json, a label it
+ *   does not declare, or a placeholder (`0000…`, `<…>`, the label itself). There
+ *   is no id to look a record up by, and nothing is lost: such a flow cannot
+ *   run its trigger on any connection, and BINDING_SELF_NAME /
+ *   BINDING_UNDECLARED / CONNECTION_STUB already say so.
+ *
+ * @param where - The call site, as the other event diagnostics name it (`trigger`, `waitForEvent "x"`).
+ * @param sub - The subscription.
+ * @param facts - The event's facts from the library, or `undefined` when unknown.
+ * @param ledger - The overlay ledger's `byoa` section.
+ * @param bindings - Resolves the `connection:` label to an id.
+ */
+export function byoaUnverified(where, sub, facts, ledger, bindings) {
+    if (!facts?.byoaConnection)
+        return undefined;
+    if (typeof sub.connection !== 'string' || sub.connection === '')
+        return undefined;
+    const label = sub.connection;
+    const id = bindings?.resolve(label) ?? label;
+    if (!GUID_RE.test(id) || STUB_GUID_RE.test(id))
+        return undefined;
+    if (byoaRecordFor(ledger, byoaLedgerKey(sub.connector, sub.event), id))
+        return undefined;
+    const named = label === id ? `connection ${id}` : `connection \`${label}\` (${id})`;
+    const object = sub.object ? ` --object ${sub.object}` : '';
+    return `${where}: \`${sub.connector}\` \`${sub.event}\` requires a BYOA (bring-your-own-app) connection — `
+        + `one created with your own OAuth app — and ${named} was never checked against that requirement. `
+        + `A standard connection deploys and the trigger never fires. Prepare the event on this connection, `
+        + `which refuses a standard connection and records a BYOA one:\n`
+        + `  ${prepareCommand(sub.connector, sub.event)}${object} --connection-id ${id}\n`
+        + `BYOA connections (rows for \`${sub.connector}\`): uip is connections list --byoa --all-folders`;
+}

package/dist/core/library.d.ts

@@ -1,4 +1,5 @@
 import { type LookupResolutions, type LookupSpec } from './lookups.js';
+import type { ByoaEventFacts, ByoaLedger } from './byoa.js';
 export interface ResolvedConnector {
     nodeType: string;
     version: string;
@@ -229,6 +230,12 @@ export declare class Library {
      * id from someone else's connection.
      */
     readonly lookupResolutions: LookupResolutions;
+    /**
+     * The BYOA checks `prepare` recorded (`resolutions.json` → `byoa`), from the
+     * overlay only, for the same reason as {@link lookupResolutions}: whether a
+     * connection is BYOA is a fact about one tenant.
+     */
+    readonly byoaVerifications: ByoaLedger;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     private readonly invariantCollections;
     constructor(dir: string, opts?: LibraryOpts);
@@ -348,6 +355,22 @@ export declare class Library {
      * raw library snapshot carries ZERO trigger/event entries).
      */
     eventParameterFields(key: string, event: string, objectName?: string): EventParameterFields | undefined;
+    /**
+     * Whether a connector event needs a BYOA (bring-your-own-app) connection, and
+     * whether its webhook URL must be registered by hand — or `undefined` when no
+     * layer carries the event in either form.
+     *
+     * Read from the `.v1def.json` sidecar, where the library build stamps the
+     * facts from the event's `triggers objects` row and `prepare` stores them on
+     * the overlay. A fact is TRUE when ANY layer, in either form (`.event.` or
+     * `.trigger.`), says so: the requirement belongs to the event object, not to
+     * a tenant, and an overlay written by an older `prepare` — which stored the
+     * `describe` answer, `false` for Slack `message-received-in-slack` — must not
+     * hide the true fact a newer baked library carries.
+     *
+     * `check` and `compile` read this through the one rule in `core/byoa.ts`.
+     */
+    eventFacts(key: string, event: string, objectName?: string): ByoaEventFacts | undefined;
     /**
      * The filterable-field names a connector event declares — the vocabulary a
      * `filters` leaf may name.

package/dist/core/library.js

@@ -11,7 +11,7 @@ import { join } from 'node:path';
 import { prepareCommand } from './cli-spelling.js';
 import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
 import { lookupSpecOf } from './lookups.js';
-import { loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
+import { loadByoaLedger, loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
 export class Library {
     layers = [];
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */
@@ -24,10 +24,17 @@ export class Library {
      * id from someone else's connection.
      */
     lookupResolutions;
+    /**
+     * The BYOA checks `prepare` recorded (`resolutions.json` → `byoa`), from the
+     * overlay only, for the same reason as {@link lookupResolutions}: whether a
+     * connection is BYOA is a fact about one tenant.
+     */
+    byoaVerifications;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     invariantCollections;
     constructor(dir, opts = {}) {
         this.lookupResolutions = loadLookupResolutions(opts.overlayDir);
+        this.byoaVerifications = loadByoaLedger(opts.overlayDir);
         this.invariantCollections = new Set([
             ...loadInvariantCollections(dir),
             ...loadInvariantCollections(opts.overlayDir),
@@ -434,6 +441,45 @@ export class Library {
                 .some(([name, value]) => name !== 'type' && Boolean(value)),
         };
     }
+    /**
+     * Whether a connector event needs a BYOA (bring-your-own-app) connection, and
+     * whether its webhook URL must be registered by hand — or `undefined` when no
+     * layer carries the event in either form.
+     *
+     * Read from the `.v1def.json` sidecar, where the library build stamps the
+     * facts from the event's `triggers objects` row and `prepare` stores them on
+     * the overlay. A fact is TRUE when ANY layer, in either form (`.event.` or
+     * `.trigger.`), says so: the requirement belongs to the event object, not to
+     * a tenant, and an overlay written by an older `prepare` — which stored the
+     * `describe` answer, `false` for Slack `message-received-in-slack` — must not
+     * hide the true fact a newer baked library carries.
+     *
+     * `check` and `compile` read this through the one rule in `core/byoa.ts`.
+     */
+    eventFacts(key, event, objectName) {
+        let found = false;
+        const facts = { byoaConnection: false, isWebhookUrlVisible: false };
+        for (const layer of this.layers) {
+            for (const kind of ['event', 'trigger']) {
+                let rc;
+                try {
+                    rc = this.resolveInLayer(layer, `uipath.connector.${kind}.${key}.${event}`, undefined, objectName);
+                }
+                catch {
+                    continue; // an ambiguous object is resolveEvent's refusal to report
+                }
+                if (!rc)
+                    continue;
+                found = true;
+                const v1def = (rc.v1def ?? {});
+                if (v1def.byoaConnection === true)
+                    facts.byoaConnection = true;
+                if (v1def.isWebhookUrlVisible === true)
+                    facts.isWebhookUrlVisible = true;
+            }
+        }
+        return found ? facts : undefined;
+    }
     /**
      * The filterable-field names a connector event declares — the vocabulary a
      * `filters` leaf may name.

package/dist/core/lookup-store.d.ts

@@ -1,3 +1,4 @@
+import type { ByoaLedger } from './byoa.js';
 import type { LookupResolutions } from './lookups.js';
 /**
  * Load `<overlayDir>/resolutions.json`, or an empty map.
@@ -8,6 +9,17 @@ import type { LookupResolutions } from './lookups.js';
  * behaviour an author wants from a missing resolution anyway.
  */
 export declare function loadLookupResolutions(overlayDir: string | undefined): LookupResolutions;
+/**
+ * Load the `byoa` section of `<overlayDir>/resolutions.json` — the BYOA checks
+ * `registry prepare` recorded (see `core/byoa.ts`) — or an empty map.
+ *
+ * Lenient like {@link loadLookupResolutions}: an absent or malformed file reads
+ * as EMPTY, and the consequence of empty is the EVENT_BYOA_UNVERIFIED error
+ * naming the `prepare` command that records the check. Read fresh on every
+ * call rather than cached: `prepare` rewrites this file, and a stale "never
+ * checked" answer would refuse a flow that was just verified.
+ */
+export declare function loadByoaLedger(overlayDir: string | undefined): ByoaLedger;
 /**
  * The invariant-collection ledger's `objectName` set, from a library dir.
  *

package/dist/core/lookup-store.js

@@ -45,6 +45,31 @@ export function loadLookupResolutions(overlayDir) {
     RESOLUTION_CACHE.set(overlayDir, rows);
     return rows;
 }
+/**
+ * Load the `byoa` section of `<overlayDir>/resolutions.json` — the BYOA checks
+ * `registry prepare` recorded (see `core/byoa.ts`) — or an empty map.
+ *
+ * Lenient like {@link loadLookupResolutions}: an absent or malformed file reads
+ * as EMPTY, and the consequence of empty is the EVENT_BYOA_UNVERIFIED error
+ * naming the `prepare` command that records the check. Read fresh on every
+ * call rather than cached: `prepare` rewrites this file, and a stale "never
+ * checked" answer would refuse a flow that was just verified.
+ */
+export function loadByoaLedger(overlayDir) {
+    if (!overlayDir)
+        return {};
+    const file = join(overlayDir, 'resolutions.json');
+    if (!existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const byoa = parsed?.byoa;
+        return byoa && typeof byoa === 'object' && !Array.isArray(byoa) ? byoa : {};
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * The invariant-collection ledger's `objectName` set, from a library dir.
  *

package/dist/core/queue-record.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The queue item's own Orchestrator record — the fields `core.action.queue.create`
+ * publishes, declared so a downstream read is checkable. Shared by the serializer
+ * (which declares it on the node) and `check` (which refuses a read outside it).
+ *
+ * Unlike an rpa process's output arguments, this shape is NOT per-tenant: it is
+ * Orchestrator's queue-item record, the same for every queue, so the author has
+ * nothing to declare and `returns` is not needed for a fire-and-forget enqueue.
+ * The dispatcher returns `env.Data` from `uip or queue-items add` verbatim, and
+ * these are the fields a real add answered with (pinned 2026-07-28 against
+ * `Shared/SupplierInvoices` on codereval; `gen-tests`' fixture for the node is the
+ * same list). Declaring the EVIDENCED fields and no more is PR 10's payload-schema
+ * pattern — an invented field would be #73's `firedAt` again.
+ */
+export declare const QUEUE_ITEM_RECORD_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly Id: {
+            readonly type: "number";
+        };
+        readonly Key: {
+            readonly type: "string";
+        };
+        readonly UniqueKey: {
+            readonly type: "string";
+        };
+        readonly Reference: {
+            readonly type: "string";
+        };
+        readonly Status: {
+            readonly type: "string";
+        };
+        readonly Priority: {
+            readonly type: "string";
+        };
+        readonly QueueDefinitionName: {
+            readonly type: "string";
+        };
+        readonly QueueDefinitionKey: {
+            readonly type: "string";
+        };
+        readonly CreationTime: {
+            readonly type: "string";
+        };
+        readonly StartProcessing: {
+            readonly type: "string";
+        };
+        readonly EndProcessing: {
+            readonly type: "string";
+        };
+        readonly Progress: {
+            readonly type: "string";
+        };
+        readonly ReviewStatus: {
+            readonly type: "string";
+        };
+        readonly DueDate: {
+            readonly type: "string";
+        };
+        readonly RiskSlaDate: {
+            readonly type: "string";
+        };
+        readonly DeferDate: {
+            readonly type: "string";
+        };
+        readonly Encrypted: {
+            readonly type: "boolean";
+        };
+        readonly SpecificContent: {
+            readonly type: "object";
+        };
+        readonly Output: {
+            readonly type: "object";
+        };
+        readonly OutputData: {
+            readonly type: "string";
+        };
+        readonly Analytics: {
+            readonly type: "object";
+        };
+        readonly AnalyticsData: {
+            readonly type: "string";
+        };
+        readonly ProcessingExceptionType: {
+            readonly type: "string";
+        };
+        readonly ProcessingExceptionReason: {
+            readonly type: "string";
+        };
+        readonly SecondsInPreviousAttempts: {
+            readonly type: "number";
+        };
+        readonly RetryNumber: {
+            readonly type: "number";
+        };
+        readonly CreatorJobKey: {
+            readonly type: "string";
+        };
+        readonly ExecutorJobKey: {
+            readonly type: "string";
+        };
+        readonly RobotKey: {
+            readonly type: "string";
+        };
+    };
+};

package/dist/core/queue-record.js

@@ -0,0 +1,48 @@
+/**
+ * The queue item's own Orchestrator record — the fields `core.action.queue.create`
+ * publishes, declared so a downstream read is checkable. Shared by the serializer
+ * (which declares it on the node) and `check` (which refuses a read outside it).
+ *
+ * Unlike an rpa process's output arguments, this shape is NOT per-tenant: it is
+ * Orchestrator's queue-item record, the same for every queue, so the author has
+ * nothing to declare and `returns` is not needed for a fire-and-forget enqueue.
+ * The dispatcher returns `env.Data` from `uip or queue-items add` verbatim, and
+ * these are the fields a real add answered with (pinned 2026-07-28 against
+ * `Shared/SupplierInvoices` on codereval; `gen-tests`' fixture for the node is the
+ * same list). Declaring the EVIDENCED fields and no more is PR 10's payload-schema
+ * pattern — an invented field would be #73's `firedAt` again.
+ */
+export const QUEUE_ITEM_RECORD_SCHEMA = {
+    type: 'object',
+    properties: {
+        Id: { type: 'number' },
+        Key: { type: 'string' },
+        UniqueKey: { type: 'string' },
+        Reference: { type: 'string' },
+        Status: { type: 'string' },
+        Priority: { type: 'string' },
+        QueueDefinitionName: { type: 'string' },
+        QueueDefinitionKey: { type: 'string' },
+        CreationTime: { type: 'string' },
+        StartProcessing: { type: 'string' },
+        EndProcessing: { type: 'string' },
+        Progress: { type: 'string' },
+        ReviewStatus: { type: 'string' },
+        DueDate: { type: 'string' },
+        RiskSlaDate: { type: 'string' },
+        DeferDate: { type: 'string' },
+        Encrypted: { type: 'boolean' },
+        SpecificContent: { type: 'object' },
+        Output: { type: 'object' },
+        OutputData: { type: 'string' },
+        Analytics: { type: 'object' },
+        AnalyticsData: { type: 'string' },
+        ProcessingExceptionType: { type: 'string' },
+        ProcessingExceptionReason: { type: 'string' },
+        SecondsInPreviousAttempts: { type: 'number' },
+        RetryNumber: { type: 'number' },
+        CreatorJobKey: { type: 'string' },
+        ExecutorJobKey: { type: 'string' },
+        RobotKey: { type: 'string' },
+    },
+};

package/dist/flow-sdk.d.ts

@@ -974,7 +974,7 @@ declare class StepList {
      * **Paginate until the API says stop**
      * ```ts
      * .var('page', types.number, 1)
-     * .doWhile('paginate', js`$vars.fetch.output.hasNextPage === true`, (b) => b
+     * .doWhile('paginate', js`$vars.fetch.output.body.hasNextPage === true`, (b) => b
      *   .step('fetch', http({ url: tmpl`https://api.example.test/items?page=${v('page')}`, method: 'GET', managed: false, returns: { hasNextPage: 'boolean' } }), {
      *     updates: { page: js`$vars.page + 1` },
      *   }), { limit: 50 })

package/dist/flow-sdk.js

@@ -709,7 +709,7 @@ class StepList {
      * **Paginate until the API says stop**
      * ```ts
      * .var('page', types.number, 1)
-     * .doWhile('paginate', js`$vars.fetch.output.hasNextPage === true`, (b) => b
+     * .doWhile('paginate', js`$vars.fetch.output.body.hasNextPage === true`, (b) => b
      *   .step('fetch', http({ url: tmpl`https://api.example.test/items?page=${v('page')}`, method: 'GET', managed: false, returns: { hasNextPage: 'boolean' } }), {
      *     updates: { page: js`$vars.page + 1` },
      *   }), { limit: 50 })

package/dist/registry/generators/descriptors.d.ts

@@ -40,7 +40,7 @@ export declare function emitLookupsBlock(specs: ReadonlyMap<string, LookupSpecDa
  * parameters (HTTP Webhook) or one nothing has described yet, and an empty
  * interface would refuse every key in both cases.
  */
-export declare function emitEvent(entry: LibraryEntry, inFields: readonly LibraryField[], inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
+export declare function emitEvent(entry: LibraryEntry, inFields: readonly LibraryField[], inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>, v1def?: V1Definition): string[];
 /** One operation: its `Inputs`/`Outputs` interfaces, doc comment and `descriptor()` const. */
 export declare function emitOp(entry: LibraryEntry, v1def: V1Definition, inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
 /**

package/dist/registry/generators/descriptors.js

@@ -18,6 +18,7 @@
  * event's per-object variants are skipped because they share their template's
  * node type and so would emit the same const twice.
  */
+import { prepareCommand } from "../../core/cli-spelling.js";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
@@ -165,7 +166,7 @@ function versionOf(entry) {
  * parameters (HTTP Webhook) or one nothing has described yet, and an empty
  * interface would refuse every key in both cases.
  */
-export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set()) {
+export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set(), v1def = {}) {
     const nodeType = entry.nodeType;
     const eventId = afterLast(nodeType, ".");
     const connectorKey = pyTruthy(entry.connector?.key) ? entry.connector.key : "";
@@ -196,6 +197,23 @@ export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTyp
         lines.push(` * Start a flow on it with \`onEvent(${name}, { where: { … } })\`, or pause for it`);
         lines.push(` * with \`waitForEvent(${name}, { … })\`; \`where\` carries its event parameters.`);
     }
+    // The facts the library build stamped from the event's `triggers objects`
+    // row. An author holding only the descriptor must learn the requirement here:
+    // on a standard connection the trigger deploys and never fires.
+    if (v1def.byoaConnection === true) {
+        lines.push(" *");
+        lines.push(" * Requires a BYOA (bring-your-own-app) connection — on a standard one the");
+        lines.push(" * trigger deploys and never fires. Bind it with");
+        // Spelled for whoever ran the generator, like every `check` remedy.
+        lines.push(` * \`${prepareCommand(pyStr(connectorKey), eventId, "--connection-id", "<id>")}\`,`);
+        lines.push(" * which refuses a standard connection and records the check `compile` requires;");
+        lines.push(" * `uip is connections list --byoa --all-folders` lists the BYOA connections.");
+    }
+    if (v1def.isWebhookUrlVisible === true) {
+        lines.push(" *");
+        lines.push(" * After deploying, register the trigger's webhook URL in the connector app's");
+        lines.push(" * event-subscription settings; `registry prepare` prints the instructions.");
+    }
     // INSIDE the block: `emitLookupComment` returns bare ` * ` body lines.
     if (specs.size > 0) {
         lines.push(" *");
@@ -222,7 +240,7 @@ export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, ou
     const runtime = entry.runtime ?? {};
     const inFields = descriptorInputFields(entry, v1def);
     if (isEventNodeType(nodeType)) {
-        return emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant);
+        return emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant, v1def);
     }
     const lines = [];
     lines.push(...emitInterface(`${name}Inputs`, false, inputTypes, inputTree, true));

package/dist/registry/generators/markdown/page.js

@@ -1,12 +1,13 @@
 /**
  * One library entry rendered to Markdown: header → schema-dynamic notice →
- * choosing the object → resolving the field set → required inputs → optional
+ * connection requirements (events) → choosing the object → resolving the field set → required inputs → optional
  * inputs → resolving lookups → example → filtering → outputs. Ported from
  * `render_op`; the page is `"\n".join(lines)` with no trailing newline.
  */
 import { afterLast, pyStr } from "../../compat/pystr.js";
 import { dictOf, getStr, pyOr, pyTruthy } from "./pyvalue.js";
 import { choosingObjectLines } from "./sections/choosing-object.js";
+import { eventFactsLines } from "./sections/event-facts.js";
 import { exampleLines } from "./sections/example.js";
 import { eventFilterLines } from "./sections/filtering.js";
 import { headerLines } from "./sections/header.js";
@@ -28,6 +29,7 @@ export function renderOp(j, v1def, symbol, invariant) {
     const out = [];
     out.push(...headerLines(j, nodeType));
     out.push(...schemaDynamicLines(j, nodeType));
+    out.push(...eventFactsLines(j, v1def));
     const fields = assembleFields(j, v1def);
     const required = fields.filter((f) => pyTruthy(f.required));
     const optional = fields.filter((f) => !pyTruthy(f.required));

package/dist/registry/generators/markdown/sections/event-facts.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function eventFactsLines(j: Dict, v1def: Dict | undefined): string[];

package/dist/registry/generators/markdown/sections/event-facts.js

@@ -0,0 +1,45 @@
+/**
+ * `## Connection requirements`: the event facts an author has to act on before
+ * the trigger can fire — a BYOA (bring-your-own-app) connection, and a webhook
+ * URL registered by hand. Emitted only when a fact is TRUE, so every other
+ * event page is unchanged. The facts are the sidecar's, which the library build
+ * stamps from the event's `triggers objects` row (#848).
+ */
+import { prepareCommand } from "../../../../core/cli-spelling.js";
+import { isEventNodeType } from "../../../model/library.js";
+import { dictOf, getStr } from "../pyvalue.js";
+export function eventFactsLines(j, v1def) {
+    const nodeType = getStr(j, "nodeType", "");
+    if (!isEventNodeType(nodeType))
+        return [];
+    const facts = dictOf(v1def);
+    const byoa = facts.byoaConnection === true;
+    const webhook = facts.isWebhookUrlVisible === true;
+    if (!byoa && !webhook)
+        return [];
+    const key = getStr(dictOf(j.connector), "key", "<connector>");
+    const event = nodeType.slice(nodeType.lastIndexOf(".") + 1);
+    const out = ["## Connection requirements", ""];
+    if (byoa) {
+        out.push("**Requires a BYOA connection.** This event fires only on a BYOA " +
+            "(bring-your-own-app) connection — one created with your own OAuth app. " +
+            "On a standard connection the trigger deploys and never fires. Prepare " +
+            "the event on the connection you bind: it refuses a standard connection " +
+            "and records a BYOA one, and `check` and `compile` refuse this event on a " +
+            "connection that was never checked (`EVENT_BYOA_UNVERIFIED`).");
+        out.push("");
+        out.push("```bash");
+        out.push(prepareCommand(key, event, "--connection-id", "<id>"));
+        out.push("uip is connections list --byoa --all-folders   # the BYOA connections");
+        out.push("```");
+        out.push("");
+    }
+    if (webhook) {
+        out.push("**Register the webhook URL.** The connector's app delivers these events " +
+            "to a URL Integration Service issues. After deploying, copy the trigger's " +
+            "webhook URL into the app's event-subscription settings; `registry prepare` " +
+            "prints the connector's own instructions.");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/library-build/events.d.ts

@@ -48,15 +48,43 @@ export declare function normalizeBucketFields(parameters: unknown): Dict[];
  * survives the merge.
  */
 export declare function unionEventParameters(declared: unknown, objectParameters: unknown): Dict[];
-/** `merge_describe_into_node`: fold a `triggers describe` answer into a registry trigger definition (a copy). */
-export declare function mergeDescribeIntoNode(node: Dict, describe: Dict, objectParameters?: unknown): Dict;
+/** The three event facts: the API's (PascalCase) spelling and the stored (camelCase) one. */
+declare const EVENT_FACTS: ReadonlyArray<readonly [string, "eventMode" | "byoaConnection" | "isWebhookUrlVisible"]>;
+/** The facts one source states, under their stored names; a fact the source does not state is absent. */
+export type StatedEventFacts = Partial<Record<(typeof EVENT_FACTS)[number][1], unknown>>;
+/**
+ * THE precedence rule for the three event facts, used by every place that
+ * decides one: the `triggers objects` ROW wins, then `fallback`, and a fact
+ * neither states stays absent.
+ *
+ * `fallback` is whichever definition the caller holds — a `triggers describe`
+ * answer (PascalCase, generate time) or a registry node (camelCase, prepare
+ * time); both spellings are read. The row is the only one of the three sources
+ * that tells the truth about BYOA: Slack `message-received-in-slack` answers
+ * `ByoaConnection: true` in its objects row and `false` in both `describe` and
+ * the registry node. Generate time used to read `describe` alone while
+ * `prepare` read the row, so the library baked `false` for a BYOA-only event
+ * and nothing downstream could refuse a standard connection on it (#848).
+ * One function, so the two sides cannot drift again.
+ */
+export declare function resolveEventFacts(objectRow: unknown, fallback: unknown): StatedEventFacts;
+/**
+ * `merge_describe_into_node`: fold a `triggers describe` answer into a registry
+ * trigger definition (a copy). The facts follow {@link resolveEventFacts}, so
+ * pass the event's `triggers objects` row when there is one: `prepare` stores
+ * this definition as the overlay, and `check` reads BYOA off the overlay.
+ */
+export declare function mergeDescribeIntoNode(node: Dict, describe: Dict, objectParameters?: unknown, objectRow?: unknown): Dict;
 export interface EventFacts {
     eventMode: string;
     byoaConnection: boolean;
     isWebhookUrlVisible: boolean;
     textBlocks: string[];
 }
-/** `event_facts`: the three facts that change how a subscription is prepared or tested; the object row wins. */
+/**
+ * `event_facts`: the three facts that change how a subscription is prepared or
+ * tested, by {@link resolveEventFacts} (the object row wins), with defaults.
+ */
 export declare function eventFacts(node: Dict, objectRow: unknown): EventFacts;
 /**
  * `triggers_objects_cached`: cached `uip is triggers objects <key> <OPERATION>`,
@@ -106,3 +134,4 @@ export declare function expandGenericEvents(ctx: BuildContext, templates: Librar
  * input with curated events described in place.
  */
 export declare function resolveConnectorEvents(ctx: BuildContext, entries: LibraryEntry[]): Promise<[LibraryEntry[], LibraryEntry[]]>;
+export {};