# 🚀 TinyServiceWorkerEngine Documentation

Welcome to the official documentation for the **TinyServiceWorkerEngine**. This engine is a professional-grade tool designed to manage the complexities of a Service Worker, specifically focusing on **Fetch Interception**, **Messaging Communication**, and **Lifecycle Management**.

Instead of writing hundreds of lines of repetitive `addEventListener` logic, this engine provides a structured, plugin-based architecture to handle network requests and cross-context communication.

---

## 🧠 Core Concepts (The Mental Model)

To use this engine effectively, you must understand its three primary "layers":

1.  **The Interception Layer (Fetch):** The engine sits between the browser and the network. It can watch every request, match it against patterns (URLs or Regex), and decide: *"Should I let this go to the internet, or should I provide a custom response (like a cached file or an error page)?"*
2.  **The Communication Layer (Messaging):** The Service Worker lives in a separate thread from your web page. This engine provides a "bridge" to send structured messages back and forth using `postMessage`, including helper methods to reply specifically to the sender.
3.  **The Routing Layer (Router):** When a fetch fails (e.g., a 404 or 500 error), the engine can automatically route the user to a specific "Error Page" (like `404.html`) without you writing manual logic every time.

---

## 🛠️ Getting Started

### 1. The Constructor

To start the engine, you must instantiate the `TinyServiceWorkerEngine` class and call the `.init()` method.

When you instantiate the engine, you can provide two configuration objects.

#### `new TinyServiceWorkerEngine(config, lgConfig)`

**Parameter: `config` (Object) — `ServiceWorkerSettings`**
Defines the operational behavior of the engine.
* `spaMode` (boolean): If `true`, the engine uses the `spaPath` (default: `/index.html`) when handling routing errors. If `false`, it uses the original requested path.
* `lifecycle` (Object) — `LifecycleOptions`: Controls how the `install` and `activate` phases are resolved.
  * `installStrategy` (`'immediate' | 'wait' | 'manual'`): How the `install` phase is resolved. Default: `'immediate'`.
  * `activateStrategy` (`'immediate' | 'wait' | 'manual'`): How the `activate` phase is resolved. Default: `'immediate'`.
  * `installOrder` (`'before' | 'after'`): Whether the install strategy runs before or after the install listeners. Default: `'after'`.
  * `activateOrder` (`'before' | 'after'`): Whether the activate strategy runs before or after the activate listeners. Default: `'after'`.
* `fetch` (Object):
  * `enabled` (boolean): Activates/deactivates fetch interception.
  * `router` (Object):
      * `enabled` (boolean): Activates/deactivates the automatic error routing.
      * `codes` (Map<number, RouterCodeConfig>): A Map where keys are HTTP status codes and values are custom response handlers.
* `push` (Object) — `PushOptions`: Configuration for push notification interception.
  * `enabled` (boolean): Activates/deactivates push event interception.
  * `vapidPublicKey` (string): Base64 URL-safe VAPID public key.
  * `subscribeEndpoint` (string): Backend route that persists subscriptions.
  * `defaultIcon` (string): Fallback notification icon.
  * `defaultBadge` (string): Fallback notification badge.
  * `defaultUrl` (string): Fallback click URL.
* `sync` (Object) — `SyncOptions`: Configuration for background sync event interception.
  * `enabled` (boolean): Activates/deactivates sync event interception.
* `messaging` (Object):
  * `enabled` (boolean): Activates/deactivates the `message` event listener.

**Parameter: `lgConfig` (Object) — `LoggerOptions`**
Defines how the engine logs its internal operations.
*   `debugMode` (boolean): If `true`, enables verbose internal logging.
*   `useLogColors` (boolean): If `true`, adds terminal/console colors to logs.
*   `logger` (Object): A custom logger (defaults to `console`).

**Why this structure?**
By separating `config` from `lgConfig`, we separate **business logic** (how the SW behaves) from **developer tools** (how the SW reports its status).

```javascript
import TinyServiceWorkerEngine from 'tiny-essentials/libs/sw/service/TinyServiceWorkerEngine';

const engine = new TinyServiceWorkerEngine({
  spaMode: true, // Set to true if you are building a Single Page Application
  lifecycle: {
    installStrategy: 'manual', // 'immediate' | 'wait' | 'manual'
    activateStrategy: 'manual',
    installOrder: 'after',
    activateOrder: 'after',
  },
  fetch: {
    enabled: true,
    router: {
      enabled: true,
      codes: new Map(), // You can add custom status code handlers here
    },
  },
  messaging: {
    enabled: true,
  },
});

// This is a mandatory step to start listening to events
engine.init();
```

