@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

package/dist/nodes/data-fabric/flow/shared.js

@@ -0,0 +1,174 @@
+/**
+ * What the four Flow Data Fabric verbs share: the `entityConfig` envelope every
+ * one of them serializes into, the record selector update and delete use, the
+ * folder-scope bindings, and the lift back to source.
+ *
+ * Moved verbatim from serialize.ts / decompile.ts (Phase 2 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md); the comments that explain each wire
+ * decision came with the code.
+ */
+import { Expr } from '../../../core/expr.js';
+export function entityConfigOf(node) {
+    const inputs = node?.inputs ?? {};
+    return (inputs.entityConfig ?? {});
+}
+/** `entityConfig` as every verb starts it. */
+export function baseConfig(inputs) {
+    return { entityName: inputs.entity };
+}
+/**
+ * `recordSource` is how update and delete both name their target; the read
+ * step's emitted node id is rename-aware, for subflow copies.
+ */
+export function targetRecord(cfg, record, ctx) {
+    const r = record;
+    if (typeof r.fromRead === 'string') {
+        cfg.recordSource = 'fromRead';
+        cfg.readEntityNodeId = ctx.stepNodeId(r.fromRead);
+    }
+    else {
+        cfg.recordSource = 'byId';
+        cfg.recordId = String(ctx.render(r.byId));
+    }
+}
+/** A `{ <field>: <value> }` map as the `{ field, value }` rows create and update write. */
+export function fieldRows(values, ctx) {
+    return Object.entries(values ?? {}).map(([field, value]) => ({
+        field,
+        value: String(ctx.render(value)),
+    }));
+}
+/**
+ * The flat `_filters` array. `join: 'OR'` on a row STARTS a new alternative —
+ * `entity-vdo.ts`'s `buildQesFromEntityConfig` splits the array into runs on that
+ * key, ANDs within a run, and ORs the runs together. So the query model is
+ * disjunctive: `alt1 OR alt2 OR …`, each `alt` an AND of its rows, which is why
+ * `[A, B(or), C]` is `A OR (B AND C)` and not `(A OR B) AND C`.
+ *
+ * The grouped `{ logicalOperator, rows, groups }` object the authoring guide
+ * shows is a NEWER shape: the vendored converter the local engine runs throws
+ * `(filters ?? []).filter is not a function` on it, so emitting it would trade
+ * a working offline rung for a shape only the current platform can read. The
+ * array is the form both accept.
+ */
+export function filterRows(filters, ctx) {
+    return filters.map((f, i) => ({
+        field: f.field,
+        operator: f.operator ?? '=',
+        value: String(ctx.render(f.value)),
+        // Never on the first row: a leading `join` starts an empty run, which the
+        // platform's own loop guards against, and which means nothing anyway.
+        ...(i > 0 && f.or ? { join: 'OR' } : {}),
+    }));
+}
+/**
+ * The folder scope, last in `entityConfig`. A folder-scoped entity is portable
+ * only with its `Entity` bindings; the half-authored form is refused by check(),
+ * so reaching here with both means emit both. Same id for the same (entity,
+ * resourceKey), so two steps on one entity share one pair rather than
+ * duplicating it.
+ */
+export function applyScope(cfg, inputs, ctx) {
+    if (inputs.folderKey !== undefined)
+        cfg._folderKey = inputs.folderKey;
+    if (inputs.folderKey !== undefined && inputs.resourceKey !== undefined) {
+        cfg._resourceKey = inputs.resourceKey;
+        for (const entry of entityBindings(inputs.entity, inputs.folderKey, inputs.resourceKey))
+            ctx.bind(entry);
+    }
+}
+/**
+ * The two `bindings[]` rows a FOLDER-SCOPED entity needs to survive export to
+ * another org, and the `_resourceKey` that ties them to the node.
+ *
+ * Nothing else emits `resource: 'Entity'`: the kind is matched by
+ * `(resourceKey, propertyAttribute)` rather than by name, carries no
+ * `resourceSubType`, spells the folder attribute `folderKey` (never
+ * `folderPath` — a folderPath row receives the Orchestrator FQN, which the
+ * Data Fabric query rejects even in the source org), and puts a DISPLAY label
+ * in `name`. The capital `E` is load-bearing: packaging ignores a lowercase
+ * row, so deploy emits no override at all.
+ *
+ * A tenant-scoped entity needs none of this — it serializes as a dotted
+ * literal — which is why the pair is emitted only when the author supplied
+ * both `folderKey` and `resourceKey`.
+ */
+function entityBindings(entity, folderKey, resourceKey) {
+    const base = `b${entity.replace(/[^A-Za-z0-9]/g, '')}Entity`;
+    return [
+        {
+            id: `${base}Name`,
+            name: entity,
+            type: 'string',
+            resource: 'Entity',
+            resourceKey,
+            default: entity,
+            propertyAttribute: 'name',
+        },
+        {
+            id: `${base}Folder`,
+            name: `${entity}Folder`,
+            type: 'string',
+            resource: 'Entity',
+            resourceKey,
+            default: folderKey,
+            propertyAttribute: 'folderKey',
+        },
+    ];
+}
+// ─── The lift ──────────────────────────────────────────────────────────────────
+/**
+ * A serialized value back as the spec holds it. 1.3 let `recordId` and a
+ * create's field value be a `{ type: 'jsExpression', expression }` object as well
+ * as a `=js:` string; a product-authored node can carry either, and both recover
+ * as an expression. Anything else is TEXT — a number in a field row prints as
+ * `"5"`, as it always has.
+ */
+export function liftValue(v) {
+    const obj = v;
+    if (obj && typeof obj === 'object' && obj.type === 'jsExpression')
+        return new Expr(String(obj.expression ?? ''));
+    const raw = typeof v === 'string' ? v : String(v ?? '');
+    return raw.startsWith('=js:') ? new Expr(raw.slice(4)) : raw;
+}
+/** The scope options, read back. */
+export function liftScope(cfg) {
+    return {
+        entity: String(cfg.entityName ?? ''),
+        ...(typeof cfg._folderKey === 'string' ? { folderKey: cfg._folderKey } : {}),
+        ...(typeof cfg._resourceKey === 'string' ? { resourceKey: cfg._resourceKey } : {}),
+    };
+}
+/** The record selector, read back. */
+export function liftRecord(cfg) {
+    return cfg.recordSource === 'fromRead'
+        ? { fromRead: String(cfg.readEntityNodeId ?? '') }
+        : { byId: liftValue(cfg.recordId) };
+}
+/** `{ field, value }` rows back as the `{ <field>: <value> }` map. */
+export function liftFields(rows) {
+    const list = Array.isArray(rows) ? rows : [];
+    const out = {};
+    for (const r of list)
+        out[String(r.field ?? '')] = liftValue(r.value);
+    return out;
+}
+// ─── Printing ──────────────────────────────────────────────────────────────────
+/** `entity`, then the verb's own options, then the scope — the order every verb prints in. */
+export function scopeOptions(inputs, ctx) {
+    return {
+        entity: ['entity', ctx.string(inputs.entity)],
+        tail: [
+            ['folderKey', inputs.folderKey !== undefined ? ctx.string(inputs.folderKey) : undefined],
+            ['resourceKey', inputs.resourceKey !== undefined ? ctx.string(inputs.resourceKey) : undefined],
+        ],
+    };
+}
+export function printRecord(record, ctx) {
+    const r = record;
+    return typeof r.fromRead === 'string' ? `{ fromRead: ${ctx.string(r.fromRead)} }` : `{ byId: ${ctx.value(r.byId)} }`;
+}
+/** A field map as `{ k: v, … }` — `{  }` when empty, exactly as the decompiler always wrote it. */
+export function printFields(values, ctx) {
+    return `{ ${Object.entries(values ?? {}).map(([k, v]) => `${ctx.key(k)}: ${ctx.value(v)}`).join(', ')} }`;
+}

