tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/libs/sw/service/TinyServiceWorkerEngine.d.mts

@@ -0,0 +1,993 @@
+import TinyPushRouter from './TinyPushRouter.mjs';
+import { TinyPluginCore, TinyPlugin, TinyPluginLayer } from '../../plugin/TinyPlugin.mjs';
+export type GlobalMsgCodeItem<Path extends string | null> = {
+    /**
+     * - Absolute path of the file served for this entry.
+     * When the value is `null`, no file is fetched and the response is built from
+     * {@link GlobalMsgCodeItem.msg} only.
+     */
+    path: Path;
+    /**
+     * - Short, human readable message. It is used as the response
+     * body and as the `statusText` of the generated error response.
+     */
+    msg: string;
+    /**
+     * - Message written to the log. It is aimed at developers,
+     * so it can be more descriptive than {@link GlobalMsgCodeItem.msg}.
+     */
+    logMsg: string;
+};
+export type GlobalMsgCode = {
+    spaPath: string;
+    unknown: GlobalMsgCodeItem<string>;
+    200: GlobalMsgCodeItem<null>;
+    404: GlobalMsgCodeItem<string>;
+    500: GlobalMsgCodeItem<string>;
+};
+export type SyncEventObj = {
+    /**
+     * - The native sync event.
+     */
+    event: SyncEvent;
+    /**
+     * - The tag associated with the sync event.
+     */
+    tag: string;
+};
+export type SyncCallback = (msg: SyncEventObj) => Promise<void> | void;
+export type LifecycleEventObj = {
+    /**
+     * - The native install or activate event.
+     */
+    event: ExtendableEvent;
+};
+export type LifecycleCallback = (msg: LifecycleEventObj) => Promise<void> | void;
+export type MessageApiReply = (type: string, data?: MessagePayload, timeout?: number) => Promise<any>;
+export type ApiHandlerOptions = {
+    /**
+     * - The payload received from the browser.
+     */
+    data?: MessagePayload;
+    /**
+     * - The ID of the client that sent the message.
+     */
+    clientId: string;
+    /**
+     * - The request ID.
+     */
+    correlationId: string;
+    /**
+     * - A function to send a reply to the message source.
+     */
+    replyTo: MessageReplyTo;
+    /**
+     * - A function to send a reply to all clients.
+     */
+    replyToAll: MessageReplyToAll;
+    /**
+     * - A template function to format reply messages.
+     */
+    replyTemplate: MessageReplyTemplate;
+    /**
+     * - A convenience method to reply to the message source.
+     */
+    reply: MessageReply;
+    /**
+     * - A convenience method to reply to the message api source.
+     */
+    replyApi: MessageApiReply;
+};
+export type ApiHandlerCallback = (options: ApiHandlerOptions) => Promise<MessagePayload | undefined> | (MessagePayload | undefined);
+export type InstallStrategy = 'immediate' | 'wait' | 'manual';
+export type ActivateStrategy = 'immediate' | 'wait' | 'manual';
+export type LifecycleOrder = 'before' | 'after';
+export type LifecycleOptions = {
+    /**
+     * - How the `install` phase is resolved.
+     */
+    installStrategy: InstallStrategy;
+    /**
+     * - How the `activate` phase is resolved.
+     */
+    activateStrategy: ActivateStrategy;
+    /**
+     * - Order of the strategy inside the `install` phase.
+     */
+    installOrder: LifecycleOrder;
+    /**
+     * - Order of the strategy inside the `activate` phase.
+     */
+    activateOrder: LifecycleOrder;
+};
+export type PartialServiceWorkerSettings = {
+    /**
+     * - Whether the service worker is running in Single Page Application mode.
+     */
+    spaMode?: boolean;
+    /**
+     * - Partial lifecycle configuration.
+     */
+    lifecycle?: Partial<LifecycleOptions>;
+    /**
+     * - Partial configuration for fetch event interception.
+     */
+    fetch: PartialFetchOptions;
+    /**
+     * - Partial configuration for push event interception.
+     */
+    push: PartialPushOptions;
+    /**
+     * - Partial configuration for sync event interception.
+     */
+    sync: PartialSyncOptions;
+    /**
+     * - Partial configuration for message event handling.
+     */
+    messaging: Partial<MessagingOptions>;
+};
+export type PartialSyncOptions = {
+    /**
+     * - Indicates if sync interception is enabled.
+     */
+    enabled?: boolean;
+};
+export type PartialPushOptions = {
+    /**
+     * - Indicates if push interception is enabled.
+     */
+    enabled?: boolean;
+    /**
+     * - Base64 URL-safe VAPID public key.
+     */
+    vapidPublicKey?: string;
+    /**
+     * - Backend route that persists subscriptions.
+     */
+    subscribeEndpoint?: string;
+    /**
+     * - Fallback notification icon.
+     */
+    defaultIcon?: string;
+    /**
+     * - Fallback notification badge.
+     */
+    defaultBadge?: string;
+    /**
+     * - Fallback click URL.
+     */
+    defaultUrl?: string;
+};
+export type PartialFetchOptions = {
+    /**
+     * - Indicates if fetch interception is enabled.
+     */
+    enabled?: boolean;
+    /**
+     * - Partial configuration for the routing logic.
+     */
+    router: Partial<RouterOptions>;
+};
+export type FetchOptions = {
+    /**
+     * - Indicates if fetch interception is enabled.
+     */
+    enabled: boolean;
+    /**
+     * - Configuration for the routing logic.
+     */
+    router: RouterOptions;
+};
+export type PushOptions = {
+    /**
+     * - Indicates if push interception is enabled.
+     */
+    enabled: boolean;
+    /**
+     * - Base64 URL-safe VAPID public key.
+     */
+    vapidPublicKey: string;
+    /**
+     * - Backend route that persists subscriptions.
+     */
+    subscribeEndpoint: string;
+    /**
+     * - Fallback notification icon.
+     */
+    defaultIcon: string;
+    /**
+     * - Fallback notification badge.
+     */
+    defaultBadge: string;
+    /**
+     * - Fallback click URL.
+     */
+    defaultUrl: string;
+};
+export type MessagingOptions = {
+    /**
+     * - Indicates if message communication is enabled.
+     */
+    enabled: boolean;
+};
+export type SyncOptions = {
+    /**
+     * - Indicates if sync interception is enabled.
+     */
+    enabled: boolean;
+};
+export type RouterOptions = {
+    /**
+     * - Indicates if the router is active.
+     */
+    enabled: boolean;
+    /**
+     * - A map linking HTTP status codes to their respective configurations.
+     */
+    codes: Map<number, RouterCodeConfig>;
+};
+export type ServiceWorkerSettings = {
+    /**
+     * - Whether the service worker is running in Single Page Application mode.
+     */
+    spaMode: boolean;
+    /**
+     * - Lifecycle strategy configuration.
+     */
+    lifecycle: LifecycleOptions;
+    /**
+     * - Configuration for fetch event interception.
+     */
+    fetch: FetchOptions;
+    /**
+     * - Configuration for push event interception.
+     */
+    push: PushOptions;
+    /**
+     * - Configuration for background sync event interception.
+     */
+    sync: SyncOptions;
+    /**
+     * - Configuration for message event handling.
+     */
+    messaging: MessagingOptions;
+};
+export type PathGetter = (path: string) => string;
+export type DefaultCodeData = {
+    /**
+     * - A function to retrieve the path for a given input.
+     */
+    pathGetter: PathGetter;
+    /**
+     * - The configuration data for the default response.
+     */
+    data: RouterCodeConfig;
+};
+export type FnOptions = {
+    /**
+     * - The fetch event being handled.
+     */
+    event: FetchEvent;
+    /**
+     * - The request object from the fetch event.
+     */
+    request: Request;
+    /**
+     * - The parsed URL of the request.
+     */
+    url: URL;
+    /**
+     * - The categorized response type.
+     */
+    resType: HttpResponseType;
+    /**
+     * - A custom error message.
+     */
+    customMsg?: string;
+    /**
+     * - A custom page path.
+     */
+    customPath?: string;
+    /**
+     * - The HTTP status code.
+     */
+    code: number;
+};
+export type RouterCodeConfig = {
+    /**
+     * - The function executed to handle the request.
+     */
+    fn: (ops: FnOptions) => Promise<Response> | Response;
+    /**
+     * - The message string to be sent in the response.
+     */
+    msg: string;
+    /**
+     * - The log message to be recorded.
+     */
+    logMsg: string;
+};
+export type FetchCheckerValues = {
+    /**
+     * - The HTTP status code associated with the fetch result.
+     */
+    code: number;
+    /**
+     * - Whether the router must build a response for the current request.
+     */
+    needValidation: boolean;
+    /**
+     * - Whether the next registered fetch listener is still allowed to run.
+     */
+    continueCheck: boolean;
+    /**
+     * - Overrides the path served by the router for this request.
+     */
+    customPath?: string;
+    /**
+     * - Overrides the message attached to the generated response.
+     */
+    customMsg?: string;
+};
+export type FetchCheckerResult = FetchCheckerValues & {
+    [id: string]: any;
+};
+export type MessagePayload = any;
+export type MessagingData = {
+    /**
+     * - The identifier for the message type.
+     */
+    type: string;
+    /**
+     * - The actual payload of the message.
+     */
+    data?: MessagePayload;
+};
+export type MessageReplyTemplate = (type: string, data?: MessagePayload) => MessagingData;
+export type MessageReplyTo = (client: Client, type: string, data?: MessagePayload) => any;
+export type MessageReplyToAllOptions = {
+    /**
+     * - The type identifier for the reply message.
+     */
+    type: string;
+    /**
+     * - The payload to be sent in the reply.
+     */
+    data?: MessagePayload;
+    /**
+     * - Additional options for client matching.
+     */
+    options?: ClientQueryOptions;
+};
+export type MessageReplyToAllResponse = Promise<void | readonly (Client | WindowClient)[]>;
+export type MessageReplyToAll = (options: MessageReplyToAllOptions) => Promise<MessageReplyToAllResponse>;
+export type MessageReply = (type: string, data?: MessagePayload) => any;
+export type MessageObj = {
+    /**
+     * - The original message event.
+     */
+    event: ExtendableMessageEvent;
+    /**
+     * - The ID of the client that sent the message.
+     */
+    clientId: string;
+    /**
+     * - The payload sent within the message.
+     */
+    data?: MessagePayload;
+    /**
+     * - A function to send a reply to the message source.
+     */
+    replyTo: MessageReplyTo;
+    /**
+     * - A function to send a reply to all clients.
+     */
+    replyToAll: MessageReplyToAll;
+    /**
+     * - A template function to format reply messages.
+     */
+    replyTemplate: MessageReplyTemplate;
+    /**
+     * - A convenience method to reply to the message source.
+     */
+    reply: MessageReply;
+};
+export type MessageCallback = (msg: MessageObj) => any;
+export type FetchObjParams = Record<string, string>;
+export type FetchObj = {
+    /**
+     * - The original fetch event.
+     */
+    event: FetchEvent;
+    /**
+     * - The intercepted request.
+     */
+    request: Request;
+    /**
+     * - The parsed URL of the request.
+     */
+    url: URL;
+    /**
+     * - Parameters extracted from the URL (e.g., /:id).
+     */
+    params: FetchObjParams;
+    /**
+     * - A function to send a reply to the message source.
+     */
+    replyTo: MessageReplyTo;
+    /**
+     * - A function to send a reply to all clients.
+     */
+    replyToAll: MessageReplyToAll;
+    /**
+     * - A template function to format reply messages.
+     */
+    replyTemplate: MessageReplyTemplate;
+    /**
+     * - Indicates if the request is same-origin.
+     */
+    isSameOrigin: boolean;
+    /**
+     * - An error object if the plugin execution failed.
+     */
+    error?: Error;
+};
+export type FetchCallback = (fetchObj: FetchObj, result: FetchCheckerResult) => Promise<void> | void;
+export type HttpResponseType = 'info' | 'success' | 'redirect' | 'client-error' | 'server-error' | 'unknown';
+export type SwPluginInstaller<Layer extends TinyPluginLayer, IdString extends string, VersionString extends string, Options extends any[]> = import('../../plugin/TinyPlugin.mjs').TinyPluginInstaller<TinyServiceWorkerEngine, Layer, IdString, VersionString, Options>;
+export type TinyServiceWorkerPlugin<Layer extends TinyPluginLayer, IdString extends string, VersionString extends string, Options extends any[]> = TinyPlugin<TinyServiceWorkerEngine, Layer, IdString, VersionString, Options>;
+/**
+ * Manages the lifecycle and execution of modules based on the provided configuration.
+ */
+declare class TinyServiceWorkerEngine extends TinyPluginCore {
+    #private;
+    static get PUSH_TYPE(): Readonly<{
+        NOTIFICATION: "notification";
+        DATA: "data";
+        SYNC: "sync";
+        COMMAND: "command";
+        UNKNOWN: "unknown";
+    }>;
+    /**
+     * A function used to format a reply message into a standard MessagingData object.
+     *
+     * @param {string} type - The type identifier for the reply message.
+     * @param {MessagePayload} [payload] - The payload to be sent in the reply.
+     * @returns {MessagingData} The formatted message object.
+     * @throws {TypeError} If type is not a string.
+     */
+    static replyTemplate(type: string, payload?: MessagePayload): MessagingData;
+    /**
+     * A function that handles the actual postMessage call to a specific Client.
+     *
+     * @param {Client} targetSource - The target client to receive the message.
+     * @param {string} type - The type identifier for the reply message.
+     * @param {MessagePayload} [payload] - The payload to be sent in the reply.
+     * @returns {void}
+     * @throws {TypeError} If targetSource is invalid or type is not a string.
+     */
+    static replyTo(targetSource: Client, type: string, payload?: MessagePayload): void;
+    /**
+     * A function that handles the actual postMessage call to all Clients.
+     *
+     * @param {MessageReplyToAllOptions} ops - The options for the reply.
+     * @returns {Promise<MessageReplyToAllResponse>} The result of the broadcast.
+     */
+    static replyToAll(ops: MessageReplyToAllOptions): Promise<MessageReplyToAllResponse>;
+    /**
+     * Checks if the provided Request object is a navigation request.
+     * @param {Request} req - The request to evaluate.
+     * @returns {boolean} True if the request mode is 'navigate', false otherwise.
+     */
+    static isNavigate(req: Request): boolean;
+    /**
+     * Determines whether the origin of a given Request or URL matches the origin of the current Service Worker context.
+     * @param {Request|URL} data - The request or URL to check.
+     * @returns {boolean} True if the origins match, false otherwise.
+     */
+    static isSameOrigin(data: Request | URL): boolean;
+    /**
+     * Retrieves the configuration for a specific HTTP status code.
+     * @param {number} c - The HTTP status code.
+     * @returns {RouterCodeConfig} The configuration for the given code.
+     * @throws {TypeError} If c is not a number.
+     */
+    getCodeCfg(c: number): RouterCodeConfig;
+    /**
+     * Sets the SPA mode configuration.
+     * @param {boolean} value - The value to set for spaMode.
+     * @throws {TypeError} If value is not a boolean.
+     */
+    set spaMode(value: boolean);
+    /**
+     * Gets the current SPA mode configuration.
+     * @returns {boolean} The current spaMode value.
+     */
+    get spaMode(): boolean;
+    /**
+     * Gets a deep clone of the current lifecycle configuration.
+     *
+     * @returns {LifecycleOptions} A deep cloned copy of the lifecycle configuration.
+     */
+    get lifecycle(): LifecycleOptions;
+    /**
+     * Merges the provided properties into the current lifecycle configuration.
+     *
+     * The operation is a **merge**, not a replacement: omitted keys keep their
+     * current value. This is required because the internal validation is strict,
+     * so a partial patch such as `{ strategyOrder: 'before' }` must not erase the
+     * install and activate strategies.
+     *
+     * @param {Partial<LifecycleOptions>} value - The lifecycle properties to merge.
+     * @throws {TypeError} If `value` is not a valid partial {@link LifecycleOptions}.
+     */
+    set lifecycle(value: Partial<LifecycleOptions>);
+    /**
+     * Returns the global path based on the current SPA mode configuration.
+     * @param {string} path - The original path.
+     * @returns {string} The path adjusted for SPA mode or the original path.
+     * @throws {TypeError} If path is not a non-empty string.
+     */
+    globalPathGetter(path: string): string;
+    /**
+     * Handles a successful fetch request.
+     * @param {string} msg - The message to be logged.
+     * @param {string} logMsg - The log message to be recorded.
+     * @param {string|PathGetter} pathGetter - The path to fetch.
+     * @param {FnOptions} options - The options for the fetch operation.
+     * @returns {Promise<Response>} A promise that resolves to the Response object.
+     */
+    fetchFn(msg: string, logMsg: string, pathGetter: string | PathGetter, options: FnOptions): Promise<Response>;
+    /**
+     * Handles a failed fetch request by simulating an error page.
+     * @param {string} msg - The message to be logged.
+     * @param {string} logMsg - The log message to be recorded.
+     * @param {string|PathGetter} pathGetter - The path to fetch.
+     * @param {FnOptions} options - The options for the fetch operation.
+     * @returns {Promise<Response>} A promise that resolves to the error Response object.
+     */
+    fetchErrorFn(msg: string, logMsg: string, pathGetter: string | PathGetter, options: FnOptions): Promise<Response>;
+    /**
+     * Creates a configuration for a fetch response.
+     * @param {Object} ops - The creation options.
+     * @param {boolean} ops.isError - Indicates if it is an error response.
+     * @param {string} ops.msg - The message to be sent.
+     * @param {string} ops.logMsg - The log message.
+     * @param {string|PathGetter} ops.pathGetter - The path to use for the response.
+     * @returns {RouterCodeConfig} The newly created configuration.
+     * @throws {TypeError} If any property is missing or has the wrong type.
+     */
+    createFetchRes({ isError, msg, logMsg, pathGetter }: {
+        isError: boolean;
+        msg: string;
+        logMsg: string;
+        pathGetter: string | PathGetter;
+    }): RouterCodeConfig;
+    /**
+     * Replaces the push router.
+     * @param {TinyPushRouter} router - The new router.
+     * @throws {TypeError} If `router` is not a TinyPushRouter.
+     */
+    set pushRouter(router: TinyPushRouter);
+    /** @returns {TinyPushRouter} The active push router. */
+    get pushRouter(): TinyPushRouter;
+    /**
+     * Sets the engine configuration.
+     * @param {ServiceWorkerSettings} config - The new configuration to apply.
+     * @throws {TypeError} If the configuration does not meet the minimum requirements.
+     */
+    set config(config: ServiceWorkerSettings);
+    /**
+     * Gets the current engine configuration.
+     * Returns a deep clone to prevent external mutation of the internal state.
+     * @returns {ServiceWorkerSettings} A deep cloned copy of the configuration.
+     */
+    get config(): ServiceWorkerSettings;
+    /**
+     * Indicates if the engine has been initialized.
+     * @returns {boolean} True if started, false otherwise.
+     */
+    get started(): boolean;
+    /**
+     * Initializes a new instance of the TinyServiceWorkerEngine with the provided configuration and logger settings.
+     * @param {Partial<PartialServiceWorkerSettings>} config - The configuration to apply.
+     * @param {Object} [lgConfig] - Configuration options for the instance.
+     * @param {boolean} [lgConfig.debugMode=false] - Whether to enable internal debug logging.
+     * @param {boolean} [lgConfig.useLogColors=false] - Whether to enable log color support.
+     * @param {Partial<Console>} [lgConfig.logger=console] - A custom logger object.
+     * @throws {TypeError} If the configuration does not meet the minimum requirements.
+     */
+    constructor(config?: Partial<PartialServiceWorkerSettings>, lgConfig?: {
+        debugMode?: boolean;
+        useLogColors?: boolean;
+        logger?: Partial<Console>;
+    });
+    /**
+     * Gets the number of registered fetch RegExp listeners.
+     * @returns {number} The count of registered RegExp listeners.
+     */
+    get fetchRegExpSize(): number;
+    /**
+     * Adds a fetch RegExp listener.
+     * @param {string} type - The identifier for the fetch type.
+     * @param {FetchCallback} callback - The callback to execute.
+     */
+    addFetchRegExpListener(type: string, callback: FetchCallback): void;
+    /**
+     * Removes a fetch RegExp listener.
+     * @param {string} type - The identifier for the fetch type.
+     * @returns {boolean} True if the listener was removed, false otherwise.
+     */
+    removeFetchRegExpListener(type: string): boolean;
+    /**
+     * Retrieves a fetch RegExp listener.
+     * @param {string} type - The identifier for the fetch type.
+     * @returns {FetchCallback|undefined} The listener, or undefined if not found.
+     */
+    getFetchRegExpListener(type: string): FetchCallback | undefined;
+    /**
+     * Checks if a fetch RegExp listener exists.
+     * @param {string} type - The identifier for the fetch type.
+     * @returns {boolean} True if the listener exists, false otherwise.
+     */
+    hasFetchRegExp(type: string): boolean;
+    /**
+     * Clears all registered fetch RegExp listeners.
+     * @returns {void}
+     */
+    clearFetchRegExps(): void;
+    /**
+     * Gets the number of registered fetch URL listeners.
+     * @returns {number} The count of registered URL listeners.
+     */
+    get fetchUrlSize(): number;
+    /**
+     * Adds a fetch URL listener.
+     * @param {string} type - The identifier for the fetch type.
+     * @param {FetchCallback} callback - The callback to execute.
+     */
+    addFetchUrlListener(type: string, callback: FetchCallback): void;
+    /**
+     * Removes a fetch URL listener.
+     * @param {string} type - The identifier for the fetch type.
+     * @returns {boolean} True if the listener was removed, false otherwise.
+     */
+    removeFetchUrlListener(type: string): boolean;
+    /**
+     * Retrieves a fetch URL listener.
+     * @param {string} type - The identifier for the fetch type.
+     * @returns {FetchCallback|undefined} The listener, or undefined if not found.
+     */
+    getFetchUrlListener(type: string): FetchCallback | undefined;
+    /**
+     * Checks if a fetch URL listener exists.
+     * @param {string} type - The identifier for the fetch type.
+     * @returns {boolean} True if the listener exists, false otherwise.
+     */
+    hasFetchUrl(type: string): boolean;
+    /**
+     * Clears all registered fetch URL listeners.
+     * @returns {void}
+     */
+    clearFetchUrls(): void;
+    /**
+     * Gets the number of registered global fetch tracking listeners.
+     * @returns {number} The count of registered tracking listeners.
+     */
+    get fetchGlobalSize(): number;
+    /**
+     * Adds a global fetch tracking listener.
+     * @param {string} type - The identifier for the tracking type.
+     * @param {FetchCallback} callback - The callback function to be executed.
+     */
+    addFetchGlobalListener(type: string, callback: FetchCallback): void;
+    /**
+     * Removes a global fetch tracking listener.
+     * @param {string} type - The identifier for the tracking type.
+     * @returns {boolean} True if the listener was removed, false otherwise.
+     */
+    removeFetchGlobalListener(type: string): boolean;
+    /**
+     * Retrieves a global fetch tracking listener.
+     * @param {string} type - The identifier for the tracking type.
+     * @returns {FetchCallback|undefined} The listener, or undefined if not found.
+     */
+    getFetchGlobalListener(type: string): FetchCallback | undefined;
+    /**
+     * Checks if a global fetch tracking listener exists.
+     * @param {string} type - The identifier for the tracking type.
+     * @returns {boolean} True if the listener exists, false otherwise.
+     */
+    hasFetchGlobal(type: string): boolean;
+    /**
+     * Clears all global fetch tracking listeners.
+     * @returns {void}
+     */
+    clearFetchGlobals(): void;
+    /**
+     * Gets the number of registered message listeners.
+     * @returns {number} The count of registered message listeners.
+     */
+    get messagesSize(): number;
+    /**
+     * Adds a message listener.
+     * @param {string} type - The identifier for the message type.
+     * @param {MessageCallback} callback - The callback to execute.
+     */
+    addMessageListener(type: string, callback: MessageCallback): void;
+    /**
+     * Removes a message listener.
+     * @param {string} type - The identifier for the message type.
+     * @returns {boolean} True if the listener was removed, false otherwise.
+     */
+    removeMessageListener(type: string): boolean;
+    /**
+     * Retrieves a message listener.
+     * @param {string} type - The identifier for the message type.
+     * @returns {MessageCallback|undefined} The listener, or undefined if not found.
+     */
+    getMessageListener(type: string): MessageCallback | undefined;
+    /**
+     * Checks if a message listener exists.
+     * @param {string} type - The identifier for the message type.
+     * @returns {boolean} True if the listener exists, false otherwise.
+     */
+    hasMessageListener(type: string): boolean;
+    /**
+     * Clears all registered message listeners.
+     * @returns {void}
+     */
+    clearMessageListeners(): void;
+    /**
+     * Returns a copy of the blacklisted event names.
+     * @returns {string[]} An array with every blacklisted event name.
+     */
+    get eventBlacklist(): string[];
+    /**
+     * Adds an event name to the blacklist. Blacklisted events are ignored when
+     * they arrive from the browser.
+     * @param {string} type - The event name to ignore.
+     * @returns {void}
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    addToEventBlacklist(type: string): void;
+    /**
+     * Removes an event name from the blacklist.
+     * @param {string} type - The event name to remove.
+     * @returns {boolean} True if the event was removed, false otherwise.
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    removeFromEventBlacklist(type: string): boolean;
+    /**
+     * Checks whether an event name is blacklisted.
+     * @param {string} type - The event name to check.
+     * @returns {boolean} True if the event is blacklisted, false otherwise.
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    hasInEventBlacklist(type: string): boolean;
+    /**
+     * Removes every event name from the blacklist.
+     * @returns {void}
+     */
+    clearEventBlacklist(): void;
+    /**
+     * Promotes the waiting Service Worker to the active state.
+     *
+     * This is the manual counterpart of the `'immediate'` install strategy. It is
+     * safe to call at any time: when no worker is waiting, the browser resolves the
+     * call without side effects.
+     *
+     * @param {ExtendableEvent} [event] - The lifecycle event that triggered the call, when any.
+     * @returns {Promise<boolean>} `true` when `skipWaiting()` was requested.
+     * @throws {TypeError} If `event` is provided and does not expose a `waitUntil` method.
+     */
+    skipWaiting(event?: ExtendableEvent): Promise<boolean>;
+    /**
+     * Makes the active Service Worker take control of every open client.
+     *
+     * This is the manual counterpart of the `'immediate'` activate strategy.
+     *
+     * @param {ClientQueryOptions} [query] - Filter applied to the clients that must be claimed.
+     * @returns {Promise<readonly Client[]>} The clients that are now controlled.
+     * @throws {TypeError} If `query` is provided and is not a non-null object.
+     */
+    claimClients(query?: ClientQueryOptions): Promise<readonly Client[]>;
+    /**
+     * Forces every controlled client to navigate to the given URL.
+     *
+     * Useful when the new Service Worker changes the routing contract and the open
+     * tabs must be reloaded to stay consistent with the new version.
+     *
+     * @param {string} [url] - Target URL. Defaults to the current URL of each client.
+     * @returns {Promise<number>} The number of clients that were navigated.
+     * @throws {TypeError} If `url` is provided and is not a non-empty string.
+     */
+    reloadClients(url?: string): Promise<number>;
+    /**
+     * Gets a deep clone of the current global message configuration.
+     * @returns {GlobalMsgCode} A deep cloned copy of the global message configuration.
+     */
+    get globalMsgCode(): GlobalMsgCode;
+    /**
+     * Replaces the whole global message configuration.
+     *
+     * The provided object is validated and deep cloned, so later mutations of the
+     * argument do not affect the engine.
+     *
+     * @param {GlobalMsgCode} newConfig - The complete configuration that replaces the current one.
+     * @throws {TypeError} If `newConfig` is not a complete, valid {@link GlobalMsgCode} object.
+     */
+    set globalMsgCode(newConfig: GlobalMsgCode);
+    /**
+     * Merges the provided properties into the current global message configuration.
+     *
+     * @param {Partial<GlobalMsgCode>} newConfig - The properties to merge.
+     * @throws {TypeError} If `newConfig` is not a valid partial {@link GlobalMsgCode} object.
+     */
+    updateGlobalMsgCode(newConfig: Partial<GlobalMsgCode>): void;
+    /**
+     * Adds or updates a custom router configuration for a specific HTTP status code.
+     * @param {number} code - The HTTP status code.
+     * @param {RouterCodeConfig} config - The configuration object.
+     * @throws {TypeError} If code is not a number or config is invalid.
+     */
+    addRouterCode(code: number, config: RouterCodeConfig): void;
+    /**
+     * Removes a custom router configuration for a specific HTTP status code.
+     * @param {number} code - The HTTP status code to remove.
+     * @returns {boolean} True if a code was removed, false otherwise.
+     * @throws {TypeError} If code is not a number.
+     */
+    removeRouterCode(code: number): boolean;
+    /**
+     * Retrieves a deep clone of the current configuration for a specific HTTP status code.
+     * @param {number} code - The HTTP status code.
+     * @returns {RouterCodeConfig|undefined} A deep cloned copy of the configuration or undefined.
+     * @throws {TypeError} If code is not a number.
+     */
+    getRouterCode(code: number): RouterCodeConfig | undefined;
+    /**
+     * Adds a handler for a specific sync event.
+     * @param {string} tag - The tag of the sync event.
+     * @param {SyncCallback} callback - The function to be executed.
+     * @throws {TypeError} If tag is not a string or callback is not a function.
+     */
+    addSyncListener(tag: string, callback: SyncCallback): void;
+    /**
+     * Removes a sync handler for a specific tag.
+     * @param {string} tag - The tag of the sync event.
+     * @returns {boolean} True if the handler was removed.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    removeSyncListener(tag: string): boolean;
+    /**
+     * Returns the number of registered sync listeners.
+     * @returns {number} The count of registered sync listeners.
+     */
+    get syncListenerSize(): number;
+    /**
+     * Clears all sync listeners.
+     * @returns {void}
+     */
+    clearSyncListeners(): void;
+    /**
+     * Gets the number of registered install listeners.
+     * @returns {number} The count of registered install listeners.
+     */
+    get installListenerSize(): number;
+    /**
+     * Adds an install listener.
+     * @param {string} tag - The identifier for the install listener.
+     * @param {LifecycleCallback} callback - The callback to execute.
+     * @returns {void}
+     * @throws {TypeError} If tag is not a non-empty string or callback is not a function.
+     */
+    addInstallListener(tag: string, callback: LifecycleCallback): void;
+    /**
+     * Removes an install listener.
+     * @param {string} tag - The identifier for the install listener.
+     * @returns {boolean} True if the listener was removed, false otherwise.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    removeInstallListener(tag: string): boolean;
+    /**
+     * Retrieves an install listener.
+     * @param {string} tag - The identifier for the install listener.
+     * @returns {LifecycleCallback|undefined} The listener, or undefined if not found.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    getInstallListener(tag: string): LifecycleCallback | undefined;
+    /**
+     * Checks if an install listener exists.
+     * @param {string} tag - The identifier for the install listener.
+     * @returns {boolean} True if the listener exists, false otherwise.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    hasInstallListener(tag: string): boolean;
+    /**
+     * Clears all registered install listeners.
+     * @returns {void}
+     */
+    clearInstallListeners(): void;
+    /**
+     * Gets the number of registered activate listeners.
+     * @returns {number} The count of registered activate listeners.
+     */
+    get activateListenerSize(): number;
+    /**
+     * Adds an activate listener.
+     * @param {string} tag - The identifier for the activate listener.
+     * @param {LifecycleCallback} callback - The callback to execute.
+     * @returns {void}
+     * @throws {TypeError} If tag is not a non-empty string or callback is not a function.
+     */
+    addActivateListener(tag: string, callback: LifecycleCallback): void;
+    /**
+     * Removes an activate listener.
+     * @param {string} tag - The identifier for the activate listener.
+     * @returns {boolean} True if the listener was removed, false otherwise.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    removeActivateListener(tag: string): boolean;
+    /**
+     * Retrieves an activate listener.
+     * @param {string} tag - The identifier for the activate listener.
+     * @returns {LifecycleCallback|undefined} The listener, or undefined if not found.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    getActivateListener(tag: string): LifecycleCallback | undefined;
+    /**
+     * Checks if an activate listener exists.
+     * @param {string} tag - The identifier for the activate listener.
+     * @returns {boolean} True if the listener exists, false otherwise.
+     * @throws {TypeError} If tag is not a non-empty string.
+     */
+    hasActivateListener(tag: string): boolean;
+    /**
+     * Clears all registered activate listeners.
+     * @returns {void}
+     */
+    clearActivateListeners(): void;
+    /**
+     * Removes a registered API handler.
+     * @param {string} type - The identifier for the call.
+     * @returns {boolean} True if the handler was removed, false otherwise.
+     * @throws {TypeError} If type is not a non-empty string.
+     */
+    offApi(type: string): boolean;
+    /**
+     * Registers a handler for API calls coming from the browser.
+     * @param {string} type - The identifier for the call.
+     * @param {ApiHandlerCallback} callback - Function that processes the request and returns a payload.
+     * @returns {void}
+     * @throws {TypeError} If type is not a non-empty string or callback is not a function.
+     */
+    onApi(type: string, callback: ApiHandlerCallback): void;
+    /**
+     * Sends a request to a specific client in the browser and waits for a response.
+     * @param {Client} client - The client (tab/worker) to which to send.
+     * @param {string} type - The identifier for the call.
+     * @param {MessagePayload} [data] - The request payload.
+     * @param {number} [timeout=10000] - Maximum waiting time in milliseconds.
+     * @returns {Promise<any>} A promise that resolves with the result object or undefined from the Service Worker.
+     * @throws {TypeError} If any argument has an invalid type.
+     */
+    emitApi(client: Client, type: string, data?: MessagePayload, timeout?: number): Promise<any>;
+    /**
+     * Displays a native notification to the user.
+     *
+     * @param {string} title - The notification title.
+     * @param {string} body - The message body.
+     * @param {NotificationOptions} [options] - Additional options from the Notification API.
+     * @returns {Promise<void>}
+     */
+    showNotification(title: string, body: string, options?: NotificationOptions): Promise<void>;
+    /**
+     * Initializes the Service Worker event listeners.
+     * @returns {void}
+     * @throws {Error} If the engine has already been started.
+     */
+    init(): void;
+}
+export default TinyServiceWorkerEngine;
+//# sourceMappingURL=TinyServiceWorkerEngine.d.mts.map