@tenonhq/dovetail-servicenow 0.0.7 → 0.0.9

package/README.md

@@ -154,8 +154,53 @@ npx dove-sn set-related-lists \
   --table x_cadso_automate_audience \
   --related-lists "x_cadso_automate_audience_member.audience" \
   --update-set 0083c3bb33d003507b18bc534d5c7b6d
+
+# View a flow / subflow's compiled step graph (read-only, headless)
+npx dove-sn view-flow --sys-id 327c53bfc33e3250d4ddf1db05013135
+npx dove-sn view-flow --sys-id <sys_id> --json --raw   # structured + full model
+
+# View a Custom Action Type's model (inputs/outputs)
+npx dove-sn view-action --sys-id <action_type_sys_id> --scope <scope_sys_id>
+
+# Copy a flow / subflow (creates an INACTIVE DRAFT) via the Designer's Copy endpoint
+npx dove-sn copy-flow --sys-id <sys_id> --name "My Copy"   # scope defaults to source's
+
+# Publish (compile the snapshot of) a flow / subflow after editing in the Designer
+npx dove-sn publish-flow --sys-id <sys_id>             # scope defaults to the flow's
+
+# Test a flow: validate (default, read-only) or actually run it
+npx dove-sn test-flow --sys-id <sys_id> --inputs '{"phone":"+1555..."}'
+npx dove-sn test-flow --sys-id <sys_id> --execute --confirm --inputs '{...}'  # runs it
+
+# Edit a flow in place (rename / description / step inputs)
+echo '{"rename":{"name":"New Name"},"patchStepInputs":[{"step":"Calculate SMS Send At","input":"send_rate","value":"5"}]}' > ops.json
+npx dove-sn edit-flow --sys-id <sys_id> --from-json ops.json                          # dry-run (diff)
+npx dove-sn edit-flow --sys-id <sys_id> --from-json ops.json --apply --update-set <id> # persist
 ```
 
+`copy-flow` calls the Designer's own `POST /processflow/flow/{id}/copy` — a
+complete, faithful clone created as an **inactive draft**. (Don't publish +
+activate a copy of a triggered production flow unless you intend it to fire.)
+`test-flow` defaults to **validate** — a safe pre-flight (published? inputs match
+declared variables?) that never runs the flow; `--execute --confirm` runs it via
+the server-side FlowAPI runner (deploy `resources/runFlow.md` first).
+
+`edit-flow` defaults to a **dry-run** diff. With `--apply`: rename/description are
+written to `sys_hub_flow` through the update-set-aware API (so `--update-set` is
+**required** for those), while `patchStepInputs` ride a snapshot recompile (the
+`/snapshot` POST persists step input values but NOT top-level flow fields).
+Step-input persistence via the snapshot POST is verified for action types but is
+**best-effort for flows** — after the recompile, `edit-flow` reads the model back
+and **warns** if a value didn't actually persist, so a no-op never reports as a
+silent success.
+
+`view-flow` reads `GET /api/now/processflow/flow/{id}` — the Designer's own model
+endpoint — and prints the ordered, nesting-aware action + flow-logic step graph
+plus the flow variables. This works for the integration user with plain basic
+auth; the raw `sys_hub_flow_snapshot` Table API 404 is a row-level restriction on
+the working snapshot, not a barrier. `publish-flow` POSTs the model back to
+`.../flow/{id}/snapshot`, recompiling the current design (a write).
+
 `set-form-layout` JSON payload shape:
 
 ```json
@@ -193,10 +238,14 @@ console.log(formatLayoutResult("form layout", result));
 
 ## MCP server
 
-`dove-sn mcp` runs a self-contained MCP stdio server exposing the write tools to
+`dove-sn mcp` runs a self-contained MCP stdio server exposing the tools to
 Claude Code and agents: `create_view`, `set_list_layout`, `set_form_layout`,
