mirror of
https://github.com/jellyfin/jellyfin-sdk-typescript.git
synced 2024-10-07 03:13:35 +00:00
163 lines
6.4 KiB
Markdown
163 lines
6.4 KiB
Markdown
<h1 align="center">jellyfin-sdk-typescript</h1>
|
|
<h3 align="center">Part of the <a href="https://jellyfin.org">Jellyfin Project</a></h3>
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<img alt="Logo Banner" src="https://raw.githubusercontent.com/jellyfin/jellyfin-ux/master/branding/SVG/banner-logo-solid.svg?sanitize=true"/>
|
|
<br/>
|
|
<br/>
|
|
<a href="https://github.com/jellyfin/jellyfin-sdk-typescript/blob/master/LICENSE"><img alt="MPL-2.0 license" src="https://img.shields.io/github/license/jellyfin/jellyfin-sdk-typescript"></a>
|
|
<a href="https://github.com/jellyfin/jellyfin-sdk-typescript/releases"><img alt="Current Release" src="https://img.shields.io/github/release/jellyfin/jellyfin-sdk-typescript.svg"/></a>
|
|
<a href="https://www.npmjs.com/package/@jellyfin/sdk"><img alt="npm" src="https://img.shields.io/npm/v/@jellyfin/sdk"></a>
|
|
<a href="https://sonarcloud.io/component_measures?metric=coverage&id=jellyfin_jellyfin-sdk-typescript">
|
|
<img alt="Sonar Coverage" src="https://img.shields.io/sonar/coverage/jellyfin_jellyfin-sdk-typescript/master?server=https%3A%2F%2Fsonarcloud.io">
|
|
</a>
|
|
</p>
|
|
|
|
A TypeScript SDK for Jellyfin.
|
|
|
|
> Warning: This project is under active development, so API changes may occur.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
npm i --save @jellyfin/sdk
|
|
```
|
|
|
|
or
|
|
|
|
```sh
|
|
yarn add @jellyfin/sdk
|
|
```
|
|
|
|
### Supported Jellyfin Versions
|
|
|
|
| SDK Version | Jellyfin Version |
|
|
|:-:|:-:|
|
|
| 0.10.0 | 10.9.x |
|
|
| 0.9.0 | 10.9.x |
|
|
| 0.8.2 - 0.6.0 | 10.8.1 - 10.8.13 |
|
|
| 0.5.0 | 10.8.0 |
|
|
| <0.5.0 | 10.7.x |
|
|
|
|
> Note: Versions prior to 0.7.0 were published as `@thornbill/jellyfin-sdk`.
|
|
|
|
### React Native
|
|
|
|
The generated Axios client used in this library depends on `URL` and `URLSearchParams` to be available on the global scope.
|
|
React Native only includes incomplete implementations for these classes, so a polyfill is required.
|
|
[React Native URL Polyfill](https://github.com/charpeni/react-native-url-polyfill) seems like a good solution for this.
|
|
|
|
## Usage
|
|
|
|
```js
|
|
// Create a new instance of the SDK
|
|
const jellyfin = new Jellyfin({
|
|
clientInfo: {
|
|
name: 'My Client Application',
|
|
version: '1.0.0'
|
|
},
|
|
deviceInfo: {
|
|
name: 'Device Name',
|
|
id: 'unique-device-id'
|
|
}
|
|
});
|
|
|
|
// Find a valid server by trying to connect using common protocols and ports.
|
|
// Each server receives a score based on security, speed, and other criteria.
|
|
const servers = await jellyfin.discovery.getRecommendedServerCandidates('demo.jellyfin.org/stable');
|
|
// A utility function for finding the best result is available.
|
|
// If there is no "best" server, an error message should be displayed.
|
|
const best = jellyfin.discovery.findBestServer(servers);
|
|
|
|
// Create an API instance
|
|
const api = jellyfin.createApi(best.address);
|
|
|
|
// Each API endpoint is represented by a class in the generated client.
|
|
// Helper utility functions are provided under `/lib/utils/api/` to create an
|
|
// instance of a specific Jellyfin API using the shared Configuration and Axios
|
|
// instance from the `api` object created above.
|
|
|
|
// For example, the SystemApi can be generated using the `getSystemApi`
|
|
// function in `/lib/utils/api/system-api`.
|
|
|
|
// Fetch the public system info
|
|
const info = await getSystemApi(api).getPublicSystemInfo();
|
|
console.log('Info =>', info.data);
|
|
|
|
// Fetch the list of public users
|
|
const users = await getUserApi(api).getPublicUsers();
|
|
console.log('Users =>', users.data);
|
|
|
|
// A helper method for authentication has been added to the SDK because
|
|
// the default method exposed in the generated Axios client is rather
|
|
// cumbersome to use.
|
|
const auth = await api.authenticateUserByName('demo', '');
|
|
console.log('Auth =>', auth.data);
|
|
|
|
// Authentication state is stored internally in the Api class, so now
|
|
// requests that require authentication can be made normally
|
|
const libraries = await getLibraryApi(api).getMediaFolders();
|
|
console.log('Libraries =>', libraries.data);
|
|
|
|
// A helper method for logging out the current user has been added to the
|
|
// SDK so the internal state is updated correctly.
|
|
await api.logout();
|
|
```
|
|
|
|
## Breaking Changes
|
|
|
|
### v0.10.0
|
|
|
|
* Updated build target to ES2018. [#712](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/712)
|
|
|
|
### v0.9.0
|
|
|
|
* Updated OpenAPI spec for Jellyfin 10.9.1. [#694](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/694)
|
|
|
|
### v0.8.0
|
|
|
|
* The library is now fully targeted to ES6/ES2015.
|
|
[#341](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/341)
|
|
* Axios received a major version upgrade.
|
|
[#300](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/300)
|
|
|
|
### v0.7.0
|
|
|
|
* Renamed package to @jellyfin/sdk.
|
|
[#262](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/262)
|
|
|
|
### v0.6.0
|
|
|
|
* Updated OpenAPI spec for Jellyfin 10.8.1.
|
|
[#208](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/208)
|
|
|
|
### v0.5.0
|
|
|
|
* Build directory is now `lib` instead of `dist`.
|
|
Any imports used that were previously in `dist` will need updated.
|
|
[#147](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/147)
|
|
* Duplicated exports were removed.
|
|
Any imports may need updated if you referenced one of the duplicates.
|
|
[#148](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/148)
|
|
* API classes are no longer exposed via getters.
|
|
Instead you need to call a function passing the `Api` instance as a parameter.
|
|
For example: `getSystemApi(api)`.
|
|
While I do feel this is a slightly worse developer experience, it was a necessary change to support tree-shaking.
|
|
[#149](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/149)
|
|
* `BaseItemKind` is now included in the generated client.
|
|
Imports will need updated.
|
|
[#187](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/187)
|
|
|
|
## Roadmap to 1.0
|
|
|
|
* [x] Use custom generator templates for API versions [#231](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/231) (Currently uses sed to update the value could be improved.)
|
|
* [x] Automate OpenAPI spec updates using GitHub [#351](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/351)
|
|
* [x] Create branch tracking unstable Jellyfin builds with automated builds [#354](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/354)
|
|
* [x] Fix authentication header escaping [#564](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/564)
|
|
* [ ] Add WebSocket API support
|
|
* [ ] Add example projects for different ecosystems [#186](https://github.com/jellyfin/jellyfin-sdk-typescript/issues/186)
|
|
* [ ] Add utility function for `getFile` [#164](https://github.com/jellyfin/jellyfin-sdk-typescript/issues/164)
|
|
* [ ] More complete device profile generation utilities
|