@omnibase/core-js 0.4.2 → 0.5.1

package/dist/tenants/index.cjs

@@ -20,189 +20,567 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/tenants/index.ts
 var tenants_exports = {};
 __export(tenants_exports, {
-  acceptTenantInvite: () => acceptTenantInvite,
-  createTenant: () => createTenant,
-  createTenantUserInvite: () => createTenantUserInvite,
-  deleteTenant: () => deleteTenant,
-  switchActiveTenant: () => switchActiveTenant
+  TenantHandler: () => TenantHandler
 });
 module.exports = __toCommonJS(tenants_exports);
 
-// src/tenants/switch-tenant.ts
-async function switchActiveTenant(tenantId) {
-  const baseUrl = process.env.OMNIBASE_AUTH_URL;
-  if (!baseUrl) {
-    throw new Error("OMNIBASE_AUTH_URL is not configured");
+// 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;
   }
-  if (!tenantId) {
-    throw new Error("Tenant ID is required");
+  /**
+   * 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
+   * Basic invitation acceptance:
+   * ```typescript
+   * const result = await acceptTenantInvite('inv_secure_token_abc123');
+   *
+   * console.log(`Successfully joined tenant: ${result.data.tenant_id}`);
+   * // User can now access tenant resources
+   * await switchActiveTenant(result.data.tenant_id);
+   * ```
+   *
+   * @example
+   * Handling the invitation flow:
+   * ```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 acceptTenantInvite(inviteToken);
+   *
+   *     // Success - redirect to tenant dashboard
+   *     window.location.href = `/dashboard?tenant=${result.data.tenant_id}`;
+   *   } catch (error) {
+   *     console.error('Failed to accept invitation:', error.message);
+   *     // Show error to user
+   *   }
+   * }
+   * ```
+   *
+   *
+   * @since 1.0.0
+   * @public
+   * @group User Management
+   */
+  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;
+    }
   }
-  const requestBody = {
-    tenant_id: tenantId
-  };
-  try {
-    const response = await fetch(`${baseUrl}/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}`
+  /**
+   * Creates a new user invitation for a specific tenant
+   *
+   * Generates a secure invitation that allows a user to join the specified
+   * tenant with the defined role. The invitation is sent to the provided
+   * email address and includes a time-limited token for security.
+   *
+   * The function creates the invitation record in the database and can
+   * trigger email notifications (depending on server configuration).
+   * The invitation expires after a predefined time period and can only
+   * be used once.
+   *
+   * Only existing tenant members with appropriate permissions can create
+   * invitations. The inviter's authentication is validated via HTTP-only
+   * cookies sent with the request.
+   *
+   * @param tenantId - Unique identifier of the tenant to invite the user to
+   * @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')
+   *
+   * @returns Promise resolving to the created invitation with secure token
+   *
+   * @throws {Error} When tenantId parameter is missing or empty
+   * @throws {Error} When required fields (email, role) 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
+   * Basic invitation creation:
+   * ```typescript
+   * const invite = await createTenantUserInvite('tenant_123', {
+   *   email: 'colleague@company.com',
+   *   role: 'member'
+   * });
+   *
+   * console.log(`Invite sent to: ${invite.data.invite.email}`);
+   * // The invite token can be used to generate invitation links
+   * const inviteLink = `https://app.com/accept-invite?token=${invite.data.invite.token}`;
+   * ```
+   *
+   * @example
+   * Creating admin invitation:
+   * ```typescript
+   * const adminInvite = await createTenantUserInvite('tenant_456', {
+   *   email: 'admin@company.com',
+   *   role: 'admin'
+   * });
+   *
+   * // Admin users get elevated permissions
+   * console.log(`Admin invite created with ID: ${adminInvite.data.invite.id}`);
+   * ```
+   *
+   *
+   * @since 1.0.0
+   * @public
+   * @group User Management
+   */
+  async create(tenantId, inviteData) {
+    if (!tenantId) {
+      throw new Error("Tenant ID is required");
+    }
+    if (!inviteData.email || !inviteData.role) {
+      throw new Error("Email and role are required");
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/${tenantId}/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;
     }
-    const data = await response.json();
-    return data;
-  } catch (error) {
-    console.error("Error switching active tenant:", error);
-    throw error;
   }
-}
+};
 
