@omnibase/core-js 0.6.0 → 0.7.1

package/dist/index.cjs

@@ -57,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) {
@@ -302,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
    */
@@ -329,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) {
@@ -384,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
    */
@@ -413,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({
@@ -422,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) {
@@ -477,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) {
@@ -509,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;
@@ -833,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
@@ -853,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) {
@@ -902,67 +838,53 @@ 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}`;
+   * console.log(`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
+   * @since 0.6.0
    * @public
-   * @group User Management
+   * @group Tenant Invitations
    */
   async create(inviteData) {
     if (!inviteData.email || !inviteData.role || !inviteData.invite_url) {
       throw new Error(
-        "Missing data in `create` - email, role, invite_url and tenant_id are required"
+        "Missing data in `create` - email, role, and invite_url are required"
       );
     }
     try {
@@ -1031,17 +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(`Tenant created: ${newTenant.data.tenant.id}`);
+   * ```
    *
-   * @since 1.0.0
+   * @since 0.6.0
    * @public
    * @group Tenant Management
    */
@@ -1106,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';
    *
@@ -1117,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';
@@ -1128,7 +1049,7 @@ var TenantManger = class {
    * }
    * ```
    *
-   * @since 1.0.0
+   * @since 0.6.0
    * @public
    * @group Tenant Management
    */
@@ -1191,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
    */
@@ -1317,7 +1209,7 @@ var TenantUserManager = class {
    * }
    * ```
    *
-   * @since 1.0.0
+   * @since 0.6.0
    * @public
    * @group Tenant User Management
    */
@@ -1381,7 +1273,7 @@ var TenantUserManager = class {
    * }
    * ```
    *
-   * @since 1.0.0
+   * @since 0.6.0
    * @public
    * @group Tenant User Management
    */
@@ -1442,7 +1334,7 @@ var TenantHandler = class {
    * await tenantHandler.user.remove({ user_id: 'user_123' });
    * ```
    *
-   * @since 1.0.0
+   * @since 0.6.0
    * @group Tenant Management
    */
   user;
@@ -1456,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;
@@ -1480,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)
@@ -1523,7 +1416,90 @@ 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

package/dist/index.js

@@ -1,15 +1,15 @@
-import {
-  PaymentHandler
-} from "./chunk-PNP3T7XU.js";
 import {
   PermissionsClient
 } from "./chunk-DDFBRGMG.js";
+import {
+  PaymentHandler
+} from "./chunk-QPW6G4PA.js";
 import {
   StorageClient
 } from "./chunk-I6DMWC32.js";
 import {
   TenantHandler
-} from "./chunk-LMDKQ6Z2.js";
+} from "./chunk-6OGESVXW.js";
 
 // src/client.ts
 var OmnibaseClient = class {
@@ -42,7 +42,90 @@ 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