import { MediaSessionCreate, MediaAction, Subscription } from '@napplet/core';
import { MediaSessionResult, MediaState, MediaMetadata } from './types.js';

/**
 * Napplet NAP media sdk entrypoint.
 *
 * @module
 */
/**
 * @napplet/nap/media -- SDK helpers wrapping window.napplet.media.
 *
 * These convenience functions delegate to `window.napplet.media.*` at call time.
 * The shim must be imported somewhere to install the global.
 */

/**
 * Create a new media session.
 *
 * @param options  Ownership-aware media session options
 * @returns The confirmed session result
 *
 * @example
 * ```ts
 * import { mediaCreateSession } from '@napplet/nap/media';
 *
 * const { sessionId } = await mediaCreateSession({
 *   owner: 'napplet',
 *   metadata: { title: 'My Song', artist: 'The Artist' },
 * });
 * ```
 */
declare function mediaCreateSession(options: MediaSessionCreate): Promise<MediaSessionResult>;
/**
 * Update metadata for an existing session.
 *
 * @param sessionId  The session to update
 * @param metadata   Partial metadata fields to update
 *
 * @example
 * ```ts
 * import { mediaUpdateSession } from '@napplet/nap/media';
 *
 * mediaUpdateSession('s1', { title: 'Updated Title' });
 * ```
 */
declare function mediaUpdateSession(sessionId: string, metadata: Partial<MediaMetadata>): void;
/**
 * Destroy a media session.
 *
 * @param sessionId  The session to destroy
 *
 * @example
 * ```ts
 * import { mediaDestroySession } from '@napplet/nap/media';
 *
 * mediaDestroySession('s1');
 * ```
 */
declare function mediaDestroySession(sessionId: string): void;
/**
 * Report current playback state for a session.
 *
 * @param sessionId  The session to report state for
 * @param state      The current playback state
 *
 * @example
 * ```ts
 * import { mediaReportState } from '@napplet/nap/media';
 *
 * mediaReportState('s1', {
 *   status: 'playing',
 *   position: 42.5,
 *   duration: 240,
 *   volume: 0.8,
 * });
 * ```
 */
declare function mediaReportState(sessionId: string, state: MediaState): void;
/**
 * Declare which media actions the session currently supports.
 *
 * @param sessionId  The session to update capabilities for
 * @param actions    Currently supported actions
 *
 * @example
 * ```ts
 * import { mediaReportCapabilities } from '@napplet/nap/media';
 *
 * mediaReportCapabilities('s1', ['play', 'pause', 'seek', 'volume']);
 * ```
 */
declare function mediaReportCapabilities(sessionId: string, actions: MediaAction[]): void;
/**
 * Send a media command to the current playback owner.
 *
 * @param sessionId  The session to control
 * @param action     The media action to request
 * @param value      Optional value for seek/volume
 *
 * @example
 * ```ts
 * import { mediaSendCommand } from '@napplet/nap/media';
 *
 * mediaSendCommand('shell-session', 'pause');
 * ```
 */
declare function mediaSendCommand(sessionId: string, action: MediaAction, value?: number): void;
/**
 * Listen for media commands from the shell.
 *
 * @param sessionId  The session to listen for commands on
 * @param callback   Called with (action, value?) when a command is received
 * @returns A Subscription with `close()` to stop listening
 *
 * @example
 * ```ts
 * import { mediaOnCommand } from '@napplet/nap/media';
 *
 * const sub = mediaOnCommand('s1', (action, value) => {
 *   if (action === 'seek') player.seekTo(value);
 *   if (action === 'pause') player.pause();
 * });
 * // Later: sub.close();
 * ```
 */
declare function mediaOnCommand(sessionId: string, callback: (action: MediaAction, value?: number) => void): Subscription;
/**
 * Listen for shell-reported state for a shell-owned session.
 *
 * @param sessionId  The session to listen for state on
 * @param callback   Called with the current playback state
 * @returns A Subscription with `close()` to stop listening
 */
declare function mediaOnState(sessionId: string, callback: (state: MediaState) => void): Subscription;
/**
 * Listen for shell-reported capabilities for a shell-owned session.
 *
 * @param sessionId  The session to listen for capabilities on
 * @param callback   Called with currently available actions
 * @returns A Subscription with `close()` to stop listening
 */
declare function mediaOnCapabilities(sessionId: string, callback: (actions: MediaAction[]) => void): Subscription;
/**
 * Listen for the shell's media control list.
 *
 * @param sessionId  The session to associate controls with
 * @param callback   Called with the shell's supported controls
 * @returns A Subscription with `close()` to stop listening
 *
 * @example
 * ```ts
 * import { mediaOnControls } from '@napplet/nap/media';
 *
 * const sub = mediaOnControls('s1', (controls) => {
 *   showNextButton = controls.includes('next');
 * });
 * // Later: sub.close();
 * ```
 */
declare function mediaOnControls(sessionId: string, callback: (controls: MediaAction[]) => void): Subscription;

export { mediaCreateSession, mediaDestroySession, mediaOnCapabilities, mediaOnCommand, mediaOnControls, mediaOnState, mediaReportCapabilities, mediaReportState, mediaSendCommand, mediaUpdateSession };