@venturialstd/organization 0.0.1

package/README.md

@@ -0,0 +1,678 @@
+# @venturialstd/organization
+
+Organization Management Module for Venturial - A NestJS module for managing organizations and organization members with role-based access control.
+
+## 📋 Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Module Structure](#module-structure)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Entities](#entities)
+- [API Reference](#api-reference)
+- [Enums & Constants](#enums--constants)
+- [Guards & Decorators](#guards--decorators)
+- [Test Server](#test-server)
+- [NPM Scripts](#npm-scripts)
+- [Usage Examples](#usage-examples)
+
+---
+
+## ✨ Features
+
+- 🏢 **Organization Management**: Complete CRUD operations
+- 👥 **Member Management**: Add, invite, remove organization members
+- 🔐 **Role-Based Access**: Owner, Admin, Member, Viewer roles
+- ⚙️ **Settings System**: Configurable organization settings
+- 🛡️ **Guards & Decorators**: Request-level access control
+- 🔄 **TypeORM Integration**: Full database support with migrations
+- 📦 **Fully Typed**: Complete TypeScript support
+- 🧪 **Test Infrastructure**: Standalone test server on port 3002
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @venturialstd/organization
+```
+
+### Peer Dependencies
+
+```json
+{
+  "@nestjs/common": "^11.0.11",
+  "@nestjs/core": "^11.0.5",
+  "@nestjs/typeorm": "^10.0.0",
+  "@venturialstd/core": "^1.0.16",
+  "class-transformer": "^0.5.1",
+  "class-validator": "^0.14.1",
+  "typeorm": "^0.3.20"
+}
+```
+
+---
+
+## 📁 Module Structure
+
+```
+src/organization/
+├── package.json                           # Module configuration
+├── tsconfig.json                         # TypeScript configuration
+├── README.md                             # This file
+├── .npmignore                            # NPM publish exclusions
+├── src/                                  # Source code
+│   ├── constants/
+│   │   ├── organization.constant.ts      # Enums (roles, status)
+│   │   └── organization.settings.constant.ts  # Settings keys
+│   ├── decorators/
+│   │   ├── organization.decorator.ts     # @OrganizationId(), @UserId(), etc.
+│   │   └── roles.decorator.ts            # @Roles() decorator
+│   ├── entities/
+│   │   ├── organization.entity.ts        # Organization entity
+│   │   └── organization-user.entity.ts   # OrganizationUser entity
+│   ├── guards/
+│   │   └── organization.guard.ts         # OrganizationGuard, OrganizationRoleGuard
+│   ├── services/
+│   │   ├── organization.service.ts       # Organization CRUD service
+│   │   └── organization-user.service.ts  # User-Organization service
+│   ├── settings/
+│   │   └── organization.settings.ts      # Module settings definition
+│   ├── organization.module.ts            # NestJS module
+│   └── index.ts                          # Public exports
+└── test/                                 # Test infrastructure
+    ├── controllers/
+    │   ├── organization-test.controller.ts
+    │   └── organization-user-test.controller.ts
+    ├── migrations/                       # Database migrations
+    ├── .env.example                      # Environment template
+    ├── data-source.ts                    # TypeORM DataSource
+    ├── test-app.module.ts                # Test app module
+    └── main.ts                           # Test server bootstrap
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { OrganizationModule } from '@venturialstd/organization';
+
+@Module({
+  imports: [OrganizationModule],
+})
+export class AppModule {}
+```
+
+### 2. Use the Services
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { OrganizationService, OrganizationUserService } from '@venturialstd/organization';
+
+@Injectable()
+export class YourService {
+  constructor(
+    private readonly organizationService: OrganizationService,
+    private readonly organizationUserService: OrganizationUserService,
+  ) {}
+
+  async createOrganization() {
+    const organization = await this.organizationService.createOrganization(
+      'My Organization',
+      'my-org',
+      'example.com',
+      'Organization description',
+      'user-id-123'
+    );
+    
+    return organization;
+  }
+
+  async addMember() {
+    return this.organizationUserService.addUserToOrganization(
+      'org-id',
+      'user-id',
+      ORGANIZATION_USER_ROLE.MEMBER
+    );
+  }
+}
+```
+
+---
+
+## ⚙️ Configuration
+
+### Development Setup
+
+```bash
+# Navigate to module directory
+cd src/organization
+
+# Install dependencies
+npm install --legacy-peer-deps
+
+# Set up environment
+cp test/.env.example test/.env
+# Edit test/.env with your database credentials
+
+# Generate migration
+npm run migration:generate --name=InitialSchema
+
+# Run migrations
+npm run migration:run
+
+# Start test server
+npm run test:dev
+```
+
+### Environment Variables (test/.env)
+
+```bash
+APP_PORT=3002
+DB_HOST=localhost
+DB_PORT=5433
+DB_NAME=organization_test
+DB_USER=root
+DB_PASS=example
+```
+
+---
+
+## 🗄️ Entities
+
+### Organization
+
+```typescript
+@Entity('organization')
+export class Organization {
+  id: string;                          // UUID primary key
+  name: string;                        // Unique organization name
+  slug: string;                        // Unique URL-friendly slug
+  domain?: string;                     // Optional custom domain
+  description?: string;                // Organization description
+  isActive: boolean;                   // Active/inactive status
+  settings: Record<string, unknown>;   // JSONB settings
+  ownerId?: string;                    // Owner user ID
+  createdAt: Date;                     // Creation timestamp
+  updatedAt: Date;                     // Update timestamp
+}
+```
+
+**Key Features:**
+- Unique `name` and `slug` constraints
+- JSONB `settings` for flexible configuration
+- Soft activation with `isActive` flag
+- Owner tracking via `ownerId`
+
+### OrganizationUser
+
+```typescript
+@Entity('organization_user')
+export class OrganizationUser {
+  id: string;                          // UUID primary key
+  organizationId: string;              // Organization reference (indexed)
+  userId: string;                      // User reference (indexed)
+  role: ORGANIZATION_USER_ROLE;        // User role in organization
+  status: ORGANIZATION_USER_STATUS;    // Member status
+  isPrimary: boolean;                  // Primary owner flag
+  invitedBy?: string;                  // Inviter user ID
+  invitedAt?: Date;                    // Invitation timestamp
+  joinedAt?: Date;                     // Join timestamp
+  permissions: Record<string, unknown>; // JSONB custom permissions
+  createdAt: Date;                     // Creation timestamp
+  updatedAt: Date;                     // Update timestamp
+}
+```
+
+**Key Features:**
+- Unique index on `(organizationId, userId)`
+- Separate indexes on `organizationId` and `userId`
+- Invitation system support
+- Primary owner designation
+- Custom permissions via JSONB
+
+---
+
+## 📖 API Reference
+
+### OrganizationService
+
+#### Create Organization
+```typescript
+createOrganization(
+  name: string,
+  slug: string,
+  domain?: string,
+  description?: string,
+  ownerId?: string
+): Promise<Organization>
+```
+
+#### Find Methods
+```typescript
+getOrganizationBySlug(slug: string): Promise<Organization>
+getOrganizationByDomain(domain: string): Promise<Organization>
+getActiveOrganizations(): Promise<Organization[]>
+getOrganizationsByOwner(ownerId: string): Promise<Organization[]>
+```
+
+#### Update Methods
+```typescript
+updateOrganizationSettings(
+  organizationId: string,
+  settings: Record<string, unknown>
+): Promise<Organization>
+
+setOrganizationStatus(
+  organizationId: string,
+  isActive: boolean
+): Promise<Organization>
+```
+
+### OrganizationUserService
+
+#### Member Management
+```typescript
+addUserToOrganization(
+  organizationId: string,
+  userId: string,
+  role?: ORGANIZATION_USER_ROLE,
+  invitedBy?: string
+): Promise<OrganizationUser>
+
+inviteUserToOrganization(
+  organizationId: string,
+  userId: string,
+  role: ORGANIZATION_USER_ROLE,
+  invitedBy: string
+): Promise<OrganizationUser>
+
+acceptInvitation(
+  organizationId: string,
+  userId: string
+): Promise<OrganizationUser>
+
+removeUserFromOrganization(
+  organizationId: string,
+  userId: string
+): Promise<void>
+```
+
+#### Role Management
+```typescript
+updateUserRole(
+  organizationId: string,
+  userId: string,
+  newRole: ORGANIZATION_USER_ROLE
+): Promise<OrganizationUser>
+
+setPrimaryOwner(
+  organizationId: string,
+  userId: string
+): Promise<OrganizationUser>
+
+transferOwnership(
+  organizationId: string,
+  fromUserId: string,
+  toUserId: string
+): Promise<void>
+```
+
+#### Query Methods
+```typescript
+getUserOrganizations(userId: string): Promise<OrganizationUser[]>
+getOrganizationUsers(organizationId: string): Promise<OrganizationUser[]>
+getActiveOrganizationUsers(organizationId: string): Promise<OrganizationUser[]>
+getUserInvitations(userId: string): Promise<OrganizationUser[]>
+hasAccess(organizationId: string, userId: string): Promise<boolean>
+getUserRole(organizationId: string, userId: string): Promise<ORGANIZATION_USER_ROLE | null>
+```
+
+#### Status Management
+```typescript
+suspendUser(organizationId: string, userId: string): Promise<OrganizationUser>
+reactivateUser(organizationId: string, userId: string): Promise<OrganizationUser>
+```
+
+---
+
+## 🎭 Enums & Constants
+
+### ORGANIZATION_USER_ROLE
+
+```typescript
+enum ORGANIZATION_USER_ROLE {
+  OWNER = 'owner',      // Full control over organization
+  ADMIN = 'admin',      // Administrative access
+  MEMBER = 'member',    // Standard member access
+  VIEWER = 'viewer'     // Read-only access
+}
+```
+
+### ORGANIZATION_USER_STATUS
+
+```typescript
+enum ORGANIZATION_USER_STATUS {
+  ACTIVE = 'active',       // Active member
+  INVITED = 'invited',     // Pending invitation
+  SUSPENDED = 'suspended'  // Suspended member
+}
+```
+
+### Settings Keys
+
+```typescript
+ORGANIZATION_SETTING_KEYS = {
+  GENERAL_MAX_ORGANIZATIONS: 'organization.general.max_organizations',
+  GENERAL_MAX_MEMBERS: 'organization.general.max_members',
+  FEATURES_CUSTOM_DOMAIN: 'organization.features.custom_domain',
+  FEATURES_API_ACCESS: 'organization.features.api_access',
+  FEATURES_SSO: 'organization.features.sso',
+  LIMITS_STORAGE: 'organization.limits.storage_gb',
+  LIMITS_BANDWIDTH: 'organization.limits.bandwidth_gb',
+  LIMITS_PROJECTS: 'organization.limits.projects',
+}
+```
+
+---
+
+## 🛡️ Guards & Decorators
+
+### Decorators
+
+#### @OrganizationId()
+Extract organization ID from request:
+```typescript
+@Get()
+async getData(@OrganizationId() organizationId: string) {
+  return this.service.getData(organizationId);
+}
+```
+
+#### @UserId()
+Extract user ID from request:
+```typescript
+@Get()
+async getData(@UserId() userId: string) {
+  return this.service.getUserData(userId);
+}
+```
+
+#### @OrganizationContext()
+Extract full context:
+```typescript
+@Get()
+async getData(@OrganizationContext() context) {
+  // context = { organizationId, userId, role, user }
+  return this.service.getData(context);
+}
+```
+
+#### @Roles()
+Specify required roles:
+```typescript
+@Roles(ORGANIZATION_USER_ROLE.OWNER, ORGANIZATION_USER_ROLE.ADMIN)
+@UseGuards(OrganizationGuard, OrganizationRoleGuard)
+@Delete(':id')
+async delete() { ... }
+```
+
+### Guards
+
+#### OrganizationGuard
+Ensures user has access to the organization:
+```typescript
+@UseGuards(OrganizationGuard)
+@Get()
+async getData(@OrganizationId() organizationId: string) {
+  return this.service.getData(organizationId);
+}
+```
+
+#### OrganizationRoleGuard
+Enforces role-based access control:
+```typescript
+@Roles(ORGANIZATION_USER_ROLE.OWNER, ORGANIZATION_USER_ROLE.ADMIN)
+@UseGuards(OrganizationGuard, OrganizationRoleGuard)
+@Delete(':id')
+async delete() { ... }
+```
+
+---
+
+## 🧪 Test Server
+
+Start the test server on port **3002**:
+
+```bash
+npm run test:dev
+```
+
+### Available Endpoints
+
+#### Organization Management
+```
+POST   /organizations                      - Create organization
+GET    /organizations                      - Get all organizations
+GET    /organizations/active               - Get active organizations
+GET    /organizations/owner/:ownerId       - Get by owner
+GET    /organizations/slug/:slug           - Get by slug
+GET    /organizations/domain/:domain       - Get by domain
+GET    /organizations/:id                  - Get by ID
+PUT    /organizations/:id/settings         - Update settings
+PUT    /organizations/:id/status           - Update status
+DELETE /organizations/:id                  - Delete organization
+```
+
+#### User-Organization Management
+```
+POST   /organization-users/add                              - Add user
+POST   /organization-users/invite                           - Invite user
+POST   /organization-users/accept-invitation                - Accept invite
+GET    /organization-users/organization/:organizationId     - Get members
+GET    /organization-users/organization/:organizationId/active - Get active members
+GET    /organization-users/user/:userId                     - Get user's organizations
+GET    /organization-users/user/:userId/invitations         - Get invitations
+GET    /organization-users/check-access/:orgId/:userId      - Check access
+GET    /organization-users/role/:orgId/:userId              - Get user role
+PUT    /organization-users/role                             - Update role
+PUT    /organization-users/primary-owner                    - Set primary owner
+POST   /organization-users/transfer-ownership               - Transfer ownership
+PUT    /organization-users/suspend                          - Suspend user
+PUT    /organization-users/reactivate                       - Reactivate user
+DELETE /organization-users/remove                           - Remove user
+```
+
+---
+
+## 📝 NPM Scripts
+
+```bash
+# Build
+npm run build                              # Build TypeScript to dist/
+npm run prepublishOnly                     # Auto-build before publish
+
+# Publishing
+npm run release:patch                      # Build, bump version, publish
+
+# Development
+npm run test:dev                           # Start test server
+npm run test:watch                         # Watch mode for development
+
+# Migrations
+npm run migration:generate --name=Name     # Generate migration
+npm run migration:run                      # Run pending migrations
+npm run migration:revert                   # Revert last migration
+```
+
+---
+
+## 💡 Usage Examples
+
+### Basic Organization Creation
+
+```typescript
+import { OrganizationService } from '@venturialstd/organization';
+
+@Injectable()
+export class MyService {
+  constructor(private orgService: OrganizationService) {}
+
+  async createOrg() {
+    return this.orgService.createOrganization(
+      'Acme Corp',
+      'acme-corp',
+      'acme.com',
+      'A leading company',
+      'owner-user-id-123'
+    );
+  }
+}
+```
+
+### Adding Members with Roles
+
+```typescript
+import { 
+  OrganizationUserService, 
+  ORGANIZATION_USER_ROLE 
+} from '@venturialstd/organization';
+
+@Injectable()
+export class MemberService {
+  constructor(private orgUserService: OrganizationUserService) {}
+
+  async addAdmin(orgId: string, userId: string) {
+    return this.orgUserService.addUserToOrganization(
+      orgId,
+      userId,
+      ORGANIZATION_USER_ROLE.ADMIN,
+      'inviter-user-id'
+    );
+  }
+}
+```
+
+### Protected Endpoints
+
+```typescript
+import { 
+  Controller, 
+  Get, 
+  UseGuards 
+} from '@nestjs/common';
+import {
+  OrganizationGuard,
+  OrganizationRoleGuard,
+  OrganizationId,
+  Roles,
+  ORGANIZATION_USER_ROLE
+} from '@venturialstd/organization';
+
+@Controller('projects')
+@UseGuards(OrganizationGuard)
+export class ProjectController {
+  
+  // Any member can view
+  @Get()
+  async list(@OrganizationId() orgId: string) {
+    return this.service.getProjects(orgId);
+  }
+
+  // Only owners and admins can delete
+  @Delete(':id')
+  @UseGuards(OrganizationRoleGuard)
+  @Roles(ORGANIZATION_USER_ROLE.OWNER, ORGANIZATION_USER_ROLE.ADMIN)
+  async delete(@OrganizationId() orgId: string, @Param('id') id: string) {
+    return this.service.deleteProject(orgId, id);
+  }
+}
+```
+
+### Invitation Flow
+
+```typescript
+@Injectable()
+export class InvitationService {
+  constructor(private orgUserService: OrganizationUserService) {}
+
+  // Step 1: Send invitation
+  async inviteMember(orgId: string, email: string, inviterId: string) {
+    const userId = await this.userService.findByEmail(email);
+    
+    return this.orgUserService.inviteUserToOrganization(
+      orgId,
+      userId,
+      ORGANIZATION_USER_ROLE.MEMBER,
+      inviterId
+    );
+  }
+
+  // Step 2: Get user's pending invitations
+  async getPendingInvites(userId: string) {
+    return this.orgUserService.getUserInvitations(userId);
+  }
+
+  // Step 3: Accept invitation
+  async acceptInvite(orgId: string, userId: string) {
+    return this.orgUserService.acceptInvitation(orgId, userId);
+  }
+}
+```
+
+### Ownership Transfer
+
+```typescript
+@Injectable()
+export class OwnershipService {
+  constructor(private orgUserService: OrganizationUserService) {}
+
+  async transferOwnership(
+    orgId: string,
+    currentOwnerId: string,
+    newOwnerId: string
+  ) {
+    // Verify current owner
+    const isPrimaryOwner = await this.orgUserService
+      .getUserRole(orgId, currentOwnerId);
+    
+    if (isPrimaryOwner !== ORGANIZATION_USER_ROLE.OWNER) {
+      throw new ForbiddenException('Only owner can transfer');
+    }
+
+    // Transfer
+    await this.orgUserService.transferOwnership(
+      orgId,
+      currentOwnerId,
+      newOwnerId
+    );
+  }
+}
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 📧 Support
+
+For issues and questions, please create an issue in the repository.
+
+---
+
+**Built with ❤️ using NestJS and TypeORM**

package/dist/constants/organization.constant.d.ts

@@ -0,0 +1,12 @@
+export declare enum ORGANIZATION_USER_ROLE {
+    OWNER = "owner",
+    ADMIN = "admin",
+    MEMBER = "member",
+    VIEWER = "viewer"
+}
+export declare enum ORGANIZATION_USER_STATUS {
+    ACTIVE = "active",
+    INVITED = "invited",
+    SUSPENDED = "suspended"
+}
+//# sourceMappingURL=organization.constant.d.ts.map

package/dist/constants/organization.constant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization.constant.d.ts","sourceRoot":"","sources":["../../src/constants/organization.constant.ts"],"names":[],"mappings":"AAAA,oBAAY,sBAAsB;IAChC,KAAK,UAAU;IACf,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,oBAAY,wBAAwB;IAClC,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,SAAS,cAAc;CACxB"}

package/dist/constants/organization.constant.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORGANIZATION_USER_STATUS = exports.ORGANIZATION_USER_ROLE = void 0;
+var ORGANIZATION_USER_ROLE;
+(function (ORGANIZATION_USER_ROLE) {
+    ORGANIZATION_USER_ROLE["OWNER"] = "owner";
+    ORGANIZATION_USER_ROLE["ADMIN"] = "admin";
+    ORGANIZATION_USER_ROLE["MEMBER"] = "member";
+    ORGANIZATION_USER_ROLE["VIEWER"] = "viewer";
+})(ORGANIZATION_USER_ROLE || (exports.ORGANIZATION_USER_ROLE = ORGANIZATION_USER_ROLE = {}));
+var ORGANIZATION_USER_STATUS;
+(function (ORGANIZATION_USER_STATUS) {
+    ORGANIZATION_USER_STATUS["ACTIVE"] = "active";
+    ORGANIZATION_USER_STATUS["INVITED"] = "invited";
+    ORGANIZATION_USER_STATUS["SUSPENDED"] = "suspended";
+})(ORGANIZATION_USER_STATUS || (exports.ORGANIZATION_USER_STATUS = ORGANIZATION_USER_STATUS = {}));
+//# sourceMappingURL=organization.constant.js.map

package/dist/constants/organization.constant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization.constant.js","sourceRoot":"","sources":["../../src/constants/organization.constant.ts"],"names":[],"mappings":";;;AAAA,IAAY,sBAKX;AALD,WAAY,sBAAsB;IAChC,yCAAe,CAAA;IACf,yCAAe,CAAA;IACf,2CAAiB,CAAA;IACjB,2CAAiB,CAAA;AACnB,CAAC,EALW,sBAAsB,sCAAtB,sBAAsB,QAKjC;AAED,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAClC,6CAAiB,CAAA;IACjB,+CAAmB,CAAA;IACnB,mDAAuB,CAAA;AACzB,CAAC,EAJW,wBAAwB,wCAAxB,wBAAwB,QAInC"}