@omnibase/core-js 0.6.0 → 0.7.1

package/dist/payments/index.d.cts

@@ -28,7 +28,7 @@ import '@ory/client';
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  */
 type ApiResponse<T> = {
@@ -53,20 +53,20 @@ type ApiResponse<T> = {
  * Configuration options for creating a Stripe checkout session
  *
  * 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.
+ * one-time payments or subscription billing. The checkout mode (payment vs
+ * subscription) is automatically determined by examining the price configuration
+ * - no need to specify it manually.
  *
  * @example
  * ```typescript
  * const options: CheckoutOptions = {
- *   price_id: 'price_1234567890',
- *   mode: 'subscription',
+ *   price_id: 'price_monthly_pro',
  *   success_url: 'https://app.com/success?session_id={CHECKOUT_SESSION_ID}',
  *   cancel_url: 'https://app.com/pricing',
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Checkout
  */
@@ -87,7 +87,7 @@ type CheckoutOptions = {
  * Contains the checkout session URL and ID for redirecting users
  * to Stripe's hosted checkout page and tracking the session.
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Checkout
  */
@@ -101,17 +101,18 @@ type CreateCheckoutResponse = ApiResponse<{
  * Manager for Stripe checkout session operations
  *
  * 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.
+ * one-time payments and subscription billing. The checkout mode is automatically
+ * determined by examining whether the price has a recurring interval - recurring
+ * prices create subscription checkouts, while non-recurring prices create one-time
+ * payment checkouts.
  *
- * 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.
+ * Checkout sessions provide a secure, PCI-compliant payment flow without requiring
+ * sensitive payment data to touch your servers. The API automatically fetches the
+ * price details from Stripe to determine the appropriate checkout mode.
  *
  * @example
- * Creating a checkout session (mode auto-detected from price):
  * ```typescript
- * const checkoutManager = new CheckoutManager(paymentHandler);
+ * const checkoutManager = new CheckoutManager(omnibaseClient);
  *
  * const session = await checkoutManager.createSession({
  *   price_id: 'price_monthly_pro',
@@ -123,7 +124,7 @@ type CreateCheckoutResponse = ApiResponse<{
  * window.location.href = session.data.url;
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Checkout
  */
@@ -157,31 +158,20 @@ declare class CheckoutManager {
      * @throws {ValidationError} When required parameters are missing or invalid
      *
      * @example
-     * Creating a checkout session (mode is auto-detected):
      * ```typescript
      * const session = await checkoutManager.createSession({
-     *   price_id: 'price_one_time_product',
+     *   price_id: 'price_monthly_pro',
      *   success_url: 'https://app.com/success',
      *   cancel_url: 'https://app.com/cancel'
      * });
      *
      * // Redirect to Stripe checkout
-     * window.location.href = session.data.url;
-     * ```
-     *
-     * @example
-     * Checkout with session tracking:
-     * ```typescript
-     * const session = await checkoutManager.createSession({
-     *   price_id: 'price_monthly_plan',
-     *   success_url: 'https://app.com/dashboard?session_id={CHECKOUT_SESSION_ID}',
-     *   cancel_url: 'https://app.com/pricing',
-     * });
-     *
-     * console.log(`Session created: ${session.data.sessionId}`);
+     * if (session.data?.url) {
+     *   window.location.href = session.data.url;
+     * }
      * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @group Checkout
      */
     createSession(options: CheckoutOptions): Promise<CreateCheckoutResponse>;
@@ -194,7 +184,7 @@ declare class CheckoutManager {
  * and UI customization settings. This represents the complete billing
  * configuration loaded from the database.
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Configuration
  */
@@ -227,7 +217,7 @@ type StripeConfigResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Configuration
  */
@@ -264,7 +254,7 @@ interface StripeConfiguration {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Configuration
  */
@@ -322,7 +312,7 @@ interface Product {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Configuration
  */
@@ -387,7 +377,7 @@ interface Price {
  * ];
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Configuration
  */
@@ -427,7 +417,7 @@ interface Tier {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group UI Configuration
  */
@@ -470,7 +460,7 @@ interface ProductUI {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group UI Configuration
  */
@@ -501,7 +491,7 @@ interface PriceUI {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group UI Configuration
  */
@@ -534,7 +524,7 @@ interface PriceDisplay {
  * ];
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group UI Configuration
  */
@@ -571,7 +561,7 @@ interface PriceLimit {
  * });
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group UI Configuration
  */
@@ -706,7 +696,7 @@ declare class ConfigManager {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Portal
  */
@@ -721,7 +711,7 @@ type PortalOptions = {
  * Stripe's hosted customer portal where they can manage their
  * billing and subscription settings.
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Portal
  */
@@ -741,9 +731,8 @@ type CreateCustomerPortalResponse = ApiResponse<{
  * billing tasks independently.
  *
  * @example
- * Creating a customer portal session:
  * ```typescript
- * const portalManager = new PortalManager(paymentHandler);
+ * const portalManager = new PortalManager(omnibaseClient);
  *
  * const portal = await portalManager.create({
  *   return_url: 'https://app.com/billing'
@@ -753,7 +742,7 @@ type CreateCustomerPortalResponse = ApiResponse<{
  * window.location.href = portal.data.url;
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Portal
  */
@@ -762,7 +751,7 @@ declare class PortalManager {
     /**
      * Initialize the portal manager
      *
-     * @param paymentHandler - Payment handler instance for API communication
+     * @param omnibaseClient - OmnibaseClient instance for API communication
      *
      * @group Portal
      */
@@ -787,32 +776,18 @@ declare class PortalManager {
      * @throws {ValidationError} When required parameters are missing or invalid
      *
      * @example
-     * Basic portal creation:
      * ```typescript
      * const portal = await portalManager.create({
      *   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({
-     *     return_url: window.location.origin + '/billing'
-     *   });
-     *
+     * if (portal.data?.url) {
      *   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
+     * @since 0.6.0
      * @group Portal
      */
     create(options: PortalOptions): Promise<CreateCustomerPortalResponse>;
@@ -833,7 +808,7 @@ declare class PortalManager {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Usage
  */
@@ -860,9 +835,8 @@ type UsageOptions = {
  * transparency to customers about their consumption patterns.
  *
  * @example
- * Recording API usage:
  * ```typescript
- * const usageManager = new UsageManager(paymentHandler);
+ * const usageManager = new UsageManager(omnibaseClient);
  *
  * // Record a single API call
  * await usageManager.recordUsage({
@@ -877,7 +851,7 @@ type UsageOptions = {
  * });
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Usage
  */
@@ -886,7 +860,7 @@ declare class UsageManager {
     /**
      * Initialize the usage manager
      *
-     * @param paymentHandler - Payment handler instance for API communication
+     * @param omnibaseClient - OmnibaseClient instance for API communication
      *
      * @group Usage
      */
@@ -913,7 +887,6 @@ declare class UsageManager {
      * @throws {ValidationError} When required parameters are missing or invalid
      *
      * @example
-     * API call tracking:
      * ```typescript
      * // Record each API call
      * await usageManager.recordUsage({
@@ -922,37 +895,7 @@ declare class UsageManager {
      * });
      * ```
      *
-     * @example
-     * Batch usage recording:
-     * ```typescript
-     * // Record multiple operations at once
-     * const usageEvents = [
-     *   { meter_event_name: 'compute_hours', value: '0.5' },
-     *   { meter_event_name: 'storage_gb', value: '10' },
-     *   { meter_event_name: 'api_calls', 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',
-     *     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
+     * @since 0.6.0
      * @group Usage
      */
     recordUsage(options: UsageOptions): Promise<ApiResponse<"">>;
@@ -963,19 +906,20 @@ declare class UsageManager {
  *
  * 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.
+ * and usage tracking. It delegates specific operations to specialized managers
+ * that handle checkout, configuration, portal, and usage operations.
  *
- * The handler automatically manages authentication, request formatting, and
- * provides a consistent interface across all payment operations.
+ * The handler provides a consistent interface across all payment operations,
+ * with automatic checkout mode detection (subscription vs one-time payment)
+ * based on the price configuration retrieved from Stripe.
  *
  * @example
  * ```typescript
- * const paymentHandler = new PaymentHandler('https://api.example.com');
+ * const paymentHandler = new PaymentHandler(omnibaseClient);
  *
  * // Create a checkout session (mode auto-detected from price)
  * const checkout = await paymentHandler.checkout.createSession({
- *   price_id: 'price_123',
+ *   price_id: 'price_monthly_pro',
  *   success_url: 'https://app.com/success',
  *   cancel_url: 'https://app.com/cancel'
  * });
@@ -984,27 +928,27 @@ declare class UsageManager {
  * const products = await paymentHandler.config.getAvailableProducts();
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Client
  */
 declare class PaymentHandler {
     private omnibaseClient;
     /**
-     * Initialize the payment handler with API configuration
+     * Initialize the payment handler with OmnibaseClient
      *
-     * Creates a new payment handler instance that will communicate with
-     * the specified API endpoint. The handler automatically handles
-     * request formatting and authentication headers.
+     * Creates a new payment handler instance with access to all payment
+     * operations including checkout, configuration, portal, and usage tracking.
+     * The handler uses the provided OmnibaseClient for API communication.
      *
-     * @param apiUrl - Base URL for the payment API endpoint
+     * @param omnibaseClient - OmnibaseClient instance for API communication
      *
      * @example
      * ```typescript
-     * const paymentHandler = new PaymentHandler('https://api.myapp.com');
+     * const paymentHandler = new PaymentHandler(omnibaseClient);
      * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @group Client
      */
     constructor(omnibaseClient: OmnibaseClient);
@@ -1017,10 +961,14 @@ declare class PaymentHandler {
      * @example
      * ```typescript
      * const session = await paymentHandler.checkout.createSession({
-     *   price_id: 'price_monthly',
+     *   price_id: 'price_monthly_pro',
      *   success_url: window.location.origin + '/success',
      *   cancel_url: window.location.origin + '/pricing'
      * });
+     *
+     * if (session.data?.url) {
+     *   window.location.href = session.data.url;
+     * }
      * ```
      */
     readonly checkout: CheckoutManager;
@@ -1193,9 +1141,9 @@ declare class StorageClient {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
- * @group User Management
+ * @group Tenant Invitations
  */
 type AcceptTenantInviteRequest = {
     /** Secure invitation token from the email invitation */
@@ -1220,9 +1168,9 @@ type AcceptTenantInviteRequest = {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
- * @group User Management
+ * @group Tenant Invitations
  */
 type AcceptTenantInviteResponse = ApiResponse<{
     /** ID of the tenant the user has joined */
@@ -1257,9 +1205,9 @@ type AcceptTenantInviteResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
- * @group User Management
+ * @group Tenant Invitations
  */
 type CreateTenantUserInviteResponse = ApiResponse<{
     /** The newly created tenant invite */
@@ -1289,9 +1237,9 @@ type CreateTenantUserInviteResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
- * @group User Management
+ * @group Tenant Invitations
  */
 type TenantInvite = {
     /** Unique identifier for the invitation */
@@ -1316,28 +1264,30 @@ type TenantInvite = {
 /**
  * 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.
+ * Specifies the email address of the user to invite, their intended
+ * role within the tenant, and the invitation URL that will be sent in the email.
+ * The role determines what permissions the user will have once they accept the invitation.
+ * The invite_url will be automatically appended with ?token=XYZ when sent to the user.
  *
  * @example
  * ```typescript
  * const inviteData: CreateTenantUserInviteRequest = {
  *   email: 'developer@company.com',
- *   role: 'admin'
+ *   role: 'admin',
+ *   invite_url: 'https://yourapp.com/accept-invite'
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
- * @group User Management
+ * @group Tenant Invitations
  */
 type CreateTenantUserInviteRequest = {
     /** Email address of the user to invite */
     email: string;
     /** Role the invited user will have in the tenant */
     role: string;
-    /** Invite URL - the link that will be sent to the users email suffixed automatically w/ ?token=XYZ */
+    /** Invite URL - the link that will be sent to the user's email, automatically suffixed with ?token=XYZ */
     invite_url: string;
 };
 /**
@@ -1363,9 +1313,10 @@ type CreateTenantUserInviteRequest = {
  * const inviteManager = new TenantInviteManager(omnibaseClient);
  *
  * // Create an invitation
- * const invite = await inviteManager.create('tenant_123', {
+ * const invite = await inviteManager.create({
  *   email: 'colleague@company.com',
- *   role: 'member'
+ *   role: 'member',
+ *   invite_url: 'https://yourapp.com/accept-invite'
  * });
  *
  * // Accept an invitation (from the invited user's session)
@@ -1373,7 +1324,7 @@ type CreateTenantUserInviteRequest = {
  * console.log(`Joined tenant: ${result.data.tenant_id}`);
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Invitations
  */
@@ -1419,17 +1370,6 @@ declare class TenantInviteManager {
      * @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
@@ -1439,80 +1379,65 @@ declare class TenantInviteManager {
      *
      * if (inviteToken) {
      *   try {
-     *     const result = await acceptTenantInvite(inviteToken);
+     *     const result = await inviteManager.accept(inviteToken);
      *
      *     // Success - redirect to tenant dashboard
+     *     console.log(`Successfully joined tenant: ${result.data.tenant_id}`);
      *     window.location.href = `/dashboard?tenant=${result.data.tenant_id}`;
      *   } catch (error) {
      *     console.error('Failed to accept invitation:', error.message);
-     *     // Show error to user
      *   }
      * }
      * ```
      *
-     *
-     * @since 1.0.0
+     * @since 0.6.0
      * @public
-     * @group User Management
+     * @group Tenant Invitations
      */
     accept(token: string): Promise<AcceptTenantInviteResponse>;
     /**
-     * Creates a new user invitation for a specific tenant
+     * Creates a new user invitation for the active 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.
+     * Generates a secure invitation that allows a user to join the currently active
+     * tenant with the defined role. The invitation is sent to the provided email address
+     * and includes a time-limited token for security. The invite URL will be automatically
+     * appended with ?token=XYZ when sent to the user.
      *
-     * The function creates the invitation record in the database and can
-     * trigger email notifications (depending on server configuration).
-     * The invitation expires after a predefined time period and can only
+     * The function creates the invitation record in the database and triggers an email
+     * notification to the invited user. The invitation expires after 7 days and can only
      * be used once.
      *
-     * Only existing tenant members with appropriate permissions can create
-     * invitations. The inviter's authentication is validated via HTTP-only
-     * cookies sent with the request.
+     * Only existing tenant members with appropriate permissions (invite_user permission)
+     * can create invitations. The inviter's authentication and tenant context are validated
+     * via HTTP-only cookies sent with the request.
      *
-     * @param 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')
+     * @param inviteData.invite_url - Base URL for the invitation link (will be appended with ?token=XYZ)
      *
      * @returns Promise resolving to the created invitation with secure token
      *
-     * @throws {Error} When tenantId parameter is missing or empty
-     * @throws {Error} When required fields (email, role) are missing or empty
+     * @throws {Error} When required fields (email, role, invite_url) are missing or empty
+     * @throws {Error} When the user doesn't have permission to invite users to the tenant
      * @throws {Error} When the API request fails due to network issues
      * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
      *
      * @example
-     * Basic invitation creation:
      * ```typescript
-     * const invite = await createTenantUserInvite('tenant_123', {
+     * const invite = await inviteManager.create({
      *   email: 'colleague@company.com',
-     *   role: 'member'
+     *   role: 'member',
+     *   invite_url: 'https://yourapp.com/accept-invite'
      * });
      *
      * 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}`);
+     * console.log(`Invite token: ${invite.data.invite.token}`);
      * ```
      *
-     *
-     * @since 1.0.0
+     * @since 0.6.0
      * @public
-     * @group User Management
+     * @group Tenant Invitations
      */
     create(inviteData: CreateTenantUserInviteRequest): Promise<CreateTenantUserInviteResponse>;
 }
@@ -1540,7 +1465,7 @@ declare class TenantInviteManager {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -1567,7 +1492,7 @@ type SwitchActiveTenantResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -1599,7 +1524,7 @@ type DeleteTenantResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -1630,7 +1555,7 @@ type CreateTenantResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -1663,7 +1588,7 @@ type Tenant = {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -1710,7 +1635,7 @@ type CreateTenantRequest = {
  * await tenantManager.deleteTenant(tenant.data.tenant.id);
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -1751,17 +1676,17 @@ declare class TenantManger {
      * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
      *
      * @example
-     * Basic tenant creation:
      * ```typescript
-     * const newTenant = await createTenant({
+     * const newTenant = await tenantManager.createTenant({
      *   name: 'Acme Corporation',
      *   billing_email: 'billing@acme.com',
      *   user_id: 'user_123'
      * });
-     * ```
      *
+     * console.log(`Tenant created: ${newTenant.data.tenant.id}`);
+     * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @public
      * @group Tenant Management
      */
@@ -1801,7 +1726,6 @@ declare class TenantManger {
      * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
      *
      * @example
-     * Basic tenant deletion with confirmation:
      * ```typescript
      * const tenantToDelete = 'tenant_abc123';
      *
@@ -1812,8 +1736,8 @@ declare class TenantManger {
      *
      * if (userConfirmed) {
      *   try {
-     *     const result = await deleteTenant(tenantToDelete);
-     *     console.log(result.data.message); // "Tenant deleted successfully"
+     *     const result = await tenantManager.deleteTenant(tenantToDelete);
+     *     console.log(result.data.message);
      *
      *     // Redirect user away from deleted tenant
      *     window.location.href = '/dashboard';
@@ -1823,7 +1747,7 @@ declare class TenantManger {
      * }
      * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @public
      * @group Tenant Management
      */
@@ -1859,46 +1783,17 @@ declare class TenantManger {
      * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
      *
      * @example
-     * Basic tenant switching:
      * ```typescript
-     * const result = await switchActiveTenant('tenant_xyz789');
+     * const result = await tenantManager.switchActiveTenant('tenant_xyz789');
+     *
+     * // Store the new token for future requests
+     * console.log(`Switched to tenant. New token: ${result.data.token}`);
      *
      * // Now all API calls will be in the context of tenant_xyz789
      * const tenantData = await getCurrentTenantData();
      * ```
      *
-     * @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
+     * @since 0.6.0
      * @public
      * @group Tenant Management
      */
@@ -1920,7 +1815,7 @@ declare class TenantManger {
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant User Management
  */
@@ -1958,7 +1853,7 @@ type UpdateTenantUserRoleResponse = ApiResponse<{
  * };
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant User Management
  */
@@ -1987,7 +1882,7 @@ type RemoveUserRequest = {
  * await userManager.remove({ user_id: 'user_123' });
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant User Management
  */
@@ -2038,7 +1933,7 @@ declare class TenantUserManager {
      * }
      * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @public
      * @group Tenant User Management
      */
@@ -2087,7 +1982,7 @@ declare class TenantUserManager {
      * }
      * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @public
      * @group Tenant User Management
      */
@@ -2098,13 +1993,14 @@ declare class TenantUserManager {
  * 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.
+ * Omnibase SDK. It provides a unified interface to tenant management,
+ * user 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)
+ * - `manage`: Core tenant operations (create, delete, switch)
  * - `invites`: User invitation management (create, accept)
+ * - `user`: Tenant user operations (remove, update role)
  *
  * All operations are performed within the context of the authenticated user
  * and respect tenant-level permissions and row-level security policies.
@@ -2118,23 +2014,24 @@ declare class TenantUserManager {
  * const tenantHandler = new TenantHandler(client);
  *
  * // Create a new tenant
- * const tenant = await tenantHandler.tenants.createTenant({
+ * const tenant = await tenantHandler.manage.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, {
+ * const invite = await tenantHandler.invites.create({
  *   email: 'colleague@company.com',
- *   role: 'member'
+ *   role: 'member',
+ *   invite_url: 'https://yourapp.com/accept-invite'
  * });
  *
  * // Switch to the new tenant
- * await tenantHandler.tenants.switchActiveTenant(tenant.data.tenant.id);
+ * await tenantHandler.manage.switchActiveTenant(tenant.data.tenant.id);
  * ```
  *
- * @since 1.0.0
+ * @since 0.6.0
  * @public
  * @group Tenant Management
  */
@@ -2173,7 +2070,7 @@ declare class TenantHandler {
      * await tenantHandler.user.remove({ user_id: 'user_123' });
      * ```
      *
-     * @since 1.0.0
+     * @since 0.6.0
      * @group Tenant Management
      */
     readonly user: TenantUserManager;
@@ -2187,17 +2084,17 @@ declare class TenantHandler {
      * @example
      * ```typescript
      * // Create a new tenant
-     * const tenant = await tenantHandler.tenants.createTenant({
+     * const tenant = await tenantHandler.manage.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);
+     * await tenantHandler.manage.switchActiveTenant(tenant.data.tenant.id);
      *
      * // Delete the tenant (owner only)
-     * await tenantHandler.tenants.deleteTenant(tenant.data.tenant.id);
+     * await tenantHandler.manage.deleteTenant(tenant.data.tenant.id);
      * ```
      */
     readonly manage: TenantManger;
@@ -2211,9 +2108,10 @@ declare class TenantHandler {
      * @example
      * ```typescript
      * // Create an invitation
-     * const invite = await tenantHandler.invites.create('tenant_123', {
+     * const invite = await tenantHandler.invites.create({
      *   email: 'newuser@company.com',
-     *   role: 'admin'
+     *   role: 'admin',
+     *   invite_url: 'https://yourapp.com/accept-invite'
      * });
      *
      * // Accept an invitation (from the invited user's session)
@@ -2255,7 +2153,90 @@ declare class OmnibaseClient {
      * ```
      */
     readonly payments: PaymentHandler;
+    /**
+     * 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 tenant management,
+     * user management, and invitation functionality through dedicated manager instances.
+     *
+     * The handler follows the composition pattern, combining specialized managers
+     * for different aspects of tenant functionality:
+     * - `manage`: Core tenant operations (create, delete, switch)
+     * - `invites`: User invitation management (create, accept)
+     * - `user`: Tenant user operations (remove, update role)
+     *
+     * All operations are performed within the context of the authenticated user
+     * and respect tenant-level permissions and row-level security policies.
+     *
+     * @example
+     * ```typescript
+     * // Create a new tenant
+     * const tenant = await omnibase.tenants.manage.createTenant({
+     *   name: 'My Company',
+     *   billing_email: 'billing@company.com',
+     *   user_id: 'user_123'
+     * });
+     *
+     * // Invite users to the tenant
+     * const invite = await omnibase.tenants.invites.create({
+     *   email: 'colleague@company.com',
+     *   role: 'member',
+     *   invite_url: 'https://yourapp.com/accept-invite'
+     * });
+     *
+     * // Switch to the new tenant
+     * await omnibase.tenants.manage.switchActiveTenant(tenant.data.tenant.id);
+     * ```
+     *
+     * @since 0.6.0
+     * @public
+     * @group Tenant Management
+     */
     readonly tenants: TenantHandler;
+    /**
+     * Client for managing permissions and relationships using Ory Keto
+     *
+     * This client provides access to Ory Keto's permission system, allowing you to
+     * create, manage, and check relationships between subjects and objects. It handles
+     * both read operations (permission checks) and write operations (relationship management).
+     *
+     * The client automatically configures separate endpoints for read and write operations
+     * to optimize performance and security by following Ory Keto's recommended architecture.
+     *
+     * @example
+     * ```typescript
+     * // Check if a user can view a tenant
+     * const canView = await omnibase.permissions.permissions.checkPermission(
+     *   undefined,
+     *   {
+     *     namespace: 'Tenant',
+     *     object: 'tenant_123',
+     *     relation: 'view',
+     *     subjectId: 'user_456'
+     *   }
+     * );
+     *
+     * if (canView.data.allowed) {
+     *   console.log('User can view the tenant');
+     * }
+     *
+     * // Create a relationship making a user an owner of a tenant
+     * await omnibase.permissions.relationships.createRelationship(
+     *   undefined,
+     *   {
+     *     namespace: 'Tenant',
+     *     object: 'tenant_123',
+     *     relation: 'owners',
+     *     subjectId: 'user_456'
+     *   }
+     * );
+     * ```
+     *
+     * @since 0.6.0
+     * @public
+     * @group Permissions
+     */
     readonly permissions: PermissionsClient;
     /**
      * Storage client for file upload/download operations