LukeParke/plexjs
1
0
Fork 0
mirror of https://github.com/LukeHagar/plexjs.git synced 2025-12-06 04:20:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
e9cfd11a9c1717251be84da48a8f55c6e6450dd8
plexjs/docs/sdks/library/README.md

594 lines
56 KiB
Markdown
Raw Blame History

# Library
(*library*)
## Overview
API Calls interacting with Plex Media Server Libraries
### Available Operations
* [getFileHash](#getfilehash) - Get Hash Value
* [getRecentlyAdded](#getrecentlyadded) - Get Recently Added
* [getLibraries](#getlibraries) - Get All Libraries
* [getLibrary](#getlibrary) - Get Library Details
* [deleteLibrary](#deletelibrary) - Delete Library Section
* [getLibraryItems](#getlibraryitems) - Get Library Items
* [refreshLibrary](#refreshlibrary) - Refresh Library
* [searchLibrary](#searchlibrary) - Search Library
* [getMetadata](#getmetadata) - Get Items Metadata
* [getMetadataChildren](#getmetadatachildren) - Get Items Children
* [getOnDeck](#getondeck) - Get On Deck
## getFileHash
This resource returns hash values for local files
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const url = "file://C:\Image.png&type=13";
const type = 4462.17;
const result = await sdk.library.getFileHash(url, type);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url` | *string* | :heavy_check_mark: | This is the path to the local file, must be prefixed by `file://` | [object Object] |
| `type` | *number* | :heavy_minus_sign: | Item type | |
| `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. | |
### Response
**Promise<[operations.GetFileHashResponse](../../models/operations/getfilehashresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| ------------------------------ | ------------------------------ | ------------------------------ |
| errors.GetFileHashResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getRecentlyAdded
This endpoint will return the recently added content.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const result = await sdk.library.getRecentlyAdded();
// 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. |
### Response
**Promise<[operations.GetRecentlyAddedResponse](../../models/operations/getrecentlyaddedresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| ----------------------------------- | ----------------------------------- | ----------------------------------- |
| errors.GetRecentlyAddedResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getLibraries
A library section (commonly referred to as just a library) is a collection of media.
Libraries are typed, and depending on their type provide either a flat or a hierarchical view of the media.
For example, a music library has an artist > albums > tracks structure, whereas a movie library is flat.
Libraries have features beyond just being a collection of media; for starters, they include information about supported types, filters and sorts.
This allows a client to provide a rich interface around the media (e.g. allow sorting movies by release year).
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const result = await sdk.library.getLibraries();
// 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. |
### Response
**Promise<[operations.GetLibrariesResponse](../../models/operations/getlibrariesresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| ------------------------------- | ------------------------------- | ------------------------------- |
| errors.GetLibrariesResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getLibrary
## Library Details Endpoint
This endpoint provides comprehensive details about the library, focusing on organizational aspects rather than the content itself.
The details include:
### Directories
Organized into three categories:
- **Primary Directories**:
- Used in some clients for quick access to media subsets (e.g., "All", "On Deck").
- Most can be replicated via media queries.
- Customizable by users.
- **Secondary Directories**:
- Marked with `secondary="1"`.
- Used in older clients for structured navigation.
- **Special Directories**:
- Includes a "By Folder" entry for filesystem-based browsing.
- Contains an obsolete `search="1"` entry for on-the-fly search dialog creation.
### Types
Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:
- **Type Object Attributes**:
- `key`: Endpoint for the media list of this type.
- `type`: Metadata type (if standard Plex type).
- `title`: Title for this content type (e.g., "Movies").
- **Filter Objects**:
- Subset of the media query language.
- Attributes include `filter` (name), `filterType` (data type), `key` (endpoint for value range), and `title`.
- **Sort Objects**:
- Description of sort fields.
- Attributes include `defaultDirection` (asc/desc), `descKey` and `key` (sort parameters), and `title`.
> **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
import { IncludeDetails } from "@lukehagar/plexjs/models/operations";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const sectionId = 1000;
const includeDetails = IncludeDetails.Zero;
const result = await sdk.library.getLibrary(sectionId, includeDetails);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sectionId` | *number* | :heavy_check_mark: | the Id of the library to query | [object Object] |
| `includeDetails` | [operations.IncludeDetails](../../models/operations/includedetails.md) | :heavy_minus_sign: | Whether or not to include details for a section (types, filters, and sorts). <br/>Only exists for backwards compatibility, media providers other than the server libraries have it on always.<br/> | |
| `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. | |
### Response
**Promise<[operations.GetLibraryResponse](../../models/operations/getlibraryresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| ----------------------------- | ----------------------------- | ----------------------------- |
| errors.GetLibraryResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## deleteLibrary
Delate a library using a specific section
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const sectionId = 1000;
const result = await sdk.library.deleteLibrary(sectionId);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sectionId` | *number* | :heavy_check_mark: | the Id of the library to query | [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. | |
### Response
**Promise<[operations.DeleteLibraryResponse](../../models/operations/deletelibraryresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| -------------------------------- | -------------------------------- | -------------------------------- |
| errors.DeleteLibraryResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getLibraryItems
Fetches details from a specific section of the library identified by a section key and a tag. The tag parameter accepts the following values:
- `all`: All items in the section.
- `unwatched`: Items that have not been played.
- `newest`: Items that are recently released.
- `recentlyAdded`: Items that are recently added to the library.
- `recentlyViewed`: Items that were recently viewed.
- `onDeck`: Items to continue watching.
- `collection`: Items categorized by collection.
- `edition`: Items categorized by edition.
- `genre`: Items categorized by genre.
- `year`: Items categorized by year of release.
- `decade`: Items categorized by decade.
- `director`: Items categorized by director.
- `actor`: Items categorized by starring actor.
- `country`: Items categorized by country of origin.
- `contentRating`: Items categorized by content rating.
- `rating`: Items categorized by rating.
- `resolution`: Items categorized by resolution.
- `firstCharacter`: Items categorized by the first letter.
- `folder`: Items categorized by folder.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
import { Tag } from "@lukehagar/plexjs/models/operations";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const sectionId = 451092;
const tag = Tag.Unwatched;
const result = await sdk.library.getLibraryItems(sectionId, tag);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sectionId` | *number* | :heavy_check_mark: | the Id of the library to query |
| `tag` | [operations.Tag](../../models/operations/tag.md) | :heavy_check_mark: | A key representing a specific tag within the section. |
| `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. |
### Response
**Promise<[operations.GetLibraryItemsResponse](../../models/operations/getlibraryitemsresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| --------------- | --------------- | --------------- |
| errors.SDKError | 4xx-5xx | */* |
## refreshLibrary
This endpoint Refreshes the library.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const sectionId = 934.16;
const result = await sdk.library.refreshLibrary(sectionId);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sectionId` | *number* | :heavy_check_mark: | the Id of the library to refresh |
| `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. |
### Response
**Promise<[operations.RefreshLibraryResponse](../../models/operations/refreshlibraryresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| --------------------------------- | --------------------------------- | --------------------------------- |
| errors.RefreshLibraryResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## searchLibrary
Search for content within a specific section of the library.
### Types
Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:
- **Type Object Attributes**:
- `type`: Metadata type (if standard Plex type).
- `title`: Title for this content type (e.g., "Movies").
- **Filter Objects**:
- Subset of the media query language.
- Attributes include `filter` (name), `filterType` (data type), `key` (endpoint for value range), and `title`.
- **Sort Objects**:
- Description of sort fields.
- Attributes include `defaultDirection` (asc/desc), `descKey` and `key` (sort parameters), and `title`.
> **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
import { TypeT } from "@lukehagar/plexjs/models/operations";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const sectionId = 933505;
const type = TypeT.Four;
const result = await sdk.library.searchLibrary(sectionId, type);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sectionId` | *number* | :heavy_check_mark: | the Id of the library to query |
| `type` | [operations.TypeT](../../models/operations/typet.md) | :heavy_check_mark: | Plex content type to search for |
| `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. |
### Response
**Promise<[operations.SearchLibraryResponse](../../models/operations/searchlibraryresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| --------------- | --------------- | --------------- |
| errors.SDKError | 4xx-5xx | */* |
## getMetadata
This endpoint will return the metadata of a library item specified with the ratingKey.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const ratingKey = 8382.31;
const result = await sdk.library.getMetadata(ratingKey);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ratingKey` | *number* | :heavy_check_mark: | the id of the library item to return the children of. |
| `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. |
### Response
**Promise<[operations.GetMetadataResponse](../../models/operations/getmetadataresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| ------------------------------ | ------------------------------ | ------------------------------ |
| errors.GetMetadataResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getMetadataChildren
This endpoint will return the children of of a library item specified with the ratingKey.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const ratingKey = 1539.14;
const result = await sdk.library.getMetadataChildren(ratingKey);
// Handle the result
console.log(result)
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ratingKey` | *number* | :heavy_check_mark: | the id of the library item to return the children of. |
| `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. |
### Response
**Promise<[operations.GetMetadataChildrenResponse](../../models/operations/getmetadatachildrenresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| -------------------------------------- | -------------------------------------- | -------------------------------------- |
| errors.GetMetadataChildrenResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
## getOnDeck
This endpoint will return the on deck content.
### Example Usage
```typescript
import { PlexAPI } from "@lukehagar/plexjs";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const result = await sdk.library.getOnDeck();
// 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. |
### Response
**Promise<[operations.GetOnDeckResponse](../../models/operations/getondeckresponse.md)>**
### Errors
| Error Object | Status Code | Content Type |
| ---------------------------- | ---------------------------- | ---------------------------- |
| errors.GetOnDeckResponseBody | 401 | application/json |
| errors.SDKError | 4xx-5xx | */* |
Reference in New Issue View Git Blame Copy Permalink