@tenonhq/dovetail-servicenow 0.0.6 → 0.0.7

package/README.md

@@ -212,6 +212,53 @@ npx dove-sn mcp           # run the stdio server (wire into .mcp.json)
 This server is separate from `@tenonhq/dovetail-mcp` (the read-only cross-system
 aggregator) — `dovetail-servicenow`'s server is the ServiceNow **write** surface.
 
+## Publishing a Custom Action Type
+
+`publishActionType` compiles the `sys_hub_flow_snapshot` for a Custom Action Type
+— the step that makes it draggable in the Flow Designer palette. This replays the
+Designer's **Publish** button, which is a plain REST call that **works with basic
+auth** (no session cookie, CSRF token, or `sn_build_agent` role):
+
+```
+GET  /api/now/processflow/action/action_types/{sysId}?sysparm_transaction_scope={scope}
+       -> 200, the full action-type model EXCEPT `steps` (always returns null)
+POST /api/now/processflow/action/action_types/{sysId}/snapshot?sysparm_transaction_scope={scope}
+       body = the model with a `steps` array grafted in
+       -> 201 Created (compiles the snapshot; also persists step input values
+          back to sys_variable_value)
+```
+
+This is the **real** snapshot compiler and supersedes `triggerPublication` for
+action types — that function ships in degraded mode (it only sets
+`status="published"` and polls, because the snapshot trigger was unknown when it
+was written). `triggerPublication` is retained for back-compat and the subflow path.
+
+```ts
+import { createClient, publishActionType } from "@tenonhq/dovetail-servicenow";
+
+var client = createClient({});
+var result = await publishActionType({
+  client: client,
+  sysId: "60e6743e33814bd07b18bc534d5c7b9e",      // sys_hub_action_type_definition
+  scopeSysId: "cd61acbbc3c85a1085b196c4e40131bd",  // sysparm_transaction_scope
+  steps: require("./fixtures/my-action.steps.json") // see caveat below
+});
+// { status: "published", httpStatus: 201, snapshotSysId?: "..." }
+```
+
+### Steps-fixture caveat (required)
+
+The GET returns **`steps: null`** even for an already-published action — the
+Designer assembles `steps` client-side from the step records. So to publish you
+**must supply a `steps` fixture** via `params.steps`. Each step's `action` field
+is remapped to the target `sysId` automatically. If you omit `steps` and the
+fetched model has no usable `steps` array, `publishActionType` throws with a clear
+message. For a faithful clone, capture the source action's `steps` from a HAR of
+the Publish call and store it as a fixture beside your driver.
+
+Full recipe and the 6-record action-type graph:
+`docs/servicenow-flow-designer-headless-authoring.md` in the CTO repo.
+
 ## Roadmap
 
 The same query-to-diff pattern will continue across the rest of the

package/dist/client.d.ts

@@ -102,5 +102,16 @@ export interface ServiceNowClient {
             [k: string]: any;
         }>;
     };
+    now: {
+        /**
+         * GET an arbitrary native ServiceNow REST path (e.g. /api/now/processflow/...).
+         * Basic auth, same credentials/retry/throttle as the rest of the client.
+         * Use for endpoints that aren't the Table API or the Dovetail Scripted REST API
+         * — currently the Flow Designer processflow endpoints. Returns the raw response body.
+         */
+        get: <T = any>(path: string) => Promise<T>;
+        /** POST an arbitrary native ServiceNow REST path with a JSON body. See `get`. */
+        post: <T = any>(path: string, body: any) => Promise<T>;
+    };
 }
 export declare function createClient(config?: ServiceNowClientConfig): ServiceNowClient;

package/dist/client.js

@@ -296,6 +296,14 @@ function createClient(config = {}) {
                 var data = await dovetailRequest("POST", "deleteRecord", { table: params.table, sys_id: params.sys_id }, null, "claude.deleteRecord(" + params.table + ")");
                 return data.result || data;
             }
+        },
+        now: {
+            get: function (path) {
+                return request({ method: "GET", url: path }, "now.get(" + path + ")");
+            },
+            post: function (path, body) {
+                return request({ method: "POST", url: path, data: body }, "now.post(" + path + ")");
+            }
         }
     };
 }

package/dist/flowDesigner/index.d.ts

@@ -14,6 +14,8 @@ export { cloneActionType } from "./cloneActionType";
 export type { CloneActionTypeParams, CloneActionTypeResult } from "./cloneActionType";
 export { triggerPublication } from "./triggerPublication";
 export type { TriggerPublicationParams, TriggerPublicationResult } from "./triggerPublication";
