@explorins/pers-sdk 2.0.7 → 2.0.11

package/dist/chunks/business-membership-service-D6vaVQTR.js

@@ -0,0 +1,751 @@
+import { b as buildPaginationParams, n as normalizeToPaginated } from './pagination-utils-9vQ-Npkr.js';
+import { MembershipRole, hasMinimumRole } from '@explorins/pers-shared';
+
+/**
+ * Platform-Agnostic Business API Client
+ *
+ * Updated to match the actual RESTful endpoints:
+ * - /businesses for business operations
+ * - /business-types for business type operations (separate controller)
+ */
+class BusinessApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/businesses';
+        this.businessTypesPath = '/businesses/types';
+    }
+    // ==========================================
+    // 🌐 BUSINESS TYPES MANAGEMENT
+    // ==========================================
+    /**
+     * Get all business types (project key required)
+     *
+     * Endpoint: GET /business-types
+     * Auth: @ApiSecurity('projectKey')
+     *
+     * @param options Pagination options (page, limit, sortBy, sortOrder)
+     * @returns Paginated response with business types
+     */
+    async getBusinessTypes(options) {
+        const params = buildPaginationParams(options);
+        const response = await this.apiClient.get(`${this.businessTypesPath}?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
+    /**
+     * ADMIN: Create business type
+     *
+     * Endpoint: POST /business-types
+     * Auth: @TenantAdmin()
+     */
+    async createBusinessType(dto) {
+        return this.apiClient.post(this.businessTypesPath, dto);
+    }
+    /**
+     * ADMIN: Update business type
+     *
+     * Endpoint: PUT /business-types
+     * Auth: @TenantAdmin()
+     */
+    async updateBusinessType(dto) {
+        return this.apiClient.put(this.businessTypesPath, dto);
+    }
+    /**
+     * ADMIN: Delete business type
+     *
+     * Endpoint: DELETE /business-types/{id}
+     * Auth: @TenantAdmin()
+     */
+    async deleteBusinessType(id) {
+        return this.apiClient.delete(`${this.businessTypesPath}/${id}`);
+    }
+    // ==========================================
+    // 🏢 BUSINESS MANAGEMENT
+    // ==========================================
+    /**
+     * Get current business info (business authentication required)
+     *
+     * Endpoint: GET /businesses/me
+     * Auth: @Business()
+     */
+    async getCurrentBusiness() {
+        return this.apiClient.get(`${this.basePath}/me`);
+    }
+    /**
+     * Get all businesses with role-based filtering and pagination
+     *
+     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}&page={number}&limit={number}
+     * Auth: @ApiSecurity('projectKey') (enhanced with role-based filtering)
+     *
+     * Note:
+     * - Project API Key users: Active businesses only (automatically filtered)
+     * - Admin JWT users: Full access with all query parameters
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated list of businesses
+     *
+     * @example
+     * ```typescript
+     * // Get first page of active businesses
+     * const page1 = await businessApi.getBusinesses({ active: true });
+     *
+     * // Get all businesses (admin only) with pagination
+     * const page2 = await businessApi.getBusinesses({
+     *   page: 2,
+     *   limit: 25,
+     *   sanitize: 'soft'
+     * });
+     * ```
+     */
+    async getBusinesses(options) {
+        const params = buildPaginationParams(options);
+        if (options?.active !== undefined) {
+            params.set('active', String(options.active));
+        }
+        if (options?.sanitize) {
+            params.set('sanitize', options.sanitize);
+        }
+        const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
+    /**
+     * Get business by ID
+     *
+     * Endpoint: GET /businesses/{id}
+     * Auth: @ApiSecurity('projectKey')
+     */
+    async getBusinessById(businessId) {
+        return this.apiClient.get(`${this.basePath}/${businessId}`);
+    }
+    /**
+     * Get business by account address
+     *
+     * Endpoint: GET /businesses/account/{accountAddress}
+     * Auth: @ApiSecurity('projectKey')
+     */
+    async getBusinessByAccount(accountAddress) {
+        return this.apiClient.get(`${this.basePath}/account/${accountAddress}`);
+    }
+    // ==========================================
+    // 🔧 ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create business
+     *
+     * Endpoint: POST /businesses
+     * Auth: @TenantAdmin()
+     * Returns: BusinessApiKeyDTO | BusinessTokenBalancesDTO
+     */
+    async createBusiness(dto) {
+        return this.apiClient.post(this.basePath, dto);
+    }
+    /**
+     * ADMIN: Create business by display name (convenience method)
+     */
+    async createBusinessByDisplayName(displayName) {
+        const dto = {
+            displayName,
+            // Add other required fields based on BusinessCreateRequestDTO structure
+        };
+        return this.createBusiness(dto);
+    }
+    /**
+     * ADMIN: Create businesses from URL
+     *
+     * Endpoint: POST /businesses/bulk/url
+     * Auth: @TenantAdmin()
+     */
+    async createBusinessesFromUrl(url) {
+        return this.apiClient.post(`${this.basePath}/bulk/url`, { url });
+    }
+    /**
+     * ADMIN: Update business
+     *
+     * Endpoint: PUT /businesses/{id}
+     * Auth: @TenantAdmin()
+     */
+    async updateBusiness(id, businessData) {
+        return this.apiClient.put(`${this.basePath}/${id}`, businessData);
+    }
+    /**
+     * ADMIN: Toggle business active status
+     *
+     * Endpoint: PUT /businesses/{id}/status
+     * Auth: @TenantAdmin()
+     */
+    async toggleBusinessStatus(id, dto) {
+        return this.apiClient.put(`${this.basePath}/${id}/status`, dto);
+    }
+}
+
+/**
+ * Business Membership API Client
+ *
+ * Platform-agnostic API client for managing business memberships.
+ * Handles user access to businesses with role-based permissions.
+ *
+ * Base Path: /businesses/:businessId/members
+ *
+ * Required Headers:
+ * - Authorization: Bearer <business_jwt_token>
+ * - X-Project-Key: <project_key>
+ *
+ * @example
+ * ```typescript
+ * const membershipApi = new BusinessMembershipApi(apiClient);
+ *
+ * // List all members of a business
+ * const members = await membershipApi.getMembers('business-123');
+ *
+ * // Add a new member
+ * const newMember = await membershipApi.addMember('business-123', {
+ *   userId: 'user-456',
+ *   role: MembershipRole.EDITOR
+ * });
+ * ```
+ *
+ * @version 2.0.0
+ */
+class BusinessMembershipApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    /**
+     * Build the membership endpoint path for a business
+     */
+    getMembersPath(businessId) {
+        return `/businesses/${businessId}/members`;
+    }
+    /**
+     * Build the membership endpoint path for a specific member
+     */
+    getMemberPath(businessId, userId) {
+        return `/businesses/${businessId}/members/${userId}`;
+    }
+    // ==========================================
+    // LIST MEMBERS
+    // ==========================================
+    /**
+     * List all members of a business with pagination
+     *
+     * Endpoint: GET /businesses/:businessId/members
+     * Min Role: VIEWER (any member can view)
+     *
+     * @param businessId - The business UUID
+     * @param options - Pagination and filter options
+     * @returns Paginated array of business memberships with user and role details
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - businessId in path doesn't match JWT's business
+     *
+     * @example
+     * ```typescript
+     * // Get first page of members
+     * const page1 = await membershipApi.getMembers('business-123');
+     * page1.data.forEach(m => console.log(`${m.userId}: ${m.role}`));
+     *
+     * // Filter by role
+     * const admins = await membershipApi.getMembers('business-123', {
+     *   role: MembershipRole.ADMIN,
+     *   page: 1,
+     *   limit: 50
+     * });
+     *
+     * // Paginate through all members
+     * const page2 = await membershipApi.getMembers('business-123', { page: 2 });
+     * ```
+     */
+    async getMembers(businessId, options) {
+        const params = buildPaginationParams(options);
+        if (options?.role) {
+            params.set('role', options.role);
+        }
+        const response = await this.apiClient.get(`${this.getMembersPath(businessId)}?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
+    // ==========================================
+    // ADD MEMBER
+    // ==========================================
+    /**
+     * Add a member to a business
+     *
+     * Endpoint: POST /businesses/:businessId/members
+     * Min Role: ADMIN
+     *
+     * @param businessId - The business UUID
+     * @param request - The add member request with userId and optional role
+     * @returns The created business membership
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN or higher)
+     * @throws {PersApiError} 404 - User not found
+     * @throws {PersApiError} 409 - User is already a member
+     *
+     * @example
+     * ```typescript
+     * const newMember = await membershipApi.addMember('business-123', {
+     *   userId: 'user-456',
+     *   role: MembershipRole.EDITOR
+     * });
+     * ```
+     */
+    async addMember(businessId, request) {
+        return this.apiClient.post(this.getMembersPath(businessId), request);
+    }
+    /**
+     * Add a member to a business with explicit parameters
+     *
+     * Convenience method that constructs the request DTO internally.
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to add
+     * @param role - The role to assign (defaults to VIEWER)
+     * @returns The created business membership
+     *
+     * @example
+     * ```typescript
+     * const member = await membershipApi.addMemberByUserId(
+     *   'business-123',
+     *   'user-456',
+     *   MembershipRole.EDITOR
+     * );
+     * ```
+     */
+    async addMemberByUserId(businessId, userId, role = MembershipRole.VIEWER) {
+        return this.addMember(businessId, { userId, role });
+    }
+    // ==========================================
+    // UPDATE MEMBER ROLE
+    // ==========================================
+    /**
+     * Update a member's role in a business
+     *
+     * Endpoint: PUT /businesses/:businessId/members/:userId
+     * Min Role: ADMIN
+     *
+     * Business Rules:
+     * - Cannot demote the last OWNER (must transfer ownership first)
+     * - Can only assign roles up to your own level (ADMIN cannot create OWNER)
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to update
+     * @param request - The update request with new role
+     * @returns The updated business membership
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN or higher)
+     * @throws {PersApiError} 404 - Membership not found
+     * @throws {PersApiError} 400 - Cannot demote last OWNER
+     *
+     * @example
+     * ```typescript
+     * const updated = await membershipApi.updateMemberRole(
+     *   'business-123',
+     *   'user-456',
+     *   { role: MembershipRole.ADMIN }
+     * );
+     * ```
+     */
+    async updateMemberRole(businessId, userId, request) {
+        return this.apiClient.put(this.getMemberPath(businessId, userId), request);
+    }
+    /**
+     * Update a member's role with explicit parameters
+     *
+     * Convenience method that constructs the request DTO internally.
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to update
+     * @param role - The new role to assign
+     * @returns The updated business membership
+     *
+     * @example
+     * ```typescript
+     * const updated = await membershipApi.setMemberRole(
+     *   'business-123',
+     *   'user-456',
+     *   MembershipRole.ADMIN
+     * );
+     * ```
+     */
+    async setMemberRole(businessId, userId, role) {
+        return this.updateMemberRole(businessId, userId, { role });
+    }
+    // ==========================================
+    // REMOVE MEMBER
+    // ==========================================
+    /**
+     * Remove a member from a business
+     *
+     * Endpoint: DELETE /businesses/:businessId/members/:userId
+     * Min Role: ADMIN
+     *
+     * Business Rules:
+     * - Cannot remove the last OWNER
+     * - Cannot remove yourself (use leave endpoint or transfer ownership)
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to remove
+     * @returns Success confirmation
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN or higher)
+     * @throws {PersApiError} 404 - Membership not found
+     * @throws {PersApiError} 400 - Cannot remove last OWNER
+     *
+     * @example
+     * ```typescript
+     * const result = await membershipApi.removeMember('business-123', 'user-456');
+     * if (result.success) {
+     *   console.log('Member removed successfully');
+     * }
+     * ```
+     */
+    async removeMember(businessId, userId) {
+        return this.apiClient.delete(this.getMemberPath(businessId, userId));
+    }
+}
+
+/**
+ * Platform-Agnostic Business Service
+ *
+ * Contains business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class BusinessService {
+    constructor(businessApi) {
+        this.businessApi = businessApi;
+    }
+    /**
+     * Get all active businesses with pagination
+     * @deprecated Use getBusinesses({ active: true }) for more control
+     */
+    async getActiveBusinesses(options) {
+        return this.businessApi.getBusinesses({ active: true, ...options });
+    }
+    /**
+     * Get all business types with pagination
+     */
+    async getBusinessTypes(options) {
+        return this.businessApi.getBusinessTypes(options);
+    }
+    /**
+     * Get business by ID
+     */
+    async getBusinessById(businessId) {
+        return this.businessApi.getBusinessById(businessId);
+    }
+    /**
+     * Get business by account address
+     */
+    async getBusinessByAccount(accountAddress) {
+        return this.businessApi.getBusinessByAccount(accountAddress);
+    }
+    /**
+     * Get businesses by type (client-side filtering)
+     * @deprecated Consider implementing server-side filtering for better performance
+     */
+    async getBusinessesByType(typeId, options) {
+        const response = await this.getActiveBusinesses(options);
+        const filtered = response.data.filter((business) => business.businessType && business.businessType.id === parseInt(typeId));
+        return {
+            data: filtered,
+            pagination: {
+                ...response.pagination,
+                total: filtered.length,
+                pages: Math.ceil(filtered.length / (response.pagination.limit || 20))
+            }
+        };
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get all businesses with pagination (active and inactive)
+     */
+    async getBusinesses(options) {
+        return this.businessApi.getBusinesses(options);
+    }
+    /**
+     * ADMIN: Create business by display name
+     */
+    async createBusinessByDisplayName(displayName) {
+        return this.businessApi.createBusinessByDisplayName(displayName);
+    }
+    /**
+     * ADMIN: Update business
+     */
+    async updateBusiness(id, businessData) {
+        return this.businessApi.updateBusiness(id, businessData);
+    }
+    /**
+     * ADMIN: Toggle business active status
+     */
+    async toggleBusinessStatus(id, dto) {
+        return this.businessApi.toggleBusinessStatus(id, dto);
+    }
+}
+
+/**
+ * Business Membership Service
+ *
+ * Platform-agnostic service for managing business memberships.
+ * Provides business logic layer on top of the API client with
+ * convenience methods and role-based utilities.
+ *
+ * @example
+ * ```typescript
+ * const service = new BusinessMembershipService(membershipApi);
+ *
+ * // Get members with admin permissions
+ * const admins = await service.getMembersByRole('business-123', MembershipRole.ADMIN);
+ *
+ * // Check permissions
+ * const canManage = service.canManageMembers(MembershipRole.ADMIN); // true
+ * ```
+ *
+ * @version 2.0.0
+ */
+class BusinessMembershipService {
+    constructor(membershipApi) {
+        this.membershipApi = membershipApi;
+    }
+    // ==========================================
+    // MEMBER LISTING
+    // ==========================================
+    /**
+     * Get all members of a business with pagination
+     *
+     * @param businessId - The business UUID
+     * @param options - Pagination options
+     * @returns Paginated response with business memberships
+     */
+    async getMembers(businessId, options) {
+        return this.membershipApi.getMembers(businessId, options);
+    }
+    /**
+     * Get members filtered by role (client-side filtering)
+     * @deprecated Consider server-side role filtering for better performance
+     */
+    async getMembersByRole(businessId, role, options) {
+        const response = await this.getMembers(businessId, options);
+        const filtered = response.data.filter((m) => m.role === role);
+        return {
+            data: filtered,
+            pagination: {
+                ...response.pagination,
+                total: filtered.length,
+                pages: Math.ceil(filtered.length / (response.pagination.limit || 20))
+            }
+        };
+    }
+    /**
+     * Get members with at least a minimum role level
+     *
+     * Uses the role hierarchy: OWNER > ADMIN > EDITOR > VIEWER
+     *
+     * @param businessId - The business UUID
+     * @param minRole - The minimum role level
+     * @returns Array of memberships with role >= minRole
+     *
+     * @example
+     * ```typescript
+     * // Get all members who can manage content (EDITOR and above)
+     * const editors = await service.getMembersWithMinRole('biz-123', MembershipRole.EDITOR);
+     * ```
+     */
+    async getMembersWithMinRole(businessId, minRole) {
+        const response = await this.getMembers(businessId);
+        return response.data.filter((m) => hasMinimumRole(m.role, minRole));
+    }
+    /**
+     * Get a specific member by user ID
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to find
+     * @returns The membership if found, undefined otherwise
+     */
+    async getMemberByUserId(businessId, userId) {
+        const response = await this.getMembers(businessId);
+        return response.data.find((m) => m.userId === userId);
+    }
+    /**
+     * Count members by role
+     *
+     * @param businessId - The business UUID
+     * @returns Object with count per role
+     *
+     * @example
+     * ```typescript
+     * const counts = await service.getMemberCountsByRole('biz-123');
+     * // { OWNER: 1, ADMIN: 2, EDITOR: 5, VIEWER: 10 }
+     * ```
+     */
+    async getMemberCountsByRole(businessId) {
+        const response = await this.getMembers(businessId);
+        const counts = {
+            [MembershipRole.OWNER]: 0,
+            [MembershipRole.ADMIN]: 0,
+            [MembershipRole.EDITOR]: 0,
+            [MembershipRole.VIEWER]: 0,
+        };
+        for (const member of response.data) {
+            if (member.role in counts) {
+                counts[member.role]++;
+            }
+        }
+        return counts;
+    }
+    // ==========================================
+    // MEMBER MANAGEMENT
+    // ==========================================
+    /**
+     * Add a new member to a business
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to add
+     * @param role - The role to assign (defaults to VIEWER)
+     * @returns The created membership
+     */
+    async addMember(businessId, userId, role = MembershipRole.VIEWER) {
+        return this.membershipApi.addMemberByUserId(businessId, userId, role);
+    }
+    /**
+     * Update a member's role
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to update
+     * @param newRole - The new role to assign
+     * @returns The updated membership
+     */
+    async updateMemberRole(businessId, userId, newRole) {
+        return this.membershipApi.setMemberRole(businessId, userId, newRole);
+    }
+    /**
+     * Remove a member from a business
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to remove
+     * @returns Success confirmation
+     */
+    async removeMember(businessId, userId) {
+        return this.membershipApi.removeMember(businessId, userId);
+    }
+    /**
+     * Promote a member to a higher role
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to promote
+     * @param targetRole - The target role (must be higher than current)
+     * @returns The updated membership
+     * @throws Error if target role is not higher than current
+     */
+    async promoteMember(businessId, userId, targetRole) {
+        const member = await this.getMemberByUserId(businessId, userId);
+        if (!member) {
+            throw new Error(`Member not found: ${userId}`);
+        }
+        // Validate that target role is actually a promotion
+        if (!hasMinimumRole(targetRole, member.role) || targetRole === member.role) {
+            throw new Error(`Cannot promote to ${targetRole}: current role is ${member.role}`);
+        }
+        return this.updateMemberRole(businessId, userId, targetRole);
+    }
+    /**
+     * Demote a member to a lower role
+     *
+     * Note: Cannot demote the last OWNER
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to demote
+     * @param targetRole - The target role (must be lower than current)
+     * @returns The updated membership
+     * @throws Error if target role is not lower than current
+     */
+    async demoteMember(businessId, userId, targetRole) {
+        const member = await this.getMemberByUserId(businessId, userId);
+        if (!member) {
+            throw new Error(`Member not found: ${userId}`);
+        }
+        // Validate that target role is actually a demotion
+        if (hasMinimumRole(targetRole, member.role)) {
+            throw new Error(`Cannot demote to ${targetRole}: current role is ${member.role}`);
+        }
+        return this.updateMemberRole(businessId, userId, targetRole);
+    }
+    // ==========================================
+    // PERMISSION UTILITIES
+    // ==========================================
+    /**
+     * Check if a role can view members (any member)
+     */
+    canViewMembers(role) {
+        return role !== null;
+    }
+    /**
+     * Check if a role can manage members (ADMIN or higher)
+     */
+    canManageMembers(role) {
+        return role !== null && hasMinimumRole(role, MembershipRole.ADMIN);
+    }
+    /**
+     * Check if a role can edit content (EDITOR or higher)
+     */
+    canEditContent(role) {
+        return role !== null && hasMinimumRole(role, MembershipRole.EDITOR);
+    }
+    /**
+     * Check if a role can delete the business (OWNER only)
+     */
+    canDeleteBusiness(role) {
+        return role === MembershipRole.OWNER;
+    }
+    /**
+     * Get permissions object for a role
+     *
+     * Useful for UI components to conditionally render based on permissions.
+     *
+     * @param role - The membership role (or null if not a member)
+     * @returns Object with boolean permission flags
+     *
+     * @example
+     * ```typescript
+     * const perms = service.getPermissions(MembershipRole.EDITOR);
+     * // { canViewMembers: true, canManageMembers: false, canEditContent: true, canDeleteBusiness: false }
+     *
+     * if (perms.canManageMembers) {
+     *   showAddMemberButton();
+     * }
+     * ```
+     */
+    getPermissions(role) {
+        return {
+            canViewMembers: this.canViewMembers(role),
+            canManageMembers: this.canManageMembers(role),
+            canEditContent: this.canEditContent(role),
+            canDeleteBusiness: this.canDeleteBusiness(role),
+        };
+    }
+    /**
+     * Check if a role can assign another role
+     *
+     * Rule: Can only assign roles up to your own level
+     * (ADMIN cannot create OWNER, but OWNER can create anything)
+     *
+     * @param assignerRole - The role of the user assigning
+     * @param targetRole - The role being assigned
+     * @returns true if the assigner can assign the target role
+     */
+    canAssignRole(assignerRole, targetRole) {
+        // Must be at least ADMIN to assign any role
+        if (!hasMinimumRole(assignerRole, MembershipRole.ADMIN)) {
+            return false;
+        }
+        // Can only assign roles up to your own level
+        return hasMinimumRole(assignerRole, targetRole);
+    }
+}
+
+export { BusinessApi as B, BusinessMembershipApi as a, BusinessService as b, BusinessMembershipService as c };
+//# sourceMappingURL=business-membership-service-D6vaVQTR.js.map