@venizia/ignis-docs 0.0.1-7 → 0.0.1-9

package/wiki/references/components/authentication.md

@@ -9,8 +9,9 @@ JWT-based authentication and authorization system for Ignis applications.
 | **AuthenticateComponent** | Main component registering auth services and controllers |
 | **AuthenticationStrategyRegistry** | Singleton managing available auth strategies |
 | **JWTAuthenticationStrategy** | JWT verification using `JWTTokenService` |
-| **JWTTokenService** | Generate, verify, encrypt/decrypt JWT tokens |
+| **JWTTokenService** | Generate, verify, encrypt/decrypt JWT tokens (safely handles undefined/null) |
 | **IAuthService** | Interface for custom auth implementation (sign-in, sign-up) |
+| **defineAuthController** | Factory function for creating custom auth controllers |
 
 ### Key Environment Variables
 
@@ -20,12 +21,26 @@ JWT-based authentication and authorization system for Ignis applications.
 | `APP_ENV_JWT_SECRET` | Sign and verify JWT signature | ✅ Yes |
 | `APP_ENV_JWT_EXPIRES_IN` | Token expiration (seconds) | Optional |
 
+### Authentication Options Configuration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `restOptions.useAuthController` | `boolean` | Enable/disable built-in auth controller (default: `false`) |
+| `restOptions.controllerOpts` | `TDefineAuthControllerOpts` | Configuration for built-in auth controller (required if `useAuthController` is `true`) |
+| `restOptions.controllerOpts.restPath` | `string` | Base path for auth endpoints (default: `/auth`) |
+| `restOptions.controllerOpts.serviceKey` | `string` | Dependency injection key for auth service (default: `services.AuthenticationService`) |
+| `restOptions.controllerOpts.requireAuthenticatedSignUp` | `boolean` | Whether sign-up requires authentication (default: `false`) |
+| `restOptions.controllerOpts.payload` | `object` | Custom Zod schemas for request/response payloads |
+| `alwaysAllowPaths` | `string[]` | Array of paths that bypass authentication |
+| `tokenOptions` | `IJWTTokenServiceOptions` | JWT token configuration |
+
 ## Architecture Components
 
--   **`AuthenticateComponent`**: Registers all necessary services and controllers
+-   **`AuthenticateComponent`**: Registers all necessary services and optionally the authentication controller
 -   **`AuthenticationStrategyRegistry`**: Singleton managing authentication strategies
 -   **`JWTAuthenticationStrategy`**: JWT strategy implementation using `JWTTokenService`
--   **`JWTTokenService`**: Generates, verifies, encrypts/decrypts JWT payloads
+-   **`JWTTokenService`**: Generates, verifies, encrypts/decrypts JWT payloads (handles undefined/null values safely)
+-   **`defineAuthController`**: Factory function to create customizable authentication controller
 -   **Protected Routes**: Use `authStrategies` in route configs to secure endpoints
 
 ## Implementation Details
@@ -62,6 +77,8 @@ APP_ENV_JWT_EXPIRES_IN=86400
 
 In `src/application.ts`, register the `AuthenticateComponent` and the `JWTAuthenticationStrategy`. You also need to provide an `AuthenticationService`.
 
