@omnibase/core-js 0.7.5 → 0.8.0

package/dist/index.cjs

@@ -801,25 +801,56 @@ var PermissionsClient = class {
    * on an object. This API handles read operations and is optimized for fast
    * permission checks in your application logic.
    *
+   * All operations are proxied through Omnibase's API at `/api/v1/permissions/read`.
+   *
    * 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
+   * - `checkPermission(params)` - Checks if a subject has permission on an object
+   * - `checkPermissionOrError(params)` - Same as above but throws error if denied
+   * - `expandPermissions(namespace, object, relation, maxDepth?)` - Expands relationships to show all granted permissions
+   * - `postCheckPermission(maxDepth?, body)` - POST variant of permission check
    *
    * @example
+   * Check a single permission:
    * ```typescript
-   * // Check permission
-   * const result = await client.permissions.checkPermission(
-   *   undefined,
-   *   {
+   * const result = await omnibase.permissions.permissions.checkPermission({
+   *   namespace: 'Tenant',
+   *   object: 'tenant_123',
+   *   relation: 'view',
+   *   subjectId: 'user_456'
+   * });
+   *
+   * if (result.data.allowed) {
+   *   console.log('User has permission');
+   * }
+   * ```
+   *
+   * @example
+   * Expand permission tree:
+   * ```typescript
+   * const tree = await omnibase.permissions.permissions.expandPermissions(
+   *   'Tenant',
+   *   'tenant_123',
+   *   'view'
+   * );
+   *
+   * console.log('Permission tree:', tree.data);
+   * ```
+   *
+   * @example
+   * Check permission or throw error:
+   * ```typescript
+   * try {
+   *   await omnibase.permissions.permissions.checkPermissionOrError({
    *     namespace: 'Tenant',
    *     object: 'tenant_123',
-   *     relation: 'view',
+   *     relation: 'edit',
    *     subjectId: 'user_456'
-   *   }
-   * );
-   *
-   * console.log('Has permission:', result.data.allowed);
+   *   });
+   *   // Permission granted
+   * } catch (error) {
+   *   // Permission denied
+   *   console.error('Access denied');
+   * }
    * ```
    *
    * @since 1.0.0
@@ -833,20 +864,34 @@ var PermissionsClient = class {
    * and managing role assignments. Works alongside the Keto-based
    * permissions system to provide dynamic RBAC capabilities.
    *
+   * Roles are stored in the database and automatically synchronized with
+   * Ory Keto relationships, providing a higher-level abstraction over
+   * raw relationship tuples.
+   *
    * @example
+   * Create a custom role:
    * ```typescript
-   * // Create a custom role
    * const role = await omnibase.permissions.roles.create({
    *   role_name: 'billing_manager',
    *   permissions: ['tenant#manage_billing', 'tenant#view_invoices']
    * });
+   * ```
    *
-   * // Assign role to user
+   * @example
+   * Assign role to a user:
+   * ```typescript
    * await omnibase.permissions.roles.assign('user_123', {
    *   role_id: role.id
    * });
    * ```
    *
+   * @example
+   * List all roles:
+   * ```typescript
+   * const roles = await omnibase.permissions.roles.list();
+   * console.log('Available roles:', roles);
+   * ```
+   *
    * @since 0.7.0
    * @group Roles
    */
@@ -855,19 +900,43 @@ var PermissionsClient = class {
    * 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.
+   * The client automatically configures the Ory Keto client libraries to use
+   * Omnibase's permission proxy endpoints:
+   * - Write endpoint: `${apiBaseUrl}/api/v1/permissions/write`
+   * - Read endpoint: `${apiBaseUrl}/api/v1/permissions/read`
+   *
+   * This separation follows Ory Keto's recommended architecture for optimal
+   * performance and security.
    *
-   * @param apiBaseUrl - The base URL for your Omnibase API instance
-   * @param client - The main OmnibaseClient instance (for roles handler)
+   * @param apiBaseUrl - The base URL for your Omnibase API instance (e.g., 'https://api.example.com')
+   * @param client - The main OmnibaseClient instance (required for roles handler)
    *
    * @throws {Error} When the base URL is invalid or cannot be reached
    *
    * @example
+   * Direct instantiation (not recommended - use OmnibaseClient instead):
    * ```typescript
    * const client = new PermissionsClient('https://api.example.com', omnibaseClient);
    * ```
    *
+   * @example
+   * Recommended usage via OmnibaseClient:
+   * ```typescript
+   * import { OmnibaseClient } from '@omnibase/core-js';
+   *
+   * const omnibase = new OmnibaseClient({
+   *   apiUrl: 'https://api.example.com'
+   * });
+   *
+   * // Use the permissions client
+   * await omnibase.permissions.permissions.checkPermission({
+   *   namespace: 'Tenant',
+   *   object: 'tenant_123',
+   *   relation: 'view',
+   *   subjectId: 'user_456'
+   * });
+   * ```
+   *
    * @since 1.0.0
    * @group Client
    */
@@ -1423,6 +1492,157 @@ var TenantManger = class {
   }
 };
 
+// src/tenants/subscriptions.ts
+var TenantSubscriptionManager = class {
+  /**
+   * Creates a new TenantSubscriptionManager instance
+   *
+   * @param omnibaseClient - Configured Omnibase client instance
+   *
+   * @group Tenant Subscriptions
+   */
+  constructor(omnibaseClient) {
+    this.omnibaseClient = omnibaseClient;
+  }
+  /**
+   * Get all active subscriptions for the current tenant
+   *
+   * Retrieves all active Stripe subscriptions associated with the user's
+   * currently active tenant. Returns subscriptions with config-based price IDs
+   * instead of raw Stripe IDs, making it easier to match against your billing
+   * configuration.
+   *
+   * The endpoint automatically:
+   * - Fetches subscriptions from Stripe API
+   * - Maps Stripe price IDs to your config price IDs
+   * - Checks both current and historical price mappings
+   * - Flags legacy prices from old billing configurations
+   * - Filters to only active/trialing/past_due subscriptions
+   *
+   * Returns an empty array if:
+   * - Tenant has no Stripe customer ID configured
+   * - Tenant has no active subscriptions
+   * - User is not authenticated
+   *
+   * @returns Promise resolving to array of active subscriptions
+   *
+   * @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)
+   *
+   * @example
+   * ```typescript
+   * const response = await subscriptionManager.getActive();
+   *
+   * if (response.data.length === 0) {
+   *   console.log('No active subscriptions');
+   * } else {
+   *   response.data.forEach(sub => {
+   *     console.log(`Plan: ${sub.config_price_id}`);
+   *     console.log(`Status: ${sub.status}`);
+   *     if (sub.is_legacy_price) {
+   *       console.log('⚠️ Using legacy pricing');
+   *     }
+   *   });
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Subscriptions
+   */
+  async getActive() {
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/subscriptions`,
+        {
+          method: "GET",
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to fetch subscriptions: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error fetching tenant subscriptions:", error);
+      throw error;
+    }
+  }
+  /**
+   * Check if the current tenant has billing information configured
+   *
+   * Verifies whether the tenant has valid payment methods attached to their
+   * Stripe customer account. This is useful for:
+   * - Showing billing setup prompts
+   * - Gating premium features behind payment method requirement
+   * - Displaying billing status indicators in UI
+   * - Determining if customer portal access should be shown
+   *
+   * The check verifies:
+   * - Default payment source (card, bank account, etc.)
+   * - Default payment method in invoice settings
+   * - Whether the payment method is valid and active
+   *
+   * Returns `false` if:
+   * - Tenant has no Stripe customer ID
+   * - No payment methods are configured
+   * - User is not authenticated
+   *
+   * @returns Promise resolving to billing status information
+   *
+   * @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)
+   *
+   * @example
+   * ```typescript
+   * const response = await subscriptionManager.getBillingStatus();
+   *
+   * if (!response.data.has_billing_info) {
+   *   // Show billing setup prompt
+   *   showBillingSetupModal();
+   * } else if (!response.data.is_active) {
+   *   // Payment method exists but may be expired/invalid
+   *   showPaymentMethodUpdatePrompt();
+   * } else {
+   *   // All good - show customer portal link
+   *   showManageBillingButton();
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @public
+   * @group Tenant Subscriptions
+   */
+  async getBillingStatus() {
+    try {
+      const response = await this.omnibaseClient.fetch(
+        `/api/v1/tenants/billing-status`,
+        {
+          method: "GET",
+          credentials: "include"
+        }
+      );
+      if (!response.ok) {
+        const errorData = await response.text();
+        throw new Error(
+          `Failed to fetch billing status: ${response.status} - ${errorData}`
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Error fetching billing status:", error);
+      throw error;
+    }
+  }
+};
+
 // src/tenants/user.ts
 var TenantUserManager = class {
   /**
@@ -1634,6 +1854,7 @@ var TenantHandler = class {
   constructor(omnibaseClient) {
     this.invites = new TenantInviteManager(omnibaseClient);
     this.manage = new TenantManger(omnibaseClient);
+    this.subscriptions = new TenantSubscriptionManager(omnibaseClient);
     this.user = new TenantUserManager(omnibaseClient);
   }
   /**
@@ -1698,6 +1919,30 @@ var TenantHandler = class {
    * ```
    */
   invites;
+  /**
+   * Tenant subscription and billing management
+   *
+   * Provides access to subscription data and billing status for the
+   * active tenant, including legacy price detection and payment method
+   * verification. All operations are automatically scoped to the user's
+   * currently active tenant.
+   *
+   * @example
+   * ```typescript
+   * // Get active subscriptions
+   * const subs = await tenantHandler.subscriptions.getActive();
+   *
+   * // Check billing status
+   * const status = await tenantHandler.subscriptions.getBillingStatus();
+   * if (!status.data.has_billing_info) {
+   *   console.log('No payment method configured');
+   * }
+   * ```
+   *
+   * @since 0.6.0
+   * @group Tenant Management
+   */
+  subscriptions;
 };
 
 // src/client.ts

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-export { q as ApiResponse, A as AssignRoleRequest, C as CreateRoleRequest, D as DownloadResult, N as NamespaceDefinition, p as OmnibaseClient, O as OmnibaseClientConfig, P as PermissionsClient, a as Role, R as RolesHandler, S as StorageClient, U as UpdateRoleRequest, b as UploadOptions, c as UploadResult } from './payments/index.cjs';
+export { t as ApiResponse, A as AssignRoleRequest, C as CreateRoleRequest, D as DownloadResult, N as NamespaceDefinition, s as OmnibaseClient, O as OmnibaseClientConfig, P as PermissionsClient, a as Role, R as RolesHandler, S as StorageClient, U as UpdateRoleRequest, b as UploadOptions, c as UploadResult } from './payments/index.cjs';
 import '@ory/client';

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { q as ApiResponse, A as AssignRoleRequest, C as CreateRoleRequest, D as DownloadResult, N as NamespaceDefinition, p as OmnibaseClient, O as OmnibaseClientConfig, P as PermissionsClient, a as Role, R as RolesHandler, S as StorageClient, U as UpdateRoleRequest, b as UploadOptions, c as UploadResult } from './payments/index.js';
+export { t as ApiResponse, A as AssignRoleRequest, C as CreateRoleRequest, D as DownloadResult, N as NamespaceDefinition, s as OmnibaseClient, O as OmnibaseClientConfig, P as PermissionsClient, a as Role, R as RolesHandler, S as StorageClient, U as UpdateRoleRequest, b as UploadOptions, c as UploadResult } from './payments/index.js';
 import '@ory/client';

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   PermissionsClient,
   RolesHandler
-} from "./chunk-V4FWENQQ.js";
+} from "./chunk-5B37CXXH.js";
 import {
   PaymentHandler
 } from "./chunk-QPW6G4PA.js";
@@ -10,7 +10,7 @@ import {
 } from "./chunk-I6DMWC32.js";
 import {
   TenantHandler
-} from "./chunk-V6HVRJCU.js";
+} from "./chunk-TFAV5P6I.js";
 
 // src/client.ts
 var OmnibaseClient = class {