diff --git a/types/pendo-io-browser/index.d.ts b/types/pendo-io-browser/index.d.ts index 82e6bce9826a19..7676aceaced381 100644 --- a/types/pendo-io-browser/index.d.ts +++ b/types/pendo-io-browser/index.d.ts @@ -18,27 +18,149 @@ declare namespace pendo { type IdentityCookieDomain = `.${string}`; interface InitOptions extends Identity { + // Core Configuration apiKey?: string | undefined; + publicAppId?: string | undefined; + additionalPublicAppIds?: string[] | undefined; excludeAllText?: boolean | undefined; excludeTitle?: boolean | undefined; disableCookies?: boolean; disablePersistence?: boolean | undefined; + disablePendo?: boolean | undefined; guides?: { + attachPoint?: string | (() => HTMLElement) | undefined; delay?: boolean | undefined; disabled?: boolean | undefined; + ejectOnTimeout?: boolean | undefined; + globalScripts?: any[] | undefined; timeout?: number | undefined; tooltip?: { arrowSize?: number | undefined; } | undefined; } | undefined; events?: EventCallbacks | undefined; + + // URL and Location Configuration + annotateUrl?: ( + url: string, + ) => string | string[] | { + exclude?: string[]; + include?: string[] | Record; + fragment?: string; + }; sanitizeUrl?: (url: string) => string; + queryStringWhitelist?: string[] | (() => string[]) | undefined; + ignoreHashRouting?: boolean | undefined; + location?: { + pushState?: boolean | undefined; + } | undefined; + + // Hosting and Delivery + assetHost?: string | undefined; + contentHost?: string | undefined; + dataHost?: string | undefined; + selfHostedWebSDKUrl?: string | undefined; + + // Frame and Cross-Origin Configuration + allowCrossOriginFrames?: boolean | undefined; + autoFrameInstall?: boolean | undefined; + frameIdentitySync?: boolean | undefined; + frameIdentityTopDownOnly?: boolean | undefined; + forcedLeader?: boolean | undefined; + preferBroadcastChannel?: boolean | undefined; + enableCrossOriginIsolation?: boolean | undefined; + + // Identity and Persistence + forceAnonymous?: boolean | undefined; + identityStorageSuffix?: string | undefined; + crossAppGuideStorageSuffix?: string | undefined; + localStorageOnly?: boolean | undefined; + dropAnonymous?: boolean | undefined; + + // Analytics Configuration + allowedText?: string[] | undefined; + analytics?: { + excludeEvents?: string[] | undefined; + localStorageUnload?: boolean | undefined; + } | undefined; + enableDebugEvents?: boolean | undefined; + eventPropertyMatchParents?: boolean | undefined; + eventPropertyConfigurations?: any[] | undefined; + excludeNonGuideAnalytics?: boolean | undefined; + interceptPreventDefault?: boolean | undefined; + interceptStopPropagation?: boolean | undefined; + syntheticClicks?: { + elementRemoval?: boolean | undefined; + targetChanged?: boolean | undefined; + } | undefined; + interceptElementRemoval?: boolean | undefined; // Deprecated: use syntheticClicks.elementRemoval + + // Guide Configuration + appAutoOrdering?: string[] | undefined; + blockAgentMetadata?: boolean | undefined; + cacheGuides?: boolean | undefined; + cacheGuidesPersistent?: boolean | undefined; + cacheGuidesTimeout?: number | undefined; + captureConsoleLogs?: boolean | undefined; + captureNetworkRequests?: boolean | undefined; + disableDesigner?: boolean | undefined; + disableDesignerKeyboardShortcut?: boolean | undefined; + disableGlobalCSS?: boolean | undefined; + disableGuidePseudoStyles?: boolean | undefined; + disablePrefetch?: boolean | undefined; + enableAllEmbeddedGuideEvents?: boolean | undefined; + enableDesignerKeyboardShortcut?: boolean | undefined; + enableFullUtmReferrer?: boolean | undefined; + enableGuideTimeout?: boolean | undefined; + enableSignedMetadata?: boolean | undefined; + guideMarkdown?: boolean | undefined; + guideSeenTimeoutLength?: number | undefined; + guideValidation?: boolean | undefined; + htmlAttributeBlacklist?: string[] | null | undefined; + htmlAttributes?: RegExp | undefined; + inlineStyleNonce?: string | undefined; + leaderApplication?: string[] | undefined; + preventCodeInjection?: boolean | undefined; + preventCookieRefresh?: boolean | undefined; + preventUnloadListener?: boolean | undefined; + predictGuides?: boolean | undefined; + initializeImmediately?: boolean | undefined; + observeShadowRoots?: boolean | undefined; + preferMutationObserver?: boolean | undefined; + + // Feedback Configuration + disableFeedback?: boolean | undefined; + disableFeedbackAutoInit?: boolean | undefined; + pendoFeedback?: boolean | undefined; + + // Performance and Monitoring + environmentName?: string | undefined; + errorClickLogging?: boolean | undefined; + extensionPersistLocalStorage?: boolean | undefined; + formValidation?: boolean | undefined; + isPendoFree?: boolean | undefined; + pendoCore?: boolean | undefined; + performanceMetricsEnabled?: boolean | undefined; + performanceMetricsSampleRate?: number | undefined; + recording?: { enabled?: boolean | undefined } | undefined; + requestSegmentFlags?: boolean | undefined; + requireHTTPS?: boolean | undefined; + requireSignedMetadata?: boolean | undefined; + resourceCaching?: boolean | undefined; + sendEventsWithPostOnly?: boolean | undefined; + siblingSelectors?: boolean | undefined; + stagingServers?: (string | RegExp)[] | undefined; + unminified?: boolean | undefined; + vocPortal?: boolean | undefined; } interface EventCallbacks { ready?(): void; guidesLoaded?(): void; guidesFailed?(): void; + validateGlobalScript?(result: any): void; + validateGuide?(signatureString: string, guide: Guide): void | Promise; + validateLauncher?(signatureString: string): void | Promise; } interface Pendo { @@ -47,30 +169,49 @@ declare namespace pendo { identify(visitorId: string, accountId?: string): void; identify(identity: Identity): void; isReady(): boolean; - flushNow(): Promise; + flushNow(options?: { hidden?: boolean; unload?: boolean }): Promise; updateOptions(options: Identity): void; getVersion(): string; getVisitorId(): string; + get_visitor_id(): string; + set_visitor_id(newVisitorId: string): void; getAccountId(): string | null; + get_account_id(): string | null; + set_account_id(newAccountId: string): void; getCurrentUrl(): string; clearSession(): void; teardown(): void; + isAnonymousVisitor(id?: string): boolean; + generate_unique_id(prefix?: string): string; // Guides and Guide Center // eslint-disable-next-line @typescript-eslint/no-invalid-void-type findGuideByName(name: string): Guide | void; // eslint-disable-next-line @typescript-eslint/no-invalid-void-type findGuideById(id: string): Guide | void; + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type + findGuideBy(field: string, value: any): Guide | void; + findModuleByName(name: string): any; + findStepInGuide(guide: Guide, stepId: string): GuideStep | undefined; showGuideByName(name: string): void; - showGuideById(id: string): void; + showGuideById(id: string, reason?: string): void; + isGuideShown(): boolean; + getActiveGuides(): Guide[]; + getActiveGuide(): Guide | undefined; + hideGuides(hideOptions?: { stayHidden?: boolean }): void; toggleLauncher(): void; + showLauncher(): void; + hideLauncher(): void; removeLauncher(): void; // Troubleshooting setGuidesDisabled(state: boolean): void; + areGuidesDisabled(): boolean; loadGuides(): void; startGuides(): void; stopGuides(): void; + showPreview(): void; + pageLoad(): void; // Debugging enableDebugging(): void; @@ -82,6 +223,12 @@ declare namespace pendo { // Events events: Events; track(trackType: string, metadata?: Metadata): void; + trackAgent(trackType: string, metadata?: Metadata): void; + isSendingEvents(): boolean; + startSendingEvents(): void; + stopSendingEvents(): void; + getEventCache(): any[]; + flushEventCache(): void; // Guide Events onGuideAdvanced(step?: GuideStep): void; @@ -89,6 +236,7 @@ declare namespace pendo { onGuidePrevious(step?: GuideStep): void; onGuideDismissed(step?: GuideStep): void; onGuideDismissed(until: { until: "reload" }): void; + onGuideSnoozed(evt: any, step?: GuideStep, snoozeDuration?: number): void; // feedback feedback: Feedback; @@ -96,10 +244,38 @@ declare namespace pendo { // Properties additionalApiKeys: string[]; apiKey: string; + visitorId: string; + accountId: string; + guides: Guide[]; + designerEnabled: boolean; + features: any; + VERSION: string; + ENV: string; + + // URL and Location + url: UrlManager; + location: LocationManager; - // Other - validateInstall(): void; + // Utilities + log(message: string, ...contexts: string[]): void; + ajax: AjaxHelper; + validateInstall(skipLogging?: boolean): void; + validateEnvironment(skipLogging?: boolean): void; dom(input: any): HTMLElement; // TODO + doesExist(arg: any): boolean; + getMode(): string | undefined; + getNormalizedUrl(): string; + /** @deprecated Use pendo.sniffer or navigator.userAgent directly */ + getUA(): string; + getURL(): string; + getSerializedMetadata(): Metadata; + isURLValid(url: string): boolean; + + // Advanced + BuildingBlocks?: any; // Internal API + buffers?: any; // Internal API + frames?: any; // Internal API + sniffer?: BrowserSniffer; } interface FeedbackOptions { @@ -110,16 +286,33 @@ declare namespace pendo { } interface Debugging { - getEventCache(): any[]; // TODO + getEventCache(): any[]; getAllGuides(): Guide[]; getAutoGuides(): { auto: Guide[]; override: Guide[] }; getBadgeGuides(): Guide[]; - getLauncherGuides(): Guide[]; + getLauncherGuides(guideList?: Guide[]): Guide[]; + getEventHistory(): any[]; + getMetadata(): any; + areGuidesDelayed(): boolean; + isLeader(): boolean; + getState(): any; } - type Events = { - [K in keyof EventCallbacks]-?: (callback: EventCallbacks[K]) => Events; - }; + type Events = + & { + [K in keyof EventCallbacks]-?: (callback: EventCallbacks[K]) => Events; + } + & { + on(eventName: string, callback: (...args: any[]) => void): void; + off(eventName: string, callback?: (...args: any[]) => void): void; + once(eventName: string, callback: (...args: any[]) => void): void; + one(eventName: string, callback: (...args: any[]) => void): void; + trigger(eventName: string, ...args: any[]): void; + addEventListener(eventName: string, callback: (...args: any[]) => void): void; + removeEventListener(eventName: string, callback?: (...args: any[]) => void): void; + onClickCaptured(callback: (event: any) => void): Events; + deliverablesLoaded(callback: () => void): Events; + }; interface Guide { createdByUser: User; @@ -180,6 +373,61 @@ declare namespace pendo { lastUpdatedAt: number; resetAt: number; } + + interface UrlManager { + get(url?: string): string; + watch(callback: (url: string) => void): void; + clear(): void; + getWindowLocation(): Location; + isElectron(): boolean; + electronAppName(): string | undefined; + electronUserDirectory(): string | undefined; + electronUserHomeDirectory(): string | undefined; + electronResourcesPath(): string | undefined; + externalizeURL( + href: string, + qs?: string | Record, + xhrWhitelist?: string[] | (() => string[]), + ): string; + startPoller(): void; + } + + interface LocationManager { + (cmd?: string): any; + getHref(): string; + clearTransforms(): void; + addTransforms(transforms: any): void; + setUrl(strOrFn: string | (() => string)): void; + useBrowserUrl(): void; + } + + interface AjaxHelper { + (config: any): any; + get(url: string, headers?: any): Promise; + post(url: string, data?: any, headers?: any): Promise; + postJSON(url: string, data?: any, headers?: any): Promise; + urlFor(base: string, params?: string[] | Record, fragment?: string): string; + supported(): boolean; + } + + interface BrowserSniffer { + MutationObserver: boolean; + addEventListener: boolean; + android: number; + animations: boolean; + msie: number; + msieDocumentMode: number | undefined; + safari: boolean; + sri: boolean; + transitions: boolean; + vendorPrefix: string; + isChromeExtension: boolean | undefined; + hasEvent(event: string): boolean; + isMinimumIEVersion(minVersion: number): boolean; + isMobileUserAgent(key?: string): boolean; + supportsHashChange(): boolean; + supportsHistoryApi(key?: string): boolean; + } } declare const pendo: pendo.Pendo; diff --git a/types/pendo-io-browser/package.json b/types/pendo-io-browser/package.json index 13b2e2fd3e4f9c..a4f5862bde6012 100644 --- a/types/pendo-io-browser/package.json +++ b/types/pendo-io-browser/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/pendo-io-browser", - "version": "2.19.9999", + "version": "2.314.9999", "nonNpm": true, "nonNpmDescription": "Pendo.io Agent", "projects": [ diff --git a/types/pendo-io-browser/pendo-io-browser-tests.ts b/types/pendo-io-browser/pendo-io-browser-tests.ts index 647410fd37ee68..ef34a151080d4b 100644 --- a/types/pendo-io-browser/pendo-io-browser-tests.ts +++ b/types/pendo-io-browser/pendo-io-browser-tests.ts @@ -166,3 +166,417 @@ pendo.teardown(); // $ExpectType void pendo.clearSession(); + +// Test trackAgent method +pendo.trackAgent("customEvent"); +pendo.trackAgent("customEvent", { action: "click", value: 123 }); + +// Test identity methods with aliases +// $ExpectType string +pendo.getVisitorId(); +// $ExpectType string +pendo.get_visitor_id(); + +pendo.set_visitor_id("new-visitor-id-2"); + +// $ExpectType string | null +pendo.getAccountId(); +// $ExpectType string | null +pendo.get_account_id(); + +pendo.set_account_id("new-account-id-2"); + +// $ExpectType string +pendo.generate_unique_id(); +// $ExpectType string +pendo.generate_unique_id("prefix-"); + +// Test anonymous visitor check +// $ExpectType boolean +pendo.isAnonymousVisitor(); +// $ExpectType boolean +pendo.isAnonymousVisitor("_PENDO_T_123"); + +// Test guide management methods +const guide = pendo.findGuideByName("My Guide"); +const guideById = pendo.findGuideById("guide-123"); +const guideByField = pendo.findGuideBy("state", "published"); +const module = pendo.findModuleByName("My Module"); + +if (guide) { + const step = pendo.findStepInGuide(guide, "step-123"); +} + +// $ExpectType boolean +pendo.isGuideShown(); + +// $ExpectType Guide[] +pendo.getActiveGuides(); + +const activeGuide = pendo.getActiveGuide(); + +pendo.hideGuides(); +pendo.hideGuides({ stayHidden: true }); + +pendo.showLauncher(); +pendo.hideLauncher(); +pendo.removeLauncher(); + +// Test troubleshooting methods +// $ExpectType boolean +pendo.areGuidesDisabled(); + +pendo.showPreview(); +pendo.pageLoad(); + +// Test event tracking methods +// $ExpectType boolean +pendo.isSendingEvents(); + +pendo.startSendingEvents(); +pendo.stopSendingEvents(); + +// $ExpectType any[] +pendo.getEventCache(); + +pendo.flushEventCache(); + +// Test guide event handlers +const guideStep = pendo.guides[0]?.steps[0]; +pendo.onGuideSnoozed({}, guideStep, 3600000); + +// Test extended Events interface +pendo.events.on("customEvent", (data) => { + console.log(data); +}); + +pendo.events.off("customEvent"); + +pendo.events.once("oneTimeEvent", () => { + console.log("fired once"); +}); + +pendo.events.one("anotherOneTime", () => { + console.log("also fired once"); +}); + +pendo.events.trigger("myEvent", { data: "test" }); + +pendo.events.addEventListener("domEvent", (e) => { + console.log(e); +}); + +pendo.events.removeEventListener("domEvent"); + +pendo.events.onClickCaptured((event) => { + console.log(event); +}); + +pendo.events.deliverablesLoaded(() => { + console.log("deliverables loaded"); +}); + +// Test debugging interface extensions +// $ExpectType any[] +pendo.debugging.getEventHistory(); + +// $ExpectType any +pendo.debugging.getMetadata(); + +// $ExpectType boolean +pendo.debugging.areGuidesDelayed(); + +// $ExpectType boolean +pendo.debugging.isLeader(); + +// $ExpectType any +pendo.debugging.getState(); + +// Test utility methods +// $ExpectType boolean +pendo.doesExist(null); +// $ExpectType boolean +pendo.doesExist("value"); + +// $ExpectType boolean +pendo.isURLValid("https://example.com"); + +// $ExpectType string | undefined +pendo.getMode(); + +// $ExpectType string +pendo.getNormalizedUrl(); + +// $ExpectType string +pendo.getUA(); + +// $ExpectType string +pendo.getURL(); + +// $ExpectType Metadata +pendo.getSerializedMetadata(); + +pendo.log("message", "context1", "context2"); + +pendo.validateInstall(); +pendo.validateInstall(true); + +pendo.validateEnvironment(); +pendo.validateEnvironment(true); + +// Test URL Manager +// $ExpectType string +pendo.url.get(); +// $ExpectType string +pendo.url.get("https://example.com"); + +pendo.url.watch((url) => { + console.log(url); +}); + +pendo.url.clear(); + +// $ExpectType Location +pendo.url.getWindowLocation(); + +// $ExpectType boolean +pendo.url.isElectron(); + +// $ExpectType string | undefined +pendo.url.electronAppName(); + +// $ExpectType string | undefined +pendo.url.electronUserDirectory(); + +// $ExpectType string | undefined +pendo.url.electronUserHomeDirectory(); + +// $ExpectType string | undefined +pendo.url.electronResourcesPath(); + +// $ExpectType string +pendo.url.externalizeURL("https://example.com"); + +pendo.url.startPoller(); + +// Test Location Manager +pendo.location(); +pendo.location("getHref"); + +// $ExpectType string +pendo.location.getHref(); + +pendo.location.clearTransforms(); + +pendo.location.addTransforms([{ match: "test", replace: "replaced" }]); + +pendo.location.setUrl("https://example.com"); +pendo.location.setUrl(() => "https://example.com"); + +pendo.location.useBrowserUrl(); + +// Test AJAX Helper +pendo.ajax({ url: "https://api.example.com" }); + +pendo.ajax.get("https://api.example.com").then((response) => { + console.log(response); +}); + +pendo.ajax.get("https://api.example.com", { Authorization: "Bearer token" }).then((response) => { + console.log(response); +}); + +pendo.ajax.post("https://api.example.com", { data: "test" }).then((response) => { + console.log(response); +}); + +pendo.ajax.postJSON("https://api.example.com", { data: "test" }).then((response) => { + console.log(response); +}); + +// $ExpectType string +pendo.ajax.urlFor("https://api.example.com", { param: "value" }, "fragment"); + +// $ExpectType boolean +pendo.ajax.supported(); + +// Test Browser Sniffer +if (pendo.sniffer) { + // $ExpectType boolean + pendo.sniffer.MutationObserver; + + // $ExpectType boolean + pendo.sniffer.addEventListener; + + // $ExpectType number + pendo.sniffer.android; + + // $ExpectType boolean + pendo.sniffer.animations; + + // $ExpectType number + pendo.sniffer.msie; + + // $ExpectType number | undefined + pendo.sniffer.msieDocumentMode; + + // $ExpectType boolean + pendo.sniffer.safari; + + // $ExpectType string + pendo.sniffer.vendorPrefix; + + // $ExpectType boolean + pendo.sniffer.hasEvent("click"); + + // $ExpectType boolean + pendo.sniffer.isMinimumIEVersion(11); + + // $ExpectType boolean + pendo.sniffer.isMobileUserAgent(); + + // $ExpectType boolean + pendo.sniffer.supportsHashChange(); + + // $ExpectType boolean + pendo.sniffer.supportsHistoryApi(); +} + +// Test extended InitOptions configuration +pendo.initialize({ + // Core Configuration + apiKey: "test-key", + publicAppId: "test-app-id", + additionalPublicAppIds: ["app-1", "app-2"], + disablePendo: false, + initializeImmediately: true, + + // URL and Location Configuration + annotateUrl: (url) => url + "?annotated=true", + queryStringWhitelist: ["param1", "param2"], + ignoreHashRouting: true, + location: { + pushState: true, + }, + + // Hosting and Delivery + assetHost: "https://assets.example.com", + contentHost: "https://content.example.com", + dataHost: "https://data.example.com", + selfHostedWebSDKUrl: "https://sdk.example.com/pendo.js", + + // Frame and Cross-Origin Configuration + allowCrossOriginFrames: true, + autoFrameInstall: true, + frameIdentitySync: true, + frameIdentityTopDownOnly: false, + forcedLeader: true, + preferBroadcastChannel: true, + enableCrossOriginIsolation: true, + + // Identity and Persistence + forceAnonymous: false, + identityStorageSuffix: "custom", + crossAppGuideStorageSuffix: "shared", + localStorageOnly: false, + dropAnonymous: false, + + // Analytics Configuration + allowedText: ["Button", "Link"], + analytics: { + excludeEvents: ["click", "focus"], + localStorageUnload: true, + }, + enableDebugEvents: true, + eventPropertyMatchParents: true, + excludeNonGuideAnalytics: false, + interceptPreventDefault: true, + interceptStopPropagation: true, + syntheticClicks: { + elementRemoval: true, + targetChanged: true, + }, + + // Guide Configuration + appAutoOrdering: ["app-1", "app-2"], + blockAgentMetadata: false, + cacheGuides: true, + cacheGuidesTimeout: 600000, + disableDesigner: false, + disableDesignerKeyboardShortcut: false, + disableGlobalCSS: false, + disableGuidePseudoStyles: false, + disablePrefetch: false, + enableAllEmbeddedGuideEvents: true, + enableDesignerKeyboardShortcut: true, + enableGuideTimeout: true, + guideSeenTimeoutLength: 10000, + guideValidation: true, + inlineStyleNonce: "nonce-12345", + leaderApplication: ["app-1"], + preventCodeInjection: false, + preventUnloadListener: false, + observeShadowRoots: true, + preferMutationObserver: true, + + guides: { + attachPoint: "#guide-container", + delay: false, + disabled: false, + ejectOnTimeout: true, + globalScripts: [{ test: () => true }], + timeout: 5000, + tooltip: { + arrowSize: 20, + }, + }, + + // Feedback Configuration + disableFeedback: false, + disableFeedbackAutoInit: false, + pendoFeedback: true, + + // Performance and Monitoring + environmentName: "production", + errorClickLogging: true, + formValidation: true, + performanceMetricsEnabled: true, + performanceMetricsSampleRate: 0.1, + recording: { + enabled: true, + }, + stagingServers: ["https://staging.example.com", /test\.example\.com/], + vocPortal: true, + + visitor: { + id: "visitor-123", + }, + account: { + id: "account-456", + }, +}); + +// Test properties +// $ExpectType string[] +pendo.additionalApiKeys; + +// $ExpectType string +pendo.apiKey; + +// $ExpectType string +pendo.visitorId; + +// $ExpectType string +pendo.accountId; + +// $ExpectType Guide[] +pendo.guides; + +// $ExpectType boolean +pendo.designerEnabled; + +// $ExpectType string +pendo.VERSION; + +// $ExpectType string +pendo.ENV;