+**Basic Setup (without built-in auth controller):**
+
 ```typescript
 // src/application.ts
 import {
@@ -79,7 +96,116 @@ export class Application extends BaseApplication {
 
   registerAuth() {
     this.service(AuthenticationService);
-    this.component(AuthenticateComponent);
+    this.component(AuthenticateComponent, {
+      restOptions: {
+        useAuthController: false, // Default: controller not registered
+      },
+      alwaysAllowPaths: [],
+      tokenOptions: {
+        applicationSecret: process.env.APP_ENV_APPLICATION_SECRET,
+        jwtSecret: process.env.APP_ENV_JWT_SECRET,
+        getTokenExpiresFn: () => Number(process.env.APP_ENV_JWT_EXPIRES_IN || 86400),
+      },
+    });
+    AuthenticationStrategyRegistry.getInstance().register({
+      container: this,
+      name: Authentication.STRATEGY_JWT,
+      strategy: JWTAuthenticationStrategy,
+    });
+  }
+
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.registerAuth();
+    // ...
+  }
+}
+```
+
+**Advanced Setup (with built-in auth controller):**
+
+```typescript
+import {
+  AuthenticateComponent,
+  Authentication,
+  AuthenticationStrategyRegistry,
+  JWTAuthenticationStrategy,
+  BaseApplication,
+  ValueOrPromise,
+} from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { AuthenticationService } from './services';
+
+export class Application extends BaseApplication {
+  // ...
+
+  registerAuth() {
+    this.service(AuthenticationService);
+    this.component(AuthenticateComponent, {
+      restOptions: {
+        useAuthController: true, // Enable built-in auth controller
+        controllerOpts: {
+          restPath: '/auth', // Base path for auth endpoints
+          serviceKey: 'services.AuthenticationService', // Default service key
+          requireAuthenticatedSignUp: false, // Whether sign-up requires authentication
+          payload: {
+            signIn: {
+              request: { 
+                schema: z.object({
+                  identifier: z.object({
+                    type: z.string(),
+                    value: z.string(),
+                  }),
+                  credential: z.object({
+                    type: z.string(),
+                    value: z.string(),
+                  }),
+                })
+              },
+              response: { 
+                schema: z.object({
+                  token: z.string(),
+                })
+              },
+            },
+            signUp: {
+              request: { 
+                schema: z.object({
+                  username: z.string(),
+                  email: z.string().email(),
+                  password: z.string().min(8),
+                })
+              },
+              response: { 
+                schema: z.object({
+                  token: z.string(),
+                  userId: z.string(),
+                })
+              },
+            },
+            changePassword: {
+              request: { 
+                schema: z.object({
+                  oldPassword: z.string(),
+                  newPassword: z.string().min(8),
+                })
+              },
+              response: { 
+                schema: z.object({
+                  success: z.boolean(),
+                })
+              },
+            },
+          },
+        },
+      },
+      alwaysAllowPaths: [],
+      tokenOptions: {
+        applicationSecret: process.env.APP_ENV_APPLICATION_SECRET,
+        jwtSecret: process.env.APP_ENV_JWT_SECRET,
+        getTokenExpiresFn: () => Number(process.env.APP_ENV_JWT_EXPIRES_IN || 86400),
+      },
+    });
     AuthenticationStrategyRegistry.getInstance().register({
       container: this,
       name: Authentication.STRATEGY_JWT,
@@ -158,7 +284,95 @@ export class AuthenticationService extends BaseService implements IAuthService {
 
 This service is then registered in `application.ts` as shown in the previous step. It injects the `JWTTokenService` (provided by the `AuthenticateComponent`) to generate a token upon successful sign-in.
 
-#### 3. Securing Routes
+#### 3. Custom Authentication Controller (Optional)
+
+If you need more control over the authentication endpoints, you can create a custom controller using the `defineAuthController` factory function.
+
+```typescript
+// src/controllers/custom-auth.controller.ts
+import { defineAuthController } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+export const CustomAuthController = defineAuthController({
+  restPath: '/api/auth',
+  serviceKey: 'services.AuthenticationService',
+  requireAuthenticatedSignUp: true, // Require authentication for sign-up
+  payload: {
+    signIn: {
+      request: {
+        schema: z.object({
+          email: z.string().email(),
+          password: z.string(),
+        }),
+      },
+      response: {
+        schema: z.object({
+          token: z.string(),
+          expiresIn: z.number(),
+        }),
+      },
+    },
+    signUp: {
+      request: {
+        schema: z.object({
+          email: z.string().email(),
+          password: z.string().min(8),
+          firstName: z.string(),
+          lastName: z.string(),
+        }),
+      },
+      response: {
+        schema: z.object({
+          token: z.string(),
+          userId: z.string(),
+        }),
+      },
+    },
+    changePassword: {
+      request: {
+        schema: z.object({
+          currentPassword: z.string(),
+          newPassword: z.string().min(8),
+        }),
+      },
+      response: {
+        schema: z.object({
+          success: z.boolean(),
+          message: z.string().optional(),
+        }),
+      },
+    },
+  },
+});
+```
+
+Then register it in your application:
+
+```typescript
+// src/application.ts
+import { CustomAuthController } from './controllers/custom-auth.controller';
+
+export class Application extends BaseApplication {
+  registerAuth() {
+    this.service(AuthenticationService);
+    this.component(AuthenticateComponent, {
+      restOptions: { useAuthController: false }, // Disable built-in controller
+      // ... other options
+    });
+    
+    // Register your custom controller
+    this.controller(CustomAuthController);
+    
+    AuthenticationStrategyRegistry.getInstance().register({
+      container: this,
+      name: Authentication.STRATEGY_JWT,
+      strategy: JWTAuthenticationStrategy,
+    });
+  }
+}
+```
+
+#### 4. Securing Routes
 
 In your controllers, use decorator-based routing (`@get`, `@post`, etc.) with the `authStrategies` property in the `configs` object to protect endpoints. This will automatically run the necessary authentication middlewares and attach the authenticated user to the Hono `Context`, which can then be accessed type-safely using `TRouteContext`.
 
@@ -199,12 +413,15 @@ export class TestController extends BaseController {
   secureData(c: TRouteContext<typeof SECURE_ROUTE_CONFIG>) {
     // 'c' is fully typed here, including c.get and c.json return type
     const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload | undefined;
-    return c.json({ message: `Hello, ${user?.userId || 'guest'} from protected data` });
+    return c.json(
+      { message: `Hello, ${user?.userId || 'guest'} from protected data` },
+      HTTP.ResultCodes.RS_2.Ok,
+    );
   }
 }
 ```
 