**Why `init()`?**
The constructor sets up the internal state, but the `.init()` method actually attaches the listeners to the `self` (Service Worker) global scope. Without it, the engine remains idle.

---

## 🌐 Feature 1: Fetch Interception

The engine allows you to intercept requests using three different levels of granularity. All listeners receive a `fetchObj` and `result` as the arguments.

**Callback Signature:**
`async (fetchObj: FetchObj, result: FetchCheckerResult) => Promise<void> | void`

### 📦 The `fetchObj` Argument Reference
When a match is found, the callback is executed with this object:

| Property | Type | Description |
| :--- | :--- | :--- |
| `event` | `FetchEvent` | The original browser FetchEvent. |
| `request` | `Request` | The original Request object being intercepted. |
| `url` | `URL` | The parsed URL object of the request. |
| `params` | `Record<string, string>` | Key-value pairs extracted from dynamic paths (e.g., `/:id`). |
| `isSameOrigin` | `boolean` | `true` if the request is from the same origin as the SW. |
| `replyTo` | `Function` | Helper to reply to the specific client that triggered the fetch. |
| `replyToAll` | `Function` | Helper to broadcast a message to all open browser tabs. |
| `replyTemplate` | `Function` | Utility to format a message object before sending. |
| `error` | `Error` (Optional) | Contains error details if the plugin execution failed. |

### ⚙️ The Interception Flow Control (`result` object)

When you intercept a request, the engine provides a `result` object as the **second argument** to your callback function. This object is used to communicate back to the engine how the interception should proceed.

#### `FetchCheckerResult` Property Reference

| Property | Type | Description |
| :--- | :--- | :--- |
| `code` | `number` | The HTTP status code associated with the fetch result. This can be used to trigger the Router. |
| `needValidation` | `boolean` | **The Router Trigger.** If `true`, the engine checks the `code` against the Router configuration. If the code is an error (like 404), the engine will serve the configured error page. |
| `continueCheck` | `boolean` | **The Flow Controller.** If set to `false`, the engine immediately stops searching for other matching plugins and proceeds with the standard network request. |
| `customPath` | `string` (optional) | Overrides the path resolved by the Router for this specific request. |
| `customMsg` | `string` (optional) | Overrides the message sent to the Router for this specific request. |
| `customResponse` | `Response` (optional) | **The Direct Reply.** If set to a `Response` instance, the engine returns it immediately, bypassing the Router and the network. |

> ⚠️ **Important — Priority Order:** The engine evaluates `continueCheck` **before** `customResponse`. If you set `continueCheck = false`, the engine performs the network request and **ignores** any `customResponse` you may have set. To return a custom response, set **only** `customResponse` and leave `continueCheck` as `true` (its default).

#### 🛠️ Practical Implementation Examples

**1. Returning a Custom Response (`customResponse`)**
Callbacks do **not** return a `Response`. Instead, you assign it to `result.customResponse`. The engine detects this instance after the plugin chain finishes and returns it to the browser.

```javascript
engine.addFetchUrlListener('/api/secure-data', async (fetchObj, result) => {
  // Perform security logic...

  // Provide a direct response using customResponse
  result.customResponse = new Response(JSON.stringify({ data: 'secret' }), {
    headers: { 'Content-Type': 'application/json' },
  });
});
```

**2. Stopping the Search (Flow Control)**
If you want to stop the engine from evaluating other plugins for this request and let the network handle it, set `continueCheck` to `false`.

```javascript
engine.addFetchUrlListener('/api/public', async (fetchObj, result) => {
  // Stop the engine from looking for more matches for this request
  result.continueCheck = false;
});
```

**3. Forcing an Error Page (Router Trigger)**
If your plugin detects that a resource is missing (even if the browser has not realized it yet), you can force the engine to trigger the Router by setting `needValidation` to `true` and providing a `code`.