-// src/tenants/create-invite.ts
-async function createTenantUserInvite(tenantId, inviteData) {
-  const baseUrl = process.env.OMNIBASE_AUTH_URL;
-  if (!baseUrl) {
-    throw new Error("OMNIBASE_AUTH_URL is not configured");
-  }
-  if (!tenantId) {
-    throw new Error("Tenant ID is required");
+// src/tenants/tenants.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;
   }
-  if (!inviteData.email || !inviteData.role) {
-    throw new Error("Email and role are required");
-  }
-  try {
-    const response = await fetch(
-      `${baseUrl}/api/v1/tenants/${tenantId}/invites`,
-      {
+  /**
+   * 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
+   * Basic tenant creation:
+   * ```typescript
+   * const newTenant = await createTenant({
+   *   name: 'Acme Corporation',
+   *   billing_email: 'billing@acme.com',
+   *   user_id: 'user_123'
+   * });
+   *
+   * console.log(`Created tenant: ${newTenant.data.tenant.name}`);
+   * // Store the token for authenticated requests
+   * localStorage.setItem('tenant_token', newTenant.data.token);
+   * ```
+   *
+   *
+   * @since 1.0.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(inviteData),
+        body: JSON.stringify(tenantData),
         credentials: "include"
+      });
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to create tenant: ${response.status} - ${errorData}`
+        );
       }
-    );
-    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:", error);
+      throw error;
     }
-    const data = await response.json();
-    return data;
-  } catch (error) {
-    console.error("Error creating tenant user invite:", error);
-    throw error;
-  }
-}
-
-// src/tenants/create-tenant.ts
-async function createTenant(tenantData) {
-  const baseUrl = process.env.OMNIBASE_AUTH_URL;
-  if (!baseUrl) {
-    throw new Error("OMNIBASE_AUTH_URL is not configured");
   }
-  if (!tenantData.name || !tenantData.user_id) {
-    throw new Error("Name and user_id are required");
-  }
-  try {
-    const response = await fetch(`${baseUrl}/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}`
+  /**
+   * 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
+   *
+   * @param tenantId - The unique identifier of the tenant to delete
+   *
+   * @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
+   * Basic tenant deletion with confirmation:
+   * ```typescript
+   * const tenantToDelete = 'tenant_abc123';
+   *
+   * // 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 deleteTenant(tenantToDelete);
+   *     console.log(result.data.message); // "Tenant deleted successfully"
+   *
+   *     // Redirect user away from deleted tenant
+   *     window.location.href = '/dashboard';
+   *   } catch (error) {
+   *     console.error('Failed to delete tenant:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   * @public
+   * @group Tenant Management
+   */
+  async deleteTenant(tenantId) {
+    if (!tenantId) {
+      throw new Error("Tenant ID is required");
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/${tenantId}`,
+        {
+          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;
     }
-    const data = await response.json();
-    return data;
-  } catch (error) {
-    console.error("Error creating tenant:", error);
-    throw error;
   }
-}
-
-// src/tenants/accept-invite.ts
-async function acceptTenantInvite(token) {
-  const baseUrl = process.env.OMNIBASE_AUTH_URL;
-  if (!baseUrl) {
-    throw new Error("OMNIBASE_AUTH_URL is not configured");
-  }
-  if (!token) {
-    throw new Error("Invite token is required");
-  }
-  const requestBody = {
-    token
-  };
-  try {
-    const response = await fetch(`${baseUrl}/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}`
+  /**
+   * 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
+   * Basic tenant switching:
+   * ```typescript
+   * const result = await switchActiveTenant('tenant_xyz789');
+   *
+   * // Now all API calls will be in the context of tenant_xyz789
+   * const tenantData = await getCurrentTenantData();
+   * ```
+   *
+   * @example
+   * Using with tenant-aware data fetching:
+   * ```typescript
+   * // Switch tenant and immediately fetch tenant-specific data
+   * const switchAndLoadTenant = async (tenantId: string) => {
+   *   try {
+   *     // Switch to new tenant context
+   *     const switchResult = await switchActiveTenant(tenantId);
+   *
+   *     // Update authentication token
+   *     setAuthToken(switchResult.data.token);
+   *
+   *     // Fetch data in new tenant context
+   *     const [tenantInfo, userPermissions, tenantSettings] = await Promise.all([
+   *       getTenantInfo(),
+   *       getUserPermissions(),
+   *       getTenantSettings()
+   *     ]);
+   *
+   *     return {
+   *       tenant: tenantInfo,
+   *       permissions: userPermissions,
+   *       settings: tenantSettings
+   *     };
+   *   } catch (error) {
+   *     console.error('Failed to switch tenant and load data:', error);
+   *     throw error;
+   *   }
+   * };
+   * ```
+   *
+   * @since 1.0.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;
     }
-    const data = await response.json();
-    return data;
-  } catch (error) {
-    console.error("Error accepting tenant invite:", error);
-    throw error;
   }
-}
+};
 
-// src/tenants/delete-tenant.ts
-async function deleteTenant(tenantId) {
-  const baseUrl = process.env.OMNIBASE_AUTH_URL;
-  if (!baseUrl) {
-    throw new Error("OMNIBASE_AUTH_URL is not configured");
+// 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.omnibaseClient = omnibaseClient;
+    this.invites = new TenantInviteManager(this.omnibaseClient);
+    this.tenants = new TenantManger(this.omnibaseClient);
   }
-  if (!tenantId) {
-    throw new Error("Tenant ID is required");
-  }
-  try {
-    const response = await fetch(`${baseUrl}/api/v1/tenants/${tenantId}`, {
-      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;
-  }
-}
+  /**
+   * 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.tenants.createTenant({
+   *   name: 'New Company',
+   *   billing_email: 'billing@newcompany.com',
+   *   user_id: 'user_456'
+   * });
+   *
+   * // Switch to the tenant
+   * await tenantHandler.tenants.switchActiveTenant(tenant.data.tenant.id);
+   *
+   * // Delete the tenant (owner only)
+   * await tenantHandler.tenants.deleteTenant(tenant.data.tenant.id);
+   * ```
+   */
+  tenants;
+  /**
+   * 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('tenant_123', {
+   *   email: 'newuser@company.com',
+   *   role: 'admin'
+   * });
+   *
+   * // Accept an invitation (from the invited user's session)
+   * const result = await tenantHandler.invites.accept('invite_token_xyz');
+   * ```
+   */
+  invites;
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  acceptTenantInvite,
-  createTenant,
-  createTenantUserInvite,
-  deleteTenant,
-  switchActiveTenant
+  TenantHandler
 });