@omnibase/core-js 0.7.2 → 0.7.4

package/dist/chunk-DQBFDKRC.js

@@ -0,0 +1,641 @@
+// src/tenants/invites.ts
+var TenantInviteManager = class {
+  /**
+   * Creates a new TenantInviteManager instance
+   *
+   * Initializes the manager with the provided Omnibase client for making
+   * authenticated API requests to tenant invitation endpoints.
+   *
+   * @param omnibaseClient - Configured Omnibase client instance
+   *
+   * @group Tenant Invitations
+   */
+  constructor(omnibaseClient) {
+    this.omnibaseClient = omnibaseClient;
+  }
+  /**
+   * Accepts a tenant invitation using a secure token
+   *
+   * Processes a tenant invitation by validating the provided token and
+   * adding the authenticated user to the specified tenant. The invitation
+   * token is consumed during this process and cannot be used again.
+   *
+   * The function performs several validations:
+   * - Verifies the token exists and is valid
+   * - Checks that the invitation hasn't expired
+   * - Ensures the invitation hasn't already been used
+   * - Confirms the user is authenticated via session cookies
+   *
+   * Upon successful acceptance, the user is granted access to the tenant
+   * with the role specified in the original invitation. The invitation
+   * record is marked as used and cannot be accepted again.
+   *
+   * @param token - The secure invitation token from the email invitation
+   *
+   * @returns Promise resolving to the tenant ID and success confirmation
+   *
+   * @throws {Error} When the token parameter is missing or empty
+   * @throws {Error} When the invitation token is invalid or expired
+   * @throws {Error} When the invitation has already been accepted
+   * @throws {Error} When the user is not authenticated
+   * @throws {Error} When the API request fails due to network issues
+   * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
+   *
+   * @example
+   * ```typescript
+   * // Typically called from an invitation link like:
+   * // https://app.com/accept-invite?token=inv_secure_token_abc123
+   *
+   * const urlParams = new URLSearchParams(window.location.search);
+   * const inviteToken = urlParams.get('token');
+   *
+   * if (inviteToken) {
+   *   try {
+   *     const result = await inviteManager.accept(inviteToken);
+   *
+   *     // Success - redirect to tenant dashboard
+   *     console.log(`Successfully joined tenant: ${result.data.tenant_id}`);
+   *     window.location.href = `/dashboard?tenant=${result.data.tenant_id}`;
+   *   } catch (error) {
+   *     console.error('Failed to accept invitation:', error.message);
+   *   }
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Invitations
+   */
+  async accept(token) {
+    if (!token) {
+      throw new Error("Invite token is required");
+    }
+    const requestBody = {
+      token
+    };
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/invites/accept`,
+        {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody),
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to accept invite: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error accepting tenant invite:", error);
+      throw error;
+    }
+  }
+  /**
+   * Creates a new user invitation for the active tenant
+   *
+   * Generates a secure invitation that allows a user to join the currently active
+   * tenant with the defined role. The invitation is sent to the provided email address
+   * and includes a time-limited token for security. The invite URL will be automatically
+   * appended with ?token=XYZ when sent to the user.
+   *
+   * The function creates the invitation record in the database and triggers an email
+   * notification to the invited user. The invitation expires after 7 days and can only
+   * be used once.
+   *
+   * Only existing tenant members with appropriate permissions (invite_user permission)
+   * can create invitations. The inviter's authentication and tenant context are validated
+   * via HTTP-only cookies sent with the request.
+   *
+   * @param inviteData - Configuration object for the invitation
+   * @param inviteData.email - Email address of the user to invite
+   * @param inviteData.role - Role the user will have after joining (e.g., 'member', 'admin')
+   * @param inviteData.invite_url - Base URL for the invitation link (will be appended with ?token=XYZ)
+   *
+   * @returns Promise resolving to the created invitation with secure token
+   *
+   * @throws {Error} When required fields (email, role, invite_url) are missing or empty
+   * @throws {Error} When the user doesn't have permission to invite users to the tenant
+   * @throws {Error} When the API request fails due to network issues
+   * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
+   *
+   * @example
+   * ```typescript
+   * const invite = await inviteManager.create({
+   *   email: 'colleague@company.com',
+   *   role: 'member',
+   *   invite_url: 'https://yourapp.com/accept-invite'
+   * });
+   *
+   * console.log(`Invite sent to: ${invite.data.invite.email}`);
+   * console.log(`Invite token: ${invite.data.invite.token}`);
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Invitations
+   */
+  async create(inviteData) {
+    if (!inviteData.email || !inviteData.role || !inviteData.invite_url) {
+      throw new Error(
+        "Missing data in `create` - email, role, and invite_url are required"
+      );
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/invites`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(inviteData),
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to create invite: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error creating tenant user invite:", error);
+      throw error;
+    }
+  }
+};
+
+// src/tenants/management.ts
+var TenantManger = class {
+  /**
+   * Creates a new TenantManger instance
+   *
+   * Initializes the manager with the provided Omnibase client for making
+   * authenticated API requests to tenant management endpoints.
+   *
+   * @param omnibaseClient - Configured Omnibase client instance
+   *
+   * @group Tenant Management
+   */
+  constructor(omnibaseClient) {
+    this.omnibaseClient = omnibaseClient;
+  }
+  /**
+   * Creates a new tenant in the multi-tenant system
+   *
+   * Establishes a new tenant with integrated Stripe billing setup and assigns
+   * the specified user as the tenant owner. The operation creates the necessary
+   * database records and returns a JWT token that enables Row-Level Security
+   * access to the tenant's isolated data.
+   *
+   * The function automatically handles Stripe customer creation for billing
+   * integration and sets up the initial tenant configuration. The returned
+   * token should be stored securely for subsequent API calls.
+   *
+   * @param tenantData - Configuration object for the new tenant
+   * @param tenantData.name - Display name for the tenant organization
+   * @param tenantData.billing_email - Email address for Stripe billing notifications
+   * @param tenantData.user_id - Unique identifier of the user who will own this tenant
+   *
+   * @returns Promise resolving to the created tenant with authentication token
+   *
+   * @throws {Error} When required fields (name, user_id) are missing or empty
+   * @throws {Error} When the API request fails due to network issues
+   * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
+   *
+   * @example
+   * ```typescript
+   * const newTenant = await tenantManager.createTenant({
+   *   name: 'Acme Corporation',
+   *   billing_email: 'billing@acme.com',
+   *   user_id: 'user_123'
+   * });
+   *
+   * console.log(`Tenant created: ${newTenant.data.tenant.id}`);
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Management
+   */
+  async createTenant(tenantData) {
+    if (!tenantData.name || !tenantData.user_id) {
+      throw new Error("Name and user_id are required");
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(`/api/v1/tenants`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(tenantData),
+        credentials: "include"
+      });
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to create tenant: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error creating tenant:", error);
+      throw error;
+    }
+  }
+  /**
+   * Permanently deletes a tenant and all associated data
+   *
+   * ⚠️ **WARNING: This operation is irreversible and will permanently delete:**
+   * - The tenant record and all metadata
+   * - All user memberships and invitations for this tenant
+   * - All tenant-specific data protected by row-level security
+   * - Any tenant-related billing information
+   * - All tenant configuration and settings
+   *
+   * **Access Control:**
+   * Only tenant owners can delete a tenant. This operation requires:
+   * - User must be authenticated
+   * - User must have 'owner' role for the specified tenant
+   * - Tenant must exist and be accessible to the user
+   *
+   * **Security Considerations:**
+   * - All tenant data is immediately and permanently removed
+   * - Other tenant members lose access immediately
+   * - Any active sessions for this tenant are invalidated
+   * - Billing subscriptions are cancelled (if applicable)
+   * - Audit logs for deletion are maintained for compliance
+   *
+   * @returns Promise resolving to a confirmation message
+   *
+   * @throws {Error} When the tenantId parameter is missing or empty
+   * @throws {Error} When the user is not authenticated
+   * @throws {Error} When the user is not an owner of the specified tenant
+   * @throws {Error} When the tenant doesn't exist or is not accessible
+   * @throws {Error} When the API request fails due to network issues
+   * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
+   *
+   * @example
+   * ```typescript
+   * // Always confirm before deleting
+   * const userConfirmed = confirm(
+   *   'Are you sure you want to delete this tenant? This action cannot be undone.'
+   * );
+   *
+   * if (userConfirmed) {
+   *   try {
+   *     const result = await tenantManager.deleteTenant();
+   *     console.log(result.data.message);
+   *
+   *     // Redirect user away from deleted tenant
+   *     window.location.href = '/dashboard';
+   *   } catch (error) {
+   *     console.error('Failed to delete tenant:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Management
+   */
+  async deleteTenant() {
+    try {
+      const response = await this.omnibaseClient.fetch(`/api/v1/tenants`, {
+        method: "DELETE",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "include"
+      });
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to delete tenant: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error deleting tenant:", error);
+      throw error;
+    }
+  }
+  /**
+   * Switches the user's active tenant context
+   *
+   * Changes the user's active tenant to the specified tenant ID, updating
+   * their authentication context and permissions. This function is essential
+   * for multi-tenant applications where users belong to multiple tenants
+   * and need to switch between them.
+   *
+   * The function performs several operations:
+   * - Validates that the user has access to the specified tenant
+   * - Updates the user's active tenant in their session
+   * - Generates a new JWT token with updated tenant claims
+   * - Updates any cached tenant-specific data
+   *
+   * After switching tenants, all subsequent API calls will be made within
+   * the context of the new active tenant, with row-level security policies
+   * applied accordingly. The new JWT token should be used for all future
+   * authenticated requests.
+   *
+   * @param tenantId - The ID of the tenant to switch to (must be a tenant the user belongs to)
+   *
+   * @returns Promise resolving to a new JWT token and success confirmation
+   *
+   * @throws {Error} When the tenantId parameter is missing or empty
+   * @throws {Error} When the user doesn't have access to the specified tenant
+   * @throws {Error} When the user is not authenticated
+   * @throws {Error} When the specified tenant doesn't exist
+   * @throws {Error} When the API request fails due to network issues
+   * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
+   *
+   * @example
+   * ```typescript
+   * const result = await tenantManager.switchActiveTenant('tenant_xyz789');
+   *
+   * // Store the new token for future requests
+   * console.log(`Switched to tenant. New token: ${result.data.token}`);
+   *
+   * // Now all API calls will be in the context of tenant_xyz789
+   * const tenantData = await getCurrentTenantData();
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Management
+   */
+  async switchActiveTenant(tenantId) {
+    if (!tenantId) {
+      throw new Error("Tenant ID is required");
+    }
+    const requestBody = {
+      tenant_id: tenantId
+    };
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/switch-active`,
+        {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody),
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to switch tenant: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error switching active tenant:", error);
+      throw error;
+    }
+  }
+};
+
+// src/tenants/user.ts
+var TenantUserManager = class {
+  /**
+   * Creates a new tenant user manager
+   *
+   * @param omnibaseClient - Configured OmnibaseClient instance for API communication
+   *
+   * @group Tenant User Management
+   */
+  constructor(omnibaseClient) {
+    this.omnibaseClient = omnibaseClient;
+  }
+  /**
+   * Removes a user from the active tenant
+   *
+   * This method removes a specified user from the current active tenant. The operation
+   * requires the requesting user to have appropriate permissions (admin or owner role).
+   * The user being removed will lose access to the tenant and all its resources.
+   *
+   * Note: You cannot remove yourself from a tenant using this method. To leave a tenant,
+   * use the appropriate leave or delete tenant operations instead.
+   *
+   * @param data - Request data containing the user ID to remove
+   * @param data.user_id - ID of the user to remove from the tenant
+   *
+   * @returns Promise resolving to an API response confirming the removal
+   *
+   * @throws {Error} When user_id is not provided
+   * @throws {Error} When the API request fails (includes status code and error details)
+   * @throws {Error} When the user doesn't have permission to remove users
+   * @throws {Error} When the specified user is not a member of the tenant
+   *
+   * @example
+   * ```typescript
+   * // Remove a user from the active tenant
+   * try {
+   *   await userManager.remove({ user_id: 'user_abc123' });
+   *   console.log('User removed successfully');
+   * } catch (error) {
+   *   if (error.message.includes('403')) {
+   *     console.error('Insufficient permissions to remove user');
+   *   } else if (error.message.includes('404')) {
+   *     console.error('User not found in tenant');
+   *   } else {
+   *     console.error('Failed to remove user:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant User Management
+   */
+  async remove(data) {
+    if (!data.user_id) {
+      throw new Error("user_id is required");
+    }
+    const response = await this.omnibaseClient.fetch("/api/v1/tenants/users", {
+      method: "DELETE",
+      body: JSON.stringify(data)
+    });
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to delete user from tenant: ${response.status} - ${errorData}`
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * Updates a user's role within the active tenant
+   *
+   * This method changes the role of a specified user in the current active tenant. The operation
+   * requires the requesting user to have appropriate permissions (typically admin or owner role).
+   * Role updates take effect immediately and affect the user's permissions and access rights
+   * within the tenant.
+   *
+   * Common roles include 'admin', 'member', and 'viewer', but the exact roles available depend
+   * on your tenant's configuration. Changing a user's role will modify their ability to perform
+   * various operations within the tenant.
+   *
+   * @param data - Request data containing the user ID and new role
+   * @param data.user_id - ID of the user whose role is being updated
+   * @param data.role - New role to assign to the user
+   *
+   * @returns Promise resolving to an API response confirming the role update
+   *
+   * @throws {Error} When user_id or role is not provided
+   * @throws {Error} When the API request fails (includes status code and error details)
+   * @throws {Error} When the user doesn't have permission to update roles
+   * @throws {Error} When the specified user is not a member of the tenant
+   * @throws {Error} When the specified role is invalid or not allowed
+   *
+   * @example
+   * ```typescript
+   * // Update a user's role to admin
+   * try {
+   *   const result = await userManager.updateRole({
+   *     user_id: 'user_abc123',
+   *     role: 'admin'
+   *   });
+   *   console.log('Role updated successfully:', result.data.message);
+   * } catch (error) {
+   *   if (error.message.includes('403')) {
+   *     console.error('Insufficient permissions to update roles');
+   *   } else if (error.message.includes('404')) {
+   *     console.error('User not found in tenant');
+   *   } else {
+   *     console.error('Failed to update role:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant User Management
+   */
+  async updateRole(data) {
+    if (!data.role || !data.user_id)
+      throw new Error("user_id and role is required");
+    const response = await this.omnibaseClient.fetch("/api/v1/tenants/users", {
+      method: "PUT",
+      body: JSON.stringify(data)
+    });
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to update users role: ${response.status} - ${errorData}`
+      );
+    }
+    return await response.json();
+  }
+};
+
+// src/tenants/handler.ts
+var TenantHandler = class {
+  /**
+   * Creates a new TenantHandler instance
+   *
+   * Initializes the handler with the provided Omnibase client and sets up
+   * the specialized manager instances for tenant and invitation operations.
+   * The client is used for all underlying HTTP requests and authentication.
+   *
+   * @param omnibaseClient - Configured Omnibase client instance
+   *
+   * @example
+   * ```typescript
+   * const client = new OmnibaseClient({
+   *   apiKey: 'your-api-key',
+   *   baseURL: 'https://api.yourapp.com'
+   * });
+   * const tenantHandler = new TenantHandler(client);
+   * ```
+   *
+   * @group Tenant Management
+   */
+  constructor(omnibaseClient) {
+    this.invites = new TenantInviteManager(omnibaseClient);
+    this.manage = new TenantManger(omnibaseClient);
+    this.user = new TenantUserManager(omnibaseClient);
+  }
+  /**
+   * Tenant user management operations
+   *
+   * Provides access to operations for managing users within tenants, including
+   * removing users from the active tenant. All operations respect user permissions
+   * and tenant ownership rules.
+   *
+   * @example
+   * ```typescript
+   * // Remove a user from the active tenant
+   * await tenantHandler.user.remove({ user_id: 'user_123' });
+   * ```
+   *
+   * @since 0.6.0
+   * @group Tenant Management
+   */
+  user;
+  /**
+   * Core tenant management operations
+   *
+   * Provides access to tenant lifecycle operations including creation,
+   * deletion, and active tenant switching. All operations respect user
+   * permissions and tenant ownership rules.
+   *
+   * @example
+   * ```typescript
+   * // Create a new tenant
+   * const tenant = await tenantHandler.manage.createTenant({
+   *   name: 'New Company',
+   *   billing_email: 'billing@newcompany.com',
+   *   user_id: 'user_456'
+   * });
+   *
+   * // Switch to the tenant
+   * await tenantHandler.manage.switchActiveTenant(tenant.data.tenant.id);
+   *
+   * // Delete the tenant (owner only)
+   * await tenantHandler.manage.deleteTenant(tenant.data.tenant.id);
+   * ```
+   */
+  manage;
+  /**
+   * Tenant invitation management operations
+   *
+   * Provides access to user invitation functionality including creating
+   * invitations for new users and accepting existing invitations.
+   * Supports role-based access control and secure token-based workflows.
+   *
+   * @example
+   * ```typescript
+   * // Create an invitation
+   * const invite = await tenantHandler.invites.create({
+   *   email: 'newuser@company.com',
+   *   role: 'admin',
+   *   invite_url: 'https://yourapp.com/accept-invite'
+   * });
+   *
+   * // Accept an invitation (from the invited user's session)
+   * const result = await tenantHandler.invites.accept('invite_token_xyz');
+   * ```
+   */
+  invites;
+};
+
+export {
+  TenantHandler
+};