```javascript
engine.addFetchUrlListener('/old-api/:version', async (fetchObj, result) => {
  const isLegacy = fetchObj.params.version === 'v1';

  if (isLegacy) {
    // Force the engine to treat this as a 404 error and trigger the Router
    result.code = 404;
    result.needValidation = true;
  }
});
```

**4. Bypassing the Router for Errors**
Sometimes a request returns a 404, but you want the browser to handle it normally (perhaps to allow a different part of your app to catch the error) instead of showing a custom `404.html` page.

```javascript
engine.addFetchUrlListener('/api/external-service', async (fetchObj, result) => {
  // We do not want the Router to intercept this 404.
  // We want the original 404 response to go straight to the application.
  result.needValidation = false;
});
```

**5. Exact or Parameterized URL Matching**

```javascript
// Intercepting a specific path
engine.addFetchUrlListener('/api/config', async ({ url }, result) => {
  console.log('Intercepted config request:', url);
  result.customResponse = new Response(JSON.stringify({ status: 'ok' }), {
    headers: { 'Content-Type': 'application/json' },
  });
});

// Intercepting a parameterized path
engine.addFetchUrlListener('/user/:id', async ({ params }, result) => {
  const { id } = params; // The engine extracts ':id' automatically
  result.customResponse = new Response(`Hello User ${id}`);
});
```

**6. Regular Expression (RegExp) Matching**
Use this for patterns that are too complex for simple URL strings.

```javascript
// Intercepting any image request
engine.addFetchRegExpListener('\\.png$', async ({ url }) => {
  console.log('User requested a PNG:', url.pathname);
  // You could return a placeholder image here
});
```

**7. Global Tracking**
If you want to perform an action (like logging) on **every single request** without changing the response, use the Global listener.

```javascript
engine.addFetchGlobalListener('analytics', async ({ url }) => {
  console.log(`Request made to: ${url.pathname}`);
  // This does not stop the request; it just "watches" it.
});
```

---

## 💬 Feature 2: Messaging System

The messaging system enables bidirectional communication. Listeners receive a `msg` object as their first argument.

### 📦 The `msg` Argument Reference
When a message is received, the callback is executed with this object:

| Property | Type | Description |
| :--- | :--- | :--- |
| `event` | `ExtendableMessageEvent` | The original message event. |
| `clientId` | `string` | The unique ID of the client (tab) that sent the message. |
| `data` | `Object` | The payload sent by the client (`event.data.data`). |
| `reply` | `Function` | A convenience method to reply directly to the sender. |
| `replyTo` | `Function` | Sends a message to a specific `Client`. |
| `replyToAll` | `Function` | Broadcasts a message to all available clients. |
| `replyTemplate` | `Function` | Formats the reply into the required `MessagingData` structure. |

```javascript
engine.addMessageListener('GET_USER_DATA', async ({ data, reply }) => {
  const userId = data.id;
  
  // Perform some logic
  const userData = { id: userId, name: 'Yasmin' };

  // Reply directly to the specific window/client that asked
  reply('USER_DATA_RESPONSE', userData);
});
```

### Sending a Message from the Website (Main Thread)

```javascript
// In your main app.js
navigator.serviceWorker.controller.postMessage({
  type: 'GET_USER_DATA',
  data: { id: 123 }
});

// Listening for the reply
navigator.serviceWorker.addEventListener('message', (event) => {
  if (event.data.type === 'USER_DATA_RESPONSE') {
    console.log('Received data:', event.data.data);
  }
});
```

**Why use `msg.reply()`?**
In a Service Worker, there might be many open tabs. If you use a broadcast, every tab receives the message. `msg.reply()` ensures that **only the tab that requested the data** receives the answer.

### 🚫 Event Blacklist (Third-Party Isolation)

The `message` event is shared by every Service Worker in the same scope. A third-party worker can therefore deliver events that reach your handlers. The blacklist drops those events **before** they are dispatched to any registered listener.

```javascript
// Ignore every event emitted by a third-party worker.
engine.addToEventBlacklist('THIRD_PARTY_PING');
engine.addToEventBlacklist('analytics:beacon');

// Check and remove.
engine.hasInEventBlacklist('THIRD_PARTY_PING'); // true
engine.removeFromEventBlacklist('THIRD_PARTY_PING'); // true

// Inspect or reset the whole list.
console.log(engine.eventBlacklist); // ['analytics:beacon']
engine.clearEventBlacklist();
```

