@omnibase/core-js 0.5.8 → 0.5.9

package/dist/chunk-PNP3T7XU.js

@@ -0,0 +1,542 @@
+// 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 checkout mode (one-time payment or subscription) is automatically
+   * determined from the price's configuration - no need to specify it manually.
+   *
+   * @param options - Configuration options for the checkout session
+   * @param options.price_id - Stripe price ID for the product/service
+   * @param options.success_url - URL to redirect after successful payment
+   * @param options.cancel_url - URL to redirect if user cancels
+   *
+   * @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
+   * Creating a checkout session (mode is auto-detected):
+   * ```typescript
+   * const session = await checkoutManager.createSession({
+   *   price_id: 'price_one_time_product',
+   *   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}`);
+   * ```
+   *
+   * @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.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
+   * @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'
+   *   });
+   *
+   *   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.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',
+   *   value: '1'
+   * });
+   * ```
+   *
+   * @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
+   * @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',
+   *   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({
+   *   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',
+   *   value: '1'
+   * });
+   * ```
+   */
+  usage;
+};
+
+export {
+  CheckoutManager,
+  ConfigManager,
+  PortalManager,
+  UsageManager,
+  PaymentHandler
+};

package/dist/index.cjs

@@ -41,12 +41,11 @@ var CheckoutManager = class {
    *
    * 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.
+   * The checkout mode (one-time payment or subscription) is automatically
+   * determined from the price's configuration - no need to specify it manually.
    *
    * @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
    *
@@ -57,11 +56,10 @@ var CheckoutManager = class {
    * @throws {ValidationError} When required parameters are missing or invalid
    *
    * @example
-   * One-time payment checkout:
+   * Creating a checkout session (mode is auto-detected):
    * ```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'
    * });
@@ -71,12 +69,11 @@ var CheckoutManager = class {
    * ```
    *
    * @example
-   * Subscription checkout with existing customer:
+   * Checkout with session tracking:
    * ```typescript
    * const session = await checkoutManager.createSession({
    *   price_id: 'price_monthly_plan',
-   *   mode: 'subscription',
-   *   success_url: 'https://app.com/dashboard?welcome=true',
+   *   success_url: 'https://app.com/dashboard?session_id={CHECKOUT_SESSION_ID}',
    *   cancel_url: 'https://app.com/pricing',
    * });
    *
@@ -512,7 +509,6 @@ var PaymentHandler = class {
    * ```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'
    * });
@@ -1242,10 +1238,9 @@ var OmnibaseClient = class {
    *
    * @example
    * ```typescript
-   * // Create a checkout session
+   * // Create a checkout session (mode auto-detected from price)
    * 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'
    * });

package/dist/index.js

@@ -1,12 +1,12 @@
 import {
   PermissionsClient
 } from "./chunk-DDFBRGMG.js";
+import {
+  PaymentHandler
+} from "./chunk-PNP3T7XU.js";
 import {
   TenantHandler
 } from "./chunk-L7EZC6WP.js";
-import {
-  PaymentHandler
-} from "./chunk-KGG7T6KJ.js";
 
 // src/client.ts
 var OmnibaseClient = class {
@@ -27,10 +27,9 @@ var OmnibaseClient = class {
    *
    * @example
    * ```typescript
-   * // Create a checkout session
+   * // Create a checkout session (mode auto-detected from price)
    * 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'
    * });

package/dist/payments/index.cjs

@@ -45,12 +45,11 @@ var CheckoutManager = class {
    *
    * 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.
+   * The checkout mode (one-time payment or subscription) is automatically
+   * determined from the price's configuration - no need to specify it manually.
    *
    * @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
    *
@@ -61,11 +60,10 @@ var CheckoutManager = class {
    * @throws {ValidationError} When required parameters are missing or invalid
    *
    * @example
-   * One-time payment checkout:
+   * Creating a checkout session (mode is auto-detected):
    * ```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'
    * });
@@ -75,12 +73,11 @@ var CheckoutManager = class {
    * ```
    *
    * @example
-   * Subscription checkout with existing customer:
+   * Checkout with session tracking:
    * ```typescript
    * const session = await checkoutManager.createSession({
    *   price_id: 'price_monthly_plan',
-   *   mode: 'subscription',
-   *   success_url: 'https://app.com/dashboard?welcome=true',
+   *   success_url: 'https://app.com/dashboard?session_id={CHECKOUT_SESSION_ID}',
    *   cancel_url: 'https://app.com/pricing',
    * });
    *
@@ -516,7 +513,6 @@ var PaymentHandler = class {
    * ```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'
    * });

package/dist/payments/index.d.cts

@@ -73,12 +73,6 @@ type ApiResponse<T> = {
 type CheckoutOptions = {
     /** Stripe price ID for the product/service being purchased */
     price_id: string;
-    /**
-     * Checkout mode determining the type of transaction
-     * - 'payment': One-time payment
-     * - 'subscription': Recurring subscription
-     */
-    mode: "payment" | "subscription";
     /**
      * URL to redirect to after successful payment
      * Can include {CHECKOUT_SESSION_ID} placeholder for session tracking
@@ -115,13 +109,12 @@ type CreateCheckoutResponse = ApiResponse<{
  * sensitive payment data to touch your servers.
  *
  * @example
- * Creating a subscription checkout:
+ * Creating a checkout session (mode auto-detected from price):
  * ```typescript
  * const checkoutManager = new CheckoutManager(paymentHandler);
  *
  * const session = await checkoutManager.createSession({
  *   price_id: 'price_monthly_pro',
- *   mode: 'subscription',
  *   success_url: 'https://app.com/welcome?session_id={CHECKOUT_SESSION_ID}',
  *   cancel_url: 'https://app.com/pricing',
  * });
@@ -149,12 +142,11 @@ declare class CheckoutManager {
      *
      * 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.
+     * The checkout mode (one-time payment or subscription) is automatically
+     * determined from the price's configuration - no need to specify it manually.
      *
      * @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
      *
@@ -165,11 +157,10 @@ declare class CheckoutManager {
      * @throws {ValidationError} When required parameters are missing or invalid
      *
      * @example
-     * One-time payment checkout:
+     * Creating a checkout session (mode is auto-detected):
      * ```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'
      * });
@@ -179,12 +170,11 @@ declare class CheckoutManager {
      * ```
      *
      * @example
-     * Subscription checkout with existing customer:
+     * Checkout with session tracking:
      * ```typescript
      * const session = await checkoutManager.createSession({
      *   price_id: 'price_monthly_plan',
-     *   mode: 'subscription',
-     *   success_url: 'https://app.com/dashboard?welcome=true',
+     *   success_url: 'https://app.com/dashboard?session_id={CHECKOUT_SESSION_ID}',
      *   cancel_url: 'https://app.com/pricing',
      * });
      *
@@ -983,10 +973,9 @@ declare class UsageManager {
  * ```typescript
  * const paymentHandler = new PaymentHandler('https://api.example.com');
  *
- * // Create a checkout session
+ * // Create a checkout session (mode auto-detected from price)
  * const checkout = await paymentHandler.checkout.createSession({
  *   price_id: 'price_123',
- *   mode: 'subscription',
  *   success_url: 'https://app.com/success',
  *   cancel_url: 'https://app.com/cancel'
  * });
@@ -1029,7 +1018,6 @@ declare class PaymentHandler {
      * ```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'
      * });
@@ -1941,10 +1929,9 @@ declare class OmnibaseClient {
      *
      * @example
      * ```typescript
-     * // Create a checkout session
+     * // Create a checkout session (mode auto-detected from price)
      * 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'
      * });

package/dist/payments/index.d.ts

@@ -73,12 +73,6 @@ type ApiResponse<T> = {
 type CheckoutOptions = {
     /** Stripe price ID for the product/service being purchased */
     price_id: string;
-    /**
-     * Checkout mode determining the type of transaction
-     * - 'payment': One-time payment
-     * - 'subscription': Recurring subscription
-     */
-    mode: "payment" | "subscription";
     /**
      * URL to redirect to after successful payment
      * Can include {CHECKOUT_SESSION_ID} placeholder for session tracking
@@ -115,13 +109,12 @@ type CreateCheckoutResponse = ApiResponse<{
  * sensitive payment data to touch your servers.
  *
  * @example
- * Creating a subscription checkout:
+ * Creating a checkout session (mode auto-detected from price):
  * ```typescript
  * const checkoutManager = new CheckoutManager(paymentHandler);
  *
  * const session = await checkoutManager.createSession({
  *   price_id: 'price_monthly_pro',
- *   mode: 'subscription',
  *   success_url: 'https://app.com/welcome?session_id={CHECKOUT_SESSION_ID}',
  *   cancel_url: 'https://app.com/pricing',
  * });
@@ -149,12 +142,11 @@ declare class CheckoutManager {
      *
      * 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.
+     * The checkout mode (one-time payment or subscription) is automatically
+     * determined from the price's configuration - no need to specify it manually.
      *
      * @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
      *
@@ -165,11 +157,10 @@ declare class CheckoutManager {
      * @throws {ValidationError} When required parameters are missing or invalid
      *
      * @example
-     * One-time payment checkout:
+     * Creating a checkout session (mode is auto-detected):
      * ```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'
      * });
@@ -179,12 +170,11 @@ declare class CheckoutManager {
      * ```
      *
      * @example
-     * Subscription checkout with existing customer:
+     * Checkout with session tracking:
      * ```typescript
      * const session = await checkoutManager.createSession({
      *   price_id: 'price_monthly_plan',
-     *   mode: 'subscription',
-     *   success_url: 'https://app.com/dashboard?welcome=true',
+     *   success_url: 'https://app.com/dashboard?session_id={CHECKOUT_SESSION_ID}',
      *   cancel_url: 'https://app.com/pricing',
      * });
      *
@@ -983,10 +973,9 @@ declare class UsageManager {
  * ```typescript
  * const paymentHandler = new PaymentHandler('https://api.example.com');
  *
- * // Create a checkout session
+ * // Create a checkout session (mode auto-detected from price)
  * const checkout = await paymentHandler.checkout.createSession({
  *   price_id: 'price_123',
- *   mode: 'subscription',
  *   success_url: 'https://app.com/success',
  *   cancel_url: 'https://app.com/cancel'
  * });
@@ -1029,7 +1018,6 @@ declare class PaymentHandler {
      * ```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'
      * });
@@ -1941,10 +1929,9 @@ declare class OmnibaseClient {
      *
      * @example
      * ```typescript
-     * // Create a checkout session
+     * // Create a checkout session (mode auto-detected from price)
      * 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'
      * });

package/dist/payments/index.js

@@ -4,7 +4,7 @@ import {
   PaymentHandler,
   PortalManager,
   UsageManager
-} from "../chunk-KGG7T6KJ.js";
+} from "../chunk-PNP3T7XU.js";
 export {
   CheckoutManager,
   ConfigManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnibase/core-js",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "OmniBase core Javascript SDK - framework agnostic",
   "files": [
     "dist/**/*"