@servicenow/sdk-build-plugins 4.4.0 → 4.5.0

package/src/schedule-script/timeZoneConverter.ts

@@ -0,0 +1,188 @@
+/**
+ * Formats a Date object to ServiceNow UTC datetime format (YYYY-MM-DD HH:MM:SS)
+ * @param date - The Date object to format (defaults to current time)
+ * @returns Formatted UTC datetime string
+ *
+ * @example
+ * const formatted = formatToUTC(new Date());
+ * // Returns: '1970-01-01 09:45:00'
+ *
+ * @example
+ * const formatted = formatToUTC();
+ * // Returns current time in UTC: '2026-02-27 07:43:00'
+ */
+export function formatToUTC(date: Date = new Date()): string {
+    const year = date.getUTCFullYear()
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0')
+    const day = String(date.getUTCDate()).padStart(2, '0')
+    const hour = String(date.getUTCHours()).padStart(2, '0')
+    const minute = String(date.getUTCMinutes()).padStart(2, '0')
+    const second = String(date.getUTCSeconds()).padStart(2, '0')
+
+    return `${year}-${month}-${day} ${hour}:${minute}:${second}`
+}
+
+/**
+ * Converts a datetime string from a specified timezone to UTC.
+ * Similar to timeFieldToXML but handles full date and time, not just time of day.
+ *
+ * @param dateTimeStr - DateTime string in format 'YYYY-MM-DD HH:MM:SS'
+ * @param timeZone - Optional IANA timezone string (e.g., 'America/New_York', 'Asia/Kolkata'). Defaults to system timezone.
+ * @returns Formatted UTC datetime string in 'YYYY-MM-DD HH:MM:SS' format
+ *
+ * @example
+ * // Convert '2026-03-02 14:30:00' from IST to UTC
+ * const utcDate = dateTimeFieldToXML('2026-03-02 14:30:00', 'Asia/Kolkata')
+ * // Returns '2026-03-02 09:00:00'
+ */
+export function dateTimeFieldToXML(dateTimeStr: string, timeZone?: string): string {
+    // Parse the datetime string
+    const match = dateTimeStr.match(/^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2}):(\d{2})$/)
+    if (!match) {
+        throw new Error(`Invalid datetime format: ${dateTimeStr}. Expected format: YYYY-MM-DD HH:MM:SS`)
+    }
+    // If timezone is 'floating' or not provided, use system timezone
+    const targetTimeZone =
+        timeZone === 'floating' || !timeZone ? Intl.DateTimeFormat().resolvedOptions().timeZone : timeZone
+
+    if (targetTimeZone === 'GMT' || targetTimeZone === 'UTC') {
+        return dateTimeStr
+    }
+
+    const year = parseInt(match[1]!, 10)
+    const month = parseInt(match[2]!, 10)
+    const day = parseInt(match[3]!, 10)
+    const hours = parseInt(match[4]!, 10)
+    const minutes = parseInt(match[5]!, 10)
+    const seconds = parseInt(match[6]!, 10)
+
+    const padZero = (n: number) => String(n).padStart(2, '0')
+
+    // Convert from specified timezone to UTC
+    // Create a reference date to calculate the timezone offset
+    const localDateStr = `${year}-${padZero(month)}-${padZero(day)}T${padZero(hours)}:${padZero(minutes)}:${padZero(seconds)}`
+
+    // Create a Date treating the input as UTC first
+    const utcDate = new Date(`${localDateStr}Z`)
+
+    // Get what this UTC time looks like in the target timezone
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: targetTimeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    })
+
+    const parts = formatter.formatToParts(utcDate)
+    const dateParts: Record<string, string> = {}
+
+    parts.forEach((part) => {
+        if (part.type !== 'literal') {
+            dateParts[part.type] = part.value
+        }
+    })
+
+    // Calculate the difference between what we want and what we got
+    const targetYear = parseInt(dateParts['year']!, 10)
+    const targetMonth = parseInt(dateParts['month']!, 10)
+    const targetDay = parseInt(dateParts['day']!, 10)
+    const targetHour = parseInt(dateParts['hour']!, 10)
+    const targetMinute = parseInt(dateParts['minute']!, 10)
+    const targetSecond = parseInt(dateParts['second']!, 10)
+
+    // Calculate the offset in milliseconds
+    const wantedTime = new Date(year, month - 1, day, hours, minutes, seconds).getTime()
+    const gotTime = new Date(targetYear, targetMonth - 1, targetDay, targetHour, targetMinute, targetSecond).getTime()
+    const offset = gotTime - wantedTime
+
+    // Apply the offset to get the correct UTC time
+    const resultDate = new Date(utcDate.getTime() - offset)
+    return formatToUTC(resultDate)
+}
+
+/**
+ * Converts an XML datetime string (in UTC) to a datetime string in a specified timezone
+ * @param utcDateTimeStr - UTC datetime string in format 'YYYY-MM-DD HH:MM:SS'
+ * @param timeZone - Optional IANA timezone string (e.g., 'America/New_York', 'Asia/Kolkata'). If not provided, returns the UTC string as-is.
+ * @returns Datetime string in the specified timezone in 'YYYY-MM-DD HH:MM:SS' format
+ *
+ * @example
+ * // Convert '2026-03-02 09:00:00' UTC to IST
+ * const localDateTime = convertXMLToDateTime('2026-03-02 09:00:00', 'Asia/Kolkata')
+ * // Returns '2026-03-02 14:30:00'
+ *
+ * @example
+ * // Without timezone, returns the UTC string as-is
+ * const utcDateTime = convertXMLToDateTime('2026-03-02 09:00:00')
+ * // Returns '2026-03-02 09:00:00'
+ */
+export function convertXMLToDateTime(utcDateTimeStr: string, timeZone?: string): string {
+    // Parse the UTC datetime string
+    const match = utcDateTimeStr.match(/^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2}):(\d{2})$/)
+    if (!match) {
+        throw new Error(`Invalid datetime format: ${utcDateTimeStr}. Expected format: YYYY-MM-DD HH:MM:SS`)
+    }
+
+    // If timezone is 'floating' or not provided, use system timezone
+    const targetTimeZone =
+        timeZone === 'floating' || !timeZone ? Intl.DateTimeFormat().resolvedOptions().timeZone : timeZone
+
+    if (targetTimeZone === 'GMT' || targetTimeZone === 'UTC') {
+        return utcDateTimeStr
+    }
+
+    const year = parseInt(match[1]!, 10)
+    const month = parseInt(match[2]!, 10)
+    const day = parseInt(match[3]!, 10)
+    const hours = parseInt(match[4]!, 10)
+    const minutes = parseInt(match[5]!, 10)
+    const seconds = parseInt(match[6]!, 10)
+
+    // Create a Date object from the UTC datetime
+    const utcDate = new Date(Date.UTC(year, month - 1, day, hours, minutes, seconds))
+
+    // Format the date in the target timezone
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: targetTimeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    })
+
+    const parts = formatter.formatToParts(utcDate)
+    const dateParts: Record<string, string> = {}
+
+    parts.forEach((part) => {
+        if (part.type !== 'literal') {
+            dateParts[part.type] = part.value
+        }
+    })
+
+    return `${dateParts['year']}-${dateParts['month']}-${dateParts['day']} ${dateParts['hour']}:${dateParts['minute']}:${dateParts['second']}`
+}
+
+/**
+ * Formats time data (hours, minutes, seconds) as a datetime string without timezone conversion.
+ * Used for storing the original user-entered time value in the 'entered_time' field.
+ *
+ * @param timeData - Object containing hours, minutes, and seconds
+ * @returns Formatted datetime string in 'YYYY-MM-DD HH:MM:SS' format with epoch date (1970-01-01)
+ *
+ * @example
+ * formatTimeDataToDateTime({ hours: 14, minutes: 30, seconds: 0 })
+ * // Returns '1970-01-01 14:30:00'
+ */
+export function formatTimeDataToDateTime(timeData: { hours?: number; minutes?: number; seconds?: number }): string {
+    const hours = String(timeData.hours || 0).padStart(2, '0')
+    const minutes = String(timeData.minutes || 0).padStart(2, '0')
+    const seconds = String(timeData.seconds || 0).padStart(2, '0')
+    return `1970-01-01 ${hours}:${minutes}:${seconds}`
+}

