@tenonhq/dovetail-servicenow 0.0.2

package/README.md

@@ -0,0 +1,118 @@
+# @tenonhq/dovetail-servicenow
+
+ServiceNow platform helpers for Dovetail. The first shipped feature is
+**`addChoicesToField`** — upserts `sys_choice` rows for a given `table.column`
+and flips `sys_dictionary.choice` in one idempotent call, with every write
+captured in the update set you pass in.
+
+## Why
+
+Adding choice values to a scoped ServiceNow field is a 3-part ritual:
+
+1. Find the `sys_dictionary` row for `(table, column)` and set its `choice`
+   field (0 = none, 1 = suggestion, **3 = dropdown w/ `-- None --`**).
+2. Create one `sys_choice` row per value/label pair, with `sys_scope` matching
+   the dictionary record.
+3. Make sure your user's current update set points at the *right* update set
+   (not Default), or the whole change set gets trapped.
+
+This package collapses it into:
+
+```ts
+await addChoicesToField(client, {
+  table: "x_cadso_core_event",
+  column: "state",
+  updateSetSysId: "0083c3bb33d003507b18bc534d5c7b6d",
+  choices: [
+    { value: "delivered", label: "Delivered" },
+    { value: "failed",    label: "Failed" }
+  ]
+});
+```
+
+Writes go through the **Dovetail Scripted REST API** (`/api/cadso/dovetail/*`,
+historically named "Claude" at `/api/cadso/claude/*`; the client falls back to
+the legacy path on instances where the rename hasn't been imported yet). The
+API pins every write to the supplied update set regardless of the REST user's
+current preference, so re-running with the same inputs is safe — every row
+comes back as `unchanged`.
+
+## Install
+
+```bash
+npm install @tenonhq/dovetail-servicenow
+```
+
+Requires Node 20 LTS.
+
+## Configure
+
+Reads ServiceNow credentials from env vars in this order of precedence:
+
+| Field    | Preferred       | Dev fallback        | Prod fallback        |
+|----------|-----------------|---------------------|----------------------|
+| Host     | `SN_INSTANCE`   | `SN_DEV_INSTANCE`   | `SN_PROD_INSTANCE`   |
+| User     | `SN_USER`       | `SN_DEV_USERNAME`   | `SN_PROD_USERNAME`   |
+| Password | `SN_PASSWORD`   | `SN_DEV_PASSWORD`   | `SN_PROD_PASSWORD`   |
+
+The dev/prod fallbacks match the names already documented in
+`Craftsman/CLAUDE.local.md`, so existing developer setups work out of the box.
+Bare instance names (e.g. `TenonWorkStudio`) get `.service-now.com` appended
+automatically.
+
+```
+SN_INSTANCE=tenonworkstudio.service-now.com
+SN_USER=...
+SN_PASSWORD=...
+```
+
+## CLI
+
+```bash
+# Inline form
+npx sinc-sn add-choices \
+  --table x_cadso_core_event \
+  --column state \
+  --update-set 0083c3bb33d003507b18bc534d5c7b6d \
+  --choices "delivered=Delivered,failed=Failed,expired=Expired"
+
+# JSON payload form (recommended for >5 choices)
+npx sinc-sn add-choices --from-json ./choices.json
+```
+
+JSON payload shape:
+
+```json
+{
+  "table": "x_cadso_core_event",
+  "column": "state",
+  "updateSetSysId": "0083c3bb33d003507b18bc534d5c7b6d",
+  "choiceType": 3,
+  "choices": [
+    { "value": "delivered", "label": "Delivered" },
+    { "value": "failed",    "label": "Failed" }
+  ]
+}
+```
+
+## Programmatic
+
+```ts
+import { createClient, addChoicesToField } from "@tenonhq/dovetail-servicenow";
+
+var client = createClient({});
+var result = await addChoicesToField(client, { /* ... */ });
+
+console.log(result.choices);
+// [
+//   { value: "delivered", label: "Delivered", sysId: "...", action: "created" },
+//   { value: "failed",    label: "Failed",    sysId: "...", action: "created" }
+// ]
+```
+
+## Roadmap
+
+Same package will grow to cover the rest of the `sinch-dlr-manual-steps`
+patterns: indexes (`sys_db_object_ix`), table properties (`accessible_from`),
+`sys_trigger` creation, `sys_property` creation. Pattern stays identical —
+query to diff, write through the Dovetail REST API, report per-row actions.

package/dist/choices.d.ts

@@ -0,0 +1,17 @@
+/**
+ * addChoicesToField — upsert sys_choice rows for a given table.column,
+ * and (optionally) flip sys_dictionary.choice so the column renders as a dropdown.
+ *
+ * All writes go through the Dovetail "Claude" Scripted REST API, which pins
+ * each write to the supplied update set regardless of the REST user's current
+ * preference. sys_scope on sys_choice is inherited from the dictionary record
+ * so choices stay in the same application as the field.
+ */
+import type { ServiceNowClient } from "./client";
+import type { AddChoicesParams, AddChoicesResult } from "./types";
+/**
+ * Upsert choices for a field and (optionally) toggle sys_dictionary.choice.
+ * Idempotent: re-running with the same inputs returns `action: "unchanged"`
+ * for every row and skips the dictionary write when no change is required.
+ */
+export declare function addChoicesToField(client: ServiceNowClient, params: AddChoicesParams): Promise<AddChoicesResult>;

package/dist/choices.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * addChoicesToField — upsert sys_choice rows for a given table.column,
+ * and (optionally) flip sys_dictionary.choice so the column renders as a dropdown.
+ *
+ * All writes go through the Dovetail "Claude" Scripted REST API, which pins
+ * each write to the supplied update set regardless of the REST user's current
+ * preference. sys_scope on sys_choice is inherited from the dictionary record
+ * so choices stay in the same application as the field.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addChoicesToField = addChoicesToField;
+function encodeQueryValue(v) {
+    // ServiceNow encoded-query values: commas/carets/equals are special. We
+    // don't expect them in table/column/value/language inputs, but keep this
+    // escape-lite to surface surprises loudly rather than silently.
+    if (/[,\^=]/.test(v)) {
+        throw new Error("Invalid character in query value: " + JSON.stringify(v));
+    }
+    return v;
+}
+/**
+ * Resolve a sys_scope record's namespace name (e.g. "x_cadso_core") from its
+ * sys_id. The Claude REST API's `scope` parameter expects the namespace name,
+ * not the sys_id, so dictionary records (whose sys_scope is a sys_id) need
+ * a translation step before we can pass them through.
+ */
+async function resolveScopeName(client, scopeSysId) {
+    if (!scopeSysId)
+        return "";
+    var rows = await client.table.query("sys_scope", "sys_id=" + encodeQueryValue(scopeSysId), 1);
+    if (rows.length === 0) {
+        throw new Error("sys_scope record not found for sys_id " + scopeSysId);
+    }
+    // sys_scope.scope is the namespace (e.g. "x_cadso_core"); fall back to name
+    // if a scope record was created without a populated scope field.
+    return rows[0].scope || rows[0].name || "";
+}
+async function fetchDictionary(client, table, column) {
+    var rows = await client.table.query("sys_dictionary", "name=" + encodeQueryValue(table) + "^element=" + encodeQueryValue(column), 1);
+    if (rows.length === 0) {
+        throw new Error("sys_dictionary record not found for " + table + "." + column +
+            " — verify the field exists and your user has read access.");
+    }
+    var row = rows[0];
+    // sys_scope comes back as a reference object or string depending on display_value.
+    // We set sysparm_display_value=false in client.query so we get the sys_id string.
+    var scope = typeof row.sys_scope === "object" && row.sys_scope != null
+        ? row.sys_scope.value
+        : row.sys_scope;
+    return {
+        sys_id: row.sys_id,
+        name: row.name,
+        element: row.element,
+        choice: String(row.choice || "0"),
+        sys_scope: scope || ""
+    };
+}
+async function fetchUpdateSet(client, sysId) {
+    var rows = await client.table.query("sys_update_set", "sys_id=" + encodeQueryValue(sysId), 1);
+    if (rows.length === 0) {
+        throw new Error("Update set " + sysId + " not found — verify the sys_id and your access.");
+    }
+    var row = rows[0];
+    if (row.state && row.state !== "in progress" && row.state !== "in_progress") {
+        throw new Error("Update set " + row.name + " is in state '" + row.state +
+            "' — only 'in progress' update sets can capture new changes.");
+    }
+    return row;
+}
+async function fetchExistingChoices(client, table, column) {
+    return client.table.query("sys_choice", "name=" + encodeQueryValue(table) +
+        "^element=" + encodeQueryValue(column), 1000);
+}
+function buildChoiceFields(table, column, choice, scope) {
+    var fields = {
+        name: table,
+        element: column,
+        value: choice.value,
+        label: choice.label,
+        language: choice.language || "en",
+        inactive: "false"
+    };
+    if (choice.sequence != null) {
+        fields.sequence = String(choice.sequence);
+    }
+    if (scope) {
+        fields.sys_scope = scope;
+    }
+    return fields;
+}
+function isUnchanged(existing, choice) {
+    var sameLabel = existing.label === choice.label;
+    var sameLang = (existing.language || "en") === (choice.language || "en");
+    var sameSeq = choice.sequence == null
+        ? true
+        : String(existing.sequence || "") === String(choice.sequence);
+    return sameLabel && sameLang && sameSeq && existing.inactive === "false";
+}
+/**
+ * Upsert choices for a field and (optionally) toggle sys_dictionary.choice.
+ * Idempotent: re-running with the same inputs returns `action: "unchanged"`
+ * for every row and skips the dictionary write when no change is required.
+ */
+async function addChoicesToField(client, params) {
+    if (!params.updateSetSysId) {
+        throw new Error("updateSetSysId is required — every write must be captured in a named update set.");
+    }
+    if (!params.choices || params.choices.length === 0) {
+        throw new Error("choices must be a non-empty array.");
+    }
+    var dict = await fetchDictionary(client, params.table, params.column);
+    var updateSet = await fetchUpdateSet(client, params.updateSetSysId);
+    var scopeName = await resolveScopeName(client, dict.sys_scope);
+    var targetChoiceType = params.choiceType === null
+        ? Number(dict.choice)
+        : (params.choiceType != null ? params.choiceType : 3);
+    var choiceWas = Number(dict.choice);
+    var choiceNow = choiceWas;
+    if (params.choiceType !== null && Number(dict.choice) !== targetChoiceType) {
+        await client.claude.pushWithUpdateSet({
+            update_set_sys_id: params.updateSetSysId,
+            table: "sys_dictionary",
+            record_sys_id: dict.sys_id,
+            fields: { choice: String(targetChoiceType) }
+        });
+        choiceNow = targetChoiceType;
+    }
+    var existing = await fetchExistingChoices(client, params.table, params.column);
+    var existingByValue = {};
+    existing.forEach(function (row) {
+        var key = (row.language || "en") + "::" + row.value;
+        existingByValue[key] = row;
+    });
+    var results = [];
+    for (var i = 0; i < params.choices.length; i += 1) {
+        var choice = params.choices[i];
+        var key = (choice.language || "en") + "::" + choice.value;
+        var match = existingByValue[key];
+        if (match && isUnchanged(match, choice)) {
+            results.push({ value: choice.value, label: choice.label, sysId: match.sys_id, action: "unchanged" });
+            continue;
+        }
+        if (match) {
+            var updFields = {
+                label: choice.label,
+                language: choice.language || "en",
+                inactive: "false"
+            };
+            if (choice.sequence != null) {
+                updFields.sequence = String(choice.sequence);
+            }
+            await client.claude.pushWithUpdateSet({
+                update_set_sys_id: params.updateSetSysId,
+                table: "sys_choice",
+                record_sys_id: match.sys_id,
+                fields: updFields
+            });
+            results.push({ value: choice.value, label: choice.label, sysId: match.sys_id, action: "updated" });
+            continue;
+        }
+        var created = await client.claude.createRecord({
+            table: "sys_choice",
+            fields: buildChoiceFields(params.table, params.column, choice, dict.sys_scope),
+            scope: scopeName,
+            update_set_sys_id: params.updateSetSysId
+        });
+        results.push({
+            value: choice.value,
+            label: choice.label,
+            sysId: created.sys_id,
+            action: "created"
+        });
+    }
+    return {
+        dictionary: {
+            sysId: dict.sys_id,
+            scope: dict.sys_scope,
+            choiceWas: choiceWas,
+            choiceNow: choiceNow
+        },
+        updateSet: { sysId: updateSet.sys_id, name: updateSet.name },
+        choices: results
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * sinc-sn — thin CLI adapter for @tenonhq/dovetail-servicenow.
+ *
+ * Usage:
+ *   sinc-sn add-choices \
+ *     --table x_cadso_core_event \
+ *     --column state \
+ *     --update-set <sys_id> \
+ *     --choices 'delivered=Delivered,failed=Failed,...' \
+ *     [--choice-type 3] [--json]
+ *
+ *   sinc-sn add-choices --from-json path/to/choices.json
+ *
+ * JSON payload shape:
+ *   {
+ *     "table": "x_cadso_core_event",
+ *     "column": "state",
+ *     "updateSetSysId": "...",
+ *     "choiceType": 3,
+ *     "choices": [{ "value": "delivered", "label": "Delivered" }, ...]
+ *   }
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * sinc-sn — thin CLI adapter for @tenonhq/dovetail-servicenow.
+ *
+ * Usage:
+ *   sinc-sn add-choices \
+ *     --table x_cadso_core_event \
+ *     --column state \
+ *     --update-set <sys_id> \
+ *     --choices 'delivered=Delivered,failed=Failed,...' \
+ *     [--choice-type 3] [--json]
+ *
+ *   sinc-sn add-choices --from-json path/to/choices.json
+ *
+ * JSON payload shape:
+ *   {
+ *     "table": "x_cadso_core_event",
+ *     "column": "state",
+ *     "updateSetSysId": "...",
+ *     "choiceType": 3,
+ *     "choices": [{ "value": "delivered", "label": "Delivered" }, ...]
+ *   }
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const client_1 = require("./client");
+const choices_1 = require("./choices");
+const formatter_1 = require("./formatter");
+function parseArgs(argv) {
+    var command = argv[0] || "";
+    var flags = {};
+    for (var i = 1; i < argv.length; i += 1) {
+        var arg = argv[i];
+        if (arg.indexOf("--") !== 0)
+            continue;
+        var key = arg.slice(2);
+        var value = "true";
+        var eq = key.indexOf("=");
+        if (eq !== -1) {
+            value = key.slice(eq + 1);
+            key = key.slice(0, eq);
+        }
+        else if (i + 1 < argv.length && argv[i + 1].indexOf("--") !== 0) {
+            value = argv[i + 1];
+            i += 1;
+        }
+        flags[key] = value;
+    }
+    return { command: command, flags: flags };
+}
+function parseChoicesInline(input) {
+    return input.split(",").map(function (pair) {
+        var parts = pair.split("=");
+        if (parts.length !== 2) {
+            throw new Error("Invalid --choices entry '" + pair + "' (expected value=Label)");
+        }
+        return { value: parts[0].trim(), label: parts[1].trim() };
+    });
+}
+function paramsFromFlags(flags) {
+    if (flags["from-json"]) {
+        var raw = fs.readFileSync(flags["from-json"], "utf8");
+        var obj = JSON.parse(raw);
+        return obj;
+    }
+    var table = flags.table;
+    var column = flags.column;
+    var updateSetSysId = flags["update-set"] || flags.updateSetSysId;
+    var choicesInline = flags.choices;
+    if (!table || !column || !updateSetSysId || !choicesInline) {
+        throw new Error("Missing required flags: --table, --column, --update-set, --choices");
+    }
+    var params = {
+        table: table,
+        column: column,
+        updateSetSysId: updateSetSysId,
+        choices: parseChoicesInline(choicesInline)
+    };
+    if (flags["choice-type"]) {
+        params.choiceType = Number(flags["choice-type"]);
+    }
+    return params;
+}
+async function runAddChoices(flags) {
+    var params = paramsFromFlags(flags);
+    var client = (0, client_1.createClient)({});
+    var result = await (0, choices_1.addChoicesToField)(client, params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify({ params: params, result: result }, null, 2) + "\n");
+        return;
+    }
+    process.stdout.write((0, formatter_1.formatAddChoicesResult)(params.table, params.column, result) + "\n");
+}
+function printHelp() {
+    process.stdout.write("sinc-sn — ServiceNow helpers\n\n" +
+        "Commands:\n" +
+        "  add-choices   Upsert sys_choice rows for a table.column (see --help in source)\n");
+}
+async function main() {
+    var parsed = parseArgs(process.argv.slice(2));
+    if (parsed.command === "add-choices") {
+        await runAddChoices(parsed.flags);
+        return;
+    }
+    if (!parsed.command || parsed.command === "help" || parsed.flags.help === "true") {
+        printHelp();
+        return;
+    }
+    throw new Error("Unknown command: " + parsed.command);
+}
+main().catch(function (err) {
+    process.stderr.write("sinc-sn error: " + (err && err.message ? err.message : String(err)) + "\n");
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ServiceNow REST client for @tenonhq/dovetail-servicenow.
+ *
+ * Provides two entry points:
+ *   - `table.*`       — read-only GETs against the native Table API
+ *   - `claude.*`      — writes via the Dovetail Scripted REST API
+ *                       (/api/cadso/dovetail/*), which handles update-set + scope
+ *                       switching atomically so every write lands in the right
+ *                       update set without touching sys_user_preference.
+ *                       Falls back to the legacy /api/cadso/claude/* path on
+ *                       instances where the API has not yet been re-imported.
+ *                       The namespace name `claude` is preserved for API
+ *                       compatibility; the underlying server-side API is now
+ *                       named "Dovetail".
+ *
+ * Env fallbacks mirror prior dashboard-fetch helpers so dev setups that already
+ * have SN_INSTANCE/SN_USER/SN_PASSWORD work without reconfiguration.
+ */
+import type { ServiceNowClientConfig } from "./types";
+export interface TableQueryOptions {
+    limit?: number;
+    fields?: string[];
+}
+export interface ServiceNowClient {
+    table: {
+        /** GET /api/now/table/<t>?sysparm_query=...&sysparm_limit=N — returns result array. */
+        query: {
+            <T = Record<string, any>>(table: string, query: string, limit?: number): Promise<Array<T>>;
+            <T = Record<string, any>>(table: string, query: string, options: TableQueryOptions): Promise<Array<T>>;
+        };
+    };
+    claude: {
+        /** POST /api/cadso/dovetail/createRecord (legacy path: /api/cadso/claude/createRecord). */
+        createRecord: (params: {
+            table: string;
+            fields: Record<string, any>;
+            scope?: string;
+            update_set_sys_id?: string;
+            sys_id?: string;
+        }) => Promise<{
+            sys_id: string;
+            [k: string]: any;
+        }>;
+        /** POST /api/cadso/dovetail/pushWithUpdateSet (legacy: /api/cadso/claude/pushWithUpdateSet). */
+        pushWithUpdateSet: (params: {
+            update_set_sys_id: string;
+            table: string;
+            record_sys_id: string;
+            fields: Record<string, any>;
+        }) => Promise<{
+            sys_id: string;
+            [k: string]: any;
+        }>;
+        /** GET /api/cadso/dovetail/currentUpdateSet?scope=... (legacy: /api/cadso/claude/currentUpdateSet). */
+        currentUpdateSet: (scope?: string) => Promise<{
+            sys_id: string;
+            name: string;
+        }>;
+    };
+}
+export declare function createClient(config?: ServiceNowClientConfig): ServiceNowClient;

package/dist/client.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * ServiceNow REST client for @tenonhq/dovetail-servicenow.
+ *
+ * Provides two entry points:
+ *   - `table.*`       — read-only GETs against the native Table API
+ *   - `claude.*`      — writes via the Dovetail Scripted REST API
+ *                       (/api/cadso/dovetail/*), which handles update-set + scope
+ *                       switching atomically so every write lands in the right
+ *                       update set without touching sys_user_preference.
+ *                       Falls back to the legacy /api/cadso/claude/* path on
+ *                       instances where the API has not yet been re-imported.
+ *                       The namespace name `claude` is preserved for API
+ *                       compatibility; the underlying server-side API is now
+ *                       named "Dovetail".
+ *
+ * Env fallbacks mirror prior dashboard-fetch helpers so dev setups that already
+ * have SN_INSTANCE/SN_USER/SN_PASSWORD work without reconfiguration.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Env precedence for instance/auth: explicit cfg > SN_* > SN_DEV_* > SN_PROD_*.
+ * SN_DEV_* / SN_PROD_* fallbacks match the names documented in Craftsman/CLAUDE.local.md
+ * so existing developer setups work without re-exporting variables. SN_DEV_INSTANCE
+ * may be a bare instance name (e.g. "TenonWorkStudio") — `.service-now.com` is
+ * appended when it isn't already part of the host.
+ */
+function normalizeHost(raw) {
+    var host = raw.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    if (host && host.indexOf(".") === -1) {
+        host = host.toLowerCase() + ".service-now.com";
+    }
+    return host;
+}
+function resolveInstance(cfg) {
+    var raw = cfg.instance
+        || process.env.SN_INSTANCE
+        || process.env.SN_DEV_INSTANCE
+        || process.env.SN_PROD_INSTANCE
+        || "";
+    if (!raw) {
+        throw new Error("ServiceNow instance not configured. Set SN_INSTANCE (preferred) or SN_DEV_INSTANCE / SN_PROD_INSTANCE, or pass { instance }.");
+    }
+    return normalizeHost(raw);
+}
+function resolveAuth(cfg) {
+    var user = cfg.user
+        || process.env.SN_USER
+        || process.env.SN_DEV_USERNAME
+        || process.env.SN_PROD_USERNAME
+        || "";
+    var password = cfg.password
+        || process.env.SN_PASSWORD
+        || process.env.SN_DEV_PASSWORD
+        || process.env.SN_PROD_PASSWORD
+        || "";
+    if (!user || !password) {
+        throw new Error("ServiceNow credentials missing — set SN_USER/SN_PASSWORD (preferred) " +
+            "or SN_DEV_USERNAME/SN_DEV_PASSWORD (or SN_PROD_*).");
+    }
+    return { user: user, password: password };
+}
+function sleep(ms) {
+    return new Promise(function (resolve) {
+        setTimeout(resolve, ms);
+    });
+}
+function createClient(config = {}) {
+    var host = resolveInstance(config);
+    var creds = resolveAuth(config);
+    var intervalMs = config.requestIntervalMs != null
+        ? config.requestIntervalMs
+        : Number(process.env.SN_REQUEST_INTERVAL_MS) || 20;
+    var max429 = config.maxRetries429 != null
+        ? config.maxRetries429
+        : Number(process.env.SN_MAX_RETRIES_429) || 5;
+    var max5xx = config.maxRetries5xx != null
+        ? config.maxRetries5xx
+        : Number(process.env.SN_MAX_RETRIES_5XX) || 3;
+    var http = axios_1.default.create({
+        baseURL: "https://" + host,
+        auth: { username: creds.user, password: creds.password },
+        headers: { accept: "application/json", "content-type": "application/json" },
+        validateStatus: function () { return true; }
+    });
+    var lastAt = 0;
+    // Dovetail Scripted REST API rebrand: prefer /api/cadso/dovetail/* and fall back
+    // to the legacy /api/cadso/claude/* path on instances where the rename hasn't
+    // been imported yet. Latch the legacy flag after the first 404 to avoid paying
+    // the round-trip cost on every subsequent call.
+    var useDovetailLegacyClaudePath = false;
+    async function request(cfg, ctx) {
+        var attempt429 = 0;
+        var attempt5xx = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            var elapsed = Date.now() - lastAt;
+            if (elapsed < intervalMs) {
+                await sleep(intervalMs - elapsed);
+            }
+            lastAt = Date.now();
+            var res;
+            try {
+                res = await http.request(cfg);
+            }
+            catch (netErr) {
+                if (attempt5xx >= max5xx) {
+                    throw new Error("SN network error on " + ctx + ": " + (netErr && netErr.message));
+                }
+                attempt5xx += 1;
+                await sleep(Math.pow(2, attempt5xx) * 1000);
+                continue;
+            }
+            if (res.status === 401 || res.status === 403) {
+                throw new Error("SN auth error " + res.status + " on " + ctx + " — check SN_USER/SN_PASSWORD and ACLs.");
+            }
+            if (res.status === 404) {
+                throw new Error("SN 404 on " + ctx + " — endpoint or record not found.");
+            }
+            if (res.status === 429) {
+                if (attempt429 >= max429) {
+                    throw new Error("SN 429 rate limit — retries exhausted on " + ctx);
+                }
+                attempt429 += 1;
+                await sleep(Math.min(60000, Math.pow(2, attempt429) * 1000));
+                continue;
+            }
+            if (res.status >= 500) {
+                if (attempt5xx >= max5xx) {
+                    throw new Error("SN " + res.status + " on " + ctx + " — retries exhausted.");
+                }
+                attempt5xx += 1;
+                await sleep(Math.pow(2, attempt5xx) * 1000);
+                continue;
+            }
+            if (res.status < 200 || res.status >= 300) {
+                var body = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
+                throw new Error("SN " + res.status + " on " + ctx + ": " + body.substring(0, 400));
+            }
+            return res.data;
+        }
+    }
+    // Dovetail Scripted REST API request: try /api/cadso/dovetail/<op>, fall back to
+    // /api/cadso/claude/<op> on 404 (with a one-time deprecation warning).
+    async function dovetailRequest(method, op, body, params, ctx) {
+        var url = useDovetailLegacyClaudePath
+            ? "/api/cadso/claude/" + op
+            : "/api/cadso/dovetail/" + op;
+        try {
+            return await request({ method: method, url: url, data: body, params: params }, ctx);
+        }
+        catch (e) {
+            var msg = e && e.message ? String(e.message) : "";
+            if (!useDovetailLegacyClaudePath && msg.indexOf("SN 404 on") === 0) {
+                // eslint-disable-next-line no-console
+                console.warn("[deprecation] /api/cadso/dovetail/" + op +
+                    " returned 404. Falling back to legacy /api/cadso/claude/" + op +
+                    ". Re-import the Dovetail Scripted REST API XML on your ServiceNow instance to silence this warning.");
+                useDovetailLegacyClaudePath = true;
+                var legacyUrl = "/api/cadso/claude/" + op;
+                return await request({ method: method, url: legacyUrl, data: body, params: params }, ctx);
+            }
+            throw e;
+        }
+    }
+    return {
+        table: {
+            query: async function (table, query, limitOrOptions) {
+                var limit = 100;
+                var fields;
+                if (typeof limitOrOptions === "number") {
+                    limit = limitOrOptions;
+                }
+                else if (limitOrOptions && typeof limitOrOptions === "object") {
+                    if (typeof limitOrOptions.limit === "number") {
+                        limit = limitOrOptions.limit;
+                    }
+                    if (limitOrOptions.fields && limitOrOptions.fields.length > 0) {
+                        fields = limitOrOptions.fields;
+                    }
+                }
+                var params = {
+                    sysparm_query: query,
+                    sysparm_limit: limit,
+                    sysparm_display_value: false
+                };
+                if (fields) {
+                    params.sysparm_fields = fields.join(",");
+                }
+                var data = await request({
+                    method: "GET",
+                    url: "/api/now/table/" + encodeURIComponent(table),
+                    params: params
+                }, "table.query(" + table + ")");
+                return data.result || [];
+            }
+        },
+        claude: {
+            createRecord: async function (params) {
+                var data = await dovetailRequest("POST", "createRecord", params, null, "claude.createRecord(" + params.table + ")");
+                return data.result || data;
+            },
+            pushWithUpdateSet: async function (params) {
+                var data = await dovetailRequest("POST", "pushWithUpdateSet", params, null, "claude.pushWithUpdateSet(" + params.table + ")");
+                return data.result || data;
+            },
+            currentUpdateSet: async function (scope) {
+                var data = await dovetailRequest("GET", "currentUpdateSet", null, scope ? { scope: scope } : null, "claude.currentUpdateSet");
+                return data.result || data;
+            }
+        }
+    };
+}

package/dist/formatter.d.ts

@@ -0,0 +1,6 @@
+import type { AddChoicesResult } from "./types";
+/**
+ * Human-readable one-page summary of an addChoicesToField result.
+ * Used by the CLI and by Claude skills when surfacing outcomes back to the user.
+ */
+export declare function formatAddChoicesResult(table: string, column: string, result: AddChoicesResult): string;

package/dist/formatter.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAddChoicesResult = formatAddChoicesResult;
+/**
+ * Human-readable one-page summary of an addChoicesToField result.
+ * Used by the CLI and by Claude skills when surfacing outcomes back to the user.
+ */
+function formatAddChoicesResult(table, column, result) {
+    var lines = [];
+    lines.push("ServiceNow choice values — " + table + "." + column);
+    lines.push("");
+    lines.push("Update set: " + result.updateSet.name + " (" + result.updateSet.sysId + ")");
+    lines.push("Dictionary: " + result.dictionary.sysId + " [scope " + result.dictionary.scope + "]");
+    if (result.dictionary.choiceWas !== result.dictionary.choiceNow) {
+        lines.push("  sys_dictionary.choice: " + result.dictionary.choiceWas + " -> " + result.dictionary.choiceNow);
+    }
+    else {
+        lines.push("  sys_dictionary.choice: " + result.dictionary.choiceNow + " (unchanged)");
+    }
+    lines.push("");
+    var created = 0;
+    var updated = 0;
+    var unchanged = 0;
+    lines.push("Choices:");
+    result.choices.forEach(function (row) {
+        if (row.action === "created")
+            created += 1;
+        else if (row.action === "updated")
+            updated += 1;
+        else
+            unchanged += 1;
+        lines.push("  [" + row.action.padEnd(9) + "] " + row.value + " -> " + row.label +
+            "  (" + row.sysId + ")");
+    });
+    lines.push("");
+    lines.push("Summary: " + created + " created, " + updated + " updated, " + unchanged + " unchanged.");
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @tenonhq/dovetail-servicenow
+ *
+ * ServiceNow helpers that route writes through the Dovetail "Claude" Scripted
+ * REST API so every change lands in the target update set and scope.
+ */
+export { createClient } from "./client";
+export type { ServiceNowClient, TableQueryOptions } from "./client";
+export { addChoicesToField } from "./choices";
+export { formatAddChoicesResult } from "./formatter";
+export { sincPlugin } from "./plugin";
+export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, DictionaryRecord, UpdateSetRecord } from "./types";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @tenonhq/dovetail-servicenow
+ *
+ * ServiceNow helpers that route writes through the Dovetail "Claude" Scripted
+ * REST API so every change lands in the target update set and scope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sincPlugin = 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");
+Object.defineProperty(exports, "addChoicesToField", { enumerable: true, get: function () { return choices_1.addChoicesToField; } });
+var formatter_1 = require("./formatter");
+Object.defineProperty(exports, "formatAddChoicesResult", { enumerable: true, get: function () { return formatter_1.formatAddChoicesResult; } });
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "sincPlugin", { enumerable: true, get: function () { return plugin_1.sincPlugin; } });

package/dist/plugin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Dovetail init plugin for @tenonhq/dovetail-servicenow.
+ * Auth piggybacks on `npx dove configure` — SN_INSTANCE / SN_USER / SN_PASSWORD
+ * already get wired there, so this plugin is currently a no-op discoverable marker.
+ */
+export declare const sincPlugin: {
+    name: string;
+    displayName: string;
+    description: string;
+    login: never[];
+    configure: never[];
+};

package/dist/plugin.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Dovetail init plugin for @tenonhq/dovetail-servicenow.
+ * Auth piggybacks on `npx dove configure` — SN_INSTANCE / SN_USER / SN_PASSWORD
+ * already get wired there, so this plugin is currently a no-op discoverable marker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sincPlugin = void 0;
+exports.sincPlugin = {
+    name: "servicenow",
+    displayName: "ServiceNow",
+    description: "Dictionary / choice helpers and update-set-aware writes",
+    login: [],
+    configure: []
+};

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @tenonhq/dovetail-servicenow — type definitions
+ */
+export interface ServiceNowClientConfig {
+    /** Instance host, e.g. "tenonworkstudio.service-now.com". Defaults to SN_INSTANCE env var. */
+    instance?: string;
+    /** Basic-auth user. Defaults to SN_USER env var. */
+    user?: string;
+    /** Basic-auth password. Defaults to SN_PASSWORD env var. */
+    password?: string;
+    /** Min gap between requests (ms). Defaults to SN_REQUEST_INTERVAL_MS or 20. */
+    requestIntervalMs?: number;
+    /** Max retries on 429. Defaults to SN_MAX_RETRIES_429 or 5. */
+    maxRetries429?: number;
+    /** Max retries on 5xx/network. Defaults to SN_MAX_RETRIES_5XX or 3. */
+    maxRetries5xx?: number;
+}
+export interface ChoiceValue {
+    value: string;
+    label: string;
+    /** Order hint. Optional; ServiceNow auto-sequences when omitted. */
+    sequence?: number;
+    /** Defaults to "en". */
+    language?: string;
+}
+/** sys_dictionary.choice column values. 0 = none, 1 = suggestion, 3 = dropdown w/ --None--. */
+export type ChoiceType = 0 | 1 | 3;
+export interface AddChoicesParams {
+    /** Target table, e.g. "x_cadso_core_event". */
+    table: string;
+    /** Target column, e.g. "state". */
+    column: string;
+    /** Choice values to upsert. */
+    choices: Array<ChoiceValue>;
+    /** Update set sys_id that will capture every write. Required — no default. */
+    updateSetSysId: string;
+    /** sys_dictionary.choice setting. Defaults to 3 (dropdown). Pass null to leave dictionary alone. */
+    choiceType?: ChoiceType | null;
+}
+export interface DictionaryRecord {
+    sys_id: string;
+    name: string;
+    element: string;
+    choice: string;
+    /** sys_scope is a reference; ServiceNow returns the sys_id string. */
+    sys_scope: string;
+}
+export interface UpdateSetRecord {
+    sys_id: string;
+    name: string;
+    state: string;
+    application: string;
+}
+export interface ChoiceActionResult {
+    value: string;
+    label: string;
+    sysId: string;
+    action: "created" | "updated" | "unchanged";
+}
+export interface AddChoicesResult {
+    dictionary: {
+        sysId: string;
+        scope: string;
+        choiceWas: ChoiceType;
+        choiceNow: ChoiceType;
+    };
+    updateSet: {
+        sysId: string;
+        name: string;
+    };
+    choices: Array<ChoiceActionResult>;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @tenonhq/dovetail-servicenow — type definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tenonhq/dovetail-servicenow",
+  "version": "0.0.2",
+  "description": "ServiceNow platform helpers for Dovetail — dictionary, choices, update-set-aware writes via the Dovetail Scripted REST API",
+  "main": "./dist/index.js",
+  "bin": {
+    "dove-sn": "./dist/cli.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "prepack": "tsc",
+    "version:bump": "node ./../../Scripts/bump-version.js ./package.json",
+    "postpublish": "npm run version:bump"
+  },
+  "author": "Tenon",
+  "license": "GPL-3.0",
+  "dependencies": {
+    "axios": "^1.5.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.5",
+    "@types/node": ">=20.8.4",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.2.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tenonhq/dovetail.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tenonhq/dovetail/issues"
+  }
+}