@hotfusion/modeller 0.0.7 → 0.0.8

package/README.md

@@ -1,71 +1,835 @@
 # @hotfusion/modeller
 
-A schema-first data layer for Node.js, built as a three-layer chain:
+A schema-first, all-in-one backend framework for Node.js. Define your data model once and get validation, persistence, business logic, HTTP API, real-time WebSocket, authentication, file uploads, background workers, and static file serving — all wired up automatically.
 
+Think of it as the Node.js equivalent of IIS or Apache, but built for modern data-driven applications. Where a traditional web server just routes requests, **modeller** understands your data: it knows its shape, enforces its rules, exposes it safely over the network, and reacts to changes in real time.
+
+---
+
+### What problem does it solve?
+
+Building a production backend typically means stitching together a dozen separate libraries: a validation library, an ORM, an HTTP framework, a WebSocket server, an auth layer, a job scheduler, a file upload handler, and more. Each has its own config, its own conventions, and its own failure modes. Keeping them consistent as your app grows is where most of the complexity lives.
+
+**modeller** collapses that stack into a single, coherent package:
+
+- **One schema** drives validation, CRUD, API shape, and documentation — no duplication.
+- **One model** handles your business logic: hooks that fire before/after operations, background workers, custom methods, event subscriptions, and file processing.
+- **One server** exposes everything over HTTP and WebSocket automatically. Register a model and your REST API, real-time events, and file upload endpoints exist immediately — no route boilerplate.
+- **One connector** gives the client a typed interface to the entire backend without writing a single fetch call by hand.
+
+---
+
+### What makes it different?
+
+**Fast deployment.** A fully functional API server with real-time support, auth, sessions, file uploads, and static file serving can be up in under 50 lines of code. No scaffolding, no generators, no config files.
+
+**Security by default.** Sessions are signed and encrypted. Private schema fields are stripped from all public responses automatically. Protected routes verify JWTs out of the box. OIDC/OAuth provider support is built in. Chunked file uploads use per-upload IDs with server-side ack and timeout protection.
+
+**Real-time built in.** Every model can publish events to WebSocket subscribers scoped to a query. Clients subscribe to a slice of data, dispatch typed events, and receive live updates — with no extra infrastructure.
+
+**Schema-first, not code-first.** Your JSON Schema definition is the single source of truth. It drives runtime validation, unique index enforcement, default values, private field filtering, and the metadata endpoint that powers the client connector — all from the same object.
+
+**Layered and composable.** Use only what you need. The `Core` layer is a standalone schema-validated CRUD store. The `Model` layer adds behavior on top. The `Server` layer adds transport. Each layer is independently usable and testable.
+
+Each layer is usable independently. Start with `Model` for most apps.
+
+---
+
+## Installation
+
+```bash
+npm install @hotfusion/modeller
 ```
-┌──────────────┐   data primitives — schema, validation, CRUD,
-│   core.ts    │   indexes, persistence adapter, trash
-└──────┬───────┘
-       │ extends
-┌──────▼───────┐   behavior — hooks, workers, methods, uploads,
-│   model.ts   │   streams, events, subscriptions, logging
-└──────┬───────┘
-       │ consumed by
-┌──────▼───────┐   transport — HTTP + WebSocket exposure of any model
-│  server.ts   │   (auth, sessions, socket fan-out)
-└──────────────┘
+
+---
+
+## Quick Start
+
+```ts
+import { Model, Server } from '@hotfusion/modeller';
+
+const users = new Model('users', {
+  type: 'object',
+  required: ['email'],
+  properties: {
+    email    : { type: 'string', format: 'email', unique: true },
+    name     : { type: 'string' },
+    password : { type: 'string', private: true },
+    role     : { type: 'string', enum: ['user', 'admin'], default: 'user' }
+  }
+});
+
+users.hook({
+  id: 'normalize-email',
+  on: 'before:insert',
+  callback: ({ data }) => { data.email = data.email.toLowerCase(); }
+});
+
+await users.insert({ email: 'alex@example.com', name: 'Alex' });
+
+const server = new Server(3030);
+server.registerModel('system', 'users', users);
+await server.start();
 ```
 
