@omnibase/core-js 0.7.5 → 0.8.0

package/dist/payments/index.d.ts

@@ -79,6 +79,21 @@ type CheckoutOptions = {
     success_url: string;
     /** URL to redirect to if the user cancels the checkout */
     cancel_url: string;
+    /**
+     * Number of days for the trial period (subscriptions only)
+     * Only applies when the price has a recurring interval
+     */
+    trial_period_days?: number;
+    /**
+     * Stripe promotion code ID to apply automatically
+     * Mutually exclusive with allow_promotion_codes
+     */
+    promotion_code?: string;
+    /**
+     * Whether to show promotion code input field in checkout
+     * Allows customers to enter their own promo codes
+     */
+    allow_promotion_codes?: boolean;
 };
 /**
  * Response from creating a checkout session
@@ -1451,97 +1466,80 @@ declare class RolesHandler {
 /**
  * Client for managing permissions and relationships using Ory Keto
  *
- * This client provides access to Ory Keto's permission system, allowing you to
- * create, manage, and check relationships between subjects and objects. It handles
- * both read operations (permission checks) and write operations (relationship management).
+ * This client provides access to Ory Keto's permission system through Omnibase's API,
+ * allowing you to create, manage, and check relationships between subjects and objects.
+ * It handles both read operations (permission checks) and write operations (relationship management).
  *
- * The client automatically configures separate endpoints for read and write operations
- * to optimize performance and security by following Ory Keto's recommended architecture.
+ * The client automatically configures separate endpoints for read and write operations:
+ * - Read operations (permission checks): `/api/v1/permissions/read`
+ * - Write operations (relationship management): `/api/v1/permissions/write`
+ *
+ * This separation optimizes performance and security by following Ory Keto's recommended architecture.
  *
  * @example
- * Basic permission checking:
+ * Initialize the permissions client:
  * ```typescript
- * import { PermissionsClient } from '@omnibase/core-js/permissions';
+ * import { OmnibaseClient } from '@omnibase/core-js';
+ *
+ * const omnibase = new OmnibaseClient({
+ *   apiUrl: 'https://api.example.com'
+ * });
  *
- * const permissionsClient = new PermissionsClient('https://api.example.com');
+ * // Access permissions client
+ * const permissions = omnibase.permissions;
+ * ```
  *
+ * @example
+ * Check if a user has permission:
+ * ```typescript
  * // Check if a user can view a tenant
- * const canView = await permissionsClient.permissions.checkPermission(
- *   undefined,
- *   {
- *     namespace: 'Tenant',
- *     object: 'tenant_123',
- *     relation: 'view',
- *     subjectId: 'user_456'
- *   }
- * );
+ * const result = await omnibase.permissions.permissions.checkPermission({
+ *   namespace: 'Tenant',
+ *   object: 'tenant_123',
+ *   relation: 'view',
+ *   subjectId: 'user_456'
+ * });
  *
- * if (canView.data.allowed) {
+ * if (result.data.allowed) {
  *   console.log('User can view the tenant');
  * }
  * ```
  *
  * @example
- * Creating tenant relationships:
+ * Create relationships:
  * ```typescript
- * // Create a relationship making a user an owner of a tenant
- * await permissionsClient.relationships.createRelationship(
- *   undefined,
- *   {
- *     namespace: 'Tenant',
- *     object: 'tenant_123',
- *     relation: 'owners',
- *     subjectId: 'user_456'
- *   }
- * );
- *
- * // Now the user has owner permissions on the tenant
- * console.log('User is now an owner of the tenant');
+ * // Make a user an owner of a tenant
+ * await omnibase.permissions.relationships.createRelationship({
+ *   namespace: 'Tenant',
+ *   object: 'tenant_123',
+ *   relation: 'owners',
+ *   subjectId: 'user_456'
+ * });
  * ```
  *
  * @example
- * Complex tenant permission management:
+ * Query existing relationships:
  * ```typescript
- * const tenantId = 'tenant_123';
- * const userId = 'user_456';
- *
- * // Grant admin permissions to a user
- * await permissionsClient.relationships.createRelationship(
- *   undefined,
- *   {
- *     namespace: 'Tenant',
- *     object: tenantId,
- *     relation: 'admins',
- *     subjectId: userId
- *   }
- * );
- *
- * // Check if user can manage members (admins and owners can)
- * const canManageMembers = await permissionsClient.permissions.checkPermission(
- *   undefined,
- *   {
- *     namespace: 'Tenant',
- *     object: tenantId,
- *     relation: 'manage_members',
- *     subjectId: userId
- *   }
- * );
+ * // Get all members of a tenant
+ * const relationships = await omnibase.permissions.relationships.getRelationships({
+ *   namespace: 'Tenant',
+ *   object: 'tenant_123',
+ *   relation: 'members'
+ * });
  *
- * if (canManageMembers.data.allowed) {
- *   // User can invite/remove members
- *   console.log('User can manage tenant members');
- * }
+ * console.log('Tenant members:', relationships.data.relation_tuples);
+ * ```
  *
- * // Later, remove admin permissions
- * await permissionsClient.relationships.deleteRelationships(
- *   undefined,
- *   {
- *     namespace: 'Tenant',
- *     object: tenantId,
- *     relation: 'admins',
- *     subjectId: userId
- *   }
- * );
+ * @example
+ * Delete relationships:
+ * ```typescript
+ * // Remove a user from tenant admins
+ * await omnibase.permissions.relationships.deleteRelationships({
+ *   namespace: 'Tenant',
+ *   object: 'tenant_123',
+ *   relation: 'admins',
+ *   subjectId: 'user_456'
+ * });
  * ```
  *
  * @since 1.0.0
@@ -1587,25 +1585,56 @@ declare class PermissionsClient {
      * 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
@@ -1619,20 +1648,34 @@ declare class PermissionsClient {
      * 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
      */
