@servicenow/sdk-build-core 4.2.0 → 4.4.0

package/src/telemetry/clients/browser-client.ts

@@ -0,0 +1,160 @@
+import type { TelemetryEvent, TelemetryEventData, Datapoint, HeartbeatBody } from '../types'
+import { NETWORK_TIMEOUT_MS, DatapointType, type InstanceSettings } from '../types'
+import { AbstractAppSeeClient } from './abstract-client'
+
+export class BrowserTelemetryClient extends AbstractAppSeeClient {
+    constructor(
+        config: InstanceSettings,
+        telemetryAttributes?: {
+            sdkVersion?: string
+            clientName?: 'ide' | string
+            hostname?: string
+            ideVersion?: string
+        }
+    ) {
+        const { ideVersion, ...baseAttributes } = telemetryAttributes ?? {}
+        super(config, {
+            ...baseAttributes,
+            clientName: telemetryAttributes?.clientName ?? 'ide',
+        })
+
+        this.ideVersion = ideVersion
+    }
+
+    private readonly ideVersion: string | undefined
+    private userId?: string
+
+    private async getUserHash() {
+        const userUniqueId = await this.getUserIdentifier()
+        const bytes = new TextEncoder().encode(userUniqueId)
+        const byteHash = await crypto.subtle.digest('SHA-256', bytes)
+        const hashArray = Array.from(new Uint8Array(byteHash))
+        return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')
+    }
+
+    private async getUserIdentifier(): Promise<string> {
+        if (typeof window === 'undefined') {
+            return 'unknown'
+        }
+
+        const storageKey = 'sdk_telemetry_user_id'
+        try {
+            let userId = localStorage.getItem(storageKey)
+
+            if (!userId) {
+                userId = `anon_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`
+                localStorage.setItem(storageKey, userId)
+            }
+
+            return userId
+        } catch {
+            return `temp_${Math.random().toString(36).substring(2, 15)}`
+        }
+    }
+
+    private generateHexString(): string {
+        return crypto.randomUUID()
+    }
+
+    override async doStart(): Promise<void> {
+        try {
+            if (this.session) {
+                return
+            }
+
+            this.userId = await this.getUserHash()
+
+            const tabId = this.generateHexString()
+            const body = {
+                RequestId: this.generateHexString(),
+                TabId: tabId,
+                SystemLocale: navigator.language ?? 'unknown',
+                AppUserId: this.userId,
+                ScreenHeight: typeof screen !== 'undefined' ? screen.height : 0,
+                ScreenWidth: typeof screen !== 'undefined' ? screen.width : 0,
+                ClientTime: new Date().toISOString(),
+                TrackingLevel: 'Full',
+            }
+
+            const response = await fetch(new URL('/web/config', this.config.BaseUrl), {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+            })
+
+            const bodyResponse = await response.json()
+            if (response.ok) {
+                this.session = { ...bodyResponse, TabId: tabId }
+            } else {
+                throw new Error(`Failed to start session with status ${response.status}: ${bodyResponse.Error}`)
+            }
+        } catch (_error) {}
+    }
+
+    override doSendEvent(events: TelemetryEvent | TelemetryEvent[]): void {
+        try {
+            if (!this.session) {
+                return
+            }
+
+            const defaultValues = this.getDefaultDataValues()
+            const eventData = Array.isArray(events) ? events : [events]
+            const now = Date.now()
+            const hostname = this.hostname ? { hostname: this.hostname } : {}
+
+            const dataPoints = eventData.map<Datapoint>((d) => ({
+                t: DatapointType.Event,
+                d: now,
+                n: d.name,
+                p: { scopeId: d.appInfo?.scopeId, ...hostname, ...defaultValues, ...d.data },
+            }))
+
+            const userProps = { hostname } //does CI make sense for browser environment ??
+
+            dataPoints.push({
+                t: DatapointType.User,
+                d: now,
+                n: this.userId!,
+                p: userProps,
+            })
+
+            const body: HeartbeatBody = {
+                SessionId: this.session.SessionId,
+                DataPoints: dataPoints,
+                TabId: this.session.TabId || '0',
+                ClientTime: new Date().toISOString(),
+                ConfigReceivedTime: new Date().toISOString(),
+            }
+
+            fetch(new URL('/web/heartbeat', this.config.BaseUrl), {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+            }).catch(() => {})
+        } catch (_error) {}
+    }
+
+    private getHeaders() {
+        return {
+            APIKey: this.config.APIKey,
+            APIAuth: this.config.APIAuth,
+            BrowserId: '0',
+            ClientId: this.session?.ClientId || '0',
+            Version: this.sdkVersion || 'unknown',
+            'Content-Type': 'application/json',
+        }
+    }
+
+    private getDefaultDataValues() {
+        const defaultValues: TelemetryEventData = {
+            browser: navigator.userAgent || 'unknown',
+            version: this.sdkVersion || 'unknown',
+            clientName: this.clientName,
+            ideVersion: this.ideVersion || 'unknown',
+        }
+
+        return defaultValues
+    }
+}

