@uipath/maestro-builder-sdk 6.11.0 → 6.11.1

package/dist/registry/prepare/ledger.js

@@ -146,7 +146,10 @@ export async function writeResolutions(run, specs) {
         }
         let got;
         try {
-            got = await resolveOne(run.client, run.connectorKey, table.get(field), field, by, value, run.connectionId, resolved);
+            const notes = [];
+            got = await resolveOne(run.client, run.connectorKey, table.get(field), field, by, value, run.connectionId, resolved, notes);
+            for (const note of notes)
+                run.reporter.info(note);
         }
         catch (error) {
             // The collection was read to the END on this connection and the value

package/dist/registry/prepare/resolve.d.ts

@@ -229,7 +229,7 @@ export declare function scanCollection(client: UipClient, connectorKey: string,
  * A collection read to its end with no match throws {@link LookupExhausted},
  * the subclass the caller's retry keys on; every other failure is the parent.
  */
-export declare function resolveOne(client: UipClient, connectorKey: string, spec: ResolveSpec, field: string, by: string, value: string, connectionId: string, resolved?: Resolved): Promise<string>;
+export declare function resolveOne(client: UipClient, connectorKey: string, spec: ResolveSpec, field: string, by: string, value: string, connectionId: string, resolved?: Resolved, notes?: string[]): Promise<string>;
 /**
  * The child collection of `parent`: `childPath` with each `{Field}` read off
  * the parent record (`{ID}` → the folder's id), split into collection and

package/dist/registry/prepare/resolve.js

@@ -449,7 +449,7 @@ export async function* scanCollection(client, connectorKey, collection, connecti
  * A collection read to its end with no match throws {@link LookupExhausted},
  * the subclass the caller's retry keys on; every other failure is the parent.
  */
-export async function resolveOne(client, connectorKey, spec, field, by, value, connectionId, resolved = new Map()) {
+export async function resolveOne(client, connectorKey, spec, field, by, value, connectionId, resolved = new Map(), notes) {
     const searchableBy = Array.isArray(spec.by) ? spec.by : [];
     if (!searchableBy.includes(by)) {
         const searchable = searchableBy.map(pyRepr).join(", ");
@@ -482,13 +482,15 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
     // pasting a literal id (flow-builder-sdk#818). A server-side filter still
     // wins: it answers from the whole collection in one request.
     if (pyTruthy(spec.childPath) && !pyTruthy(filterPattern)) {
-        return resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, collection, query, send);
+        return resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, collection, query, send, notes);
     }
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
     // What the collection DOES hold at `by`, for the refusal: kept only while it
     // could still be listed in full, plus the first case-insensitive equal.
     const held = [];
-    let near;
+    // Records whose `by` equals the value ignoring case only, first per distinct
+    // spelling: the fallback when no record matches exactly.
+    const caseOnly = new Map();
     let step = await scan.next();
     while (!step.done) {
         for (const record of step.value) {
@@ -497,8 +499,8 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
                 const text = pyStrAny(at);
                 if (held.length <= CANDIDATE_LIMIT && !held.includes(text))
                     held.push(text);
-                if (near === undefined && text !== value && text.toLowerCase() === value.toLowerCase())
-                    near = text;
+                if (text !== value && text.toLowerCase() === value.toLowerCase() && !caseOnly.has(text))
+                    caseOnly.set(text, record);
             }
             if (matchRecord(record, by, value)) {
                 const got = readPath(record, send);
@@ -512,6 +514,27 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         step = await scan.next();
     }
     const { scanned, pages, capped } = step.value;
+    // No exact match anywhere in the collection: try the case-only ones. Exact
+    // first, because an id picked by a looser rule while the exact record sat
+    // on a later page would be the wrong id. Only once the scan has read to the
+    // END — a capped scan may still hold the exact record further in, so it
+    // keeps the refusal and the hint.
+    //
+    // `send_as:name=user` against `available_tokens` ('Bot', 'User') and
+    // `E2E-testing` against `E2E-Testing` each cost a refused `prepare` and a
+    // re-run whose only change was the letter case the refusal had already
+    // named (flow-builder-sdk#818). One spelling is unambiguous, so it is taken
+    // and said; two spellings that differ only in case are two records, and
+    // choosing between them would be a guess.
+    const near = caseOnly.size > 0 ? [...caseOnly.keys()][0] : undefined;
+    if (!capped && caseOnly.size > 0) {
+        const record = findRecord([...caseOnly.values()], field, by, value, notes);
+        const got = readPath(record, send);
+        if (got === null) {
+            throw new ResolutionRefusal(`${field}: matched a record on ${by}=${pyRepr(pyStrAny(readPath(record, by)))}, but it carries no ${pyRepr(send)} to send.`, "RESOLVE_NO_VALUE");
+        }
+        return pyStrAny(got);
+    }
     // This states the FACT and stops; `prepare` owns the remedy, because
     // `prepare` is what knows the other candidate connections.
     //
@@ -529,8 +552,8 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
     // is finally the next step rather than a detour.
     //
     // What it DOES carry is what the collection holds, when that is small enough
-    // to read in one line, and a case-only near miss: facts about this
-    // connection, not a remedy. `matchRecord` stays exact — nothing is picked.
+    // to read in one line, and — when the cap stopped the scan — a case-only
+    // near miss that was NOT taken: facts about this connection, not a remedy.
     //
     // Never under a server-side filter: the scan then read only the records the
     // filter returned (`name like '%Coder Eval%'` gives 'Coder Evals' and 'Coder
@@ -541,13 +564,43 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         `(scanned ${scanned} record(s) across ${pages + 1} page(s)` +
         (capped ? `; STOPPED AT THE ${MAX_SCANNED}-record cap, so the value may be further in` : "; collection exhausted") +
         `) on connection ${connectionId}.` +
-        (near !== undefined ? ` Did you mean ${pyRepr(near)}? The match is exact, case included.` : "") +
+        (near !== undefined
+            ? ` Did you mean ${pyRepr(near)}? It differs only in case and was not taken: the scan stopped before the end, where an exact match may still be.`
+            : "") +
         (candidates !== undefined ? ` It holds: ${candidates.map(pyRepr).join(", ")}.` : ""), {
         field, collection, by, value, scanned, pages: pages + 1, capped,
         ...(candidates !== undefined ? { candidates } : {}),
         ...(near !== undefined ? { near } : {}),
     });
 }
+/**
+ * The record in `records` matching `value` on `by`: exact first, else the one
+ * case-only spelling (reported through `notes`), else `undefined`. Two
+ * case-only spellings are a refusal, as in the flat scan.
+ */
+function findRecord(records, field, by, value, notes) {
+    const exact = records.find((record) => matchRecord(record, by, value));
+    if (exact !== undefined)
+        return exact;
+    const caseOnly = new Map();
+    for (const record of records) {
+        const at = readPath(record, by);
+        if (at === null || at === undefined)
+            continue;
+        const text = pyStrAny(at);
+        if (text !== value && text.toLowerCase() === value.toLowerCase() && !caseOnly.has(text))
+            caseOnly.set(text, record);
+    }
+    if (caseOnly.size === 0)
+        return undefined;
+    if (caseOnly.size > 1) {
+        throw new ResolutionRefusal(`${field}: no record has ${by}=${pyRepr(value)} exactly, and ${caseOnly.size} differ from it only in case: ` +
+            `${[...caseOnly.keys()].map(pyRepr).join(", ")}. They are different records; pass the one you mean exactly.`, "RESOLVE_CASE_AMBIGUOUS");
+    }
+    const [[text, record]] = [...caseOnly.entries()];
+    notes?.push(`  ${field}: no record has ${by}=${pyRepr(value)} exactly; took ${pyRepr(text)}, the only one that differs from it only in case`);
+    return record;
+}
 async function listAll(client, connectorKey, collection, connectionId, query) {
     const records = [];
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
@@ -602,7 +655,7 @@ function isContainer(record) {
  * connections. A path whose segment is missing from a listing read to the end
  * IS evidence, and is reported as an exhaustive miss like a flat scan's.
  */
-async function resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, rootCollection, rootQuery, send) {
+async function resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, rootCollection, rootQuery, send, notes) {
     const childPath = pyStrAny(spec.childPath);
     const answer = (record) => {
         const got = readPath(record, send);
@@ -625,12 +678,14 @@ async function resolveInTree(client, connectorKey, spec, field, by, value, conne
     const exact = root.records.find((record) => matchRecord(record, by, value));
     if (exact !== undefined)
         return answer(exact);
+    // A whole-value case-only match at the root is deferred: a path value, or a
+    // bare name one level down, may still match exactly.
     const segments = value.split("/").map((segment) => pyStrip(segment)).filter((segment) => segment !== "");
     if (segments.length > 1) {
         let level = root;
         let where = rootCollection;
         for (const [i, segment] of segments.entries()) {
-            const hit = level.records.find((record) => matchRecord(record, by, segment));
+            const hit = findRecord(level.records, field, by, segment, notes);
             if (hit === undefined) {
                 const held = level.records.map((record) => pyStrAny(readPath(record, by))).filter((text) => text !== "None");
                 const shown = !level.outcome.capped && held.length > 0 && held.length <= CANDIDATE_LIMIT ? ` It holds: ${held.map(pyRepr).join(", ")}.` : "";
@@ -651,6 +706,7 @@ async function resolveInTree(client, connectorKey, spec, field, by, value, conne
         }
     }
     // Bare name: one level below every root container.
+    const below = [];
     for (const parent of root.records) {
         if (!isContainer(parent))
             continue;
@@ -660,10 +716,16 @@ async function resolveInTree(client, connectorKey, spec, field, by, value, conne
         if (child === undefined)
             continue;
         const level = await list(child.collection, child.query);
-        const hit = level.records.find((record) => matchRecord(record, by, value));
-        if (hit !== undefined)
-            return answer(hit);
+        const exactBelow = level.records.find((record) => matchRecord(record, by, value));
+        if (exactBelow !== undefined)
+            return answer(exactBelow);
+        below.push(...level.records);
     }
+    // No exact match at either depth: the case-only one, root and one level
+    // down together, so a spelling in each is two records and a refusal.
+    const loose = findRecord([...root.records, ...below], field, by, value, notes);
+    if (loose !== undefined)
+        return answer(loose);
     const top = root.records.map((record) => pyStrAny(readPath(record, by))).filter((text) => text !== "None");
     const example = `${top[0] ?? "<top-level>"}/<folder>/${value}`;
     throw new LookupExhausted(`${field}: no record in ${pyRepr(rootCollection)} or one level below it has ${by}=${pyRepr(value)} ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.11.0",
+  "version": "6.11.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "fa8ffa3eea8369ff520a8214644c971df0c4af74"
+  "gitref": "85e9b8d11773bb7e83aed5deb38eea2ecd25bd2a"
 }