import { NappletMessage } from '@napplet/core';

/**
 * Napplet NAP storage types entrypoint.
 *
 * @module
 */
/**
 * @napplet/nap/storage -- Scoped storage message types for the JSON envelope wire protocol.
 *
 * Defines 8 message types for key-value storage proxied through the shell:
 * - Napplet -> Shell: get, set, remove, keys
 * - Shell -> Napplet: get.result, set.result, remove.result, keys.result
 *
 * All types form a discriminated union on the `type` field.
 * Values are strings; null indicates a missing key.
 * All results include an optional `error` field.
 */

/** The NAP domain name for storage messages. */
declare const DOMAIN: "storage";
/**
 * Storage scope for a request: `"shared"` (default) or `"instance"`.
 *
 * `"shared"` is the default; a request that omits `scope` MUST behave exactly
 * as a shared request (backward compatible). `"instance"` selects per-instance
 * storage, reached via the `instance.*` sugar. This is the only wire-level
 * addition for per-instance storage.
 *
 * @see NAP-STORAGE (napplet/naps) — non-normative; defer to the spec.
 */
type StorageScope = 'shared' | 'instance';
/**
 * Base interface for all storage NAP messages.
 * Concrete message types narrow the `type` field to specific literals.
 */
interface StorageMessage extends NappletMessage {
    /** Message type in "storage.<action>" format. */
    type: `storage.${string}`;
}
/**
 * Retrieve a stored value by key.
 *
 * @example
 * ```ts
 * const msg: StorageGetMessage = {
 *   type: 'storage.get',
 *   id: crypto.randomUUID(),
 *   key: 'user-preference',
 * };
 * ```
 */
interface StorageGetMessage extends StorageMessage {
    type: 'storage.get';
    /** Correlation ID. */
    id: string;
    /** The storage key to retrieve. */
    key: string;
    /** Storage scope; default `"shared"` when omitted. */
    scope?: StorageScope;
}
/**
 * Store a key-value pair.
 *
 * @example
 * ```ts
 * const msg: StorageSetMessage = {
 *   type: 'storage.set',
 *   id: crypto.randomUUID(),
 *   key: 'user-preference',
 *   value: 'dark-mode',
 * };
 * ```
 */
interface StorageSetMessage extends StorageMessage {
    type: 'storage.set';
    /** Correlation ID. */
    id: string;
    /** The storage key. */
    key: string;
    /** The string value to store. */
    value: string;
    /** Storage scope; default `"shared"` when omitted. */
    scope?: StorageScope;
}
/**
 * Remove a stored key.
 */
interface StorageRemoveMessage extends StorageMessage {
    type: 'storage.remove';
    /** Correlation ID. */
    id: string;
    /** The storage key to remove. */
    key: string;
    /** Storage scope; default `"shared"` when omitted. */
    scope?: StorageScope;
}
/**
 * List all storage keys for this napplet.
 */
interface StorageKeysMessage extends StorageMessage {
    type: 'storage.keys';
    /** Correlation ID. */
    id: string;
    /** Storage scope; default `"shared"` when omitted. */
    scope?: StorageScope;
}
/**
 * Result of a storage.get request.
 */
interface StorageGetResultMessage extends StorageMessage {
    type: 'storage.get.result';
    /** Correlation ID matching the original request. */
    id: string;
    /** The stored value, or null if key does not exist. */
    value: string | null;
    /** Error message if request failed. */
    error?: string;
}
/**
 * Result of a storage.set request.
 */
interface StorageSetResultMessage extends StorageMessage {
    type: 'storage.set.result';
    /** Correlation ID matching the original request. */
    id: string;
    /** Error message if request failed (e.g., quota exceeded). */
    error?: string;
}
/**
 * Result of a storage.remove request.
 */
interface StorageRemoveResultMessage extends StorageMessage {
    type: 'storage.remove.result';
    /** Correlation ID matching the original request. */
    id: string;
    /** Error message if request failed. */
    error?: string;
}
/**
 * Result of a storage.keys request.
 */
interface StorageKeysResultMessage extends StorageMessage {
    type: 'storage.keys.result';
    /** Correlation ID matching the original request. */
    id: string;
    /** Array of all storage keys for this napplet. */
    keys: string[];
    /** Error message if request failed. */
    error?: string;
}
/** Napplet -> Shell storage request messages. */
type StorageRequestMessage = StorageGetMessage | StorageSetMessage | StorageRemoveMessage | StorageKeysMessage;
/** Shell -> Napplet storage result messages. */
type StorageResultMessage = StorageGetResultMessage | StorageSetResultMessage | StorageRemoveResultMessage | StorageKeysResultMessage;
/** All storage NAP message types (discriminated union on `type` field). */
type StorageNapMessage = StorageRequestMessage | StorageResultMessage;

export { DOMAIN, type StorageGetMessage, type StorageGetResultMessage, type StorageKeysMessage, type StorageKeysResultMessage, type StorageMessage, type StorageNapMessage, type StorageRemoveMessage, type StorageRemoveResultMessage, type StorageRequestMessage, type StorageResultMessage, type StorageScope, type StorageSetMessage, type StorageSetResultMessage };