@sonisoft/now-sdk-ext-core 6.6.3 → 6.8.0

package/README.md

@@ -926,6 +926,12 @@ npm test
 npm pack
 ```
 
+## ServiceNow SDK upgrades
+
+New `@servicenow/sdk` releases are rolled through sn-credstore, core, the CLI and the MCP
+server by a scheduled routine. Its runbook and scripts (`scripts/sdk-watch/`) are described in
+[docs/SDK_UPGRADE_ROUTINE.md](docs/SDK_UPGRADE_ROUTINE.md).
+
 ## 📝 License
 
 MIT License - see LICENSE file for details

package/dist/comm/http/FormHtmlParser.d.ts

@@ -0,0 +1,34 @@
+import type { FormTransportLoadOptions, FormTransportSnapshot } from "./internal/FormTransportModels.js";
+/**
+ * Parse a form page.
+ *
+ * @param html The form page
+ * @param table The table the form belongs to
+ * @throws Error when the page is not a form for `table` (e.g. a login page or an error page)
+ */
+export declare function parseFormHtml(html: string, table: string, options?: FormTransportLoadOptions): FormTransportSnapshot;
+/**
+ * Split `<table>.<varField>.var__m_<model>.<element>` into its parts.
+ * Returns undefined for ordinary (possibly dot-walked) field names.
+ */
+export declare function splitVariableName(name: string, table: string): {
+    field: string;
+    model: string;
+    element: string;
+} | undefined;
+/**
+ * Messages shown on a classic UI page, split by severity.
+ */
+export declare function parseFormMessages(html: string): {
+    errors: string[];
+    info: string[];
+};
+/**
+ * Read the action and sys_id that `modal_dialog_form_response.do` reports after a
+ * successful form submit. Returns undefined when the page is anything else — which is
+ * how a rejected submit (re-rendered form, error page) shows up.
+ */
+export declare function parseFormResponse(html: string): {
+    action: string;
+    sysId: string;
+} | undefined;

package/dist/comm/http/FormHtmlParser.js

@@ -0,0 +1,227 @@
+import { Parser } from "htmlparser2";
+/**
+ * Parses classic UI form pages (`/<table>.do`) into a {@link FormSnapshot}.
+ *
+ * Kept separate from the writer so it can be exercised against fixture HTML. Only the
+ * controls a browser would submit for the record are kept: `<table>.*` inputs,
+ * textareas and selects, plus the hidden tokens a submit must echo back. Display-only
+ * mirrors (`sys_display.*`, `sys_select.*`, `sys_original.*`) are ignored — posting a
+ * `sys_select` value is how the UI ends up storing a reference it only displayed.
+ */
+const TOKENS = new Set([
+    "sys_uniqueValue", "sysparm_encoded_record", "sys_modCount", "onLoad_sys_updated_on", "sys_row",
+]);
+/**
+ * Parse a form page.
+ *
+ * @param html The form page
+ * @param table The table the form belongs to
+ * @throws Error when the page is not a form for `table` (e.g. a login page or an error page)
+ */
+export function parseFormHtml(html, table, options = {}) {
+    const renderedInputs = {};
+    const pageTokens = [];
+    const prefix = `${table}.`;
+    const tokens = {};
+    const actions = {};
+    const controls = new Map();
+    const types = new Map();
+    const mandatory = new Set();
+    let target;
+    let textarea = null;
+    let select = null;
+    let option = null;
+    const keep = (name) => !!name && name.startsWith(prefix) && !name.endsWith(".ui_policy_sensitive");
+    const parser = new Parser({
+        onopentag(tag, attrs) {
+            switch (tag) {
+                case "input": {
+                    const name = attrs.name;
+                    if (name === "sys_target")
+                        target = attrs.value;
+                    if (TOKENS.has(name))
+                        tokens[name] = attrs.value ?? "";
+                    if (options.captureRenderedInputs && name)
+                        renderedInputs[name] = attrs.value ?? "";
+                    if (options.tokenSource === "page" && name === "sysparm_ck")
+                        pageTokens.push(attrs.value ?? "");
+                    if (!keep(name))
+                        return;
+                    const type = (attrs.type || "text").toLowerCase();
+                    if (type === "button" || type === "submit" || type === "image")
+                        return;
+                    if ((type === "checkbox" || type === "radio") && attrs.checked === undefined)
+                        return;
+                    controls.set(name, { name, value: attrs.value ?? "" });
+                    return;
+                }
+                case "textarea":
+                    if (keep(attrs.name) || (options.captureRenderedInputs && attrs.name))
+                        textarea = { name: attrs.name, text: "" };
+                    return;
+                case "select":
+                    if (keep(attrs.name) || (options.captureRenderedInputs && attrs.name))
+                        select = { name: attrs.name, options: [] };
+                    return;
+                case "option":
+                    if (select)
+                        option = { value: attrs.value, label: "", selected: attrs.selected !== undefined };
+                    return;
+                case "button":
+                    if (attrs["data-action-name"] && attrs.gsft_id)
+                        actions[attrs["data-action-name"]] = attrs.gsft_id;
+                    return;
+                case "div":
+                    if (attrs["data-type"] === "label" && attrs.id?.startsWith("label.") && attrs.type) {
+                        types.set(attrs.id.slice("label.".length), attrs.type);
+                    }
+                    return;
+                case "span":
+                    if (attrs.id?.startsWith("status.") && attrs.mandatory === "true") {
+                        mandatory.add(attrs.id.slice("status.".length));
+                    }
+                    return;
+            }
+        },
+        ontext(text) {
+            if (textarea)
+                textarea.text += text;
+            if (option)
+                option.label += text;
+        },
+        onclosetag(tag) {
+            if (tag === "textarea" && textarea) {
+                if (options.captureRenderedInputs)
+                    renderedInputs[textarea.name] = textarea.text;
+                if (keep(textarea.name))
+                    controls.set(textarea.name, { name: textarea.name, value: textarea.text });
+                textarea = null;
+            }
+            else if (tag === "option" && select && option) {
+                select.options.push({ value: option.value ?? option.label, label: option.label.trim(), selected: option.selected });
+                option = null;
+            }
+            else if (tag === "select" && select) {
+                const chosen = select.options.find(o => o.selected) ?? select.options[0];
+                if (options.captureRenderedInputs)
+                    renderedInputs[select.name] = chosen?.value ?? "";
+                if (keep(select.name))
+                    controls.set(select.name, {
+                        name: select.name,
+                        value: chosen ? chosen.value : "",
+                        choices: select.options.map(o => ({ value: o.value, label: o.label })),
+                    });
+                select = null;
+            }
+        },
+    }, { decodeEntities: true, lowerCaseAttributeNames: true, lowerCaseTags: true });
+    parser.write(html);
+    parser.end();
+    if (target !== table || tokens.sys_uniqueValue === undefined) {
+        throw new Error(`The response was not a ${table} form (it may be a login or error page)`);
+    }
+    const fields = {};
+    const variables = {};
+    for (const control of controls.values()) {
+        const type = types.get(control.name);
+        if (type)
+            control.type = type;
+        if (mandatory.has(control.name))
+            control.mandatory = true;
+        const variable = splitVariableName(control.name, table);
+        // Keyed by column and element: a form can show the same element on two glide_var columns.
+        if (variable)
+            variables[`${variable.field}.${variable.element}`] = { ...control, ...variable };
+        else
+            fields[control.name] = control;
+    }
+    if (options.tokenSource === "page" && (!pageTokens.length || pageTokens.some(token => !token || token !== pageTokens[0]))) {
+        throw new Error("csrf_token_unavailable");
+    }
+    const sysId = tokens.sys_uniqueValue;
+    return {
+        table,
+        sysId,
+        isNewRecord: tokens.sys_row === "-1",
+        encodedRecord: tokens.sysparm_encoded_record ?? "",
+        modCount: tokens.sys_modCount ?? "",
+        updatedOn: tokens.onLoad_sys_updated_on ?? "",
+        actions,
+        fields,
+        variables,
+        ...(options.captureRenderedInputs ? { renderedInputs } : {}),
+        ...(options.tokenSource === "page" ? { pageToken: pageTokens[0] } : {}),
+    };
+}
+/**
+ * Split `<table>.<varField>.var__m_<model>.<element>` into its parts.
+ * Returns undefined for ordinary (possibly dot-walked) field names.
+ */
+export function splitVariableName(name, table) {
+    const parts = name.slice(table.length + 1).split(".");
+    if (parts.length !== 3 || !parts[1].startsWith("var__m_"))
+        return undefined;
+    return { field: parts[0], model: parts[1], element: parts[2] };
+}
+/**
+ * Messages shown on a classic UI page, split by severity.
+ */
+export function parseFormMessages(html) {
+    const errors = [];
+    const info = [];
+    // Message containers do not nest, so the most recent one decides the severity.
+    let current = null;
+    let text = null;
+    const parser = new Parser({
+        onopentag(tag, attrs) {
+            const cls = attrs.class ?? "";
+            if (tag === "div" && /\boutputmsg\b/.test(cls)) {
+                current = /outputmsg_error|notification-error/.test(cls) ? "error" : "info";
+            }
+            if (current && tag === "span" && /\boutputmsg_text\b/.test(cls))
+                text = "";
+        },
+        ontext(t) {
+            if (text !== null)
+                text += t;
+        },
+        onclosetag(tag) {
+            if (tag === "span" && text !== null) {
+                const message = text.replace(/\s+/g, " ").trim();
+                if (message)
+                    (current === "error" ? errors : info).push(message);
+                text = null;
+            }
+        },
+    }, { decodeEntities: true, lowerCaseAttributeNames: true });
+    parser.write(html);
+    parser.end();
+    return { errors, info };
+}
+/**
+ * Read the action and sys_id that `modal_dialog_form_response.do` reports after a
+ * successful form submit. Returns undefined when the page is anything else — which is
+ * how a rejected submit (re-rendered form, error page) shows up.
+ */
+export function parseFormResponse(html) {
+    let inResponse = false;
+    const values = {};
+    const parser = new Parser({
+        onopentag(tag, attrs) {
+            if (tag === "span" && /\bmodal_dialog_form_response\b/.test(attrs.class ?? ""))
+                inResponse = true;
+            else if (inResponse && tag === "input" && attrs.name)
+                values[attrs.name] = attrs.value ?? "";
+        },
+        onclosetag(tag) {
+            if (tag === "span")
+                inResponse = false;
+        },
+    }, { decodeEntities: true, lowerCaseAttributeNames: true });
+    parser.write(html);
+    parser.end();
+    if (!values.action || !values.sysid)
+        return undefined;
+    return { action: values.action, sysId: values.sysid };
+}
+//# sourceMappingURL=FormHtmlParser.js.map

package/dist/comm/http/FormHtmlParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormHtmlParser.js","sourceRoot":"","sources":["../../../src/comm/http/FormHtmlParser.ts"],"names":[],"mappings":"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"}

package/dist/comm/http/FormRecordModels.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Models for {@link FormRecordWriter}: writing a record through the classic UI form
+ * (`/<table>.do`) the way a browser does.
+ */
+/**
+ * A duration accepted for a `glide_duration` form field. Numbers are seconds.
+ */
+export interface FormDurationInput {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}
+/**
+ * A value for a form field or a variable.
+ *
+ * - `boolean` is posted as `true`/`false`
+ * - an array is posted comma-separated (glide_list)
+ * - a `number` or {@link FormDurationInput} on a `glide_duration` field is posted as `D HH:MM:SS`
+ * - `null` posts an empty value
+ * - anything else is posted as its string form, exactly as given
+ */
+export type FormValueInput = string | number | boolean | null | string[] | FormDurationInput;
+/**
+ * One control on a loaded form.
+ */
+export interface FormControl {
+    /** The posted parameter name, e.g. `wf_activity.name` or `wf_activity.vars.var__m_<id>.script` */
+    name: string;
+    /** The value the form would post if left untouched */
+    value: string;
+    /** Field type from the form label (e.g. `choice`, `boolean`, `glide_duration`, `reference`), when the form declares one */
+    type?: string;
+    /** Whether the form marks the field mandatory */
+    mandatory?: boolean;
+    /** Options offered by a choice field, in form order */
+    choices?: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+/**
+ * A variable (glide_var) element exposed by a loaded form.
+ */
+export interface FormVariableControl extends FormControl {
+    /** The glide_var column on the record, e.g. `vars` or `inputs` */
+    field: string;
+    /** The variable model table name, e.g. `var__m_3961a1da0a0a0b5c00ecd84822f70d85` */
+    model: string;
+    /** The variable element name, e.g. `timer_type` */
+    element: string;
+}
+/**
+ * A parsed classic form: the tokens a submit must echo back plus every control.
+ */
+export interface FormSnapshot {
+    /** Table the form belongs to */
+    table: string;
+    /** sys_id the form will insert as (pre-assigned for new records) or the record being edited */
+    sysId: string;
+    /** True when the form was loaded for a new record (`sys_id=-1`) */
+    isNewRecord: boolean;
+    /**
+     * Opaque, signed form-load state. Carries values that are not form inputs, such as
+     * fields set through `sysparm_query` at load time. Required for the submit to apply
+     * variables.
+     */
+    encodedRecord: string;
+    /** `sys_modCount` of the record when the form was loaded */
+    modCount: string;
+    /** `onLoad_sys_updated_on` of the record when the form was loaded */
+    updatedOn: string;
+    /** Form-action UI action sys_ids keyed by action name (e.g. `sysverb_insert`, `sysverb_update`) */
+    actions: Record<string, string>;
+    /** Ordinary field controls, keyed by posted name */
+    fields: Record<string, FormControl>;
+    /**
+     * Variable controls, keyed by `<variable column>.<element>` (e.g. `vars.timer_type`): a
+     * form can show the same element on more than one glide_var column.
+     */
+    variables: Record<string, FormVariableControl>;
+}
+/**
+ * Options for loading a form.
+ */
+export interface FormLoadOptions {
+    /** Form view (`sysparm_view`). Defaults to the table's default view. */
+    view?: string;
+    /**
+     * Encoded query applied to a new record at load time (`sysparm_query`), e.g.
+     * `workflow_version=<id>^activity_definition=<id>`. Fields set this way travel in the
+     * encoded record, so they apply even when they are not on the form.
+     */
+    initialQuery?: string;
+}
+/**
+ * Options for inserting or updating a record through its form.
+ */
+export interface FormWriteOptions extends FormLoadOptions {
+    /** Field values keyed by column name (e.g. `{ name: 'Wait 1 day' }`). Dot-walked names are not supported. */
+    fields?: Record<string, FormValueInput>;
+    /** Variable values keyed by element name. Unknown elements are rejected. */
+    variables?: Record<string, FormValueInput>;
+    /**
+     * Which glide_var column the variables belong to, when the form exposes more than
+     * one (e.g. ATF step `inputs` vs `outputs`). Defaults to the only one present.
+     */
+    variableField?: string;
+}
+/**
+ * Result of a form write.
+ */
+export interface FormWriteResult {
+    /** sys_id of the inserted or updated record */
+    sysId: string;
+    /** The form action that ran */
+    action: 'sysverb_insert' | 'sysverb_update';
+    /** Info messages the instance returned with the response */
+    messages: string[];
+}

package/dist/comm/http/FormRecordModels.js

@@ -0,0 +1,6 @@
+/**
+ * Models for {@link FormRecordWriter}: writing a record through the classic UI form
+ * (`/<table>.do`) the way a browser does.
+ */
+export {};
+//# sourceMappingURL=FormRecordModels.js.map

package/dist/comm/http/FormRecordModels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormRecordModels.js","sourceRoot":"","sources":["../../../src/comm/http/FormRecordModels.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/comm/http/FormRecordWriter.d.ts

@@ -0,0 +1,99 @@
+import type { FormTransportLoadOptions, FormTransportSubmitOptions, FormTransportSnapshot, FormTransportResult } from "./internal/FormTransportModels.js";
+import { ServiceNowInstance } from "../../sn/ServiceNowInstance.js";
+import { FormControl, FormDurationInput, FormLoadOptions, FormSnapshot, FormValueInput, FormWriteOptions, FormWriteResult } from "./FormRecordModels.js";
+/**
+ * Writes a record through its classic UI form (`/<table>.do`), exactly as a browser does:
+ * load the form, then submit it with the form's tokens.
+ *
+ * This is a low-level tool for writing directly to an instance when the record is NOT
+ * authored in a now-sdk application. Its reason to exist is variable-backed records
+ * (any table with a glide_var column, e.g. `wf_activity.vars`): the form submit is the
+ * path that writes their `sys_variable_value` rows, where REST writes to that table run
+ * into ACLs. Records that belong in a now-sdk app (ATF tests, flows, …) should be
+ * authored there instead.
+ *
+ * Why two requests: a new record's form carries values that are not form inputs —
+ * anything set through `sysparm_query` at load time, such as the record's variable
+ * model — inside the signed `sysparm_encoded_record`. A submit without it inserts the
+ * record but silently drops every variable.
+ *
+ * Only the values you pass are posted. The instance fills in everything else the same
+ * way the form would: variable defaults on insert, current values on update.
+ */
+declare class FormTransport {
+    private _logger;
+    private _instance;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * Load a record's form.
+     *
+     * @param table Table name
+     * @param sysId Record sys_id, or `-1` for a new record
+     * @param options View and, for new records, the initial query
+     * @throws Error when the page is not the expected form, or the record does not exist
+     */
+    loadForm(table: string, sysId?: string, options?: FormTransportLoadOptions): Promise<FormTransportSnapshot>;
+    /**
+     * Submit a form you already loaded. Use this to inspect the form's variables (names,
+     * types, choices) before deciding what to write.
+     */
+    submit(snapshot: FormTransportSnapshot, action: string, options?: FormTransportSubmitOptions): Promise<FormTransportResult>;
+    /** Validate caller values without submitting the form. */
+    validate(snapshot: FormSnapshot, options: FormWriteOptions): void;
+    /**
+     * Turn caller values into posted form parameters, validating variables against the
+     * form so a misspelt element fails loudly instead of being silently ignored.
+     */
+    private buildFields;
+    private variablesFor;
+    requireExists(table: string, sysId: string): Promise<void>;
+    private guardedLanding;
+    private request;
+    private requireTable;
+    private text;
+    private sanitizeError;
+}
+/** Shared internal transport. Excluded from the package barrel. */
+export declare function createFormTransport(instance: ServiceNowInstance): FormTransport;
+/** Write ordinary records through classic forms with the established defaults. */
+export declare class FormRecordWriter {
+    private _transport;
+    constructor(instance: ServiceNowInstance);
+    loadForm(table: string, sysId?: string, options?: FormLoadOptions): Promise<FormSnapshot>;
+    /**
+     * Insert a record through its form.
+     *
+     * @param table Table name
+     * @param options Field values, variable values, view and initial query
+     * @returns The new record's sys_id and any info messages
+     * @throws InvalidParameterException for unknown variables or invalid choice values
+     * @throws FormSubmitError when the instance does not accept the submit
+     */
+    insert(table: string, options?: FormWriteOptions): Promise<FormWriteResult>;
+    /**
+     * Update a record through its form. Fields and variables you do not pass keep their
+     * current values.
+     *
+     * @param table Table name
+     * @param sysId Record sys_id
+     * @param options Field values, variable values and view
+     * @throws InvalidParameterException for unknown variables or invalid choice values
+     * @throws FormSubmitError when the instance does not accept the submit
+     */
+    update(table: string, sysId: string, options?: FormWriteOptions): Promise<FormWriteResult>;
+    submit(snapshot: FormSnapshot, action: "sysverb_insert" | "sysverb_update", options?: FormWriteOptions): Promise<FormWriteResult>;
+}
+/**
+ * Encode a caller value the way the form posts it.
+ *
+ * @param value The caller's value
+ * @param control The form control it is going to, when known (drives duration and choice handling)
+ */
+export declare function encodeFormValue(value: FormValueInput, control?: FormControl): string;
+/**
+ * Durations post in the form's display format, `D HH:MM:SS`. The stored format
+ * (`1970-01-03 01:02:03`) and plain seconds are not understood by the form, so both are
+ * converted here.
+ */
+export declare function encodeDuration(value: number | string | FormDurationInput): string;
+export {};