@servicenow/sdk-build-plugins 2.0.1

package/src/scriptedRESTAPI/RestApiPlugin.ts

@@ -0,0 +1,438 @@
+import { RestApi, RestApiConfig, RestApiSchema, Version } from '@servicenow/sdk-core/runtime/rest'
+import { Record, RecordWithLegacyId } from '@servicenow/sdk-core/runtime/db'
+import {
+    linkDocument,
+    Context,
+    Plugin,
+    Document,
+    extractCallExpression,
+    getCallExpressionName,
+    generateCallExpressionExportForDocument,
+    getOrCreateEntitySourceFile,
+    getSysUpdateName,
+    EntityData,
+    ObjectData,
+} from '@servicenow/sdk-build-core'
+import { RecordPlugin } from '../db/RecordPlugin'
+import { buildScriptImport, scriptInfo, type ScriptInfo } from '../scripts/scriptUtils'
+import {
+    EnforceAcl,
+    mergeACLIds,
+    generateVersionRecords,
+    generateRoutesAndRouteAttrRecords,
+} from './RESTSerializationUtils'
+import * as ts from 'ts-morph'
+import {
+    transformDefinition,
+    transformRestAttrs,
+    transformRouteAttrs,
+    transformRouteAttrsMap,
+    transformRoutes,
+} from './RESTDeserializationUtils'
+import { RestRouteHeaderMap, RestRouteQueryMap } from './RestSchemaUtils'
+import {
+    getRestDocumentMap,
+    getRouteAttrResult,
+    getRouteAttrMapResult,
+    getRouteAttrWithRecordNodeResult,
+    getRouteAttrWithRestNodeResult,
+    getRouteAttrMapWithRecordNodeResult,
+    getRouteAttrMapWithRestNodeResult,
+    handleAndReturnResult,
+    createRecordCall,
+    restTables,
+    unHandledIds,
+    completelyUnassociatedParamIds,
+    potentialRecordCallRouteParams,
+} from './RestUtils'
+import * as z from 'zod'
+import { Diagnostic } from '@servicenow/sdk-project'
+
+const methodsAllowedToOverrideRequests = ['PUT', 'PATCH', 'POST']
+const parseAcls = (enforce_acl: EnforceAcl, context: Context) =>
+    enforce_acl.map((acl) => (typeof acl === 'string' ? acl : context.keys.registerExplicitId(acl.table, acl.$id)))
+
+function restApiAsRecord<I extends number, V extends Version<I>>(config: RestApiConfig<I, V>) {
+    const api = RestApiSchema.parse(config)
+    return Record({
+        table: 'sys_ws_definition',
+        $id: api.$id,
+        data: {
+            active: api.active,
+            name: api.name,
+            consumes: api.consumes,
+            consumes_customized: api.consumes === RestApiSchema.shape.consumes._def.defaultValue() ? false : true,
+            produces: api.produces,
+            produces_customized: api.produces === RestApiSchema.shape.produces._def.defaultValue() ? false : true,
+            default_version: '',
+            doc_link: api.doc_link,
+            is_versioned: false,
+            service_id: api.service_id,
+            short_description: api.short_description,
+            base_uri: '',
+            namespace: '',
+            enforce_acl: api.enforce_acl as any,
+            ...(api.policy && { sys_policy: api.policy }),
+        },
+    })
+}
+
+export default Plugin({
+    name: 'RestApi',
+    ownedTables: {
+        sys_ws_definition: { diagnosticLevel: Diagnostic.Level.Warn },
+        sys_ws_version: { diagnosticLevel: Diagnostic.Level.Warn },
+        sys_ws_operation: { diagnosticLevel: Diagnostic.Level.Warn },
+    },
+    extractors: {
+        entity: {
+            CallExpression: (node, context) => {
+                const result = extractCallExpression(RestApi, 'restApi', node, context, (restApi) =>
+                    context.registerExplicitId('sys_ws_definition', restApi.$id as string)
+                )
+
+                if (!result.handled || !(0 in result.data)) {
+                    return result
+                }
+
+                const restAPIEntity = result.data[0]
+                const entityData = RestApiSchema.parse(restAPIEntity.getValue())
+                const { routes, enforce_acl, consumes, produces } = entityData
+                for (const route of routes) {
+                    const { enforce_acl } = route
+                    const rawOperationScript = route.script as unknown as ScriptInfo | string
+                    route.name = route.name ? route.name : route.path
+
+                    if (typeof rawOperationScript !== 'string') {
+                        const { filePath, functionName, isDefault } = rawOperationScript
+                        route.script = buildScriptImport(
+                            filePath,
+                            functionName,
+                            isDefault,
+                            context,
+                            (funcName: string) => `${funcName}(request, response)\n`
+                        )
+                    }
+
+                    /** allow users to override consumes for allowed http methods*/
+                    if (
+                        route.consumes &&
+                        route.consumes !== consumes &&
+                        !methodsAllowedToOverrideRequests.includes(route.method)
+                    ) {
+                        throw Error(`Cannot override consumer type for ${route.method} method`)
+                    }
+
+                    route.consumes = route.consumes ? route.consumes : consumes
+                    route.produces = route.produces ? route.produces : produces
+                    route.enforce_acl = parseAcls(enforce_acl, context)
+                }
+
+                return {
+                    handled: true,
+                    diagnostics: result.diagnostics,
+                    data: [
+                        new EntityData(
+                            restAPIEntity.getKind(),
+                            restAPIEntity.getGuid(),
+                            ObjectData.fromObjectValue(
+                                {
+                                    ...entityData,
+                                    enforce_acl: parseAcls(enforce_acl, context),
+                                },
+                                restAPIEntity.getNode()
+                            ),
+                            restAPIEntity.getNode()
+                        ),
+                    ],
+                }
+            },
+        },
+        raw: {
+            FunctionDeclaration(node, context) {
+                const info = scriptInfo(node, context, RestApi.name)
+                if (!info) {
+                    return { handled: false }
+                }
+
+                return { handled: true, diagnostics: [], data: [info] }
+            },
+
+            FunctionExpression(node, context) {
+                const info = scriptInfo(node, context, RestApi.name)
+                if (!info) {
+                    return { handled: false }
+                }
+
+                return { handled: true, diagnostics: [], data: [info] }
+            },
+        },
+    },
+    composers: {
+        entity: {
+            restApi(entity, context) {
+                const restEntity = entity.getValue()
+                const parsedEntity = RestApiSchema.safeParse(restEntity)
+                if (!parsedEntity.success) {
+                    return
+                }
+
+                const { routes, versions, enforce_acl } = parsedEntity.data
+                const defaultVersions = versions.filter((version) => version.is_default)
+                if (defaultVersions.length > 1) {
+                    throw Error(`Multiple versions cannot be set to default.`)
+                }
+
+                const {
+                    app: {
+                        config: { scope },
+                    },
+                } = context
+                const restRecord = restApiAsRecord(restEntity as any) as RecordWithLegacyId<'sys_ws_definition'>
+                const apiData = { ...restRecord.data }
+
+                apiData.base_uri = `/api/${scope}/${apiData.service_id}`
+                apiData.namespace = scope
+                apiData.default_version =
+                    defaultVersions.length > 0 ? `v${defaultVersions[0]!.version}` : 'No active default version'
+                apiData.enforce_acl = mergeACLIds(enforce_acl) as any
+                apiData.is_versioned = versions.length > 0 ? true : false
+
+                /** generates sys_ws_definition record */
+                const updatedRestRecord = Record({
+                    table: 'sys_ws_definition',
+                    $id: entity.getGuid(),
+                    data: apiData,
+                })
+
+                /** generates the sys_ws_version record */
+                const versionRecordsAndMap = generateVersionRecords(
+                    context,
+                    apiData.default_version,
+                    versions,
+                    updatedRestRecord
+                )
+
+                /** generates the sys_ws_operation, sys_ws_header, sys_ws_header_map, sys_ws_query_paramter, sys_ws_query_parameter_map records */
+                const routesAndRouteAttrRecords = generateRoutesAndRouteAttrRecords(
+                    context,
+                    restRecord.$id,
+                    routes,
+                    apiData,
+                    updatedRestRecord,
+                    versionRecordsAndMap.mapping
+                )
+
+                return context.composeEntities(
+                    [updatedRestRecord, ...versionRecordsAndMap.records, ...routesAndRouteAttrRecords].map(
+                        (r) =>
+                            new EntityData(
+                                'record',
+                                r.$id as string,
+                                ObjectData.fromObjectValue(r, entity.getNode()),
+                                entity.getNode()
+                            )
+                    ),
+                    [RecordPlugin]
+                )
+            },
+        },
+    },
+    arrangers: {
+        record(document, context) {
+            const table = document.data!['table']
+            /** skipping arrangers while serializing as we don't care about the order here. */
+            if (!restTables.includes(table) || context.mode === 'serialize') {
+                return { handled: false }
+            }
+
+            /** generates rest document map and validates the params and their mapping records */
+            const restDocMap = getRestDocumentMap(context)
+            switch (table) {
+                case 'sys_ws_operation':
+                case 'sys_ws_version':
+                    return {
+                        handled: true,
+                        result: { kind: 'record', guid: document.data!['data']['web_service_definition'] },
+                    }
+                case 'sys_ws_header':
+                case 'sys_ws_query_parameter':
+                    if (!document.node) {
+                        /** handles case where the incoming xml doesn't have any node associated with it. */
+                        return handleAndReturnResult(getRouteAttrResult(document, restDocMap), document)
+                    } else {
+                        const docNode = document.node as ts.CallExpression
+                        if (getCallExpressionName(docNode) === Record.name) {
+                            /** handles case where the incoming xml is currently associated with record call */
+                            return handleAndReturnResult(
+                                getRouteAttrWithRecordNodeResult(document, context, restDocMap),
+                                document
+                            )
+                        } else {
+                            /** handles case where the incoming xml is currently associated with rest call */
+                            return handleAndReturnResult(
+                                getRouteAttrWithRestNodeResult(document, context, restDocMap),
+                                document
+                            )
+                        }
+                    }
+                case 'sys_ws_header_map':
+                case 'sys_ws_query_parameter_map':
+                    if (!document.node) {
+                        /** handles case where the incoming xml doesn't have any node associated with it. */
+                        return handleAndReturnResult(getRouteAttrMapResult(document, restDocMap), document)
+                    } else {
+                        const docNode = document.node as ts.CallExpression
+                        if (getCallExpressionName(docNode) === Record.name) {
+                            /** handles case where the incoming xml is currently associated with record call */
+                            return handleAndReturnResult(
+                                getRouteAttrMapWithRecordNodeResult(document, context, restDocMap),
+                                document
+                            )
+                        } else {
+                            /** handles case where the incoming xml is currently associated with rest call */
+                            return handleAndReturnResult(
+                                getRouteAttrMapWithRestNodeResult(document, context, restDocMap),
+                                document
+                            )
+                        }
+                    }
+                default:
+                    return { handled: true, result: undefined }
+            }
+        },
+    },
+    generators: {
+        record(document, context, linkedDocuments) {
+            const table = document.data!['table']
+            /**
+             * Edge case: m2m record maps non-app rest causing you to unassociate the only associated
+             * param record to rest. May require creation of record call for unassociated param if not consumed
+             * by any
+             */
+            completelyUnassociatedParamIds.forEach((id) => {
+                if (potentialRecordCallRouteParams.has(id)) {
+                    createRecordCall(id, context)
+                    potentialRecordCallRouteParams.delete(id)
+                }
+            })
+            completelyUnassociatedParamIds.clear()
+            /** unHandledIds contains rest record ids for which we need to create record call */
+            if (!restTables.includes(table) || unHandledIds.includes(document.guid)) {
+                return undefined
+            }
+
+            switch (table) {
+                case 'sys_ws_definition':
+                    // eslint-disable-next-line no-case-declarations
+                    const linkedDoc = linkDocument(
+                        document,
+                        generateCallExpressionExportForDocument(
+                            context,
+                            {
+                                sourceFile: getOrCreateEntitySourceFile(
+                                    context,
+                                    getSysUpdateName(document, 'sys_ws_definition')
+                                ),
+                                moduleSpecifier: '@servicenow/sdk/core',
+                            },
+                            RestApi,
+                            {}
+                        ).getExpressionIfKindOrThrow(ts.SyntaxKind.CallExpression)
+                    )
+                    return linkedDoc
+                case 'sys_ws_operation':
+                case 'sys_ws_version':
+                case 'sys_ws_header':
+                case 'sys_ws_query_parameter':
+                    // eslint-disable-next-line no-case-declarations
+                    const restDef = linkedDocuments.find(
+                        (doc) =>
+                            (doc.data as any).table === 'sys_ws_definition' &&
+                            doc.guid === (document.data as any).data.web_service_definition
+                    )
+                    // eslint-disable-next-line no-case-declarations
+                    const o_v_node = document.parent!.node ? document.parent!.node : restDef?.node
+                    if (!o_v_node) {
+                        return undefined
+                    }
+                    return linkDocument(document, o_v_node as ts.CallExpression<ts.ts.CallExpression>)
+                case 'sys_ws_header_map':
+                case 'sys_ws_query_parameter_map':
+                    // eslint-disable-next-line no-case-declarations
+                    const operationDef = linkedDocuments.find(
+                        (doc) =>
+                            (doc.data as any).table === 'sys_ws_operation' &&
+                            doc.guid === (document.data as any).data.web_service_operation
+                    )
+                    // eslint-disable-next-line no-case-declarations
+                    const h_q_node = document.parent?.node ? document.parent?.node : operationDef?.node
+                    if (!h_q_node) {
+                        return undefined
+                    }
+                    return linkDocument(document, h_q_node as ts.CallExpression<ts.ts.CallExpression>)
+            }
+            return undefined
+        },
+    },
+    transformers: {
+        record: {
+            CallExpression(document, context) {
+                if (!shouldHandle(document)) {
+                    return false
+                }
+
+                const documentMap = context.getDocumentMap()
+                const table = document.data!['table']
+                switch (table) {
+                    case 'sys_ws_definition':
+                        return transformDefinition(document, context)
+                    case 'sys_ws_version':
+                        return transformRestAttrs(document, context)
+                    case 'sys_ws_operation':
+                        return transformRoutes(document, context, documentMap!)
+                    case 'sys_ws_header':
+                        return transformRouteAttrs(document, context, 'headers')
+                    case 'sys_ws_query_parameter':
+                        return transformRouteAttrs(document, context, 'parameters')
+                    case 'sys_ws_query_parameter_map':
+                        return transformRouteAttrsMap(
+                            document,
+                            context,
+                            documentMap!,
+                            RestRouteQueryMap,
+                            'parameters',
+                            (data: z.infer<typeof RestRouteQueryMap>) => {
+                                return {
+                                    operationId: data.web_service_operation,
+                                    attrId: data.web_service_query_parameter,
+                                }
+                            }
+                        )
+                    case 'sys_ws_header_map':
+                        return transformRouteAttrsMap(
+                            document,
+                            context,
+                            documentMap!,
+                            RestRouteHeaderMap,
+                            'headers',
+                            (data: z.infer<typeof RestRouteHeaderMap>) => {
+                                return { operationId: data.web_service_operation, attrId: data.web_service_header }
+                            }
+                        )
+                }
+                return false
+            },
+        },
+    },
+})
+
+function shouldHandle(document: Document): boolean {
+    const docNode = document.node as ts.CallExpression
+    return !docNode.wasForgotten() &&
+        getCallExpressionName(docNode) === RestApi.name &&
+        document.data!['table'] &&
+        docNode.getArguments()[0]
+        ? true
+        : false
+}