package/dist/nodes/data-fabric/flow/spec.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The Flow Data Fabric family's authoring types, and its four kinds' entries in
+ * `FlowActionSpecs` (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §4.6). Moved from
+ * core/actions.ts in Phase 2c; the family adds its kinds to the map here, by
+ * declaration merging, so `ActionSpec` gains them wherever this module is part of
+ * the program — the package entry re-exports it, so that is everywhere.
+ */
+import type { Expr } from '../../../core/expr.js';
+/**
+ * The comparison operators the Data Fabric query serializer can emit, spelled
+ * exactly as the file carries them.
+ *
+ * @remarks
+ * There is deliberately no `not in`, `not contains`, or null check — the
+ * serializer cannot emit them, and a filter it cannot emit takes the WHOLE
+ * query down rather than dropping one row. `is any of` is the legacy spelling
+ * of `in` and is still read, but author `in`.
+ */
+export type DataFabricOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'starts with' | 'ends with' | 'in';
+/** One filter row on a Data Fabric query — rows AND together unless `or` is set. */
+export interface DataFabricFilter {
+    /**
+     * The entity column to filter on. A dotted related path (`customer.Name`) is
+     * capped at 3 segments and needs the canvas's `_entityFields` snapshot, which
+     * the SDK does not author — keep from-scratch filters on the entity's own
+     * columns.
+     */
+    field: string;
+    /** Comparison operator; `=` when omitted. */
+    operator?: DataFabricOperator;
+    /**
+     * The comparison value. An `Expr` re-evaluates at activation time.
+     *
+     * A choice-set column compares against the choice's numeric `numberId`, never
+     * its label — a label matches nothing.
+     */
+    value: string | Expr;
+    /**
+     * Start a new OR alternative at this row.
+     *
+     * @remarks
+     * The query model is disjunctive — `alt1 OR alt2 OR …`, each alternative an
+     * AND of its own rows — so `or` SPLITS the list rather than joining one row
+     * to the one before it. `[A, B(or), C]` is therefore `A OR (B AND C)`, not
+     * `(A OR B) AND C`; to get the latter, write it out as
+     * `(A AND C) OR (B AND C)`.
+     *
+     * Ignored on the first row, which has no earlier alternative to split from.
+     */
+    or?: boolean;
+}
+/** How a multi-record query orders its rows before the limit is applied. */
+export interface DataFabricSort {
+    /** The column to order by — a real one; a sort on a missing column is not caught by `validate`. */
+    field: string;
+    /** `'asc'` when omitted. */
+    direction?: 'asc' | 'desc';
+}
+/**
+ * Which record a Data Fabric write targets — exactly ONE of the two forms.
+ *
+ * @remarks
+ * `{ byId }` names a record id, literal or expression. `{ fromRead }` names an
+ * earlier {@link dataFabricRead} STEP and reuses the record that step found, so
+ * the id never has to be carried by hand; `check` rejects a name no read step
+ * has. Shared by {@link dataFabricUpdate} and {@link dataFabricDelete} — the
+ * platform gives them the same `recordSource` shape.
+ */
+export type DataFabricRecordRef = {
+    byId: string | Expr;
+    fromRead?: never;
+} | {
+    fromRead: string;
+    byId?: never;
+};
+export interface DataFabricReadInputs {
+    /** The Data Fabric entity's name, e.g. `'Invoices'`. */
+    entity: string;
+    /** Filter rows selecting the record(s) to query. Omit to take everything the entity holds. */
+    filters?: DataFabricFilter[];
+    /**
+     * `'single'` publishes ONE record as the step's `output`; `'multiple'`
+     * publishes the matching records under `output.results`.
+     *
+     * Setting either selects the node's **1.4** definition, which is where
+     * `resultMode` exists at all — the SDK's pinned default is 1.0, the
+     * read-one-record node this family started as. Omit it and nothing changes:
+     * the step stays on 1.0 and reads one record, as it always did.
+     *
+     * A `'single'` read faults only on an OVER-match; zero matches completes
+     * normally and leaves the step's output unresolved, so treat "not found" as a
+     * branch rather than an error.
+     */
+    resultMode?: 'single' | 'multiple';
+    /**
+     * Row cap for a `'multiple'` query. The emitted query ALWAYS carries a limit:
+     * omitting this resolves to 100, and 1000 is a hard ceiling — a larger value
+     * truncates silently, so page with `skip` instead.
+     */
+    limit?: number;
+    /** Rows to skip before the limit — the paging half of `limit`. */
+    skip?: number;
+    /** Order rows before the limit applies. Without it a limited slice is arbitrary. */
+    sort?: DataFabricSort;
+    /** Only these columns. Omit for every column the entity has. */
+    fields?: string[];
+    /**
+     * Folder key (GUID) for a folder-scoped entity — its `folderId` from
+     * `uip df entities list --include-folders`.
+     *
+     * Requires `resourceKey`: `folderKey` alone serializes the folder as a
+     * source-org LITERAL, which looks portable and breaks on cross-org deploy, so
+     * `check` refuses the pair being half-authored.
+     */
+    folderKey?: string;
+    /**
+     * The key the entity's reference is registered under in the solution, from
+     * `uip solution resources list --kind Entity`.
+     *
+     * @remarks
+     * Only meaningful with `folderKey`. Supplying both emits the two
+     * `resource: 'Entity'` binding rows (`propertyAttribute` `name` and
+     * `folderKey`) that let the flow deploy to another org. Nothing mints this
+     * key for a hand-authored flow — if you cannot resolve one, keep the entity
+     * tenant-scoped and omit both.
+     */
+    resourceKey?: string;
+}
+export interface DataFabricCreateInputs {
+    /** The Data Fabric entity's name, e.g. `'Invoices'`. */
+    entity: string;
+    /**
+     * The columns the new record starts with, by field name. At least one is
+     * required — the node's schema rejects an empty field list rather than
+     * inserting a blank row.
+     */
+    values: Record<string, string | Expr>;
+    /**
+     * Folder key (GUID) for a folder-scoped entity — its `folderId` from
+     * `uip df entities list --include-folders`.
+     *
+     * Requires `resourceKey`: `folderKey` alone serializes the folder as a
+     * source-org LITERAL, which looks portable and breaks on cross-org deploy, so
+     * `check` refuses the pair being half-authored.
+     */
+    folderKey?: string;
+    /**
+     * The key the entity's reference is registered under in the solution, from
+     * `uip solution resources list --kind Entity`.
+     *
+     * @remarks
+     * Only meaningful with `folderKey`. Supplying both emits the two
+     * `resource: 'Entity'` binding rows (`propertyAttribute` `name` and
+     * `folderKey`) that let the flow deploy to another org. Nothing mints this
+     * key for a hand-authored flow — if you cannot resolve one, keep the entity
+     * tenant-scoped and omit both.
+     */
+    resourceKey?: string;
+}
+export interface DataFabricUpdateInputs {
+    /** The Data Fabric entity's name, e.g. `'Invoices'`. */
+    entity: string;
+    /** Which record to update — see {@link DataFabricRecordRef}. */
+    record: DataFabricRecordRef;
+    /**
+     * The columns to write, by field name. An empty string is a real write — it
+     * clears the column.
+     */
+    set: Record<string, string | Expr>;
+    /**
+     * Folder key (GUID) for a folder-scoped entity — its `folderId` from
+     * `uip df entities list --include-folders`.
+     *
+     * Requires `resourceKey`: `folderKey` alone serializes the folder as a
+     * source-org LITERAL, which looks portable and breaks on cross-org deploy, so
+     * `check` refuses the pair being half-authored.
+     */
+    folderKey?: string;
+    /**
+     * The key the entity's reference is registered under in the solution, from
+     * `uip solution resources list --kind Entity`.
+     *
+     * @remarks
+     * Only meaningful with `folderKey`. Supplying both emits the two
+     * `resource: 'Entity'` binding rows (`propertyAttribute` `name` and
+     * `folderKey`) that let the flow deploy to another org. Nothing mints this
+     * key for a hand-authored flow — if you cannot resolve one, keep the entity
+     * tenant-scoped and omit both.
+     */
+    resourceKey?: string;
+}
+export interface DataFabricDeleteInputs {
+    /** The Data Fabric entity's name, e.g. `'Invoices'`. */
+    entity: string;
+    /** Which record to delete — see {@link DataFabricRecordRef}. */
+    record: DataFabricRecordRef;
+    /**
+     * Folder key (GUID) for a folder-scoped entity — its `folderId` from
+     * `uip df entities list --include-folders`.
+     *
+     * Requires `resourceKey`: `folderKey` alone serializes the folder as a
+     * source-org LITERAL, which looks portable and breaks on cross-org deploy, so
+     * `check` refuses the pair being half-authored.
+     */
+    folderKey?: string;
+    /**
+     * The key the entity's reference is registered under in the solution, from
+     * `uip solution resources list --kind Entity`.
+     *
+     * @remarks
+     * Only meaningful with `folderKey`. Supplying both emits the two
+     * `resource: 'Entity'` binding rows (`propertyAttribute` `name` and
+     * `folderKey`) that let the flow deploy to another org. Nothing mints this
+     * key for a hand-authored flow — if you cannot resolve one, keep the entity
+     * tenant-scoped and omit both.
+     */
+    resourceKey?: string;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link dataFabricRead} builds. */
+        dataFabricRead: {
+            inputs: DataFabricReadInputs;
+        };
+        /** The spec {@link dataFabricCreate} builds. */
+        dataFabricCreate: {
+            inputs: DataFabricCreateInputs;
+        };
+        /** The spec {@link dataFabricUpdate} builds. */
+        dataFabricUpdate: {
+            inputs: DataFabricUpdateInputs;
+        };
+        /** The spec {@link dataFabricDelete} builds. */
+        dataFabricDelete: {
+            inputs: DataFabricDeleteInputs;
+        };
+    }
+}

