@omnibase/core-js 0.7.6 → 0.8.0

package/dist/payments/index.d.cts

@@ -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:
+ * - Read operations (permission checks): `/api/v1/permissions/read`
+ * - Write operations (relationship management): `/api/v1/permissions/write`
  *
- * The client automatically configures separate endpoints for read and write operations
- * to optimize performance and security by following Ory Keto's recommended architecture.
+ * 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 permissionsClient = new PermissionsClient('https://api.example.com');
+ * const omnibase = new OmnibaseClient({
+ *   apiUrl: '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`
      *
-     * @param apiBaseUrl - The base URL for your Omnibase API instance
-     * @param client - The main OmnibaseClient instance (for roles handler)
+     * This separation follows Ory Keto's recommended architecture for optimal
+     * performance and security.
+     *
+     * @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
      */

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:
+ * - Read operations (permission checks): `/api/v1/permissions/read`
+ * - Write operations (relationship management): `/api/v1/permissions/write`
  *
- * The client automatically configures separate endpoints for read and write operations
- * to optimize performance and security by following Ory Keto's recommended architecture.
+ * 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 permissionsClient = new PermissionsClient('https://api.example.com');
+ * const omnibase = new OmnibaseClient({
+ *   apiUrl: '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`
      *
-     * @param apiBaseUrl - The base URL for your Omnibase API instance
-     * @param client - The main OmnibaseClient instance (for roles handler)
+     * This separation follows Ory Keto's recommended architecture for optimal
+     * performance and security.
+     *
+     * @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
      */