package/src/scriptedRESTAPI/RestSchemaUtils.ts

@@ -0,0 +1,72 @@
+import {
+    BaseRestApiSchema,
+    BaseRouteSchema,
+    RouteAttributeSchema,
+    VersionSchema,
+} from '@servicenow/sdk-core/runtime/rest'
+import { z } from 'zod'
+
+export const RestRouteHeaderMap = z.object({
+    web_service_operation: z.string(),
+    web_service_header: z.string(),
+})
+
+export const RestRouteQueryMap = z.object({
+    web_service_operation: z.string(),
+    web_service_query_parameter: z.string(),
+})
+
+export const RouteAttrWithOutIdSchema = RouteAttributeSchema.omit({ $id: true })
+
+export const VersionWithOutIdSchema = VersionSchema.omit({ $id: true })
+
+const RestDefinitionSchema = BaseRestApiSchema.omit({ $id: true }).extend({
+    enforce_acl: z.string().default(''),
+    sys_policy: z.enum(['', 'read', 'protected']).default(''),
+})
+
+export const RestDefinitionTransformer = RestDefinitionSchema.partial().transform((data) => {
+    const { sys_policy, enforce_acl, ...rest } = data
+    return {
+        ...rest,
+        ...(enforce_acl !== undefined && { enforce_acl: enforce_acl ? enforce_acl.split(',') : [] }),
+        ...(sys_policy && { policy: sys_policy }),
+    }
+})
+
+const RestRouteSchema = BaseRouteSchema.omit({ $id: true }).extend({
+    operation_script: z.string().default(''),
+    http_method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('GET'),
+    relative_path: z.string().default('/'),
+    requires_acl_authorization: z.boolean().default(true),
+    requires_authentication: z.boolean().default(true),
+    requires_snc_internal_role: z.boolean().default(true),
+    sys_policy: z.enum(['', 'read', 'protected']).default(''),
+    enforce_acl: z.string().default(''),
+    web_service_version: z.string().default(''),
+})
+
+export const RestRouteTransformer = RestRouteSchema.partial().transform((data) => {
+    const {
+        operation_script,
+        http_method,
+        relative_path,
+        requires_acl_authorization,
+        requires_authentication,
+        requires_snc_internal_role,
+        sys_policy,
+        enforce_acl,
+        ...rest
+    } = data
+    return {
+        ...rest,
+        ...(enforce_acl !== undefined && { enforce_acl: enforce_acl ? enforce_acl.split(',') : [] }),
+        ...(operation_script !== undefined && { script: operation_script }),
+        ...(http_method && { method: http_method }),
+        ...(relative_path && { path: relative_path }),
+        ...(requires_acl_authorization !== undefined && { authorization: requires_acl_authorization }),
+        ...(requires_authentication !== undefined && { authentication: requires_authentication }),
+        ...(requires_snc_internal_role !== undefined && { internalRole: requires_snc_internal_role }),
+        ...(sys_policy && { policy: sys_policy }),
+    }
+})