-`set_related_lists`, and `add_choices_to_field`. It reads ServiceNow credentials
-from the same env vars as the CLI.
+`set_related_lists`, `add_choices_to_field`, plus the Flow Designer tools
+`flow_view` (read a flow/subflow's step graph), `action_view` (read an action
+type's model), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
+(copy a flow as an inactive draft), `flow_test` (validate or run a flow), and
+`flow_edit` (patch a flow). It reads ServiceNow credentials from the same env
+vars as the CLI.
 
 ```bash
 npx dove-sn mcp --smoke   # list the registered tools and exit

package/dist/cli.js

@@ -68,6 +68,13 @@ const formatter_2 = require("./layout/formatter");
 const server_1 = require("./mcp/server");
 const buildFlowOrchestrator_1 = require("./flowDesigner/buildFlowOrchestrator");
 const flowDesigner_formatter_1 = require("./flowDesigner-formatter");
+const readFlow_1 = require("./flowDesigner/readFlow");
+const readActionType_1 = require("./flowDesigner/readActionType");
+const publishFlow_1 = require("./flowDesigner/publishFlow");
+const copyFlow_1 = require("./flowDesigner/copyFlow");
+const editFlow_1 = require("./flowDesigner/editFlow");
+const testFlow_1 = require("./flowDesigner/testFlow");
+const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
     var command = argv[0] || "";
     var flags = {};
@@ -299,6 +306,220 @@ async function runSetRelatedLists(flags) {
  * dove-sn mcp — run the MCP stdio server. With --smoke, list the registered
  * tools and exit. Otherwise the process stays alive until the transport closes.
  */
+/**
+ * dove-sn view-flow:
+ *   --sys-id <sys_id>   Required. sys_hub_flow sys_id (flow or subflow).
+ *   --json              Optional. Emit the structured ReadFlowResult.
+ *   --raw               Optional (with --json). Include the full processflow model.
+ *
+ * Reads the compiled flow headlessly via GET /api/now/processflow/flow/{id} and
+ * prints the ordered, nesting-aware step graph + flow variables. Read-only.
+ */
+async function runViewFlow(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    if (!sysId) {
+        process.stderr.write("view-flow: --sys-id <sys_id> is required\n");
+        return 1;
+    }
+    var client = (0, client_1.createClient)({});
+    var result = await (0, readFlow_1.readFlow)({ client: client, sysId: sysId, raw: flags.raw === "true" });
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write((0, flowDesigner_formatter_2.formatReadFlowResult)(result) + "\n");
+    return 0;
+}
+/**
+ * dove-sn view-action:
+ *   --sys-id <sys_id>   Required. sys_hub_action_type_definition sys_id.
+ *   --scope <sys_id>    Required. Application scope (sysparm_transaction_scope).
+ *   --json [--raw]      Optional. Structured ReadActionTypeResult / full model.
+ *
+ * Reads a Custom Action Type's compiled model (identity, inputs, outputs). Read-only.
+ */
+async function runViewAction(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    var scope = flags.scope || flags.scopeSysId;
+    if (!sysId || !scope) {
+        process.stderr.write("view-action: --sys-id <sys_id> and --scope <sys_id> are required\n");
+        return 1;
+    }
+    var client = (0, client_1.createClient)({});
+    var result = await (0, readActionType_1.readActionType)({
+        client: client,
+        sysId: sysId,
+        scopeSysId: scope,
+        raw: flags.raw === "true"
+    });
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write((0, flowDesigner_formatter_2.formatReadActionTypeResult)(result) + "\n");
+    return 0;
+}
+/**
+ * dove-sn publish-flow:
+ *   --sys-id <sys_id>   Required. sys_hub_flow sys_id (flow or subflow) to publish.
+ *   --scope <sys_id>    Optional. sysparm_transaction_scope (defaults to the model's scope).
+ *   --json              Optional. Emit the structured PublishFlowResult.
+ *
+ * Compiles the flow's snapshot via POST /api/now/processflow/flow/{id}/snapshot —
+ * a WRITE that recompiles the current design. Use the Designer to edit, then this
+ * to publish. (For edited content, the library publishFlow accepts a model.)
+ */
+async function runPublishFlow(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    if (!sysId) {
+        process.stderr.write("publish-flow: --sys-id <sys_id> is required\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        sysId: sysId
+    };
+    if (flags.scope || flags.scopeSysId) {
+        params.scopeSysId = flags.scope || flags.scopeSysId;
+    }
+    var result = await (0, publishFlow_1.publishFlow)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write("Published flow " + sysId + " (HTTP " + result.httpStatus + ")"
+        + (result.snapshotSysId ? " — snapshot " + result.snapshotSysId : "") + "\n");
+    return 0;
+}
+/**
+ * dove-sn copy-flow:
+ *   --sys-id <sys_id>   Required. Source sys_hub_flow sys_id (flow or subflow).
+ *   --name <name>       Required. Name for the copy.
+ *   --scope <sys_id>    Optional. Target scope (defaults to the source's scope).
+ *   --json              Optional. Emit the structured CopyFlowResult.
+ *
+ * Copies the flow via the Designer's own Copy endpoint — a complete, faithful
+ * clone created as an INACTIVE DRAFT. Publish it with publish-flow when ready.
+ * (Do NOT publish + activate a copy of a triggered production flow unless you
+ * intend it to fire.)
+ */
+async function runCopyFlow(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    var name = flags.name;
+    if (!sysId || !name) {
+        process.stderr.write("copy-flow: --sys-id <sys_id> and --name <name> are required\n");
+        return 1;
+    }
+    var params = { client: (0, client_1.createClient)({}), sourceSysId: sysId, newName: name };
+    if (flags.scope || flags.scopeSysId) {
+        params.scopeSysId = flags.scope || flags.scopeSysId;
+    }
+    var result = await (0, copyFlow_1.copyFlow)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write("Copied to '" + result.name + "' (sys_id " + result.sysId + ", scope " + result.scopeSysId
+        + ") — inactive draft. Publish with: dove-sn publish-flow --sys-id " + result.sysId + "\n");
+    return 0;
+}
+/**
+ * dove-sn test-flow:
+ *   --sys-id <sys_id>   Required. sys_hub_flow sys_id (flow or subflow).
+ *   --execute           Optional. Actually run it (default is validate-only).
+ *   --confirm           Required with --execute. A deliberate run-for-real gate.
+ *   --inputs <json>     Optional. JSON object of inputs (or --inputs-json <path>).
+ *   --json              Optional. Emit the structured TestFlowResult.
+ *
+ * Default (no --execute) is a safe pre-flight: published? readable? inputs match
+ * declared variables? --execute POSTs the FlowAPI runner endpoint (see
+ * resources/runFlow.md). Executing a flow can cause real side effects.
+ */
+async function runTestFlow(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    if (!sysId) {
+        process.stderr.write("test-flow: --sys-id <sys_id> is required\n");
+        return 1;
+    }
+    var inputs = {};
+    if (flags["inputs-json"]) {
+        inputs = JSON.parse(fs.readFileSync(flags["inputs-json"], "utf8"));
+    }
+    else if (flags.inputs) {
+        inputs = JSON.parse(flags.inputs);
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        sysId: sysId,
+        mode: flags.execute === "true" ? "execute" : "validate",
+        inputs: inputs,
+        confirm: flags.confirm === "true"
+    };
+    if (flags.runner) {
+        params.runnerPath = flags.runner;
+    }
+    var result = await (0, testFlow_1.testFlow)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write("[" + result.mode + "] ok=" + result.ok + "\n");
+    for (var i = 0; i < result.notes.length; i += 1) {
+        process.stdout.write("  " + result.notes[i] + "\n");
+    }
+    return result.ok ? 0 : 2;
+}
+/**
+ * dove-sn edit-flow:
+ *   --sys-id <sys_id>     Required. sys_hub_flow sys_id (flow or subflow).
+ *   --from-json <path>    Required. JSON EditFlowOps { rename?, description?, patchStepInputs? }.
+ *   --apply               Optional. Persist the edit (default is a dry-run diff).
+ *   --scope <sys_id>      Optional. sysparm_transaction_scope for the publish.
+ *   --update-set <sys_id> Required with --apply when ops include rename/description.
+ *   --json                Optional. Emit the structured EditFlowResult.
+ *
+ * Reads the model, applies the declarative edits, and (with --apply) persists them:
+ * rename/description via the update-set-aware record write, step inputs via a
+ * snapshot recompile. Without --apply it prints the would-be changes.
+ */
+async function runEditFlow(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    if (!sysId) {
+        process.stderr.write("edit-flow: --sys-id <sys_id> is required\n");
+        return 1;
+    }
+    if (!flags["from-json"]) {
+        process.stderr.write("edit-flow: --from-json <path> (EditFlowOps) is required\n");
+        return 1;
+    }
+    var ops = JSON.parse(fs.readFileSync(flags["from-json"], "utf8"));
+    var params = {
+        client: (0, client_1.createClient)({}),
+        sysId: sysId,
+        ops: ops,
+        apply: flags.apply === "true"
+    };
+    if (flags.scope || flags.scopeSysId) {
+        params.scopeSysId = flags.scope || flags.scopeSysId;
+    }
+    if (flags["update-set"] || flags.updateSetSysId) {
+        params.updateSetSysId = flags["update-set"] || flags.updateSetSysId;
+    }
+    var result = await (0, editFlow_1.editFlow)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write("[" + result.status + "] " + result.changes.length + " change(s)"
+        + (result.snapshotSysId ? " — snapshot " + result.snapshotSysId : "") + "\n");
+    for (var i = 0; i < result.changes.length; i += 1) {
+        process.stdout.write("  + " + result.changes[i] + "\n");
+    }
+    for (var w = 0; w < result.warnings.length; w += 1) {
+        process.stdout.write("  ! " + result.warnings[w] + "\n");
+    }
+    return 0;
+}
 async function runMcp(flags) {
     if (flags.smoke === "true") {
         await (0, server_1.runSmoke)();
@@ -324,6 +545,18 @@ function printHelp() {
         "                      [--view <v>] [--scope <s>] [--prune false] [--dry-run] [--json])\n" +
         "  build-flow         Author Custom Action Types and Subflows from a JSON spec\n" +
         "                     (--from-json <path> [--update-set <sys_id>] [--dry-run] [--skip-publish] [--json])\n" +
+        "  view-flow          Read a flow/subflow's compiled step graph (read-only)\n" +
+        "                     (--sys-id <sys_id> [--json] [--raw])\n" +
+        "  view-action        Read a Custom Action Type's model — inputs/outputs (read-only)\n" +
+        "                     (--sys-id <sys_id> --scope <sys_id> [--json] [--raw])\n" +
+        "  publish-flow       Compile a flow/subflow snapshot (write)\n" +
+        "                     (--sys-id <sys_id> [--scope <sys_id>] [--json])\n" +
+        "  copy-flow          Copy a flow/subflow (inactive draft) via the Designer Copy API\n" +
+        "                     (--sys-id <sys_id> --name <name> [--scope <sys_id>] [--json])\n" +
+        "  test-flow          Validate (default) or run a flow/subflow\n" +
+        "                     (--sys-id <sys_id> [--execute --confirm] [--inputs <json>] [--json])\n" +
+        "  edit-flow          Patch a flow/subflow (rename, description, step inputs)\n" +
+        "                     (--sys-id <sys_id> --from-json <ops.json> [--apply] [--update-set <sys_id>] [--scope <sys_id>] [--json])\n" +
         "  mcp                Run the MCP stdio server (--smoke lists tools and exits)\n");
 }
 async function main() {
@@ -335,6 +568,24 @@ async function main() {
     if (parsed.command === "build-flow") {
         return await runBuildFlowCmd(parsed.flags);
     }
+    if (parsed.command === "view-flow") {
+        return await runViewFlow(parsed.flags);
+    }
+    if (parsed.command === "view-action") {
+        return await runViewAction(parsed.flags);
+    }
+    if (parsed.command === "publish-flow") {
+        return await runPublishFlow(parsed.flags);
+    }
+    if (parsed.command === "copy-flow") {
+        return await runCopyFlow(parsed.flags);
+    }
+    if (parsed.command === "test-flow") {
+        return await runTestFlow(parsed.flags);
+    }
+    if (parsed.command === "edit-flow") {
+        return await runEditFlow(parsed.flags);
+    }
     if (parsed.command === "create-view") {
         await runCreateView(parsed.flags);
         return 0;

package/dist/flowDesigner/buildFlowOrchestrator.d.ts

@@ -29,6 +29,15 @@ export interface BuildFlowOptions {
     skipPublish?: boolean;
     /** Forwarded to triggerPublication. Useful for tight tests; defaults to its own 15s. */
     snapshotTimeoutMs?: number;
+    /**
+     * Steps fixture for publishing an action-type clone. The action-type model GET
+     * returns `steps: null`, so the real publisher (publishActionType) needs a
+     * steps array. When provided for kind="actionType", the orchestrator uses the
+     * real processflow publisher; without it, action-type publish falls back to
+     * the degraded triggerPublication. Ignored for subflows (publishFlow re-posts
+     * the full model, which already carries the instance graph).
+     */
+    steps?: Array<Record<string, any>>;
 }
 /**
  * Outcome categories. Maps directly to CLI exit codes:

package/dist/flowDesigner/buildFlowOrchestrator.js

@@ -14,6 +14,8 @@ const cloneSubflow_1 = require("./cloneSubflow");
 const cloneActionType_1 = require("./cloneActionType");
 const verifyArtifact_1 = require("./verifyArtifact");
 const triggerPublication_1 = require("./triggerPublication");
+const publishFlow_1 = require("./publishFlow");
+const publishActionType_1 = require("./publishActionType");
 const RX_SYS_ID = /^[0-9a-f]{32}$/;
 function unrecoverable(spec, stage, message) {
     return {
@@ -23,6 +25,50 @@ function unrecoverable(spec, stage, message) {
         error: { stage: stage, message: message },
     };
 }
+/**
+ * Publish a freshly cloned artifact. Tries the real processflow publisher first
+ * (publishFlow for subflows, publishActionType for action types when a steps
+ * fixture is supplied), and falls back to the degraded triggerPublication if the
+ * real path is unavailable or throws. Never throws — always returns a
+ * TriggerPublicationResult-compatible object so the caller's outcome mapping is
+ * unchanged (status "published" => done; anything else => needs-ui-publish).
+ */
+async function publishArtifact(client, spec, sysId, opts) {
+    try {
+        if (spec.kind === "subflow") {
+            var pf = await (0, publishFlow_1.publishFlow)({ client: client, sysId: sysId, scopeSysId: spec.newScope });
+            return { status: "published", snapshotSysId: pf.snapshotSysId, pushSucceeded: true };
+        }
+        // actionType: the real publisher needs a steps fixture (model GET => steps:null).
+        if (spec.kind === "actionType" && opts.steps && opts.steps.length > 0) {
+            var pa = await (0, publishActionType_1.publishActionType)({
+                client: client,
+                sysId: sysId,
+                scopeSysId: spec.newScope,
+                steps: opts.steps,
+            });
+            return { status: "published", snapshotSysId: pa.snapshotSysId, pushSucceeded: true };
+        }
+    }
+    catch (err) {
+        // Real publish failed — fall through to the degraded path below, which is
+        // engineered to surface a UI publish URL rather than throw.
+    }
+    try {
+        return await (0, triggerPublication_1.triggerPublication)({
+            client: client,
+            sysId: sysId,
+            kind: spec.kind,
+            updateSetSysId: spec.updateSetSysId,
+            snapshotTimeoutMs: opts.snapshotTimeoutMs,
+        });
+    }
+    catch (err) {
+        // triggerPublication is engineered to never throw on the happy path, but
+        // defensive: treat unexpected throws as needs-ui-publish.
+        return { status: "needs-ui-publish", pushSucceeded: false, uiPublishUrl: undefined };
+    }
+}
 function validateSpec(spec) {
     if (!spec || typeof spec !== "object")
         throw new Error("spec must be a JSON object");
@@ -163,27 +209,14 @@ async function runBuildFlow(client, rawSpec, opts = {}) {
             verify: verify,
         };
     }
-    // Phase 4: publication (best-effort, degraded mode until Phase 0 lands).
+    // Phase 4: publication. Try the real processflow publisher first (compiles
+    // the snapshot via the Designer's own Publish endpoint — basic auth, 2xx),
+    // and fall back to the degraded triggerPublication (status flip + poll, UI
+    // fallback) only if the real path throws. This is what replaces the long-
+    // standing "needs-ui-publish" default for the common case.
     var publish;
     if (!opts.skipPublish) {
-        try {
-            publish = await (0, triggerPublication_1.triggerPublication)({
-                client: client,
-                sysId: cloneResult.sysId,
-                kind: spec.kind,
-                updateSetSysId: spec.updateSetSysId,
-                snapshotTimeoutMs: opts.snapshotTimeoutMs,
-            });
-        }
-        catch (err) {
-            // triggerPublication is engineered to never throw on the happy path,
-            // but defensive: treat unexpected throws as needs-ui-publish.
-            publish = {
-                status: "needs-ui-publish",
-                pushSucceeded: false,
-                uiPublishUrl: undefined,
-            };
-        }
+        publish = await publishArtifact(client, spec, cloneResult.sysId, opts);
     }
     var artifact = {
         sysId: cloneResult.sysId,

package/dist/flowDesigner/copyFlow.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copy a Flow Designer flow or subflow — the Designer's own "Copy flow" action,
+ * headless.
+ *
+ * The Workflow Studio "Copy flow" button calls a clean REST endpoint (captured
+ * from a HAR, same family as the publish/snapshot endpoint), which works for the
+ * integration user with basic auth:
+ *
+ *   POST /api/now/processflow/flow/{sourceSysId}/copy?sysparm_transaction_scope={scope}
+ *     body: { name: "<new flow name>", scope: "<target scope sys_id>" }
+ *     -> 200, { result: { data: "<new flow sys_id>" } } — the copy is a complete,
+ *        faithful clone (trigger + all actions + variables + properties), created
+ *        as an INACTIVE DRAFT.
+ *
+ * This supersedes the record-graph clone (cloneSubflow), which can't work for
+ * the integration user: the design tables (sys_hub_flow_input/action_instance)
+ * ignore sysparm_query on the plain Table API, and the build-agent endpoint that
+ * honors the filter returns 401 without the Build Agent role — so a record-graph
+ * read either 401s or scans the whole table. The platform copy endpoint sidesteps
+ * all of that: ServiceNow assembles the copy server-side.
+ *
+ * The copy lands in `scopeSysId` (sysparm_transaction_scope) — which may differ
+ * from the source's scope — as an inactive draft. Publish it with publishFlow
+ * when ready. Do NOT publish + activate a copy of a triggered production flow
+ * unless you intend it to fire (e.g. a Send-SMS flow would duplicate sends).
+ */
+import type { ServiceNowClient } from "../client";
+export interface CopyFlowParams {
+    client: ServiceNowClient;
+    /** sys_id of the sys_hub_flow (flow or subflow) to copy. */
+    sourceSysId: string;
+    /** Name for the new copy. */
+    newName: string;
+    /**
+     * Target application scope sys_id (sysparm_transaction_scope) the copy is
+     * created in. Optional — defaults to the source flow's own scope (read first).
+     */
+    scopeSysId?: string;
+}
+export interface CopyFlowResult {
+    /** sys_id of the newly created copy. */
+    sysId: string;
+    /** Name of the copy (echoes newName). */
+    name: string;
+    /** The scope the copy was created in. */
+    scopeSysId: string;
+}
+export declare function copyFlow(params: CopyFlowParams): Promise<CopyFlowResult>;

package/dist/flowDesigner/copyFlow.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Copy a Flow Designer flow or subflow — the Designer's own "Copy flow" action,
+ * headless.
+ *
+ * The Workflow Studio "Copy flow" button calls a clean REST endpoint (captured
+ * from a HAR, same family as the publish/snapshot endpoint), which works for the
+ * integration user with basic auth:
+ *
+ *   POST /api/now/processflow/flow/{sourceSysId}/copy?sysparm_transaction_scope={scope}
+ *     body: { name: "<new flow name>", scope: "<target scope sys_id>" }
+ *     -> 200, { result: { data: "<new flow sys_id>" } } — the copy is a complete,
+ *        faithful clone (trigger + all actions + variables + properties), created
+ *        as an INACTIVE DRAFT.
+ *
+ * This supersedes the record-graph clone (cloneSubflow), which can't work for
+ * the integration user: the design tables (sys_hub_flow_input/action_instance)
+ * ignore sysparm_query on the plain Table API, and the build-agent endpoint that
+ * honors the filter returns 401 without the Build Agent role — so a record-graph
+ * read either 401s or scans the whole table. The platform copy endpoint sidesteps
+ * all of that: ServiceNow assembles the copy server-side.
+ *
+ * The copy lands in `scopeSysId` (sysparm_transaction_scope) — which may differ
+ * from the source's scope — as an inactive draft. Publish it with publishFlow
+ * when ready. Do NOT publish + activate a copy of a triggered production flow
+ * unless you intend it to fire (e.g. a Send-SMS flow would duplicate sends).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyFlow = copyFlow;
+/**
+ * Pull the new flow's sys_id from the copy response. The endpoint returns the
+ * new sys_id as a bare string under `result.data`; older/alternate shapes may
+ * nest it under a model object's `id`/`sys_id`.
+ */
+function extractCopiedSysId(resp) {
+    if (resp && typeof resp === "object" && resp.result && typeof resp.result === "object") {
+        var d = resp.result.data;
+        if (typeof d === "string" && d.length >= 32) {
+            return d;
+        }
+        if (d && typeof d === "object") {
+            if (typeof d.id === "string")
+                return d.id;
+            if (typeof d.sys_id === "string")
+                return d.sys_id;
+        }
+    }
+    if (resp && typeof resp === "object") {
+        if (typeof resp.id === "string")
+            return resp.id;
+        if (typeof resp.sys_id === "string")
+            return resp.sys_id;
+    }
+    return "";
+}
+function flowGetPath(sysId) {
+    return "/api/now/processflow/flow/" + encodeURIComponent(sysId);
+}
+function copyPath(sourceSysId, scopeSysId) {
+    return "/api/now/processflow/flow/" + encodeURIComponent(sourceSysId) + "/copy"
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+function unwrapModel(data) {
+    if (data && typeof data === "object" && data.result && typeof data.result === "object") {
+        if (data.result.data && typeof data.result.data === "object") {
+            return data.result.data;
+        }
+        return data.result;
+    }
+    if (data && typeof data === "object" && data.data && typeof data.data === "object") {
+        return data.data;
+    }
+    return data;
+}
+async function copyFlow(params) {
+    var client = params.client;
+    var sourceSysId = params.sourceSysId;
+    if (!sourceSysId) {
+        throw new Error("copyFlow: sourceSysId is required.");
+    }
+    if (typeof params.newName !== "string" || params.newName.trim().length === 0) {
+        throw new Error("copyFlow: newName is required.");
+    }
+    // Resolve the target scope: explicit param, else the source flow's own scope.
+    var scopeSysId = params.scopeSysId;
+    if (!scopeSysId) {
+        var src = unwrapModel(await client.now.get(flowGetPath(sourceSysId)));
+        if (src && typeof src.scope === "string") {
+            scopeSysId = src.scope;
+        }
+    }
+    if (!scopeSysId) {
+        throw new Error("copyFlow: scopeSysId is required and the source flow carried no `scope` to default from.");
+    }
+    var resp = await client.now.post(copyPath(sourceSysId, scopeSysId), { name: params.newName, scope: scopeSysId });
+    var newSysId = extractCopiedSysId(resp);
+    if (!newSysId) {
+        throw new Error("copyFlow: the copy succeeded but no new flow sys_id was found in the response: "
+            + JSON.stringify(resp).substring(0, 300));
+    }
+    return {
+        sysId: newSysId,
+        name: params.newName,
+        scopeSysId: scopeSysId
+    };
+}