+export { publishActionType } from "./publishActionType";
+export type { PublishActionTypeParams, PublishActionTypeResult } from "./publishActionType";
 export { generateSysId, stripSystemFields, applyScope, assertSysId, SYSTEM_FIELDS_TO_STRIP, } from "./shape";
 export { topoSort, executeWritePlan, WriteOrderError } from "./writeOrder";
 export type { WriteOp, WriteOpResult } from "./writeOrder";

package/dist/flowDesigner/index.js

@@ -6,7 +6,7 @@
  * functions land in Phase 1.C/D.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
 var listTemplates_1 = require("./listTemplates");
 Object.defineProperty(exports, "listTemplates", { enumerable: true, get: function () { return listTemplates_1.listTemplates; } });
 var verifyArtifact_1 = require("./verifyArtifact");
@@ -17,6 +17,8 @@ var cloneActionType_1 = require("./cloneActionType");
 Object.defineProperty(exports, "cloneActionType", { enumerable: true, get: function () { return cloneActionType_1.cloneActionType; } });
 var triggerPublication_1 = require("./triggerPublication");
 Object.defineProperty(exports, "triggerPublication", { enumerable: true, get: function () { return triggerPublication_1.triggerPublication; } });
+var publishActionType_1 = require("./publishActionType");
+Object.defineProperty(exports, "publishActionType", { enumerable: true, get: function () { return publishActionType_1.publishActionType; } });
 var shape_1 = require("./shape");
 Object.defineProperty(exports, "generateSysId", { enumerable: true, get: function () { return shape_1.generateSysId; } });
 Object.defineProperty(exports, "stripSystemFields", { enumerable: true, get: function () { return shape_1.stripSystemFields; } });

