@omnibase/core-js 0.5.10 → 0.7.0

package/dist/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  OmnibaseClient: () => OmnibaseClient
+  OmnibaseClient: () => OmnibaseClient,
+  StorageClient: () => StorageClient
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -56,31 +57,20 @@ var CheckoutManager = class {
    * @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
    */
   async createSession(options) {
@@ -301,7 +291,7 @@ var PortalManager = class {
   /**
    * Initialize the portal manager
    *
-   * @param paymentHandler - Payment handler instance for API communication
+   * @param omnibaseClient - OmnibaseClient instance for API communication
    *
    * @group Portal
    */
@@ -328,32 +318,18 @@ var PortalManager = class {
    * @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
    */
   async create(options) {
@@ -383,7 +359,7 @@ var UsageManager = class {
   /**
    * Initialize the usage manager
    *
-   * @param paymentHandler - Payment handler instance for API communication
+   * @param omnibaseClient - OmnibaseClient instance for API communication
    *
    * @group Usage
    */
@@ -412,7 +388,6 @@ var UsageManager = class {
    * @throws {ValidationError} When required parameters are missing or invalid
    *
    * @example
-   * API call tracking:
    * ```typescript
    * // Record each API call
    * await usageManager.recordUsage({
@@ -421,37 +396,7 @@ var UsageManager = class {
    * });
    * ```
    *
-   * @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
    */
   async recordUsage(options) {
@@ -476,20 +421,20 @@ var UsageManager = class {
 // src/payments/handler.ts
 var PaymentHandler = class {
   /**
-   * 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) {
@@ -508,10 +453,14 @@ var PaymentHandler = class {
    * @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;
+   * }
    * ```
    */
   checkout;
@@ -662,6 +611,132 @@ var PermissionsClient = class {
   }
 };
 
+// src/storage/index.ts
+var StorageClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upload a file to storage
+   *
+   * @param path - Full path for the file (e.g., "public/images/avatar.png", "users/123/private/doc.pdf")
+   * @param file - File or Blob to upload
+   * @param options - Upload options including custom metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await storage.upload(
+   *   'public/avatars/user-123.png',
+   *   file,
+   *   {
+   *     metadata: {
+   *       userId: '123',
+   *       uploadedBy: 'john@example.com',
+   *       tags: ['profile', 'avatar']
+   *     }
+   *   }
+   * );
+   *
+   * // File is automatically uploaded to S3 via the presigned URL
+   * console.log('File uploaded to:', result.path);
+   * ```
+   */
+  async upload(path, file, options) {
+    const metadata = {
+      // File metadata
+      filename: file instanceof File ? file.name : "blob",
+      size: file.size,
+      mime_type: file.type,
+      uploaded_at: (/* @__PURE__ */ new Date()).toISOString(),
+      // Merge custom metadata
+      ...options?.metadata || {}
+    };
+    const response = await this.client.fetch("/api/v1/storage/upload", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path,
+        metadata
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Upload failed" }));
+      throw new Error(error.error || "Failed to get upload URL");
+    }
+    const responseData = await response.json();
+    const result = responseData.data;
+    const uploadResponse = await fetch(result.upload_url, {
+      method: "PUT",
+      body: file,
+      headers: {
+        "Content-Type": file.type
+      }
+    });
+    if (!uploadResponse.ok) {
+      throw new Error("Failed to upload file to storage");
+    }
+    return result;
+  }
+  /**
+   * Download a file from storage
+   *
+   * @param path - Full path to the file
+   *
+   * @example
+   * ```typescript
+   * const { download_url } = await storage.download('public/images/logo.png');
+   *
+   * // Download the file
+   * const response = await fetch(download_url);
+   * const blob = await response.blob();
+   * ```
+   */
+  async download(path) {
+    const response = await this.client.fetch("/api/v1/storage/download", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Download failed" }));
+      throw new Error(error.error || "Failed to get download URL");
+    }
+    const responseData = await response.json();
+    return responseData.data;
+  }
+  /**
+   * Delete a file from storage
+   *
+   * @param path - Full path to the file
+   *
+   * @example
+   * ```typescript
+   * await storage.delete('users/123/documents/old-report.pdf');
+   * ```
+   */
+  async delete(path) {
+    const response = await this.client.fetch("/api/v1/storage/object", {
+      method: "DELETE",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Delete failed" }));
+      throw new Error(error.error || "Failed to delete file");
+    }
+  }
+};
+
 // src/tenants/invites.ts
 var TenantInviteManager = class {
   /**
@@ -706,17 +781,6 @@ var TenantInviteManager = class {
    * @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
@@ -726,21 +790,20 @@ var TenantInviteManager = class {
    *
    * 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
    */
   async accept(token) {
     if (!token) {
@@ -775,73 +838,58 @@ var TenantInviteManager = class {
     }
   }
   /**
-   * 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
    */
-  async create(tenantId, inviteData) {
-    if (!tenantId) {
-      throw new Error("Tenant ID is required");
-    }
-    if (!inviteData.email || !inviteData.role) {
-      throw new Error("Email and role are required");
+  async create(inviteData) {
+    if (!inviteData.email || !inviteData.role || !inviteData.invite_url) {
+      throw new Error(
+        "Missing data in `create` - email, role, and invite_url are required"
+      );
     }
     try {
       const response = await this.omnibaseClient.fetch(
-        `/api/v1/tenants/${tenantId}/invites`,
+        `/api/v1/tenants/invites`,
         {
           method: "POST",
           headers: {
@@ -905,21 +953,17 @@ var TenantManger = class {
    * @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(`Created tenant: ${newTenant.data.tenant.name}`);
-   * // Store the token for authenticated requests
-   * localStorage.setItem('tenant_token', newTenant.data.token);
+   * console.log(`Tenant created: ${newTenant.data.tenant.id}`);
    * ```
    *
-   *
-   * @since 1.0.0
+   * @since 0.6.0
    * @public
    * @group Tenant Management
    */
@@ -984,7 +1028,6 @@ var TenantManger = class {
    * @throws {Error} When the server returns an error response (4xx, 5xx status codes)
    *
    * @example
-   * Basic tenant deletion with confirmation:
    * ```typescript
    * const tenantToDelete = 'tenant_abc123';
    *
@@ -995,8 +1038,8 @@ var TenantManger = class {
    *
    * 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';
@@ -1006,7 +1049,7 @@ var TenantManger = class {
    * }
    * ```
    *
-   * @since 1.0.0
+   * @since 0.6.0
    * @public
    * @group Tenant Management
    */
@@ -1069,46 +1112,17 @@ var TenantManger = class {
    * @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
    */
@@ -1146,6 +1160,140 @@ var TenantManger = class {
   }
 };
 
+// src/tenants/user.ts
+var TenantUserManager = class {
+  /**
+   * Creates a new tenant user manager
+   *
+   * @param omnibaseClient - Configured OmnibaseClient instance for API communication
+   *
+   * @group Tenant User Management
+   */
+  constructor(omnibaseClient) {
+    this.omnibaseClient = omnibaseClient;
+  }
+  /**
+   * Removes a user from the active tenant
+   *
+   * This method removes a specified user from the current active tenant. The operation
+   * requires the requesting user to have appropriate permissions (admin or owner role).
+   * The user being removed will lose access to the tenant and all its resources.
+   *
+   * Note: You cannot remove yourself from a tenant using this method. To leave a tenant,
+   * use the appropriate leave or delete tenant operations instead.
+   *
+   * @param data - Request data containing the user ID to remove
+   * @param data.user_id - ID of the user to remove from the tenant
+   *
+   * @returns Promise resolving to an API response confirming the removal
+   *
+   * @throws {Error} When user_id is not provided
+   * @throws {Error} When the API request fails (includes status code and error details)
+   * @throws {Error} When the user doesn't have permission to remove users
+   * @throws {Error} When the specified user is not a member of the tenant
+   *
+   * @example
+   * ```typescript
+   * // Remove a user from the active tenant
+   * try {
+   *   await userManager.remove({ user_id: 'user_abc123' });
+   *   console.log('User removed successfully');
+   * } catch (error) {
+   *   if (error.message.includes('403')) {
+   *     console.error('Insufficient permissions to remove user');
+   *   } else if (error.message.includes('404')) {
+   *     console.error('User not found in tenant');
+   *   } else {
+   *     console.error('Failed to remove user:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant User Management
+   */
+  async remove(data) {
+    if (!data.user_id) {
+      throw new Error("user_id is required");
+    }
+    const response = await this.omnibaseClient.fetch("/api/v1/tenants/users", {
+      method: "DELETE",
+      body: JSON.stringify(data)
+    });
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to delete user from tenant: ${response.status} - ${errorData}`
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * Updates a user's role within the active tenant
+   *
+   * This method changes the role of a specified user in the current active tenant. The operation
+   * requires the requesting user to have appropriate permissions (typically admin or owner role).
+   * Role updates take effect immediately and affect the user's permissions and access rights
+   * within the tenant.
+   *
+   * Common roles include 'admin', 'member', and 'viewer', but the exact roles available depend
+   * on your tenant's configuration. Changing a user's role will modify their ability to perform
+   * various operations within the tenant.
+   *
+   * @param data - Request data containing the user ID and new role
+   * @param data.user_id - ID of the user whose role is being updated
+   * @param data.role - New role to assign to the user
+   *
+   * @returns Promise resolving to an API response confirming the role update
+   *
+   * @throws {Error} When user_id or role is not provided
+   * @throws {Error} When the API request fails (includes status code and error details)
+   * @throws {Error} When the user doesn't have permission to update roles
+   * @throws {Error} When the specified user is not a member of the tenant
+   * @throws {Error} When the specified role is invalid or not allowed
+   *
+   * @example
+   * ```typescript
+   * // Update a user's role to admin
+   * try {
+   *   const result = await userManager.updateRole({
+   *     user_id: 'user_abc123',
+   *     role: 'admin'
+   *   });
+   *   console.log('Role updated successfully:', result.data.message);
+   * } catch (error) {
+   *   if (error.message.includes('403')) {
+   *     console.error('Insufficient permissions to update roles');
+   *   } else if (error.message.includes('404')) {
+   *     console.error('User not found in tenant');
+   *   } else {
+   *     console.error('Failed to update role:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant User Management
+   */
+  async updateRole(data) {
+    if (!data.role || !data.user_id)
+      throw new Error("user_id and role is required");
+    const response = await this.omnibaseClient.fetch("/api/v1/tenants/users", {
+      method: "PUT",
+      body: JSON.stringify(data)
+    });
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to update users role: ${response.status} - ${errorData}`
+      );
+    }
+    return await response.json();
+  }
+};
+
 // src/tenants/handler.ts
 var TenantHandler = class {
   /**
@@ -1169,10 +1317,27 @@ var TenantHandler = class {
    * @group Tenant Management
    */
   constructor(omnibaseClient) {
-    this.omnibaseClient = omnibaseClient;
-    this.invites = new TenantInviteManager(this.omnibaseClient);
-    this.manage = new TenantManger(this.omnibaseClient);
+    this.invites = new TenantInviteManager(omnibaseClient);
+    this.manage = new TenantManger(omnibaseClient);
+    this.user = new TenantUserManager(omnibaseClient);
   }
+  /**
+   * Tenant user management operations
+   *
+   * Provides access to operations for managing users within tenants, including
+   * removing users from the active tenant. All operations respect user permissions
+   * and tenant ownership rules.
+   *
+   * @example
+   * ```typescript
+   * // Remove a user from the active tenant
+   * await tenantHandler.user.remove({ user_id: 'user_123' });
+   * ```
+   *
+   * @since 0.6.0
+   * @group Tenant Management
+   */
+  user;
   /**
    * Core tenant management operations
    *
@@ -1183,17 +1348,17 @@ var TenantHandler = class {
    * @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);
    * ```
    */
   manage;
@@ -1207,9 +1372,10 @@ var TenantHandler = class {
    * @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)
@@ -1250,8 +1416,105 @@ var OmnibaseClient = class {
    * ```
    */
   payments = new PaymentHandler(this);
+  /**
+   * 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
+   */
   tenants = new TenantHandler(this);
+  /**
+   * 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
+   */
   permissions;
+  /**
+   * Storage client for file upload/download operations
+   *
+   * @example
+   * ```typescript
+   * // Upload with metadata
+   * await omnibase.storage.bucket('documents').upload(
+   *   'report.pdf',
+   *   file,
+   *   { metadata: { department: 'engineering' } }
+   * );
+   * ```
+   */
+  storage = new StorageClient(this);
   async fetch(endpoint, options = {}) {
     if (this.config.fetch)
       return this.config.fetch(this.config.api_url + endpoint, options);
@@ -1263,5 +1526,6 @@ var OmnibaseClient = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  OmnibaseClient
+  OmnibaseClient,
+  StorageClient
 });