import { ConfigValues, ConfigSchemaErrorCode, NappletConfigSchema } from './types.js';
import { Subscription } from '@napplet/core';

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

/**
 * Handle config.* messages from the shell. Called by the central shim dispatcher.
 *
 * Routes three shell->napplet message types:
 * - `config.registerSchema.result` -- positive-ACK for registerSchema (correlated by id)
 * - `config.values` -- dual-use: correlated response to config.get (with id) OR subscription push (without id)
 * - `config.schemaError` -- uncorrelated error push (e.g., no-schema, manifest parse failure)
 *
 * @param msg  A parsed envelope object with at least a `type` string field
 */
declare function handleConfigMessage(msg: {
    type: string;
    [key: string]: unknown;
}): void;
/**
 * Register a napplet configuration schema at runtime.
 *
 * The local schema snapshot is populated only after the shell accepts this
 * explicit registration; the shim never discovers protocol state from HTML.
 *
 * Correlates via UUID; resolves on `config.registerSchema.result { ok: true }`;
 * rejects with `Error(code + ': ' + error)` on `{ ok: false }`.
 *
 * @param schema   JSON Schema (draft-07+) describing this napplet's config surface.
 * @param version  Optional `$version` migration hint.
 * @returns Promise<void> that resolves on acceptance.
 */
declare function registerSchema(schema: NappletConfigSchema, version?: number): Promise<void>;
/**
 * Request a one-shot snapshot of the current validated + defaulted config values.
 *
 * Correlates via UUID; resolves on `config.values` carrying the matching id.
 *
 * @returns Promise resolving to the current ConfigValues.
 */
declare function get(): Promise<ConfigValues>;
/**
 * Subscribe to live configuration updates.
 *
 * The wire-level `config.subscribe` is emitted only on the 0->1 local-subscriber
 * transition; subsequent subscribers piggyback on the existing wire subscription.
 * Late subscribers (arriving after a snapshot has already landed) receive an
 * initial callback via `queueMicrotask` using the cached `lastValues`, so every
 * subscriber gets an initial delivery without waiting for the next push.
 *
 * The returned Subscription's `close()` removes the callback; on 1->0 transition
 * the wire-level `config.unsubscribe` is emitted.
 *
 * @param callback  Invoked with the current ConfigValues snapshot on each push.
 * @returns A Subscription with `close()` to detach.
 */
declare function subscribe(callback: (values: ConfigValues) => void): Subscription;
/**
 * Request the shell open its settings UI for this napplet.
 *
 * Fire-and-forget. The optional `section` deep-links to a named section
 * declared via the `x-napplet-section` extension somewhere in the current
 * schema. The shell decides render style (modal, panel, tab) and MAY ignore
 * an unknown section silently.
 *
 * @param options.section  Optional section name to deep-link to.
 */
declare function openSettings(options?: {
    section?: string;
}): void;
/**
 * Listen for schema-registration errors pushed by the shell.
 *
 * Fires on every `config.schemaError` push (no correlation id); typical
 * triggers are manifest schema parse failures at napplet load time and
 * `no-schema` when a subscribe/get arrives before any schema has been
 * registered.
 *
 * @param callback  Invoked with `{ code, error }` on each error push.
 * @returns A plain teardown function that removes the listener.
 */
declare function onSchemaError(callback: (err: {
    code: ConfigSchemaErrorCode;
    error: string;
}) => void): () => void;
/**
 * Install the config shim and mount `window.napplet.config`.
 *
 * Idempotent: a second call is a no-op and returns a no-op cleanup.
 *
 * @returns cleanup function that clears all state and removes the window mount.
 */
declare function installConfigShim(): () => void;

export { get, handleConfigMessage, installConfigShim, onSchemaError, openSettings, registerSchema, subscribe };