package/dist/flowDesigner/publishActionType.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Publish a Custom Action Type — the real Flow Designer snapshot compiler.
+ *
+ * This is the working path that supersedes the degraded `triggerPublication`
+ * (which only set status="published" and polled, with a comment admitting the
+ * real snapshot trigger was an unknown "Phase 0 spike"). The Designer's
+ * **Publish** button is a plain REST call that works with basic auth — no
+ * session token, CSRF, or sn_build_agent role:
+ *
+ *   GET  /api/now/processflow/action/action_types/{sysId}?sysparm_transaction_scope={scope}
+ *          -> 200, the full action-type model EXCEPT `steps` (which comes back null)
+ *   POST /api/now/processflow/action/action_types/{sysId}/snapshot?sysparm_transaction_scope={scope}
+ *          body = the model with a `steps` array grafted in
+ *          -> 201 Created (compiles sys_hub_flow_snapshot; sets latest/master_snapshot;
+ *             also persists step input values back to sys_variable_value)
+ *
+ * STEPS-FIXTURE CAVEAT: the GET returns `steps: null` even for a published
+ * action — the Designer assembles `steps` client-side from the step records.
+ * So a `steps` fixture is required to publish. Supply it via `params.steps`
+ * (each step's `action` is remapped to `sysId`). If the model already carries
+ * a non-empty `steps` array, that is used instead. If neither is available,
+ * this throws — the caller must provide a steps fixture.
+ *
+ * Full write-up: docs/servicenow-flow-designer-headless-authoring.md.
+ */
+import type { ServiceNowClient } from "../client";
+export interface PublishActionTypeParams {
+    client: ServiceNowClient;
+    /** sys_id of the sys_hub_action_type_definition to publish. */
+    sysId: string;
+    /** Application scope sys_id, passed as sysparm_transaction_scope. */
+    scopeSysId: string;
+    /**
+     * The `steps` array to graft onto the model. Required when the GET returns
+     * `steps: null` (the normal case). Each step's `action` is remapped to `sysId`.
+     * Omit only when the fetched model already carries a non-empty `steps` array.
+     */
+    steps?: Array<Record<string, any>>;
+}
+export interface PublishActionTypeResult {
+    status: "published";
+    /** HTTP status of the snapshot POST (201 on success). */
+    httpStatus: number;
+    /** sys_id of the compiled snapshot, when the response surfaces it. */
+    snapshotSysId?: string;
+}
+export declare function publishActionType(params: PublishActionTypeParams): Promise<PublishActionTypeResult>;

package/dist/flowDesigner/publishActionType.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Publish a Custom Action Type — the real Flow Designer snapshot compiler.
+ *
+ * This is the working path that supersedes the degraded `triggerPublication`
+ * (which only set status="published" and polled, with a comment admitting the
+ * real snapshot trigger was an unknown "Phase 0 spike"). The Designer's
+ * **Publish** button is a plain REST call that works with basic auth — no
+ * session token, CSRF, or sn_build_agent role:
+ *
+ *   GET  /api/now/processflow/action/action_types/{sysId}?sysparm_transaction_scope={scope}
+ *          -> 200, the full action-type model EXCEPT `steps` (which comes back null)
+ *   POST /api/now/processflow/action/action_types/{sysId}/snapshot?sysparm_transaction_scope={scope}
+ *          body = the model with a `steps` array grafted in
+ *          -> 201 Created (compiles sys_hub_flow_snapshot; sets latest/master_snapshot;
+ *             also persists step input values back to sys_variable_value)
+ *
+ * STEPS-FIXTURE CAVEAT: the GET returns `steps: null` even for a published
+ * action — the Designer assembles `steps` client-side from the step records.
+ * So a `steps` fixture is required to publish. Supply it via `params.steps`
+ * (each step's `action` is remapped to `sysId`). If the model already carries
+ * a non-empty `steps` array, that is used instead. If neither is available,
+ * this throws — the caller must provide a steps fixture.
+ *
+ * Full write-up: docs/servicenow-flow-designer-headless-authoring.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishActionType = publishActionType;
+function actionTypePath(sysId, scopeSysId, suffix) {
+    return "/api/now/processflow/action/action_types/" + encodeURIComponent(sysId)
+        + suffix
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+/**
+ * Unwrap the various response envelopes ServiceNow uses. The processflow
+ * endpoints have been observed returning the model both bare and under
+ * `result`; normalize to the model object.
+ */
+function unwrap(data) {
+    if (data && typeof data === "object" && data.result && typeof data.result === "object") {
+        return data.result;
+    }
+    return data;
+}
+async function publishActionType(params) {
+    var client = params.client;
+    var sysId = params.sysId;
+    var scopeSysId = params.scopeSysId;
+    if (!sysId) {
+        throw new Error("publishActionType: sysId is required.");
+    }
+    if (!scopeSysId) {
+        throw new Error("publishActionType: scopeSysId is required (sysparm_transaction_scope).");
+    }
+    // 1. GET the model. Returns everything except `steps` (always null).
+    var getResp = await client.now.get(actionTypePath(sysId, scopeSysId, ""));
+    var model = unwrap(getResp);
+    if (!model || typeof model !== "object") {
+        throw new Error("publishActionType: unexpected GET response for action type " + sysId
+            + " — expected a model object, got: " + JSON.stringify(getResp).substring(0, 300));
+    }
+    // 2. Resolve the steps to graft. Caller-supplied steps win; otherwise reuse
+    //    a non-empty steps array already on the model. The GET returns steps:null,
+    //    so in practice a steps fixture must be supplied — fail loudly if absent.
+    var steps = null;
+    if (params.steps && params.steps.length > 0) {
+        steps = params.steps.map(function (step) {
+            var copy = {};
+            for (var key in step) {
+                if (Object.prototype.hasOwnProperty.call(step, key)) {
+                    copy[key] = step[key];
+                }
+            }
+            copy.action = sysId;
+            return copy;
+        });
+    }
+    else if (model.steps && Array.isArray(model.steps) && model.steps.length > 0) {
+        steps = model.steps;
+    }
+    if (!steps || steps.length === 0) {
+        throw new Error("publishActionType: no steps to publish for action type " + sysId + ". "
+            + "The GET returns steps:null, so you must supply a steps fixture via params.steps. "
+            + "See docs/servicenow-flow-designer-headless-authoring.md.");
+    }
+    model.steps = steps;
+    // 3. POST the grafted model to /snapshot — compiles the snapshot (201).
+    var snapResp = await client.now.post(actionTypePath(sysId, scopeSysId, "/snapshot"), model);
+    var snapBody = unwrap(snapResp);
+    // request() throws on any non-2xx, so reaching here means a 2xx (201 in practice).
+    var snapshotSysId;
+    if (snapBody && typeof snapBody === "object") {
+        // The snapshot ref is surfaced under different keys and as either a bare
+        // sys_id string or a record object — coerce whichever is present to a string.
+        var snap = snapBody.latest_snapshot || snapBody.master_snapshot || snapBody.snapshot;
+        if (snap && typeof snap === "object") {
+            snapshotSysId = typeof snap.sys_id === "string" ? snap.sys_id : undefined;
+        }
+        else if (typeof snap === "string") {
+            snapshotSysId = snap;
+        }
+    }
+    return {
+        status: "published",
+        httpStatus: 201,
+        snapshotSysId: snapshotSysId
+    };
+}

package/dist/flowDesigner/triggerPublication.d.ts

@@ -1,10 +1,18 @@
 /**
  * Best-effort publication trigger for a Subflow or Custom Action Type.
  *
- * Ships in DEGRADED MODE for Phase 1 — the deterministic field/value combo
- * that compels ServiceNow to compile sys_hub_flow_snapshot is the subject
- * of Phase 0's gating spike and is not yet known. Until that lands, this
- * function:
+ * DEPRECATED FOR ACTION TYPES — the real snapshot compiler is now known and
+ * shipped as `publishActionType` (see ./publishActionType.ts). That function
+ * replays the Flow Designer Publish call (GET model → graft `steps` → POST to
+ * /snapshot → 201) over basic auth and actually compiles sys_hub_flow_snapshot,
+ * which is what makes a Custom Action Type draggable in the palette. Prefer
+ * `publishActionType` for action types. `triggerPublication` is retained for
+ * back-compat and for the subflow path, which still uses the degraded trigger
+ * below.
+ *
+ * Ships in DEGRADED MODE — the deterministic field/value combo that compels
+ * ServiceNow to compile sys_hub_flow_snapshot was, when this was written, an
+ * unknown "Phase 0 spike". This function:
  *
  *   1. Sets `status="published"` on the parent record via pushWithUpdateSet
  *      (this is the most likely single-field trigger; harmless if it isn't).

package/dist/flowDesigner/triggerPublication.js

@@ -2,10 +2,18 @@
 /**
  * Best-effort publication trigger for a Subflow or Custom Action Type.
  *
- * Ships in DEGRADED MODE for Phase 1 — the deterministic field/value combo
- * that compels ServiceNow to compile sys_hub_flow_snapshot is the subject
- * of Phase 0's gating spike and is not yet known. Until that lands, this
- * function:
+ * DEPRECATED FOR ACTION TYPES — the real snapshot compiler is now known and
+ * shipped as `publishActionType` (see ./publishActionType.ts). That function
+ * replays the Flow Designer Publish call (GET model → graft `steps` → POST to
+ * /snapshot → 201) over basic auth and actually compiles sys_hub_flow_snapshot,
+ * which is what makes a Custom Action Type draggable in the palette. Prefer
+ * `publishActionType` for action types. `triggerPublication` is retained for
+ * back-compat and for the subflow path, which still uses the degraded trigger
+ * below.
+ *
+ * Ships in DEGRADED MODE — the deterministic field/value combo that compels
+ * ServiceNow to compile sys_hub_flow_snapshot was, when this was written, an
+ * unknown "Phase 0 spike". This function:
  *
  *   1. Sets `status="published"` on the parent record via pushWithUpdateSet
  *      (this is the most likely single-field trigger; harmless if it isn't).

package/dist/index.d.ts

@@ -14,6 +14,6 @@ export { setFormLayout } from "./layout/formLayout";
 export { setRelatedLists } from "./layout/relatedLists";
 export { formatLayoutResult, formatCreateViewResult } from "./layout/formatter";
 export { sincPlugin } from "./plugin";
-export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
-export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, WriteOp, WriteOpResult } from "./flowDesigner";
+export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
+export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, WriteOp, WriteOpResult } from "./flowDesigner";
 export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, DictionaryRecord, UpdateSetRecord, LayoutAction, LayoutRecordResult, LayoutResult, CreateViewParams, CreateViewResult, FormSectionSpec, SetFormLayoutParams, SetListLayoutParams, SetRelatedListsParams } from "./types";

package/dist/index.js

@@ -6,7 +6,7 @@
  * REST API so every change lands in the target update set and scope.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 var choices_1 = require("./choices");
@@ -32,6 +32,7 @@ Object.defineProperty(exports, "verifyArtifact", { enumerable: true, get: functi
 Object.defineProperty(exports, "cloneSubflow", { enumerable: true, get: function () { return flowDesigner_1.cloneSubflow; } });
 Object.defineProperty(exports, "cloneActionType", { enumerable: true, get: function () { return flowDesigner_1.cloneActionType; } });
 Object.defineProperty(exports, "triggerPublication", { enumerable: true, get: function () { return flowDesigner_1.triggerPublication; } });
+Object.defineProperty(exports, "publishActionType", { enumerable: true, get: function () { return flowDesigner_1.publishActionType; } });
 Object.defineProperty(exports, "generateSysId", { enumerable: true, get: function () { return flowDesigner_1.generateSysId; } });
 Object.defineProperty(exports, "topoSort", { enumerable: true, get: function () { return flowDesigner_1.topoSort; } });
 Object.defineProperty(exports, "executeWritePlan", { enumerable: true, get: function () { return flowDesigner_1.executeWritePlan; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-servicenow",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "engines": {
     "node": ">=22"
   },