@@ -1641,19 +1684,43 @@ declare class PermissionsClient {
      * 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
      */
@@ -2440,6 +2507,219 @@ declare class TenantManger {
     switchActiveTenant(tenantId: string): Promise<SwitchActiveTenantResponse>;
 }
 
+/**
+ * Active subscription data returned from the API
+ *
+ * Represents a tenant's active Stripe subscription with config-based price IDs
+ * instead of raw Stripe IDs. Includes legacy price detection for historical
+ * billing configurations.
+ *
+ * @example
+ * ```typescript
+ * const subscription: TenantSubscription = {
+ *   subscription_id: 'sub_1234567890',
+ *   config_price_id: 'price_pro_monthly',
+ *   status: 'active',
+ *   is_legacy_price: false,
+ *   current_period_end: 1735416000
+ * };
+ * ```
+ *
+ * @since 0.6.0
+ * @public
+ * @group Tenant Subscriptions
+ */
+type TenantSubscription = {
+    /** Stripe subscription ID */
+    subscription_id: string;
+    /** Config-based price ID from your billing configuration */
+    config_price_id: string;
+    /** Subscription status (active, trialing, past_due) */
+    status: string;
+    /** Whether this price is from a legacy billing configuration */
+    is_legacy_price: boolean;
+    /** Unix timestamp when the current billing period ends */
+    current_period_end: number;
+};
+/**
+ * Response structure for getting active subscriptions
+ *
+ * @since 0.6.0
+ * @public
+ * @group Tenant Subscriptions
+ */
+type GetActiveSubscriptionsResponse = ApiResponse<TenantSubscription[]>;
+/**
+ * Billing status information for a tenant
+ *
+ * Indicates whether the tenant has valid billing information configured
+ * in their Stripe customer account.
+ *
+ * @example
+ * ```typescript
+ * const status: BillingStatus = {
+ *   has_billing_info: true,
+ *   is_active: true
+ * };
+ * ```
+ *
+ * @since 0.6.0
+ * @public
+ * @group Tenant Subscriptions
+ */
+type BillingStatus = {
+    /** Whether the tenant has payment method(s) configured */
+    has_billing_info: boolean;
+    /** Whether the billing information is active and valid */
+    is_active: boolean;
+};
+/**
+ * Response structure for billing status check
+ *
+ * @since 0.6.0
+ * @public
+ * @group Tenant Subscriptions
+ */
+type GetBillingStatusResponse = ApiResponse<BillingStatus>;
+/**
+ * Tenant subscription and billing management
+ *
+ * Provides access to the active tenant's Stripe subscriptions and billing
+ * status. All operations are automatically scoped to the user's currently
+ * active tenant via session authentication.
+ *
+ * Key features:
+ * - View all active subscriptions with config-based price IDs
+ * - Legacy price detection for historical billing configurations
+ * - Billing status verification (payment method availability)
+ * - Automatic tenant scoping via session context
+ *
+ * @example
+ * ```typescript
+ * const subscriptionManager = new TenantSubscriptionManager(omnibaseClient);
+ *
+ * // Get all active subscriptions for the current tenant
+ * const subscriptions = await subscriptionManager.getActive();
+ * console.log(`Active subscriptions: ${subscriptions.data.length}`);
+ *
+ * // Check if tenant has billing configured
+ * const status = await subscriptionManager.getBillingStatus();
+ * if (!status.data.has_billing_info) {
+ *   console.log('Please add a payment method');
+ * }
+ * ```
+ *
+ * @since 0.6.0
+ * @public
+ * @group Tenant Subscriptions
+ */
+declare class TenantSubscriptionManager {
+    private omnibaseClient;
+    /**
+     * Creates a new TenantSubscriptionManager instance
+     *
+     * @param omnibaseClient - Configured Omnibase client instance
+     *
+     * @group Tenant Subscriptions
+     */
+    constructor(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
+     */
+    getActive(): Promise<GetActiveSubscriptionsResponse>;
+    /**
+     * 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
+     */
+    getBillingStatus(): Promise<GetBillingStatusResponse>;
+}
+
 /**
  * Response structure for a tenant user
  *
@@ -2844,6 +3124,30 @@ declare class TenantHandler {
      * ```
      */
     readonly invites: TenantInviteManager;
+    /**
+     * 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
+     */
+    readonly subscriptions: TenantSubscriptionManager;
 }
 
 type OmnibaseClientConfig = {
@@ -2980,4 +3284,4 @@ declare class OmnibaseClient {
     fetch(endpoint: string, options?: RequestInit): Promise<Response>;
 }
 
-export { type AssignRoleRequest as A, type CreateRoleRequest as C, CheckoutManager, type CheckoutOptions, ConfigManager, type CreateCheckoutResponse, type CreateCustomerPortalResponse, type DownloadResult as D, type NamespaceDefinition as N, type OmnibaseClientConfig as O, PermissionsClient as P, PaymentHandler, PortalManager, type PortalOptions, type Price, type PriceDisplay, type PriceLimit, type PriceUI, type Product, type ProductUI, type ProductWithPricingUI, RolesHandler as R, StorageClient as S, type StripeConfigResponse, type StripeConfiguration, TenantHandler as T, type Tier, type UpdateRoleRequest as U, UsageManager, type UsageOptions, type Role as a, type UploadOptions as b, type UploadResult as c, type AcceptTenantInviteRequest as d, type AcceptTenantInviteResponse as e, type CreateTenantUserInviteResponse as f, type TenantInvite as g, type CreateTenantUserInviteRequest as h, TenantInviteManager as i, type SwitchActiveTenantResponse as j, type DeleteTenantResponse as k, type CreateTenantResponse as l, type Tenant as m, type CreateTenantRequest as n, TenantManger as o, OmnibaseClient as p, type ApiResponse as q };
+export { type AssignRoleRequest as A, type BillingStatus as B, type CreateRoleRequest as C, CheckoutManager, type CheckoutOptions, ConfigManager, type CreateCheckoutResponse, type CreateCustomerPortalResponse, type DownloadResult as D, type GetActiveSubscriptionsResponse as G, type NamespaceDefinition as N, type OmnibaseClientConfig as O, PermissionsClient as P, PaymentHandler, PortalManager, type PortalOptions, type Price, type PriceDisplay, type PriceLimit, type PriceUI, type Product, type ProductUI, type ProductWithPricingUI, RolesHandler as R, StorageClient as S, type StripeConfigResponse, type StripeConfiguration, TenantHandler as T, type Tier, type UpdateRoleRequest as U, UsageManager, type UsageOptions, type Role as a, type UploadOptions as b, type UploadResult as c, type AcceptTenantInviteRequest as d, type AcceptTenantInviteResponse as e, type CreateTenantUserInviteResponse as f, type TenantInvite as g, type CreateTenantUserInviteRequest as h, TenantInviteManager as i, type SwitchActiveTenantResponse as j, type DeleteTenantResponse as k, type CreateTenantResponse as l, type Tenant as m, type CreateTenantRequest as n, TenantManger as o, type TenantSubscription as p, type GetBillingStatusResponse as q, TenantSubscriptionManager as r, OmnibaseClient as s, type ApiResponse as t };