diff --git a/types/new-relic-browser/index.d.ts b/types/new-relic-browser/index.d.ts index c0cfb5124c55f1..b23f722d0a7903 100644 --- a/types/new-relic-browser/index.d.ts +++ b/types/new-relic-browser/index.d.ts @@ -1,8 +1,150 @@ +declare global { + let newrelic: NewRelicAPI; +} + +export interface EventObject { + /** Event name */ + name: string; + /** Start time in ms since epoch */ + start: number; + /** End time in ms since epoch. Defaults to same as start resulting in trace object with a duration of zero. */ + end?: number | undefined; + /** Origin of event */ + origin?: string | undefined; + /** Event type - I can't find this being used in the newrelic-browser-agent code */ + type?: string | undefined; +} + +export interface BrowserInteraction { + /** + * Sets the text value of the HTML element that was clicked to start a browser interaction. + * + * @param value The text value of the HTML element that represents the action that started the interaction. + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/actiontext + */ + actionText(value: string): this; + + /** + * Times sub-components of a SPA interaction separately, including wait time and JS execution time. + * + * @param name This will be used as the name of the tracer. If you do not include a name, + * New Relic Browser does not add a node to the interaction tree. The callback time will be + * attributed to the parent node. + * @param callback A callback that contains the synchronous work to run at the end of the async work. + * To execute this callback, call the wrapper function returned using createTracer() + * @returns This method ends the async time. It calls (and times) the callback that was passed into createTracer(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/createtracer + */ + createTracer(name: string, callback?: Callback): Wrapper; + + /** + * Ends the New Relic SPA interaction at the current time. + * + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/end + */ + end(): this; + + /** + * Stores values across the current SPA interaction asynchronously in New Relic Browser. + * + * @param callback A function that accepts the interaction context object + * as its only argument. + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/getcontext + */ + // eslint-disable-next-line @definitelytyped/no-unnecessary-generics + getContext(callback: GetContextCallback): this; + + /** + * Overrides other SPA save() calls; ignores an interaction so it is not saved or sent to New Relic. + * + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/ignore + */ + ignore(): this; + + /** + * Adds custom attributes for SPA interactions to the end of an event. It is called when the interaction + * has finished. You can invoke methods to modify the interaction, but methods that have asynchronous + * side effects will not have an effect. + * + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/onend + */ + // eslint-disable-next-line @definitelytyped/no-unnecessary-generics + onEnd(callback: GetContextCallback): this; + + /** + * Ensures a SPA browser interaction will be saved when it ends. + * + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/save + */ + save(): this; + + /** + * Adds a custom SPA attribute only to the current interaction in New Relic Browser. + * + * @param key Used as the attribute name on the BrowserInteraction event. + * @param value Used as the attribute value on the BrowserInteraction event. This can be a + * string, number, boolean, or object. If it is an object, New Relic serializes it to a JSON string. + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setattribute + */ + setAttribute(key: string, value: ComplexType): this; + + /** + * Sets the name and trigger of a SPA's browser interaction that is not a route change or URL change. + * + * @param name If null, the name will be set using the targetGroupedUrl attribute. + * If not null, this will set the browserInteractionName attribute in the BrowserInteraction event. + * @param trigger If not null, this will set the TRIGGER attribute on the BrowserInteraction event. + * @returns This method returns the same API object created by interaction(). + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setname + */ + setName(name: string, trigger?: string): this; +} + +export interface ContextObject extends Record {} + +export interface Callback { + (): void; +} + +export interface ErrorHandler { + (err: any): boolean; +} + +export interface GetContextCallback { + (contextObject: T): void; +} + +export interface Wrapper { + (): void; +} + +export type SimpleType = string | number; +export type ComplexType = string | number | boolean | unknown; + +export interface Info { + agent: string; + applicationID: string; + beacon: string; + errorBeacon: string; + jsAttributes: Record; + licenseKey: string; + sa: number; +} + /** * The browser and Single Page Application (SPA) APIs * allow you to customize and extend your browser monitoring. */ -declare namespace newrelic { +export interface NewRelicAPI { + info: Info; + /** * Adds a unique name and ID to identify releases with multiple JavaScript bundles on the same page. * @@ -11,9 +153,9 @@ declare namespace newrelic { * @param releaseId The ID or version of this release; for example, a version number, build number * from your CI environment, GitHub SHA, GUID, or a hash of the contents. Since New Relic converts this * value into a string, you can also use null or undefined if necessary - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/add-release + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/addrelease */ - function addRelease(releaseName: string, releaseId: string): void; + addRelease(releaseName: string, releaseId: string): void; /** * Reports a Browser PageAction event to Insights along with a name and attributes. @@ -21,9 +163,9 @@ declare namespace newrelic { * @param name Name or category of the action. Reports to Insights as the actionName attribute. * @param attributes JSON object with one or more key/value pairs. * The key will report to Insights as its own PageAction attribute with the specified values. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/addpageaction */ - function addPageAction(name: string, attributes?: Record): void; + addPageAction(name: string, attributes?: Record): void; /** * Adds a JavaScript object with a custom name, start time, etc. to an in-progress session trace. @@ -31,18 +173,18 @@ declare namespace newrelic { * @param eventObject If you are sending the same event object to New Relic Insights as a * PageAction, omit the TYPE attribute. If included, it will override the event type and cause the * PageAction event to be sent incorrectly. Instead, use the NAME attribute for event information. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/add-to-trace + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/addtotrace */ - function addToTrace(eventObject: EventObject): void; + addToTrace(eventObject: EventObject): void; /** * Records an additional time point as "finished" in a session trace, and sends the event to Insights. * * @param timestamp Defaults to the current time of the call. If used, this marks the time that * the page is "finished" according to your own criteria. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/finished + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/finished */ - function finished(timestamp?: number): void; + finished(timestamp?: number): void; /** * Identifies a browser error without disrupting your app's operations. @@ -50,9 +192,9 @@ declare namespace newrelic { * @param error Provide a meaningful error message that you can use when analyzing data on * New Relic Browser's JavaScript errors page. * @param customAttributes An object containing name/value pairs representing custom attributes. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/notice-error + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/noticeerror */ - function noticeError(error: Error | string, customAttributes?: Record): void; + noticeError(error: Error | string, customAttributes?: Record): void; /** * Adds a user-defined application version string to subsequent events on the page. @@ -64,7 +206,7 @@ declare namespace newrelic { * subsequent events. * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setApplicationVersion/ */ - function setApplicationVersion(value: string | null): void; + setApplicationVersion(value: string | null): void; /** * Adds a user-defined attribute name and value to subsequent events on the page. @@ -74,18 +216,18 @@ declare namespace newrelic { * @param value Value of the attribute. Appears as the value in the named attribute column in the * PageView event. It will appear as a column in the PageAction event if you are using it. Custom attribute * values cannot be complex objects, only simple types such as strings and numbers. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/set-custom-attribute + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setcustomattribute */ - function setCustomAttribute(name: string, value: SimpleType, persist?: boolean): void; + setCustomAttribute(name: string, value: SimpleType, persist?: boolean): void; /** * Allows selective ignoring of known errors that the Browser agent captures. * * @param filterCallback The callback will be called with each error, so it is not * specific to one error. `err` will usually be an error object, but it can be other data types. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/set-error-handler + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/seterrorhandler */ - function setErrorHandler(filterCallback: ErrorHandler): void; + setErrorHandler(filterCallback: ErrorHandler): void; /** * Groups page views to help URL structure or to capture the URL's routing information. @@ -95,9 +237,9 @@ declare namespace newrelic { * To further group these custom transactions, provide a custom host. Otherwise, the page views will be * assigned the default domain custom.transaction. Segments within the name must be explicitly added to * the Whitelist segments in your URL whitelist settings if they do not already appear. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/set-pageview-name + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setpageviewname */ - function setPageViewName(name: string, host?: string): void; + setPageViewName(name: string, host?: string): void; /** * Returns a new API object that is bound to the current SPA interaction. @@ -105,9 +247,9 @@ declare namespace newrelic { * @returns This method returns an API object that is bound to a specific BrowserInteraction * event. Each time this method is called for the same BrowserInteraction, a new object is created, but it still * references the same interaction. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/interaction-browser-spa-api + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/interaction/ */ - function interaction(): BrowserInteraction; + interaction(): BrowserInteraction; /** * Gives SPA routes more accurate names than default names. Monitors specific routes rather than by default @@ -117,9 +259,9 @@ declare namespace newrelic { * be any string, but they should represent a routing pattern rather than a specific resource. For example, * use /users/:id rather than /users/123. If null, exits out of the route change requirement and returns to * the default naming strategy. - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-set-current-route-name + * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setcurrentroutename/ */ - function setCurrentRouteName(name: string | null): void; + setCurrentRouteName(name: string | null): void; /** * Adds a user-defined identifier string to subsequent events on the page. @@ -129,143 +271,5 @@ declare namespace newrelic { * validation. Passing a null value unsets any existing user ID. * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setuserid/ */ - function setUserId(userId: string | null): void; - - interface EventObject { - /** Event name */ - name: string; - /** Start time in ms since epoch */ - start: number; - /** End time in ms since epoch. Defaults to same as start resulting in trace object with a duration of zero. */ - end?: number | undefined; - /** Origin of event */ - origin?: string | undefined; - /** Event type */ - type?: string | undefined; - } - - interface BrowserInteraction { - /** - * Sets the text value of the HTML element that was clicked to start a browser interaction. - * - * @param value The text value of the HTML element that represents the action that started the interaction. - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/actiontext-browser-spa-api - */ - actionText(value: string): this; - - /** - * Times sub-components of a SPA interaction separately, including wait time and JS execution time. - * - * @param name This will be used as the name of the tracer. If you do not include a name, - * New Relic Browser does not add a node to the interaction tree. The callback time will be - * attributed to the parent node. - * @param callback A callback that contains the synchronous work to run at the end of the async work. - * To execute this callback, call the wrapper function returned using createTracer() - * @returns This method ends the async time. It calls (and times) the callback that was passed into createTracer(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-create-tracer - */ - createTracer(name: string, callback?: Callback): Wrapper; - - /** - * Ends the New Relic SPA interaction at the current time. - * - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-end - */ - end(): this; - - /** - * Stores values across the current SPA interaction asynchronously in New Relic Browser. - * - * @param callback A function that accepts the interaction context object - * as its only argument. - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-get-context - */ - // eslint-disable-next-line @definitelytyped/no-unnecessary-generics - getContext(callback: GetContextCallback): this; - - /** - * Overrides other SPA save() calls; ignores an interaction so it is not saved or sent to New Relic. - * - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-ignore-browser - */ - ignore(): this; - - /** - * Adds custom attributes for SPA interactions to the end of an event. It is called when the interaction - * has finished. You can invoke methods to modify the interaction, but methods that have asynchronous - * side effects will not have an effect. - * - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-on-end - */ - // eslint-disable-next-line @definitelytyped/no-unnecessary-generics - onEnd(callback: GetContextCallback): this; - - /** - * Ensures a SPA browser interaction will be saved when it ends. - * - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-save - */ - save(): this; - - /** - * Adds a custom SPA attribute only to the current interaction in New Relic Browser. - * - * @param key Used as the attribute name on the BrowserInteraction event. - * @param value Used as the attribute value on the BrowserInteraction event. This can be a - * string, number, boolean, or object. If it is an object, New Relic serializes it to a JSON string. - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-set-attribute - */ - setAttribute(key: string, value: ComplexType): this; - - /** - * Sets the name and trigger of a SPA's browser interaction that is not a route change or URL change. - * - * @param name If null, the name will be set using the targetGroupedUrl attribute. - * If not null, this will set the browserInteractionName attribute in the BrowserInteraction event. - * @param trigger If not null, this will set the TRIGGER attribute on the BrowserInteraction event. - * @returns This method returns the same API object created by interaction(). - * @see https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/spa-set-name - */ - setName(name: string, trigger?: string): this; - } - - interface ContextObject extends Record {} - - interface Callback { - (): void; - } - - interface ErrorHandler { - (err: any): boolean; - } - - interface GetContextCallback { - (contextObject: T): void; - } - - interface Wrapper { - (): void; - } - - type SimpleType = string | number; - type ComplexType = string | number | boolean | unknown; - - interface Info { - agent: string; - applicationID: string; - beacon: string; - errorBeacon: string; - jsAttributes: Record; - licenseKey: string; - sa: number; - } - - const info: Info; + setUserId(userId: string | null): void; } diff --git a/types/new-relic-browser/new-relic-browser-tests.ts b/types/new-relic-browser/new-relic-browser-tests.ts index b91a2f74e2be60..50fbea3edbdbc4 100644 --- a/types/new-relic-browser/new-relic-browser-tests.ts +++ b/types/new-relic-browser/new-relic-browser-tests.ts @@ -1,5 +1,14 @@ -// The following tests are largely taken straight from the examples -// at https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api +// The following tests are largely taken straight from the examples at +// https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api + +import { NewRelicAPI } from "new-relic-browser"; + +// Test that we can import and use the newrelic type +let newrelicCopy: NewRelicAPI = newrelic; // $ExpectType NewRelicAPI + +// Test whether the global newrelic object is defined (keeping the behavior +// consistent with the original namespace version) +newrelic; // $ExpectType NewRelicAPI // --- NewRelic.Browser methods ----------------------------------------------