package/src/script-action-plugin.ts

@@ -1,9 +1,11 @@
 import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
 import { ModuleFunctionShape } from './server-module-plugin'
+import { createSdkDocEntry } from './utils'
 
 export const ScriptActionPlugin = Plugin.create({
     name: 'ScriptActionPlugin',
+    docs: [createSdkDocEntry('ScriptAction', ['sysevent_script_action'])],
     records: {
         sysevent_script_action: {
             toShape(record) {

package/src/script-include-plugin.ts

@@ -1,11 +1,13 @@
 import { CallExpressionShape, isSNScope, Plugin } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
 import { NowIncludeShape } from './now-include-plugin'
+import { createSdkDocEntry } from './utils'
 
 const nameRegex = /^[a-zA-Z_$][0-9a-zA-Z_$]+$/
 
 export const ScriptIncludePlugin = Plugin.create({
     name: `ScriptIncludePlugin`,
+    docs: [createSdkDocEntry('ScriptInclude', ['sys_script_include'])],
     records: {
         sys_script_include: {
             async toShape(record, { transform }) {

package/src/server-module-plugin/index.ts

@@ -351,6 +351,7 @@ function getModuleDependencyPath(
 
 export const ServerModulePlugin = Plugin.create({
     name: 'ServerModulePlugin',
+    docs: [],
     files: [
         {
             entryPoint: true,
@@ -432,6 +433,16 @@ export const ServerModulePlugin = Plugin.create({
                     return { success: false }
                 }
 
+                // Lint local module for Rhino compatibility (no Glide restrictions)
+                if (/\.(js|cjs|mjs|ts)$/.test(pathModule.extname(resolvedPath))) {
+                    const { LocalModuleLint } = await import('../repack/lint/index.js')
+                    const lint = new LocalModuleLint()
+                    const lintResult = lint.check(content)
+                    if (lintResult) {
+                        diagnostics.error(file, `Unsupported APIs detected in module:\n${lintResult}`)
+                    }
+                }
+
                 const relativePath = pathModule.relative(project.getRootDir(), resolvedPath)
                 const sysModulePath = NowConfig.moduleResolutionPath(config, packageJson, false, relativePath)
 
@@ -487,6 +498,7 @@ export const ServerModulePlugin = Plugin.create({
 
                 const modules: { id: string; path: string; content: string }[] = []
                 const { Lint } = await import('../repack/lint/index.js')
+                const lint = new Lint()
                 for (const node of dependencyNodes) {
                     const { packagePath, files, updatedManifest, originalPath } = node
                     const { name, version } = updatedManifest
@@ -499,8 +511,8 @@ export const ServerModulePlugin = Plugin.create({
                     )
                     for (const file of files) {
                         const fileContent = fs.readFileSync(pathModule.join(packagePath, file)).toString('utf-8')
-                        if (/(.js|.cjs|.mjs)$/.test(pathModule.extname(file))) {
-                            const result = await new Lint().check(fileContent)
+                        if (/\.(js|cjs|mjs)$/.test(pathModule.extname(file))) {
+                            const result = lint.check(fileContent)
                             if (result) {
                                 logger.warn(`Use of unsupported APIs detected in npm dependency ${name}`)
                                 logger.warn(result)

package/src/service-catalog/catalog-clientscript-plugin.ts

@@ -11,9 +11,11 @@ import {
     resolveAndValidateVariableId,
 } from './utils'
 import { validateCatalogItemVariableSetExclusivity } from './service-catalog-diagnostics'
+import { createSdkDocEntry } from '../utils'
 
 export const CatalogClientScriptPlugin = Plugin.create({
     name: 'CatalogClientScriptPlugin',
+    docs: [createSdkDocEntry('CatalogClientScript', ['catalog_script_client'])],
     records: {
         catalog_script_client: {
             async toShape(record, { database, transform }) {

package/src/service-catalog/catalog-item-plugin.ts

@@ -14,6 +14,7 @@ import {
     createScript,
 } from './utils'
 import { validateFulfillmentProcessExclusivity, validateCategoriesRequireCatalogs } from './service-catalog-diagnostics'
+import { createSdkDocEntry } from '../utils'
 import {
     buildVariablesSchema,
     CatalogItemBaseRelationships,
@@ -27,6 +28,7 @@ import {
 
 export const CatalogItemPlugin = Plugin.create({
     name: 'CatalogItemPlugin',
+    docs: [createSdkDocEntry('CatalogItem', ['sc_cat_item'])],
     records: {
         sc_cat_item: {
             relationships: CatalogItemBaseRelationships,

package/src/service-catalog/catalog-ui-policy-plugin.ts

@@ -25,6 +25,7 @@ import {
     getValueActionToDb,
 } from './utils'
 import { validateCatalogItemVariableSetExclusivity, validateUiPolicyActionMessage } from './service-catalog-diagnostics'
+import { createSdkDocEntry } from '../utils'
 
 // Define table names as constants since they're not exported from the core tables
 const CATALOG_UI_POLICY = 'catalog_ui_policy'
@@ -50,6 +51,7 @@ const stripIOPrefix = (value: string): string => {
 
 export const CatalogUiPolicyPlugin = Plugin.create({
     name: 'CatalogUiPolicyPlugin',
+    docs: [createSdkDocEntry('CatalogUiPolicy', ['catalog_ui_policy'])],
     records: {
         [CATALOG_UI_POLICY]: {
             relationships: {

package/src/service-catalog/sc-record-producer-plugin.ts

@@ -28,9 +28,11 @@ import {
 } from './service-catalog-base'
 import { validateFulfillmentProcessExclusivity, validateCategoriesRequireCatalogs } from './service-catalog-diagnostics'
 import { ModuleFunctionShape } from '../server-module-plugin'
+import { createSdkDocEntry } from '../utils'
 
 export const CatalogItemRecordProducerPlugin = Plugin.create({
     name: 'CatalogItemRecordProducerPlugin',
+    docs: [createSdkDocEntry('CatalogItemRecordProducer', ['sc_cat_item_producer'])],
     records: {
         sc_cat_item_producer: {
             relationships: CatalogItemBaseRelationships,

package/src/service-catalog/service-catalog-diagnostics.ts

@@ -156,6 +156,36 @@ export function validateMandatoryReadOnlyHidden(config: ObjectShape, diagnostics
     return true
 }
 
+/**
+ * Validates that selectionRequired is not true when hidden or readOnly is true, and vice versa.
+ * This is specific to Checkbox variables which use selectionRequired instead of mandatory.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateSelectionRequiredReadOnlyHidden(config: ObjectShape, diagnostics: Diagnostics): boolean {
+    const isSelectionRequired =
+        config.get('selectionRequired').isDefined() && config.get('selectionRequired').ifBoolean()?.getValue() === true
+    const isReadOnly = config.get('readOnly').isDefined() && config.get('readOnly').ifBoolean()?.getValue() === true
+    const isHidden = config.get('hidden').isDefined() && config.get('hidden').ifBoolean()?.getValue() === true
+
+    if (isSelectionRequired && isReadOnly) {
+        diagnostics.error(
+            config.get('selectionRequired'),
+            `'selectionRequired' cannot be true when 'readOnly' is true. A checkbox cannot be both required and read-only.`
+        )
+        return false
+    }
+
+    if (isSelectionRequired && isHidden) {
+        diagnostics.error(
+            config.get('selectionRequired'),
+            `'selectionRequired' cannot be true when 'hidden' is true. A checkbox cannot be both required and hidden.`
+        )
+        return false
+    }
+
+    return true
+}
+
 /**
  * Validates lookup variable configuration: table-based and choice-based properties are mutually exclusive,
  * and price fields are not allowed when uniqueValuesOnly is true.

package/src/service-catalog/shape-to-record.ts

@@ -11,6 +11,7 @@ import { convertRolesToString, getVisibilityId, validateFieldNameBelongsToTable
 import {
     validateMapToFieldRequiresField,
     validateMandatoryReadOnlyHidden,
+    validateSelectionRequiredReadOnlyHidden,
     validateLookupSourceExclusivity,
     validateReferenceQualifierExclusivity,
 } from './service-catalog-diagnostics'
@@ -59,7 +60,9 @@ export async function buildVariableRecords(options: {
         }
 
         // Validate mandatory/readOnly/hidden consistency (applies to interactive variables)
-        if (
+        if (calleeName === VariableTypeName.CHECKBOX) {
+            validateSelectionRequiredReadOnlyHidden(config, diagnostics)
+        } else if (
             calleeName !== VariableTypeName.BREAK &&
             calleeName !== VariableTypeName.CONTAINER_END &&
             calleeName !== VariableTypeName.CONTAINER_SPLIT &&
@@ -112,7 +115,10 @@ export async function buildVariableRecords(options: {
                 question_text: $.from('question').def(''),
                 order: $.def(0),
                 active: $.from('active').toBoolean().def(true),
-                mandatory: $.from('mandatory').toBoolean().def(false),
+                mandatory:
+                    calleeName === VariableTypeName.CHECKBOX
+                        ? $.from('selectionRequired').toBoolean().def(false)
+                        : $.from('mandatory').toBoolean().def(false),
                 read_only: $.from('readOnly').toBoolean().def(false),
                 hidden: $.from('hidden').toBoolean().def(false),
                 disable_initial_slot_fill: $.from('disableInitialSlotFill').toBoolean().def(false),

package/src/service-catalog/variable-set-plugin.ts

@@ -20,9 +20,11 @@ import {
     getVariableSetTypeFromDb,
     getVariableSetTypeToDb,
 } from './utils'
+import { createSdkDocEntry } from '../utils'
 
 export const VariableSetPlugin = Plugin.create({
     name: 'VariableSetPlugin',
+    docs: [createSdkDocEntry('VariableSet', ['item_option_new_set'])],
     records: {
         item_option_new_set: {
             relationships: {

package/src/service-portal/angular-provider-plugin.ts

@@ -1,8 +1,10 @@
 import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { NowIdShape } from '../now-id-plugin'
+import { createSdkDocEntry } from '../utils'
 
 export const SPAngularProviderPlugin = Plugin.create({
     name: 'SPAngularProviderPlugin',
+    docs: [createSdkDocEntry('SPAngularProvider', ['sp_angular_provider'])],
     records: {
         sp_angular_provider: {
             relationships: {

package/src/service-portal/dependency-plugin.ts

@@ -1,17 +1,12 @@
-import {
-    CallExpressionShape,
-    type Diagnostics,
-    type Factory,
-    Plugin,
-    type Record,
-    type Shape,
-    type RecordId,
-} from '@servicenow/sdk-build-core'
+import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { toReference } from '../utils'
 import { NowIdShape } from '../now-id-plugin'
+import { createSdkDocEntry } from '../utils'
+import { getIncludeRecords } from './utils'
 
 export const SPWidgetDependencyPlugin = Plugin.create({
     name: 'SPWidgetDependencyPlugin',
+    docs: [createSdkDocEntry('SPWidgetDependency', ['sp_dependency'])],
     records: {
         sp_dependency: {
             relationships: {
@@ -217,6 +212,7 @@ export const SPWidgetDependencyPlugin = Plugin.create({
                     factory,
                     'm2m_sp_dependency_css_include',
                     'sp_css_include',
+                    'sp_dependency',
                     diagnostics
                 )
 
@@ -226,6 +222,7 @@ export const SPWidgetDependencyPlugin = Plugin.create({
                     factory,
                     'm2m_sp_dependency_js_include',
                     'sp_js_include',
+                    'sp_dependency',
                     diagnostics
                 )
 
@@ -237,47 +234,3 @@ export const SPWidgetDependencyPlugin = Plugin.create({
         },
     ],
 })
-
-async function getIncludeRecords(
-    shape: Shape,
-    dependencyId: Shape,
-    factory: Factory,
-    m2mTable: string,
-    includeTable: string,
-    diagnostics: Diagnostics
-) {
-    return (
-        await Promise.all(
-            shape?.ifArray()?.map(async (include) => {
-                const includeProps = include.ifObject()?.get('include')
-
-                let includeId: string | RecordId
-                if (includeProps?.isString()) {
-                    includeId = includeProps.toString().getValue()
-                } else if (includeProps?.isRecord()) {
-                    includeId = includeProps.getId()
-                } else {
-                    const necessaryPlugin = includeTable === 'sp_js_include' ? 'JsInclude' : 'CssInclude'
-                    diagnostics.error(
-                        includeProps!,
-                        `include must contain a valid ${necessaryPlugin}, Record<'${includeTable}'> or sys_id'`
-                    )
-                    return undefined
-                }
-
-                const m2mProps = {
-                    [includeTable]: includeId,
-                    sp_dependency: dependencyId,
-                }
-                return await factory.createRecord({
-                    source: shape,
-                    table: m2mTable,
-                    properties: {
-                        order: include.ifObject()?.get('order').asNumber().getValue() || 100,
-                        ...m2mProps,
-                    },
-                })
-            }) ?? []
-        )
-    ).filter((rec) => rec) as Record[]
-}