@omnibase/core-js 0.4.2 → 0.5.1

package/dist/index.d.cts

@@ -1,10 +1,3 @@
-/**
- * Base API Response structure for API
- */
-type ApiResponse<T> = {
-    data?: T;
-    status: number;
-    error?: string;
-};
-
-export type { ApiResponse };
+export { i as OmnibaseClient, O as OmnibaseClientConfig } from './payments/index.cjs';
+import './permissions/index.cjs';
+import '@ory/client';

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./auth/index";
-export * from "./database/index";
-export * from "./tenants/index";
+export { i as OmnibaseClient, O as OmnibaseClientConfig } from './payments/index.js';
+import './permissions/index.js';
+import '@ory/client';

package/dist/index.js

@@ -0,0 +1,51 @@
+import {
+  PermissionsClient
+} from "./chunk-DDFBRGMG.js";
+import {
+  TenantHandler
+} from "./chunk-LIS5WD3H.js";
+import {
+  PaymentHandler
+} from "./chunk-767PUXYD.js";
+
+// 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);
+  }
+};
+export {
+  OmnibaseClient
+};

package/dist/payments/index.cjs

@@ -20,62 +20,218 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/payments/index.ts
 var payments_exports = {};
 __export(payments_exports, {
-  createCheckout: () => createCheckout,
-  createCustomerPortal: () => createCustomerPortal,
-  getAvailableProducts: () => getAvailableProducts,
-  getProduct: () => getProduct,
-  getStripeConfig: () => getStripeConfig,
-  recordUsage: () => recordUsage
+  CheckoutManager: () => CheckoutManager,
+  ConfigManager: () => ConfigManager,
+  PaymentHandler: () => PaymentHandler,
+  PortalManager: () => PortalManager,
+  UsageManager: () => UsageManager
 });
 module.exports = __toCommonJS(payments_exports);
 
-// src/payments/config.ts
-async function getStripeConfig() {
-  const baseUrl = process.env.OMNIBASE_API_URL;
-  if (!baseUrl) {
-    throw new Error("OMNIBASE_API_URL is not configured");
-  }
-  try {
-    const response = await fetch(`${baseUrl}/api/v1/stripe/config`, {
-      method: "GET",
-      headers: {
-        "Content-Type": "application/json"
-      },
-      credentials: "include"
-    });
+// 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 get Stripe config: ${response.status} - ${errorData}`
+        `Failed to create checkout session: ${response.status} - ${errorData}`
       );
     }
-    const data = await response.json();
-    return data;
-  } catch (error) {
-    console.error("Error getting Stripe config:", error);
-    throw error;
+    const result = await response.json();
+    return result;
   }
-}
-async function getAvailableProducts() {
-  const configResponse = await 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
-  );
-}
-async function getProduct(productId) {
-  const configResponse = await getStripeConfig();
-  if (!configResponse.data?.config) {
-    return null;
-  }
-  const product = configResponse.data.config.products.find(
-    (p) => p.id === productId
-  );
-  return product || null;
-}
+};
+
+// 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 {
@@ -149,47 +305,282 @@ function formatDefaultBillingPeriod(price) {
   return "one-time";
 }
 
-// src/payments/checkout.ts
-var API_URL = process.env.OMNIBASE_API_URL;
-if (!API_URL) throw new Error("must set OMNIBASE_API_URL in env variables");
-var createCheckout = async (options) => {
-  const response = await fetch(API_URL + "/api/v1/payments/checkout", {
-    method: "POST",
-    body: JSON.stringify(options)
-  });
-  const result = await response.json();
-  return result;
-};
-
 // src/payments/portal.ts
-var API_URL2 = process.env.OMNIBASE_API_URL;
-if (!API_URL2) throw new Error("must set OMNIBASE_API_URL in env variables");
-var createCustomerPortal = async (options) => {
-  const response = await fetch(API_URL2 + "/api/v1/payments/portal", {
-    method: "POST",
-    body: JSON.stringify(options)
-  });
-  const result = await response.json();
-  return result;
+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 API_URL3 = process.env.OMNIBASE_API_URL;
-if (!API_URL3) throw new Error("must set OMNIBASE_API_URL in env variables");
-var recordUsage = async (options) => {
-  const response = await fetch(API_URL3 + "/api/v1/payments/usage", {
-    method: "POST",
-    body: JSON.stringify(options)
-  });
-  const result = await response.json();
-  return result;
+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;
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createCheckout,
-  createCustomerPortal,
-  getAvailableProducts,
-  getProduct,
-  getStripeConfig,
-  recordUsage
+  CheckoutManager,
+  ConfigManager,
+  PaymentHandler,
+  PortalManager,
+  UsageManager
 });