@uipath/maestro-builder-sdk 6.11.5 → 6.12.0

package/dist/bpmn/typed-node.js

@@ -19,12 +19,16 @@ export function registryTypeNames() {
  * `FLOW_SDK_BPMN_REGISTRY_FALLBACK=0` to keep resolution snapshot-only.
  *
  * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
+ * @param inline - A spec supplied by the author, which is used as is.
  * @returns Its emission spec.
  * @throws If the type is in neither the snapshot nor the registry — which means a
  * typo, or no `uip` to ask.
  */
-export function registryType(type) {
-    const spec = REGISTRY.types[type] ?? resolveFromRegistry(type);
+export function registryType(type, inline) {
+    // An inline spec wins over both the snapshot and the tenant — it is the author
+    // saying "emit THIS", for a type the snapshot lacks and no `uip` can describe, or
+    // for one the snapshot describes wrongly. See `ActivityNodeOpts.spec`.
+    const spec = inline ?? REGISTRY.types[type] ?? resolveFromRegistry(type);
     if (!spec) {
         throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types `
             + `(uip ${REGISTRY.provenance.uipVersion}) and the registry could not be asked for this one either — `
@@ -82,7 +86,22 @@ export const REGISTRY_GAPS = {
     // which `uip maestro bpmn validate` has always accepted. So the guard was right
     // that they are undeclared and wrong that they are invalid — recorded here rather
     // than by loosening the guard, which is what catches an author's typo.
-    'Intsvc.ActivityExecution': { extraContext: ['activity', 'resourceKey'] },
+    // `requiredContext` — context fields the PLATFORM requires and the registry
+    // snapshot does not mark required (or, here, does not declare at all).
+    //
+    // `Intsvc.ActivityExecution` must carry `activity`; without it `uip maestro bpmn
+    // validate` reports
+    //
+    //     [canvas] [ERROR] EMPTY_REQUIRED_FIELD: The field 'activity' in node 'op' is
+    //                      required but has no value.
+    //
+    // and `check` could not know, because it derives required fields from the snapshot.
+    // The connector emitter has always written `activity`, so this only bites a
+    // hand-rolled `.activity()` — but it bit it at the LAST rung. The divergence is
+    // measured rather than assumed: `bpmn-registry-required-drift.test.ts` diffs the
+    // required-field set the canvas validator carries against the snapshot's, over every
+    // type both know, and asserts the only difference is what this table records.
+    'Intsvc.ActivityExecution': { extraContext: ['activity', 'resourceKey'], requiredContext: ['activity'] },
     // `outputRowsFixed` — the type permits EXACTLY the output row its spec declares.
     // A mapped second row is refused:
     //
@@ -115,8 +134,8 @@ function identifierize(name) {
         .join('');
 }
 /** The variable a typed node's output row writes, or `undefined` when it has none. */
-export function typedNodeOutputVar(id, type, outputVar) {
-    const spec = registryType(type);
+export function typedNodeOutputVar(id, type, outputVar, inline) {
+    const spec = registryType(type, inline);
     if (!spec.output)
         return undefined;
     return outputVar ?? `${id}_${identifierize(spec.output.name)}`;
@@ -182,7 +201,13 @@ function contextRows(m, type, spec, supplied, verbatim = false) {
     // it and the author never learns why their setting did nothing — so it is
     // refused. The exception is a type with a recorded `extraContext` gap, where the
     // platform is known to accept fields the registry omits.
-    const known = new Set([...spec.context.map((f) => f.name), ...(REGISTRY_GAPS[type]?.extraContext ?? [])]);
+    const known = new Set([
+        ...spec.context.map((f) => f.name),
+        ...(REGISTRY_GAPS[type]?.extraContext ?? []),
+        // A field the platform REQUIRES is necessarily one it permits, so recording it as
+        // required is enough — an `extraContext` twin is not also needed.
+        ...(REGISTRY_GAPS[type]?.requiredContext ?? []),
+    ]);
     const unknown = Object.keys(supplied).filter((k) => !known.has(k));
     if (unknown.length) {
         throw new Error(`context field(s) ${unknown.map((u) => `"${u}"`).join(', ')} are not declared by this extension type. ` +
@@ -234,10 +259,16 @@ function inputRows(m, spec, inputs) {
         // platform does not read, and one no validator complains about.
         //
         // So: the declared field decides when there is one, the key when there is not.
+        //
+        // The same split decides the TYPE of an undeclared field. Every undeclared value
+        // used to be written as a `json` body, so a scalar came out JSON-quoted —
+        // `recordId` as `"1111-…"`, quotes included, where every real export writes
+        // `type="string" value="1111-…"`. A structured value is still a json body; a
+        // scalar is written as the `value` attribute, the way a declared scalar is.
         const declared = new Map(spec.inputs.map((f) => [f.name, f]));
         return keys.map((k) => {
             const field = declared.get(k);
-            return payloadInput(m, k, field?.target ?? k, inputs[k], field?.type ?? 'json');
+            return payloadInput(m, k, field?.target ?? k, inputs[k], field?.type ?? inferredInputType(inputs[k]));
         });
     }
     if (!spec.inputName)
@@ -277,6 +308,23 @@ function payloadInput(m, name, target, value, type) {
         props.target = target;
     return m.create('uipath:Input', props);
 }
+/** `json` for an object or array, `string` for anything else — see `inputRows`. */
+function inferredInputType(value) {
+    return value !== null && typeof value === 'object' ? 'json' : 'string';
+}
+/** `uipath:input` payload rows exactly as the caller spelled them, deriving nothing. */
+export function verbatimInputRows(m, rows) {
+    return rows.map((row) => {
+        const props = { name: row.name, type: row.type ?? 'string' };
+        if (row.target !== undefined)
+            props.target = row.target;
+        if (row.value !== undefined)
+            props.value = row.value;
+        if (row.body !== undefined)
+            props.body = jsonBody(row.body);
+        return m.create('uipath:Input', props);
+    });
+}
 /** The `uipath:output` row, when the type declares one. */
 function outputRow(m, spec, varName) {
     if (!spec.output)
@@ -308,7 +356,7 @@ export function createTypedNode(m, id, type, input,
  * Optional so a caller with no variable context still gets today's behaviour.
  */
 varType) {
-    const spec = registryType(type);
+    const spec = registryType(type, input.spec);
     if (!spec.element || !spec.tag) {
         throw new Error(`extension type "${type}" has no element/tag in the registry snapshot; it cannot be authored.`);
     }
@@ -352,7 +400,10 @@ varType) {
         }
         payload.context = m.create('uipath:Context', context);
     }
-    const ins = inputRows(m, spec, input.inputs ?? {});
+    // Spelled out by the caller: emit exactly these rows, deriving nothing — see
+    // TypedNodeInput.inputRows. This is what lets a connector's per-parameter rows
+    // (`name="start" type="string" value="0" target="query"`) survive a round trip.
+    const ins = input.inputRows ? verbatimInputRows(m, input.inputRows) : inputRows(m, spec, input.inputs ?? {});
     if (ins.length)
         payload.input = ins;
     const rows = [];
@@ -365,7 +416,7 @@ varType) {
             payload.output = rows;
         return finish(m, spec, id, input.name, payload);
     }
-    const outVar = typedNodeOutputVar(id, type, input.outputVar);
+    const outVar = typedNodeOutputVar(id, type, input.outputVar, spec);
     const out = outVar ? outputRow(m, spec, outVar) : undefined;
     if (out)
         rows.push(out);
@@ -476,8 +527,8 @@ function moddleElementOf(element) {
  * @param type - The extension type.
  * @returns Its fields that must be bound, with the target each binding needs.
  */
-export function bindingRequiredFields(type) {
-    return registryType(type).context.filter((f) => f.bindingInfo !== null && f.required);
+export function bindingRequiredFields(type, inline) {
+    return registryType(type, inline).context.filter((f) => f.bindingInfo !== null && f.required);
 }
 /**
  * Required context fields the author left unset and the registry cannot default.
@@ -490,10 +541,21 @@ export function bindingRequiredFields(type) {
  * @param context - The context values the author supplied.
  * @returns The names of required fields with no value and no default.
  */
-export function missingRequiredContext(type, context = {}) {
-    return registryType(type)
-        .context.filter((f) => f.required && context[f.name] === undefined && (f.default ?? '') === '')
+export function missingRequiredContext(type, context = {}, inline) {
+    // The platform's test is `isNilOrEmpty(field.value)`, so a field present and BLANK is
+    // as missing as one absent — and blank is the likelier authoring slip of the two, a
+    // value that came from an expression or a variable that had nothing in it. Checking
+    // only for `undefined` let every one of those through to the last rung.
+    const unset = (name) => {
+        const v = context[name];
+        return v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    };
+    const declared = registryType(type, inline)
+        .context.filter((f) => f.required && unset(f.name) && (f.default ?? '') === '')
         .map((f) => f.name);
+    // Fields the platform requires that the snapshot does not — see `REGISTRY_GAPS`.
+    const gaps = (REGISTRY_GAPS[type]?.requiredContext ?? []).filter((name) => !declared.includes(name) && unset(name));
+    return [...declared, ...gaps];
 }
 /**
  * Required PAYLOAD fields the author left unset.
@@ -519,9 +581,9 @@ export function missingRequiredInputs(type, inputs = {},
  * genuinely does not spell (it writes `connection`). Reading both makes this
  * agree with the CLI instead of guessing on either side of it.
  */
-context = {}) {
+context = {}, inline) {
     const notEnforced = new Set(REGISTRY_GAPS[type]?.notEnforcedInputs ?? []);
-    return registryType(type)
+    return registryType(type, inline)
         .inputs.filter((f) => f.required &&
         !notEnforced.has(f.name) &&
         inputs[f.name] === undefined &&
@@ -560,8 +622,8 @@ context = {}) {
  * @param type - The extension type.
  * @returns The required payload field names that cannot be expressed, or `[]`.
  */
-export function unsatisfiableRequiredInputs(type) {
-    const spec = registryType(type);
+export function unsatisfiableRequiredInputs(type, inline) {
+    const spec = registryType(type, inline);
     if (spec.inputPattern !== 'mergedBody' && spec.inputPattern !== 'splitInputsItemData')
         return [];
     return spec.inputs.filter((f) => f.required).map((f) => f.name);

package/dist/check-cli.js

@@ -9,7 +9,7 @@ import { reportDiagnostics } from './cli-result.js';
 import { existsSync } from 'node:fs';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { check } from './check.js';
-import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
+import { byoaCheckOpts, eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { connectorInputErrors } from './serialize.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
@@ -41,6 +41,7 @@ function checkOpts(argv) {
         return bindings ? { bindings } : {};
     return {
         eventResolveError: eventResolveErrorFor(library),
+        ...byoaCheckOpts(library),
         eventParams: (connector, event, object) => {
             try {
                 return library.eventParameterFields(connector, event, object);

package/dist/check.d.ts

@@ -2,6 +2,7 @@ import { type LookupResolutions, type LookupSpec } from './core/lookups.js';
 import type { SchemaReadiness } from './core/library.js';
 import type { BuiltFlow } from './flow-sdk.js';
 import { type BindingsView } from './core/binding-messages.js';
+import { type ByoaEventFacts, type ByoaLedger } from './core/byoa.js';
 export interface Diagnostic {
     level: 'error' | 'warning';
     code: string;
@@ -116,6 +117,18 @@ export interface CheckOpts {
     lookups?: (connector: string, action: string, version?: string, object?: string) => Readonly<Record<string, LookupSpec>> | undefined;
     /** Everything `registry prepare --resolve` has recorded in the local overlay. */
     resolutions?: LookupResolutions;
+    /**
+     * A connector event's BYOA and webhook-URL facts, or `undefined` when unknown.
+     * Supplied by the CLIs from `library.eventFacts` — the call `serialize` makes
+     * for the same refusal — so check and compile cannot disagree; omitted (no
+     * library) → EVENT_BYOA_UNVERIFIED is not checked.
+     */
+    eventFacts?: (connector: string, event: string, object?: string) => ByoaEventFacts | undefined;
+    /**
+     * The BYOA checks `registry prepare` recorded — the `byoa` section of the
+     * overlay's `resolutions.json`, as `library.byoaVerifications` loads it.
+     */
+    byoa?: ByoaLedger;
     /**
      * Whether a connector step's schema is materialized locally — the fact behind
      * the OBJECT_UNPREPARED and CUSTOM_FIELDS_UNPREPARED warnings. Supplied by the

package/dist/check.js

@@ -18,6 +18,7 @@ import { childStepLists, declaredExits, hasExits, stopsAtEnd } from './core/step
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
+import { EVENT_BYOA_UNVERIFIED, byoaUnverified } from './core/byoa.js';
 export function check(built, opts = {}) {
     return checkFlow(built, [], opts);
 }
@@ -1953,6 +1954,13 @@ function eventParamsFor(subscription, opts) {
  *   the fallback case for a connector the shipped library was not generated
  *   against. A warning, because compile still succeeds. Prints the one
  *   command that makes the event checkable.
+ * - `EVENT_BYOA_UNVERIFIED` — an ERROR: the event only fires on a BYOA
+ *   (bring-your-own-app) connection, and the bound connection id has no record
+ *   of `prepare` having checked it (`core/byoa.ts` has the rule and when it
+ *   stays silent). A standard connection deploys and the trigger never fires;
+ *   the usual way in is binding the connection by preparing one of the
+ *   connector's ACTIONS, which checks nothing about BYOA. `compile` throws the
+ *   same text.
  * - `EVENT_FILTER_UNKNOWN_FIELD` — a filter leaf naming a field outside the
  *   prepared vocabulary is an ERROR, not a warning, because the platform's own
  *   configure DROPS an unmatched leaf and reports Success: the deployed
@@ -1988,6 +1996,9 @@ function checkEventResolution(subscription, where, kind, opts, error, warn, even
         return;
     }
     const object = typeof sub.object === 'string' && sub.object !== '' ? sub.object : undefined;
+    const byoa = opts.eventFacts && byoaUnverified(where, { connector: connectorKey, event: eventName, ...(object ? { object } : {}), connection: sub.connection }, opts.eventFacts(connectorKey, eventName, object), opts.byoa, opts.bindings);
+    if (byoa)
+        error(EVENT_BYOA_UNVERIFIED, byoa);
     if (eventParams?.objectUnprepared && object) {
         // The generic template answers for every object, so resolution SUCCEEDS
         // and nothing downstream notices that the object named here has no

package/dist/cli/commands/bpmn.js

@@ -18,6 +18,7 @@ export function registerBpmnCommands(program) {
         .description('Check authored TypeScript. Check a .bpmn with `uip maestro bpmn validate`.')
         .argument('<input>', 'a .bpmn.ts path or bare name')
         .option('--source', 'check authored TypeScript')
+        .option('--graph', 'also print the resolved wiring: every element with the flows leaving it, implied edges marked ~>')
         .addOption(retiredCompiledOption())
         .action(async (input, options) => {
         let mode;
@@ -32,7 +33,10 @@ export function registerBpmnCommands(program) {
             refuse('flow-sdk bpmn check --compiled: use `uip maestro bpmn validate <file.bpmn>`');
             return;
         }
-        await invoke('bpmn check', () => loadTool(import.meta.url, '../../bpmn/check-cli.js'), [input]);
+        const argv = [input];
+        if (options.graph)
+            argv.push('--graph');
+        await invoke('bpmn check', () => loadTool(import.meta.url, '../../bpmn/check-cli.js'), argv);
     });
     family.command('tidy')
         .description('Add diagram layout to a compiled .bpmn artifact.')
@@ -49,10 +53,12 @@ export function registerBpmnCommands(program) {
         .argument('<input>', 'input .bpmn path')
         .option('-o, --output <file>', 'output .bpmn.ts path')
         .option('--import <specifier>', 'SDK import specifier in generated source')
+        .option('--style <style>', 'explicit (default) writes one call per element and flow; nested lifts boundary events, gateways and event sub-processes into the nesting constructs where the graph is provably the same')
         .action(async (input, options) => {
         const argv = [input];
         addValue(argv, '-o', options.output);
         addValue(argv, '--import', options.import);
+        addValue(argv, '--style', options.style);
         await invoke('bpmn decompile', () => loadTool(import.meta.url, '../../bpmn/decompile-cli.js'), argv);
     });
     family

package/dist/cli-library.d.ts

@@ -19,3 +19,10 @@ export declare function openCliLibrary(argv: readonly string[]): Library | undef
  * exactly when compile would throw, with the same text.
  */
 export declare function eventResolveErrorFor(library: Library): NonNullable<CheckOpts['eventResolveError']>;
+/**
+ * `check`'s EVENT_BYOA_UNVERIFIED inputs: the event facts and the recorded BYOA
+ * checks, from the same `library.eventFacts` / `library.byoaVerifications` that
+ * `serialize` reads for the same refusal. Both CLIs spread this into their
+ * check options, so the inner loop and the emit rung refuse the same flows.
+ */
+export declare function byoaCheckOpts(library: Library): Pick<CheckOpts, 'eventFacts' | 'byoa'>;

package/dist/cli-library.js

@@ -54,3 +54,22 @@ export function eventResolveErrorFor(library) {
         }
     };
 }
+/**
+ * `check`'s EVENT_BYOA_UNVERIFIED inputs: the event facts and the recorded BYOA
+ * checks, from the same `library.eventFacts` / `library.byoaVerifications` that
+ * `serialize` reads for the same refusal. Both CLIs spread this into their
+ * check options, so the inner loop and the emit rung refuse the same flows.
+ */
+export function byoaCheckOpts(library) {
+    return {
+        eventFacts: (connector, event, object) => {
+            try {
+                return library.eventFacts(connector, event, object);
+            }
+            catch {
+                return undefined; // unknown fails open, same as every library callback
+            }
+        },
+        byoa: library.byoaVerifications,
+    };
+}

package/dist/compile-cli.js

@@ -23,12 +23,13 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars, connectorInputErrors } from './serialize.js';
 import { check } from './check.js';
-import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
+import { byoaCheckOpts, eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { BindingRefusal } from './core/binding-messages.js';
+import { ByoaRefusal } from './core/byoa.js';
 function opt(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -96,6 +97,7 @@ export async function run(argv) {
                 // printed as `✗ [EVENT_UNKNOWN]` before stopping instead of hiding
                 // behind "1 error(s); not emitting".
                 eventResolveError: eventResolveErrorFor(library),
+                ...byoaCheckOpts(library),
                 eventParams: (connector, event) => {
                     try {
                         return library.eventParameterFields(connector, event);
@@ -134,16 +136,17 @@ export async function run(argv) {
     // check()'s. Warnings are never fatal: the .flow is still written, exit stays 0.
     // A binding LABEL the serializer refuses (its own name as the resourceKey, or a
     // label a populated bindings.json does not declare) is an error, not a
-    // warning: the check pass above reports it first, and this is the same refusal
-    // in the same `✗ [CODE]` shape when that pass was skipped (`--no-check`, or an
-    // emit-only project). Nothing is written.
+    // warning, and so is a BYOA-only event on a connection `prepare` never checked
+    // (EVENT_BYOA_UNVERIFIED): the check pass above reports each first, and this is
+    // the same refusal in the same `✗ [CODE]` shape when that pass was skipped
+    // (`--no-check`, or an emit-only project). Nothing is written.
     const warnings = [];
     let emitted;
     try {
         emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
     }
     catch (error) {
-        if (!(error instanceof BindingRefusal))
+        if (!(error instanceof BindingRefusal || error instanceof ByoaRefusal))
             throw error;
         for (const w of warnings)
             console.error(`  ⚠ [${w.code}] ${w.message}`);

package/dist/core/byoa.d.ts

@@ -0,0 +1,69 @@
+/** The diagnostic code, in `check` and on the error `serialize` throws. */
+export declare const EVENT_BYOA_UNVERIFIED = "EVENT_BYOA_UNVERIFIED";
+/** One verification `prepare` recorded. Only a PASSING check is ever written. */
+export interface ByoaRecord {
+    byoa: true;
+    /** The connection's `Name`, so a person reading the file can tell which one it is. */
+    connectionName?: string;
+    /** `YYYY-MM-DD`: a resolved answer is a snapshot, like every other ledger row. */
+    verifiedAt?: string;
+}
+/**
+ * The ledger's `byoa` section: `byoa[<event node type>][<connection id>]`.
+ *
+ * Keyed per EVENT, not per connector — Slack `send-reply` needs no BYOA, the
+ * message trigger does — and per CONNECTION, so swapping the connection in
+ * bindings.json un-verifies the event until it is prepared again.
+ */
+export type ByoaLedger = Record<string, Record<string, ByoaRecord>>;
+/** The event facts the rule reads, as `Library.eventFacts` answers them. */
+export interface ByoaEventFacts {
+    byoaConnection: boolean;
+    isWebhookUrlVisible: boolean;
+}
+/**
+ * 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 declare function byoaLedgerKey(connectorKey: string, event: string): string;
+/** The record for `connectionId` under `nodeType`, matching the id case-insensitively. */
+export declare function byoaRecordFor(ledger: ByoaLedger | undefined, nodeType: string, connectionId: string): ByoaRecord | undefined;
+/** What `compile` throws for the refusal; `code` lets the CLI print it as `✗ [CODE]`. */
+export declare class ByoaRefusal extends Error {
+    readonly code = "EVENT_BYOA_UNVERIFIED";
+    constructor(message: string);
+}
+/** One subscription, as the rule needs it. */
+export interface ByoaSubscription {
+    connector: string;
+    event: string;
+    object?: string;
+    /** The `connection:` label as authored — a bindings.json name, or a connection id. */
+    connection?: unknown;
+}
+/**
+ * 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 declare function byoaUnverified(where: string, sub: ByoaSubscription, facts: ByoaEventFacts | undefined, ledger: ByoaLedger | undefined, bindings: {
+    resolve(name?: string): string | undefined;
+} | undefined): string | undefined;

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.