@omnibase/core-js 0.7.0 → 0.7.2

package/dist/payments/index.d.cts

@@ -1,5 +1,4 @@
-import { PermissionsClient } from '../permissions/index.cjs';
-import '@ory/client';
+import { RelationshipApi, PermissionApi } from '@ory/client';
 
 /**
  * Base API Response structure for all operations
@@ -1016,6 +1015,607 @@ declare class PaymentHandler {
     readonly usage: UsageManager;
 }
 
+/**
+ * Types for the Permissions and Roles API
+ *
+ * This module defines TypeScript types for interacting with the Omnibase
+ * permissions system, including both Ory Keto relationships and the
+ * role-based access control (RBAC) system.
+ *
+ * @module Permissions Types
+ * @since 0.7.0
+ */
+/**
+ * Namespace definition from the database
+ *
+ * Represents a permission namespace (e.g., Tenant, Project) and its
+ * available relations/permissions. Used for building role configuration UIs.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'uuid-123',
+ *   namespace: 'Tenant',
+ *   relations: ['invite_user', 'delete_tenant', 'manage_billing'],
+ *   created_at: '2024-01-01T00:00:00Z',
+ *   updated_at: '2024-01-01T00:00:00Z'
+ * }
+ * ```
+ *
+ * @since 0.7.0
+ * @public
+ */
+interface NamespaceDefinition {
+    /**
+     * Unique identifier for the namespace definition
+     */
+    id: string;
+    /**
+     * Name of the namespace (e.g., 'Tenant', 'Project')
+     */
+    namespace: string;
+    /**
+     * Available relations/permissions for this namespace
+     * @example ['invite_user', 'delete_tenant', 'manage_billing']
+     */
+    relations: string[];
+    /**
+     * Timestamp when the namespace definition was created
+     */
+    created_at: string;
+    /**
+     * Timestamp when the namespace definition was last updated
+     */
+    updated_at: string;
+}
+/**
+ * Role model representing a collection of permissions
+ *
+ * Roles can be system-wide (tenant_id = null) or tenant-specific.
+ * System roles are defined in roles.config.json and apply to all tenants.
+ * Custom roles are created via the API and are specific to a tenant.
+ *
+ * @example
+ * System role:
+ * ```typescript
+ * {
+ *   id: 'role_123',
+ *   tenant_id: null,
+ *   role_name: 'admin',
+ *   permissions: ['tenant#delete_all_projects', 'tenant#manage_billing'],
+ *   user_ids: ['user_456', 'user_789'],
+ *   created_at: '2024-01-01T00:00:00Z',
+ *   updated_at: '2024-01-01T00:00:00Z'
+ * }
+ * ```
+ *
+ * @example
+ * Custom tenant role:
+ * ```typescript
+ * {
+ *   id: 'role_456',
+ *   tenant_id: 'tenant_123',
+ *   role_name: 'billing_manager',
+ *   permissions: ['tenant#manage_billing', 'tenant#view_invoices'],
+ *   user_ids: ['user_999'],
+ *   created_at: '2024-01-01T00:00:00Z',
+ *   updated_at: '2024-01-01T00:00:00Z'
+ * }
+ * ```
+ *
+ * @since 0.7.0
+ * @public
+ */
+interface Role {
+    /**
+     * Unique identifier for the role
+     */
+    id: string;
+    /**
+     * Tenant ID this role belongs to, or null for system roles
+     *
+     * - `null`: System role (applies to all tenants)
+     * - `string`: Tenant-specific custom role
+     */
+    tenant_id: string | null;
+    /**
+     * Human-readable name for the role
+     * @example 'admin', 'billing_manager', 'developer'
+     */
+    role_name: string;
+    /**
+     * Array of permission strings in format: namespace#relation or namespace:id#relation
+     *
+     * @example
+     * Tenant-wide permissions:
+     * - 'tenant#invite_user'
+     * - 'tenant#delete_all_projects'
+     *
+     * Resource-specific permissions:
+     * - 'project:proj_abc123#deploy'
+     * - 'project:proj_abc123#view_logs'
+     */
+    permissions: string[];
+    /**
+     * Array of user IDs assigned to this role
+     *
+     * When a user is assigned to a role, their ID is added here and
+     * corresponding Keto relationship tuples are created for each permission.
+     */
+    user_ids: string[];
+    /**
+     * Timestamp when the role was created
+     */
+    created_at: string;
+    /**
+     * Timestamp when the role was last updated
+     */
+    updated_at: string;
+}
+/**
+ * Request body for creating a new role
+ *
+ * @example
+ * ```typescript
+ * {
+ *   role_name: 'billing_manager',
+ *   permissions: [
+ *     'tenant#manage_billing',
+ *     'tenant#view_invoices',
+ *     'tenant#update_payment_methods'
+ *   ]
+ * }
+ * ```
+ *
+ * @since 0.7.0
+ * @public
+ */
+interface CreateRoleRequest {
+    /**
+     * Name for the new role
+     * @example 'billing_manager', 'support_agent', 'developer'
+     */
+    role_name: string;
+    /**
+     * Array of permission strings to assign to the role
+     * @example ['tenant#manage_billing', 'tenant#view_invoices']
+     */
+    permissions: string[];
+}
+/**
+ * Request body for updating an existing role's permissions
+ *
+ * @example
+ * ```typescript
+ * {
+ *   permissions: [
+ *     'tenant#manage_billing',
+ *     'tenant#view_invoices',
+ *     'tenant#manage_users' // Added new permission
+ *   ]
+ * }
+ * ```
+ *
+ * @since 0.7.0
+ * @public
+ */
+interface UpdateRoleRequest {
+    /**
+     * New array of permissions for the role
+     *
+     * This replaces all existing permissions. Old permissions are removed
+     * from Keto and new ones are created for all assigned users.
+     */
+    permissions: string[];
+}
+/**
+ * Request body for assigning a role to a user
+ *
+ * @example
+ * ```typescript
+ * {
+ *   role_id: 'role_456'
+ * }
+ * ```
+ *
+ * @since 0.7.0
+ * @public
+ */
+interface AssignRoleRequest {
+    /**
+     * ID of the role to assign to the user
+     */
+    role_id: string;
+}
+
+/**
+ * Handler for managing roles and role-based permissions
+ *
+ * Provides methods for creating custom roles, assigning permissions,
+ * and managing role assignments. Works alongside the Keto-based
+ * permissions system to provide dynamic RBAC capabilities.
+ *
+ * @example
+ * ```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
+ * await omnibase.permissions.roles.assign('user_123', {
+ *   role_id: role.id
+ * });
+ * ```
+ *
+ * @since 0.7.0
+ * @public
+ */
+declare class RolesHandler {
+    private client;
+    constructor(client: OmnibaseClient);
+    /**
+     * Get available namespace definitions for UI
+     *
+     * Returns all namespaces and their available relations/permissions.
+     * Useful for building role configuration UIs.
+     *
+     * @returns List of namespace definitions
+     *
+     * @example
+     * ```typescript
+     * const definitions = await omnibase.permissions.roles.getDefinitions();
+     *
+     * // Output: [{ namespace: 'Tenant', relations: ['invite_user', 'delete_tenant', ...] }]
+     * definitions.forEach(def => {
+     *   console.log(`${def.namespace} supports: ${def.relations.join(', ')}`);
+     * });
+     * ```
+     */
+    getDefinitions(): Promise<NamespaceDefinition[]>;
+    /**
+     * List all roles for the current tenant
+     *
+     * Returns both system roles (defined in roles.config.json) and
+     * custom roles created via the API. System roles have `tenant_id = null`.
+     *
+     * @returns List of roles
+     *
+     * @example
+     * ```typescript
+     * const roles = await omnibase.permissions.roles.list();
+     *
+     * const systemRoles = roles.filter(r => r.tenant_id === null);
+     * const customRoles = roles.filter(r => r.tenant_id !== null);
+     *
+     * console.log(`System roles: ${systemRoles.map(r => r.role_name).join(', ')}`);
+     * console.log(`Custom roles: ${customRoles.map(r => r.role_name).join(', ')}`);
+     * ```
+     */
+    list(): Promise<Role[]>;
+    /**
+     * Create a new custom role
+     *
+     * Creates a tenant-specific role with the specified permissions.
+     * Permissions use the format `namespace#relation` or `namespace:id#relation`.
+     *
+     * @param request - Role creation request
+     * @returns Created role
+     *
+     * @example
+     * ```typescript
+     * const role = await omnibase.permissions.roles.create({
+     *   role_name: 'billing_manager',
+     *   permissions: [
+     *     'tenant#manage_billing',
+     *     'tenant#view_invoices',
+     *     'tenant#update_payment_methods'
+     *   ]
+     * });
+     *
+     * console.log(`Created role: ${role.id}`);
+     * ```
+     *
+     * @example
+     * Resource-specific permissions:
+     * ```typescript
+     * const devRole = await omnibase.permissions.roles.create({
+     *   role_name: 'project_developer',
+     *   permissions: [
+     *     'project:proj_abc123#deploy',
+     *     'project:proj_abc123#view_logs',
+     *     'tenant#invite_user'
+     *   ]
+     * });
+     * ```
+     */
+    create(request: CreateRoleRequest): Promise<Role>;
+    /**
+     * Update an existing role's permissions
+     *
+     * Updates the permissions for a role and automatically updates all
+     * Keto relationships for users assigned to this role. Old permissions
+     * are removed and new ones are created.
+     *
+     * @param roleId - ID of role to update
+     * @param request - Update request with new permissions
+     * @returns Updated role
+     *
+     * @example
+     * ```typescript
+     * const updatedRole = await omnibase.permissions.roles.update('role_123', {
+     *   permissions: [
+     *     'tenant#manage_billing',
+     *     'tenant#view_invoices',
+     *     'tenant#manage_users' // Added new permission
+     *   ]
+     * });
+     *
+     * console.log(`Updated role with ${updatedRole.permissions.length} permissions`);
+     * ```
+     */
+    update(roleId: string, request: UpdateRoleRequest): Promise<Role>;
+    /**
+     * Delete a role
+     *
+     * Deletes the role and automatically removes all Keto relationships
+     * for users assigned to this role. Cannot delete system roles.
+     *
+     * @param roleId - ID of role to delete
+     *
+     * @example
+     * ```typescript
+     * await omnibase.permissions.roles.delete('role_123');
+     * console.log('Role deleted successfully');
+     * ```
+     */
+    delete(roleId: string): Promise<void>;
+    /**
+     * Assign a role to a user
+     *
+     * Assigns a role to a user and automatically creates all necessary
+     * Keto relationship tuples based on the role's permissions. The user
+     * immediately gains all permissions defined in the role.
+     *
+     * @param userId - ID of user to assign role to
+     * @param request - Assignment request with role ID
+     *
+     * @example
+     * ```typescript
+     * // Assign billing manager role to user
+     * await omnibase.permissions.roles.assign('user_123', {
+     *   role_id: 'role_456'
+     * });
+     *
+     * // User now has all permissions from the role
+     * const canManageBilling = await omnibase.permissions.permissions.checkPermission(
+     *   undefined,
+     *   {
+     *     namespace: 'Tenant',
+     *     object: 'tenant_789',
+     *     relation: 'manage_billing',
+     *     subjectId: 'user_123'
+     *   }
+     * );
+     * // canManageBilling.data.allowed === true
+     * ```
+     */
+    assign(userId: string, request: AssignRoleRequest): Promise<void>;
+}
+
+/**
+ * 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).
+ *
+ * The client automatically configures separate endpoints for read and write operations
+ * to optimize performance and security by following Ory Keto's recommended architecture.
+ *
+ * @example
+ * Basic permission checking:
+ * ```typescript
+ * import { PermissionsClient } from '@omnibase/core-js/permissions';
+ *
+ * const permissionsClient = new PermissionsClient('https://api.example.com');
+ *
+ * // 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'
+ *   }
+ * );
+ *
+ * if (canView.data.allowed) {
+ *   console.log('User can view the tenant');
+ * }
+ * ```
+ *
+ * @example
+ * Creating tenant 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');
+ * ```
+ *
+ * @example
+ * Complex tenant permission management:
+ * ```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
+ *   }
+ * );
+ *
+ * if (canManageMembers.data.allowed) {
+ *   // User can invite/remove members
+ *   console.log('User can manage tenant members');
+ * }
+ *
+ * // Later, remove admin permissions
+ * await permissionsClient.relationships.deleteRelationships(
+ *   undefined,
+ *   {
+ *     namespace: 'Tenant',
+ *     object: tenantId,
+ *     relation: 'admins',
+ *     subjectId: userId
+ *   }
+ * );
+ * ```
+ *
+ * @since 1.0.0
+ * @public
+ * @group Client
+ */
+declare class PermissionsClient {
+    /**
+     * 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: RelationshipApi;
+    /**
+     * 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: PermissionApi;
+    /**
+     * Handler for managing roles and role-based permissions
+     *
+     * Provides methods for creating custom roles, assigning permissions,
+     * and managing role assignments. Works alongside the Keto-based
+     * permissions system to provide dynamic RBAC capabilities.
+     *
+     * @example
+     * ```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
+     * await omnibase.permissions.roles.assign('user_123', {
+     *   role_id: role.id
+     * });
+     * ```
+     *
+     * @since 0.7.0
+     * @group Roles
+     */
+    roles: RolesHandler;
+    /**
+     * 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
+     * @param client - The main OmnibaseClient instance (for roles handler)
+     *
+     * @throws {Error} When the base URL is invalid or cannot be reached
+     *
+     * @example
+     * ```typescript
+     * const client = new PermissionsClient('https://api.example.com', omnibaseClient);
+     * ```
+     *
+     * @since 1.0.0
+     * @group Client
+     */
+    constructor(apiBaseUrl: string, client: OmnibaseClient);
+}
+
 interface UploadOptions {
     /**
      * Custom metadata to attach to the file
@@ -2255,4 +2855,4 @@ declare class OmnibaseClient {
     fetch(endpoint: string, options?: RequestInit): Promise<Response>;
 }
 
-export { type AcceptTenantInviteRequest as A, type CreateTenantUserInviteResponse as C, CheckoutManager, type CheckoutOptions, ConfigManager, type CreateCheckoutResponse, type CreateCustomerPortalResponse, type DownloadResult as D, type OmnibaseClientConfig as O, PaymentHandler, PortalManager, type PortalOptions, type Price, type PriceDisplay, type PriceLimit, type PriceUI, type Product, type ProductUI, type ProductWithPricingUI, StorageClient as S, type StripeConfigResponse, type StripeConfiguration, TenantHandler as T, type Tier, type UploadOptions as U, UsageManager, type UsageOptions, type UploadResult as a, type AcceptTenantInviteResponse as b, type TenantInvite as c, type CreateTenantUserInviteRequest as d, TenantInviteManager as e, type SwitchActiveTenantResponse as f, type DeleteTenantResponse as g, type CreateTenantResponse as h, type Tenant as i, type CreateTenantRequest as j, TenantManger as k, OmnibaseClient as l, type ApiResponse as m };
+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 };