Skip to content

Latest commit

 

History

History
398 lines (274 loc) · 29.1 KB

README.md

File metadata and controls

398 lines (274 loc) · 29.1 KB

Butler

(butler)

Overview

Butler is the task manager of the Plex Media Server Ecosystem.

Available Operations

getButlerTasks

Returns a list of butler tasks

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.butler.getButlerTasks();

  // Handle the result
  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

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) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result);
}

run();

Parameters

Parameter Type Required Description
options RequestOptions ➖ Used to set various options for making HTTP requests.
options.fetchOptions RequestInit ➖ 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 ➖ Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.GetButlerTasksResponse>

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

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.butler.startAllTasks();

  // Handle the result
  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

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) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result);
}

run();

Parameters

Parameter Type Required Description
options RequestOptions ➖ Used to set various options for making HTTP requests.
options.fetchOptions RequestInit ➖ 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 ➖ Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.StartAllTasksResponse>

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

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.butler.stopAllTasks();

  // Handle the result
  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

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) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result);
}

run();

Parameters

Parameter Type Required Description
options RequestOptions ➖ Used to set various options for making HTTP requests.
options.fetchOptions RequestInit ➖ 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 ➖ Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.StopAllTasksResponse>

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

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.CleanOldBundles);

  // Handle the result
  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

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.CleanOldBundles);

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result);
}

run();

Parameters

Parameter Type Required Description
taskName operations.TaskName ✔️ the name of the task to be started.
options RequestOptions ➖ Used to set various options for making HTTP requests.
options.fetchOptions RequestInit ➖ 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 ➖ Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.StartTaskResponse>

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

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.BackupDatabase);

  // Handle the result
  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

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.BackupDatabase);

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result);
}

run();

Parameters

Parameter Type Required Description
taskName operations.PathParamTaskName ✔️ The name of the task to be started.
options RequestOptions ➖ Used to set various options for making HTTP requests.
options.fetchOptions RequestInit ➖ 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 ➖ Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.StopTaskResponse>

Errors

Error Type Status Code Content Type
errors.StopTaskBadRequest 400 application/json
errors.StopTaskUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*