package/dist/nodes/data-fabric/flow/spec.js

@@ -0,0 +1 @@
+export {};

package/dist/nodes/data-fabric/flow/verbs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The four Flow Data Fabric verbs as node types: read (1.0 and 1.4), create
+ * (1.3), update (1.0 and 1.3) and delete (1.3). Each version's implementation is
+ * the same code today — the serialized shape is identical across the bundled
+ * versions — so a version is one `verb(version)` call; a version that changes the
+ * shape gets its own implementation (design §7).
+ */
+import type { DataFabricCreateInputs, DataFabricDeleteInputs, DataFabricReadInputs, DataFabricUpdateInputs } from './spec.js';
+import type { FlowNodeType, FlowVersionedNodeType } from '../../../flow-node-type.js';
+export type DataFabricReadSpec = {
+    kind: 'dataFabricRead';
+    inputs: DataFabricReadInputs;
+};
+export type DataFabricCreateSpec = {
+    kind: 'dataFabricCreate';
+    inputs: DataFabricCreateInputs;
+};
+export type DataFabricUpdateSpec = {
+    kind: 'dataFabricUpdate';
+    inputs: DataFabricUpdateInputs;
+};
+export type DataFabricDeleteSpec = {
+    kind: 'dataFabricDelete';
+    inputs: DataFabricDeleteInputs;
+};
+export declare const dataFabricRead: FlowVersionedNodeType<DataFabricReadSpec>;
+export declare const dataFabricCreate: FlowNodeType<DataFabricCreateSpec>;
+export declare const dataFabricUpdate: FlowVersionedNodeType<DataFabricUpdateSpec>;
+export declare const dataFabricDelete: FlowNodeType<DataFabricDeleteSpec>;