@omnibase/core-js 0.5.0 → 0.5.2

package/dist/chunk-767PUXYD.js

@@ -0,0 +1,556 @@
+// 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;
+};
+
+export {
+  CheckoutManager,
+  ConfigManager,
+  PortalManager,
+  UsageManager,
+  PaymentHandler
+};

package/dist/chunk-DDFBRGMG.js

@@ -0,0 +1,106 @@
+// src/permissions/handler.ts
+import { RelationshipApi, PermissionApi } from "@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 RelationshipApi(
+      void 0,
+      `${apiBaseUrl}/api/v1/permissions/write`
+    );
+    this.permissions = new PermissionApi(
+      void 0,
+      `${apiBaseUrl}/api/v1/permissions/read`
+    );
+  }
+};
+
+export {
+  PermissionsClient
+};