@omnibase/core-js 0.5.0 → 0.5.1

package/dist/index.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -15,4 +19,1259 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  OmnibaseClient: () => OmnibaseClient
+});
 module.exports = __toCommonJS(index_exports);
+
+// src/payments/checkout.ts
+var CheckoutManager = class {
+  /**
+   * Initialize the checkout manager
+   *
+   * @param paymentHandler - Payment handler instance for API communication
+   *
+   * @group Checkout
+   */
+  constructor(omnibaseClient) {
+    this.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
+   */
+  async createSession(options) {
+    const response = await this.omnibaseClient.fetch(
+      "/api/v1/payments/checkout",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(options)
+      }
+    );
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to create checkout session: ${response.status} - ${errorData}`
+      );
+    }
+    const result = await response.json();
+    return result;
+  }
+};
+
+// src/payments/config.ts
+var ConfigManager = class {
+  constructor(omnibaseClient) {
+    this.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'}`);
+   * });
+   * ```
+   */
+  async getStripeConfig() {
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/stripe/config`,
+        {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to get Stripe config: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error getting Stripe config:", error);
+      throw error;
+    }
+  }
+  /**
+   * 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}`);
+   *   });
+   * });
+   * ```
+   */
+  async getAvailableProducts() {
+    const configResponse = await this.getStripeConfig();
+    if (!configResponse.data?.config) {
+      throw new Error("No Stripe configuration found");
+    }
+    const products = configResponse.data.config.products;
+    return products.map(transformProductToUIReady).sort(
+      (a, b) => a.pricing_display.sort_order - b.pricing_display.sort_order
+    );
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async getProduct(productId) {
+    const configResponse = await this.getStripeConfig();
+    if (!configResponse.data?.config) {
+      return null;
+    }
+    const product = configResponse.data.config.products.find(
+      (p) => p.id === productId
+    );
+    return product || null;
+  }
+};
+function transformProductToUIReady(product) {
+  const ui = product.ui || {};
+  return {
+    ...product,
+    pricing_display: {
+      name: ui.display_name || product.name,
+      tagline: ui.tagline,
+      features: ui.features || [],
+      badge: ui.badge,
+      cta_text: ui.cta_text || "Choose Plan",
+      highlighted: ui.highlighted || false,
+      sort_order: ui.sort_order || 0,
+      prices: product.prices.map((price) => {
+        const priceUI = price.ui || {};
+        return {
+          id: price.id,
+          display_name: priceUI.display_name || formatDefaultPriceName(price),
+          formatted_price: formatPrice(price, priceUI),
+          billing_period: priceUI.billing_period || formatDefaultBillingPeriod(price),
+          features: priceUI.features || [],
+          limits: priceUI.limits || []
+        };
+      })
+    }
+  };
+}
+function formatPrice(price, priceUI) {
+  if (priceUI.price_display?.custom_text) {
+    return priceUI.price_display.custom_text;
+  }
+  if (!price.amount || price.amount === 0) {
+    return "Free";
+  }
+  const amount = price.amount / 100;
+  const currency = price.currency.toUpperCase();
+  let formattedPrice = "";
+  if (priceUI.price_display?.show_currency !== false) {
+    const currencySymbol = getCurrencySymbol(currency);
+    formattedPrice = `${currencySymbol}${amount.toFixed(2)}`;
+  } else {
+    formattedPrice = amount.toFixed(2);
+  }
+  if (priceUI.price_display?.suffix) {
+    formattedPrice += ` ${priceUI.price_display.suffix}`;
+  }
+  return formattedPrice;
+}
+function getCurrencySymbol(currency) {
+  const symbols = {
+    USD: "$",
+    EUR: "\u20AC",
+    GBP: "\xA3",
+    JPY: "\xA5",
+    CAD: "C$",
+    AUD: "A$"
+  };
+  return symbols[currency] || currency;
+}
+function formatDefaultPriceName(price) {
+  if (price.interval) {
+    return price.interval.charAt(0).toUpperCase() + price.interval.slice(1);
+  }
+  return "One-time";
+}
+function formatDefaultBillingPeriod(price) {
+  if (price.interval) {
+    const count = price.interval_count || 1;
+    const period = count === 1 ? price.interval : `${count} ${price.interval}s`;
+    return `per ${period}`;
+  }
+  return "one-time";
+}
+
+// src/payments/portal.ts
+var PortalManager = class {
+  /**
+   * Initialize the portal manager
+   *
+   * @param paymentHandler - Payment handler instance for API communication
+   *
+   * @group Portal
+   */
+  constructor(omnibaseClient) {
+    this.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
+   */
+  async create(options) {
+    const response = await this.omnibaseClient.fetch(
+      "/api/v1/payments/portal",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(options)
+      }
+    );
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to create customer portal: ${response.status} - ${errorData}`
+      );
+    }
+    const result = await response.json();
+    return result;
+  }
+};
+
+// src/payments/usage.ts
+var UsageManager = class {
+  /**
+   * Initialize the usage manager
+   *
+   * @param paymentHandler - Payment handler instance for API communication
+   *
+   * @group Usage
+   */
+  constructor(omnibaseClient) {
+    this.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
+   */
+  async recordUsage(options) {
+    const response = await this.omnibaseClient.fetch("/api/v1/payments/usage", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(
+        `Failed to record usage: ${response.status} - ${errorData}`
+      );
+    }
+    const result = await response.json();
+    return result;
+  }
+};
+
+// src/payments/handler.ts
+var PaymentHandler = class {
+  /**
+   * 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) {
+    this.omnibaseClient = omnibaseClient;
+    this.checkout = new CheckoutManager(this.omnibaseClient);
+    this.config = new ConfigManager(this.omnibaseClient);
+    this.portal = new PortalManager(this.omnibaseClient);
+    this.usage = new UsageManager(this.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'
+   * });
+   * ```
+   */
+  checkout;
+  /**
+   * 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();
+   * ```
+   */
+  config;
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  portal;
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  usage;
+};
+
+// src/permissions/handler.ts
+var import_client = require("@ory/client");
+var PermissionsClient = class {
+  /**
+   * Ory Keto RelationshipApi for managing subject-object relationships
+   *
+   * Provides methods for creating, updating, and deleting relationships between
+   * subjects (users, groups) and objects (tenants, resources). This API handles
+   * write operations and is used to establish permission structures.
+   *
+   * Key methods:
+   * - `createRelationship()` - Creates a new relationship tuple
+   * - `deleteRelationships()` - Removes existing relationship tuples
+   * - `getRelationships()` - Queries existing relationships
+   * - `patchRelationships()` - Updates multiple relationships atomically
+   *
+   * @example
+   * ```typescript
+   * // Create a relationship
+   * await client.relationships.createRelationship(
+   *   undefined,
+   *   {
+   *     namespace: 'Tenant',
+   *     object: 'tenant_123',
+   *     relation: 'members',
+   *     subjectId: 'user_456'
+   *   }
+   * );
+   * ```
+   *
+   * @since 1.0.0
+   * @group Relationships
+   */
+  relationships;
+  /**
+   * Ory Keto PermissionApi for checking permissions
+   *
+   * Provides methods for querying whether a subject has a specific permission
+   * on an object. This API handles read operations and is optimized for fast
+   * permission checks in your application logic.
+   *
+   * Key methods:
+   * - `checkPermission()` - Checks if a subject has permission on an object
+   * - `checkPermissionOrError()` - Same as above but throws error if denied
+   * - `expandPermissions()` - Expands relationships to show all granted permissions
+   *
+   * @example
+   * ```typescript
+   * // Check permission
+   * const result = await client.permissions.checkPermission(
+   *   undefined,
+   *   {
+   *     namespace: 'Tenant',
+   *     object: 'tenant_123',
+   *     relation: 'view',
+   *     subjectId: 'user_456'
+   *   }
+   * );
+   *
+   * console.log('Has permission:', result.data.allowed);
+   * ```
+   *
+   * @since 1.0.0
+   * @group Permissions
+   */
+  permissions;
+  /**
+   * Creates a new PermissionsClient instance
+   *
+   * Initializes the client with separate endpoints for read and write operations.
+   * The client automatically appends the appropriate Keto API paths to the base URL
+   * for optimal performance and security separation.
+   *
+   * @param apiBaseUrl - The base URL for your Omnibase API instance
+   *
+   * @throws {Error} When the base URL is invalid or cannot be reached
+   *
+   * @example
+   * ```typescript
+   * const client = new PermissionsClient('https://api.example.com');
+   * ```
+   *
+   * @example
+   * Local development:
+   * ```typescript
+   * const client = new PermissionsClient('http://localhost:8080');
+   * ```
+   *
+   * @since 1.0.0
+   * @group Client
+   */
+  constructor(apiBaseUrl) {
+    this.relationships = new import_client.RelationshipApi(
+      void 0,
+      `${apiBaseUrl}/api/v1/permissions/write`
+    );
+    this.permissions = new import_client.PermissionApi(
+      void 0,
+      `${apiBaseUrl}/api/v1/permissions/read`
+    );
+  }
+};
+
+// src/tenants/invites.ts
+var TenantInviteManager = class {
+  /**
+   * 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) {
+    this.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
+   */
+  async accept(token) {
+    if (!token) {
+      throw new Error("Invite token is required");
+    }
+    const requestBody = {
+      token
+    };
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/invites/accept`,
+        {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody),
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to accept invite: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error accepting tenant invite:", error);
+      throw error;
+    }
+  }
+  /**
+   * 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
+   */
+  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");
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/${tenantId}/invites`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(inviteData),
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to create invite: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error creating tenant user invite:", error);
+      throw error;
+    }
+  }
+};
+
+// src/tenants/tenants.ts
+var TenantManger = class {
+  /**
+   * 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) {
+    this.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
+   */
+  async createTenant(tenantData) {
+    if (!tenantData.name || !tenantData.user_id) {
+      throw new Error("Name and user_id are required");
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(`/api/v1/tenants`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(tenantData),
+        credentials: "include"
+      });
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to create tenant: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error creating tenant:", error);
+      throw error;
+    }
+  }
+  /**
+   * 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
+   */
+  async deleteTenant(tenantId) {
+    if (!tenantId) {
+      throw new Error("Tenant ID is required");
+    }
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/${tenantId}`,
+        {
+          method: "DELETE",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to delete tenant: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error deleting tenant:", error);
+      throw error;
+    }
+  }
+  /**
+   * 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
+   */
+  async switchActiveTenant(tenantId) {
+    if (!tenantId) {
+      throw new Error("Tenant ID is required");
+    }
+    const requestBody = {
+      tenant_id: tenantId
+    };
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/switch-active`,
+        {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody),
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to switch tenant: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error switching active tenant:", error);
+      throw error;
+    }
+  }
+};
+
+// src/tenants/handler.ts
+var TenantHandler = class {
+  /**
+   * 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) {
+    this.omnibaseClient = omnibaseClient;
+    this.invites = new TenantInviteManager(this.omnibaseClient);
+    this.tenants = new TenantManger(this.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);
+   * ```
+   */
+  tenants;
+  /**
+   * 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');
+   * ```
+   */
+  invites;
+};
+
+// src/client.ts
+var OmnibaseClient = class {
+  constructor(config) {
+    this.config = config;
+    this.permissions = new PermissionsClient(this.config.api_url);
+  }
+  /**
+   * 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();
+   * ```
+   */
+  payments = new PaymentHandler(this);
+  tenants = new TenantHandler(this);
+  permissions;
+  async fetch(endpoint, options = {}) {
+    return await fetch(this.config.api_url + endpoint, options);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OmnibaseClient
+});