> **Note:** The filter is applied to **incoming** messages only. It never blocks an event that your own code sends with `reply`, `replyTo` or `replyToAll`.

---

## 🚦 Feature 3: The HTTP Router

The router automatically handles errors by serving specific HTML files based on the HTTP status code.

### Customizing Error Pages

`addRouterCode` expects a `RouterCodeConfig` object. The recommended way to build one is the `createFetchRes` helper, which wires the `pathGetter` into the correct fetch handler:

```javascript
// If a request returns a 404, serve a custom 404.html file
engine.addRouterCode(
  404,
  engine.createFetchRes({
    isError: true,
    msg: 'Not Found',
    logMsg: 'User tried to access a non-existent route',
    pathGetter: () => '/errors/custom-404.html',
  }),
);
```

**Why use this?**
This mimics how professional web servers (like Apache2) work. It ensures that if an API call or a page load fails, the user sees a beautiful, branded error page instead of a generic browser error.

### Inspecting the Router State

```javascript
// Returns a deep clone of the config for a specific code (or undefined)
const cfg = engine.getRouterCode(404);

// Returns the effective config used at runtime (custom code, then default, then 500 fallback)
const resolved = engine.getCodeCfg(404);

// Removes a custom code handler
engine.removeRouterCode(404);
```

### Global Messages and SPA Mode

The engine keeps a `globalMsgCode` object that stores the default paths and messages for `200`, `404`, and `500`, plus the `spaPath` (default: `/index.html`).

```javascript
// Read the current global messages (deep clone)
const messages = engine.globalMsgCode;

// Patch the global messages (shallow merge, then deep clone)
engine.updateGlobalMsgCode({ 404: { path: '/errors/not-found.html' } });

// Toggle SPA mode at runtime
engine.spaMode = true;
```

---

## 🔔 Feature 4: Push & Notifications

The engine provides built-in support for the Web Push API and user interaction with browser notifications.

### 📡 Push Events
When a push event is received from the server, the engine automates the following workflow:
1.  **Data Parsing:** It attempts to parse the payload as JSON. If parsing fails, it falls back to a text format.
2.  **Internal Event:** It emits a `push` event, allowing plugins to react to the incoming data.
3.  **Client Broadcast:** It automatically broadcasts a `sw:PushReceived` message to all open browser tabs/clients via `postMessage`. This allows your website's main thread to react to the push event in real-time.

### 🖱️ Notification Interaction
The engine listens for `notificationclick` events. When a user interacts with a notification:
1.  **Event Emission:** The engine emits a `notificationclick` event for internal handling.
2.  **Automatic Cleanup:** The engine automatically calls `event.notification.close()` to dismiss the notification from the user's screen.

### 🔕 Notification Close
When a notification is dismissed by the user (either by clicking the close button or by the system), the engine emits a `notificationclose` event. The same event is emitted when the browser forwards a `sw:NotificationClosed` message to the Service Worker.

```javascript
engine.on('notificationclose', ({ event }) => {
  console.log('Notification closed:', event);
});
```

### 🔁 Subscription Change
The browser fires a `pushsubscriptionchange` event when the push service rotates the subscription endpoint. Without a handler, the user would silently stop receiving pushes. The engine:
1.  **Emits the event:** `pushsubscriptionchange` is emitted so your code can persist the new subscription.
2.  **Broadcasts a message:** A `sw:PushSubscriptionChange` message is sent to every open client, allowing the main thread to re-sync the subscription with your backend.

```javascript
engine.on('pushsubscriptionchange', ({ event }) => {
  // Persist the new subscription on your backend.
});
```

### 🛠️ Manual Notifications
You can trigger a native browser notification directly from the Service Worker using the `showNotification` method.

```javascript
// Triggering a manual notification
await engine.showNotification('New Message', 'You have received a new notification!', {
  icon: '/icons/icon-192x192.png',
  badge: '/icons/badge-72x72.png'
});
```
*Note: This method will throw an error if `push.enabled` is set to `false` in the configuration.*

---

## 🔄 Feature 5: Background Sync

The engine provides built-in support for the **Background Sync API**. This allows your application to defer tasks (like sending analytics or syncing data) until the user has a stable internet connection.

