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

/**
 * Napplet NAP media shim entrypoint.
 *
 * @module
 */

/**
 * Handle media.* messages from the shell via the central message listener.
 */
declare function handleMediaMessage(msg: {
    type: string;
    [key: string]: unknown;
}): void;
/**
 * Create a new media session with the shell.
 * Returns the shell result with the canonical session ID and owner, or error.
 *
 * @param options  Ownership-aware media session options
 * @returns The confirmed session result
 */
declare function createSession(options: MediaSessionCreate): Promise<MediaSessionResult>;
/**
 * Update metadata for an existing session.
 * Fire-and-forget -- no response expected.
 *
 * @param sessionId  The session to update
 * @param metadata   Partial metadata fields to update
 */
declare function updateSession(sessionId: string, metadata: Partial<MediaMetadata>): void;
/**
 * Destroy a media session.
 * Fire-and-forget -- no response expected.
 *
 * @param sessionId  The session to destroy
 */
declare function destroySession(sessionId: string): void;
/**
 * Report current playback state for a session.
 * Fire-and-forget, high frequency during active playback.
 *
 * @param sessionId  The session to report state for
 * @param state      The current playback state
 */
declare function reportState(sessionId: string, state: MediaState): void;
/**
 * Declare which media actions the session currently supports.
 * Fire-and-forget.
 *
 * @param sessionId  The session to update capabilities for
 * @param actions    Currently supported actions
 */
declare function reportCapabilities(sessionId: string, actions: MediaAction[]): void;
/**
 * Send a media command to the current playback owner.
 * Used by napplets to control shell-owned sessions.
 *
 * @param sessionId  The session to control
 * @param action     The media action to request
 * @param value      Optional value for seek/volume
 */
declare function sendCommand(sessionId: string, action: MediaAction, value?: number): void;
/**
 * Listen for media commands from the shell for a specific session.
 * Returns a Subscription with close() to stop listening.
 *
 * @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 unsubscribe
 */
declare function onCommand(sessionId: string, callback: (action: MediaAction, value?: number) => void): Subscription;
/**
 * Listen for shell-reported state for a shell-owned session.
 * Returns a Subscription with close() to stop listening.
 *
 * @param sessionId  The session to listen for state on
 * @param callback   Called with the shell-owned playback state
 * @returns A Subscription with `close()` to unsubscribe
 */
declare function onState(sessionId: string, callback: (state: MediaState) => void): Subscription;
/**
 * Listen for shell-reported capabilities for a shell-owned session.
 * Returns a Subscription with close() to stop listening.
 *
 * @param sessionId  The session to listen for capabilities on
 * @param callback   Called with currently available actions
 * @returns A Subscription with `close()` to unsubscribe
 */
declare function onCapabilities(sessionId: string, callback: (actions: MediaAction[]) => void): Subscription;
/**
 * Listen for the shell's media control list for a specific session.
 * Returns a Subscription with close() to stop listening.
 *
 * @param sessionId  The session to listen for controls on
 * @param callback   Called with the shell's supported controls
 * @returns A Subscription with `close()` to unsubscribe
 */
declare function onControls(sessionId: string, callback: (controls: MediaAction[]) => void): Subscription;
/**
 * Install the media shim. Currently a no-op placeholder --
 * media sessions are created on demand, not at install time.
 *
 * @returns cleanup function that clears all state
 */
declare function installMediaShim(): () => void;

export { createSession, destroySession, handleMediaMessage, installMediaShim, onCapabilities, onCommand, onControls, onState, reportCapabilities, reportState, sendCommand, updateSession };