@pulsesync/yamusic-types 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PulseSync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# `@pulsesync/yamusic-types`
+
+TypeScript declaration package for PulseSync YaMusic addons.
+
+## Использование
+
+```ts
+import type { PulseSyncApi, SonataState } from '@pulsesync/yamusic-types'
+```
+
+```ts
+import '@pulsesync/yamusic-types/global'
+```
+
+## Разработка
+
+```bash
+npm install
+npm run check
+npm run build
+```
+
+## Локальная проверка перед публикацией
+
+```bash
+npm run pack
+```
+
+Для публикации:
+
+```bash
+npm run publish:public
+```
+
+Нужен `.env` с `NPM_TOKEN=...`.

package/dist/global.d.ts

@@ -0,0 +1,12 @@
+import type { PulseSyncApi, PulseSyncDesktopEvents, SonataState, WolfyLibraryGlobal } from './index';
+declare global {
+    interface Window {
+        pulsesyncApi?: PulseSyncApi;
+        sonataState?: SonataState;
+        desktopEvents?: PulseSyncDesktopEvents;
+        WolfyLibrary?: WolfyLibraryGlobal;
+        Addon?: typeof import('./index').Addon;
+        findCssRuleByPartialName?: (partialName: string) => string[];
+    }
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,361 @@
+export type AddonSettingValue<T> = {
+    value?: T;
+    default?: T;
+};
+export type AddonSettings = Record<string, AddonSettingValue<unknown> | unknown>;
+export interface AddonSettingsStore<TSettings extends AddonSettings = AddonSettings> {
+    getCurrent: () => TSettings;
+    onChange: (callback: (settings: TSettings) => void) => () => void;
+}
+export type PulseSyncRepeatMode = 'none' | 'all' | 'one' | string;
+export type PulseSyncPlayerStatus = 'playing' | 'paused' | 'buffering' | 'idle' | 'stopped' | 'ended' | 'mediaElementError' | string;
+export interface PulseSyncPlayVibeParams extends Record<string, unknown> {
+    screen?: string;
+}
+export interface PulseSyncTrackSelector {
+    albumId?: string;
+    from?: string;
+    position?: 'next' | 'last' | string;
+}
+export interface PulseSyncTrackArtist {
+    id?: string | number;
+    name?: string;
+    [key: string]: unknown;
+}
+export interface PulseSyncTrackAlbum {
+    id?: string | number;
+    name?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+export interface PulseSyncDerivedColors {
+    accent?: string;
+    average?: string;
+    miniPlayer?: string;
+    waveText?: string;
+    [key: string]: unknown;
+}
+export interface PulseSyncTrackMeta {
+    id: string;
+    title?: string;
+    version?: string;
+    duration?: number;
+    durationMs?: number;
+    artists?: PulseSyncTrackArtist[];
+    albums?: PulseSyncTrackAlbum[];
+    coverUri?: string;
+    derivedColors?: PulseSyncDerivedColors;
+    lyricsAvailable?: boolean;
+    [key: string]: unknown;
+}
+export interface PulseSyncQueueEntity {
+    entityData?: {
+        meta?: PulseSyncTrackMeta;
+    };
+    data?: {
+        meta?: PulseSyncTrackMeta;
+    };
+    hidden?: boolean;
+    likeStore?: Record<string, unknown>;
+}
+export interface PulseSyncBaseQueueItem {
+    entity?: PulseSyncQueueEntity;
+    [key: string]: unknown;
+}
+export interface PulseSyncProgressState {
+    duration?: number;
+    loaded?: number;
+    position?: number;
+    remainingBufferedTime?: number;
+    [key: string]: unknown;
+}
+export interface PulseSyncObservableState<T> {
+    value?: T;
+    onChange?: (callback: (value: T) => void, options?: Record<string, unknown>) => (() => void) | void;
+}
+export interface PulseSyncMediaPlayerMethods {
+    destroy?: () => void;
+    pause?: () => Promise<unknown> | unknown;
+    play?: (params?: Record<string, unknown>) => Promise<unknown> | unknown;
+    releaseSrc?: (reason?: unknown) => Promise<unknown> | unknown;
+    reload?: (entity?: unknown) => Promise<unknown> | unknown;
+    resume?: () => Promise<unknown> | unknown;
+    setContainer?: (container?: unknown) => void;
+    setExponentVolume?: (value: number) => Promise<number> | number;
+    setProgress?: (value: number) => Promise<number> | number;
+    setSpeed?: (value: number) => Promise<number> | number;
+    setVolume?: (value: number) => Promise<number> | number;
+    startTimeTracking?: (currentContextEntityPair?: SonataContextEntityPair, nextContextEntityPair?: SonataContextEntityPair) => void;
+    stop?: () => Promise<unknown> | unknown;
+    togglePause?: () => Promise<unknown> | unknown;
+}
+export interface SonataMediaPlayerRuntimeState {
+    initialState?: Record<string, unknown>;
+    onChange?: (state: SonataMediaPlayerRuntimeState) => void;
+    status?: PulseSyncObservableState<PulseSyncPlayerStatus>;
+    preloadingStatus?: PulseSyncObservableState<unknown>;
+    event?: PulseSyncObservableState<string>;
+    progress?: PulseSyncObservableState<number | PulseSyncProgressState>;
+    volume?: PulseSyncObservableState<number>;
+    exponentVolume?: PulseSyncObservableState<number>;
+    speed?: PulseSyncObservableState<number>;
+    [key: string]: unknown;
+}
+export interface SonataContextEntityPair {
+    context?: SonataEntityContext | SonataCurrentContextValue;
+    entity?: SonataEntity;
+    lastChangeMethod?: string | null;
+    lastSeekPosition?: number;
+    internalPositionSec?: number;
+    positionSec?: number;
+    canBePlayedOnlyWithCrossing?: boolean;
+    [key: string]: unknown;
+}
+export interface SonataMediaPlayerNode extends PulseSyncMediaPlayerMethods {
+    state?: SonataMediaPlayerRuntimeState;
+    mediaProvider?: unknown;
+    hooks?: Record<string, unknown>;
+    handlers?: Record<string, unknown>;
+    core?: unknown;
+    currentAudioElement?: PulseSyncObservableState<HTMLAudioElement | null>;
+    isCrossing?: PulseSyncObservableState<boolean>;
+    isEnabled?: PulseSyncObservableState<boolean>;
+    [key: string]: unknown;
+}
+export interface SonataCrossMediaPlayerValue extends PulseSyncMediaPlayerMethods {
+    audioElementsStore?: Array<HTMLAudioElement | null | undefined>;
+    config?: {
+        useVolumeForAudioEffect?: boolean;
+        [key: string]: unknown;
+    };
+    crossInMediaPlayer?: SonataMediaPlayerNode | null;
+    crossOutMediaPlayer?: SonataMediaPlayerNode | null;
+    currentAudioElement?: PulseSyncObservableState<HTMLAudioElement | null>;
+    currentContextEntityPair?: SonataContextEntityPair | null;
+    currentEntityEarlyOutStart?: number;
+    currentMediaPlayer?: SonataMediaPlayerNode | null;
+    firstMediaPlayer?: SonataMediaPlayerNode;
+    hooks?: Record<string, unknown>;
+    isCrossfadeForceDisabled?: boolean;
+    isCrossing?: PulseSyncObservableState<boolean>;
+    isEnabled?: PulseSyncObservableState<boolean>;
+    isReadyForAudioEffect?: PulseSyncObservableState<boolean>;
+    isReadyForAudioEffectInStart?: PulseSyncObservableState<boolean>;
+    nextContextEntityPair?: SonataContextEntityPair | null;
+    secondMediaPlayer?: SonataMediaPlayerNode;
+    state?: SonataMediaPlayerRuntimeState;
+    ticker?: Record<string, unknown>;
+    forceStopCrossfade?: () => void;
+    [key: string]: unknown;
+}
+export interface SonataAvailableActionState extends PulseSyncObservableState<boolean> {
+}
+export interface SonataAvailableActions {
+    moveBackward: SonataAvailableActionState;
+    moveForward: SonataAvailableActionState;
+    repeat?: SonataAvailableActionState;
+    shuffle?: SonataAvailableActionState;
+    speed?: SonataAvailableActionState;
+    [key: string]: PulseSyncObservableState<boolean> | undefined;
+}
+export interface SonataCurrentContextData {
+    type?: string;
+    meta?: {
+        id?: string | number;
+        streamEpisodeId?: string | number;
+        stream?: {
+            id?: string | number;
+            [key: string]: unknown;
+        };
+        streamSlug?: string;
+        session?: {
+            radioSessionId?: string | number;
+            batchId?: string | number;
+            sequence?: string | number;
+            [key: string]: unknown;
+        };
+        sessionTracks?: unknown[];
+        [key: string]: unknown;
+    };
+    enableVariousAutoFlow?: boolean;
+    [key: string]: unknown;
+}
+export interface SonataCurrentContextValue {
+    from?: string;
+    restartsCount?: number;
+    contextData?: {
+        from?: string;
+        type?: string;
+        meta?: {
+            id?: string | number;
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+    data?: SonataCurrentContextData;
+    availableActions?: SonataAvailableActions;
+    sendFeedback?: (...args: unknown[]) => Promise<unknown> | unknown;
+    [key: string]: unknown;
+}
+export interface SonataLikeStore extends Record<string, unknown> {
+    isTrackLiked?: (entityId: string) => boolean;
+    isTrackDisliked?: (entityId: string) => boolean;
+    likeTrack?: (entityId: string) => boolean;
+    unlikeTrack?: (entityId: string) => boolean;
+    dislikeTrack?: (entityId: string) => boolean;
+    undislikeTrack?: (entityId: string) => boolean;
+}
+export interface SonataEntity extends PulseSyncQueueEntity {
+    likeStore?: SonataLikeStore;
+}
+export interface SonataEntityContext {
+    data?: SonataCurrentContextData;
+    [key: string]: unknown;
+}
+export interface SonataQueueItem {
+    entity?: SonataEntity;
+    context?: SonataEntityContext;
+    canBePlayed?: (params?: Record<string, unknown>) => boolean;
+    lastSeekPosition?: number;
+    positionSec?: number;
+    [key: string]: unknown;
+}
+export interface SonataState {
+    playerState?: SonataMediaPlayerRuntimeState;
+    currentMediaPlayer?: PulseSyncObservableState<SonataMediaPlayerNode | SonataCrossMediaPlayerValue | null>;
+    mediaPlayersStore?: PulseSyncObservableState<Record<string, SonataMediaPlayerNode | SonataCrossMediaPlayerValue>>;
+    queueState?: {
+        prevIndex?: PulseSyncObservableState<number | null>;
+        currentEntity?: PulseSyncObservableState<SonataQueueItem>;
+        prevEntity?: PulseSyncObservableState<SonataQueueItem>;
+        nextEntity?: PulseSyncObservableState<SonataQueueItem>;
+        entityList?: PulseSyncObservableState<SonataQueueItem[]>;
+        index?: PulseSyncObservableState<number>;
+        nextIndex?: PulseSyncObservableState<number | null>;
+        livePlayableIndex?: PulseSyncObservableState<number>;
+        order?: PulseSyncObservableState<number[]>;
+        repeat?: PulseSyncObservableState<PulseSyncRepeatMode>;
+        shuffle?: PulseSyncObservableState<boolean>;
+        filterParams?: PulseSyncObservableState<Record<string, unknown>>;
+        [key: string]: unknown;
+    };
+    currentContext?: PulseSyncObservableState<SonataCurrentContextValue>;
+    [key: string]: unknown;
+}
+export type PulseSyncPlayerState = SonataState;
+export type PulseSyncQueueItem = SonataQueueItem;
+export interface PulseSyncApi {
+    playVibe: (params?: PulseSyncPlayVibeParams) => void;
+    play: () => void;
+    pause: () => void;
+    togglePlayPause: () => void;
+    next: () => void;
+    previous: () => void;
+    setRepeatMode: (mode: PulseSyncRepeatMode) => void;
+    toggleShuffle: () => void;
+    setVolume: (volume: number) => void;
+    setProgress: (progress: number) => void;
+    playTrackById: (trackId: string, options?: PulseSyncTrackSelector) => void;
+    addTrackToQueueById: (trackId: string, options?: PulseSyncTrackSelector) => void;
+    likeTrack: (trackId?: string, options?: PulseSyncTrackSelector) => boolean;
+    unlikeTrack: (trackId?: string, options?: PulseSyncTrackSelector) => boolean;
+    dislikeTrack: (trackId?: string, options?: PulseSyncTrackSelector) => boolean;
+    undislikeTrack: (trackId?: string, options?: PulseSyncTrackSelector) => boolean;
+    isTrackLiked: (trackId?: string, albumId?: string) => boolean;
+    isTrackDisliked: (trackId?: string, albumId?: string) => boolean;
+    getState: () => PulseSyncPlayerState | null | undefined;
+    getCurrentTrack: () => PulseSyncTrackMeta | undefined;
+    getQueue: () => PulseSyncQueueItem[] | undefined;
+    getProgress: () => number | PulseSyncProgressState | undefined;
+    getDuration: () => number | undefined;
+    getVolume: () => number | undefined;
+    getRepeatMode: () => PulseSyncRepeatMode | undefined;
+    isShuffle: () => boolean | undefined;
+    getSettings: <TSettings extends AddonSettings = AddonSettings>(addonId: string) => AddonSettingsStore<TSettings>;
+}
+export interface WolfyPlayerState {
+    speed: number;
+    status: PulseSyncPlayerStatus;
+    page: string;
+    volume: number;
+    progress: PulseSyncProgressState;
+    shuffle: boolean;
+    repeat: PulseSyncRepeatMode;
+    track: PulseSyncTrackMeta;
+    [key: string]: unknown;
+}
+export interface WolfyContext {
+    settings: SettingsManager;
+    styles: StylesManager;
+    state: WolfyPlayerState;
+}
+export interface WolfyActionContext extends WolfyContext {
+    setting: unknown;
+    changed: boolean;
+}
+export type WolfyEventCallback<TData = unknown> = (data: TData) => void;
+export type WolfyActionHandler = (context: WolfyActionContext) => void;
+export declare class StylesManager {
+    constructor(addonName: string);
+    readonly result: string;
+    apply(): void;
+    add(id: string, styles: string): void;
+    remove(id: string): boolean;
+    clear(): void;
+}
+export declare class EventEmitter {
+    on<TData = unknown>(eventName: string, callback: WolfyEventCallback<TData>): void;
+    off<TData = unknown>(eventName: string, callback: WolfyEventCallback<TData>): void;
+    emit<TData = unknown>(eventName: string, data: TData): void;
+    once<TData = unknown>(eventName: string, callback: WolfyEventCallback<TData>): void;
+    removeAllListeners(eventName: string): void;
+}
+export declare class SettingsManager extends EventEmitter {
+    constructor(addon: Addon);
+    settings: AddonSettings;
+    oldSettings: AddonSettings;
+    start(): void;
+    update(): Promise<AddonSettings | null>;
+    get<TValue = unknown>(id: string): TValue | undefined;
+    hasChanged(id: string): boolean;
+}
+export declare class AssetsManager {
+    constructor(addonName: string);
+    getContent<TValue = unknown>(fileName: string): Promise<TValue>;
+    getFileLink(fileName: string): string;
+    readonly files: Promise<string[] | undefined>;
+}
+export declare class PlayerEvents extends EventEmitter {
+    constructor(addon: Addon);
+    settingsManager: SettingsManager;
+    stylesManager: StylesManager;
+    state: WolfyPlayerState;
+}
+export declare class Addon {
+    constructor(addonName: string);
+    name: string;
+    actions: Record<string, WolfyActionHandler>;
+    stylesManager: StylesManager;
+    assetsManager: AssetsManager;
+    settingsManager: SettingsManager;
+    player: PlayerEvents;
+    applyTheme(): void;
+    addAction(id: string, callback: WolfyActionHandler): void;
+    update(): Promise<void>;
+    start(): void;
+}
+export interface WolfyLibraryGlobal {
+    StylesManager: typeof StylesManager;
+    EventEmitter: typeof EventEmitter;
+    SettingsManager: typeof SettingsManager;
+    AssetsManager: typeof AssetsManager;
+    PlayerEvents: typeof PlayerEvents;
+    Addon: typeof Addon;
+}
+export interface PulseSyncDesktopEvents {
+    send: (name: string, ...args: unknown[]) => void;
+    on: <TArgs extends unknown[] = unknown[]>(name: string, callback: (event: unknown, ...args: TArgs) => void) => () => void;
+    off: (name: string, listener: (event: unknown, ...args: unknown[]) => void) => void;
+    invoke: <TResult = unknown>(name: string, ...args: unknown[]) => Promise<TResult>;
+    emit: (name: string, ...args: unknown[]) => unknown;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pulsesync/yamusic-types",
+  "version": "0.0.1",
+  "description": "TypeScript declaration package for PulseSync YaMusic addon development",
+  "license": "GPL-3.0-or-later",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.d.ts",
+    "./global": "./dist/global.d.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "pack": "npm run build && npm pack --cache ./.npm-cache",
+    "publish:public": "npm run build && dotenv -e .env -- npm publish --access public --cache ./.npm-cache"
+  },
+  "devDependencies": {
+    "dotenv-cli": "^11.0.0",
+    "typescript": "^6.0.2"
+  },
+  "keywords": [
+    "pulsesync",
+    "yamusic",
+    "addon",
+    "types",
+    "typescript"
+  ]
+}