import { EventTemplate, NostrFilter } from '@napplet/core';
import { OutboxEventOptions, OutboxEventResult, OutboxPublishOptions, OutboxPublishResult, OutboxQueryOptions, OutboxResult, OutboxTarget, OutboxRelayPlan, OutboxSubscribeOptions, OutboxSubscription } from './types.js';

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

/**
 * Handle outbox.* messages from the shell via the central message listener.
 * Covers query/publish/resolveRelays results plus event/closed lifecycle.
 */
declare function handleOutboxMessage(msg: {
    type: string;
    [key: string]: unknown;
}): void;
/**
 * Fetch one event by ID through shell-owned outbox routing. The shell validates
 * that any returned event matches `eventId` and has a valid signature.
 *
 * @param eventId  Event id to fetch
 * @param options  Optional author/relay hints and timeout
 * @returns Promise resolving to the outbox event result
 *
 * @example
 * ```ts
 * const { result } = await getEvent('ev1...', { author: 'ab12...', timeoutMs: 3000 });
 * ```
 */
declare function getEvent(eventId: string, options?: OutboxEventOptions): Promise<OutboxEventResult>;
/**
 * Perform a one-shot outbox-aware query. The shell resolves the relevant relays,
 * queries them, deduplicates events by id, validates signatures, and returns the
 * collected events. Partial results arrive with `incomplete: true`; an inline
 * `error` field describes a query-level failure (the promise still resolves).
 *
 * @param filters  NIP-01 filter or filters
 * @param options  Optional query options (authors, relays, limit, timeoutMs)
 * @returns Promise resolving to the outbox result
 *
 * @example
 * ```ts
 * const { events } = await query(
 *   [{ authors: ['ab12...'], kinds: [1], limit: 20 }],
 *   { authors: ['ab12...'], timeoutMs: 3000 },
 * );
 * ```
 */
declare function query(filters: NostrFilter | NostrFilter[], options?: OutboxQueryOptions): Promise<OutboxResult>;
/**
 * Open a live outbox-aware subscription. Returns a handle with an event-emitter
 * `on(...)` API and `close()`. The shell may add/remove relay connections as
 * NIP-65 relay lists change.
 *
 * @param filters  NIP-01 filter or filters
 * @param options  Optional subscribe options
 * @returns An OutboxSubscription handle
 *
 * @example
 * ```ts
 * const sub = subscribe([{ authors: ['ab12...'], kinds: [1] }], { timeoutMs: 3000 });
 * sub.on('event', (result) => render(result.event, result.sidecar?.relayHints));
 * // later: sub.close();
 * ```
 */
declare function subscribe(filters: NostrFilter | NostrFilter[], options?: OutboxSubscribeOptions): OutboxSubscription;
/**
 * Publish a shell-signed event using outbox-aware relay fanout. The promise
 * resolves with the full result (including inline `ok`/`error`); it rejects only
 * if the shell never responds.
 *
 * @param template  Unsigned event template; the shell signs before fanout
 * @param options   Optional publish fanout (`relays`, `toOutbox`, `toInboxes`);
 *                  `toOutbox` defaults to true when omitted
 * @returns Promise resolving to the outbox publish result
 *
 * @example
 * ```ts
 * const res = await publish(
 *   { kind: 1, content: 'hello', tags: [], created_at: Math.floor(Date.now() / 1000) },
 *   { toInboxes: ['ab12...'] },
 * );
 * ```
 */
declare function publish(template: EventTemplate, options?: OutboxPublishOptions): Promise<OutboxPublishResult>;
/**
 * Resolve the relay plan the shell would use for a read/write target. Useful for
 * diagnostics and UI; prefer `query`/`subscribe`/`publish` for actual access.
 *
 * @param target  The read/write target (authors/pubkey, direction)
 * @returns Promise resolving to the relay plan
 */
declare function resolveRelays(target: OutboxTarget): Promise<OutboxRelayPlan>;
/**
 * Install the outbox shim. Registration-only -- outbox operations are issued on
 * demand, not at install time.
 *
 * @returns cleanup function that rejects pending requests and clears all state
 */
declare function installOutboxShim(): () => void;

export { getEvent, handleOutboxMessage, installOutboxShim, publish, query, resolveRelays, subscribe };