mirror of
https://github.com/LukeHagar/plexjs.git
synced 2025-12-06 04:20:46 +00:00
383 lines
30 KiB
Markdown
383 lines
30 KiB
Markdown
# 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
|
|
|
|
<!-- UsageSnippet language="typescript" operationID="getButlerTasks" method="get" path="/butler" -->
|
|
```typescript
|
|
import { PlexAPI } from "@lukehagar/plexjs";
|
|
|
|
const plexAPI = new PlexAPI({
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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
|
|
|
|
<!-- UsageSnippet language="typescript" operationID="startAllTasks" method="post" path="/butler" -->
|
|
```typescript
|
|
import { PlexAPI } from "@lukehagar/plexjs";
|
|
|
|
const plexAPI = new PlexAPI({
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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
|
|
|
|
<!-- UsageSnippet language="typescript" operationID="stopAllTasks" method="delete" path="/butler" -->
|
|
```typescript
|
|
import { PlexAPI } from "@lukehagar/plexjs";
|
|
|
|
const plexAPI = new PlexAPI({
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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
|
|
|
|
<!-- UsageSnippet language="typescript" operationID="startTask" method="post" path="/butler/{taskName}" -->
|
|
```typescript
|
|
import { PlexAPI } from "@lukehagar/plexjs";
|
|
import { TaskName } from "@lukehagar/plexjs/sdk/models/operations";
|
|
|
|
const plexAPI = new PlexAPI({
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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
|
|
|
|
<!-- UsageSnippet language="typescript" operationID="stopTask" method="delete" path="/butler/{taskName}" -->
|
|
```typescript
|
|
import { PlexAPI } from "@lukehagar/plexjs";
|
|
import { PathParamTaskName } from "@lukehagar/plexjs/sdk/models/operations";
|
|
|
|
const plexAPI = new PlexAPI({
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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: "<YOUR_API_KEY_HERE>",
|
|
});
|
|
|
|
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 | \*/\* | |