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

/**
 * Napplet NAP config sdk entrypoint.
 *
 * @module
 */
/**
 * @napplet/nap/config -- SDK helpers wrapping window.napplet.config.
 *
 * These convenience functions delegate to `window.napplet.config.*` at call time.
 * The runtime must inject the `config` domain before these wrappers are called.
 * Each wrapper is a thin, stateless facade over the mounted API -- no domain
 * logic lives here.
 *
 * Bare names are used (not `configGet` / `configSubscribe` etc.) per the merged
 * NAP-CONFIG spec. Phase 115 re-exports these under a `config` namespace in
 * `@napplet/sdk` to avoid collisions with other NAPs.
 */

/**
 * Snapshot current validated + defaulted config values.
 *
 * @returns A one-shot ConfigValues object.
 *
 * @example
 * ```ts
 * import { get } from '@napplet/nap/config';
 *
 * const values = await get();
 * console.log(values.theme);
 * ```
 */
declare function get(): Promise<ConfigValues>;
/**
 * Subscribe to live config values. First delivery is an immediate snapshot;
 * subsequent deliveries fire whenever the shell commits a change.
 *
 * @param cb  Called with the full validated + defaulted ConfigValues on every change.
 * @returns A Subscription with close() to stop listening.
 *
 * @example
 * ```ts
 * import { subscribe } from '@napplet/nap/config';
 *
 * const sub = subscribe((values) => { applyTheme(values.theme); });
 * // later:
 * sub.close();
 * ```
 */
declare function subscribe(cb: (values: ConfigValues) => void): Subscription;
/**
 * Request the shell open its settings UI for this napplet.
 * Optional section deep-links by `x-napplet-section` name.
 *
 * @param options  Optional section deep-link.
 *
 * @example
 * ```ts
 * import { openSettings } from '@napplet/nap/config';
 *
 * openSettings({ section: 'credentials' });
 * ```
 */
declare function openSettings(options?: {
    section?: string;
}): void;
/**
 * Register a configuration schema with the shell at runtime.
 *
 * @param schema   JSON Schema (draft-07+) describing the config surface.
 * @param version  Optional `$version` migration hint.
 * @returns Promise that resolves on successful registration, rejects on shell rejection.
 *
 * @example
 * ```ts
 * import { registerSchema } from '@napplet/nap/config';
 *
 * await registerSchema({
 *   type: 'object',
 *   properties: { theme: { type: 'string', enum: ['light', 'dark'], default: 'dark' } },
 * }, 1);
 * ```
 */
declare function registerSchema(schema: NappletConfigSchema, version?: number): Promise<void>;
/**
 * Listen for schema-registration errors pushed by the shell (manifest parse
 * failure, subscribe-before-schema, etc.).
 *
 * @param cb  Called with { code, error } on every config.schemaError push.
 * @returns A teardown function that detaches the listener.
 *
 * @example
 * ```ts
 * import { onSchemaError } from '@napplet/nap/config';
 *
 * const off = onSchemaError((err) => console.error(err.code, err.error));
 * // later:
 * off();
 * ```
 */
declare function onSchemaError(cb: (err: {
    code: ConfigSchemaErrorCode;
    error: string;
}) => void): () => void;

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