@redseat/api 0.3.14 → 0.4.2

package/CLAUDE.md

@@ -1,2 +1,275 @@
-@AGENTS.md
-if you need to modify this file apply the instruction into agents.md instead
+# AI Agent Instructions
+
+This document provides guidelines for AI agents working with the `@redseat/api` package. Follow these instructions to maintain code quality and keep documentation up to date.
+
+## Getting Started
+
+### Always Read First
+
+1. **Start with [README.md](README.md)**
+   - Understand the package structure
+   - Identify which API classes are relevant to your task
+   - Find links to specialized documentation
+
+2. **Read Relevant Documentation**
+   - [client.md](client.md) - For HTTP client changes
+   - [server.md](server.md) - For server API changes
+   - [libraries.md](libraries.md) - For library API changes
+   - [encryption.md](encryption.md) - For encryption module changes
+   - [test.md](test.md) - For testing changes
+
+3. **Examine Source Code**
+   - Read the actual implementation files in `src/`
+   - Understand the current architecture
+   - Check existing patterns and conventions
+
+## Documentation Maintenance
+
+### When Modifying Existing Functionality
+
+**Required Actions:**
+
+1. **Update the Relevant Documentation File**
+   - If changing `RedseatClient`: Update [client.md](client.md)
+   - If changing `ServerApi`: Update [server.md](server.md)
+   - If changing `LibraryApi`: Update [libraries.md](libraries.md)
+   - If changing encryption: Update [encryption.md](encryption.md)
+
+2. **Update Method Signatures**
+   - Document new parameters
+   - Document changed return types
+   - Document new error cases
+   - Update examples if behavior changed
+
+3. **Update README.md if Needed**
+   - If API signatures changed significantly
+   - If new major features were added
+   - If package exports changed
+
+4. **Keep Examples Current**
+   - Update code examples to reflect new behavior
+   - Ensure examples are runnable
+   - Fix broken examples
+
+**Example Workflow:**
+```
+1. User requests: "Add timeout parameter to getMedia()"
+2. Read libraries.md to see current getMedia() documentation
+3. Modify src/library.ts to add timeout parameter
+4. Update libraries.md with new parameter documentation
+5. Update example code in libraries.md
+6. Check if README.md needs updates (probably not for this change)
+```
+
+### When Adding New Functionality
+
+**Required Actions:**
+
+1. **Document in Appropriate File**
+   - Add new methods to the relevant documentation file
+   - Follow existing formatting and structure
+   - Include parameters, return types, and examples
+
+2. **Update README.md**
+   - Add to package exports list if it's a new public export
+   - Update overview if it's a major feature
+   - Add to quick start if it's commonly used
+
+3. **Include Usage Examples**
+   - Provide at least one example per new method
+   - Show common use cases
+   - Include error handling examples
+
+4. **Update Related Documentation**
+   - If adding new encryption function: Update [encryption.md](encryption.md)
+   - If adding new test: Update [test.md](test.md)
+   - Cross-reference related functionality
+
+**Example Workflow:**
+```
+1. User requests: "Add getMediaStats() method to LibraryApi"
+2. Implement method in src/library.ts
+3. Add documentation to libraries.md in "Media" section
+4. Add example showing usage
+5. Update README.md exports if needed
+6. Add test and update test.md if applicable
+```
+
+## Code Change Workflow
+
+### Before Making Changes
+
+1. **Understand the Request**
+   - What functionality is being added/modified?
+   - Which files are affected?
+   - Are there breaking changes?
+
+2. **Plan the Changes**
+   - Identify all files that need modification
+   - Identify all documentation that needs updates
+   - Consider backward compatibility
+
+3. **Check Dependencies**
+   - Will this change affect other parts of the codebase?
+   - Are there tests that need updating?
+   - Are there examples that need updating?
+
+### During Implementation
+
+1. **Follow Existing Patterns**
+   - Match code style and conventions
+   - Use similar error handling
+   - Follow naming conventions
+
+2. **Write Tests**
+   - Add tests for new functionality
+   - Update tests for modified functionality
+   - Ensure tests pass
+
+3. **Update Documentation As You Go**
+   - Don't wait until the end
+   - Update docs as you implement
+   - This helps catch documentation issues early
+
+### After Implementation
+
+1. **Verify Documentation**
+   - Read through your documentation changes
+   - Ensure examples are correct
+   - Check for typos and formatting
+
+2. **Check Cross-References**
+   - Update links if files moved
+   - Update related documentation
+   - Ensure consistency across files
+
+3. **Test Examples**
+   - Verify code examples are syntactically correct
+   - Ensure examples demonstrate the feature correctly
+   - Check that examples use current API
+
+## Documentation Standards
+
+### Formatting
+
+- Use consistent markdown formatting
+- Use code blocks with language tags for code examples
+- Use proper heading hierarchy (## for sections, ### for subsections)
+- Include parameter tables for complex methods
+
+### Code Examples
+
+- Always include TypeScript type annotations
+- Show both success and error cases when relevant
+- Include imports when showing complete examples
+- Use realistic variable names
+
+### Method Documentation Template
+
+```markdown
+### `methodName(param1: Type1, param2: Type2): Promise<ReturnType>`
+
+Brief description of what the method does.
+
+**Parameters:**
+- `param1`: Description of parameter
+- `param2`: Description of parameter
+
+**Returns:** Promise resolving to description
+
+**Example:**
+\`\`\`typescript
+const result = await libraryApi.methodName('value1', 'value2');
+\`\`\`
+```
+
+## Common Scenarios
+
+### Scenario 1: Adding a New Method to LibraryApi
+
+1. Implement method in `src/library.ts`
+2. Add documentation to [libraries.md](libraries.md) in appropriate section
+3. Add example code
+4. Add test to appropriate test file
+5. Update [test.md](test.md) if new test file created
+6. Check if [README.md](README.md) needs updates
+
+### Scenario 2: Modifying Encryption Function
+
+1. Modify function in `src/encryption.ts`
+2. Update [encryption.md](encryption.md) with changes
+3. Update examples if behavior changed
+4. Update tests in `src/encryption.test.ts`
+5. Check if [libraries.md](libraries.md) needs updates (if LibraryApi uses it)
+
+### Scenario 3: Adding New Export
+
+1. Add export to `src/index.ts`
+2. Update [README.md](README.md) package exports section
+3. Add documentation to appropriate file
+4. Add example in README or relevant doc file
+
+### Scenario 4: Breaking Change
+
+1. Document breaking change clearly
+2. Update all affected documentation
+3. Update examples to show new usage
+4. Consider migration guide if significant
+
+## Quality Checklist
+
+Before completing a task, verify:
+
+- [ ] All code changes are implemented
+- [ ] All relevant documentation is updated
+- [ ] Examples are current and correct
+- [ ] Tests are added/updated
+- [ ] README.md is updated if needed
+- [ ] Cross-references are correct
+- [ ] No broken links
+- [ ] Code follows existing patterns
+- [ ] Documentation is clear and complete
+
+## Error Prevention
+
+### Common Mistakes to Avoid
+
+1. **Forgetting to Update Documentation**
+   - Always update docs when code changes
+   - Don't assume someone else will do it
+
+2. **Outdated Examples**
+   - Verify examples still work
+   - Update examples when API changes
+
+3. **Inconsistent Formatting**
+   - Follow existing documentation style
+   - Use consistent code formatting
+
+4. **Missing Error Cases**
+   - Document when methods throw errors
+   - Show error handling in examples
+
+5. **Incomplete Documentation**
+   - Document all parameters
+   - Document return types
+   - Include usage examples
+
+## Questions?
+
+If you're unsure about:
+- Which documentation file to update
+- How to format documentation
+- Whether a change needs documentation
+
+**Default Action:** Update the documentation. It's better to have slightly redundant documentation than missing documentation.
+
+## Related Documentation
+
+- [README.md](README.md) - Start here for package overview
+- [client.md](client.md) - RedseatClient documentation
+- [server.md](server.md) - ServerApi documentation
+- [libraries.md](libraries.md) - LibraryApi documentation
+- [encryption.md](encryption.md) - Encryption module documentation
+- [test.md](test.md) - Testing guide
+

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import { Method, AxiosRequestConfig } from 'axios';
 import { Observable } from 'rxjs';
 import { IToken } from './auth.js';
 import { IServer } from './interfaces.js';
-import { SSEConnectionState, SSEConnectionOptions, SSEConnectionError, SSELibraryEvent, SSELibraryStatusEvent, SSEMediasEvent, SSEUploadProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSEBackupsEvent, SSEBackupFilesEvent, SSEMediaRatingEvent, SSEMediaProgressEvent, SSEPlayersListEvent, SSEWatchedEvent, SSEUnwatchedEvent, SSERequestProcessingEvent } from './sse-types.js';
+import { SSEConnectionState, SSEConnectionOptions, SSEConnectionError, SSELibraryEvent, SSELibraryStatusEvent, SSEMediasEvent, SSEUploadProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEBooksEvent, SSEPeopleEvent, SSETagsEvent, SSEBackupsEvent, SSEBackupFilesEvent, SSEMediaRatingEvent, SSEMediaProgressEvent, SSEPlayersListEvent, SSEWatchedEvent, SSEUnwatchedEvent, SSERequestProcessingEvent } from './sse-types.js';
 export interface ClientOptions {
     server: IServer;
     getIdToken: (forceRefresh?: boolean) => Promise<string>;
@@ -47,6 +47,7 @@ export declare class RedseatClient {
     readonly episodes$: Observable<SSEEpisodesEvent>;
     readonly series$: Observable<SSESeriesEvent>;
     readonly movies$: Observable<SSEMoviesEvent>;
+    readonly books$: Observable<SSEBooksEvent>;
     readonly people$: Observable<SSEPeopleEvent>;
     readonly tags$: Observable<SSETagsEvent>;
     readonly backups$: Observable<SSEBackupsEvent>;

package/dist/client.js

@@ -20,6 +20,7 @@ export class RedseatClient {
             'episodes': 'episodes',
             'series': 'series',
             'movies': 'movies',
+            'books': 'books',
             'people': 'people',
             'tags': 'tags',
             'request_processing': 'requestProcessing',
@@ -60,6 +61,7 @@ export class RedseatClient {
         this.episodes$ = this.createEventStream('episodes');
         this.series$ = this.createEventStream('series');
         this.movies$ = this.createEventStream('movies');
+        this.books$ = this.createEventStream('books');
         this.people$ = this.createEventStream('people');
         this.tags$ = this.createEventStream('tags');
         this.backups$ = this.createEventStream('backups');

package/dist/interfaces.d.ts

@@ -96,9 +96,6 @@ export interface IFile {
     pages?: number;
     progress?: number;
     lang?: string;
-    tags?: MediaItemReference[];
-    series?: SerieInMedia[];
-    people?: MediaItemReference[];
     faces?: FaceEmbedding[];
     backups?: BackupFile[];
     thumb?: string;
@@ -106,16 +103,73 @@ export interface IFile {
     thumbsize?: number;
     iv?: string;
     origin?: RsLink;
-    movie?: string;
     uploader?: string;
     uploadkey?: string;
     faceRecognitionError?: string;
+    relations?: Relations;
+}
+export interface MediaForUpdate {
+    name?: string;
+    description?: string;
+    mimetype?: string;
+    kind?: FileTypes;
+    size?: number;
+    md5?: string;
+    modified?: number;
+    created?: number;
+    width?: number;
+    height?: number;
+    orientation?: number;
+    colorSpace?: string;
+    icc?: string;
+    mp?: number;
+    vcodecs?: string[];
+    acodecs?: string[];
+    fps?: number;
+    bitrate?: number;
+    focal?: number;
+    iso?: number;
+    model?: string;
+    sspeed?: string;
+    fNumber?: number;
+    pages?: number;
+    duration?: number;
+    progress?: number;
+    addTags?: MediaItemReference[];
+    removeTags?: string[];
+    tagsLookup?: string[];
+    addSeries?: SerieInMedia[];
+    removeSeries?: SerieInMedia[];
+    seriesLookup?: string[];
+    season?: number;
+    episode?: number;
+    addPeople?: MediaItemReference[];
+    removePeople?: string[];
+    peopleLookup?: string[];
+    long?: number;
+    lat?: number;
+    gps?: string;
+    origin?: RsLink;
+    originUrl?: string;
+    ignoreOriginDuplicate?: boolean;
+    movie?: string;
+    book?: string;
+    lang?: string;
+    rating?: number;
+    thumbsize?: number;
+    iv?: string;
+    uploader?: string;
+    uploadkey?: string;
+    uploadId?: string;
+    originalHash?: string;
+    originalId?: string;
 }
 export declare enum LibraryTypes {
     'Photos' = "photos",
     'Shows' = "shows",
     'Movies' = "movies",
-    'IPTV' = "iptv"
+    'IPTV' = "iptv",
+    'Books' = "books"
 }
 export declare enum LibrarySources {
     'Path' = "PathProvider",
@@ -131,7 +185,8 @@ export declare enum LibraryRole {
     admin = "admin"
 }
 export interface UserMapping {
-    [key: string]: unknown;
+    from: string;
+    to: string;
 }
 export interface ServerLibrarySettings {
     faceThreshold?: number;
@@ -140,14 +195,25 @@ export interface ServerLibrarySettings {
     mapProgress?: UserMapping[];
     dataPath?: string;
 }
+export interface ServerLibraryForUpdate {
+    name?: string;
+    source?: LibrarySources;
+    root?: string;
+    settings?: ServerLibrarySettings;
+    credentials?: string;
+    plugin?: string;
+}
 export interface ILibrary {
     id?: string;
     name: string;
     type: LibraryTypes;
     source?: LibrarySources;
+    root?: string;
     roles?: LibraryRole[];
     crypt?: boolean;
     settings: ServerLibrarySettings;
+    credentials?: string;
+    plugin?: string;
     hidden?: boolean;
     status?: string;
 }
@@ -163,6 +229,7 @@ export interface ITag {
     alt?: string[];
     thumb?: string;
     params?: any;
+    otherids?: string[];
 }
 export declare enum LinkType {
     'profile' = "profile",
@@ -197,6 +264,7 @@ export interface IPerson {
     tmdb?: number;
     trakt?: number;
     socials?: RsLink[];
+    otherids?: string[];
     gender?: Gender;
     country?: string;
     bio?: string;
@@ -218,7 +286,7 @@ export interface ISerie {
     tmdb?: number;
     trakt?: number;
     tvdb?: number;
-    otherids?: string;
+    otherids?: string[];
     imdbRating?: number;
     imdbVotes?: number;
     traktRating?: number;
@@ -298,6 +366,32 @@ export interface IMovie {
     backgroundv: number;
     cardv: number;
 }
+export interface IBook {
+    id: string;
+    name: string;
+    kind?: string;
+    serieRef?: string;
+    volume?: number;
+    chapter?: number;
+    year?: number;
+    airdate?: number;
+    overview?: string;
+    pages?: number;
+    params?: any;
+    lang?: string;
+    original?: string;
+    isbn13?: string;
+    openlibraryEditionId?: string;
+    openlibraryWorkId?: string;
+    googleBooksVolumeId?: string;
+    asin?: string;
+    modified: number;
+    added: number;
+    posterv?: number;
+    backgroundv?: number;
+    cardv?: number;
+}
+export type BookSort = 'modified' | 'added' | 'name' | 'year';
 export interface IServer {
     id: string;
     name?: string;
@@ -349,8 +443,58 @@ export interface IBackupFile {
     error?: string;
 }
 export interface ExternalImage {
-    url: string;
-    type: string;
+    type?: string;
+    url: RsRequest;
+    aspectRatio?: number;
+    height?: number;
+    lang?: string;
+    voteAverage?: number;
+    voteCount?: number;
+    width?: number;
+}
+export interface Relations {
+    peopleDetails?: IPerson[];
+    tagsDetails?: ITag[];
+    people?: MediaItemReference[];
+    tags?: MediaItemReference[];
+    series?: SerieInMedia[];
+    seriesDetails?: ISerie[];
+    movies?: string[];
+    moviesDetails?: IMovie[];
+    books?: string[];
+    booksDetails?: IBook[];
+    extImages?: ExternalImage[];
+}
+export type ItemWithRelations<T> = T & {
+    relations?: Relations;
+};
+export interface SearchRelations {
+    peopleDetails?: IPerson[];
+    tagsDetails?: ITag[];
+    people?: MediaItemReference[];
+    tags?: MediaItemReference[];
+    extImages?: ExternalImage[];
+}
+export interface SearchStreamResultBase {
+    relations?: SearchRelations;
+    images?: ExternalImage[];
+}
+export type SearchStreamResult<K extends string, T> = SearchStreamResultBase & {
+    metadata?: Partial<Record<K, T>>;
+};
+export type SearchResult<K extends string, T> = SearchStreamResult<K, T>;
+export type BookSearchResult = SearchResult<'book', IBook>;
+export type MovieSearchResult = SearchResult<'movie', IMovie>;
+export type SerieSearchResult = SearchResult<'serie', ISerie>;
+export type BookSearchStreamResult = SearchStreamResult<'book', IBook>;
+export type MovieSearchStreamResult = SearchStreamResult<'movie', IMovie>;
+export type SerieSearchStreamResult = SearchStreamResult<'serie', ISerie>;
+export type LookupSearchStreamResult = SearchStreamResult<'book' | 'movie' | 'serie', IBook | IMovie | ISerie>;
+export type GroupedSearchStreamPayload<T> = Record<string, T[]>;
+export interface SearchStreamCallbacks<T> {
+    onResults?: (results: GroupedSearchStreamPayload<T>) => void;
+    onFinished?: () => void;
+    onError?: (error: unknown) => void;
 }
 export interface IChannel {
     id: string;
@@ -759,6 +903,8 @@ export interface RsRequest {
     albums?: string[];
     season?: number;
     episode?: number;
+    movie?: string;
+    book?: SerieInMedia;
     language?: string;
     resolution?: string;
     videoFormat?: string;
@@ -780,6 +926,7 @@ export interface RsGroupDownload {
     groupFilename?: string;
     groupMime?: string;
     requests: RsRequest[];
+    infos?: MediaForUpdate;
 }
 /**
  * Request processing status from plugin-based download/processing.

package/dist/interfaces.js

@@ -14,6 +14,7 @@ export var LibraryTypes;
     LibraryTypes["Shows"] = "shows";
     LibraryTypes["Movies"] = "movies";
     LibraryTypes["IPTV"] = "iptv";
+    LibraryTypes["Books"] = "books";
 })(LibraryTypes || (LibraryTypes = {}));
 export var LibrarySources;
 (function (LibrarySources) {