package/src/telemetry/clients/node-client.ts

@@ -0,0 +1,151 @@
+import * as os from 'os'
+import ciInfo from 'ci-info'
+import { NETWORK_TIMEOUT_MS, DatapointType } from '../types'
+import type { TelemetryEvent, TelemetryEventData, Datapoint, HeartbeatBody, InstanceSettings } from '../types'
+import { AbstractAppSeeClient } from './abstract-client'
+
+function generateHexString() {
+    // biome-ignore lint/style/noRestrictedImports: <explanation>
+    const crypto = require('node:crypto')
+    return crypto.randomBytes(16).toString('hex')
+}
+
+async function getUserHash() {
+    const user = `${os.userInfo().username}:${os.hostname()}`
+    if (!user) {
+        return 'unknown'
+    }
+
+    const bytes = new TextEncoder().encode(user)
+    const byteHash = await crypto.subtle.digest('SHA-256', bytes)
+    return Buffer.from(byteHash).toString('hex')
+}
+
+export class NodeTelemetryClient extends AbstractAppSeeClient {
+    constructor(
+        config: InstanceSettings,
+        telemetryAttributes?: { sdkVersion?: string; clientName?: 'cli' | string; hostname?: string }
+    ) {
+        super(config, {
+            ...(telemetryAttributes ?? {}),
+            clientName: telemetryAttributes?.clientName ?? 'cli',
+        })
+    }
+
+    private userId?: string
+
+    override async doStart(): Promise<void> {
+        try {
+            if (this.session) {
+                return
+            }
+
+            this.userId = await getUserHash()
+
+            const tabId = generateHexString()
+            const body = {
+                RequestId: generateHexString(),
+                TabId: tabId,
+                SystemLocale: (process.env['LANG'] || 'unknown').split('.')[0],
+                AppUserId: this.userId,
+                ScreenHeight: 0,
+                ScreenWidth: 0,
+                ClientTime: new Date().toISOString(),
+                TrackingLevel: 'Full',
+            }
+
+            const response = await fetch(new URL('/web/config', this.config.BaseUrl), {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+            })
+
+            const bodyResponse = await response.json()
+            if (response.ok) {
+                this.session = { ...bodyResponse, TabId: tabId }
+            } else {
+                throw new Error(`Failed to start session with status ${response.status}: ${bodyResponse.Error}`)
+            }
+        } catch (_error) {
+            //ignore
+        }
+    }
+
+    override doSendEvent(events: TelemetryEvent | TelemetryEvent[]): void {
+        try {
+            //Check if we have a session
+            if (!this.session) {
+                return
+            }
+
+            const defaultValues = this.getDefaultDataValues()
+            const eventData = Array.isArray(events) ? events : [events]
+            const now = Date.now()
+            const hostname = this.hostname ? { hostname: this.hostname } : {}
+
+            const dataPoints = eventData.map<Datapoint>((d) => ({
+                t: DatapointType.Event,
+                d: now,
+                n: d.name,
+                p: { scopeId: d.appInfo?.scopeId, ...hostname, ...defaultValues, ...d.data },
+            }))
+
+            const userProps = this.applyCITelemetry({ ...hostname })
+
+            dataPoints.push({
+                t: DatapointType.User,
+                d: now,
+                n: this.userId!,
+                p: userProps,
+            })
+
+            const body: HeartbeatBody = {
+                SessionId: this.session.SessionId,
+                DataPoints: dataPoints,
+                TabId: this.session.TabId || '0',
+                ClientTime: new Date().toISOString(),
+                ConfigReceivedTime: new Date().toISOString(),
+            }
+
+            fetch(new URL('/web/heartbeat', this.config.BaseUrl), {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+            }).catch(() => {})
+        } catch (_error) {
+            //ignore errors from telemetry
+        }
+    }
+
+    private getHeaders() {
+        return {
+            APIKey: this.config.APIKey,
+            APIAuth: this.config.APIAuth,
+            BrowserId: '0',
+            ClientId: this.session?.ClientId || '0',
+            Version: this.sdkVersion || 'unknown',
+            'Content-Type': 'application/json',
+        }
+    }
+
+    private getDefaultDataValues() {
+        const defaultValues: TelemetryEventData = {
+            os: os.type(),
+            version: this.sdkVersion || 'unknown',
+            nodeVersion: process.version,
+            clientName: this.clientName,
+        }
+
+        return this.applyCITelemetry(defaultValues)
+    }
+
+    private applyCITelemetry(data: TelemetryEventData) {
+        if (ciInfo.isCI) {
+            return { ...data, ci: true, ciName: ciInfo.name, ciPR: ciInfo.isPR }
+        }
+
+        return data
+    }
+}

