@omnibase/core-js 0.4.1 → 0.5.0

package/dist/tenants/index.d.cts

@@ -1,4 +1,53 @@
-import { A as ApiResponse } from '../types-DgsX5kVK.cjs';
+import { PermissionsClient } from '../permissions/index.cjs';
+import '@ory/client';
+
+/**
+ * Base API Response structure for all operations
+ *
+ * This generic type defines the standard response format returned by all
+ * 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;
+};
 
 /**
  * Request data for accepting a tenant invitation
@@ -53,74 +102,6 @@ type AcceptTenantInviteResponse = ApiResponse<{
     /** JWT token for postgrest RLS */
     token: string;
 }>;
-/**
- * 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_AUTH_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<AcceptTenantInviteResponse>;
-
 /**
  * Response structure for tenant user invite creation
  *
@@ -182,7 +163,7 @@ type CreateTenantUserInviteResponse = ApiResponse<{
  * @public
  * @group User Management
  */
-interface TenantInvite {
+type TenantInvite = {
     /** Unique identifier for the invitation */
     id: string;
     /** ID of the tenant the user is being invited to */
@@ -201,7 +182,7 @@ interface TenantInvite {
     created_at: string;
     /** ISO 8601 timestamp when the invitation was accepted (null if unused) */
     used_at?: string;
-}
+};
 /**
  * Required data for creating a tenant user invitation
  *
@@ -228,66 +209,240 @@ type CreateTenantUserInviteRequest = {
     role: string;
 };
 /**
- * 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.
+ * Tenant invitation management handler
  *
- * Only existing tenant members with appropriate permissions can create
- * invitations. The inviter's authentication is validated via HTTP-only
- * cookies sent with the request.
+ * This class handles all tenant invitation operations including creating
+ * invitations for new users and processing invitation acceptances. It provides
+ * a secure, email-based invitation workflow with role-based access control
+ * and token-based security.
  *
- * @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')
+ * The manager handles:
+ * - Creating secure invitations with time-limited tokens
+ * - Processing invitation acceptances with validation
+ * - Email workflow integration (server-side)
+ * - Role assignment and permission setup
+ * - Security validation and anti-abuse measures
  *
- * @returns Promise resolving to the created invitation with secure token
- *
- * @throws {Error} When OMNIBASE_AUTH_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)
+ * All invitation operations respect tenant permissions and ensure that only
+ * authorized users can invite others to their tenants.
  *
  * @example
- * Basic invitation creation:
  * ```typescript
- * const invite = await createTenantUserInvite('tenant_123', {
+ * const inviteManager = new TenantInviteManager(omnibaseClient);
+ *
+ * // Create an invitation
+ * const invite = await inviteManager.create('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}`;
+ * // Accept an invitation (from the invited user's session)
+ * const result = await inviteManager.accept('invite_token_xyz');
+ * console.log(`Joined tenant: ${result.data.tenant_id}`);
  * ```
  *
+ * @since 1.0.0
+ * @public
+ * @group Tenant Invitations
+ */
+declare class TenantInviteManager {
+    private omnibaseClient;
+    /**
+     * 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: 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
+     * 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
+     */
+    accept(token: string): Promise<AcceptTenantInviteResponse>;
+    /**
+     * 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
+     */
+    create(tenantId: string, inviteData: CreateTenantUserInviteRequest): Promise<CreateTenantUserInviteResponse>;
+}
+
+/**
+ * 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
- * 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}`);
+ * 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;
+}>;
+/**
+ * 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 User Management
+ * @group Tenant Management
  */
-declare function createTenantUserInvite(tenantId: string, inviteData: CreateTenantUserInviteRequest): Promise<CreateTenantUserInviteResponse>;
-
+type DeleteTenantResponse = ApiResponse<{
+    /** Confirmation message indicating successful deletion */
+    message: string;
+}>;
 /**
  * Response structure for tenant creation operations
  *
@@ -389,247 +544,1444 @@ type CreateTenantRequest = {
     user_id: string;
 };
 /**
- * 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.
+ * Tenant management operations handler
  *
- * @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
+ * This class provides core tenant lifecycle management operations including
+ * creation, deletion, and active tenant switching. It handles all the fundamental
+ * operations needed to manage tenants in a multi-tenant application with
+ * integrated billing and row-level security.
  *
- * @returns Promise resolving to the created tenant with authentication token
+ * The manager handles:
+ * - Tenant creation with Stripe billing integration
+ * - Secure tenant deletion with data cleanup
+ * - Active tenant switching with JWT token management
+ * - User permission validation for all operations
  *
- * @throws {Error} When OMNIBASE_AUTH_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)
+ * All operations are performed within the authenticated user context and
+ * respect tenant ownership and permission rules.
  *
  * @example
- * Basic tenant creation:
  * ```typescript
- * const newTenant = await createTenant({
- *   name: 'Acme Corporation',
+ * const tenantManager = new TenantManger(omnibaseClient);
+ *
+ * // Create a new tenant
+ * const tenant = await tenantManager.createTenant({
+ *   name: 'Acme Corp',
  *   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);
+ * // Switch to the new tenant
+ * await tenantManager.switchActiveTenant(tenant.data.tenant.id);
+ *
+ * // Delete tenant (owner only)
+ * await tenantManager.deleteTenant(tenant.data.tenant.id);
  * ```
  *
+ * @since 1.0.0
+ * @public
+ * @group Tenant Management
+ */
+declare class TenantManger {
+    private omnibaseClient;
+    /**
+     * 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: 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
+     * 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
+     */
+    createTenant(tenantData: CreateTenantRequest): Promise<CreateTenantResponse>;
+    /**
+     * 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
+     */
+    deleteTenant(tenantId: string): Promise<DeleteTenantResponse>;
+    /**
+     * 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
+     */
+    switchActiveTenant(tenantId: string): Promise<SwitchActiveTenantResponse>;
+}
+
+/**
+ * Main tenant management handler
+ *
+ * This is the primary entry point for all tenant-related operations in the
+ * Omnibase SDK. It provides a unified interface to both tenant management
+ * and invitation functionality through dedicated manager instances.
+ *
+ * The handler follows the composition pattern, combining specialized managers
+ * for different aspects of tenant functionality:
+ * - `tenants`: Core tenant operations (create, delete, switch)
+ * - `invites`: User invitation management (create, accept)
+ *
+ * All operations are performed within the context of the authenticated user
+ * and respect tenant-level permissions and row-level security policies.
+ *
+ * @example
+ * ```typescript
+ * import { OmnibaseClient } from '@omnibase/core-js';
+ * import { TenantHandler } from '@omnibase/core-js/tenants';
+ *
+ * const client = new OmnibaseClient({ apiKey: 'your-api-key' });
+ * const tenantHandler = new TenantHandler(client);
+ *
+ * // Create a new tenant
+ * const tenant = await tenantHandler.tenants.createTenant({
+ *   name: 'My Company',
+ *   billing_email: 'billing@company.com',
+ *   user_id: 'user_123'
+ * });
+ *
+ * // Invite users to the tenant
+ * const invite = await tenantHandler.invites.create(tenant.data.tenant.id, {
+ *   email: 'colleague@company.com',
+ *   role: 'member'
+ * });
+ *
+ * // Switch to the new tenant
+ * await tenantHandler.tenants.switchActiveTenant(tenant.data.tenant.id);
+ * ```
  *
  * @since 1.0.0
  * @public
  * @group Tenant Management
  */
-declare function createTenant(tenantData: CreateTenantRequest): Promise<CreateTenantResponse>;
+declare class TenantHandler {
+    private omnibaseClient;
+    /**
+     * 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: OmnibaseClient);
+    /**
+     * 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);
+     * ```
+     */
+    readonly tenants: TenantManger;
+    /**
+     * 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');
+     * ```
+     */
+    readonly invites: TenantInviteManager;
+}
+
+type OmnibaseClientConfig = {
+    api_url: string;
+};
+declare class OmnibaseClient {
+    private config;
+    constructor(config: OmnibaseClientConfig);
+    /**
+     * Main payment handler for all payment-related operations
+     *
+     * This class serves as the central coordinator for all payment functionality,
+     * providing access to checkout sessions, billing configuration, customer portals,
+     * and usage tracking. It handles the low-level HTTP communication with the
+     * payment API and delegates specific operations to specialized managers.
+     *
+     * The handler automatically manages authentication, request formatting, and
+     * provides a consistent interface across all payment operations.
+     *
+     * @example
+     * ```typescript
+     * // Create a checkout session
+     * const checkout = await omnibase.payments.checkout.createSession({
+     *   price_id: 'price_123',
+     *   mode: 'subscription',
+     *   success_url: 'https://app.com/success',
+     *   cancel_url: 'https://app.com/cancel'
+     * });
+     *
+     * // Get available products
+     * const products = await omnibase.payments.config.getAvailableProducts();
+     * ```
+     */
+    readonly payments: PaymentHandler;
+    readonly tenants: TenantHandler;
+    readonly permissions: PermissionsClient;
+    fetch(endpoint: string, options?: RequestInit): Promise<Response>;
+}
 
 /**
- * Response structure for deleting a tenant
+ * Configuration options for creating a Stripe checkout session
  *
- * 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.
+ * Defines all parameters needed to create a checkout session for either
+ * one-time payments or subscription billing. The session will redirect
+ * users to Stripe's hosted checkout page.
  *
  * @example
  * ```typescript
- * const response: DeleteTenantResponse = {
- *   data: {
- *     message: 'Tenant deleted successfully'
- *   },
- *   status: 200
+ * const options: CheckoutOptions = {
+ *   price_id: 'price_1234567890',
+ *   mode: 'subscription',
+ *   success_url: 'https://app.com/success?session_id={CHECKOUT_SESSION_ID}',
+ *   cancel_url: 'https://app.com/pricing',
+ *   customer_id: 'cus_1234567890'
  * };
  * ```
  *
  * @since 1.0.0
  * @public
- * @group Tenant Management
+ * @group Checkout
  */
-type DeleteTenantResponse = ApiResponse<{
-    /** Confirmation message indicating successful deletion */
-    message: string;
+type CheckoutOptions = {
+    /** Stripe price ID for the product/service being purchased */
+    price_id: string;
+    /**
+     * Checkout mode determining the type of transaction
+     * - 'payment': One-time payment
+     * - 'subscription': Recurring subscription
+     */
+    mode: "payment" | "subscription";
+    /**
+     * URL to redirect to after successful payment
+     * Can include {CHECKOUT_SESSION_ID} placeholder for session tracking
+     */
+    success_url: string;
+    /** URL to redirect to if the user cancels the checkout */
+    cancel_url: string;
+    /**
+     * Optional Stripe customer ID to associate with this checkout
+     * If not provided, a new customer will be created
+     */
+    customer_id?: string;
+};
+/**
+ * Response from creating a checkout session
+ *
+ * Contains the checkout session URL and ID for redirecting users
+ * to Stripe's hosted checkout page and tracking the session.
+ *
+ * @since 1.0.0
+ * @public
+ * @group Checkout
+ */
+type CreateCheckoutResponse = ApiResponse<{
+    /** URL to redirect the user to for completing payment */
+    url: string;
+    /** Unique identifier for the checkout session */
+    sessionId: string;
 }>;
 /**
- * Permanently deletes a tenant and all associated data
+ * Manager for Stripe checkout session operations
  *
- * ⚠️ **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
+ * Handles creation and management of Stripe checkout sessions for both
+ * one-time payments and subscription billing. Provides a simple interface
+ * for redirecting users to Stripe's hosted checkout experience.
  *
- * **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
+ * Checkout sessions are the recommended way to accept payments as they
+ * provide a secure, PCI-compliant payment flow without requiring
+ * sensitive payment data to touch your servers.
  *
- * **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
+ * @example
+ * Creating a subscription checkout:
+ * ```typescript
+ * const checkoutManager = new CheckoutManager(paymentHandler);
+ *
+ * const session = await checkoutManager.createSession({
+ *   price_id: 'price_monthly_pro',
+ *   mode: 'subscription',
+ *   success_url: 'https://app.com/welcome?session_id={CHECKOUT_SESSION_ID}',
+ *   cancel_url: 'https://app.com/pricing',
+ *   customer_id: 'cus_existing_customer'
+ * });
  *
- * @param tenantId - The unique identifier of the tenant to delete
+ * // Redirect user to checkout
+ * window.location.href = session.data.url;
+ * ```
  *
- * @returns Promise resolving to a confirmation message
+ * @since 1.0.0
+ * @public
+ * @group Checkout
+ */
+declare class CheckoutManager {
+    private omnibaseClient;
+    /**
+     * Initialize the checkout manager
+     *
+     * @param paymentHandler - Payment handler instance for API communication
+     *
+     * @group Checkout
+     */
+    constructor(omnibaseClient: OmnibaseClient);
+    /**
+     * Create a new Stripe checkout session
+     *
+     * Creates a checkout session with the specified options and returns
+     * the session URL for redirecting the user to complete payment.
+     * The session will be configured for either one-time payment or
+     * subscription based on the mode parameter.
+     *
+     * @param options - Configuration options for the checkout session
+     * @param options.price_id - Stripe price ID for the product/service
+     * @param options.mode - Payment mode ('payment' for one-time, 'subscription' for recurring)
+     * @param options.success_url - URL to redirect after successful payment
+     * @param options.cancel_url - URL to redirect if user cancels
+     * @param options.customer_id - Optional existing Stripe customer ID
+     *
+     * @returns Promise resolving to checkout session response with URL and session ID
+     *
+     * @throws {Error} When the API request fails due to network issues
+     * @throws {Error} When the server returns an error response (invalid price_id, etc.)
+     * @throws {ValidationError} When required parameters are missing or invalid
+     *
+     * @example
+     * One-time payment checkout:
+     * ```typescript
+     * const session = await checkoutManager.createSession({
+     *   price_id: 'price_one_time_product',
+     *   mode: 'payment',
+     *   success_url: 'https://app.com/success',
+     *   cancel_url: 'https://app.com/cancel'
+     * });
+     *
+     * // Redirect to Stripe checkout
+     * window.location.href = session.data.url;
+     * ```
+     *
+     * @example
+     * Subscription checkout with existing customer:
+     * ```typescript
+     * const session = await checkoutManager.createSession({
+     *   price_id: 'price_monthly_plan',
+     *   mode: 'subscription',
+     *   success_url: 'https://app.com/dashboard?welcome=true',
+     *   cancel_url: 'https://app.com/pricing',
+     *   customer_id: 'cus_12345'
+     * });
+     *
+     * console.log(`Session created: ${session.data.sessionId}`);
+     * ```
+     *
+     * @since 1.0.0
+     * @group Checkout
+     */
+    createSession(options: CheckoutOptions): Promise<CreateCheckoutResponse>;
+}
+
+/**
+ * Response from Stripe configuration API endpoints
  *
- * @throws {Error} When OMNIBASE_AUTH_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)
+ * Contains the current Stripe configuration including products, prices,
+ * and UI customization settings. This represents the complete billing
+ * configuration loaded from the database.
+ *
+ * @since 1.0.0
+ * @public
+ * @group Configuration
+ */
+type StripeConfigResponse = ApiResponse<{
+    /** The complete Stripe configuration object */
+    config: StripeConfiguration;
+    /** Optional message from the API response */
+    message?: string;
+}>;
+/**
+ * Complete Stripe billing configuration
+ *
+ * Represents a versioned Stripe configuration containing all products,
+ * prices, and UI customizations. This configuration is stored in the
+ * database and enables safe deployment and rollback of pricing changes.
  *
  * @example
- * Basic tenant deletion with confirmation:
  * ```typescript
- * const tenantToDelete = 'tenant_abc123';
+ * const config: StripeConfiguration = {
+ *   version: "v1.2.0",
+ *   products: [
+ *     {
+ *       id: "starter_plan",
+ *       name: "Starter Plan",
+ *       description: "Perfect for individuals and small teams",
+ *       type: "service",
+ *       prices: [...]
+ *     }
+ *   ]
+ * };
+ * ```
  *
- * // Always confirm before deleting
- * const userConfirmed = confirm(
- *   'Are you sure you want to delete this tenant? This action cannot be undone.'
- * );
+ * @since 1.0.0
+ * @public
+ * @group Configuration
+ */
+interface StripeConfiguration {
+    /** Version identifier for this configuration */
+    version: string;
+    /** Array of all products in this configuration */
+    products: Product[];
+}
+/**
+ * Product definition in Stripe configuration
  *
- * if (userConfirmed) {
- *   try {
- *     const result = await deleteTenant(tenantToDelete);
- *     console.log(result.data.message); // "Tenant deleted successfully"
+ * Represents a billable product or service with associated pricing options
+ * and UI customizations. Products can be services, physical goods, or
+ * metered usage products.
  *
- *     // Redirect user away from deleted tenant
- *     window.location.href = '/dashboard';
- *   } catch (error) {
- *     console.error('Failed to delete tenant:', error);
+ * @example
+ * ```typescript
+ * const product: Product = {
+ *   id: "pro_plan",
+ *   name: "Professional Plan",
+ *   description: "Advanced features for growing businesses",
+ *   type: "service",
+ *   prices: [
+ *     { id: "monthly", amount: 2900, currency: "usd", interval: "month" },
+ *     { id: "yearly", amount: 29000, currency: "usd", interval: "year" }
+ *   ],
+ *   ui: {
+ *     display_name: "Pro",
+ *     tagline: "Most Popular",
+ *     features: ["Unlimited projects", "24/7 support"],
+ *     highlighted: true
  *   }
- * }
+ * };
  * ```
  *
  * @since 1.0.0
  * @public
- * @group Tenant Management
+ * @group Configuration
  */
-declare function deleteTenant(tenantId: string): Promise<DeleteTenantResponse>;
-
+interface Product {
+    /** Unique identifier for this product */
+    id: string;
+    /** Display name for the product */
+    name: string;
+    /** Optional detailed description */
+    description?: string;
+    /**
+     * Product type affecting billing behavior
+     * - 'service': Subscription services
+     * - 'good': Physical or digital goods
+     * - 'metered': Usage-based billing
+     */
+    type?: "service" | "good" | "metered";
+    /** Array of pricing options for this product */
+    prices: Price[];
+    /** Optional UI customization settings */
+    ui?: ProductUI;
+}
 /**
- * Response structure for switching the active tenant
+ * Price definition for a product
  *
- * 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.
+ * Defines a specific pricing option including amount, currency, billing
+ * frequency, and advanced pricing features like tiered billing. Supports
+ * both fixed and usage-based pricing models.
  *
- * 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
+ * Simple monthly pricing:
+ * ```typescript
+ * const monthlyPrice: Price = {
+ *   id: "monthly_standard",
+ *   amount: 1999, // $19.99 in cents
+ *   currency: "usd",
+ *   interval: "month",
+ *   usage_type: "licensed"
+ * };
+ * ```
  *
  * @example
+ * Tiered usage pricing:
  * ```typescript
- * const response: SwitchActiveTenantResponse = {
- *   data: {
- *     token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
- *     message: 'Active tenant switched successfully'
+ * const tieredPrice: Price = {
+ *   id: "api_calls_tiered",
+ *   currency: "usd",
+ *   usage_type: "metered",
+ *   billing_scheme: "tiered",
+ *   tiers_mode: "graduated",
+ *   tiers: [
+ *     { up_to: 1000, unit_amount: 10 }, // First 1000 calls at $0.10 each
+ *     { up_to: "inf", unit_amount: 5 }  // Additional calls at $0.05 each
+ *   ]
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Configuration
+ */
+interface Price {
+    /** Unique identifier for this price */
+    id: string;
+    /**
+     * Price amount in smallest currency unit (e.g., cents for USD)
+     * Omitted for usage-based pricing with tiers
+     */
+    amount?: number;
+    /** Currency code (ISO 4217) */
+    currency: string;
+    /**
+     * Billing interval for recurring prices
+     * - 'month': Monthly billing
+     * - 'year': Annual billing
+     * - 'week': Weekly billing
+     * - 'day': Daily billing
+     */
+    interval?: "month" | "year" | "week" | "day";
+    /**
+     * Number of intervals between billings
+     * @defaultValue 1
+     */
+    interval_count?: number;
+    /**
+     * Usage type determining billing model
+     * - 'licensed': Fixed recurring pricing
+     * - 'metered': Usage-based pricing
+     */
+    usage_type?: "licensed" | "metered";
+    /**
+     * Billing scheme for complex pricing
+     * - 'per_unit': Simple per-unit pricing
+     * - 'tiered': Graduated or volume-based tiers
+     */
+    billing_scheme?: "per_unit" | "tiered";
+    /**
+     * Tier calculation mode (when billing_scheme is 'tiered')
+     * - 'graduated': Each tier applies to usage within that tier
+     * - 'volume': Entire usage charged at the tier rate
+     */
+    tiers_mode?: "graduated" | "volume";
+    /** Pricing tiers for tiered billing */
+    tiers?: Tier[];
+    /** Optional UI customization settings */
+    ui?: PriceUI;
+}
+/**
+ * Pricing tier definition for tiered billing
+ *
+ * Defines a usage range and associated pricing for tiered billing models.
+ * Enables graduated pricing where different usage levels have different rates.
+ *
+ * @example
+ * ```typescript
+ * const tiers: Tier[] = [
+ *   { up_to: 100, flat_amount: 0, unit_amount: 10 },    // First 100 free, then $0.10 each
+ *   { up_to: 1000, unit_amount: 5 },                    // Next 900 at $0.05 each
+ *   { up_to: "inf", unit_amount: 2 }                    // Beyond 1000 at $0.02 each
+ * ];
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Configuration
+ */
+interface Tier {
+    /**
+     * Upper bound for this tier
+     * Use "inf" for the highest tier with no upper limit
+     */
+    up_to: number | "inf";
+    /**
+     * Fixed amount charged for this tier (in cents)
+     * Used for flat fees at tier boundaries
+     */
+    flat_amount?: number;
+    /**
+     * Per-unit amount for usage within this tier (in cents)
+     * Applied to each unit of usage in this tier range
+     */
+    unit_amount?: number;
+}
+/**
+ * UI customization settings for products
+ *
+ * Controls how products are displayed in pricing tables and marketing pages.
+ * Provides extensive customization options for branding and presentation.
+ *
+ * @example
+ * ```typescript
+ * const productUI: ProductUI = {
+ *   display_name: "Enterprise",
+ *   tagline: "For large organizations",
+ *   features: ["SSO integration", "Advanced analytics", "Priority support"],
+ *   badge: "Most Popular",
+ *   cta_text: "Contact Sales",
+ *   highlighted: true,
+ *   sort_order: 3
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group UI Configuration
+ */
+interface ProductUI {
+    /** Custom display name (overrides product.name) */
+    display_name?: string;
+    /** Marketing tagline or subtitle */
+    tagline?: string;
+    /** List of key features to highlight */
+    features?: string[];
+    /** Optional badge text (e.g., "Popular", "Best Value") */
+    badge?: string;
+    /** Custom call-to-action button text */
+    cta_text?: string;
+    /** Whether to visually highlight this product */
+    highlighted?: boolean;
+    /** Sort order for display (lower numbers first) */
+    sort_order?: number;
+}
+/**
+ * UI customization settings for prices
+ *
+ * Controls how individual price options are displayed within products.
+ * Enables custom formatting, feature lists, and usage limits display.
+ *
+ * @example
+ * ```typescript
+ * const priceUI: PriceUI = {
+ *   display_name: "Annual Billing",
+ *   price_display: {
+ *     custom_text: "$99/year",
+ *     suffix: "billed annually"
  *   },
- *   status: 200
+ *   billing_period: "per year",
+ *   features: ["2 months free", "Priority support"],
+ *   limits: [
+ *     { text: "Up to 10 users", value: 10, unit: "users" },
+ *     { text: "100GB storage", value: 100, unit: "GB" }
+ *   ]
  * };
  * ```
  *
  * @since 1.0.0
  * @public
- * @group Tenant Management
+ * @group UI Configuration
  */
-type SwitchActiveTenantResponse = ApiResponse<{
-    /** New JWT token with updated tenant context */
-    token: string;
-    /** Success message confirming the tenant switch */
-    message: string;
-}>;
+interface PriceUI {
+    /** Custom display name for this price option */
+    display_name?: string;
+    /** Custom price display formatting */
+    price_display?: PriceDisplay;
+    /** Custom billing period description */
+    billing_period?: string;
+    /** Price-specific features to highlight */
+    features?: string[];
+    /** Usage limits and quotas for this price */
+    limits?: PriceLimit[];
+}
 /**
- * Switches the user's active tenant context
+ * Custom price display formatting options
  *
- * 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.
+ * Provides fine-grained control over how prices are formatted and displayed,
+ * including custom text, currency symbols, and suffixes.
  *
- * 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
+ * @example
+ * ```typescript
+ * const priceDisplay: PriceDisplay = {
+ *   custom_text: "Contact us for pricing",
+ *   show_currency: false,
+ *   suffix: "per month"
+ * };
+ * ```
  *
- * 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.
+ * @since 1.0.0
+ * @public
+ * @group UI Configuration
+ */
+interface PriceDisplay {
+    /**
+     * Custom text to display instead of calculated price
+     * Useful for "Contact us" or "Free" pricing
+     */
+    custom_text?: string;
+    /**
+     * Whether to show currency symbol
+     * @defaultValue true
+     */
+    show_currency?: boolean;
+    /** Additional text to append after the price */
+    suffix?: string;
+}
+/**
+ * Usage limit or quota definition
  *
- * @param tenantId - The ID of the tenant to switch to (must be a tenant the user belongs to)
+ * Represents a specific limit or quota associated with a price tier,
+ * such as user limits, storage quotas, or API call allowances.
  *
- * @returns Promise resolving to a new JWT token and success confirmation
+ * @example
+ * ```typescript
+ * const limits: PriceLimit[] = [
+ *   { text: "Up to 5 team members", value: 5, unit: "users" },
+ *   { text: "50GB storage included", value: 50, unit: "GB" },
+ *   { text: "Unlimited API calls" } // No value/unit for unlimited
+ * ];
+ * ```
  *
- * @throws {Error} When OMNIBASE_AUTH_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)
+ * @since 1.0.0
+ * @public
+ * @group UI Configuration
+ */
+interface PriceLimit {
+    /** Human-readable description of the limit */
+    text: string;
+    /** Numeric value of the limit (omit for unlimited) */
+    value?: number;
+    /** Unit of measurement for the limit */
+    unit?: string;
+}
+/**
+ * UI-ready product data structure for pricing tables
+ *
+ * Extended product interface that includes pre-processed display data
+ * optimized for rendering pricing tables and marketing pages. Contains
+ * formatted prices, organized features, and display-ready content.
+ *
+ * This interface is returned by [`getAvailableProducts()`](config.ts) and provides
+ * everything needed to render a complete pricing table without additional
+ * data processing.
  *
  * @example
- * Basic tenant switching:
  * ```typescript
- * const result = await switchActiveTenant('tenant_xyz789');
+ * const products: ProductWithPricingUI[] = await configManager.getAvailableProducts();
+ *
+ * products.forEach(product => {
+ *   const display = product.pricing_display;
+ *   console.log(`${display.name}: ${display.tagline}`);
  *
- * // Now all API calls will be in the context of tenant_xyz789
- * const tenantData = await getCurrentTenantData();
+ *   display.prices.forEach(price => {
+ *     console.log(`  ${price.display_name}: ${price.formatted_price}`);
+ *   });
+ * });
  * ```
  *
+ * @since 1.0.0
+ * @public
+ * @group UI Configuration
+ */
+interface ProductWithPricingUI extends Product {
+    /** Pre-processed display data for UI rendering */
+    pricing_display: {
+        /** Display name for the product */
+        name: string;
+        /** Marketing tagline or subtitle */
+        tagline?: string;
+        /** Key features to highlight */
+        features: string[];
+        /** Optional badge text */
+        badge?: string;
+        /** Call-to-action button text */
+        cta_text: string;
+        /** Whether this product should be visually highlighted */
+        highlighted: boolean;
+        /** Sort order for display */
+        sort_order: number;
+        /** UI-ready price information */
+        prices: Array<{
+            /** Price identifier */
+            id: string;
+            /** Display name for this price option */
+            display_name: string;
+            /** Formatted price string ready for display */
+            formatted_price: string;
+            /** Billing period description */
+            billing_period: string;
+            /** Price-specific features */
+            features: string[];
+            /** Usage limits and quotas */
+            limits: Array<{
+                /** Limit description */
+                text: string;
+                /** Numeric value (if applicable) */
+                value?: number;
+                /** Unit of measurement */
+                unit?: string;
+            }>;
+        }>;
+    };
+}
+
+declare class ConfigManager {
+    private omnibaseClient;
+    constructor(omnibaseClient: OmnibaseClient);
+    /**
+     * Get the current Stripe configuration from the database
+     *
+     * Retrieves the latest Stripe configuration including products, prices,
+     * and UI customization data. This configuration represents the current
+     * active pricing structure with all UI elements for pricing table rendering.
+     *
+     * @returns Promise resolving to the current Stripe configuration
+     *
+     * @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 usage:
+     * ```typescript
+     * const config = await getStripeConfig();
+     * console.log(`Found ${config.data.config.products.length} products`);
+     *
+     * // Access product UI configuration
+     * config.data.config.products.forEach(product => {
+     *   console.log(`${product.name}: ${product.ui?.tagline || 'No tagline'}`);
+     * });
+     * ```
+     */
+    getStripeConfig(): Promise<StripeConfigResponse>;
+    /**
+     * Get available products with UI-ready pricing data
+     *
+     * Transforms the raw Stripe configuration into UI-ready format for pricing
+     * table rendering. Includes formatted pricing, features, limits, and all
+     * display customizations needed for marketing pages.
+     *
+     * @returns Promise resolving to products ready for UI consumption
+     *
+     * @throws {Error} When the API request fails or configuration is invalid
+     *
+     * @example
+     * Pricing table rendering:
+     * ```typescript
+     * const products = await getAvailableProducts();
+     *
+     * products.forEach(product => {
+     *   const display = product.pricing_display;
+     *   console.log(`${display.name} - ${display.tagline}`);
+     *
+     *   display.prices.forEach(price => {
+     *     console.log(`  ${price.display_name}: ${price.formatted_price}`);
+     *   });
+     * });
+     * ```
+     */
+    getAvailableProducts(): Promise<ProductWithPricingUI[]>;
+    /**
+     * Get a specific product by ID
+     *
+     * Retrieves a single product configuration by its ID from the current
+     * Stripe configuration. Useful for product-specific operations.
+     *
+     * @param productId - The configuration product ID to retrieve
+     * @returns Promise resolving to the product or null if not found
+     *
+     * @example
+     * ```typescript
+     * const product = await getProduct('starter_plan');
+     * if (product) {
+     *   console.log(`Found product: ${product.name}`);
+     * }
+     * ```
+     */
+    getProduct(productId: string): Promise<Product | null>;
+}
+
+/**
+ * Configuration options for creating a Stripe customer portal session
+ *
+ * Defines the parameters needed to create a customer portal session
+ * that allows customers to manage their subscription, payment methods,
+ * billing history, and other account settings.
+ *
  * @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);
+ * const options: PortalOptions = {
+ *   customer_id: 'cus_1234567890',
+ *   return_url: 'https://app.com/billing'
+ * };
+ * ```
  *
- *     // Update authentication token
- *     setAuthToken(switchResult.data.token);
+ * @since 1.0.0
+ * @public
+ * @group Portal
+ */
+type PortalOptions = {
+    /** Stripe customer ID for the user accessing the portal */
+    customer_id: string;
+    /** URL to redirect the customer to when they exit the portal */
+    return_url: string;
+};
+/**
+ * Response from creating a customer portal session
  *
- *     // Fetch data in new tenant context
- *     const [tenantInfo, userPermissions, tenantSettings] = await Promise.all([
- *       getTenantInfo(),
- *       getUserPermissions(),
- *       getTenantSettings()
- *     ]);
+ * Contains the portal session URL for redirecting customers to
+ * Stripe's hosted customer portal where they can manage their
+ * billing and subscription settings.
  *
- *     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 Portal
+ */
+type CreateCustomerPortalResponse = ApiResponse<{
+    /** URL to redirect the customer to for accessing their portal */
+    url: string;
+}>;
+/**
+ * Manager for Stripe customer portal operations
+ *
+ * Handles creation of customer portal sessions that allow customers
+ * to manage their own billing information, subscriptions, payment methods,
+ * and download invoices through Stripe's hosted portal interface.
+ *
+ * The customer portal provides a secure, self-service interface that
+ * reduces support burden by allowing customers to handle common
+ * billing tasks independently.
+ *
+ * @example
+ * Creating a customer portal session:
+ * ```typescript
+ * const portalManager = new PortalManager(paymentHandler);
+ *
+ * const portal = await portalManager.create({
+ *   customer_id: 'cus_customer123',
+ *   return_url: 'https://app.com/billing'
+ * });
+ *
+ * // Redirect customer to portal
+ * window.location.href = portal.data.url;
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Portal
+ */
+declare class PortalManager {
+    private omnibaseClient;
+    /**
+     * Initialize the portal manager
+     *
+     * @param paymentHandler - Payment handler instance for API communication
+     *
+     * @group Portal
+     */
+    constructor(omnibaseClient: OmnibaseClient);
+    /**
+     * Create a new customer portal session
+     *
+     * Creates a portal session that allows the specified customer to
+     * manage their billing information, subscriptions, and payment methods.
+     * Returns a URL that the customer should be redirected to.
+     *
+     * The portal session is temporary and expires after a short period
+     * for security. Each access requires creating a new session.
+     *
+     * @param options - Configuration options for the portal session
+     * @param options.customer_id - Stripe customer ID for the user
+     * @param options.return_url - URL to redirect to when exiting the portal
+     *
+     * @returns Promise resolving to portal session response with access URL
+     *
+     * @throws {Error} When the API request fails due to network issues
+     * @throws {Error} When the server returns an error response (invalid customer_id, etc.)
+     * @throws {ValidationError} When required parameters are missing or invalid
+     *
+     * @example
+     * Basic portal creation:
+     * ```typescript
+     * const portal = await portalManager.create({
+     *   customer_id: 'cus_abc123',
+     *   return_url: 'https://myapp.com/account/billing'
+     * });
+     *
+     * // Redirect user to portal
+     * window.location.href = portal.data.url;
+     * ```
+     *
+     * @example
+     * With error handling:
+     * ```typescript
+     * try {
+     *   const portal = await portalManager.create({
+     *     customer_id: currentUser.stripeCustomerId,
+     *     return_url: window.location.origin + '/billing'
+     *   });
+     *
+     *   window.location.href = portal.data.url;
+     * } catch (error) {
+     *   console.error('Failed to create portal session:', error);
+     *   showErrorMessage('Unable to access billing portal. Please try again.');
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     * @group Portal
+     */
+    create(options: PortalOptions): Promise<CreateCustomerPortalResponse>;
+}
+
+/**
+ * Configuration options for recording usage events
+ *
+ * Defines the parameters needed to record a usage event for metered billing.
+ * Usage events are used to track consumption of metered products and calculate
+ * charges based on actual usage rather than fixed pricing.
+ *
+ * @example
+ * ```typescript
+ * const options: UsageOptions = {
+ *   meter_event_name: 'api_calls',
+ *   customer_id: 'cus_1234567890',
+ *   value: '1'
  * };
  * ```
  *
  * @since 1.0.0
  * @public
- * @group Tenant Management
+ * @group Usage
+ */
+type UsageOptions = {
+    /**
+     * Name of the meter event to record usage for
+     * Must match a meter configured in your Stripe billing configuration
+     */
+    meter_event_name: string;
+    /** Stripe customer ID to record usage for */
+    customer_id: string;
+    /**
+     * Usage value to record as a string
+     * Typically represents quantity consumed (e.g., "1" for single API call, "250" for MB of storage)
+     */
+    value: string;
+};
+/**
+ * Manager for usage tracking and metered billing operations
+ *
+ * Handles recording of usage events for metered billing products. Usage events
+ * are used by Stripe to calculate charges for products with usage-based pricing,
+ * such as API calls, data transfer, or storage consumption.
+ *
+ * Usage tracking is essential for accurate metered billing and provides
+ * transparency to customers about their consumption patterns.
+ *
+ * @example
+ * Recording API usage:
+ * ```typescript
+ * const usageManager = new UsageManager(paymentHandler);
+ *
+ * // Record a single API call
+ * await usageManager.recordUsage({
+ *   meter_event_name: 'api_calls',
+ *   customer_id: 'cus_customer123',
+ *   value: '1'
+ * });
+ *
+ * // Record bulk data transfer
+ * await usageManager.recordUsage({
+ *   meter_event_name: 'data_transfer_gb',
+ *   customer_id: 'cus_customer123',
+ *   value: '2.5'
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Usage
+ */
+declare class UsageManager {
+    private omnibaseClient;
+    /**
+     * Initialize the usage manager
+     *
+     * @param paymentHandler - Payment handler instance for API communication
+     *
+     * @group Usage
+     */
+    constructor(omnibaseClient: OmnibaseClient);
+    /**
+     * Record a usage event for metered billing
+     *
+     * Records a usage event against a specific meter for billing calculation.
+     * The event will be aggregated with other usage events for the billing period
+     * to determine the customer's charges for metered products.
+     *
+     * Usage events should be recorded in real-time or as close to real-time as
+     * possible to ensure accurate billing and provide up-to-date usage visibility
+     * to customers.
+     *
+     * @param options - Usage recording options
+     * @param options.meter_event_name - Name of the meter to record against
+     * @param options.customer_id - Stripe customer ID
+     * @param options.value - Usage quantity as string
+     *
+     * @returns Promise resolving to API response confirmation
+     *
+     * @throws {Error} When the API request fails due to network issues
+     * @throws {Error} When the server returns an error response (invalid meter name, customer, etc.)
+     * @throws {ValidationError} When required parameters are missing or invalid
+     *
+     * @example
+     * API call tracking:
+     * ```typescript
+     * // Record each API call
+     * await usageManager.recordUsage({
+     *   meter_event_name: 'api_requests',
+     *   customer_id: user.stripeCustomerId,
+     *   value: '1'
+     * });
+     * ```
+     *
+     * @example
+     * Batch usage recording:
+     * ```typescript
+     * // Record multiple operations at once
+     * const usageEvents = [
+     *   { meter_event_name: 'compute_hours', customer_id: 'cus_123', value: '0.5' },
+     *   { meter_event_name: 'storage_gb', customer_id: 'cus_123', value: '10' },
+     *   { meter_event_name: 'api_calls', customer_id: 'cus_123', value: '50' }
+     * ];
+     *
+     * for (const event of usageEvents) {
+     *   await usageManager.recordUsage(event);
+     * }
+     * ```
+     *
+     * @example
+     * With error handling:
+     * ```typescript
+     * try {
+     *   await usageManager.recordUsage({
+     *     meter_event_name: 'file_uploads',
+     *     customer_id: currentUser.stripeCustomerId,
+     *     value: String(uploadedFiles.length)
+     *   });
+     * } catch (error) {
+     *   console.error('Failed to record usage:', error);
+     *   // Usage recording failure shouldn't block user operations
+     *   // but should be logged for billing accuracy
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     * @group Usage
+     */
+    recordUsage(options: UsageOptions): Promise<ApiResponse<"">>;
+}
+
+/**
+ * Main payment handler for all payment-related operations
+ *
+ * This class serves as the central coordinator for all payment functionality,
+ * providing access to checkout sessions, billing configuration, customer portals,
+ * and usage tracking. It handles the low-level HTTP communication with the
+ * payment API and delegates specific operations to specialized managers.
+ *
+ * The handler automatically manages authentication, request formatting, and
+ * provides a consistent interface across all payment operations.
+ *
+ * @example
+ * ```typescript
+ * const paymentHandler = new PaymentHandler('https://api.example.com');
+ *
+ * // Create a checkout session
+ * const checkout = await paymentHandler.checkout.createSession({
+ *   price_id: 'price_123',
+ *   mode: 'subscription',
+ *   success_url: 'https://app.com/success',
+ *   cancel_url: 'https://app.com/cancel'
+ * });
+ *
+ * // Get available products
+ * const products = await paymentHandler.config.getAvailableProducts();
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Client
  */
-declare function switchActiveTenant(tenantId: string): Promise<SwitchActiveTenantResponse>;
+declare class PaymentHandler {
+    private omnibaseClient;
+    /**
+     * Initialize the payment handler with API configuration
+     *
+     * Creates a new payment handler instance that will communicate with
+     * the specified API endpoint. The handler automatically handles
+     * request formatting and authentication headers.
+     *
+     * @param apiUrl - Base URL for the payment API endpoint
+     *
+     * @example
+     * ```typescript
+     * const paymentHandler = new PaymentHandler('https://api.myapp.com');
+     * ```
+     *
+     * @since 1.0.0
+     * @group Client
+     */
+    constructor(omnibaseClient: OmnibaseClient);
+    /**
+     * Checkout session management
+     *
+     * Provides functionality for creating and managing Stripe checkout sessions
+     * for both one-time payments and subscription billing.
+     *
+     * @example
+     * ```typescript
+     * const session = await paymentHandler.checkout.createSession({
+     *   price_id: 'price_monthly',
+     *   mode: 'subscription',
+     *   success_url: window.location.origin + '/success',
+     *   cancel_url: window.location.origin + '/pricing'
+     * });
+     * ```
+     */
+    readonly checkout: CheckoutManager;
+    /**
+     * Stripe configuration management
+     *
+     * Handles retrieval and processing of database-backed Stripe configurations,
+     * providing UI-ready product and pricing data for rendering pricing tables.
+     *
+     * @example
+     * ```typescript
+     * const products = await paymentHandler.config.getAvailableProducts();
+     * const config = await paymentHandler.config.getStripeConfig();
+     * ```
+     */
+    readonly config: ConfigManager;
+    /**
+     * Customer portal management
+     *
+     * Creates customer portal sessions for subscription management,
+     * billing history, and payment method updates.
+     *
+     * @example
+     * ```typescript
+     * const portal = await paymentHandler.portal.create({
+     *   customer_id: 'cus_123',
+     *   return_url: 'https://app.com/billing'
+     * });
+     * ```
+     */
+    readonly portal: PortalManager;
+    /**
+     * Usage tracking and metered billing
+     *
+     * Records usage events for metered billing products and manages
+     * usage-based pricing calculations.
+     *
+     * @example
+     * ```typescript
+     * await paymentHandler.usage.recordUsage({
+     *   meter_event_name: 'api_calls',
+     *   customer_id: 'cus_123',
+     *   value: '1'
+     * });
+     * ```
+     */
+    readonly usage: UsageManager;
+}
 
-export { type AcceptTenantInviteRequest, type AcceptTenantInviteResponse, 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, ConfigManager as C, type CreateTenantRequest, type CreateTenantResponse, type CreateTenantUserInviteRequest, type CreateTenantUserInviteResponse, type DeleteTenantResponse, PaymentHandler as P, type StripeConfigResponse as S, type SwitchActiveTenantResponse, type Tier as T, type Tenant, TenantHandler, type TenantInvite, TenantInviteManager, TenantManger, type UsageOptions as U, type StripeConfiguration as a, type Product as b, type Price as c, type ProductUI as d, type PriceUI as e, type PriceDisplay as f, type PriceLimit as g, type ProductWithPricingUI as h, type CheckoutOptions as i, type CreateCheckoutResponse as j, CheckoutManager as k, type PortalOptions as l, type CreateCustomerPortalResponse as m, PortalManager as n, UsageManager as o };