When a `sync` event is triggered by the browser, the engine:
1. **Identifies the Task:** It uses the `tag` from the `SyncEvent` to find the specific callback registered for that tag.
2. **Lifecycle Emission:** It emits `beforeSync` and `afterSync` events.
3. **Error Handling:** If the callback fails, it emits a `syncError` event.

### 🛠️ Implementation Example

```javascript
// Register a handler for a specific sync tag
engine.addSyncListener('sync-analytics', async ({ event, tag }) => {
  console.log(`Syncing analytics for tag: ${tag}`);
  // Perform the sync logic...
  await performAnalyticsSync();
});
```

---

## 🔌 Feature 6: The API System (Bidirectional RPC)

While the **Messaging System** is fire-and-forget, the **API System** implements a request/response (RPC) pattern between the Service Worker and a specific client. It uses a `correlationId` to match each response to its original request.

### 🛠️ Registering a Handler (`onApi`)

The handler receives an `ApiHandlerOptions` object and its **return value** (or the resolved value of the returned Promise) is automatically sent back to the caller.

```javascript
engine.onApi('GET_CACHED_USER', async ({ data, clientId, replyApi }) => {
  // 'data' is the payload sent by the browser
  // 'clientId' identifies the tab that made the call
  // 'replyApi' lets you call back into the browser and await a response
  const token = await replyApi('REQUEST_USER_TOKEN', { scope: 'profile' }, 5000);

  return { id: data.id, name: 'Yasmin', token };
});
```

### 📤 Calling a Client from the Service Worker (`emitApi`)

```javascript
const client = await sw.clients.get(clientId);

// Sends 'REQUEST_USER_TOKEN' to the client and waits up to 5s for a response
const response = await engine.emitApi(client, 'REQUEST_USER_TOKEN', { scope: 'profile' }, 5000);
```

### 🗑️ Removing a Handler (`offApi`)

```javascript
engine.offApi('GET_CACHED_USER');
```

### ⏱️ Timeout Behavior

If the client does not respond within the timeout window (default: `10000` ms), the returned Promise rejects with an `Error` whose message is `API timeout: <type>`. The pending request is then discarded from the internal `#pendingRequests` map.

---

## ♻️ Feature 7: Lifecycle Management

The engine exposes the `install` and `activate` phases through a configurable strategy system. Each phase has two independent settings:

- **Strategy** (`installStrategy` / `activateStrategy`): *what* the engine does with the phase.
- **Order** (`installOrder` / `activateOrder`): *when* the strategy runs relative to your registered listeners.

### 🎯 Strategies

| Value | `install` phase | `activate` phase |
| :--- | :--- | :--- |
| `'immediate'` *(default)* | Calls `skipWaiting()` right away. | Calls `clients.claim()` right away. |
| `'wait'` | Never calls `skipWaiting()`. The new worker stays in the `waiting` state until every tab is closed. | Never calls `clients.claim()`. Only future navigations are controlled. |
| `'manual'` | Does not call `skipWaiting()`. Emits `waitingForActivation` and lets the app decide. | Does not call `clients.claim()`. Emits `waitingForClaim` and lets the app decide. |

### 🔀 Order

| Value | Behavior |
| :--- | :--- |
| `'after'` *(default)* | Listeners run first, then the strategy is resolved. |
| `'before'` | The strategy is resolved first, then the listeners run. |

The `'before'` order is useful when a migration routine must run **before** the new worker takes control of the open tabs. The `'after'` order is the safe default: your listeners always run against a fully initialized worker.

### 🛠️ Configuration

```javascript
const engine = new TinyServiceWorkerEngine({
  lifecycle: {
    installStrategy: 'manual',
    activateStrategy: 'manual',
    installOrder: 'after',
    activateOrder: 'after',
  },
});

engine.init();
```

You can also patch the lifecycle configuration at runtime:

```javascript
// Partial patch: omitted keys keep their current value.
engine.lifecycle = { installOrder: 'before' };

// Read a deep clone of the current lifecycle configuration.
const { installStrategy } = engine.lifecycle;
```

### 🖐️ Manual Activation

When a strategy is set to `'manual'`, the engine emits an event and waits. You can then promote the worker on demand:

```javascript
// Service Worker context
engine.on('waitingForActivation', () => {
  // Notify every open tab that a new version is ready.
  TinyServiceWorkerEngine.replyToAll({ type: 'app:UpdateReady' });
});
```

