@nuclearplayer/plugin-sdk 2.2.0 → 2.4.0

package/README.md

@@ -108,13 +108,19 @@ The `api` object passed to lifecycle hooks provides access to these domain APIs:
 |-----|-------------|
 | `api.Settings` | Define, read, and persist plugin settings |
 | `api.Queue` | Read and manipulate the playback queue |
+| `api.Playback` | Control audio transport: play, pause, stop, seek |
+| `api.Events` | Subscribe to player lifecycle events (e.g. track finished) |
 | `api.Favorites` | Manage the user's favorite tracks |
+| `api.Playlists` | Create, update, and delete playlists |
 | `api.Providers` | Register and unregister providers |
 | `api.Streaming` | Resolve audio stream URLs for tracks |
 | `api.Metadata` | Search and fetch artist/album/track details |
 | `api.Dashboard` | Fetch dashboard content (top tracks, new releases, etc.) |
+| `api.Http` | Make HTTP requests from plugins and bypass CORS |
+| `api.Logger` | Structured logging |
+| `api.Ytdlp` | yt-dlp integration |
 
-See the [full documentation](https://docs.nuclearplayer.com/nuclear-xrd) for detailed guides on each API.
+See the [full documentation](https://docs.nuclearplayer.com) for detailed guides on each API.
 
 ## Permissions
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { FC } from 'react';
 import { z } from 'zod';
 
 export declare type Album = {
@@ -96,6 +97,27 @@ export declare type BooleanWidget = {
     type: 'toggle';
 };
 
+export declare type CustomSettingDefinition = {
+    id: string;
+    title: string;
+    description?: string;
+    category: SettingCategory;
+    kind: 'custom';
+    widgetId: string;
+    default?: SettingValue;
+    hidden?: boolean;
+    source?: SettingSource;
+};
+
+export declare type CustomWidgetComponent<API = unknown> = FC<CustomWidgetProps<API>>;
+
+export declare type CustomWidgetProps<API = unknown> = {
+    value: SettingValue | undefined;
+    setValue: (value: SettingValue) => void;
+    definition: CustomSettingDefinition;
+    api: API;
+};
+
 export declare class DashboardAPI {
     #private;
     constructor(host?: DashboardHost);
@@ -150,6 +172,17 @@ export declare type EnumWidget = {
     type: 'radio';
 };
 
+export declare class EventsAPI {
+    #private;
+    constructor(host?: EventsHost);
+    on<E extends keyof PluginEventMap>(event: E, listener: PluginEventListener<E>): () => void;
+}
+
+export declare type EventsHost = {
+    on<E extends keyof PluginEventMap>(event: E, listener: PluginEventListener<E>): () => void;
+    emit<E extends keyof PluginEventMap>(event: E, payload: PluginEventMap[E]): void;
+};
+
 export declare type FavoriteEntry<T> = {
     ref: T;
     addedAtIso: string;
@@ -220,6 +253,95 @@ export declare type HttpResponseData = {
     body: string;
 };
 
+export declare type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
+    [key: string]: JsonSerializable;
+};
+
+export declare const legacyConfigSchema: z.ZodEffects<z.ZodObject<{
+    playlists: z.ZodArray<z.ZodUnknown, "many">;
+}, "strip", z.ZodTypeAny, {
+    playlists: unknown[];
+}, {
+    playlists: unknown[];
+}>, {
+    playlists: unknown[];
+}, {
+    playlists: unknown[];
+}>;
+
+export declare type LegacyPlaylist = z.infer<typeof legacyPlaylistSchema>;
+
+export declare const legacyPlaylistSchema: z.ZodObject<{
+    name: z.ZodString;
+    tracks: z.ZodArray<z.ZodObject<{
+        uuid: z.ZodOptional<z.ZodString>;
+        artist: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        album: z.ZodOptional<z.ZodString>;
+        thumbnail: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodNumber, z.ZodEffects<z.ZodString, number, string>]>, number, string | number>>;
+    }, "strip", z.ZodTypeAny, {
+        thumbnail?: string | undefined;
+        name?: string | undefined;
+        uuid?: string | undefined;
+        artist?: string | undefined;
+        album?: string | undefined;
+        duration?: number | undefined;
+    }, {
+        thumbnail?: string | undefined;
+        name?: string | undefined;
+        uuid?: string | undefined;
+        artist?: string | undefined;
+        album?: string | undefined;
+        duration?: string | number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    tracks: {
+        thumbnail?: string | undefined;
+        name?: string | undefined;
+        uuid?: string | undefined;
+        artist?: string | undefined;
+        album?: string | undefined;
+        duration?: number | undefined;
+    }[];
+}, {
+    name: string;
+    tracks: {
+        thumbnail?: string | undefined;
+        name?: string | undefined;
+        uuid?: string | undefined;
+        artist?: string | undefined;
+        album?: string | undefined;
+        duration?: string | number | undefined;
+    }[];
+}>;
+
+export declare type LegacyTrack = z.infer<typeof legacyTrackSchema>;
+
+export declare const legacyTrackSchema: z.ZodObject<{
+    uuid: z.ZodOptional<z.ZodString>;
+    artist: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    album: z.ZodOptional<z.ZodString>;
+    thumbnail: z.ZodOptional<z.ZodString>;
+    duration: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodNumber, z.ZodEffects<z.ZodString, number, string>]>, number, string | number>>;
+}, "strip", z.ZodTypeAny, {
+    thumbnail?: string | undefined;
+    name?: string | undefined;
+    uuid?: string | undefined;
+    artist?: string | undefined;
+    album?: string | undefined;
+    duration?: number | undefined;
+}, {
+    thumbnail?: string | undefined;
+    name?: string | undefined;
+    uuid?: string | undefined;
+    artist?: string | undefined;
+    album?: string | undefined;
+    duration?: string | number | undefined;
+}>;
+
 export declare type LoadedPlugin = {
     metadata: PluginMetadata;
     instance: NuclearPlugin;
@@ -313,6 +435,8 @@ export declare class NuclearAPI {
     readonly Dashboard: DashboardAPI;
     readonly Playback: PlaybackAPI;
     readonly Playlists: PlaylistsAPI;
+    readonly Events: EventsAPI;
+    readonly Shell: ShellAPI;
     constructor(opts?: {
         settingsHost?: SettingsHost;
         providersHost?: ProvidersHost;
@@ -326,6 +450,10 @@ export declare class NuclearAPI {
         dashboardHost?: DashboardHost;
         playbackHost?: PlaybackHost;
         playlistsHost?: PlaylistsHost;
+        eventsHost?: EventsHost;
+        shellHost?: ShellHost;
+        widgetRegistry?: WidgetRegistry;
+        pluginId?: string;
     });
 }
 
@@ -929,6 +1057,7 @@ export declare const playlistExportSchema: z.ZodObject<{
 export declare type PlaylistIndexEntry = Pick<Playlist, 'id' | 'name' | 'createdAtIso' | 'lastModifiedIso' | 'isReadOnly' | 'artwork'> & {
     itemCount: number;
     totalDurationMs: number;
+    thumbnails: string[];
 };
 
 export declare const playlistIndexEntrySchema: z.ZodObject<{
@@ -1004,6 +1133,7 @@ export declare const playlistIndexEntrySchema: z.ZodObject<{
     }>>;
     itemCount: z.ZodNumber;
     totalDurationMs: z.ZodNumber;
+    thumbnails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     name: string;
@@ -1012,6 +1142,7 @@ export declare const playlistIndexEntrySchema: z.ZodObject<{
     isReadOnly: boolean;
     itemCount: number;
     totalDurationMs: number;
+    thumbnails: string[];
     artwork?: {
         items: {
             url: string;
@@ -1046,6 +1177,7 @@ export declare const playlistIndexEntrySchema: z.ZodObject<{
             } | undefined;
         }[];
     } | undefined;
+    thumbnails?: string[] | undefined;
 }>;
 
 export declare const playlistIndexSchema: z.ZodArray<z.ZodObject<{
@@ -1121,6 +1253,7 @@ export declare const playlistIndexSchema: z.ZodArray<z.ZodObject<{
     }>>;
     itemCount: z.ZodNumber;
     totalDurationMs: z.ZodNumber;
+    thumbnails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     name: string;
@@ -1129,6 +1262,7 @@ export declare const playlistIndexSchema: z.ZodArray<z.ZodObject<{
     isReadOnly: boolean;
     itemCount: number;
     totalDurationMs: number;
+    thumbnails: string[];
     artwork?: {
         items: {
             url: string;
@@ -1163,6 +1297,7 @@ export declare const playlistIndexSchema: z.ZodArray<z.ZodObject<{
             } | undefined;
         }[];
     } | undefined;
+    thumbnails?: string[] | undefined;
 }>, "many">;
 
 export declare type PlaylistItem<T extends Track = Track> = {
@@ -1172,6 +1307,11 @@ export declare type PlaylistItem<T extends Track = Track> = {
     addedAtIso: string;
 };
 
+export declare type PlaylistProvider = ProviderDescriptor<'playlists'> & {
+    matchesUrl: (url: string) => boolean;
+    fetchPlaylistByUrl: (url: string) => Promise<Playlist>;
+};
+
 export declare type PlaylistRef = {
     id: string;
     name: string;
@@ -1603,6 +1743,13 @@ export declare type PlaylistsHost = {
 
 export declare type PlaylistsListener = (index: PlaylistIndexEntry[]) => void;
 
+export declare type PluginEventListener<E extends keyof PluginEventMap> = (payload: PluginEventMap[E]) => void | Promise<void>;
+
+export declare type PluginEventMap = {
+    trackFinished: Track;
+    trackStarted: Track;
+};
+
 export declare type PluginIcon = {
     type: 'link';
     link: string;
@@ -1641,7 +1788,7 @@ export declare type ProviderDescriptor<K extends ProviderKind = ProviderKind> =
     pluginId?: string;
 };
 
-export declare type ProviderKind = 'metadata' | 'streaming' | 'lyrics' | 'dashboard' | (string & {});
+export declare type ProviderKind = 'metadata' | 'streaming' | 'lyrics' | 'dashboard' | 'playlists' | (string & {});
 
 export declare type ProviderRef = {
     provider: string;
@@ -1755,15 +1902,17 @@ export declare type SearchResults = {
 
 export declare type SettingCategory = string;
 
-export declare type SettingDefinition = BooleanSettingDefinition | NumberSettingDefinition | StringSettingDefinition | EnumSettingDefinition;
+export declare type SettingDefinition = BooleanSettingDefinition | NumberSettingDefinition | StringSettingDefinition | EnumSettingDefinition | CustomSettingDefinition;
 
 declare class Settings {
     #private;
-    constructor(host?: SettingsHost);
+    constructor(host?: SettingsHost, widgetRegistry?: WidgetRegistry, pluginId?: string);
     register(defs: SettingDefinition[]): Promise<SettingsRegistrationResult>;
     get<T extends SettingValue = SettingValue>(id: string): Promise<T | undefined>;
     set<T extends SettingValue = SettingValue>(id: string, value: T): Promise<void>;
     subscribe<T extends SettingValue = SettingValue>(id: string, listener: (value: T | undefined) => void): () => void;
+    registerWidget(widgetId: string, component: CustomWidgetComponent): void;
+    unregisterWidget(widgetId: string): void;
 }
 
 export declare type SettingsHost = {
@@ -1789,7 +1938,17 @@ export declare type SettingsRegistrationResult = {
     registered: string[];
 };
 
-export declare type SettingValue = boolean | number | string | undefined;
+export declare type SettingValue = JsonSerializable | undefined;
+
+export declare class ShellAPI {
+    #private;
+    constructor(host?: ShellHost);
+    openExternal(url: string): Promise<void>;
+}
+
+export declare type ShellHost = {
+    openExternal(url: string): Promise<void>;
+};
 
 export declare type Stream = {
     url: string;
@@ -1869,6 +2028,8 @@ export declare type StringWidget = {
     type: 'textarea';
     placeholder?: string;
     rows?: number;
+} | {
+    type: 'info';
 };
 
 export declare type Track = {
@@ -1894,6 +2055,12 @@ export declare type TrackRef = {
 
 export declare const useSetting: <T extends SettingValue = SettingValue>(host: SettingsHost | undefined, id: string) => readonly [T | undefined, (nextValue: T) => void];
 
+export declare type WidgetRegistry = {
+    register(pluginId: string, widgetId: string, component: CustomWidgetComponent): void;
+    unregister(pluginId: string, widgetId: string): void;
+    get(pluginId: string, widgetId: string): CustomWidgetComponent | undefined;
+};
+
 export declare class YtdlpAPI {
     private host?;
     constructor(host?: YtdlpHost);