@venturialstd/tenant 0.0.1

package/README.md

@@ -0,0 +1,974 @@
+# @venturialstd/tenant
+
+A comprehensive **Multi-Tenant SaaS Platform Package**, developed by **Venturial**, that provides complete tenant management capabilities with user isolation for building scalable SaaS applications. This package follows the Venturial architecture pattern and integrates seamlessly with TypeORM and NestJS.
+
+---
+
+## Features
+
+- **Multi-Tenant Management**: Create and manage multiple tenants with isolated data
+- **User-Tenant Relationships**: Complete user isolation per tenant with role-based access control
+- **Role-Based Access Control (RBAC)**: Owner, Admin, Member, and Viewer roles
+- **Subscription Plans**: Support for Free, Starter, Professional, and Enterprise plans
+- **Trial Period**: Configurable trial periods for new tenants
+- **Custom Domains**: Optional custom domain support for tenants
+- **Invitation System**: Invite users to tenants with pending invitation management
+- **Ownership Transfer**: Transfer tenant ownership between users
+- **User Suspension**: Suspend and reactivate user access to tenants
+- **Guards & Decorators**: Built-in guards and decorators for easy tenant isolation
+- **CRUD Operations**: Full TypeORM CRUD service integration
+- **Settings Management**: Dynamic tenant-level settings with `@venturialstd/core`
+
+---
+
+## Installation
+
+```bash
+npm install @venturialstd/tenant
+# or
+yarn add @venturialstd/tenant
+```
+
+---
+
+## Basic Usage
+
+### 1. Import the TenantModule in your application
+
+```ts
+import { Module } from '@nestjs/common';
+import { TenantModule } from '@venturialstd/tenant';
+
+@Module({
+  imports: [
+    TenantModule,
+    // ... other modules
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Use the services in your application
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { TenantService, TenantUserService, TenantUserRole } from '@venturialstd/tenant';
+
+@Injectable()
+export class YourService {
+  constructor(
+    private readonly tenantService: TenantService,
+    private readonly tenantUserService: TenantUserService,
+  ) {}
+
+  async createNewTenant(userId: string) {
+    // Create tenant
+    const tenant = await this.tenantService.createTenant(
+      'Acme Corp',
+      'acme-corp',
+      'acme.example.com',
+      'A leading software company',
+      userId
+    );
+
+    // Add user as primary owner
+    await this.tenantUserService.addUserToTenant(
+      tenant.id,
+      userId,
+      TenantUserRole.OWNER
+    );
+
+    await this.tenantUserService.setPrimaryOwner(tenant.id, userId);
+
+    return tenant;
+  }
+
+  async inviteUserToTenant(tenantId: string, userId: string, invitedBy: string) {
+    return this.tenantUserService.inviteUserToTenant(
+      tenantId,
+      userId,
+      TenantUserRole.MEMBER,
+      invitedBy
+    );
+  }
+}
+```
+
+### 3. Use Guards and Decorators for tenant isolation
+
+```ts
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { 
+  TenantGuard, 
+  TenantRoleGuard, 
+  TenantId, 
+  UserId,
+  Roles,
+  TenantUserRole 
+} from '@venturialstd/tenant';
+
+@Controller('data')
+@UseGuards(TenantGuard) // Ensure user has access to tenant
+export class DataController {
+  constructor(private readonly dataService: DataService) {}
+
+  @Get()
+  async getData(@TenantId() tenantId: string, @UserId() userId: string) {
+    // tenantId and userId are automatically extracted and validated
+    return this.dataService.getTenantData(tenantId, userId);
+  }
+
+  @Delete(':id')
+  @Roles(TenantUserRole.OWNER, TenantUserRole.ADMIN) // Only owners and admins
+  @UseGuards(TenantRoleGuard) // Enforce role-based access
+  async deleteData(@TenantId() tenantId: string, @Param('id') id: string) {
+    return this.dataService.deleteData(tenantId, id);
+  }
+}
+```
+
+---
+
+## Entity Structures
+
+### Tenant Entity
+
+The `Tenant` entity includes the following fields:
+
+- **id**: UUID primary key
+- **name**: Tenant name (required, unique)
+- **slug**: URL-friendly identifier (required, unique)
+- **domain**: Custom domain (optional)
+- **description**: Tenant description (optional)
+- **isActive**: Active/inactive status (default: true)
+- **settings**: JSON field for tenant-specific settings
+- **ownerId**: Reference to the owner user
+- **plan**: Subscription plan (free, starter, professional, enterprise)
+- **trialEndsAt**: Trial period expiration date
+- **subscriptionEndsAt**: Subscription expiration date
+- **createdAt**: Creation timestamp
+- **updatedAt**: Last update timestamp
+
+### TenantUser Entity
+
+The `TenantUser` entity manages user-tenant relationships:
+
+- **id**: UUID primary key
+- **tenantId**: Reference to tenant (indexed)
+- **userId**: Reference to user (indexed)
+- **role**: User role (OWNER, ADMIN, MEMBER, VIEWER)
+- **status**: User status (ACTIVE, INVITED, SUSPENDED)
+- **isPrimary**: Whether user is the primary owner
+- **invitedBy**: User who sent the invitation
+- **invitedAt**: Invitation timestamp
+- **joinedAt**: Join timestamp
+- **permissions**: JSON field for custom permissions
+- **createdAt**: Creation timestamp
+- **updatedAt**: Last update timestamp
+
+**Unique constraint**: (tenantId, userId) - A user can only be added once per tenant
+
+---
+
+## Available Methods
+
+### TenantService Methods
+
+#### `createTenant(name, slug, domain?, description?, ownerId?)`
+Creates a new tenant with validation and default settings.
+
+```ts
+const tenant = await tenantService.createTenant(
+  'My Company',
+  'my-company',
+  'mycompany.com',
+  'Company description',
+  'owner-uuid'
+);
+```
+
+#### `getTenantBySlug(slug)`
+Retrieve a tenant by its slug.
+
+```ts
+const tenant = await tenantService.getTenantBySlug('my-company');
+```
+
+#### `getTenantByDomain(domain)`
+Retrieve a tenant by its custom domain.
+
+```ts
+const tenant = await tenantService.getTenantByDomain('mycompany.com');
+```
+
+#### `updateTenantSettings(tenantId, settings)`
+Update tenant-specific settings.
+
+```ts
+await tenantService.updateTenantSettings('tenant-uuid', {
+  theme: 'dark',
+  language: 'en',
+  features: { api: true }
+});
+```
+
+#### `setTenantStatus(tenantId, isActive)`
+Activate or deactivate a tenant.
+
+```ts
+await tenantService.setTenantStatus('tenant-uuid', false); // Deactivate
+await tenantService.setTenantStatus('tenant-uuid', true);  // Activate
+```
+
+#### `updateTenantPlan(tenantId, plan, subscriptionEndsAt?)`
+Update the tenant's subscription plan.
+
+```ts
+const endDate = new Date();
+endDate.setMonth(endDate.getMonth() + 1);
+
+await tenantService.updateTenantPlan(
+  'tenant-uuid',
+  'professional',
+  endDate
+);
+```
+
+#### `getActiveTenants()`
+Get all active tenants.
+
+```ts
+const activeTenants = await tenantService.getActiveTenants();
+```
+
+#### `getTenantsByOwner(ownerId)`
+Get all tenants owned by a specific user.
+
+```ts
+const tenants = await tenantService.getTenantsByOwner('owner-uuid');
+```
+
+#### `isInTrialPeriod(tenantId)`
+Check if a tenant is currently in trial period.
+
+```ts
+const inTrial = await tenantService.isInTrialPeriod('tenant-uuid');
+```
+
+#### `hasActiveSubscription(tenantId)`
+Check if a tenant has an active subscription.
+
+```ts
+const isActive = await tenantService.hasActiveSubscription('tenant-uuid');
+```
+
+### TenantUserService Methods
+
+#### `addUserToTenant(tenantId, userId, role, invitedBy?)`
+Add a user to a tenant with a specific role.
+
+```ts
+await tenantUserService.addUserToTenant(
+  'tenant-uuid',
+  'user-uuid',
+  TenantUserRole.MEMBER,
+  'inviter-uuid'
+);
+```
+
+#### `inviteUserToTenant(tenantId, userId, role, invitedBy)`
+Invite a user to a tenant (creates pending invitation).
+
+```ts
+await tenantUserService.inviteUserToTenant(
+  'tenant-uuid',
+  'user-uuid',
+  TenantUserRole.ADMIN,
+  'inviter-uuid'
+);
+```
+
+#### `acceptInvitation(tenantId, userId)`
+Accept a pending tenant invitation.
+
+```ts
+await tenantUserService.acceptInvitation('tenant-uuid', 'user-uuid');
+```
+
+#### `removeUserFromTenant(tenantId, userId)`
+Remove a user from a tenant (cannot remove primary owner).
+
+```ts
+await tenantUserService.removeUserFromTenant('tenant-uuid', 'user-uuid');
+```
+
+#### `updateUserRole(tenantId, userId, newRole)`
+Update a user's role in a tenant.
+
+```ts
+await tenantUserService.updateUserRole(
+  'tenant-uuid',
+  'user-uuid',
+  TenantUserRole.ADMIN
+);
+```
+
+#### `getUserTenants(userId)`
+Get all tenants a user belongs to.
+
+```ts
+const userTenants = await tenantUserService.getUserTenants('user-uuid');
+```
+
+#### `getTenantUsers(tenantId)`
+Get all users in a tenant (including invited).
+
+```ts
+const users = await tenantUserService.getTenantUsers('tenant-uuid');
+```
+
+#### `getActiveTenantUsers(tenantId)`
+Get all active users in a tenant.
+
+```ts
+const activeUsers = await tenantUserService.getActiveTenantUsers('tenant-uuid');
+```
+
+#### `hasAccess(tenantId, userId)`
+Check if a user has access to a tenant.
+
+```ts
+const hasAccess = await tenantUserService.hasAccess('tenant-uuid', 'user-uuid');
+```
+
+#### `hasRole(tenantId, userId, role)`
+Check if a user has a specific role in a tenant.
+
+```ts
+const isAdmin = await tenantUserService.hasRole(
+  'tenant-uuid',
+  'user-uuid',
+  TenantUserRole.ADMIN
+);
+```
+
+#### `isAdminOrOwner(tenantId, userId)`
+Check if a user is an admin or owner in a tenant.
+
+```ts
+const isAdminOrOwner = await tenantUserService.isAdminOrOwner('tenant-uuid', 'user-uuid');
+```
+
+#### `getUserRole(tenantId, userId)`
+Get a user's role in a tenant.
+
+```ts
+const role = await tenantUserService.getUserRole('tenant-uuid', 'user-uuid');
+```
+
+#### `setPrimaryOwner(tenantId, userId)`
+Set a user as the primary owner of a tenant.
+
+```ts
+await tenantUserService.setPrimaryOwner('tenant-uuid', 'user-uuid');
+```
+
+#### `transferOwnership(tenantId, fromUserId, toUserId)`
+Transfer tenant ownership between users.
+
+```ts
+await tenantUserService.transferOwnership(
+  'tenant-uuid',
+  'current-owner-uuid',
+  'new-owner-uuid'
+);
+```
+
+#### `getUserInvitations(userId)`
+Get all pending invitations for a user.
+
+```ts
+const invitations = await tenantUserService.getUserInvitations('user-uuid');
+```
+
+#### `suspendUser(tenantId, userId)`
+Suspend a user's access to a tenant.
+
+```ts
+await tenantUserService.suspendUser('tenant-uuid', 'user-uuid');
+```
+
+#### `reactivateUser(tenantId, userId)`
+Reactivate a suspended user.
+
+```ts
+await tenantUserService.reactivateUser('tenant-uuid', 'user-uuid');
+```
+
+---
+
+## Guards and Decorators
+
+### TenantGuard
+
+Enforces tenant access control by validating that the authenticated user has access to the requested tenant.
+
+```ts
+@Controller('api')
+@UseGuards(TenantGuard)
+export class ApiController {
+  @Get('data')
+  async getData(@TenantId() tenantId: string) {
+    // User access to tenant is already validated
+    return this.service.getData(tenantId);
+  }
+}
+```
+
+### TenantRoleGuard
+
+Enforces role-based access control within a tenant. Use with `@Roles()` decorator.
+
+```ts
+@Controller('admin')
+@UseGuards(TenantGuard, TenantRoleGuard)
+export class AdminController {
+  @Delete('user/:userId')
+  @Roles(TenantUserRole.OWNER, TenantUserRole.ADMIN)
+  async removeUser(@TenantId() tenantId: string, @Param('userId') userId: string) {
+    // Only owners and admins can access this endpoint
+    return this.service.removeUser(tenantId, userId);
+  }
+}
+```
+
+### @TenantId()
+
+Extracts the tenant ID from the request. Checks in order:
+1. `request.tenantId`
+2. `request.headers['x-tenant-id']`
+3. `request.params.tenantId`
+4. `request.query.tenantId`
+
+```ts
+@Get()
+async getData(@TenantId() tenantId: string) {
+  return this.service.getData(tenantId);
+}
+```
+
+### @UserId()
+
+Extracts the user ID from the authenticated request.
+
+```ts
+@Get('profile')
+async getProfile(@UserId() userId: string, @TenantId() tenantId: string) {
+  return this.service.getUserProfile(tenantId, userId);
+}
+```
+
+### @TenantContext()
+
+Extracts the complete tenant context including tenantId, userId, role, and user object.
+
+```ts
+@Get()
+async getData(@TenantContext() context: { tenantId: string, userId: string, role: TenantUserRole, user: any }) {
+  return this.service.getData(context);
+}
+```
+
+### @Roles(...roles)
+
+Specifies required roles for accessing an endpoint. Must be used with `TenantRoleGuard`.
+
+```ts
+@Post('invite')
+@Roles(TenantUserRole.OWNER, TenantUserRole.ADMIN)
+@UseGuards(TenantGuard, TenantRoleGuard)
+async inviteUser(@TenantId() tenantId: string, @Body() dto: InviteUserDto) {
+  return this.service.inviteUser(tenantId, dto);
+}
+```
+
+---
+
+## Configuration Settings
+
+The module provides the following configurable settings through `SettingsService`:
+
+### General Settings
+- **ENABLED**: Enable/disable the tenant module (boolean)
+- **MAX_TENANTS**: Maximum number of tenants allowed (0 = unlimited)
+- **DEFAULT_PLAN**: Default subscription plan for new tenants
+- **TRIAL_DAYS**: Number of trial days for new tenants (default: 14)
+
+### Feature Settings
+- **CUSTOM_DOMAIN**: Allow custom domains for tenants
+- **API_ACCESS**: Allow API access for tenants
+
+---
+
+## Enums and Types
+
+### TenantUserRole
+```ts
+enum TenantUserRole {
+  OWNER = 'owner',
+  ADMIN = 'admin',
+  MEMBER = 'member',
+  VIEWER = 'viewer',
+}
+```
+
+### TenantUserStatus
+```ts
+enum TenantUserStatus {
+  ACTIVE = 'active',
+  INVITED = 'invited',
+  SUSPENDED = 'suspended',
+}
+```
+
+### TENANT_PLAN
+```ts
+enum TENANT_PLAN {
+  FREE = 'free',
+  STARTER = 'starter',
+  PROFESSIONAL = 'professional',
+  ENTERPRISE = 'enterprise',
+}
+```
+
+### TENANT_STATUS
+```ts
+enum TENANT_STATUS {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+  SUSPENDED = 'suspended',
+  TRIAL = 'trial',
+}
+```
+
+---
+
+## Integration with @venturialstd/core
+
+This package uses `@venturialstd/core` for:
+- **SharedModule**: Core functionality and configuration
+- **SettingsService**: Dynamic settings management
+- **AppLogger**: Structured logging
+
+---
+
+## TypeORM Integration
+
+The package extends `TypeOrmCrudService` from `@dataui/crud-typeorm`, providing:
+- Standard CRUD operations
+- Query builders
+- Pagination support
+- Filtering and sorting capabilities
+
+---
+
+## Example: Complete SaaS Implementation with User Isolation
+
+```ts
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { TenantModule, TenantService, TenantUserService } from '@venturialstd/tenant';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({
+      // Your database configuration
+    }),
+    TenantModule,
+  ],
+})
+export class AppModule {}
+
+// Service for onboarding new tenants
+@Injectable()
+export class SaasService {
+  constructor(
+    private readonly tenantService: TenantService,
+    private readonly tenantUserService: TenantUserService,
+  ) {}
+
+  async onboardNewTenant(data: any, ownerId: string) {
+    // Create tenant
+    const tenant = await this.tenantService.createTenant(
+      data.companyName,
+      data.slug,
+      data.domain,
+      data.description,
+      ownerId
+    );
+
+    // Add owner to tenant
+    await this.tenantUserService.addUserToTenant(
+      tenant.id,
+      ownerId,
+      TenantUserRole.OWNER
+    );
+
+    // Set as primary owner
+    await this.tenantUserService.setPrimaryOwner(tenant.id, ownerId);
+
+    // Configure tenant settings
+    await this.tenantService.updateTenantSettings(tenant.id, {
+      theme: data.preferences?.theme || 'light',
+      locale: data.preferences?.locale || 'en',
+      notifications: true,
+    });
+
+    return tenant;
+  }
+
+  async inviteTeamMember(
+    tenantId: string,
+    userId: string,
+    invitedBy: string,
+    role: TenantUserRole = TenantUserRole.MEMBER
+  ) {
+    // Verify inviter is admin or owner
+    const isAdmin = await this.tenantUserService.isAdminOrOwner(tenantId, invitedBy);
+    if (!isAdmin) {
+      throw new ForbiddenException('Only admins can invite team members');
+    }
+
+    // Invite user
+    await this.tenantUserService.inviteUserToTenant(
+      tenantId,
+      userId,
+      role,
+      invitedBy
+    );
+
+    // Send invitation email (implement your email service)
+    // await this.emailService.sendInvitation(userId, tenantId);
+  }
+
+  async checkTenantAccess(tenantId: string, userId: string) {
+    const tenant = await this.tenantService.repo.findOne({
+      where: { id: tenantId }
+    });
+
+    if (!tenant.isActive) {
+      throw new UnauthorizedException('Tenant is inactive');
+    }
+
+    const hasAccess = await this.tenantUserService.hasAccess(tenantId, userId);
+    if (!hasAccess) {
+      throw new UnauthorizedException('No access to this tenant');
+    }
+
+    const hasSubscription = await this.tenantService.hasActiveSubscription(tenantId);
+    if (!hasSubscription) {
+      throw new UnauthorizedException('Subscription expired');
+    }
+
+    return true;
+  }
+}
+
+// Controller with tenant isolation
+@Controller('projects')
+@UseGuards(TenantGuard)
+export class ProjectsController {
+  constructor(private readonly projectsService: ProjectsService) {}
+
+  @Get()
+  async list(@TenantId() tenantId: string, @UserId() userId: string) {
+    // Automatically scoped to tenant
+    return this.projectsService.findByTenant(tenantId);
+  }
+
+  @Post()
+  async create(
+    @TenantId() tenantId: string,
+    @UserId() userId: string,
+    @Body() dto: CreateProjectDto
+  ) {
+    return this.projectsService.create(tenantId, userId, dto);
+  }
+
+  @Delete(':id')
+  @Roles(TenantUserRole.OWNER, TenantUserRole.ADMIN)
+  @UseGuards(TenantRoleGuard)
+  async delete(@TenantId() tenantId: string, @Param('id') id: string) {
+    // Only owners and admins can delete
+    return this.projectsService.delete(tenantId, id);
+  }
+}
+```
+
+---
+
+## Database Migrations
+
+The package requires two database tables: `tenant` and `tenant_user`. Create migrations for both:
+
+### Tenant Table Migration
+
+```bash
+npm run typeorm migration:create -- -n CreateTenant
+```
+
+```ts
+import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm';
+
+export class CreateTenant1234567890123 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.createTable(
+      new Table({
+        name: 'tenant',
+        columns: [
+          { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'uuid_generate_v4()' },
+          { name: 'name', type: 'varchar', isUnique: true },
+          { name: 'slug', type: 'varchar', isUnique: true },
+          { name: 'domain', type: 'varchar', isNullable: true },
+          { name: 'description', type: 'text', isNullable: true },
+          { name: 'isActive', type: 'boolean', default: true },
+          { name: 'settings', type: 'jsonb', isNullable: true },
+          { name: 'ownerId', type: 'varchar', isNullable: true },
+          { name: 'plan', type: 'varchar', isNullable: true },
+          { name: 'trialEndsAt', type: 'timestamptz', isNullable: true },
+          { name: 'subscriptionEndsAt', type: 'timestamptz', isNullable: true },
+          { name: 'createdAt', type: 'timestamptz', default: 'CURRENT_TIMESTAMP' },
+          { name: 'updatedAt', type: 'timestamptz', default: 'CURRENT_TIMESTAMP' },
+        ],
+      }),
+      true,
+    );
+
+    await queryRunner.createIndex('tenant', new TableIndex({ name: 'IDX_tenant_slug', columnNames: ['slug'] }));
+    await queryRunner.createIndex('tenant', new TableIndex({ name: 'IDX_tenant_domain', columnNames: ['domain'] }));
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropTable('tenant');
+  }
+}
+```
+
+### TenantUser Table Migration
+
+```bash
+npm run typeorm migration:create -- -n CreateTenantUser
+```
+
+```ts
+import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm';
+
+export class CreateTenantUser1234567890124 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.createTable(
+      new Table({
+        name: 'tenant_user',
+        columns: [
+          { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'uuid_generate_v4()' },
+          { name: 'tenantId', type: 'uuid' },
+          { name: 'userId', type: 'uuid' },
+          { name: 'role', type: 'enum', enum: ['owner', 'admin', 'member', 'viewer'], default: "'member'" },
+          { name: 'status', type: 'enum', enum: ['active', 'invited', 'suspended'], default: "'active'" },
+          { name: 'isPrimary', type: 'boolean', default: false },
+          { name: 'invitedBy', type: 'uuid', isNullable: true },
+          { name: 'invitedAt', type: 'timestamptz', isNullable: true },
+          { name: 'joinedAt', type: 'timestamptz', isNullable: true },
+          { name: 'permissions', type: 'jsonb', isNullable: true },
+          { name: 'createdAt', type: 'timestamptz', default: 'CURRENT_TIMESTAMP' },
+          { name: 'updatedAt', type: 'timestamptz', default: 'CURRENT_TIMESTAMP' },
+        ],
+      }),
+      true,
+    );
+
+    await queryRunner.createIndex('tenant_user', new TableIndex({ name: 'IDX_tenant_user_tenantId', columnNames: ['tenantId'] }));
+    await queryRunner.createIndex('tenant_user', new TableIndex({ name: 'IDX_tenant_user_userId', columnNames: ['userId'] }));
+    await queryRunner.createIndex('tenant_user', new TableIndex({ name: 'IDX_tenant_user_tenant_user', columnNames: ['tenantId', 'userId'], isUnique: true }));
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropTable('tenant_user');
+  }
+}
+```
+
+Run migrations:
+
+```bash
+npm run typeorm migration:run
+```
+
+---
+
+## Testing
+
+The module includes an isolated NestJS test environment for testing all functionality without integrating it into your main application.
+
+### Setup Test Environment
+
+1. **Copy environment configuration**:
+   ```bash
+   cd test
+   cp .env.example .env
+   ```
+
+2. **Configure your database** in `test/.env`:
+   ```env
+   DB_HOST=localhost
+   DB_PORT=5432
+   DB_USERNAME=postgres
+   DB_PASSWORD=postgres
+   DB_DATABASE=tenant_test
+   TEST_PORT=3001
+   ```
+
+3. **Install dependencies** (from the module root):
+   ```bash
+   npm install
+   ```
+
+4. **Create test database**:
+   ```bash
+   createdb tenant_test
+   # or using psql:
+   psql -U postgres -c "CREATE DATABASE tenant_test;"
+   ```
+
+### Run Test Server
+
+Start the test server (runs on port 3001 by default):
+
+```bash
+npm run test:dev
+```
+
+Or with auto-reload on file changes:
+
+```bash
+npm run test:watch
+```
+
+The server will display all available endpoints:
+
+```
+🚀 Tenant Module Test Server running on: http://localhost:3001
+
+📋 Available endpoints:
+  Tenant Management:
+    POST   /tenants                        - Create tenant
+    GET    /tenants                        - Get all tenants
+    GET    /tenants/active                 - Get active tenants
+    GET    /tenants/owner/:ownerId         - Get tenants by owner
+    GET    /tenants/slug/:slug             - Get tenant by slug
+    GET    /tenants/domain/:domain         - Get tenant by domain
+    GET    /tenants/:id                    - Get tenant by ID
+    PUT    /tenants/:id/settings           - Update tenant settings
+    PUT    /tenants/:id/status             - Update tenant status
+    PUT    /tenants/:id/plan               - Update tenant plan
+    GET    /tenants/:id/trial              - Check if trial is active
+    GET    /tenants/:id/subscription       - Check if subscription is active
+    DELETE /tenants/:id                    - Delete tenant
+
+  User-Tenant Management:
+    POST   /tenant-users/add               - Add user to tenant
+    POST   /tenant-users/invite            - Invite user to tenant
+    GET    /tenant-users/tenant/:tenantId  - Get all users in tenant
+    GET    /tenant-users/user/:userId      - Get user's tenants
+    PUT    /tenant-users/update-role       - Update user role
+    POST   /tenant-users/transfer-ownership - Transfer ownership
+    ... and more
+```
+
+### Testing with HTTP Requests
+
+Use the provided `test/requests.http` file with REST Client (VS Code extension) or Postman:
+
+1. **Create a tenant**:
+   ```http
+   POST http://localhost:3001/tenants
+   Content-Type: application/json
+
+   {
+     "name": "Acme Corporation",
+     "slug": "acme-corp",
+     "ownerId": "user-123",
+     "domain": "acme.example.com"
+   }
+   ```
+
+2. **Add users to tenant**:
+   ```http
+   POST http://localhost:3001/tenant-users/add
+   Content-Type: application/json
+
+   {
+     "tenantId": "<tenant-id>",
+     "userId": "user-456",
+     "role": "member"
+   }
+   ```
+
+3. **Test role-based access**:
+   ```http
+   GET http://localhost:3001/tenant-users/role/<tenant-id>/user-456
+   ```
+
+See `test/requests.http` for a complete set of example requests.
+
+### Test Structure
+
+```
+test/
+├── .env.example              # Environment configuration template
+├── main.ts                   # Test server bootstrap
+├── test-app.module.ts        # Test NestJS application module
+├── requests.http             # HTTP request examples
+└── controllers/
+    ├── tenant-test.controller.ts      # Tenant CRUD endpoints
+    └── tenant-user-test.controller.ts # User-tenant management endpoints
+```
+
+---
+
+## Development
+
+### Build the package
+
+```bash
+npm run build
+```
+
+### Publish the package
+
+```bash
+npm run release:patch
+```
+
+---
+
+## Dependencies
+
+- `@nestjs/common` ^11.0.11
+- `@nestjs/typeorm` ^10.0.0
+- `@venturialstd/core` ^1.0.16
+- `@dataui/crud-typeorm` (for CRUD operations)
+- `typeorm` ^0.3.20
+- `class-validator` ^0.14.1
+- `class-transformer` ^0.5.1
+
+---
+
+## License
+
+This package is part of the Venturial ecosystem and follows the organization's licensing.
+
+---
+
+## Support
+
+For issues, questions, or contributions, please contact the Venturial development team.