brix-runtime-sdk-api-web 1.0.0

package/dist/types/types/auth.d.ts

@@ -0,0 +1,405 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file Authentication Capability Type Definitions
+ * @description Defines core types for the authentication system, including user info, auth info, permission verification, etc.
+ * @module @brix/runtime-sdk-api-web/types/auth
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file.
+ *
+ * [v3.2.0 Phase 1 Contract Layer Fix]
+ * Added types required by AuthCapabilityImpl:
+ * - User: Complete user info (including permissions and roles)
+ * - Tenant: Tenant info
+ * - AuthChangeEvent: Authentication state change event
+ * - DataScope: Data scope
+ * - LoginCredentials: Login credentials
+ * - LoginResult: Login result
+ * - AuthState: Authentication state
+ */
+import type { Unsubscribe } from './event';
+/**
+ * Authentication Capability Type Identifier
+ */
+export declare const AuthCapabilityType: unique symbol;
+/**
+ * Basic User Information
+ */
+export interface BaseUser {
+    /** User ID */
+    readonly id: string;
+    /** Username */
+    readonly username: string;
+    /** Email */
+    readonly email?: string;
+    /** Display Name */
+    readonly displayName?: string;
+    /** Avatar URL */
+    readonly avatar?: string;
+    /** Created At */
+    readonly createdAt: string;
+    /** Updated At */
+    readonly updatedAt?: string;
+}
+/**
+ * Authenticated User Information
+ *
+ * <p>User object containing roles and permissions.</p>
+ */
+export interface AuthUser {
+    /** User ID */
+    id: string;
+    /** Username */
+    username: string;
+    /** Email */
+    email?: string;
+    /** Display Name */
+    displayName?: string;
+    /** Role List */
+    roles: string[];
+    /** Permission List */
+    permissions: string[];
+}
+/**
+ * Complete User Information
+ *
+ * <p>User object containing roles, permissions, and extended attributes.
+ * This is the type returned by AuthCapability.getCurrentUser().</p>
+ *
+ * @since 3.2.0
+ */
+export interface User {
+    /** User ID */
+    readonly id: string;
+    /** Username */
+    readonly username: string;
+    /** Email */
+    readonly email?: string;
+    /** Display Name */
+    readonly displayName?: string;
+    /** Avatar URL */
+    readonly avatar?: string;
+    /** Role List */
+    readonly roles: string[];
+    /** Permission List */
+    readonly permissions: string[];
+    /** Created At */
+    readonly createdAt?: string;
+    /** Updated At */
+    readonly updatedAt?: string;
+    /** Extended Attributes */
+    readonly [key: string]: unknown;
+}
+/**
+ * Tenant Information
+ *
+ * <p>Tenant object in a multi-tenant system.</p>
+ *
+ * @since 3.2.0
+ */
+export interface Tenant {
+    /** Tenant ID */
+    readonly id: string;
+    /** Tenant Name */
+    readonly name: string;
+    /** Tenant Code (Unique Identifier) */
+    readonly code?: string;
+    /** Tenant Type */
+    readonly type?: string;
+    /** Tenant Status */
+    readonly status?: 'active' | 'inactive' | 'suspended';
+    /** Tenant Configuration */
+    readonly config?: Record<string, unknown>;
+}
+/**
+ * Data Scope
+ *
+ * <p>Describes the scope of user's data access permissions.</p>
+ *
+ * @since 3.2.0
+ */
+export interface DataScope {
+    /** Data Scope ID */
+    readonly id: string;
+    /** Scope Type (e.g., 'org', 'dept', 'self', etc.) */
+    readonly type: string;
+    /** Scope Value (e.g., organization ID list) */
+    readonly value: string | string[];
+    /** Resource Type (optional, restricts applicable resources) */
+    readonly resource?: string;
+}
+/**
+ * Login Credentials
+ *
+ * <p>Credential information submitted during user login.</p>
+ *
+ * @since 3.2.0
+ */
+export interface LoginCredentials {
+    /** Username or Email */
+    readonly username?: string;
+    /** Password */
+    readonly password?: string;
+    /** Captcha */
+    readonly captcha?: string;
+    /** Remember Login State */
+    readonly rememberMe?: boolean;
+    /** Third-party Login Provider */
+    readonly provider?: string;
+    /** Third-party Login Authorization Code */
+    readonly authorizationCode?: string;
+    /** Extended Fields */
+    readonly [key: string]: unknown;
+}
+/**
+ * Login Result
+ *
+ * <p>Result returned from a login request.</p>
+ *
+ * @since 3.2.0
+ */
+export interface LoginResult {
+    /** Whether Login Succeeded */
+    readonly success: boolean;
+    /** User Info (on success) */
+    readonly user?: User;
+    /** Access Token (on success) */
+    readonly token?: string;
+    /** Refresh Token (on success) */
+    readonly refreshToken?: string;
+    /** Token Expiration Time (seconds) */
+    readonly expiresIn?: number;
+    /** Error Code (on failure) */
+    readonly errorCode?: string;
+    /** Error Message (on failure) */
+    readonly errorMessage?: string;
+    /** Whether MFA is Required */
+    readonly requireMfa?: boolean;
+    /** MFA Session Identifier */
+    readonly mfaSession?: string;
+}
+/**
+ * Authentication State
+ *
+ * <p>Describes the complete state of the current authentication context.</p>
+ *
+ * @since 3.2.0
+ */
+export interface AuthState {
+    /** Whether Authenticated */
+    readonly isAuthenticated: boolean;
+    /** Current User */
+    readonly user: User | null;
+    /** Current Tenant */
+    readonly tenant: Tenant | null;
+    /** Whether Loading */
+    readonly loading: boolean;
+    /** Data Scope List */
+    readonly dataScopes: DataScope[];
+}
+/**
+ * Authentication State Change Event
+ *
+ * <p>Event triggered when authentication state changes.</p>
+ *
+ * @since 3.2.0
+ */
+export interface AuthChangeEvent {
+    /** Event Type */
+    readonly type: 'login' | 'logout' | 'token_refresh' | 'user_update' | 'tenant_switch';
+    /** Current User (quick access) */
+    readonly user?: User | null;
+    /** New Authentication State */
+    readonly state: AuthState;
+    /** Previous Authentication State */
+    readonly previousState?: AuthState;
+    /** Event Timestamp */
+    readonly timestamp: number;
+}
+/**
+ * Authentication Information
+ *
+ * <p>Contains access token and refresh token.</p>
+ */
+export interface AuthInfo {
+    /** Access Token */
+    readonly accessToken: string;
+    /** Refresh Token */
+    readonly refreshToken?: string;
+    /** Token Expiration Time (seconds) */
+    readonly expiresIn: number;
+    /** Token Type */
+    readonly tokenType: string;
+}
+/**
+ * Authentication Capability Contract
+ *
+ * <p>Provides user identity verification and permission checking capabilities for plugins.</p>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const auth = context.getCapability<AuthCapability>(AuthCapabilityType);
+ *
+ * if (auth.isAuthenticated()) {
+ *   const user = auth.getCurrentUser();
+ *   if (auth.hasPermission('booking:create')) {
+ *     // Create booking
+ *   }
+ * }
+ * ```
+ *
+ * @since 3.2.0 Extended methods: getCurrentTenant, getTenantId, getDataScopes, getState, onAuthChange
+ */
+export interface AuthCapability {
+    /**
+     * Get current logged-in user
+     *
+     * @returns Current user, returns null if not logged in
+     */
+    getCurrentUser(): User | null;
+    /**
+     * Check if authenticated
+     *
+     * @returns Whether logged in
+     */
+    isAuthenticated(): boolean;
+    /**
+     * User login
+     *
+     * @param credentials Login credentials
+     * @returns Login result
+     */
+    login(credentials: LoginCredentials): Promise<LoginResult>;
+    /**
+     * User logout
+     *
+     * @returns Promise, resolved when logout succeeds
+     */
+    logout(): Promise<void>;
+    /**
+     * Check if has specified permission
+     *
+     * @param permission Permission identifier
+     * @returns Whether has permission
+     */
+    hasPermission(permission: string): boolean;
+    /**
+     * Check if has any of the specified permissions
+     *
+     * @param permissions Permission identifier array
+     * @returns Whether has any permission
+     * @since 3.2.0
+     */
+    hasAnyPermission?(permissions: string[]): boolean;
+    /**
+     * Check if has all specified permissions
+     *
+     * @param permissions Permission identifier array
+     * @returns Whether has all permissions
+     * @since 3.2.0
+     */
+    hasAllPermissions?(permissions: string[]): boolean;
+    /**
+     * Check if has specified role
+     *
+     * @param role Role identifier
+     * @returns Whether has role
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Check if has any of the specified roles
+     *
+     * @param roles Role identifier array
+     * @returns Whether has any role
+     * @since 3.2.0
+     */
+    hasAnyRole?(roles: string[]): boolean;
+    /**
+     * Check if has all specified roles
+     *
+     * @param roles Role identifier array
+     * @returns Whether has all roles
+     * @since 3.2.0
+     */
+    hasAllRoles?(roles: string[]): boolean;
+    /**
+     * Get current access token
+     *
+     * @returns Access token, returns null if not logged in
+     */
+    getToken(): string | null;
+    /**
+     * Get current tenant
+     *
+     * @returns Current tenant, returns null if not set
+     * @since 3.2.0
+     */
+    getCurrentTenant?(): Tenant | null;
+    /**
+     * Get tenant ID
+     *
+     * @returns Tenant ID, returns empty string if no tenant
+     * @since 3.2.0
+     */
+    getTenantId?(): string;
+    /**
+     * Get data scopes
+     *
+     * @param resource Resource type (optional)
+     * @returns Data scope list
+     * @since 3.2.0
+     */
+    getDataScopes?(resource?: string): DataScope[];
+    /**
+     * Get authentication state
+     *
+     * @returns Current authentication state
+     * @since 3.2.0
+     */
+    getState?(): AuthState;
+    /**
+     * Subscribe to authentication state changes
+     *
+     * @param listener Change listener
+     * @returns Unsubscribe function
+     * @since 3.2.0
+     */
+    onAuthChange?(listener: (event: AuthChangeEvent) => void): Unsubscribe;
+    /**
+     * Check if Feature Flag is enabled
+     *
+     * @param featureKey Feature Flag key name
+     * @returns Whether enabled
+     * @since 3.2.0
+     */
+    isFeatureEnabled?(featureKey: string): boolean;
+    /**
+     * Refresh access token
+     *
+     * @returns New access token
+     * @since 3.2.0
+     */
+    refreshToken?(): Promise<string>;
+    /**
+     * Destroy capability instance
+     *
+     * @since 3.2.0
+     */
+    destroy?(): void;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/types/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/types/auth.ts"],"names":[],"mappings":"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"}

package/dist/types/types/capability.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file Capability Related Type Definitions
+ * @description Defines core types for the capability system, including capability metadata, status, registry, etc.
+ * @module @brix/runtime-sdk-api-web/types/capability
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file to keep the contract layer clean.
+ *
+ * [Design Principles]
+ * - All type definitions use readonly properties
+ * - Use Symbol as capability unique identifier (type-safe)
+ * - Support lazy initialization and scope control for capabilities
+ */
+/**
+ * Capability Priority Enum
+ *
+ * <p>Used to determine which implementation to use when multiple capability providers conflict.</p>
+ */
+export declare enum CapabilityPriority {
+    /** Low Priority (fallback implementation) */
+    LOW = 0,
+    /** Normal Priority (default) */
+    NORMAL = 50,
+    /** High Priority (overrides default implementation) */
+    HIGH = 100
+}
+/**
+ * Capability Metadata (Simplified)
+ */
+export interface CapabilityMetadata {
+    /** Capability Name */
+    readonly name: string;
+    /** Capability Version */
+    readonly version: string;
+    /** Priority */
+    readonly priority: CapabilityPriority;
+    /** Whether Required */
+    readonly required: boolean;
+}
+/**
+ * Capability ID Type
+ *
+ * <p>Supports string or Symbol, recommend using Symbol.for() to ensure uniqueness.</p>
+ */
+export type CapabilityId = string | symbol;
+/**
+ * Capability Meta Information (Full Version)
+ *
+ * <p>Contains complete metadata for capability registration and discovery.</p>
+ */
+export interface CapabilityMeta {
+    /** Capability Unique Identifier */
+    readonly id: CapabilityId;
+    /** Capability Name (Human-readable) */
+    readonly name: string;
+    /** Capability Description */
+    readonly description?: string;
+    /** Capability Version */
+    readonly version?: string;
+    /** Dependent Capability ID List */
+    readonly dependencies?: CapabilityId[];
+    /** Tags (for filtering and categorization) */
+    readonly tags?: string[];
+}
+/**
+ * Capability Status
+ *
+ * <p>Describes the current status of a capability in its lifecycle.</p>
+ */
+export type CapabilityStatus = 'registered' | 'initializing' | 'ready' | 'error' | 'disposed';
+/**
+ * Capability Type Identifier (Generic Interface)
+ *
+ * <p>Used to identify and create capability instances, containing capability metadata.
+ * Uses phantom property `_phantom` for type inference.</p>
+ *
+ * @example
+ * ```typescript
+ * interface MyCapability {
+ *   doSomething(): void;
+ * }
+ *
+ * const MyCapabilityType = createCapabilityType<MyCapability>({
+ *   id: 'my-capability',
+ *   name: 'My Capability',
+ * });
+ * ```
+ */
+export interface CapabilityType<T = unknown> extends CapabilityMeta {
+    /**
+     * Phantom property for type inference
+     * Does not exist at runtime, only for TypeScript type system
+     */
+    readonly _phantom?: T;
+}
+/**
+ * Create Capability Type Identifier
+ *
+ * @param meta - Capability meta information
+ * @returns Capability type identifier object
+ */
+export declare function createCapabilityType<T>(meta: Omit<CapabilityMeta, 'id'> & {
+    id: string;
+}): CapabilityType<T>;
+/**
+ * Capability Provider Interface
+ *
+ * <p>Encapsulates the creation and disposal logic of capability instances.</p>
+ */
+export interface CapabilityProvider<T = unknown> {
+    /** Get capability instance */
+    provide(): T;
+    /** Dispose capability instance (optional) */
+    dispose?(): void;
+}
+/**
+ * Simple Capability Provider
+ *
+ * <p>Can be the capability instance itself, or a factory function that returns the capability instance.</p>
+ */
+export type SimpleCapabilityProvider<T> = T | (() => T);
+/**
+ * Capability Registration Options
+ */
+export interface CapabilityRegisterOptions {
+    /**
+     * Whether to override existing capability
+     */
+    override?: boolean;
+    /**
+     * Capability priority
+     */
+    priority?: CapabilityPriority;
+    /**
+     * Capability scope
+     * - 'global': Global scope, shared by all modules
+     * - 'module': Module scope, only available in current module
+     * @default 'global'
+     */
+    scope?: 'global' | 'module';
+    /**
+     * Lazy initialization
+     * When true, capability is instantiated on first use
+     * @default false
+     */
+    lazy?: boolean;
+}
+/**
+ * Capability Runtime Information
+ *
+ * <p>Describes the detailed status of a capability at runtime.</p>
+ */
+export interface CapabilityRuntimeInfo {
+    /** Capability Metadata */
+    readonly meta: CapabilityMeta;
+    /** Current Status */
+    readonly status: CapabilityStatus;
+    /** Registration Timestamp */
+    readonly registeredAt: number;
+    /** Initialization Timestamp */
+    readonly initializedAt?: number;
+    /** Error Information (when status is error) */
+    readonly error?: Error;
+    /** Invocation Count Statistics */
+    readonly invocationCount: number;
+}
+/**
+ * Capability Registry Interface
+ *
+ * <p>Manages registration, retrieval, initialization, and disposal of capabilities.</p>
+ */
+export interface CapabilityRegistry {
+    /** Get capability instance */
+    get<T>(capabilityType: CapabilityType<T>): T | undefined;
+    /** Get required capability (throws exception if not found) */
+    getRequired<T>(capabilityType: CapabilityType<T>): T;
+    /** Register capability */
+    register<T>(capabilityType: CapabilityType<T>, provider: CapabilityProvider<T>, options?: CapabilityRegisterOptions): void;
+    /** Unregister capability */
+    unregister<T>(capabilityType: CapabilityType<T>): boolean;
+    /** Check if capability is registered */
+    has<T>(capabilityType: CapabilityType<T>): boolean;
+    /** Check if capability is ready */
+    isReady<T>(capabilityType: CapabilityType<T>): boolean;
+    /** Get capability runtime information */
+    getInfo<T>(capabilityType: CapabilityType<T>): CapabilityRuntimeInfo | undefined;
+    /** Get all registered capability IDs */
+    getRegisteredIds(): CapabilityId[];
+    /** Get runtime information for all capabilities */
+    getAllInfo(): Map<CapabilityId, CapabilityRuntimeInfo>;
+    /** Filter capabilities by status */
+    getByStatus(status: CapabilityStatus): CapabilityId[];
+    /** Filter capabilities by tag */
+    getByTag(tag: string): CapabilityId[];
+    /** Initialize all registered capabilities */
+    initializeAll(): Promise<boolean>;
+    /** Dispose all capabilities */
+    disposeAll(): Promise<void>;
+    /** Reset registry */
+    reset(): void;
+}
+//# sourceMappingURL=capability.d.ts.map

package/dist/types/types/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../../src/types/capability.ts"],"names":[],"mappings":"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"}