// @ts-ignore import type { EventEmitter } from 'events' /** The Cobrowse Agent SDK provides a way to interact with the Cobrowse APIs for a variety of use cases. * Primarily this library is designed for building a fully white-labeled version of Cobrowse, including * custom user interfaces and styling to match your own platform. * * The library can be used either from the browser (most common), or a NodeJS environment. Note: not all APIs are * available when used in NodeJS. */ export default class CobrowseAPI extends EventEmitter { /** Create a new Agent SDK instance. An instance encapsulates information about your API location (if * using the self-hosted Cobrowse Enterprise option), and optionally, the authorization token for the * agent using the SDK. * * **Options** * * `api` - The url for an Enterprise Cobrowse instance. You do not need to configure this when using our global hosted service. * * ```javascript * const token = await myJWTGeneratingFunction() * const cobrowse = new CobrowseAPI(token, { api: 'https://cobrowse.example.com' }) * ``` * @param token - The [JWT](https://docs.cobrowse.io/agent-side-integrations/json-web-tokens-jwts) for API authorization. * @param options - Options for configuring this instance of CobrowseAPI. */ constructor (token?: string, options?: Record) /** The [JWT](https://docs.cobrowse.io/agent-side-integrations/json-web-tokens-jwts) for API authorization. * This token should be securely generated by your backend to authorize use of the Cobrowse APIs.*/ get token (): string set token (token: string) /** The license key for the Cobrowse account. This uniquely identifies your account within Cobrowse, you may * choose to have different license keys for development, test, and production environments. */ get license (): string set license (license: string) /** The url for the Cobrowse instance. */ get api (): string /** Namespace API for accounts. */ get accounts (): AccountsAPI /** Namespace API for devices. A device in Cobrowse is how a single instance of an app or website is tracked by Cobrowse. */ get devices (): DevicesAPI /** Namespace API for sessions. A session in Cobrowse represents a single screensharing activity with an agent. */ get sessions (): SessionsAPI /** Namespace API for recordings. A recording in Cobrowse represents the video and event metadata for a recorded session. */ get recordings (): SessionRecordingAPI /** Namespace API for users. */ get users (): UsersAPI /** Namespace API for policies. */ get policies (): PolicyAPI /** Namespace API for regions. A region in Cobrowse represents a Cobrowse socket server deployment in a particular geographical region. */ get regions (): RegionsAPI /** Attach the agent context to an iframe; no JWT is required to use these APIs. * The returned context allows you to control certain elements within the iframe hosting * the screenshare. For example, you may switch the active agent tool being used, change the * session into a "full device" mode session, or just subscribe to changes in the session parameters. * * ```javascript * const cobrowse = new CobrowseAPI() * const frameEl = document.getElementById('myIframe') * const ctx = await cobrowse.attachContext(frameEl) * * ctx.on('session.updated', (session) => { * console.log('session was updated', session) * }) * ``` * * @param target - An iframe element. * @returns {Promise} - The context returns contains methods specific to controlling the iframe */ attachContext (target: HTMLIFrameElement): Promise /** Disconnect any open sockets */ disconnect (): void } export interface DeviceInfo { /** An identifier for the app being used (e.g. the domain name, or iOS app ID). */ app_id: string /** The name of the app being used by the end user. */ app_name: string /** The type of the device being used, e.g. iPhone or Chrome Browser. */ device: string /** The preferred locale of the user's device. */ device_locale: string /** The timezone of the user's device. */ device_timezone: string /** The OS version of the device. */ os_version: string /** Which platform is being used, e.g. web, ios, android, windows, macos */ platform: 'web' | 'ios' | 'android' | 'windows' | 'macos' /** The version of the Cobrowse SDK that the device is running */ sdk_version: string /** (Android only) Indicates whether full device remote control is currently available */ full_device_control: boolean } /** Represents a device in Cobrowse. A device in Cobrowse is how a single instance of an app or website is tracked by Cobrowse. * Each website within each different browser on a user's machine will be tracked as a separate device. Devices can be listed * and filtered by support agents to find a specific user's device. Read more about * [Identifying your devices](https://docs.cobrowse.io/sdk-features/identify-your-devices) to add metadata for filtering. * * ```javascript * const cobrowse = new CobrowseAPI(...) * const device = await cobrowse.device.get('some device id here') * device.subscribe() * device.on('updated', d => console.log('device was updated', d)) * ``` * * ### Events * * @fires updated - The updated event will be fired when device data changes. */ export interface Device extends EventEmitter { /** The unique ID of this device, generated internally by the Cobrowse SDKs. You cannot control this value. */ id: string /** The last time the device was seen */ last_active: Date /** Is the device currently connected to the Cobrowse service */ online: boolean /** Is the device in a state where it can accept a screenshare connection */ connectable: boolean /** The metadata you have associated with this device for discoverability and filtering by agents */ custom_data: Record /** The device metadata exposed by the Cobrowse SDKs */ device: DeviceInfo /** Listen for events on this device. */ on (event: string, listener: (device: Device) => void): this /** Subscribe to changes in this device. Note: this is a browser only method and will not work from a NodeJS environment */ subscribe (): Promise /** Unsubscribe from this device. Note: this is a browser only method and will not work from a NodeJS environment */ unsubscribe (): void /** Push a notification to the device indicating the agent wants to start a cobrowse session */ notify ( args: { /** The session to push to the device */ session: Session, /** The attempt, defaults to 1 when omitted */ attempt?: number }, query?: Record, options?: RequestOptions ): Promise /** Converts this device instance to a plain object. */ toJSON (): Device } export interface DevicesAPI { /** * Get a device by ID. * * ```javascript * const cobrowse = new CobrowseAPI(...) * const device = await cobrowse.devices.get('some device id here') * ``` */ get (id: string, query?: Record, options?: RequestOptions): Promise /** List devices, optionally filter by query parameters. * * Supported query parameters: * * `filter_XXX` - where XXX is replaced by your customData field names. e.g. filter_user_id=abc would filter devices with `customData = { user_id: 'abc' }` * * `seen_before` - only include devices that checked-in with the Cobrowse service before this date * * `seen_after` - only include devices that checked-in with the Cobrowse service after this date * * * ```javascript * const cobrowse = new CobrowseAPI(...) * const devices = await cobrowse.devices.list({ filter_user_id: 'abcdef' } }) * ``` */ list (query?: Record, options?: RequestOptions): Promise } /** Control Cobrowse hosted in an iframe from a parent context. Note: these are browser only methods and will not work from a NodeJS environment * * ### Events * * @fires session.updated - This event is fired when a property of the session is changed, for example full_device mode is switched on of off. * @fires session.metrics.updated - This event is fired when the session metrics are changed, for example the last_alive updated or there is a rtt probe update. * @fires screen.updated - This event is triggered when some metadata about the screen changes, for example the size or orientation. Note, this event is only available via the RemoteContext. * @fires error - This event is triggered when an error happens in the iframe (e.g. a license limit is hit) */ export interface RemoteContext extends EventEmitter { /** Listen for events in this context. */ on (event: string, listener: (param: any) => void): this /** Stop listening for events in this context. */ off (event: string, listener: (param: any) => void): this /** * Set the tool to use in the Agent session. * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.setTool('drawing') * ``` */ setTool (tool: 'laser' | 'drawing' | 'control'): Promise /** * Clear all agent session annotations from the user's view. * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.clearAnnotations() * ``` */ clearAnnotations (): Promise /** * End the current agent session. * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.endSession() * ``` */ endSession (): Promise /** Set the current state of the session full-device mode. A full device session enables * the agent to capture all screens of the user's device, not just those inside your app * or website. Initiates request or ends full-device mode. The user must approve when switching * to full device mode. * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.setFullDevice('requested') * ``` */ setFullDevice (state: 'off' | 'requested'): Promise /** Set the current state of remote control, allowing the agent to request remote control of * the user's device. Initiate or end remote control. * Note: The agent may not set the remote control state to `on` directly, they can only * set it to `requested` and the user must approve if required. * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.setRemoteControl('requested') * ``` */ setRemoteControl (state: 'on' | 'off' | 'requested' | 'rejected'): Promise /** * Triggers the Android Back button * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.androidBack() * ``` */ androidBack (): Promise /** * Triggers the Android Home button * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.androidHome() * ``` */ androidHome (): Promise /** * Destroy this remote context; stops listening for events and detaches from the iframe. * * ```javascript * const cobrowse = new CobrowseAPI() * const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id')) * ctx.destroy() * ``` */ destroy (): void /** Namespace API for users. */ get users (): UsersAPI } /** Represents a session in Cobrowse. * * ### Events * * @fires updated - fired when a session property changes * @fires ended - fired when a session transitions to the `ended` state */ export interface Session extends EventEmitter { /** The unique ID for this screenshare session */ id: string /** A 6 digit, human friendly code that can be used to initiate a session */ code: string /** The current state of the session. A session will progress through its lifecycle in * this order: `pending` → (`authorizing` →) `active` → `ended`. Only session that require * user consent will enter the `authorizing` state. */ state: 'pending' | 'authorizing' | 'active' | 'ended' /** The metadata you have associated with this session for discoverability and filtering by agents. */ custom_data: Record /** Was the session recorded */ recorded: boolean /** The activation timestamp of the session. This is the time the user accepted the session. */ activated: Date /** Metadata about the agent that started the session */ agent: Agent /** List of agents who viewed the session */ agents: Agent[] /** The date the session was first created (this will usually be before the `activated` timestamp). */ created: Date /** Metadata about the user's device */ device: DeviceInfo /** The timestamp the session was ended */ ended: Date | null /** The timestamp when the session expires */ expires: Date /** The state of the full device mode */ full_device: 'on' | 'off' | 'requested' | 'rejected' /** The state of the remote control authorization for the session */ remote_control: 'on' | 'off' | 'requested' | 'rejected' /** The reason the session ended */ ended_reason: 'device_ended' | 'agent_ended' | 'pending_timeout' | 'authorizing_timeout' | 'active_timeout' | 'limit_enforcement' | undefined /** The timestamp of the last update to the session */ updated: Date /** The state of the calling mode */ calling: 'on' | 'off' | 'requested' | 'rejected' /** Whether this is a virtual session */ virtual: boolean /** Listen for events on this session. */ on (event: 'ended', listener: (session: Session) => void): this on (event: 'updated', listener: (session: Session) => void): this /** Stop listening for events on this session. */ off (event: 'ended', listener: (session: Session) => void): this off (event: 'updated', listener: (session: Session) => void): this /** Ends this session. */ end (state?: 'ended', query?: Record, options?: RequestOptions): Promise /** Gets the recording for this session. * @deprecated Use {@link getRecording} instead. */ recording (query?: Record, options?: RequestOptions): Promise /** Gets the recording for this session. */ getRecording (query?: Record, options?: RequestOptions): Promise /** True if the session is active. An active session is one where the user has accepted * the screen share if required and frame are streaming to the agent */ isActive (): boolean /** True if the session is authorizing. An authorizing session is one where the user has * been presented with a consent dialog but has not yet agreed. */ isAuthorizing (): boolean /** True if the session is pending. A pending session is the inital state, waiting for * either a device or agent to join */ isPending (): boolean /** True if the session is ended. */ isEnded (): boolean /** Set the current state of the session full-device mode. A full device session enables * the agent to capture all screens of the user's device, not just those inside your app * or website. Initiates request or ends full-device mode. The user must approve when switching * to full device mode. */ setFullDevice (state: 'off' | 'requested', query?: Record, options?: RequestOptions): Promise /** Set the current state of remote control, allowing the agent to request remote control of * the user's device. Initiate or end remote control. * Note: The agent may not set the remote control state to `on` directly, they can only * set it to `requested` and the user must approve if required. */ setRemoteControl (state: 'on' | 'off' | 'requested' | 'rejected', query?: Record, options?: RequestOptions): Promise /** Subscribe to changes in this session. Note: this is a browser only method and will not work from a NodeJS environment */ subscribe (): Promise /** Unsubscribe from this session. Note: this is a browser only method and will not work from a NodeJS environment */ unsubscribe (): void /** * Update the session * * @param state Additional state to serialize into the session * @param query Query string parameters, if any for the update endpoint */ update ( state?: Partial< Pick & { agent: 'me', region: string } >, query?: Record, options?: RequestOptions ): Promise /** Converts this session instance to a plain object. */ toJSON (): Session } export interface SessionsQuery { /** `filter_XXX` - where XXX is replaced by your customData field names. e.g. filter_user_id=abc would filter devices with `customData = { user_id: 'abc' }` */ [key: `filter_${string}`]: string | undefined /** `activated_before` - only include sessions that were activated before this date. Useful for paging. */ activated_before?: Date /** `activated_after` - only include devices that were activated after this date. Useful for paging. */ activated_after?: Date /** `agent` - Administrator may set this to `all` to list sessions for all agents. Agent roles may only list their own sessions. */ agent?: string /** `state` - Filter by session that are in one of the supported states: `pending`, `authorizing`, `active`, `ended`. */ state?: string | string[] /** `limit` - Limit the number of results. */ limit?: number } export interface SessionsAPI { /** Create a session, optionally passing additional query parameters. */ create (resource?: any, query?: Record, options?: RequestOptions): Promise /** Get a session by ID */ get (id: string, query?: Record, options?: RequestOptions): Promise /** List sessions, optionally filter by query parameters. */ list (query?: SessionsQuery, options?: RequestOptions): Promise } /** Represents a session recording in Cobrowse. */ export interface SessionRecording extends EventEmitter { /** The unique ID for this recording */ id: string /** Provides access to the video for this recording */ video: { /** Returns a fetch() response containing the video data */ fetch (): Promise /* Returns a promise with the raw URL of the video. Note that these URLs contain short-lived tokens */ url (): Promise } /** Deletes this recording from the server */ destroy (query?: Record, options?: RequestOptions): Promise /** Gets the list of events for this recording */ events (): Promise /** Converts this session instance to a plain object. */ toJSON (): SessionRecording } export interface SessionRecordingAPI { /** Get a recording by (Session) ID */ get (id: string, query?: Record, options?: RequestOptions): Promise /** Deletes a recording by its ID */ destroy (id: string, query?: Record, options?: RequestOptions): Promise } /** Represents a user in Cobrowse. */ export interface User extends EventEmitter { id: string /** Listen for events on this user. */ on (event: 'updated', listener: (user: User) => void): this /** Converts this device instance to a plain object. */ toJSON (): User } export interface UsersAPI { /** Get a user by ID and optionally filter by query parameters. */ get (id: string, query?: Record, options?: RequestOptions): Promise /** Get the current user. */ current (query?: Record, options?: RequestOptions): Promise } /** Represents an agent */ export interface Agent { /** The unique ID for the agent */ id: string /** The agent's name */ name: string /** Agent icon background colour as a hex value */ colour: string /** Agent email address (requires `Hide agent emails` to be disabled in the Cobrowse accounts) */ email?: string /** Optional url to a profile picture */ picture?: string } /** Represents an account in Cobrowse. */ export interface Account extends EventEmitter { /** The unique ID for this account */ id: string /** The license key for this account */ license_key: string; /** Provides the account features */ features: Record /** Converts this account instance to a plain object */ toJSON (): Account } export interface AccountsAPI { /** List accounts * * ```javascript * const cobrowse = new CobrowseAPI(...) * const accounts = await cobrowse.accounts.list() * ``` */ list (query?: Record, options?: RequestOptions): Promise } /** Represents a policy in Cobrowse. */ export interface Policy extends EventEmitter { /** Check if the policy has a specific permission */ hasPermission (permission: string): boolean /** Converts this policy instance to a plain object. */ toJSON (): Policy } export interface PolicyAPI { /** Get the current policy */ current (query?: Record, options?: RequestOptions): Promise } export interface RegionsAPI { /** Get the closest geographical region */ closest (query?: Record, options?: RequestOptions): Promise } /** * Represents a Cobrowse socket server deployment in a particular geographical * region. */ export interface Region extends EventEmitter { /** The unique ID for this region */ id: string /** Converts this region instance to a plain object. */ toJSON (): Region } export interface RequestOptions { signal?: AbortSignal } /** An error received from the Cobrowse API */ export class APIError extends Error { /** The internal cobrowse identifier for the error */ id: string /** An optional HTTP status code */ status: number | null }