@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/{references → extensions}/components/static-asset/index.md

@@ -1,6 +1,6 @@
 # Static Asset
 
-> Flexible file management system with support for multiple storage backends (local disk, MinIO/S3-compatible) through a unified interface, featuring factory-based controller generation and optional database file tracking via MetaLink.
+> Flexible file management system with support for multiple storage backends (local disk, MinIO/S3-compatible, Bun S3) through a unified interface, featuring factory-based controller generation and optional database file tracking via MetaLink.
 
 ## Quick Reference
 
@@ -8,23 +8,35 @@
 |------|-------|
 | **Package** | `@venizia/ignis` |
 | **Class** | `StaticAssetComponent` |
-| **Helper** | [`DiskHelper`](/references/helpers/storage/), [`MinioHelper`](/references/helpers/storage/) |
+| **Helper** | [`DiskHelper`](/extensions/helpers/storage/), [`MinioHelper`](/extensions/helpers/storage/), [`BunS3Helper`](/extensions/helpers/storage/) |
 | **Runtimes** | Both |
 
 #### Import Paths
+
+> [!IMPORTANT]
+> `StaticAssetComponent` and its related exports are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/static-asset` subpath.
+
 ```typescript
+// From core -- subpath import (NOT from '@venizia/ignis')
 import {
   StaticAssetComponent,
   StaticAssetComponentBindingKeys,
   StaticAssetStorageTypes,
-} from '@venizia/ignis';
-import { DiskHelper, MinioHelper } from '@venizia/ignis-helpers';
+  AssetControllerFactory,
+  BaseMetaLinkModel,
+  BaseMetaLinkRepository,
+} from '@venizia/ignis/static-asset';
+
+import { DiskHelper } from '@venizia/ignis-helpers';
+import { MinioHelper } from '@venizia/ignis-helpers/minio';
+import { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
+
 import type {
   TStaticAssetsComponentOptions,
   TMetaLinkConfig,
   TStaticAssetExtraOptions,
   TStaticAssetStorageType,
-} from '@venizia/ignis';
+} from '@venizia/ignis/static-asset';
 ```
 
 ### Key Features
@@ -35,7 +47,8 @@ import type {
 | **Multiple Storage Instances** | Configure multiple storage backends simultaneously |
 | **Factory Pattern** | Dynamic controller generation per storage backend |
 | **Built-in Security** | Comprehensive name validation, path traversal protection, header sanitization |
-| **Database Tracking (MetaLink)** | Optional database-backed file tracking with metadata, principal association, and sync status |
+| **Database Tracking (MetaLink)** | Optional database-backed file tracking with metadata, principal association, variant support, and sync status |
+| **Per-Route Configuration** | Override authentication, middleware, and path for individual routes |
 | **Flexible Configuration** | Environment-based, production-ready setup |
 
 ## Setup
@@ -43,13 +56,14 @@ import type {
 ### Step 1: Bind Configuration
 
 ```typescript
