import { UploadInfo, Subscription } from '@napplet/core';
import { UploadStatus, UploadRequest, UploadResult } from './types.js';

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

/**
 * Handle upload.* messages from the shell via the central message listener.
 * Covers upload.upload.result, upload.status.result, and upload.status.changed.
 */
declare function handleUploadMessage(msg: {
    type: string;
    [key: string]: unknown;
}): void;
/**
 * Inspect upload rails and coarse policy limits disclosed by the shell.
 *
 * This is advisory introspection only. Callers can upload without calling
 * `info()` first.
 *
 * @returns Promise resolving to the upload info snapshot
 */
declare function info(): Promise<UploadInfo>;
/**
 * Upload bytes through the shell. The shell handles consent, server selection,
 * rail authorization signing, and the HTTP upload, then resolves with the initial
 * result. For large/async uploads the result has `status: "uploading"` and
 * progress arrives via {@link onStatus}; subscribe before or right after calling.
 *
 * The promise resolves with the `UploadResult` whenever the shell returns one
 * (including `ok: false` for a created-then-failed/cancelled upload). It rejects
 * only when the shell returns a top-level error (no upload created) or never responds.
 *
 * @param request  The upload request (bytes + intent). `data` is a Blob/ArrayBuffer.
 * @returns Promise resolving to the initial upload result
 *
 * @example
 * ```ts
 * const result = await upload({ rail: 'nip96', data: blob, filename: 'pic.png' });
 * if (result.status === 'complete') attach(result.url, result.nip94);
 * ```
 */
declare function upload(request: UploadRequest): Promise<UploadResult>;
/**
 * Get the latest known status for a prior upload, including progress counters.
 *
 * @param uploadId  The shell-generated id from a prior {@link upload}
 * @returns Promise resolving to the latest status
 */
declare function status(uploadId: string): Promise<UploadStatus>;
/**
 * Register for shell-pushed status updates (`upload.status.changed`) -- progress
 * while uploading and the transition to complete/failed. The handler receives
 * every status change; filter on `status.uploadId` to scope to one upload.
 *
 * @param handler  Called with each new UploadStatus
 * @returns A Subscription with `close()` to stop listening
 *
 * @example
 * ```ts
 * const sub = onStatus((s) => {
 *   if (s.uploadId === myId && s.status === 'complete') done(s.url);
 * });
 * ```
 */
declare function onStatus(handler: (status: UploadStatus) => void): Subscription;
/**
 * Install the upload shim. Registration-only -- uploads are issued on demand,
 * not at install time.
 *
 * @returns cleanup function that rejects pending requests and clears all state
 */
declare function installUploadShim(): () => void;

export { handleUploadMessage, info, installUploadShim, onStatus, status, upload };