Files
plexjs/docs/sdks/plex/README.md

566 lines
49 KiB
Markdown

# Plex
(*plex*)
## Overview
API Calls that perform operations directly against https://Plex.tv
### Available Operations
* [getCompanionsData](#getcompanionsdata) - Get Companions Data
* [getUserFriends](#getuserfriends) - Get list of friends of the user logged in
* [getGeoData](#getgeodata) - Get Geo Data
* [getHomeData](#gethomedata) - Get Plex Home Data
* [getServerResources](#getserverresources) - Get Server Resources
* [getPin](#getpin) - Get a Pin
* [getTokenByPinId](#gettokenbypinid) - Get Access Token by PinId
## getCompanionsData
Get Companions Data
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
const plexAPI = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getCompanionsData();
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetCompanionsData } from "@lukehagar/plexjs/funcs/plexGetCompanionsData.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>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetCompanionsData(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 | :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. |
| `options.serverURL` | *string* | :heavy_minus_sign: | An optional server URL to use. |
### Response
**Promise\<[operations.GetCompanionsDataResponse](../../sdk/models/operations/getcompanionsdataresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| ---------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| errors.GetCompanionsDataResponseBody | 400 | application/json |
| errors.GetCompanionsDataPlexResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getUserFriends
Get friends of provided auth token.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
const plexAPI = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getUserFriends();
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetUserFriends } from "@lukehagar/plexjs/funcs/plexGetUserFriends.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>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetUserFriends(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 | :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. |
| `options.serverURL` | *string* | :heavy_minus_sign: | An optional server URL to use. |
### Response
**Promise\<[operations.GetUserFriendsResponse](../../sdk/models/operations/getuserfriendsresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| ------------------------------------- | ------------------------------------- | ------------------------------------- |
| errors.GetUserFriendsResponseBody | 400 | application/json |
| errors.GetUserFriendsPlexResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getGeoData
Returns the geolocation and locale data of the caller
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
const plexAPI = new PlexAPI({
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getGeoData();
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetGeoData } from "@lukehagar/plexjs/funcs/plexGetGeoData.js";
// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetGeoData(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 | :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. |
| `options.serverURL` | *string* | :heavy_minus_sign: | An optional server URL to use. |
### Response
**Promise\<[operations.GetGeoDataResponse](../../sdk/models/operations/getgeodataresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| --------------------------------- | --------------------------------- | --------------------------------- |
| errors.GetGeoDataResponseBody | 400 | application/json |
| errors.GetGeoDataPlexResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getHomeData
Retrieves the home data for the authenticated user, including details like home ID, name, guest access information, and subscription status.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
const plexAPI = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getHomeData();
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetHomeData } from "@lukehagar/plexjs/funcs/plexGetHomeData.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>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetHomeData(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 | :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.GetHomeDataResponse](../../sdk/models/operations/gethomedataresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.GetHomeDataResponseBody | 400 | application/json |
| errors.GetHomeDataPlexResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getServerResources
Get Plex server access tokens and server connections
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
import { IncludeHttps, IncludeIPv6, IncludeRelay } from "@lukehagar/plexjs/sdk/models/operations";
const plexAPI = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getServerResources({
xPlexToken: "CV5xoxjTpFKUzBTShsaf",
includeHttps: IncludeHttps.One,
includeRelay: IncludeRelay.One,
includeIPv6: IncludeIPv6.One,
});
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetServerResources } from "@lukehagar/plexjs/funcs/plexGetServerResources.js";
import { IncludeHttps, IncludeIPv6, IncludeRelay } 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>",
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetServerResources(plexAPI, {
xPlexToken: "CV5xoxjTpFKUzBTShsaf",
includeHttps: IncludeHttps.One,
includeRelay: IncludeRelay.One,
includeIPv6: IncludeIPv6.One,
});
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.GetServerResourcesRequest](../../sdk/models/operations/getserverresourcesrequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `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. |
| `options.serverURL` | *string* | :heavy_minus_sign: | An optional server URL to use. |
### Response
**Promise\<[operations.GetServerResourcesResponse](../../sdk/models/operations/getserverresourcesresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| ----------------------------------------- | ----------------------------------------- | ----------------------------------------- |
| errors.GetServerResourcesResponseBody | 400 | application/json |
| errors.GetServerResourcesPlexResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getPin
Retrieve a Pin from Plex.tv for authentication flows
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
const plexAPI = new PlexAPI({
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getPin("gcgzw5rz2xovp84b4vha3a40", "Plex Web");
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetPin } from "@lukehagar/plexjs/funcs/plexGetPin.js";
// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetPin(plexAPI, "gcgzw5rz2xovp84b4vha3a40", "Plex Web");
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `strong` | *boolean* | :heavy_minus_sign: | Determines the kind of code returned by the API call<br/>Strong codes are used for Pin authentication flows<br/>Non-Strong codes are used for `Plex.tv/link`<br/> | |
| `xPlexClientIdentifier` | *string* | :heavy_minus_sign: | The unique identifier for the client application<br/>This is used to track the client application and its usage<br/>(UUID, serial number, or other number unique per device)<br/> | [object Object] |
| `xPlexProduct` | *string* | :heavy_minus_sign: | N/A | [object Object] |
| `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. | |
| `options.serverURL` | *string* | :heavy_minus_sign: | An optional server URL to use. | http://localhost:8080 |
### Response
**Promise\<[operations.GetPinResponse](../../sdk/models/operations/getpinresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| ------------------------- | ------------------------- | ------------------------- |
| errors.GetPinResponseBody | 400 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getTokenByPinId
Retrieve an Access Token from Plex.tv after the Pin has been authenticated
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
const plexAPI = new PlexAPI({
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const result = await plexAPI.plex.getTokenByPinId(408895, "gcgzw5rz2xovp84b4vha3a40");
// Handle the result
console.log(result)
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { plexGetTokenByPinId } from "@lukehagar/plexjs/funcs/plexGetTokenByPinId.js";
// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});
async function run() {
const res = await plexGetTokenByPinId(plexAPI, 408895, "gcgzw5rz2xovp84b4vha3a40");
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pinID` | *number* | :heavy_check_mark: | The PinID to retrieve an access token for | |
| `xPlexClientIdentifier` | *string* | :heavy_minus_sign: | The unique identifier for the client application<br/>This is used to track the client application and its usage<br/>(UUID, serial number, or other number unique per device)<br/> | [object Object] |
| `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. | |
| `options.serverURL` | *string* | :heavy_minus_sign: | An optional server URL to use. | http://localhost:8080 |
### Response
**Promise\<[operations.GetTokenByPinIdResponse](../../sdk/models/operations/gettokenbypinidresponse.md)\>**
### Errors
| Error Object | Status Code | Content Type |
| -------------------------------------- | -------------------------------------- | -------------------------------------- |
| errors.GetTokenByPinIdResponseBody | 400 | application/json |
| errors.GetTokenByPinIdPlexResponseBody | 404 | application/json |
| errors.SDKError | 4xx-5xx | */* |