@omnibase/core-js 0.1.5 → 0.1.6

package/dist/tenants/index.d.cts

@@ -1,13 +1,121 @@
 /**
- * Return type of the `acceptTenantInvite` function
+ * Request data for accepting a tenant invitation
+ *
+ * Contains the secure token that was provided in the invitation.
+ * This token is validated server-side to ensure the invitation
+ * is legitimate, not expired, and hasn't been used before.
+ *
+ * @example
+ * ```typescript
+ * const acceptData: AcceptTenantInviteRequest = {
+ *   token: 'inv_secure_token_abc123xyz'
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group User Management
+ */
+type AcceptTenantInviteRequest = {
+    /** Secure invitation token from the email invitation */
+    token: string;
+};
+/**
+ * Response structure for accepting a tenant invitation
+ *
+ * Contains the ID of the tenant that the user has successfully joined
+ * along with a confirmation message. After accepting an invitation,
+ * the user becomes a member of the tenant with the role specified
+ * in the original invitation.
+ *
+ * @example
+ * ```typescript
+ * const response: AcceptTenantInviteResponse = {
+ *   data: {
+ *     tenant_id: 'tenant_abc123',
+ *     message: 'Successfully joined tenant'
+ *   },
+ *   status: 200
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group User Management
  */
 type AcceptTenantInviteResponse = ApiResponse<{
+    /** ID of the tenant the user has joined */
     tenant_id: string;
+    /** Success message confirming the invitation acceptance */
     message: string;
+    /** JWT token for postgrest RLS */
+    token: string;
 }>;
 /**
- * Accept a tenant invite using token
- * Calls PUT /api/v1/tenants/invites/accept
+ * 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 OMNIBASE_API_URL environment variable is not configured
+ * @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
  */
 declare function acceptTenantInvite(token: string): Promise<ApiResponse<{
     tenant_id: string;
@@ -15,110 +123,562 @@ declare function acceptTenantInvite(token: string): Promise<ApiResponse<{
 }>>;
 
 /**
- * Return type of the `createTenantUserInvite` function
+ * Response structure for tenant user invite creation
+ *
+ * Contains the newly created invite information including the secure token
+ * that will be sent to the invitee. The invite has an expiration time and
+ * can only be used once to join the specified tenant.
+ *
+ * @example
+ * ```typescript
+ * const response: CreateTenantUserInviteResponse = {
+ *   data: {
+ *     invite: {
+ *       id: 'invite_123',
+ *       tenant_id: 'tenant_abc',
+ *       email: 'colleague@company.com',
+ *       role: 'member',
+ *       token: 'inv_secure_token_xyz',
+ *       expires_at: '2024-02-15T10:30:00Z'
+ *     },
+ *     message: 'Invite created successfully'
+ *   },
+ *   status: 201
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group User Management
  */
 type CreateTenantUserInviteResponse = ApiResponse<{
+    /** The newly created tenant invite */
     invite: TenantInvite;
+    /** Success message confirming invite creation */
     message: string;
 }>;
 /**
- * The TenantInvite Schema that maps directly to `auth.tenant_invites`
+ * Tenant invitation entity structure
+ *
+ * Represents a pending invitation for a user to join a specific tenant
+ * with a defined role. The invite contains a secure token that expires
+ * after a certain time period and can only be used once.
+ *
+ * @example
+ * ```typescript
+ * const invite: TenantInvite = {
+ *   id: 'invite_abc123',
+ *   tenant_id: 'tenant_xyz789',
+ *   email: 'newuser@company.com',
+ *   role: 'member',
+ *   token: 'inv_secure_abc123xyz',
+ *   inviter_id: 'user_owner123',
+ *   expires_at: '2024-02-01T12:00:00Z',
+ *   created_at: '2024-01-25T12:00:00Z',
+ *   used_at: undefined // null until invite is accepted
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group User Management
  */
 interface TenantInvite {
+    /** Unique identifier for the invitation */
     id: string;
+    /** ID of the tenant the user is being invited to */
     tenant_id: string;
+    /** Email address of the invited user */
     email: string;
+    /** Role the user will have in the tenant (e.g., 'owner', 'admin', 'member') */
     role: string;
+    /** Secure token used to accept the invitation */
     token: string;
+    /** ID of the user who created this invitation */
     inviter_id: string;
+    /** ISO 8601 timestamp when the invitation expires */
     expires_at: string;
+    /** ISO 8601 timestamp when the invitation was created */
     created_at: string;
+    /** ISO 8601 timestamp when the invitation was accepted (null if unused) */
     used_at?: string;
 }
 /**
- * Invite Data describing who the invite is going to `email` and their
- * role `role`
+ * Required data for creating a tenant user invitation
+ *
+ * Specifies the email address of the user to invite and their intended
+ * role within the tenant. The role determines what permissions the user
+ * will have once they accept the invitation.
+ *
+ * @example
+ * ```typescript
+ * const inviteData: CreateTenantUserInviteRequest = {
+ *   email: 'developer@company.com',
+ *   role: 'admin'
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group User Management
  */
 type CreateTenantUserInviteRequest = {
+    /** Email address of the user to invite */
     email: string;
+    /** Role the invited user will have in the tenant */
     role: string;
 };
 /**
- * Create a tenant user invite
- * Calls POST /api/v1/tenants/{id}/invites
+ * 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 OMNIBASE_API_URL environment variable is not configured
+ * @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
  */
 declare function createTenantUserInvite(tenantId: string, inviteData: CreateTenantUserInviteRequest): Promise<CreateTenantUserInviteResponse>;
 
 /**
- * Return type of the `createTenant` function
+ * Response structure for tenant creation operations
+ *
+ * Contains the newly created tenant information along with an authentication
+ * token that provides Row-Level Security (RLS) access to the tenant's data.
+ * The token should be stored securely and used for subsequent API calls
+ * that require tenant-specific access.
+ *
+ * @example
+ * ```typescript
+ * const response: CreateTenantResponse = {
+ *   data: {
+ *     tenant: {
+ *       id: 'tenant_123',
+ *       name: 'My Company',
+ *       stripe_customer_id: 'cus_abc123'
+ *     },
+ *     message: 'Tenant created successfully',
+ *     token: 'eyJhbGciOiJIUzI1NiIs...'
+ *   },
+ *   status: 201
+ * };
+ * ```
  *
- * The `token` is the authenticated users `postgrest_jwt` cookie for RLS policies specific to the active tenant
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
  */
 type CreateTenantResponse = ApiResponse<{
+    /** The newly created tenant object */
     tenant: Tenant;
+    /** Success message confirming tenant creation */
     message: string;
+    /** JWT token for RLS policies specific to the active tenant */
     token: string;
 }>;
 /**
- * The Tenant Schema that maps directly to `auth.tenants`
+ * Tenant entity structure that maps to the database schema
+ *
+ * Represents a tenant in the multi-tenant system with billing integration
+ * via Stripe. Each tenant can have multiple users with different roles
+ * and maintains its own isolated data through RLS policies.
+ *
+ * @example
+ * ```typescript
+ * const tenant: Tenant = {
+ *   id: 'tenant_abc123',
+ *   name: 'Acme Corporation',
+ *   stripe_customer_id: 'cus_stripe123',
+ *   type: 'business',
+ *   created_at: '2024-01-15T10:30:00Z',
+ *   updated_at: '2024-01-15T10:30:00Z'
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
  */
 type Tenant = {
+    /** Unique identifier for the tenant */
     id: string;
+    /** Display name of the tenant organization */
     name: string;
+    /** Associated Stripe customer ID for billing */
     stripe_customer_id: string;
+    /** Type of tenant (e.g., 'individual', 'organization') */
     type: string;
+    /** ISO 8601 timestamp when the tenant was created */
     created_at: string;
+    /** ISO 8601 timestamp when the tenant was last updated */
     updated_at: string;
 };
 /**
- * The data required to create a tenant.
+ * Required data for creating a new tenant
+ *
+ * Contains the essential information needed to establish a new tenant
+ * in the system, including billing setup and initial user assignment.
+ *
+ * @example
+ * ```typescript
+ * const tenantData: CreateTenantRequest = {
+ *   name: 'My New Company',
+ *   billing_email: 'billing@mynewcompany.com',
+ *   user_id: 'user_abc123'
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
  */
 type CreateTenantRequest = {
+    /** Name of the tenant organization */
     name: string;
+    /** Email address for billing notifications */
     billing_email: string;
+    /** ID of the user who will own the tenant */
     user_id: string;
 };
 /**
- * Create a new tenant
+ * 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 OMNIBASE_API_URL environment variable is not configured
+ * @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'
+ * });
  *
- * Calls POST /api/v1/tenants
+ * 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
  */
 declare function createTenant(tenantData: CreateTenantRequest): Promise<CreateTenantResponse>;
 
 /**
- * Return type of the `deleteTenant` function
+ * Response structure for deleting a tenant
+ *
+ * Contains a confirmation message indicating successful tenant deletion.
+ * This response is only returned after the tenant and all associated data
+ * have been permanently removed from the system.
+ *
+ * @example
+ * ```typescript
+ * const response: DeleteTenantResponse = {
+ *   data: {
+ *     message: 'Tenant deleted successfully'
+ *   },
+ *   status: 200
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
  */
 type DeleteTenantResponse = ApiResponse<{
+    /** Confirmation message indicating successful deletion */
     message: string;
 }>;
 /**
- * Delete a tenant (only owners can delete)
+ * 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 OMNIBASE_API_URL environment variable is not configured
+ * @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';
  *
- * Calls DELETE /api/v1/tenants/{id}
+ * // 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
  */
 declare function deleteTenant(tenantId: string): Promise<DeleteTenantResponse>;
 
 /**
- * Base API Response structure for API
+ * Base API Response structure for all tenant operations
+ *
+ * This generic type defines the standard response format returned by all
+ * tenant-related API endpoints. It provides a consistent structure for
+ * handling both successful responses and error conditions across the SDK.
+ *
+ * @template T - The type of the response data payload
+ *
+ * @example
+ * Successful response:
+ * ```typescript
+ * const response: ApiResponse<{ tenant: Tenant }> = {
+ *   data: { tenant: { id: '123', name: 'My Company' } },
+ *   status: 200
+ * };
+ * ```
+ *
+ * @example
+ * Error response:
+ * ```typescript
+ * const response: ApiResponse<never> = {
+ *   status: 400,
+ *   error: 'Invalid tenant name provided'
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
  */
 type ApiResponse<T> = {
+    /**
+     * Response data payload (present only on successful operations)
+     * Contains the actual data returned by the API endpoint
+     */
     data?: T;
+    /**
+     * HTTP status code indicating the result of the operation
+     * @example 200 for success, 400 for client errors, 500 for server errors
+     */
     status: number;
+    /**
+     * Error message (present only when operation fails)
+     * Provides human-readable description of what went wrong
+     */
     error?: string;
 };
 
 /**
- * Return type of the `switchActiveTenant` function
+ * Response structure for switching the active tenant
+ *
+ * Contains a new JWT token that includes the updated tenant context
+ * and a confirmation message. The new token should replace the previous
+ * token for all subsequent API calls to ensure requests are made within
+ * the context of the newly active tenant.
+ *
+ * The token includes updated tenant-specific claims and permissions,
+ * ensuring that row-level security policies are enforced correctly
+ * for the new active tenant context.
+ *
+ * @example
+ * ```typescript
+ * const response: SwitchActiveTenantResponse = {
+ *   data: {
+ *     token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+ *     message: 'Active tenant switched successfully'
+ *   },
+ *   status: 200
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
  */
 type SwitchActiveTenantResponse = ApiResponse<{
+    /** New JWT token with updated tenant context */
     token: string;
+    /** Success message confirming the tenant switch */
     message: string;
 }>;
 /**
- * Switch the user's active tenant
+ * 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 OMNIBASE_API_URL environment variable is not configured
+ * @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;
+ *   }
+ * };
+ * ```
  *
- * Calls PUT /api/v1/tenants/switch-active
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
  */
 declare function switchActiveTenant(tenantId: string): Promise<SwitchActiveTenantResponse>;
 
-export { type AcceptTenantInviteResponse, type ApiResponse, type CreateTenantRequest, type CreateTenantResponse, type CreateTenantUserInviteRequest, type CreateTenantUserInviteResponse, type DeleteTenantResponse, type SwitchActiveTenantResponse, type Tenant, type TenantInvite, acceptTenantInvite, createTenant, createTenantUserInvite, deleteTenant, switchActiveTenant };
+export { type AcceptTenantInviteRequest, type AcceptTenantInviteResponse, type ApiResponse, type CreateTenantRequest, type CreateTenantResponse, type CreateTenantUserInviteRequest, type CreateTenantUserInviteResponse, type DeleteTenantResponse, type SwitchActiveTenantResponse, type Tenant, type TenantInvite, acceptTenantInvite, createTenant, createTenantUserInvite, deleteTenant, switchActiveTenant };