-Each layer is usable on its own. Pick the layer that matches the problem you're solving.
+---
+
+## Table of Contents
+
+- [Model](#model)
+    - [Schema](#schema)
+    - [CRUD](#crud)
+    - [Hooks](#hooks)
+    - [Workers](#workers)
+    - [Methods](#methods)
+    - [Functions](#functions)
+    - [Events & Subscriptions](#events--subscriptions)
+    - [Uploads](#uploads)
+    - [Streams](#streams)
+    - [Configurations](#configurations)
+    - [Extensions](#extensions)
+    - [Views](#views)
+    - [Folders](#folders)
+    - [Logging](#logging)
+- [Server](#server)
+    - [Registering Models](#registering-models)
+    - [Static Folders](#static-folders)
+    - [Custom Routes](#custom-routes)
+    - [Extensions](#server-extensions)
+    - [Auth](#auth)
+    - [WebSocket Subscriptions](#websocket-subscriptions)
+    - [File Uploads](#file-uploads)
+- [Connector](#connector)
+    - [Connecting](#connecting)
+    - [CRUD Operations](#crud-operations)
+    - [Custom Methods](#custom-methods)
+    - [Subscriptions](#subscriptions)
+    - [Authentication](#authentication)
+    - [File Uploads](#file-uploads-1)
+
+---
+
+## Model
+
+### Schema
+
+The schema follows JSON Schema with extra modeller-specific keywords (`unique`, `private`, `default`).
 
 ```ts
-import { Adapter, Model, Server, Bundler, KeyGen } from '@hotfusion/modeller';
+const products = new Model('products', {
+  type: 'object',
+  required: ['name', 'price'],
+  properties: {
+    name     : { type: 'string' },
+    price    : { type: 'number', minimum: 0 },
+    sku      : { type: 'string', unique: true },
+    internal : { type: 'string', private: true }, // excluded from public responses
+    status   : { type: 'string', enum: ['active', 'draft'], default: 'draft' }
+  }
+});
 ```
 
 ---
 
-## Quick Start
+### CRUD
+
+All CRUD methods are async and available directly on the model instance.
 
 ```ts
-import { Model } from '@hotfusion/modeller';
+// Insert
+const user = await users.insert({ email: 'alex@example.com', name: 'Alex' });
 
-const users = new Model('users', {
+// Get by query
+const found = await users.get({ email: 'alex@example.com' });
+
+// List with pagination
+const page = await users.list({ role: 'admin' }, { start: 0, count: 20 });
+
+// Find (returns array, no pagination)
+const admins = await users.find({ role: 'admin' });
+
+// Update
+await users.update({ _id: user._id }, { name: 'Alexander' });
+
+// Delete
+await users.delete({ _id: user._id });
+```
+
+---
+
+### Hooks
+
+Hooks run before or after CRUD operations. They are async and can mutate the payload.
+
+**Available events:** `before:insert` · `after:insert` · `before:update` · `after:update` · `before:delete` · `after:delete` · `before:list` · `after:list`
+
+```ts
+// Mutate data before insert
+users.hook({
+  id: 'hash-password',
+  on: 'before:insert',
+  callback: async ({ data }) => {
+    if (data.password)
+      data.password = await bcrypt.hash(data.password, 10);
+  }
+});
+
+// Run after delete with a delay
+users.hook({
+  id: 'cleanup-sessions',
+  on: 'after:delete',
+  schedule: 2000, // runs 2s after the operation
+  callback: ({ key }) => {
+    sessions.delete({ userId: key._id });
+  }
+});
+
+// Listen to multiple events
+users.hook({
+  id: 'audit-log',
+  on: ['before:insert', 'before:update', 'before:delete'],
+  callback: ({ operation, data }) => {
+    console.log(`[audit] ${operation}`, data);
+  }
+});
+
+// Remove a hook at runtime
+users.unhook('audit-log');
+```
+
+---
+
+### Workers
+
+Workers are background tasks that run on a fixed interval.
+
+```ts
+// Named worker — can be started/stopped by id
+users.worker({
+  id       : 'cleanup-expired',
+  interval : 60_000,        // every 60s
+  immediate: true,          // run immediately on start (default: true)
+  handler  : async (model) => {
+    const expired = await model.find({ expiresAt: { $lt: Date.now() } });
+    for (const u of expired) await model.delete({ _id: u._id });
+  }
+});
+
+// Unsigned worker (no id, runs with all workers)
+users.worker({
+  interval: 5000,
+  handler : (model) => console.log('tick')
+});
+
+users.start();              // start all workers
+users.start('cleanup-expired'); // start one by id
+users.stop('cleanup-expired');  // stop one by id
+users.stop();               // stop all
+users.isRunning('cleanup-expired'); // → boolean
+```
+
+---
+
+### Methods
+
+Methods are custom RPC-style handlers exposed over HTTP automatically.
+
+```ts
+users.method({
+  id: 'resetPassword',
+  handler: async ({ email }, model) => {
+    const user = await model.get({ email });
+    if (!user) throw { status: 404, message: 'User not found' };
+    const token = crypto.randomBytes(32).toString('hex');
+    await model.update({ _id: user._id }, { resetToken: token });
+    return { token };
+  }
+});
+
+// Call locally
+const result = await users.call('resetPassword', { email: 'alex@example.com' });
+```
+
+HTTP: `POST /system/users/resetPassword`
+
+---
+
+### Functions
+
+Functions are bound directly to the model instance, useful for shared utilities.
+
+```ts
+users.function('findByEmail', async function(email: string) {
+  return this.get({ email });
+});
+
+// Call on the model instance directly
+const user = await users.findByEmail('alex@example.com');
+```
+
+---
+
+### Events & Subscriptions
+
+Subscriptions are scoped real-time channels. A client subscribes with a query (e.g. `{ roomId: 'abc' }`) and receives any payload the server publishes to that query. Events are named actions the client can dispatch back to the server through the same subscription.
+
+#### Registering events (server)
+
+```ts
+const chat = new Model('chat', schema);
+
+// Register a named event the client can dispatch
+chat.event({
+  id: 'sendMessage',
+  schema: {
     type: 'object',
-    required: ['email'],
+    required: ['text'],
     properties: {
-        email    : { type: 'string', format: 'email', unique: true },
-        name     : { type: 'string' },
-        password : { type: 'string', private: true },
-        role     : { type: 'string', enum: ['user', 'admin'], default: 'user' }
+      text   : { type: 'string' },
+      userId : { type: 'string' }
     }
+  },
+  handler: async ({ text, userId }, model, ctx) => {
+    // Persist the message
+    const message = await model.insert({ text, userId, createdAt: Date.now() });
+
+    // Publish to all clients subscribed to the same roomId
+    const sub = model.subscription({ roomId: ctx.scope });
+    sub.publish({ type: 'message', message });
+
+    return { delivered: true };
+  }
 });
 
-users.hook({
-    id: 'normalize-email',
-    on: 'before:insert',
-    callback: ({ data }) => { data.email = data.email.toLowerCase(); }
+// Register multiple events on the same model
+chat.event({
+  id: 'typing',
+  handler: async ({ userId }, model, ctx) => {
+    model.subscription({ roomId: ctx.scope }).publish({ type: 'typing', userId });
+  }
+});
+```
+
+#### Publishing from anywhere on the server
+
+You can publish to subscribers at any point — inside hooks, workers, methods, or external triggers.
+
+```ts
+// Inside a hook — notify subscribers after every insert
+chat.hook({
+  id: 'broadcast-on-insert',
+  on: 'after:insert',
+  callback: ({ data }) => {
+    chat.subscription({ roomId: data.roomId }).publish({ type: 'new-message', data });
+  }
+});
+
+// Inside a worker — push periodic updates
+chat.worker({
+  id      : 'heartbeat',
+  interval: 10_000,
+  handler : (model) => {
+    model.subscription({}).publish({ type: 'heartbeat', ts: Date.now() });
+  }
+});
+
+// From a custom method — trigger an event in response to an HTTP call
+chat.method({
+  id: 'closeRoom',
+  handler: async ({ roomId }, model) => {
+    await model.delete({ roomId });
+    model.subscription({ roomId }).publish({ type: 'room-closed', roomId });
+    return { ok: true };
+  }
+});
+```
+
+---
+
+### Uploads
+
+Register a handler for multipart file uploads.
+
+```ts
+users.upload({
+  id: 'avatar',
+  handler: async (file: Buffer, fields, model) => {
+    const filename = `${Date.now()}.jpg`;
+    fs.writeFileSync(`./uploads/${filename}`, file);
+    await model.update({ _id: fields._id }, { avatar: filename });
+    return { filename };
+  }
+});
+```
+
+HTTP: `POST /system/users/avatar` (multipart/form-data)
+
+---
+
+### Streams
+
+Register a handler for chunked binary uploads over WebSocket.
+
+```ts
+users.stream({
+  id: 'video',
+  handler: async (buffer: Buffer, meta) => {
+    fs.writeFileSync(`./uploads/${meta.filename}`, buffer);
+    return { path: meta.filename };
+  }
+});
+```
+
+---
+
+### Configurations
+
+Store and retrieve key/value configuration on the model.
+
+```ts
+users.configurations({
+  maxLoginAttempts : 5,
+  sessionTtl       : 3600
 });
 
-await users.insert({ email: 'alex@hotfusion.ca', name: 'Alex' });
+// Or lazily
+users.configurations(() => ({
+  secret: process.env.JWT_SECRET
+}));
+
+users.getConfiguration('maxLoginAttempts'); // → 5
+users.setConfiguration('maxLoginAttempts', 10);
+users.getConfigurations(); // → { maxLoginAttempts: 10, ... }
 ```
 
 ---
 
-## Documentation
+### Extensions
+
+Attach sub-models as extensions. They inherit their own scoped routes automatically.
+
+```ts
+const posts = new Model('posts', { ... });
+
+const users = new Model('users', schema, {
+  extensions: [posts]
+});
+
+// Access extension on the model
+users.posts.insert({ title: 'Hello' });
+users.getExtensions(); // → [posts]
+```
+
+HTTP routes for `posts` are mounted at `/system/users/posts/...`
+
+---
+
+### Views
+
+Serve a bundled Vue SFC as an HTML view.
+
+```ts
+import { Bundler } from '@hotfusion/modeller';
+import path from 'path';
+
+const bundler = new Bundler(path.resolve(__dirname, './view/index.vue'));
+
+const firewall = new Model('firewall', schema, { bundler });
+
+firewall.view('/', { title: 'Firewall Manager' });
+```
+
+The view is compiled once on startup, cached, and rebuilt automatically when the source file changes.
+
+HTTP: `GET /system/firewall/`
+
+---
+
+### Folders
+
+Serve a local directory as static files.
+
+```ts
+firewall.folder('/assets/fonts', path.resolve(__dirname, '../fonts'));
+```
+
+HTTP: `GET /assets/fonts/...` → serves files from the given directory.
 
-| Section                              | Covers                                                                |
-|--------------------------------------|-----------------------------------------------------------------------|
-| [Core layer](./docs/CORE.md)         | Schema, validator, CRUD primitives, indexes, adapter, trash.          |
-| [Model layer](./docs/MODEL.md)       | Hooks, workers, methods, uploads, streams, events, subscriptions, logging, extensions. |
-| [Server layer](./docs/SERVER.md)     | HTTP + WebSocket transport, auth, server events, public API.          |
-| [Utilities](./docs/UTILITIES.md)     | `Bundler`, `KeyGen`, `Adapter`, encryption, JWT helpers.              |
-| [Errors](./docs/ERRORS.md)           | Error codes thrown by the framework.                                  |
-| [Common patterns](./docs/PATTERNS.md)| Recipes for publish-on-update, FK validation, extensions, workers.    |
+Throws immediately at startup if the path does not exist.
 
-Start with **Model** if you're building an app. Drop down to **Core** when you need to understand schema or persistence semantics. Read **Server** when you're ready to expose models over the network.
+---
+
+### Logging
+
+Every model has a built-in structured logger. Log level is `silent` by default.
+
+```ts
+const users = new Model('users', schema, {
+  level    : 'info',          // 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  timestamp: true,
+  features : {
+    hook   : true,
+    worker : true,
+    method : true,
+    event  : true,
+    crud   : false,           // suppress CRUD logs
+  },
+  onEntry: (entry) => {
+    // entry: { level, feature, modelId, message, timestamp, callSite?, data? }
+    myLogService.write(entry);
+  }
+});
+
+// Use inside methods, hooks, workers
+users.method({
+  id: 'doSomething',
+  handler: async (args, model) => {
+    model.log.info('method', 'Doing something', { args });
+  }
+});
+```
+
+You can also plug in a custom adapter:
+
+```ts
+const users = new Model('users', schema, {
+  logAdapter: {
+    log: (entry) => sentryCapture(entry)
+  }
+});
+```
+
+---
+
+## Server
+
+### Registering Models
+
+```ts
+import { Server } from '@hotfusion/modeller';
+
+const server = new Server(3030, {
+  secret: process.env.SECRET,
+  domain: 'myapp.com'
+});
+
+server.registerModel('system', 'users',    users);
+server.registerModel('system', 'products', products);
+
+await server.start();
+```
+
+All CRUD, methods, uploads, views, and folders registered on each model are mounted automatically.
+
+**Auto-generated routes for each model:**
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| insert    | POST   | `/:id/:scope/insert` |
+| update    | PUT    | `/:id/:scope/update` |
+| delete    | DELETE | `/:id/:scope/delete` |
+| get       | GET    | `/:id/:scope/get` |
+| list      | GET    | `/:id/:scope/list` |
+| find      | POST   | `/:id/:scope/find` |
+
+Metadata for all registered models is available at `GET /@metadata`.
+
+---
+
+### Static Folders
+
+Declared on the model via `.folder()` — see [Folders](#folders) above. The folder is served globally (not scoped to the model path).
+
+---
+
+### Custom Routes
+
+```ts
+server.route({
+  method   : 'get',
+  path     : '/health',
+  callback : async (ctx) => ({ status: 'ok' })
+});
+
+server.route({
+  method    : 'get',
+  path      : '/admin/stats',
+  protected : true,           // requires Authorization: Bearer <token>
+  callback  : async (ctx) => ({ users: await users.list() })
+});
+```
+
+---
+
+### Server Extensions
+
+Extensions hook into the server setup lifecycle.
+
+```ts
+const oidcExtension = {
+  id: 'oidc',
+  setup(server, config) {
+    server.router.get('/auth/callback', async (ctx) => {
+      // handle callback
+    });
+  }
+};
+
+server.registerExtension(oidcExtension);
+server.setOIDCProviders('auth', [
+  { id: 'google', clientId: '...', clientSecret: '...' }
+]);
+```
+
+---
+
+### Auth
+
+```ts
+server.setOIDCProviders('auth', providers);
+```
+
+Protected routes verify a JWT `Authorization: Bearer <token>` header. The decoded payload is available as `ctx.token`.
+
+---
+
+### WebSocket Subscriptions
+
+Handled automatically for any model that has `.event()` registered. Clients use the [Connector](#connector) to subscribe.
+
+---
+
+### File Uploads
+
+Multipart uploads are handled automatically for any model with `.upload()` registered.
+
+Chunked binary streaming over WebSocket is handled automatically for any model with `.stream()` registered.
+
+---
+
+## Connector
+
+The `Connector` is the client-side counterpart — it connects to a running server over HTTP + WebSocket and exposes a typed interface to all model operations.
+
+### Connecting
+
+```ts
+import { Connector } from '@hotfusion/modeller';
+
+const connector = new Connector('http://localhost:3030');
+await connector.connect();
+```
+
+---
+
+### CRUD Operations
+
+```ts
+// Generic operation by path (auto-detects method from metadata)
+const users = await connector.operation('system/users/list');
+const user  = await connector.operation('system/users/insert', { email: 'alex@example.com' });
+
+// Raw HTTP
+await connector.get('system/users/list');
+await connector.post('system/users/insert', { email: 'alex@example.com' });
+```
+
+---
+
+### Custom Methods
+
+```ts
+const result = await connector.operation('system/users/resetPassword', {
+  email: 'alex@example.com'
+});
+```
+
+---
+
+### Subscriptions
+
+Subscriptions connect the client to a scoped real-time channel. The query you pass acts as the scope — only payloads published to the same query reach your listener.
+
+#### Basic subscribe and receive
+
+```ts
+const connector = new Connector('http://localhost:3030');
+await connector.connect();
+
+const { proxy } = await connector.subscribe(
+  'system',           // model id
+  'chat',             // scope
+  { roomId: 'abc' },  // query — scopes this subscription to room abc
+  (payload) => {
+    // Called every time the server publishes to { roomId: 'abc' }
+    console.log('received:', payload);
+
+    if (payload.type === 'message') {
+      appendMessage(payload.message);
+    }
+
+    if (payload.type === 'typing') {
+      showTypingIndicator(payload.userId);
+    }
+  }
+);
+```
+
+#### Dispatching events back to the server
+
+`proxy` contains one method per registered event. Calling it sends the event to the server over the same WebSocket and waits for the handler's return value.
+
+```ts
+// Send a message — calls the 'sendMessage' event handler on the server
+const result = await proxy.sendMessage({ text: 'Hello!', userId: 'u1' });
+console.log(result); // → { delivered: true }
+
+// Notify others you're typing
+await proxy.typing({ userId: 'u1' });
+```
+
+#### Full chat example (client)
+
+```ts
+const connector = new Connector('http://localhost:3030');
+await connector.connect();
+
+const messages = [];
+
+const { proxy } = await connector.subscribe(
+  'system',
+  'chat',
+  { roomId: 'room-42' },
+  (payload) => {
+    if (payload.type === 'message') {
+      messages.push(payload.message);
+      renderMessages(messages);
+    }
+
+    if (payload.type === 'room-closed') {
+      alert('This room has been closed.');
+      connector.unsubscribe('system', 'chat', { roomId: 'room-42' });
+    }
+  }
+);
+
+// User sends a message
+sendButton.addEventListener('click', async () => {
+  await proxy.sendMessage({ text: input.value, userId: currentUser._id });
+  input.value = '';
+});
+
+// User is typing
+input.addEventListener('input', () => {
+  proxy.typing({ userId: currentUser._id });
+});
+```
+
+#### Unsubscribing
+
+```ts
+// Remove the listener and tell the server to stop tracking this subscription
+connector.unsubscribe('system', 'chat', { roomId: 'room-42' });
+
+// Or unsubscribe a specific listener function
+connector.unsubscribe('system', 'chat', { roomId: 'room-42' }, myListener);
+```
+
+Subscriptions are also cleaned up automatically on socket disconnect.
+
+---
+
+### Authentication
+
+```ts
+// Credential login
+const token = await connector.authenticate('alex@example.com', 'password');
+
+// OIDC / OAuth (opens a popup)
+await connector.authorize('google');
+```
+
+---
+
+### File Uploads
+
+Files are detected automatically inside any operation payload — just pass a `{ source: File }` object.
+
+```ts
+// Single file inside a regular operation
+await connector.operation('system/users/avatar', {
+  _id    : user._id,
+  avatar : { source: fileInputRef.files[0] }
+});
+```
+
+#### Chunked streaming with progress
+
+Large files are uploaded in chunks over WebSocket with per-chunk server acknowledgement. Use the `onProgress` callback to track progress on the client.
+
+```ts
+await connector.operation('system/filesystem/upload', { file: { source: myFile } }, {
+  stream: {
+    path      : 'system/filesystem/stream',
+    onProgress: (sent, total, file) => {
+      const percent = Math.round((sent / total) * 100);
+      console.log(`${file.name}: ${percent}%`);
+    }
+  }
+});
+```
+
+`onProgress` receives three arguments: `sent` (chunks acknowledged so far), `total` (total chunk count), and `file` (the original `File` object). It is called once at 0% when the server confirms it is ready, then once per acknowledged chunk.
+
+#### Example: progress bar in the browser
+
+```ts
+const progressBar = document.getElementById('progress');
+
+await connector.operation('system/filesystem/upload', { file: { source: input.files[0] } }, {
+  stream: {
+    path      : 'system/filesystem/stream',
+    onProgress: (sent, total, file) => {
+      const percent = Math.round((sent / total) * 100);
+      progressBar.style.width = `${percent}%`;
+      progressBar.textContent = `${percent}% — ${file.name}`;
+    }
+  }
+});
+
+progressBar.textContent = 'Upload complete';
+```
+
+#### Multiple files
+
+When the payload contains multiple `{ source: File }` fields, each file is streamed sequentially. `onProgress` fires independently for each file.
+
+```ts
+await connector.operation('system/gallery/upload', {
+  thumbnail : { source: files[0] },
+  full      : { source: files[1] }
+}, {
+  stream: {
+    path      : 'system/filesystem/stream',
+    onProgress: (sent, total, file) => {
+      console.log(`Uploading ${file.name}: ${Math.round(sent / total * 100)}%`);
+    }
+  }
+});
+```
+
+#### Resume support
+
+If a chunked upload is interrupted (network drop, page refresh), the connector can resume from the last acknowledged chunk — the server tracks which chunks it has already received per `uploadId`. Resume is handled automatically when you restart the upload with the same session.
+
+```ts
+socket.on('upload:resume', async ({ uploadId }) => {
+  // server replies with fromChunk — the connector picks up from there
+});
+```
 
 ---
 
 ## License
 
-UNLICENSED — internal HotFusion project.
+UNLICENSED — internal HotFusion project.