@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/dist/service-catalog/utils.d.ts

@@ -0,0 +1,323 @@
+export declare const APPLIES_TO_CATALOG_ITEM = "item";
+import { type Record, PropertyAccessShape, IdentifierShape, type Database, TemplateExpressionShape, Shape, type ObjectShape, type Diagnostics, type Transform } from '@servicenow/sdk-build-core';
+import { NowIncludeShape } from '../now-include-plugin';
+/**
+ * Validates that there's at most one RequestedForVariable in a variables configuration (used only for VariableSet)
+ * @param variablesShape - The ObjectShape containing the variables configuration
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @param context - Context where the validation is being performed ('VariableSet')
+ * @returns True if validation passes, false otherwise
+ */
+export declare function validateRequestedForVariable(variablesShape: ObjectShape, diagnostics: Diagnostics, context?: 'VariableSet'): boolean;
+/**
+ * Combined validation for variable sets that performs multiple checks in a single loop:
+ * - At most one RequestedForVariable
+ * - Variable types not supported in multiRow variable sets
+ * @param variablesShape - The ObjectShape containing the variables configuration
+ * @param variableSetType - The type of the variable set ('singleRow' or 'multiRow')
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @param context - Context where the validation is being performed ('VariableSet')
+ * @returns True if validation passes, false otherwise
+ */
+export declare function validateVariableSetVariables(variablesShape: ObjectShape, variableSetType: string, diagnostics: Diagnostics, context?: 'VariableSet'): boolean;
+/**
+ * @deprecated Use validateVariableSetVariables instead
+ * Validates that certain variable types are not used in multiRow variable sets.
+ * MultiRow variable sets don't support certain display/layout variables.
+ * @param variablesShape - The ObjectShape containing the variables configuration
+ * @param variableSetType - The type of the variable set ('singleRow' or 'multiRow')
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @returns True if validation passes, false otherwise
+ */
+export declare function validateVariableTypesForMultiRow(variablesShape: ObjectShape, variableSetType: string, diagnostics: Diagnostics): boolean;
+/**
+ * Optimized validation that checks all RequestedForVariable constraints in a single pass:
+ * - At most one RequestedForVariable in direct variables
+ * - Not used in both direct variables and attached variable sets
+ * - Only one RequestedForVariable across all attached variable sets
+ * @param arg - The ObjectShape containing the catalog item/record producer configuration
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @param context - Context where the validation is being performed ('CatalogItem' or 'RecordProducer')
+ * @returns True if validation passes, false otherwise
+ */
+export declare function validateRequestedForVariableConflict(arg: ObjectShape, diagnostics: Diagnostics, context: 'CatalogItem' | 'RecordProducer'): boolean;
+/**
+ * Validates that variable names (keys) in attached variable sets don't conflict with direct variable names
+ * @param arg - The ObjectShape containing the catalog item/record producer configuration
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @param context - Context where the validation is being performed ('CatalogItem' or 'RecordProducer')
+ * @returns True if validation passes, false otherwise
+ */
+export declare function validateVariableNameConflicts(arg: ObjectShape, diagnostics: Diagnostics, context: 'CatalogItem' | 'RecordProducer'): boolean;
+/**
+ * Safely converts a value to a number with a default fallback
+ * Handles empty strings and undefined values
+ * @param value - The value to convert
+ * @param defaultValue - The default value to use if conversion fails or value is empty/undefined
+ * @returns The converted number or default value
+ */
+export declare function convertToNumber(value: Shape, defaultValue?: number): number;
+export declare function getUITypeFromId(id: number): 'desktop' | 'mobileOrServicePortal' | 'all';
+export declare function getUITypeId(value: string): number;
+/**
+ * Converts ServiceNow variable set type database value to camelCase enum value
+ * @param dbValue - Database value ('one_to_one' or 'one_to_many')
+ * @returns TypeScript enum value ('singleRow' or 'multiRow')
+ */
+export declare function getVariableSetTypeFromDb(dbValue: string): 'singleRow' | 'multiRow';
+/**
+ * Converts TypeScript enum value to ServiceNow variable set type database value
+ * @param value - TypeScript enum value ('singleRow' or 'multiRow')
+ * @returns Database value ('one_to_one' or 'one_to_many')
+ */
+export declare function getVariableSetTypeToDb(value: string): string;
+/**
+ * Converts ServiceNow redirect URL database value to camelCase enum value
+ * @param dbValue - Database value ('generated_record' or 'catalog_home')
+ * @returns TypeScript enum value ('generatedRecord' or 'catalogHomePage')
+ */
+export declare function getRedirectUrlFromDb(dbValue: string): 'generatedRecord' | 'catalogHomePage';
+/**
+ * Converts TypeScript enum value to ServiceNow redirect URL database value
+ * @param value - TypeScript enum value ('generatedRecord' or 'catalogHomePage')
+ * @returns Database value ('generated_record' or 'catalog_home')
+ */
+export declare function getRedirectUrlToDb(value: string): string;
+/**
+ * Converts ServiceNow fulfillment automation level database value to camelCase enum value
+ * @param dbValue - Database value ('unspecified', 'manual', 'semi_automated', or 'fully_automated')
+ * @returns TypeScript enum value ('unspecified', 'manual', 'semiAutomated', or 'fullyAutomated')
+ */
+export declare function getFulfillmentAutomationLevelFromDb(dbValue: string): 'unspecified' | 'manual' | 'semiAutomated' | 'fullyAutomated';
+/**
+ * Converts TypeScript enum value to ServiceNow fulfillment automation level database value
+ * @param value - TypeScript enum value ('unspecified', 'manual', 'semiAutomated', or 'fullyAutomated')
+ * @returns Database value ('unspecified', 'manual', 'semi_automated', or 'fully_automated')
+ */
+export declare function getFulfillmentAutomationLevelToDb(value: string): string;
+/**
+ * Converts ServiceNow availability database value to camelCase enum value
+ * @param dbValue - Database value ('on_desktop', 'on_mobile', or 'on_both')
+ * @returns TypeScript enum value ('desktopOnly', 'mobileOnly', or 'both')
+ */
+export declare function getAvailabilityFromDb(dbValue: string): 'desktopOnly' | 'mobileOnly' | 'both';
+/**
+ * Converts TypeScript enum value to ServiceNow availability database value
+ * @param value - TypeScript enum value ('desktopOnly', 'mobileOnly', or 'both')
+ * @returns Database value ('on_desktop', 'on_mobile', or 'on_both')
+ */
+export declare function getAvailabilityToDb(value: string): string;
+/**
+ * Converts ServiceNow mobile picture type database value to camelCase enum value
+ * @param dbValue - Database value ('use_desktop_picture', 'use_mobile_picture', or 'use_no_picture')
+ * @returns TypeScript enum value ('desktopPicture', 'mobilePicture', or 'noPicture')
+ */
+export declare function getMobilePictureTypeFromDb(dbValue: string): 'desktopPicture' | 'mobilePicture' | 'noPicture';
+/**
+ * Converts TypeScript enum value to ServiceNow mobile picture type database value
+ * @param value - TypeScript enum value ('desktopPicture', 'mobilePicture', or 'noPicture')
+ * @returns Database value ('use_desktop_picture', 'use_mobile_picture', or 'use_no_picture')
+ */
+export declare function getMobilePictureTypeToDb(value: string): string;
+/**
+ * Converts ServiceNow value action database value to camelCase enum value
+ * @param dbValue - Database value ('clear_value', 'set_value', or 'ignore')
+ * @returns TypeScript enum value ('clearValue', 'setValue'), or undefined if 'ignore'
+ */
+export declare function getValueActionFromDb(dbValue: string): 'clearValue' | 'setValue' | undefined;
+/**
+ * Converts TypeScript enum value to ServiceNow value action database value
+ * @param value - TypeScript enum value ('clearValue', 'setValue', or 'ignore')
+ * @returns Database value ('clear_value', 'set_value', or 'ignore')
+ */
+export declare function getValueActionToDb(value: string): string;
+export declare function getVisibilityFromId(id: number): 'Always' | 'Bundle' | 'Standalone';
+export declare function getVisibilityId(value: string): number;
+/**
+ * Finds a variable record from a catalog item's related records by variable name
+ * @param catalogItemRecord - The catalog item Record to search in
+ * @param variableName - The name of the variable to find
+ * @returns The variable record if found, undefined otherwise
+ */
+export declare function findNameInParent(catalogItemRecord: Record, variableName: string): Record | undefined;
+/**
+ * Resolves a variable ID from a parent record and variable name with fallback logic
+ * @param parentRecord - The resolved parent record (may or may not be a Record instance)
+ * @param variableName - The name of the variable to resolve
+ * @returns The formatted variable ID with IO: prefix
+ */
+export declare function resolveVariableId(parentRecord: Record, variableName: string): string;
+/**
+ * Resolves catalog item and variable set references based on the applies_to field
+ * @param record - The source record containing catalog_item/cat_item and variable_set fields
+ * @param database - The database instance for looking up records
+ * @returns Object with catalogItemReference and variableSetReference
+ */
+export declare function resolveCatalogReferences(record: Record, database: Database): {
+    catalogItemReference: IdentifierShape | string | undefined;
+    variableSetReference: IdentifierShape | string | undefined;
+};
+/**
+ * Resolves a record reference (catalog item or variable set) to an IdentifierShape
+ * @param recordId - The sys_id of the record to resolve
+ * @param tableName - The table name ('sc_cat_item' or 'item_option_new_set')
+ * @param database - The database instance for looking up records
+ * @returns IdentifierShape if the record exists and has a name, otherwise the original sys_id or undefined
+ */
+export declare function resolveRecordReference(recordId: string | undefined, tableName: 'sc_cat_item' | 'item_option_new_set', database: Database): IdentifierShape | string | undefined;
+export declare function parentIdentifier(parentRecord: Record): IdentifierShape | undefined;
+/**
+ * Creates a PropertyAccessShape for a catalog variable from an item record
+ * @param itemId - The item_option_new record
+ * @param source - The source record for the PropertyAccessShape
+ * @param parent - The parent record from the record
+ * @returns PropertyAccessShape representing catalogItem.variables.variableName
+ */
+export declare function createVariablePropertyAccess(variableRecord: Record, source: Record, parent: Record): PropertyAccessShape | undefined;
+/**
+ * Resolves the appropriate record for catalog item or variable set operations
+ * @param record - The source record containing catalog_item/cat_item or variable_set references
+ * @param database - The database instance for looking up records by ID
+ * @returns The resolved record (sc_cat_item or item_option_new_set) or undefined if not found
+ */
+export declare function getTargetRecord(record: Record, database: Database): Record | undefined;
+/**
+ * Resolves a variable name from a PropertyAccessShape
+ * @param variableNameShape - The shape containing the property access
+ * @returns An object containing the parent record and variable name
+ */
+export declare function resolveVariableAccess(variableNameShape: PropertyAccessShape): {
+    parentRecord: Record;
+    variableName: string;
+} | undefined;
+/**
+ * Processes a catalog condition template expression
+ * @param conditionShape - The shape containing the catalog condition
+ * @param appliesTo - Optional appliesTo value for validation
+ * @param variableSetShape - Optional variable set shape for validation
+ * @param catalogItemShape - Optional catalog item shape for validation
+ * @param diagnostics - Optional diagnostics instance for reporting validation errors
+ * @returns The processed condition string with resolved variable references
+ */
+export declare function processCatalogCondition(conditionShape: Shape<unknown>, appliesTo?: 'set' | 'item', variableSetShape?: Shape<unknown>, catalogItemShape?: Shape<unknown>, diagnostics?: Diagnostics): string | undefined;
+/**
+ * Represents the result of parsing a single catalog condition part
+ */
+interface ParsedConditionPart {
+    logicalOperator: string;
+    processedContent: string | PropertyAccessShape;
+    operatorSuffix: string;
+    hasPropertyAccess: boolean;
+}
+/**
+ * Parses a single catalog condition part and extracts logical operators and variable references
+ * @param part - The condition part to parse
+ * @param record - The source record
+ * @param database - The database instance for looking up records
+ * @returns Parsed condition part with extracted components
+ */
+export declare function parseConditionPart(part: string, record: Record, database: Database): ParsedConditionPart | undefined;
+/**
+ * Processes catalog conditions and converts them to either a TemplateExpressionShape or a string
+ * @param record - The record containing the catalog conditions
+ * @param database - The database instance for looking up records
+ * @returns The processed conditions as a TemplateExpressionShape or string, or undefined if no conditions
+ */
+export declare function processCatalogConditionsToShape(record: Record, database: Database): TemplateExpressionShape | string | undefined;
+/**
+ * Converts a title to a valid ServiceNow internal name (snake_case)
+ * @param title - The title to convert
+ * @returns Snake_case internal name
+ */
+export declare function convertTitleToInternalName(title: string): string;
+/**
+ * Validation constants for internal names
+ */
+export declare const INTERNAL_NAME_REGEX: RegExp;
+export declare const INTERNAL_NAME_MAX_LENGTH = 80;
+/**
+ * Validates an internal name for ServiceNow compatibility
+ * @param internalName - The internal name to validate
+ * @returns Validation result with error message if invalid
+ */
+export declare function validateInternalName(internalName: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Converts role values (arrays or Role records) to comma-separated string for ServiceNow storage
+ * Handles both string arrays and Role record references
+ * @param v - Shape value containing role data
+ * @returns Comma-separated role string or undefined
+ */
+export declare function convertRolesToString(v: Shape): string | undefined;
+/**
+ * Parses comma-separated string into an array
+ * @param string - Comma-separated string (e.g., "admin,itil")
+ * @returns Array of trimmed strings
+ */
+export declare function parseString(commaSeparatedString: Shape): string[];
+/**
+ * Checks if the record should be written as a call expression
+ * @param record - The record to check
+ * @returns True if the record should be written as a call expression, false otherwise
+ */
+export declare function shouldWriteAsCallExpression(record: Record): boolean;
+/**
+ * Converts a name to a valid JavaScript identifier
+ * Examples:
+ *   "Backend item" -> "backendItem"
+ *   "Developer Workstation" -> "developerWorkstation"
+ *   "My-Special_Item 123" -> "mySpecialItem123"
+ */
+export declare function toValidIdentifier(name: string): string;
+/**
+ * Default delivery time value used when no delivery time is specified
+ */
+export declare const DEFAULT_DELIVERY_TIME = "1970-01-01 00:00:00";
+/**
+ * Creates a NowIncludeShape with a custom file path suffix for script separation
+ */
+export declare function createScript(record: Record, scriptContent: string | Shape, transform: Transform, suffix: string): Promise<NowIncludeShape>;
+/**
+ * Default script
+ */
+export declare const defaultScript = "/** This script is executed before the Record is generated\n* `current`- GlideRecord produced by Record Producer\n* Don't use `current.update()` or `current.insert()` as the record is generated by Record Producer\n* Don't use `current.setValue('sys_class_name', 'xxx')` as this will trigger reparent flow and can cause data loss\n* Avoid `current.setAbortAction()` and generate a separate record\n* Use `producer.var1` to access variables\n*/";
+/**
+ * Default post insert script
+ */
+export declare const defaultpostInsertScript = "/**\n* This script is executed after the record is generated. \n* `current` Is the GlideRecord produced by Record Producer. Use `current.update()` to update the record\n* To access the variables, use `producer.var1` where var1 is the name of the variable\n* To access the Record Producer use `cat_item`\n*/";
+/**
+ * Default save script
+ */
+export declare const defaultSaveScript = "/**\n* This script is executed at every step save in Catalog Builder. \n* This script is executed before `Script` is executed.\n* `current` Is the GlideRecord produced by Record Producer. \n* To access the variables, use `producer.var1` where var1 is the name of the variable\n* To access the Record Producer use `cat_item`\n*/";
+/**
+ * Validates that a variable belongs to a target record (variable set or catalog item)
+ * Reports diagnostic error if validation fails
+ * @param targetShape - The IdentifierShape for the target reference (variable set or catalog item)
+ * @param parentRecord - The parent record where the variable is defined
+ * @param appliesTo - Whether the validation is for 'set' (variable set) or 'item' (catalog item)
+ * @param diagnostics - Optional diagnostics instance for reporting errors
+ * @returns true if the variable belongs to the target, false otherwise
+ */
+export declare function validateVariableBelongsToTarget(targetShape: IdentifierShape, parentRecord: Record, appliesTo: 'set' | 'item', diagnostics?: Diagnostics): boolean;
+/**
+ * Resolves a variable ID from variableNameShape and validates it belongs to the variable set if appliesTo is 'set'
+ * @param variableNameShape - The shape from get('variableName', false)
+ * @param appliesTo - The value from get('appliesTo')
+ * @param variableSetShape - The shape from get('variableSet', false)
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @returns The resolved variable ID with IO: prefix, or undefined if resolution fails
+ */
+export declare function resolveAndValidateVariableId(variableNameShape: Shape<unknown> | undefined, appliesTo: 'set' | 'item', variableSetShape: Shape<unknown> | undefined, catalogItemShape: Shape<unknown> | undefined, diagnostics: Diagnostics): string | undefined;
+/**
+ * Validates that each variable's 'field' value (when 'mapToField' is true) belongs to the record producer's target table.
+ * Resolves the table record from arg.get('table'), collects field names from sys_documentation descendants via .flat(),
+ * and checks each variable's 'field' against those keys.
+ * @param arg - The ObjectShape containing the record producer configuration
+ * @param diagnostics - Diagnostics instance for reporting errors
+ * @param context - Context where the validation is being performed ('RecordProducer')
+ * @returns True if all mapped fields belong to the table, false otherwise
+ */
+export declare function validateFieldNameBelongsToTable(arg: ObjectShape, diagnostics: Diagnostics, context: string): boolean;
+export {};