package/src/telemetry/clients/noop-client.ts

@@ -0,0 +1,15 @@
+import type { Telemetry, TimerMetric } from '../types'
+
+/**
+ * This is a no-op telemetry implementation that does nothing.
+ */
+export class NoOpTelemetry implements Telemetry {
+    startTimerEvent(): TimerMetric {
+        return {
+            end: () => ({ name: '', data: {} }),
+        }
+    }
+    start = () => {}
+    sendEvent = () => {}
+    error = () => {}
+}

package/src/telemetry/clients/util.ts

@@ -0,0 +1,33 @@
+import type { TelemetryEvent, TimerMetric } from '../types'
+
+export class AppSeeTimerMetric implements TimerMetric {
+    private readonly startTime: number
+
+    constructor(private readonly name: TelemetryEvent['name']) {
+        this.startTime = Date.now()
+    }
+
+    getDurationMs() {
+        const now = Date.now()
+        return {
+            duration: now - this.startTime,
+            now,
+        }
+    }
+
+    end(eventData?: Pick<TelemetryEvent, 'appInfo' | 'data'>): TelemetryEvent {
+        const durationMs = Date.now() - this.startTime
+        /**
+         * Create a an event containing the duration and all checkpoint durations
+         */
+
+        return {
+            name: this.name,
+            appInfo: eventData?.appInfo || {},
+            data: {
+                ...eventData?.data,
+                durationMs,
+            },
+        }
+    }
+}

package/src/telemetry/config.ts

@@ -0,0 +1,12 @@
+import type { InstanceSettings } from './types'
+
+declare const __APPSEE_API_KEY__: string
+declare const __APPSEE_AUTH_KEY__: string
+declare const __APPSEE_URL__: string
+
+//will be populated by esbuild during the release build
+export const getAppSeeConfig = (): InstanceSettings => ({
+    APIKey: __APPSEE_API_KEY__,
+    APIAuth: __APPSEE_AUTH_KEY__,
+    BaseUrl: __APPSEE_URL__,
+})

package/src/telemetry/factory.ts

@@ -0,0 +1,34 @@
+/** biome-ignore-all lint/complexity/noStaticOnlyClass: <explanation> */
+import type { Telemetry } from './types'
+import { NoOpTelemetry } from './clients/noop-client'
+import { NodeTelemetryClient } from './clients/node-client'
+import { BrowserTelemetryClient } from './clients/browser-client'
+import { getAppSeeConfig } from './config'
+
+export class TelemetryFactory {
+    static create(options?: {
+        type?: 'node' | 'browser'
+        attributes?: { sdkVersion?: string; clientName?: string; hostname?: string; ideVersion?: string }
+    }): Telemetry {
+        const config = getAppSeeConfig()
+
+        if (
+            process.env['NODE_ENV'] === 'test' ||
+            !options ||
+            !options.type ||
+            !config.APIKey ||
+            !config.APIAuth ||
+            !config.BaseUrl
+        ) {
+            return new NoOpTelemetry()
+        }
+
+        if (options.type === 'node') {
+            return new NodeTelemetryClient(config, options.attributes)
+        } else if (options.type === 'browser') {
+            return new BrowserTelemetryClient(config, options.attributes)
+        }
+
+        throw new Error('Invalid telemetry type.')
+    }
+}

package/src/telemetry/index.ts

@@ -1,27 +1,2 @@
-export interface Telemetry {
-    sendEvent(eventData: TelemetryEvent | TelemetryEvent[]): Promise<void>
-    error(event: string, error: unknown, data?: TelemetryEventData): Promise<void>
-    startTimerEvent(name: TelemetryEvent['name']): TimerMetric
-}
-
-export interface TimerMetric {
-    end(eventData?: Pick<TelemetryEvent, 'appInfo' | 'data'>): TelemetryEvent
-}
-
-export type TelemetryEventData = Record<string, unknown>
-
-export type TelemetryEvent = { name: string; appInfo?: { scopeId?: string }; data?: TelemetryEventData }
-
-/**
- * This is a no-op telemetry implementation that does nothing.
- */
-export class NoOpTelemetry implements Telemetry {
-    startTimerEvent(): TimerMetric {
-        return {
-            end: () => ({ name: '', data: {} }),
-        }
-    }
-    start = () => Promise.resolve()
-    sendEvent = () => Promise.resolve()
-    error = () => Promise.resolve()
-}
+export type { Telemetry, TelemetryEvent } from './types'
+export { TelemetryFactory } from './factory'

package/src/telemetry/types.ts

@@ -0,0 +1,61 @@
+export const NETWORK_TIMEOUT_MS = 2000
+
+export type InstanceSettings = {
+    APIKey: string
+    APIAuth: string
+    BaseUrl: string
+}
+
+export type Session = {
+    SessionId: string
+    ClientId: string
+    TabId: string
+}
+
+export enum DatapointType {
+    Page = 0,
+    Event = 1,
+    User = 2,
+    PerformanceTrace = 3,
+}
+
+export type Datapoint = {
+    t: DatapointType
+
+    /**
+     * Epoch time in milliseconds
+     */
+    d: number
+
+    /**
+     * Event name
+     */
+    n: string
+
+    /**
+     * Event properties
+     */
+    p?: Record<string, unknown>
+}
+
+export type HeartbeatBody = {
+    SessionId: string
+    DataPoints: Datapoint[]
+    TabId: string
+    ClientTime: string
+    ConfigReceivedTime: string
+}
+
+export interface Telemetry {
+    sendEvent(eventData: TelemetryEvent | TelemetryEvent[]): void
+    error(event: string, error: unknown, data?: TelemetryEventData): void
+    startTimerEvent(name: TelemetryEvent['name']): TimerMetric
+}
+
+export interface TimerMetric {
+    end(eventData?: Pick<TelemetryEvent, 'appInfo' | 'data'>): TelemetryEvent
+}
+
+export type TelemetryEventData = Record<string, unknown>
+
+export type TelemetryEvent = { name: string; appInfo?: { scopeId?: string }; data?: TelemetryEventData }

package/src/typescript.ts

@@ -31,6 +31,23 @@ import { ts as tsc } from 'ts-morph'
 
 export { ts, tsc }
 
+/**
+ * Checks if a value is a valid ts-morph Node that can be operated on.
+ *
+ * Unlike `ts.Node.isNode()`, this function safely handles nodes that have been
+ * removed or forgotten from the AST, returning `false` instead of throwing.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid, usable Node; `false` otherwise
+ */
+export function isValidNode(value: unknown): value is ts.Node {
+    try {
+        return ts.Node.isNode(value)
+    } catch {
+        return false
+    }
+}
+
 export function getValueDeclaration(node: ts.Node) {
     const symbol = node.getSymbol()
     if (!symbol) {

package/src/util/delete-multiple.ts

@@ -0,0 +1,35 @@
+import { type Context, Database } from '../plugins'
+
+export async function deleteMultipleDiff(
+    existing: Database,
+    incoming: Database,
+    descendants: Database,
+    { factory }: Pick<Context, 'factory'>
+) {
+    if (incoming.query().length === 0) {
+        // No changes for this record so we don't search descendents for absent deletes.
+        return {
+            success: true,
+            value: new Database(),
+        }
+    }
+
+    const changeDatabase = existing.compare(incoming)
+    const markForRemoval = descendants.query().filter((descendent) => !incoming.resolve(descendent.getId()))
+    for (const record of markForRemoval) {
+        const deleteRecord = await factory.createRecord({
+            source: record.getSource(),
+            table: record.getTable(),
+            explicitId: record.getId(),
+            properties: record.properties(),
+            action: 'DELETE',
+        })
+
+        changeDatabase.insert(deleteRecord)
+    }
+
+    return {
+        success: true,
+        value: changeDatabase.hasChanges() ? new Database(changeDatabase.query()) : new Database(),
+    }
+}

package/src/util/index.ts

@@ -1,2 +1,3 @@
 export * from './is-sn-scope'
 export * from './get-file-type'
+export * from './delete-multiple'