@servicenow/sdk-build-core 4.2.0 → 4.3.0

package/src/taxonomy.ts

@@ -13,6 +13,31 @@ const TableNames = {
     SYSEVENT_EMAIL_ACTION: 'sysevent_email_action',
     SYS_PD_PROCESS_DEFINITION: 'sys_pd_process_definition',
     SYS_HUB_TRIGGER_TEMPLATE: 'sys_hub_trigger_template',
+    SYS_VARIABLE_VALUE: 'sys_variable_value',
+    SYS_ELEMENT_MAPPING: 'sys_element_mapping',
+    SYS_HUB_FLOW_INPUT: 'sys_hub_flow_input',
+    SYS_HUB_FLOW_OUTPUT: 'sys_hub_flow_output',
+    SYS_HUB_ACTION_INPUT_ACTION_INSTANCE: 'sys_hub_action_input_action_instance',
+    SYS_HUB_FLOW_VARIABLE: 'sys_hub_flow_variable',
+    SYS_HUB_ACTION_INSTANCE: 'sys_hub_action_instance',
+    SYS_HUB_SUB_FLOW_INSTANCE: 'sys_hub_sub_flow_instance',
+    SYS_HUB_TRIGGER_INSTANCE: 'sys_hub_trigger_instance',
+    SYS_HUB_FLOW_LOGIC: 'sys_hub_flow_logic',
+    SYS_HUB_PILL_COMPOUND: 'sys_hub_pill_compound',
+    SYS_FLOW_CAT_VARIABLE_MODEL: 'sys_flow_cat_variable_model',
+    SYS_HUB_TRIGGER_INSTANCE_V2: 'sys_hub_trigger_instance_v2',
+    SYS_HUB_ACTION_INSTANCE_V2: 'sys_hub_action_instance_v2',
+    SYS_HUB_FLOW_LOGIC_INSTANCE_V2: 'sys_hub_flow_logic_instance_v2',
+    SYS_HUB_SUB_FLOW_INSTANCE_V2: 'sys_hub_sub_flow_instance_v2',
+    SYS_FLOW_RECORD_TRIGGER: 'sys_flow_record_trigger',
+    SYS_TRIGGER_RUNNER_MAPPING: 'sys_trigger_runner_mapping',
+    SYS_FLOW_TRIGGER_PLAN: 'sys_flow_trigger_plan',
+    SYS_HUB_FLOW_SNAPSHOT: 'sys_hub_flow_snapshot',
+    SYS_FLOW_SUBFLOW_PLAN: 'sys_flow_subflow_plan',
+    SYS_FLOW_EMAIL_TRIGGER: 'sys_flow_email_trigger',
+    SYS_FLOW_KNOWLEDGE_TRIGGER: 'sys_flow_knowledge_trigger',
+    SYS_FLOW_RT_QUERY_TRIGGER: 'sys_flow_rt_query_trigger',
+    SYS_FLOW_TRIGGER: 'sys_flow_trigger',
 
     // Client Development tables
     DL_U_ASSIGNMENT: 'dl_u_assignment',
@@ -156,6 +181,7 @@ const TableNames = {
 
 // String format: one or more path segments separated by '/' (e.g., 'server-development/business-rule' or 'integration/outbound/rest-api')
 const taxonomyItem = z.string().regex(/^[a-z0-9_-]+(\/[a-z0-9_-]+)*$/)
+const flowTaxonomyItem = taxonomyItem.default('automation/flow')
 
 const taxonomyMapping = z
     .object({
@@ -164,12 +190,38 @@ const taxonomyMapping = z
         [TableNames.SYS_HUB_TRIGGER_DEFINITION]: taxonomyItem.default('automation/trigger'),
         [TableNames.SYS_PD_ACTIVITY_DEFINITION]: taxonomyItem.default('automation/activity-definition'),
         [TableNames.SYS_ALIAS]: taxonomyItem.default('automation/workflow-activity'),
-        [TableNames.SYS_HUB_FLOW]: taxonomyItem.default('automation/flow'),
         [TableNames.SYS_DECISION]: taxonomyItem.default('automation/decision-table'),
         [TableNames.SYSEVENT_EMAIL_TEMPLATE]: taxonomyItem.default('automation/email-template'),
         [TableNames.SYSEVENT_EMAIL_ACTION]: taxonomyItem.default('automation/notification'),
         [TableNames.SYS_PD_PROCESS_DEFINITION]: taxonomyItem.default('automation/playbook'),
         [TableNames.SYS_HUB_TRIGGER_TEMPLATE]: taxonomyItem.default('automation/trigger'),
+        [TableNames.SYS_FLOW_EMAIL_TRIGGER]: taxonomyItem.default('automation/trigger'),
+        [TableNames.SYS_FLOW_TRIGGER_PLAN]: taxonomyItem.default('automation/trigger'),
+        [TableNames.SYS_FLOW_KNOWLEDGE_TRIGGER]: taxonomyItem.default('automation/trigger'),
+        [TableNames.SYS_FLOW_RT_QUERY_TRIGGER]: taxonomyItem.default('automation/trigger'),
+        [TableNames.SYS_FLOW_TRIGGER]: taxonomyItem.default('automation/trigger'),
+        [TableNames.SYS_HUB_FLOW]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_ACTION_TYPE_DEFINITION]: flowTaxonomyItem,
+        [TableNames.SYS_ELEMENT_MAPPING]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_FLOW_INPUT]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_FLOW_OUTPUT]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_ACTION_INPUT_ACTION_INSTANCE]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_FLOW_VARIABLE]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_ACTION_INSTANCE]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_SUB_FLOW_INSTANCE]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_FLOW_LOGIC]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_PILL_COMPOUND]: flowTaxonomyItem,
+        [TableNames.SYS_FLOW_CAT_VARIABLE_MODEL]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_TRIGGER_INSTANCE_V2]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_TRIGGER_INSTANCE]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_ACTION_INSTANCE_V2]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_FLOW_LOGIC_INSTANCE_V2]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_SUB_FLOW_INSTANCE_V2]: flowTaxonomyItem,
+        [TableNames.SYS_FLOW_RECORD_TRIGGER]: flowTaxonomyItem,
+        [TableNames.SYS_TRIGGER_RUNNER_MAPPING]: flowTaxonomyItem,
+        [TableNames.SYS_FLOW_TRIGGER_PLAN]: flowTaxonomyItem,
+        [TableNames.SYS_HUB_FLOW_SNAPSHOT]: flowTaxonomyItem,
+        [TableNames.SYS_FLOW_SUBFLOW_PLAN]: flowTaxonomyItem,
 
         // Client Development tables
         [TableNames.DL_U_ASSIGNMENT]: taxonomyItem.default('client-development/assignment-data-lookup'),

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