+import { BaseApplication } from '@venizia/ignis';
 import {
-  BaseApplication,
   StaticAssetComponentBindingKeys,
   StaticAssetStorageTypes,
-} from '@venizia/ignis';
-import { DiskHelper, MinioHelper } from '@venizia/ignis-helpers';
-import type { TStaticAssetsComponentOptions } from '@venizia/ignis';
+} from '@venizia/ignis/static-asset';
+import { DiskHelper } from '@venizia/ignis-helpers';
+import { MinioHelper } from '@venizia/ignis-helpers/minio';
+import type { TStaticAssetsComponentOptions } from '@venizia/ignis/static-asset';
 
 export class Application extends BaseApplication {
   preConfigure() {
@@ -100,7 +114,7 @@ Each storage backend gets a unique key (`staticAsset`, `staticResource`), its ow
 ### Step 2: Register Component
 
 ```typescript
-import { StaticAssetComponent } from '@venizia/ignis';
+import { StaticAssetComponent } from '@venizia/ignis/static-asset';
 
 export class Application extends BaseApplication {
   preConfigure() {
@@ -186,13 +200,15 @@ Start with `docker-compose up -d` and access the console at `http://localhost:90
 |------|----------|--------|-------------|
 | `'disk'` | `StaticAssetStorageTypes.DISK` | `DiskHelper` | Local filesystem with bucket-based directory structure |
 | `'minio'` | `StaticAssetStorageTypes.MINIO` | `MinioHelper` | S3-compatible object storage (MinIO, AWS S3, etc.) |
+| `'bun-s3'` | `StaticAssetStorageTypes.BUN_S3` | `BunS3Helper` | Bun-native S3 client (requires Bun runtime) |
 
 The `StaticAssetStorageTypes` class provides a `SCHEME_SET` (a `Set` of all valid storage type strings) and an `isValid(orgType)` method for runtime validation:
 
 ```typescript
-StaticAssetStorageTypes.isValid('minio'); // true
-StaticAssetStorageTypes.isValid('s3');    // false
-StaticAssetStorageTypes.SCHEME_SET;       // Set { 'disk', 'minio' }
+StaticAssetStorageTypes.isValid('minio');  // true
+StaticAssetStorageTypes.isValid('bun-s3'); // true
+StaticAssetStorageTypes.isValid('s3');     // false
+StaticAssetStorageTypes.SCHEME_SET;        // Set { 'disk', 'minio', 'bun-s3' }
 ```
 
 ### `TStaticAssetsComponentOptions`
@@ -204,12 +220,37 @@ Each key in the options object defines a separate storage backend with its own c
 | `controller.name` | `string` | -- | Controller class name |
 | `controller.basePath` | `string` | -- | Base URL path (e.g., `'/assets'`) |
 | `controller.isStrict` | `boolean` | `true` | Strict routing mode |
-| `storage` | `'disk' \| 'minio'` | -- | Storage type |
-| `helper` | `DiskHelper \| MinioHelper` | -- | Storage helper instance |
+| `controller.routes` | `object` | `undefined` | Per-route overrides (authenticate, middleware, path) |
+| `storage` | `'disk' \| 'minio' \| 'bun-s3'` | -- | Storage type |
+| `helper` | `DiskHelper \| MinioHelper \| BunS3Helper` | -- | Storage helper instance |
 | `extra` | `TStaticAssetExtraOptions` | `undefined` | Extra options (multipart parsing, name normalization) |
 | `useMetaLink` | `boolean` | `false` | Enable database file tracking |
 | `metaLink` | `TMetaLinkConfig` | -- | MetaLink configuration (required when `useMetaLink: true`) |
 
+#### Per-Route Configuration
+
+Each route can be individually configured with authentication, middleware, and path overrides:
+
+```typescript
+{
+  controller: {
+    name: 'AssetController',
+    basePath: '/assets',
+    routes: {
+      getBuckets: { authenticate: { strategies: ['jwt'], mode: 'required' } },
+      upload: { authenticate: { strategies: ['jwt'], mode: 'required' }, middleware: [rateLimitMw] },
+      getObjectByName: { /* public -- no authenticate */ },
+      downloadObjectByName: { /* public */ },
+      deleteObject: { authenticate: { strategies: ['jwt'], mode: 'required' } },
+      deleteBucket: { authenticate: { strategies: ['jwt'], mode: 'required' } },
+    },
+  },
+  // ...
+}
+```
+
+Available route keys: `getBuckets`, `getBucketByName`, `createBucket`, `deleteBucket`, `upload`, `listObjects`, `deleteObject`, `getObjectByName`, `downloadObjectByName`, `recreateMetaLink`.
+
 #### TStaticAssetsComponentOptions -- Full Reference
 ```typescript
 type TStaticAssetsComponentOptions = {
@@ -218,9 +259,22 @@ type TStaticAssetsComponentOptions = {
       name: string;
       basePath: string;
       isStrict?: boolean;
+      routes?: {
+        getBuckets?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        getBucketByName?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        createBucket?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        deleteBucket?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        upload?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        listObjects?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        deleteObject?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        getObjectByName?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        downloadObjectByName?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+        recreateMetaLink?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
+      };
     };
     extra?: TStaticAssetExtraOptions;
   } & (
+    | { storage: typeof StaticAssetStorageTypes.BUN_S3; helper: BunS3Helper }
     | { storage: typeof StaticAssetStorageTypes.DISK; helper: DiskHelper }
     | { storage: typeof StaticAssetStorageTypes.MINIO; helper: MinioHelper }
   ) &
@@ -232,7 +286,7 @@ type TStaticAssetExtraOptions = {
     storage?: 'memory' | 'disk';
     uploadDir?: string;
   };
-  normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
+  normalizeNameFn?: (opts: { originalName: string }) => string;
   normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
   [key: string]: any;
 };
@@ -240,9 +294,20 @@ type TStaticAssetExtraOptions = {
 type TMetaLinkConfig<Schema extends TMetaLinkSchema = TMetaLinkSchema> = {
   model: typeof BaseEntity<Schema>;
   repository: DefaultCRUDRepository<Schema>;
+  createMetaLink?: (opts: {
+    uploadResult: IUploadResult;
+    fileStat: IFileStat;
+    query: TUploadQuery;
+  }) => ValueOrPromise<{ count: number; data: Schema }>;
 };
 ```
 
+> [!NOTE]
+> The `normalizeNameFn` receives only `{ originalName }` -- there is no `folderPath` parameter.
+
+> [!TIP]
+> The `createMetaLink` callback on `TMetaLinkConfig` is optional. When provided, it replaces the default MetaLink creation logic during upload, giving you full control over how file metadata is stored.
+
 ### DiskHelper
 
 Stores files on the local filesystem using a bucket-based directory structure.
@@ -301,16 +366,26 @@ const minioHelper = new MinioHelper({
 });
 ```
 
+### BunS3Helper
+
+Bun-native S3 client for direct S3/S3-compatible access using Bun's built-in S3 support. Requires Bun runtime.
+
+```typescript
+import { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
+```
+
 ### MetaLink Configuration
 
-MetaLink is an optional feature that tracks uploaded files in a database, storing file location, metadata (mimetype, size, etag), storage type, principal association (`principalType`, `principalId`), timestamps, and custom metadata (JSONB).
+MetaLink is an optional feature that tracks uploaded files in a database, storing file location, metadata (mimetype, size, etag), storage type, principal association (`principalType`, `principalId`), variant, timestamps, and custom metadata (JSONB).
 
 #### Benefits
 
-- Query uploaded files by bucket, name, mimetype, etc.
+- Query uploaded files by bucket, name, mimetype, variant, etc.
 - Track file history and audit trails
 - Store custom metadata about files
 - Associate files with principals via `principalType` and `principalId` (passed as query parameters on the upload endpoint)
+- Tag uploads with a `variant` query parameter (e.g., `"thumbnail"`, `"original"`)
+- Custom `createMetaLink` callback for full control over MetaLink creation
 - Graceful errors -- upload succeeds even if MetaLink creation fails
 
 #### Setup
@@ -318,7 +393,7 @@ MetaLink is an optional feature that tracks uploaded files in a database, storin
 **1. Create Model:**
 
 ```typescript
-import { BaseMetaLinkModel, model } from '@venizia/ignis';
+import { BaseMetaLinkModel, model } from '@venizia/ignis/static-asset';
 
 @model({ type: 'entity' })
 export class FileMetaLinkModel extends BaseMetaLinkModel {
@@ -329,7 +404,9 @@ export class FileMetaLinkModel extends BaseMetaLinkModel {
 **2. Create Repository:**
 
 ```typescript
-import { BaseMetaLinkRepository, repository, inject, IDataSource } from '@venizia/ignis';
+import { BaseMetaLinkRepository } from '@venizia/ignis/static-asset';
+import { repository, inject } from '@venizia/ignis';
+import type { IDataSource } from '@venizia/ignis';
 
 @repository({})
 export class FileMetaLinkRepository extends BaseMetaLinkRepository {
@@ -361,6 +438,7 @@ CREATE TABLE "MetaLink" (
   metadata        JSONB,
   storage_type    TEXT NOT NULL,
   is_synced       BOOLEAN NOT NULL DEFAULT false,
+  variant         TEXT,
   principal_type  TEXT,
   principal_id    TEXT
 );
@@ -375,6 +453,12 @@ CREATE INDEX "IDX_MetaLink_isSynced" ON "MetaLink"(is_synced);
 
 ```typescript
 import { FileMetaLinkModel, FileMetaLinkRepository } from './your-models';
+import {
+  StaticAssetComponent,
+  StaticAssetComponentBindingKeys,
+  StaticAssetStorageTypes,
+} from '@venizia/ignis/static-asset';
+import type { TStaticAssetsComponentOptions } from '@venizia/ignis/static-asset';
 
 export class Application extends BaseApplication {
   configureComponents(): void {
@@ -407,23 +491,56 @@ export class Application extends BaseApplication {
 }
 ```
 
-**5. Upload with Principal Association:**
+**5. Upload with Principal Association and Variant:**
 
-When MetaLink is enabled, you can associate uploaded files with a principal (user, service, etc.) by passing query parameters on the upload endpoint:
+When MetaLink is enabled, you can associate uploaded files with a principal and variant by passing query parameters on the upload endpoint:
 
 ```typescript
 const formData = new FormData();
 formData.append('file', fileBlob, 'document.pdf');
 
-// Associate the upload with a user
+// Associate the upload with a user and tag as 'original' variant
 const response = await fetch(
-  '/uploads/buckets/user-files/upload?principalType=user&principalId=42',
+  '/uploads/buckets/user-files/upload?principalType=user&principalId=42&variant=original',
   { method: 'POST', body: formData },
 );
 ```
 
 The `principalId` value is always stored as a string regardless of input type (coerced via `String()`).
 
+#### Custom MetaLink Creation
+
+You can provide a custom `createMetaLink` callback to fully control how MetaLink records are created:
+
+```typescript
+metaLink: {
+  model: FileMetaLinkModel,
+  repository: this.getSync(FileMetaLinkRepository),
+  createMetaLink: async ({ uploadResult, fileStat, query }) => {
+    // Custom logic -- e.g., add extra fields, validate, transform
+    return metaLinkRepo.create({
+      data: {
+        bucketName: uploadResult.bucketName,
+        objectName: uploadResult.objectName,
+        link: uploadResult.link,
+        mimetype: fileStat.metadata?.['mimetype'],
+        size: fileStat.size,
+        etag: fileStat.etag,
+        metadata: fileStat.metadata,
+        storageType: 'minio',
+        isSynced: true,
+        principalId: query.principalId ? String(query.principalId) : undefined,
+        principalType: query.principalType,
+        variant: query.variant,
+        // ... additional custom fields
+      },
+    });
+  },
+},
+```
+
+When `createMetaLink` is not provided, the component uses a default implementation that stores all standard fields.
+
 #### Querying MetaLinks
 
 ```typescript
@@ -447,32 +564,27 @@ const userFiles = await fileMetaLinkRepository.find({
   where: { principalType: 'user', principalId: '42' },
 });
 
-// Get synced files only
-const syncedFiles = await fileMetaLinkRepository.find({
-  where: { isSynced: true },
+// Get files by variant
+const thumbnails = await fileMetaLinkRepository.find({
+  where: { variant: 'thumbnail' },
 });
 
-// Get unsynced files (for manual sync operations)
-const unsyncedFiles = await fileMetaLinkRepository.find({
-  where: { isSynced: false },
-});
-
-// Count synced files
-const syncedCount = await fileMetaLinkRepository.count({
+// Get synced files only
+const syncedFiles = await fileMetaLinkRepository.find({
   where: { isSynced: true },
 });
-
-// Get recent uploads
-const recent = await fileMetaLinkRepository.find({
-  orderBy: { createdAt: 'desc' },
-  limit: 10,
-});
 ```
 
 ### Quick Start Options
 
 **Option 1: MinIO Only**
 ```typescript
+import {
+  StaticAssetComponent,
+  StaticAssetComponentBindingKeys,
+  StaticAssetStorageTypes,
+} from '@venizia/ignis/static-asset';
+
 this.bind({
   key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
 }).toValue({
@@ -538,9 +650,8 @@ this.component(StaticAssetComponent);
     helper: new MinioHelper({ /* ... */ }),
     extra: {
       parseMultipartBody: { storage: 'memory' },
-      normalizeNameFn: ({ originalName, folderPath }) => {
-        const prefix = folderPath ? `${folderPath}/` : '';
-        return `${prefix}${Date.now()}_${originalName.toLowerCase().replace(/\s/g, '_')}`;
+      normalizeNameFn: ({ originalName }) => {
+        return `${Date.now()}_${originalName.toLowerCase().replace(/\s/g, '_')}`;
       },
       normalizeLinkFn: ({ bucketName, normalizeName }) => {
         return `/api/files/${bucketName}/${encodeURIComponent(normalizeName)}`;
@@ -550,49 +661,7 @@ this.component(StaticAssetComponent);
 }
 ```
 
-The `normalizeNameFn` receives both the `originalName` and an optional `folderPath` from the uploaded file. The `folderPath` is passed through from the `IUploadFile` object and can be used to organize files into subdirectories.
-
-### Custom Storage Implementation
-
-You can implement your own storage backend by extending `BaseStorageHelper`:
-
-```typescript
-import { BaseStorageHelper, IUploadFile, IUploadResult } from '@venizia/ignis-helpers';
-
-class S3Helper extends BaseStorageHelper {
-  constructor(config: S3Config) {
-    super({ scope: 'S3Helper', identifier: 'S3Helper' });
-    // Initialize S3 client
-  }
-
-  async isBucketExists(opts: { name: string }): Promise<boolean> {
-    // Implementation
-  }
-
-  async upload(opts: {
-    bucket: string;
-    files: IUploadFile[];
-    normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
-    normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
-  }): Promise<IUploadResult[]> {
-    // Implementation
-  }
-
-  // Implement other IStorageHelper methods...
-}
-
-// Usage
-this.bind<TStaticAssetsComponentOptions>({
-  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
-}).toValue({
-  s3Storage: {
-    controller: { name: 'S3Controller', basePath: '/s3-assets' },
-    storage: 'custom-s3',
-    helper: new S3Helper({ /* ... */ }),
-    extra: {},
-  },
-});
-```
+The `normalizeNameFn` receives only the `originalName` of the uploaded file.
 
 ## Binding Keys
 
@@ -608,8 +677,8 @@ this.bind<TStaticAssetsComponentOptions>({
 - [Usage & Examples](./usage) - API Endpoints and Frontend Integration
 - [API Reference](./api) - Controller Factory, Storage Interface, MetaLink Schema
 - [Error Reference](./errors) - Name Validation and Troubleshooting
-- [Storage Helpers](/references/helpers/storage/) - DiskHelper, MinioHelper, BaseStorageHelper
+- [Storage Helpers](/extensions/helpers/storage/) - DiskHelper, MinioHelper, BaseStorageHelper
 - [Request Utilities](/references/utilities/request) - File upload utilities
 - [Security Guidelines](/best-practices/security-guidelines) - File upload security
 - [Components Overview](/guides/core-concepts/components) - Component system basics
-- [Controllers](/guides/core-concepts/controllers) - File upload endpoints
+- [Controllers](/guides/core-concepts/rest-controllers) - File upload endpoints

package/wiki/{references → extensions}/components/static-asset/usage.md

@@ -73,6 +73,7 @@ The `isDeleted` field is a boolean indicating whether the bucket was successfull
 **Query Parameters:**
 - `principalType` (optional, string): Type of the principal to associate with the uploaded files (e.g., `"user"`, `"service"`)
 - `principalId` (optional, string or number): ID of the principal. Always coerced to a string via `String()` before storage regardless of input type
+- `variant` (optional, string): Variant tag for the upload (e.g., `"thumbnail"`, `"original"`)
 
 **Validation:** Bucket name validated with `isValidName()`. Returns 400 `"Invalid bucket name"` if invalid.
 
@@ -84,7 +85,7 @@ const MultipartBodySchema = z.object({
 });
 ```
 
-This accepts either a single `File` or an array of `File` objects. Each file can optionally include `folderPath` for organization.
+This accepts either a single `File` or an array of `File` objects.
 
 **Response `200` (without MetaLink):**
 ```json
@@ -115,6 +116,7 @@ This accepts either a single `File` or an array of `File` objects. Each file can
       "metadata": {},
       "storageType": "minio",
       "isSynced": true,
+      "variant": "original",
       "principalType": "user",
       "principalId": "42",
       "createdAt": "2025-12-15T03:00:00.000Z",
@@ -144,9 +146,9 @@ When MetaLink creation fails, the upload itself still succeeds. The response inc
 const formData = new FormData();
 formData.append('file', fileBlob, 'document.pdf');
 
-// Upload with principal association
+// Upload with principal association and variant
 const response = await fetch(
-  '/assets/buckets/uploads/upload?principalType=user&principalId=123',
+  '/assets/buckets/uploads/upload?principalType=user&principalId=123&variant=original',
   { method: 'POST', body: formData },
 );
 
@@ -322,14 +324,15 @@ for (const obj of objects) {
 ## Frontend Integration
 
 ```typescript
-// Upload file with principal association
-async function uploadFile(file: File, principalType?: string, principalId?: string) {
+// Upload file with principal association and variant
+async function uploadFile(file: File, principalType?: string, principalId?: string, variant?: string) {
   const formData = new FormData();
   formData.append('file', file);
 
   const url = new URL('/assets/buckets/user-uploads/upload', window.location.origin);
   if (principalType) url.searchParams.append('principalType', principalType);
   if (principalId) url.searchParams.append('principalId', principalId);
+  if (variant) url.searchParams.append('variant', variant);
 
   const response = await fetch(url, {
     method: 'POST',

package/wiki/{references → extensions}/components/swagger.md

@@ -67,11 +67,11 @@ To get the most out of the documentation, define your routes with `zod` schemas:
 ```typescript
 // src/controllers/hello.controller.ts
 import { z } from '@hono/zod-openapi';
-import { BaseController, controller, jsonContent, ValueOrPromise } from '@venizia/ignis';
+import { BaseRestController, controller, jsonContent, ValueOrPromise } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 
 @controller({ path: '/hello' })
-export class HelloController extends BaseController {
+export class HelloController extends BaseRestController {
   constructor() {
     super({ scope: HelloController.name, path: '/hello' });
   }
@@ -457,7 +457,7 @@ this.defineRoute({
 
 - **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
-  - [Controllers](/guides/core-concepts/controllers) - Defining OpenAPI routes
+  - [Controllers](/guides/core-concepts/rest-controllers) - Defining OpenAPI routes
 
 - **Components:**
   - [All Components](./index) - Built-in components list

package/wiki/{references → extensions}/components/template/index.md

@@ -40,10 +40,10 @@ A directory with 4 files:
   text: 'ComponentName',
   collapsed: true,
   items: [
-    { text: 'Setup & Configuration', link: '/references/components/slug/' },
-    { text: 'Usage & Examples', link: '/references/components/slug/usage' },
-    { text: 'API Reference', link: '/references/components/slug/api' },
-    { text: 'Error Reference', link: '/references/components/slug/errors' },
+    { text: 'Setup & Configuration', link: '/extensions/components/slug/' },
+    { text: 'Usage & Examples', link: '/extensions/components/slug/usage' },
+    { text: 'API Reference', link: '/extensions/components/slug/api' },
+    { text: 'Error Reference', link: '/extensions/components/slug/errors' },
   ],
 },
 ```

package/wiki/{references → extensions}/components/template/setup-page.md

@@ -26,7 +26,7 @@ Paired with [Usage](./usage-page), [API Reference](./api-page), and [Error Refer
 |------|-------|
 | **Package** | `@venizia/ignis` |
 | **Class** | `{ComponentClass}` |
-| **Helper** | [`{HelperClass}`](/references/helpers/{slug}) |
+| **Helper** | [`{HelperClass}`](/extensions/helpers/{slug}) |
 | **Runtimes** | Both / Bun only |
 
 | Sub-component | Purpose |

package/wiki/{references → extensions}/components/template/single-page.md

@@ -24,7 +24,7 @@ For simple components with few configuration options and straightforward behavio
 |------|-------|
 | **Package** | `@venizia/ignis` |
 | **Class** | `{ComponentClass}` |
-| **Helper** | [`{HelperClass}`](/references/helpers/{slug}) |
+| **Helper** | [`{HelperClass}`](/extensions/helpers/{slug}) |
 | **Runtimes** | Both / Bun only |
 
 #### Import Paths

package/wiki/{references → extensions}/components/websocket/api.md

@@ -232,11 +232,12 @@ Registers a post-start hook that executes the following steps:
 
 1. **Get Bun server instance** via `getServerInstance<TBunServerInstance>()`
 2. **Get Hono server** via `getServer()`
-3. **Create WebSocketServerHelper** with all resolved bindings and server options
-4. **Await `wsHelper.configure()`** which connects Redis clients and sets up subscriptions
-5. **Bind the helper** to `WEBSOCKET_INSTANCE` in the DI container
-6. **Create custom `fetch` handler** via `createBunFetchHandler({ wsPath, honoServer })`
-7. **Wire WebSocket into running server** via `serverInstance.reload({ fetch, websocket })`
+3. **Validate server instance** -- throws `"[WebSocketComponent] Bun server instance not available!"` if not found
+4. **Create WebSocketServerHelper** with all resolved bindings and server options
+5. **Await `wsHelper.configure()`** which connects Redis clients and sets up subscriptions
+6. **Bind the helper** to `WEBSOCKET_INSTANCE` in the DI container
+7. **Create custom `fetch` handler** via `createBunFetchHandler({ wsPath, honoServer })`
+8. **Wire WebSocket into running server** via `serverInstance.reload({ fetch, websocket })`
 
 #### Post-Start Hook Code Flow
 ```typescript
@@ -503,6 +504,6 @@ The emitter shutdown is simpler since it only has one Redis client and no local
 - [Setup & Configuration](./) - Quick reference, imports, setup steps, configuration, and binding keys
 - [Usage & Examples](./usage) - Server-side usage, emitter, wire protocol, client tracking, and delivery strategy
 - [Error Reference](./errors) - Error conditions table and troubleshooting
-- [WebSocketServerHelper](/references/helpers/websocket/) - Helper API documentation
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
 - [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
 - [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference

package/wiki/{references → extensions}/components/websocket/errors.md

@@ -22,6 +22,16 @@ The server can send `error` events or close the connection under the following c
 | `"Invalid redis connection!"` | Constructor: `redisConnection` is falsy | thrown `Error` (startup) |
 | `"WebSocket upgrade failed"` | `server.upgrade()` returned `false` | HTTP `500` response |
 
+### Component Errors
+
+| Method | Condition | Error Message |
+|--------|-----------|---------------|
+| `binding()` | `application` is falsy | `"[binding] Invalid application to bind WebSocketComponent"` |
+| `binding()` | Node.js runtime detected | `"[WebSocketComponent] Node.js runtime is not supported yet. Please use Bun runtime."` |
+| `resolveBindings()` | `REDIS_CONNECTION` not instanceof `DefaultRedisHelper` | `"[WebSocketComponent][resolveBindings] Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
+| `resolveBindings()` | `AUTHENTICATE_HANDLER` is falsy | `"[WebSocketComponent] Invalid authenticateFn to setup WebSocket server!"` |
+| `registerBunHook()` | Bun server instance not available | `"[WebSocketComponent] Bun server instance not available!"` |
+
 ## Troubleshooting
 
 ### "WebSocket not initialized"
@@ -32,11 +42,13 @@ The server can send `error` events or close the connection under the following c
 
 ### "Invalid instance of redisConnection"
 
-**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `DefaultRedisHelper` (or its subclass `RedisHelper`).
+**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `DefaultRedisHelper` (or its subclasses `RedisHelper` / `RedisClusterHelper`).
 
-**Fix**: Use `RedisHelper` (recommended) or `DefaultRedisHelper`:
+**Fix**: Use `RedisHelper` (single instance) or `RedisClusterHelper` (cluster mode):
 
 ```typescript
+import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
+
 // Correct
 this.bind({ key: WebSocketBindingKeys.REDIS_CONNECTION })
   .toValue(new RedisHelper({ name: 'websocket', host, port, password }));
@@ -53,6 +65,8 @@ this.bind({ key: WebSocketBindingKeys.REDIS_CONNECTION })
 **Fix**: Bind a valid authentication function before registering the component:
 
 ```typescript
+import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
+
 this.bind<TWebSocketAuthenticateFn>({
   key: WebSocketBindingKeys.AUTHENTICATE_HANDLER,
 }).toValue(async (data) => {
@@ -118,6 +132,6 @@ setInterval(() => {
 - [Setup & Configuration](./) - Quick reference, imports, setup steps, configuration, and binding keys
 - [Usage & Examples](./usage) - Server-side usage, emitter, wire protocol, client tracking, and delivery strategy
 - [API Reference](./api) - Architecture, WebSocketEmitter API, and internals
-- [WebSocketServerHelper](/references/helpers/websocket/) - Helper API documentation
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
 - [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
 - [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference