diff --git a/src/app-automate.ts b/src/app-automate.ts index 57ec285..8c55d01 100644 --- a/src/app-automate.ts +++ b/src/app-automate.ts @@ -3,7 +3,16 @@ import { BrowserStackError } from "@/error"; import { operations } from "@/generated/openapi"; import { FetchOptions } from "openapi-fetch"; +/** + * AppAutomateClient represents a client for interacting with the BrowserStack App Automate API. + * @see https://www.browserstack.com/app-automate/rest-api + * @public + */ export class AppAutomateClient extends APIClient { + /** + * Constructs a new instance of the AppAutomateClient class. + * @param options - Optional configuration options for the client. + */ constructor(options?: APIClientOptions) { super({ ...options, @@ -11,18 +20,39 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the plan information for App Automate. + * @param options - The fetch options for the request. + * @returns A promise that resolves with the plan information. + */ getPlan(options?: FetchOptions) { return this.makeGetRequest("/app-automate/plan.json", options); } + /** + * Retrieves the list of devices available for App Automate. + * @param options - The fetch options for the request. + * @returns A promise that resolves with the list of devices. + */ getDevices(options?: FetchOptions) { return this.makeGetRequest("/app-automate/devices.json", options); } + /** + * Retrieves the projects from the App Automate API. + * @param options - The fetch options for the API request. + * @returns A promise that resolves with the projects. + */ getProjects(options?: FetchOptions) { return this.makeGetRequest("/app-automate/projects.json", options); } + /** + * Retrieves a project by its ID. + * @param projectId The ID of the project to retrieve. + * @param options Additional options for the fetch request. + * @returns A promise that resolves to the retrieved project. + */ getProject(projectId: number, options?: FetchOptions) { return this.makeGetRequest("/app-automate/projects/{projectId}.json", { ...options, @@ -34,6 +64,14 @@ export class AppAutomateClient extends APIClient { }).then((data) => data.project); } + /** + * Updates a project in the App Automate API. + * + * @param projectId - The ID of the project to update. + * @param body - The request body containing the updated project data. + * @param options - Additional options for the request. + * @returns A promise that resolves with the updated project data. + */ updateProject( projectId: number, body: operations["updateAppAutomateProject"]["requestBody"]["content"]["application/json"], @@ -53,6 +91,12 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Deletes a project. + * @param projectId The ID of the project to delete. + * @param options The fetch options for the delete request. + * @returns A promise that resolves when the project is successfully deleted. + */ deleteProject( projectId: number, options?: FetchOptions @@ -67,6 +111,12 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the badge key for a specific project. + * @param projectId The ID of the project. + * @param options Additional options for the fetch request. + * @returns A promise that resolves to the badge key. + */ getBadgeKey( projectId: number, options?: Omit< @@ -85,6 +135,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves a list of builds from the App Automate API. + * + * @param query - Optional query parameters for filtering the builds. + * @param options - Optional fetch options for the API request. + * @returns A promise that resolves to an array of automation builds. + */ getBuilds( query?: operations["getAppAutomateBuilds"]["parameters"]["query"], options?: FetchOptions @@ -97,6 +154,12 @@ export class AppAutomateClient extends APIClient { }).then((data) => data.map((build) => build.automation_build)); } + /** + * Retrieves information about a specific build. + * @param id - The ID of the build to retrieve. + * @param options - Additional options for the fetch request. + * @returns A promise that resolves to the build information, including the build details and associated sessions. + */ getBuild( id: string, options?: Omit, "params"> @@ -116,6 +179,15 @@ export class AppAutomateClient extends APIClient { })); } + /** + * Updates a build in the App Automate API. + * + * @param id - The ID of the build to update. + * @param body - The request body containing the updated build information. + * @param options - Additional options for the request. + * @returns A Promise that resolves to the updated build. + * @throws {BrowserStackError} If an error occurs during the update. + */ updateBuild( id: string, body: operations["updateAppAutomateBuild"]["requestBody"]["content"]["application/json"], @@ -141,6 +213,12 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Deletes a build with the specified ID. + * @param id The ID of the build to delete. + * @param options Additional options for the delete request. + * @returns A promise that resolves when the build is successfully deleted. + */ deleteBuild( id: string, options?: Omit, "params"> @@ -155,6 +233,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Uploads terminal logs for a specific build. + * @param buildId - The ID of the build. + * @param body - The request body containing the logs file and its filename. + * @param options - Additional options for the request. + * @returns A promise that resolves to the response of the request. + */ uploadBuildTerminalLogs( buildId: string, body: operations["uploadAppAutomateBuildTerminalLogs"]["requestBody"]["content"]["multipart/form-data"] & { @@ -182,6 +267,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Uploads terminal logs for a session. + * @param sessionId - The ID of the session. + * @param body - The request body containing the logs file and filename. + * @param options - Additional options for the request. + * @returns A promise that resolves to the response of the request. + */ uploadSessionTerminalLogs( sessionId: string, body: operations["uploadAppAutomateSessionTerminalLogs"]["requestBody"]["content"]["multipart/form-data"] & { @@ -209,6 +301,12 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the session details for a given session ID. + * @param sessionId - The ID of the session to retrieve. + * @param options - Additional options for the fetch request. + * @returns A promise that resolves to the automation session data. + */ getSession( sessionId: string, options?: Omit, "params"> @@ -223,6 +321,14 @@ export class AppAutomateClient extends APIClient { }).then((data) => data.automation_session); } + /** + * Updates the status of a session in the App Automate API. + * + * @param sessionId - The ID of the session to update. + * @param body - The request body containing the updated session status. + * @param options - Additional options for the API request. + * @returns A Promise that resolves to the updated automation session. + */ updateSessionStatus( sessionId: string, body: operations["updateAppAutomateSession"]["requestBody"]["content"]["application/json"], @@ -242,6 +348,12 @@ export class AppAutomateClient extends APIClient { }).then((data) => data.automation_session); } + /** + * Deletes a session in the App Automate API. + * @param sessionId - The ID of the session to delete. + * @param options - Additional options for the delete request. + * @returns A promise that resolves when the session is successfully deleted. + */ deleteSession( sessionId: string, options?: Omit, "params"> @@ -256,6 +368,14 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the session logs for a specific build and session. + * + * @param buildId - The ID of the build. + * @param sessionId - The ID of the session. + * @param options - Additional options for the request. + * @returns A Promise that resolves to the session logs. + */ getSessionLogs( buildId: string, sessionId: string, @@ -273,6 +393,14 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the device logs for a specific session. + * + * @param buildId - The ID of the build. + * @param sessionId - The ID of the session. + * @param options - Additional options for the request. + * @returns A Promise that resolves with the device logs. + */ getSessionDeviceLogs( buildId: string, sessionId: string, @@ -290,6 +418,14 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the Appium logs for a specific session. + * + * @param buildId - The ID of the build. + * @param sessionId - The ID of the session. + * @param options - Additional options for the request. + * @returns A Promise that resolves to the Appium logs. + */ getSessionAppiumLogs( buildId: string, sessionId: string, @@ -307,6 +443,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the network logs for a specific session in a build. + * @param buildId The ID of the build. + * @param sessionId The ID of the session. + * @param options Additional options for the network logs request. + * @returns A Promise that resolves to the network logs response. + */ getSessionNetworkLogs( buildId: string, sessionId: string, @@ -323,6 +466,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the app profiling data for a specific session in a build. + * @param buildId The ID of the build. + * @param sessionId The ID of the session. + * @param options Additional options for the request. + * @returns A promise that resolves to the app profiling data. + */ getSessionAppProfilingDataV1( buildId: string, sessionId: string, @@ -339,6 +489,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the app profiling data for a specific session in a build. + * @param buildId The ID of the build. + * @param sessionId The ID of the session. + * @param options Additional options for the API request. + * @returns A promise that resolves with the app profiling data. + */ getSessionAppProfilingDataV2( buildId: string, sessionId: string, @@ -355,6 +512,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Uploads a media file to the App Automate API. + * + * @param body - The request body containing the media file to upload. + * @param options - Optional fetch options for the request. + * @returns A promise that resolves to the response of the API request. + */ uploadMediaFile( body: operations["uploadAppAutomateMediaFile"]["requestBody"]["content"]["multipart/form-data"] & { filename: string; @@ -380,6 +544,12 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the media files associated with the App Automate session. + * + * @param options - Optional fetch options for the request. + * @returns A promise that resolves to an array of media files, or an empty array if no media files are found. + */ getMediaFiles( options?: FetchOptions ) { @@ -389,6 +559,12 @@ export class AppAutomateClient extends APIClient { ).then((data) => ("message" in data ? [] : data)); } + /** + * Retrieves media files by custom ID. + * @param customId - The custom ID to filter media files. + * @param options - Optional fetch options. + * @returns A promise that resolves to an array of media files or an empty array if no media files are found. + */ getMediaFilesByCustomId( customId: string, options?: FetchOptions @@ -403,6 +579,12 @@ export class AppAutomateClient extends APIClient { }).then((data) => ("message" in data ? [] : data)); } + /** + * Retrieves the group's media files from the App Automate API. + * + * @param options - Optional fetch options for the API request. + * @returns A promise that resolves to an array of group media files, or an empty array if the response contains a "message" property. + */ getGroupMediaFiles( options?: FetchOptions ) { @@ -412,6 +594,12 @@ export class AppAutomateClient extends APIClient { ).then((data) => ("message" in data ? [] : data)); } + /** + * Deletes a media file from the app automate custom media. + * @param mediaId The ID of the media file to delete. + * @param options The fetch options for the delete request. + * @returns A promise that resolves when the media file is successfully deleted. + */ deleteMediaFile( mediaId: string, options?: FetchOptions @@ -429,6 +617,13 @@ export class AppAutomateClient extends APIClient { ); } + /** + * Uploads an Appium app to BrowserStack App Automate. + * + * @param body - The request body containing the app file or URL to be uploaded. + * @param options - Additional options for the request. + * @returns A Promise that resolves to the response of the upload request. + */ uploadAppiumApp( body: operations["uploadAppAutomateApp"]["requestBody"]["content"]["multipart/form-data"] & { filename: string; @@ -458,12 +653,24 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the list of Appium apps from the App Automate API. + * + * @param options - Optional fetch options for customizing the request. + * @returns A promise that resolves to an array of Appium apps, or an empty array if no apps are found. + */ getAppiumApps(options?: FetchOptions) { return this.makeGetRequest("/app-automate/recent_apps", options).then( (data) => ("message" in data ? [] : data) ); } + /** + * Retrieves the Appium apps by custom ID. + * @param customId The custom ID of the app. + * @param options The fetch options for the request. + * @returns A promise that resolves to the retrieved Appium apps. + */ getAppiumAppsByCustomId( customId: string, options?: FetchOptions @@ -478,6 +685,11 @@ export class AppAutomateClient extends APIClient { }).then((data) => ("message" in data ? [] : data)); } + /** + * Retrieves the list of App Automate apps for the group using the specified fetch options. + * @param options The fetch options for the request. + * @returns A promise that resolves to the list of group apps, or an empty array if there is a "message" property in the response data. + */ getAppiumGroupApps( options?: FetchOptions ) { @@ -486,6 +698,13 @@ export class AppAutomateClient extends APIClient { ); } + /** + * Deletes an Appium app. + * + * @param appId - The ID of the app to delete. + * @param options - Optional fetch options for the delete request. + * @returns A promise that resolves when the app is successfully deleted. + */ deleteAppiumApp( appId: string, options?: FetchOptions @@ -500,6 +719,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Uploads a Flutter app for App Automate. + * + * @param body - The request body containing the app file or URL and other optional parameters. + * @param options - Additional options for the request. + * @returns A promise that resolves to the response of the request. + */ uploadFlutterApp( body: operations["uploadAppAutomateFlutterApp"]["requestBody"]["content"]["multipart/form-data"] & { filename: string; @@ -532,6 +758,12 @@ export class AppAutomateClient extends APIClient { ); } + /** + * Retrieves the list of Flutter apps for Android. + * + * @param options - The fetch options for the request. + * @returns A promise that resolves to an array of Flutter apps, or an empty array if no apps are found. + */ getFlutterApps( options?: FetchOptions ) { @@ -541,6 +773,12 @@ export class AppAutomateClient extends APIClient { ).then((data) => ("apps" in data ? data.apps : [])); } + /** + * Retrieves the Flutter app with the specified appId. + * @param appId The ID of the Flutter app to retrieve. + * @param options The fetch options for the request. + * @returns A promise that resolves to the retrieved Flutter app. + */ getFlutterApp( appId: string, options?: FetchOptions @@ -558,6 +796,12 @@ export class AppAutomateClient extends APIClient { ).then((data) => data.app); } + /** + * Deletes a Flutter app from the BrowserStack App Automate service. + * @param appId The ID of the app to delete. + * @param options The fetch options for the delete request. + * @returns A promise that resolves when the app is successfully deleted. + */ deleteFlutterApp( appId: string, options?: FetchOptions @@ -575,6 +819,13 @@ export class AppAutomateClient extends APIClient { ); } + /** + * Uploads an Espresso app to BrowserStack. + * + * @param body - The request body containing the app file or URL. + * @param options - Additional options for the request. + * @returns A promise that resolves to the response from the server. + */ uploadEspressoApp( body: operations["uploadAppAutomateEspressoApp"]["requestBody"]["content"]["multipart/form-data"] & { filename: string; @@ -604,6 +855,11 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the Espresso apps from the App Automate API. + * @param options - The fetch options for the API request. + * @returns A promise that resolves to an array of Espresso apps. + */ getEspressoApps( options?: FetchOptions ) { @@ -612,6 +868,12 @@ export class AppAutomateClient extends APIClient { ); } + /** + * Retrieves the Espresso app with the specified appId. + * @param appId The ID of the Espresso app to retrieve. + * @param options The fetch options for the request. + * @returns A promise that resolves to the retrieved Espresso app. + */ getEspressoApp( appId: string, options?: FetchOptions @@ -626,6 +888,12 @@ export class AppAutomateClient extends APIClient { }).then((data) => data.app); } + /** + * Deletes an Espresso app. + * @param appId The ID of the app to delete. + * @param options The fetch options for the delete request. + * @returns A promise that resolves when the app is deleted. + */ deleteEspressoApp( appId: string, options?: FetchOptions @@ -640,6 +908,13 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Uploads an XCUITest app to BrowserStack App Automate. + * + * @param body - The request body containing the XCUITest app file or URL. + * @param options - Additional options for the request. + * @returns A Promise that resolves to the response of the request. + */ uploadXCUITestApp( body: operations["uploadAppAutomateXCUITestApp"]["requestBody"]["content"]["multipart/form-data"] & { filename: string; @@ -669,6 +944,11 @@ export class AppAutomateClient extends APIClient { }); } + /** + * Retrieves the XCUITest apps available in the BrowserStack App Automate. + * @param options - The fetch options for the request. + * @returns A promise that resolves to an array of XCUITest apps. + */ getXCUITestApps( options?: FetchOptions ) { @@ -677,6 +957,12 @@ export class AppAutomateClient extends APIClient { ); } + /** + * Retrieves the XCUITest app with the specified appId. + * @param appId The ID of the XCUITest app to retrieve. + * @param options The fetch options for the request. + * @returns A promise that resolves to the XCUITest app. + */ getXCUITestApp( appId: string, options?: FetchOptions @@ -691,6 +977,12 @@ export class AppAutomateClient extends APIClient { }).then((data) => data.app); } + /** + * Deletes an XCUITest app. + * @param appId The ID of the app to delete. + * @param options The fetch options for the delete request. + * @returns A promise that resolves when the app is successfully deleted. + */ deleteXCUITestApp( appId: string, options?: FetchOptions diff --git a/src/automate.ts b/src/automate.ts index a0b239e..af383df 100644 --- a/src/automate.ts +++ b/src/automate.ts @@ -3,7 +3,16 @@ import { BrowserStackError } from "@/error"; import { operations } from "@/generated/openapi"; import { FetchOptions } from "openapi-fetch"; +/** + * AutomateClient represents a client for interacting with the BrowserStack Automate API. + * @see https://www.browserstack.com/automate/rest-api + * @public + */ export class AutomateClient extends APIClient { + /** + * Constructs a new instance of the AutomateClient class. + * @param options - Options to customize the client. + */ constructor(options?: APIClientOptions) { super({ ...options, @@ -11,22 +20,48 @@ export class AutomateClient extends APIClient { }); } + /** + * Recycles the automate key. + * @param options The fetch options for the request. + * @returns {} A promise that resolves to the response of the request. + */ recycleKey(options?: FetchOptions) { return this.makePutRequest("/automate/recycle_key.json", options); } + /** + * Retrieves the automate plan. + * @param options - The fetch options for the request. + * @returns A promise that resolves with the automate plan. + */ getPlan(options?: FetchOptions) { return this.makeGetRequest("/automate/plan.json", options); } + /** + * Retrieves the list of available browsers for BrowserStack Automate. + * @param options - Optional fetch options for customizing the request. + * @returns A Promise that resolves to the list of available browsers. + */ getBrowsers(options?: FetchOptions) { return this.makeGetRequest("/automate/browsers.json", options); } + /** + * Retrieves the projects from the BrowserStack Automate API. + * @param options - The fetch options for the API request. + * @returns A promise that resolves with the projects data. + */ getProjects(options?: FetchOptions) { return this.makeGetRequest("/automate/projects.json", options); } + /** + * Retrieves a project by its ID. + * @param id The ID of the project to retrieve. + * @param options Additional options for the fetch request. + * @returns A promise that resolves to the retrieved project. + */ getProject( id: number, options?: Omit, "params"> @@ -41,6 +76,14 @@ export class AutomateClient extends APIClient { }).then((data) => data.project); } + /** + * Updates a project with the specified ID. + * + * @param id - The ID of the project to update. + * @param body - The request body containing the updated project details. + * @param options - Additional options for the request. + * @returns A promise that resolves with the updated project. + */ updateProject( id: number, body: operations["updateAutomateProject"]["requestBody"]["content"]["application/json"], @@ -60,6 +103,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Deletes a project with the specified ID. + * @param id The ID of the project to delete. + * @param options Additional options for the delete request. + * @returns A promise that resolves when the project is successfully deleted. + */ deleteProject( id: number, options?: Omit, "params"> @@ -74,6 +123,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves the badge key for a specific project. + * @param projectId The ID of the project. + * @param options Additional options for the request. + * @returns A promise that resolves to the badge key. + */ getBadgeKey( projectId: number, options?: Omit< @@ -92,6 +147,13 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves a list of builds from the BrowserStack Automate API. + * + * @param query - Optional query parameters for filtering the builds. + * @param options - Optional fetch options for the API request. + * @returns A Promise that resolves to an array of automation builds. + */ getBuilds( query?: operations["getAutomateBuilds"]["parameters"]["query"], options?: FetchOptions @@ -104,6 +166,12 @@ export class AutomateClient extends APIClient { }).then((data) => data.map((build) => build.automation_build)); } + /** + * Retrieves information about a specific build. + * @param id - The ID of the build. + * @param options - Additional options for the request. + * @returns A promise that resolves to the build information. + */ getBuild( id: string, options?: Omit, "params"> @@ -123,6 +191,15 @@ export class AutomateClient extends APIClient { })); } + /** + * Updates a build in the BrowserStack Automate API. + * + * @param id - The ID of the build to update. + * @param body - The request body containing the updated build data. + * @param options - Additional options for the request. + * @returns A promise that resolves to the updated build data. + * @throws {BrowserStackError} If an error occurs during the update. + */ updateBuild( id: string, body: operations["updateAutomateBuild"]["requestBody"]["content"]["application/json"], @@ -140,7 +217,7 @@ export class AutomateClient extends APIClient { }, }, }).then((data) => { - if ('error' in data) { + if ("error" in data) { throw new BrowserStackError(data.error, { response: data }); } @@ -148,6 +225,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Deletes a build with the specified ID. + * @param id The ID of the build to delete. + * @param options Additional options for the delete request. + * @returns A promise that resolves when the build is successfully deleted. + */ deleteBuild( id: string, options?: Omit, "params"> @@ -162,6 +245,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Deletes multiple builds from the BrowserStack Automate API. + * @param buildIds An array of build IDs to be deleted. + * @param options Additional options for the delete request. + * @returns A promise that resolves when the delete request is successful. + */ deleteBuilds( buildIds: string[], options?: Omit, "params"> @@ -176,6 +265,14 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves the sessions associated with a specific build. + * + * @param buildId - The ID of the build. + * @param query - Optional query parameters for filtering the sessions. + * @param options - Optional fetch options for the request. + * @returns A promise that resolves to an array of automation sessions. + */ getSessions( buildId: string, query?: operations["getAutomateSessions"]["parameters"]["query"], @@ -192,6 +289,12 @@ export class AutomateClient extends APIClient { }).then((data) => data.map((session) => session.automation_session)); } + /** + * Retrieves the details of a specific session. + * @param sessionId - The ID of the session to retrieve. + * @param options - Additional options for the fetch request. + * @returns A promise that resolves to the automation session data. + */ getSession( sessionId: string, options?: Omit, "params"> @@ -206,6 +309,14 @@ export class AutomateClient extends APIClient { }).then((data) => data.automation_session); } + /** + * Updates an automate session. + * + * @param sessionId - The ID of the session to update. + * @param body - The request body containing the updated session data. + * @param options - Additional options for the request. + * @returns A promise that resolves to the updated automation session. + */ updateSession( sessionId: string, body: operations["updateAutomateSession"]["requestBody"]["content"]["application/json"], @@ -225,6 +336,12 @@ export class AutomateClient extends APIClient { }).then((data) => data.automation_session); } + /** + * Deletes a session by its session ID. + * @param sessionId The ID of the session to delete. + * @param options Additional options for the delete request. + * @returns A promise that resolves when the session is successfully deleted. + */ deleteSession( sessionId: string, options?: Omit, "params"> @@ -239,6 +356,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Deletes the specified sessions. + * @param sessionIds - An array of session IDs to delete. + * @param options - Additional options for the delete request. + * @returns A promise that resolves when the delete request is complete. + */ deleteSessions( sessionIds: string[], options?: Omit, "params"> @@ -253,6 +376,13 @@ export class AutomateClient extends APIClient { }); } + /** + * Uploads terminal logs for a specific build. + * @param buildId - The ID of the build. + * @param body - The request body containing the logs file and its filename. + * @param options - Additional options for the request. + * @returns A promise that resolves to the response of the request. + */ uploadBuildTerminalLogs( buildId: string, body: operations["uploadAutomateBuildTerminalLogs"]["requestBody"]["content"]["multipart/form-data"] & { @@ -264,22 +394,32 @@ export class AutomateClient extends APIClient { > ) { // makePostRequest produces a non-JSON response - return this.makeCloudPostRequest("/automate/builds/{buildId}/terminallogs", { - ...options, - body, - bodySerializer: () => { - const formData = new FormData(); - formData.append("file", body.file, body.filename); - return formData; - }, - params: { - path: { - buildId, + return this.makeCloudPostRequest( + "/automate/builds/{buildId}/terminallogs", + { + ...options, + body, + bodySerializer: () => { + const formData = new FormData(); + formData.append("file", body.file, body.filename); + return formData; }, - }, - }); + params: { + path: { + buildId, + }, + }, + } + ); } + /** + * Uploads terminal logs for a session. + * @param sessionId - The ID of the session. + * @param body - The request body containing the logs file and filename. + * @param options - Additional options for the request. + * @returns A promise that resolves to the response of the request. + */ uploadSessionTerminalLogs( sessionId: string, body: operations["uploadAutomateSessionTerminalLogs"]["requestBody"]["content"]["multipart/form-data"] & { @@ -291,22 +431,32 @@ export class AutomateClient extends APIClient { > ) { // makePostRequest produces a non-JSON response - return this.makeCloudPostRequest("/automate/sessions/{sessionId}/terminallogs", { - ...options, - body, - bodySerializer: () => { - const formData = new FormData(); - formData.append("file", body.file, body.filename); - return formData; - }, - params: { - path: { - sessionId, + return this.makeCloudPostRequest( + "/automate/sessions/{sessionId}/terminallogs", + { + ...options, + body, + bodySerializer: () => { + const formData = new FormData(); + formData.append("file", body.file, body.filename); + return formData; }, - }, - }); + params: { + path: { + sessionId, + }, + }, + } + ); } + /** + * Retrieves the logs for a specific session. + * + * @param sessionId - The ID of the session. + * @param options - Additional options for the request. + * @returns A promise that resolves with the logs of the session. + */ getSessionLogs( sessionId: string, options?: Omit, "params"> @@ -322,6 +472,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves the network logs for a specific session. + * @param sessionId - The ID of the session. + * @param options - Additional options for the network logs request. + * @returns A Promise that resolves to the network logs response. + */ getSessionNetworkLogs( sessionId: string, options?: Omit< @@ -339,6 +495,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves the console logs for a specific session. + * @param sessionId The ID of the session. + * @param options Additional options for the request. + * @returns A Promise that resolves to the console logs. + */ getSessionConsoleLogs( sessionId: string, options?: Omit< @@ -357,6 +519,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves the Selenium logs for a specific session. + * @param sessionId The ID of the session. + * @param options Additional options for the request. + * @returns A Promise that resolves to the Selenium logs. + */ getSessionSeleniumLogs( sessionId: string, options?: Omit< @@ -365,17 +533,27 @@ export class AutomateClient extends APIClient { > ) { // makeGetRequest produces a non-JSON response - return this.makeCloudGetRequest("/automate/sessions/{sessionId}/seleniumlogs", { - ...options, - params: { - path: { - sessionId, + return this.makeCloudGetRequest( + "/automate/sessions/{sessionId}/seleniumlogs", + { + ...options, + params: { + path: { + sessionId, + }, }, - }, - parseAs: "text", - }); + parseAs: "text", + } + ); } + /** + * Retrieves the Appium logs for a specific session. + * + * @param sessionId - The ID of the session. + * @param options - Additional options for the request. + * @returns A Promise that resolves to the Appium logs. + */ getSessionAppiumLogs( sessionId: string, options?: Omit< @@ -394,6 +572,12 @@ export class AutomateClient extends APIClient { }); } + /** + * Retrieves the telemetry logs for a specific session. + * @param sessionId - The ID of the session. + * @param options - Additional options for the request. + * @returns A Promise that resolves with the telemetry logs. + */ getSessionTelemetryLogs( sessionId: string, options?: Omit< @@ -411,6 +595,13 @@ export class AutomateClient extends APIClient { }); } + /** + * Uploads a media file to the BrowserStack Automate API. + * + * @param body - The content of the media file to be uploaded, along with its filename. + * @param options - Additional options for the API request. + * @returns A Promise that resolves to the response of the API request. + */ uploadMediaFile( body: operations["uploadAutomateMediaFile"]["requestBody"]["content"]["multipart/form-data"] & { filename: string; @@ -431,12 +622,21 @@ export class AutomateClient extends APIClient { }); } - getMediaFiles( - options?: FetchOptions - ) { + /** + * Retrieves the recent media files from the BrowserStack Automate API. + * @param options - Optional fetch options for the API request. + * @returns A promise that resolves with the response from the API. + */ + getMediaFiles(options?: FetchOptions) { return this.makeGetRequest("/automate/recent_media_files", options); } + /** + * Deletes a media file. + * @param mediaId The ID of the media file to delete. + * @param options Additional options for the delete request. + * @returns A promise that resolves when the media file is successfully deleted. + */ deleteMediaFile( mediaId: string, options?: Omit< diff --git a/src/client.ts b/src/client.ts index b97c5a1..c2f5108 100644 --- a/src/client.ts +++ b/src/client.ts @@ -2,7 +2,11 @@ import { FetchOptions, FetchResponse } from "openapi-fetch"; import { APIClient } from "@/api"; import { components, operations } from "@/generated/openapi"; +/** + * BrowserStackClient represents a client for interacting with the BrowserStack API. + */ export class BrowserStackClient extends APIClient { + async getBrowsers( options?: FetchOptionsFlat ): Promise>; @@ -11,6 +15,12 @@ export class BrowserStackClient extends APIClient { options?: FetchOptionsFlat ): Promise>; + /** + * Retrieves a list of browsers from the server. + * + * @param options - The fetch options for the request. + * @returns A promise that resolves to a fetch response containing the list of browsers. + */ async getBrowsers( options?: FetchOptions ): Promise> { diff --git a/src/error.ts b/src/error.ts index 854a565..0b345b5 100644 --- a/src/error.ts +++ b/src/error.ts @@ -6,6 +6,9 @@ export type ErrorContext

= (FetchOptions & { response: T; }) | Error; +/** + * BrowserStackError represents an error returned from a BrowserStack Client. + */ export class BrowserStackError< P extends keyof paths, T = FetchResponse diff --git a/src/index.ts b/src/index.ts index e94728c..85a1d0a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,10 +2,13 @@ import { AppAutomateClient as AAS } from "@/app-automate"; import { AutomateClient as AS } from "@/automate"; import { BrowserStackError } from "@/error"; import { ScreenshotsClient as SC } from "@/screenshots"; + export type { APIClientOptions as BrowserStackOptions } from "@/api"; export type AutomateClient = AS; + export type ScreenshotsClient = SC; + export type AppAutomateClient = AAS; export const BrowserStack = { diff --git a/src/screenshots.ts b/src/screenshots.ts index aaa67ee..1c71f42 100644 --- a/src/screenshots.ts +++ b/src/screenshots.ts @@ -2,7 +2,16 @@ import { APIClient, APIClientOptions } from "@/api"; import type { operations } from "@/generated/openapi"; import type { FetchOptions } from "openapi-fetch"; +/** + * ScreenshotsClient represents a client for interacting with the BrowserStack Screenshots API. + * @see https://www.browserstack.com/screenshots/api + * @public + */ export class ScreenshotsClient extends APIClient { + /** + * Constructs a new instance of the ScreenshotsClient class. + * @param options - Optional configuration options for the client. + */ constructor(options?: APIClientOptions) { super({ ...options, @@ -10,10 +19,21 @@ export class ScreenshotsClient extends APIClient { }); } + /** + * Retrieves the list of available browsers for taking screenshots. + * @param options - Optional fetch options for the request. + * @returns A promise that resolves to the response from the API. + */ getBrowsers(options?: FetchOptions) { return this.makeGetRequest("/screenshots/browsers.json", options); } + /** + * Creates a new screenshots job. + * @param body - The request body for creating the job. + * @param options - Optional fetch options for the request. + * @returns A promise that resolves to the response from the API. + */ createJob( body: operations["createScreenshotsJob"]["requestBody"]["content"]["application/json"], options?: FetchOptions @@ -24,6 +44,12 @@ export class ScreenshotsClient extends APIClient { }); } + /** + * Retrieves the details of a screenshots job. + * @param jobId - The ID of the job to retrieve. + * @param options - Optional fetch options for the request. + * @returns A promise that resolves to the response from the API. + */ getJob( jobId: string, options?: FetchOptions