@@ -0,0 +1,63 @@
+import type { Telemetry, TelemetryEvent, TelemetryEventData, TimerMetric, InstanceSettings, Session } from '../types'
+import { AppSeeTimerMetric } from './util'
+
+export abstract class AbstractAppSeeClient implements Telemetry {
+    protected readonly sdkVersion?: string | undefined
+    protected readonly clientName: 'cli' | 'ide' | string
+    protected readonly hostname?: string | undefined
+    protected session?: Session
+    protected startPromise?: Promise<void>
+
+    constructor(
+        protected readonly config: InstanceSettings,
+        protected telemetryAttributes: {
+            sdkVersion?: string
+            clientName: 'cli' | 'ide' | string
+            hostname?: string
+        }
+    ) {
+        this.sdkVersion = telemetryAttributes.sdkVersion
+        this.clientName = telemetryAttributes.clientName
+        this.hostname = telemetryAttributes.hostname
+    }
+
+    startTimerEvent(name: TelemetryEvent['name']): TimerMetric {
+        return new AppSeeTimerMetric(name)
+    }
+
+    public start(): Promise<void> {
+        if (!this.startPromise) {
+            this.startPromise = this.doStart()
+        }
+        return this.startPromise
+    }
+
+    public sendEvent(events: TelemetryEvent | TelemetryEvent[]): void {
+        //we fire and forget the telemetry events
+        this.start()
+            .then(() => this.doSendEvent(events))
+            .catch(() => {})
+    }
+
+    public error(event: string, error: unknown, data?: TelemetryEventData) {
+        this.sendEvent([
+            {
+                name: 'error',
+                data: {
+                    event,
+                    ...(error instanceof Error
+                        ? {
+                              name: error.name,
+                              message: error.message,
+                              stack: error.stack,
+                          }
+                        : { message: error?.toString() }),
+                    ...data,
+                },
+            },
+        ])
+    }
+
+    protected abstract doStart(): Promise<void>
+    protected abstract doSendEvent(events: TelemetryEvent | TelemetryEvent[]): void
+}

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) {