```javascript
// Page context
navigator.serviceWorker.addEventListener('message', (event) => {
  if (event.data?.type === 'app:UpdateReady') {
    navigator.serviceWorker.getRegistration().then((reg) => {
      // The engine listens for this message and calls skipWaiting() for you.
      reg.waiting?.postMessage({ type: 'sw:SkipWaiting' });
    });
  }
});
```

### 🧩 Registering Lifecycle Listeners

```javascript
engine.addInstallListener('warm-cache', async ({ event }) => {
  const cache = await caches.open('v2');
  await cache.addAll(['/offline.html']);
});

engine.addActivateListener('cleanup', async ({ event }) => {
  const keys = await caches.keys();
  await Promise.all(keys.filter((key) => key !== 'v2').map((key) => caches.delete(key)));
});
```

A listener that throws is logged and emitted as `installListenerError` or `activateListenerError`. It never blocks the Service Worker lifecycle.

### 🔄 Forcing a Client Reload

When the new worker changes the routing contract, the open tabs must be reloaded to stay consistent. Use `reloadClients` to navigate every controlled client at once:

```javascript
await engine.reloadClients(); // Reloads the current URL of each client
await engine.reloadClients('/'); // Or navigate them all to a specific URL
```

---

## 🧰 Static Utilities

These static methods are exposed on the class itself and can be used without instantiating the engine.

| Method | Description |
| :--- | :--- |
| `TinyServiceWorkerEngine.isNavigate(req)` | Returns `true` if the request mode is `'navigate'`. |
| `TinyServiceWorkerEngine.isSameOrigin(data)` | Returns `true` if the given `Request` or `URL` shares the Service Worker's origin. |
| `TinyServiceWorkerEngine.replyTemplate(type, payload)` | Formats a message into the standard `MessagingData` shape. Throws if `type` starts with `sw:`. |
| `TinyServiceWorkerEngine.replyTo(client, type, payload)` | Sends a message to a single `Client`. |
| `TinyServiceWorkerEngine.replyToAll({ type, data, options })` | Broadcasts a message to all matching clients. |

### Reserved Event Types

Any message type that starts with the `sw:` prefix is **reserved** for internal PWA lifecycle management. Passing such a type to `replyTemplate` or `replyTo` will throw a `TypeError`.

The engine uses the following internal types:

| Type | Direction | Description |
| :--- | :--- | :--- |
| `sw:ApiResponse` | Browser → SW | Carries the response of an `emitApi` call. |
| `sw:NotificationClicked` | Browser → SW | Forwards a notification click to the engine. |
| `sw:NotificationClosed` | Browser → SW | Forwards a notification close to the engine. |
| `sw:PrepareUpdate` | Browser → SW | Asks the engine to fetch and install a new version. |
| `sw:Updated` | SW → Browser | The update finished and the new worker is waiting. |
| `sw:UpdateError` | SW → Browser | The update failed. |
| `sw:SkipWaiting` | Browser → SW | Promotes the waiting worker to active. |
| `sw:PushReceived` | SW → Browser | A push event was received. |
| `sw:PushSubscriptionChange` | SW → Browser | The push subscription changed and must be re-synced. |

---

## ⚙️ Configuration & Security

### Strict Validation
The engine is designed with "Fail Fast" principles. If you pass an incorrect type (e.g., passing a `string` where a `boolean` is expected in the config), the engine will throw a `TypeError` immediately.

**Why?**
In Service Workers, debugging is notoriously difficult because they run in the background. By throwing errors during initialization, we catch configuration mistakes immediately during development.

### SPA Mode
If `spaMode` is set to `true`, the engine adjusts how paths are calculated. This is essential for frameworks like React, Vue, or Angular where the routing is handled on the client side.

---

## 📝 API Reference Summary

To make navigation easier, the API is divided into functional modules: **Fetch Management**, **Messaging**, **Router Management**, **API (RPC)**, and **Lifecycle & State**.

### 🌐 1. Fetch Management

