# Butler (*butler*) ## Overview Butler is the task manager of the Plex Media Server Ecosystem. ### Available Operations * [getButlerTasks](#getbutlertasks) - Get Butler tasks * [startAllTasks](#startalltasks) - Start all Butler tasks * [stopAllTasks](#stopalltasks) - Stop all Butler tasks * [startTask](#starttask) - Start a single Butler task * [stopTask](#stoptask) - Stop a single Butler task ## getButlerTasks Returns a list of butler tasks ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", }); async function run() { const result = await plexAPI.butler.getButlerTasks(); console.log(result); } run(); ``` ### Standalone function The standalone function version of this method: ```typescript import { PlexAPICore } from "@lukehagar/plexjs/core.js"; import { butlerGetButlerTasks } from "@lukehagar/plexjs/funcs/butlerGetButlerTasks.js"; // Use `PlexAPICore` for best tree-shaking performance. // You can create one instance of it to use across an application. const plexAPI = new PlexAPICore({ accessToken: "", }); async function run() { const res = await butlerGetButlerTasks(plexAPI); if (res.ok) { const { value: result } = res; console.log(result); } else { console.log("butlerGetButlerTasks failed:", res.error); } } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. | | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. | ### Response **Promise\<[operations.GetButlerTasksResponse](../../sdk/models/operations/getbutlertasksresponse.md)\>** ### Errors | Error Type | Status Code | Content Type | | --------------------------------- | --------------------------------- | --------------------------------- | | errors.GetButlerTasksBadRequest | 400 | application/json | | errors.GetButlerTasksUnauthorized | 401 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* | ## startAllTasks This endpoint will attempt to start all Butler tasks that are enabled in the settings. Butler tasks normally run automatically during a time window configured on the server's Settings page but can be manually started using this endpoint. Tasks will run with the following criteria: 1. Any tasks not scheduled to run on the current day will be skipped. 2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately. 3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window. 4. If we are outside the configured window, the task will start immediately. ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", }); async function run() { const result = await plexAPI.butler.startAllTasks(); console.log(result); } run(); ``` ### Standalone function The standalone function version of this method: ```typescript import { PlexAPICore } from "@lukehagar/plexjs/core.js"; import { butlerStartAllTasks } from "@lukehagar/plexjs/funcs/butlerStartAllTasks.js"; // Use `PlexAPICore` for best tree-shaking performance. // You can create one instance of it to use across an application. const plexAPI = new PlexAPICore({ accessToken: "", }); async function run() { const res = await butlerStartAllTasks(plexAPI); if (res.ok) { const { value: result } = res; console.log(result); } else { console.log("butlerStartAllTasks failed:", res.error); } } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. | | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. | ### Response **Promise\<[operations.StartAllTasksResponse](../../sdk/models/operations/startalltasksresponse.md)\>** ### Errors | Error Type | Status Code | Content Type | | -------------------------------- | -------------------------------- | -------------------------------- | | errors.StartAllTasksBadRequest | 400 | application/json | | errors.StartAllTasksUnauthorized | 401 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* | ## stopAllTasks This endpoint will stop all currently running tasks and remove any scheduled tasks from the queue. ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", }); async function run() { const result = await plexAPI.butler.stopAllTasks(); console.log(result); } run(); ``` ### Standalone function The standalone function version of this method: ```typescript import { PlexAPICore } from "@lukehagar/plexjs/core.js"; import { butlerStopAllTasks } from "@lukehagar/plexjs/funcs/butlerStopAllTasks.js"; // Use `PlexAPICore` for best tree-shaking performance. // You can create one instance of it to use across an application. const plexAPI = new PlexAPICore({ accessToken: "", }); async function run() { const res = await butlerStopAllTasks(plexAPI); if (res.ok) { const { value: result } = res; console.log(result); } else { console.log("butlerStopAllTasks failed:", res.error); } } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. | | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. | ### Response **Promise\<[operations.StopAllTasksResponse](../../sdk/models/operations/stopalltasksresponse.md)\>** ### Errors | Error Type | Status Code | Content Type | | ------------------------------- | ------------------------------- | ------------------------------- | | errors.StopAllTasksBadRequest | 400 | application/json | | errors.StopAllTasksUnauthorized | 401 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* | ## startTask This endpoint will attempt to start a single Butler task that is enabled in the settings. Butler tasks normally run automatically during a time window configured on the server's Settings page but can be manually started using this endpoint. Tasks will run with the following criteria: 1. Any tasks not scheduled to run on the current day will be skipped. 2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately. 3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window. 4. If we are outside the configured window, the task will start immediately. ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; import { TaskName } from "@lukehagar/plexjs/sdk/models/operations"; const plexAPI = new PlexAPI({ accessToken: "", }); async function run() { const result = await plexAPI.butler.startTask(TaskName.RefreshPeriodicMetadata); console.log(result); } run(); ``` ### Standalone function The standalone function version of this method: ```typescript import { PlexAPICore } from "@lukehagar/plexjs/core.js"; import { butlerStartTask } from "@lukehagar/plexjs/funcs/butlerStartTask.js"; import { TaskName } from "@lukehagar/plexjs/sdk/models/operations"; // Use `PlexAPICore` for best tree-shaking performance. // You can create one instance of it to use across an application. const plexAPI = new PlexAPICore({ accessToken: "", }); async function run() { const res = await butlerStartTask(plexAPI, TaskName.RefreshPeriodicMetadata); if (res.ok) { const { value: result } = res; console.log(result); } else { console.log("butlerStartTask failed:", res.error); } } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `taskName` | [operations.TaskName](../../sdk/models/operations/taskname.md) | :heavy_check_mark: | the name of the task to be started. | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. | | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. | ### Response **Promise\<[operations.StartTaskResponse](../../sdk/models/operations/starttaskresponse.md)\>** ### Errors | Error Type | Status Code | Content Type | | ---------------------------- | ---------------------------- | ---------------------------- | | errors.StartTaskBadRequest | 400 | application/json | | errors.StartTaskUnauthorized | 401 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* | ## stopTask This endpoint will stop a currently running task by name, or remove it from the list of scheduled tasks if it exists. See the section above for a list of task names for this endpoint. ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; import { PathParamTaskName } from "@lukehagar/plexjs/sdk/models/operations"; const plexAPI = new PlexAPI({ accessToken: "", }); async function run() { const result = await plexAPI.butler.stopTask(PathParamTaskName.CleanOldCacheFiles); console.log(result); } run(); ``` ### Standalone function The standalone function version of this method: ```typescript import { PlexAPICore } from "@lukehagar/plexjs/core.js"; import { butlerStopTask } from "@lukehagar/plexjs/funcs/butlerStopTask.js"; import { PathParamTaskName } from "@lukehagar/plexjs/sdk/models/operations"; // Use `PlexAPICore` for best tree-shaking performance. // You can create one instance of it to use across an application. const plexAPI = new PlexAPICore({ accessToken: "", }); async function run() { const res = await butlerStopTask(plexAPI, PathParamTaskName.CleanOldCacheFiles); if (res.ok) { const { value: result } = res; console.log(result); } else { console.log("butlerStopTask failed:", res.error); } } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `taskName` | [operations.PathParamTaskName](../../sdk/models/operations/pathparamtaskname.md) | :heavy_check_mark: | The name of the task to be started. | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. | | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. | ### Response **Promise\<[operations.StopTaskResponse](../../sdk/models/operations/stoptaskresponse.md)\>** ### Errors | Error Type | Status Code | Content Type | | --------------------------- | --------------------------- | --------------------------- | | errors.StopTaskBadRequest | 400 | application/json | | errors.StopTaskUnauthorized | 401 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* |