-#### 4. Accessing the Current User in Context
+#### 5. Accessing the Current User in Context
 
 After a route has been processed, the authenticated user's payload is available directly on the Hono `Context` object, using the `Authentication.CURRENT_USER` key.
 

package/wiki/references/components/health-check.md

@@ -127,7 +127,7 @@ export class HealthCheckController extends BaseController {
 
   @api({ configs: ROUTE_CONFIGS['/'] })
   checkHealth(c: TRouteContext<typeof ROUTE_CONFIGS['/']>) {
-    return c.json({ status: 'ok' });
+    return c.json({ status: 'ok' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
   @api({ configs: ROUTE_CONFIGS['/ping'] })

package/wiki/references/components/swagger.md

@@ -158,7 +158,7 @@ export class HelloController extends BaseController {
         },
       },
       handler: (c) => {
-        return c.json({ message: 'Hello, `Ignis`!' });
+        return c.json({ message: 'Hello, `Ignis`!' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
   }

package/wiki/references/helpers/inversion.md

@@ -2,7 +2,12 @@
 
 Core DI system enabling loosely coupled, testable, and extensible code.
 
-> **Package Architecture Note:** The core DI container functionality has been extracted to a standalone package `@venizia/ignis-inversion`. The `@venizia/ignis-helpers` package extends and re-exports this functionality with application-specific enhancements (logging, framework metadata). All imports from `@venizia/ignis-helpers` or `@venizia/ignis` continue to work as before - backward compatibility is maintained.
+> **Architecture Update:** The core DI container functionality has been extracted to a standalone package `@venizia/ignis-inversion`.
+>
+> *   **Standalone Container:** `@venizia/ignis-inversion` (Generic DI)
+> *   **Framework Integration:** `@venizia/ignis` (extends Core DI with Framework Metadata)
+>
+> Previously, this module resided in `@venizia/ignis-helpers`. It has now been moved to **Core** (`@venizia/ignis`) to better align with the framework architecture.
 
 ## Quick Reference
 
@@ -141,11 +146,11 @@ export class UserController extends BaseController {
 The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a singleton class responsible for storing and retrieving all the metadata attached by decorators like `@inject`, `@controller`, `@get`, etc.
 
 -   **Base File:** `packages/inversion/src/registry.ts` (core MetadataRegistry)
--   **Extended File:** `packages/helpers/src/helpers/inversion/registry.ts` (with framework metadata)
+-   **Extended File:** `packages/core/src/helpers/inversion/registry.ts` (with framework metadata)
 
 ### Role in DI
 
 -   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
 -   When the `Container` instantiates a class, it queries the `MetadataRegistry` to find out which dependencies need to be injected and where.
 
-You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.
+You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.

package/wiki/references/src-details/core.md

@@ -12,7 +12,7 @@ Detailed breakdown of the core framework directory structure.
 |-----------|---------------|----------------|
 | **`base`** | Core architecture | Applications, Controllers, Repositories, Services, Models |
 | **`components`** | Pluggable features | Auth, Swagger, HealthCheck, SocketIO |
-| **`helpers`** | Utilities | Re-exports from `@venizia/ignis-helpers` |
+| **`helpers`** | Utilities | DI (extended), Re-exports from `@venizia/ignis-helpers` |
 | **`common`** | Shared code | Constants, bindings, types, environments |
 | **`utilities`** | Pure functions | Crypto, date, parse, performance, schema |
 | **`__tests__`** | Tests | Integration and E2E tests |
@@ -27,7 +27,7 @@ Top-level breakdown of the `src` directory:
 | **`base`**       | The core building blocks and abstract classes of the framework. This is where the fundamental architecture is defined. |
 | **`common`**     | A directory for code that is shared and used across the entire framework.                                              |
 | **`components`** | A collection of ready-to-use, high-level components that can be plugged into an Ignis application.                     |
-| **`helpers`**    | Re-exports all modules from the dedicated `@venizia/ignis-helpers` package.                                                |
+| **`helpers`**    | Contains core extensions (like Inversion) and re-exports from `@venizia/ignis-helpers`.                                    |
 | **`utilities`**  | A collection of pure, standalone utility functions.                                                                    |
 
 ---
@@ -237,11 +237,12 @@ Generates interactive OpenAPI documentation.
 
 ### `helpers`
 
-The `helpers` directory has been refactored into its own dedicated package, `@venizia/ignis-helpers`, to improve modularity. The `src/helpers` directory within the core framework now simply re-exports all modules from this new package.
+Contains framework extensions and utilities.
 
 | File/Folder | Purpose/Key Details                                                                                                                                        |
 | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.ts`  | Re-exports all helpers from the `@venizia/ignis-helpers` package, making them available through the core framework for backward compatibility and convenience. |
+| `inversion/`| **Framework DI Extension**: Extends `@venizia/ignis-inversion` to provide application-aware dependency injection with logging and enhanced metadata support. |
+| `index.ts`  | Re-exports extensions and utilities from `@venizia/ignis-helpers`. |
 
 ### `utilities`
 
@@ -260,4 +261,4 @@ This directory contains pure, standalone utility functions that perform common,
 
 ---
 
-This detailed breakdown illustrates the modular and layered design of the Ignis framework, emphasizing its extensibility and adherence to robust architectural patterns.
+This detailed breakdown illustrates the modular and layered design of the Ignis framework, emphasizing its extensibility and adherence to robust architectural patterns.

package/wiki/references/src-details/inversion.md

@@ -309,22 +309,22 @@ if (cache) {
 
 ---
 
-## Relationship with @venizia/ignis-helpers
+## Integration with Framework
 
-The `@venizia/ignis-helpers` package extends this base inversion package with:
+The core `@venizia/ignis` package extends this base inversion package with:
 
 - **ApplicationLogger integration**: Container with structured logging
 - **Framework-specific metadata**: Controllers, models, repositories, data sources
 - **Decorator implementations**: `@inject`, `@controller`, `@service`, etc.
 
-For framework usage, import from `@venizia/ignis-helpers` or `@venizia/ignis`. For standalone DI container usage, import directly from `@venizia/ignis-inversion`.
+For framework usage, import from `@venizia/ignis`. For standalone DI container usage, import directly from `@venizia/ignis-inversion`.
 
 ```typescript
 // Standalone usage
 import { Container, Binding } from '@venizia/ignis-inversion';
 
 // Framework usage (includes logging and framework metadata)
-import { Container, inject, service } from '@venizia/ignis-helpers';
+import { Container, inject, service } from '@venizia/ignis';
 ```
 
 ---

package/wiki/references/utilities/request.md

@@ -31,7 +31,7 @@ The function returns a `Promise` that resolves to an array of `IParsedFile` obje
 Here is an example of how to use `parseMultipartBody` in a controller to handle a file upload.
 
 ```typescript
-import { BaseController, controller, ... } from '@venizia/ignis';
+import { BaseController, controller, HTTP } from '@venizia/ignis';
 import { parseMultipartBody } from '@venizia/ignis';
 
 @controller({ path: '/files' })
@@ -55,9 +55,15 @@ export class FileController extends BaseController {
 
           console.log('Uploaded files:', files);
 
-          return c.json({ message: `${files.length} file(s) uploaded successfully.` });
+          return c.json(
+            { message: `${files.length} file(s) uploaded successfully.` },
+            HTTP.ResultCodes.RS_2.Ok,
+          );
         } catch (error) {
-          return c.json({ message: 'Failed to upload files', error: error.message }, 500);
+          return c.json(
+            { message: 'Failed to upload files', error: error.message },
+            HTTP.ResultCodes.RS_5.InternalServerError,
+          );
         }
       },
     });
@@ -180,10 +186,13 @@ export class FileController extends BaseController {
           uploadDir: './uploads',
         });
 
-        return ctx.json({
-          message: 'Files uploaded successfully',
-          files: files.map(f => ({ name: f.originalname, size: f.size })),
-        });
+        return ctx.json(
+          {
+            message: 'Files uploaded successfully',
+            files: files.map(f => ({ name: f.originalname, size: f.size })),
+          },
+          HTTP.ResultCodes.RS_2.Ok,
+        );
       },
     });