| Method | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| **Registration** | | | |
| `addFetchUrlListener` | Registers an exact or parameterized URL match. | `type (string)`, `callback` | `void` |
| `addFetchRegExpListener` | Registers a pattern match via Regex. | `type (string)`, `callback` | `void` |
| `addFetchGlobalListener` | Registers a listener for every request. | `type (string)`, `callback` | `void` |
| **Retrieval & Check** | | | |
| `getFetchUrlListener` | Retrieves a specific URL listener. | `type (string)` | `callback \| undefined` |
| `getFetchRegExpListener` | Retrieves a specific RegExp listener. | `type (string)` | `callback \| undefined` |
| `getFetchGlobalListener` | Retrieves a specific global listener. | `type (string)` | `callback \| undefined` |
| `hasFetchUrl` | Checks if a URL listener exists. | `type (string)` | `boolean` |
| `hasFetchRegExp` | Checks if a RegExp listener exists. | `type (string)` | `boolean` |
| `hasFetchGlobal` | Checks if a global listener exists. | `type (string)` | `boolean` |
| **Removal & Cleanup** | | | |
| `removeFetchUrlListener` | Removes a specific URL listener. | `type (string)` | `boolean` |
| `removeFetchRegExpListener` | Removes a specific RegExp listener. | `type (string)` | `boolean` |
| `removeFetchGlobalListener` | Removes a specific global listener. | `type (string)` | `boolean` |
| `clearFetchUrls` | Wipes all registered URL listeners. | None | `void` |
| `clearFetchRegExps` | Wipes all registered RegExp listeners. | None | `void` |
| `clearFetchGlobals` | Wipes all registered global listeners. | None | `void` |
| **Metadata** | | | |
| `fetchUrlSize` | Returns the count of URL listeners. | None | `number` |
| `fetchRegExpSize` | Returns the count of RegExp listeners. | None | `number` |
| `fetchGlobalSize` | Returns the count of global listeners. | None | `number` |

### 💬 2. Message Management

| Method | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| **Registration** | | | |
| `addMessageListener` | Registers a listener for a message type. | `type (string)`, `callback` | `void` |
| **Retrieval & Check** | | | |
| `getMessageListener` | Retrieves a specific message listener. | `type (string)` | `callback \| undefined` |
| `hasMessageListener` | Checks if a message listener exists. | `type (string)` | `boolean` |
| **Removal & Cleanup** | | | |
| `removeMessageListener` | Removes a specific message listener. | `type (string)` | `boolean` |
| `clearMessageListeners` | Wipes all registered message listeners. | None | `void` |
| **Event Blacklist** | | | |
| `addToEventBlacklist` | Ignores every incoming event with the given name. | `type (string)` | `void` |
| `removeFromEventBlacklist` | Removes an event name from the blacklist. | `type (string)` | `boolean` |
| `hasInEventBlacklist` | Checks whether an event name is blacklisted. | `type (string)` | `boolean` |
| `clearEventBlacklist` | Wipes the entire blacklist. | None | `void` |
| `eventBlacklist` | Returns a copy of every blacklisted event name. | None | `string[]` |
| **Metadata** | | | |
| `messagesSize` | Returns the count of message listeners. | None | `number` |

### 🔌 3. API (RPC) Management

| Method | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| `onApi` | Registers a handler for API calls coming from the browser. | `type (string)`, `callback` | `void` |
| `offApi` | Removes a registered API handler. | `type (string)` | `boolean` |
| `emitApi` | Sends a request to a specific client and waits for a response. | `client (Client)`, `type (string)`, `data (any)`, `timeout (number)` | `Promise<any>` |

### 🚦 4. Router Management

| Method | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| `addRouterCode` | Adds/updates a custom handler for a code. | `code (number)`, `config (RouterCodeConfig)` | `void` |
| `removeRouterCode` | Removes a custom code handler. | `code (number)` | `boolean` |
| `getRouterCode` | Retrieves a deep clone of a code config. | `code (number)` | `RouterCodeConfig \| undefined` |
| `getCodeCfg` | Resolves the effective config for a code (custom → default → 500). | `code (number)` | `RouterCodeConfig` |
| `updateGlobalMsgCode` | Merges a partial patch into the global message map. | `patch (Partial<GlobalMsgCode>)` | `void` |
| `createFetchRes` | Builds a `RouterCodeConfig` from a `pathGetter`. | `{ isError, msg, logMsg, pathGetter }` | `RouterCodeConfig` |
| `globalPathGetter` | Returns the SPA path or the original path. | `path (string)` | `string` |

### 🔄 5. Sync Management

| Method | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| **Registration** | | | |
| `addSyncListener` | Registers a handler for a specific sync tag. | `tag (string)`, `callback` | `void` |
| **Retrieval & Check** | | | |
| `syncListenerSize` | Returns the count of registered sync listeners. | None | `number` |
| **Removal & Cleanup** | | | |
| `removeSyncListener` | Removes a sync handler. | `tag (string)` | `boolean` |
| `clearSyncListeners` | Wipes all registered sync listeners. | None | `void` |

### ⚙️ 6. Lifecycle, State & Utility

| Method / Property | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| `init` | Initializes the Service Worker event listeners. | None | `void` |
| `started` | Whether `init()` has already been called. | None | `boolean` |
| `spaMode` | Gets/sets SPA mode at runtime. | `boolean` | `boolean` |
| `config` | Gets a deep clone of the config / applies a partial update. | `Partial<PartialServiceWorkerSettings>` | `ServiceWorkerSettings` |
| `globalMsgCode` | Gets/sets the global message map. | `Object` | `Object` |
| `showNotification` | Displays a native notification to the user. | `title (string)`, `body (string)`, `options (Object)` | `Promise<void>` |

### ♻️ 7. Lifecycle Management

| Method / Property | Purpose | Arguments | Returns |
| :--- | :--- | :--- | :--- |
| `lifecycle` | Gets a deep clone / merges a partial lifecycle config. | `Partial<LifecycleOptions>` | `LifecycleOptions` |
| `skipWaiting` | Promotes the waiting worker to active. | `event? (ExtendableEvent)` | `Promise<boolean>` |
| `claimClients` | Makes the active worker control the open clients. | `query? (ClientQueryOptions)` | `Promise<readonly Client[]>` |
| `reloadClients` | Navigates every controlled client to a URL. | `url? (string)` | `Promise<number>` |
| **Install Listeners** | | | |
| `addInstallListener` | Registers an `install` listener. | `tag (string)`, `callback` | `void` |
| `removeInstallListener` | Removes an `install` listener. | `tag (string)` | `boolean` |
| `getInstallListener` | Retrieves an `install` listener. | `tag (string)` | `callback \| undefined` |
| `hasInstallListener` | Checks if an `install` listener exists. | `tag (string)` | `boolean` |
| `clearInstallListeners` | Wipes all `install` listeners. | None | `void` |
| `installListenerSize` | Returns the count of `install` listeners. | None | `number` |
| **Activate Listeners** | | | |
| `addActivateListener` | Registers an `activate` listener. | `tag (string)`, `callback` | `void` |
| `removeActivateListener` | Removes an `activate` listener. | `tag (string)` | `boolean` |
| `getActivateListener` | Retrieves an `activate` listener. | `tag (string)` | `callback \| undefined` |
| `hasActivateListener` | Checks if an `activate` listener exists. | `tag (string)` | `boolean` |
| `clearActivateListeners` | Wipes all `activate` listeners. | None | `void` |
| `activateListenerSize` | Returns the count of `activate` listeners. | None | `number` |

---

## 🔗 Full PWA Integration (Client-Side)

To achieve a complete and seamless Progressive Web App (PWA) experience, it is highly recommended to use the `TinyServiceWorkerEngine` in conjunction with our dedicated client-side module.

While the `TinyServiceWorkerEngine` manages the background logic and network interception within the **Service Worker context**, the **`TinyServiceWorker`** module provides the necessary interface to interact with the engine from your **Main Thread (the browser window)**.

### 📍 Recommended Next Step
To learn how to communicate with the engine from your web application, please refer to the integration guide here:
👉 [TinyServiceWorker](../browser/TinyServiceWorker.md)

**Why integrate both?**
Using both modules allows you to fully leverage the **Messaging System**. This enables your website to:
1.  **Listen** to events triggered by the Service Worker.
2.  **Trigger** updates and lifecycle events.
3.  **Exchange data** between the background process and the user interface in real-time.

---

## 🧩 TinyPlugin Ecosystem Integration

`TinyServiceWorker` is not a standalone utility; it is a first-class citizen of the **[TinyPlugin](../../plugin/TinyPlugin.md)** architecture.