import { ResourceBytesRequest, ResourceBytesItem, ResourceSidecarEntry, ResourceInfo } from '@napplet/core';

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

/**
 * Handle resource.* result messages from the shell via the central message listener.
 * Called by @napplet/shim's central dispatch loop (Phase 128 wires this in).
 */
declare function handleResourceMessage(msg: {
    type: string;
    [key: string]: unknown;
}): void;
/**
 * Install the resource shim. Currently a registration-only entry point --
 * resource fetches are issued on demand, not at install time.
 *
 * @returns cleanup function that clears all in-flight + pending state
 */
declare function installResourceShim(): () => void;

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

/**
 * Inspect resource schemes and coarse policy limits disclosed by the shell.
 *
 * This is advisory introspection only. Callers can issue `bytes` or `bytesMany`
 * without calling `info()` first.
 *
 * @returns Promise resolving to the resource info snapshot.
 */
declare function info(): Promise<ResourceInfo>;
/**
 * Fetch bytes for a URL through the shell's resource pipeline.
 *
 * - `data:` URLs are decoded inline (no postMessage round-trip).
 * - All other schemes route through the shell via a `resource.bytes` envelope.
 * - Concurrent calls for the same URL share a single in-flight Promise (single-flight cache).
 * - Aborted signals are honored synchronously and via cancel envelope.
 *
 * @param url   URL identifying the resource (any registered scheme)
 * @param opts  Optional advisory Blossom `servers` and `{ signal }` for cancellation
 * @returns Promise resolving to the fetched bytes as a Blob
 *
 * @example
 * ```ts
 * const blob = await bytes('https://example.com/avatar.png');
 *
 * // With cancellation:
 * const ac = new AbortController();
 * const promise = bytes('blossom:abc...', { signal: ac.signal });
 * ac.abort(); // -> rejects with AbortError, sends resource.cancel envelope
 * ```
 */
declare function bytes(url: string, opts?: {
    servers?: string[];
    signal?: AbortSignal;
}): Promise<Blob>;
/**
 * Fetch bytes for many per-resource requests through one shell envelope.
 *
 * `items` preserves the input order and length. Failed URLs are represented as
 * `ok: false` items so successful siblings remain available to the caller.
 *
 * @param requests  Non-empty resource request list with optional per-resource Blossom servers.
 * @param opts  Optional `{ signal }` for AbortController cancellation.
 * @returns Promise resolving to ordered per-URL resource result items.
 */
declare function bytesMany(requests: ResourceBytesRequest[], opts?: {
    signal?: AbortSignal;
}): Promise<ResourceBytesItem[]>;
/**
 * Convenience wrapper around bytes(url) returning a managed object URL handle.
 *
 * The returned `url` is initially an empty string; it is replaced with the
 * actual blob URL once the underlying fetch resolves. Callers SHOULD await
 * `ready` (a non-enumerable Promise extension) before assigning to img/audio
 * or use a then-callback pattern.
 *
 * The synchronous return shape `{ url, revoke }` matches the locked
 * NappletGlobal['resource'] contract; a non-enumerable `ready` Promise is
 * defined on the handle for callers that need to await blob materialization.
 *
 * `revoke()` is idempotent -- multiple calls release the URL exactly once.
 * If `revoke()` is called BEFORE the underlying fetch resolves, the resolved
 * blob URL is never created (cancellation of object-URL allocation, not the
 * underlying fetch).
 *
 * @param url  URL identifying the resource
 * @returns `{ url, revoke }` handle. After `await (handle as any).ready`,
 *          `url` is the blob URL.
 *
 * @example
 * ```ts
 * const handle = bytesAsObjectURL('blossom:abc123...');
 * await (handle as { ready: Promise<unknown> }).ready;
 * imgEl.src = handle.url;
 * imgEl.onload = () => handle.revoke();
 * ```
 */
declare function bytesAsObjectURL(url: string): {
    url: string;
    revoke: () => void;
};
/**
 * Pre-populate the single-flight cache from sidecar entries (consumed by
 * Phase 127 NAP-RELAY sidecar amendment). After this call, subsequent
 * bytes(entry.url) for hydrated URLs resolves synchronously from cache.
 *
 * Note: hydrated entries live in the inflight map until the first consumer
 * settles them; v0.28.0 has no long-lived blob cache (deferred).
 *
 * @param entries  Pre-resolved resource entries from a relay event sidecar
 *
 * @example
 * ```ts
 * hydrateResourceCache([
 *   { url: 'https://example.com/a.png', blob: aBlob, mime: 'image/png' },
 *   { url: 'blossom:def456', blob: bBlob, mime: 'image/jpeg' },
 * ]);
 * // Subsequent bytes('https://example.com/a.png') resolves from cache.
 * ```
 */
declare function hydrateResourceCache(entries?: ResourceSidecarEntry[]): void;

export { bytes, bytesAsObjectURL, bytesMany, handleResourceMessage, hydrateResourceCache, info, installResourceShim };