brix-runtime-sdk-api-web 1.0.0

package/src/types/common.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 Common Type Definitions
+ * @description Defines utility types and API response types
+ * @module @brix/runtime-sdk-api-web/types/common
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file.
+ */
+
+// =========================================
+// Utility Types
+// =========================================
+
+/**
+ * Optional Fields
+ *
+ * <p>Makes specified fields optional.</p>
+ */
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * Required Fields
+ *
+ * <p>Makes specified fields required. Named to avoid conflict with built-in Required.</p>
+ */
+export type RequiredFields<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+
+/**
+ * Deep Readonly
+ *
+ * <p>Recursively makes all properties readonly.</p>
+ */
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+
+// =========================================
+// API Response Types
+// =========================================
+
+/**
+ * Standard API Response
+ */
+export interface ApiResponse<T = unknown> {
+  /** Whether Successful */
+  readonly success: boolean;
+  /** Response Data */
+  readonly data?: T;
+  /** Error Information */
+  readonly error?: ApiError;
+  /** Timestamp */
+  readonly timestamp: number;
+}
+
+/**
+ * API Error
+ */
+export interface ApiError {
+  /** Error Code */
+  readonly code: string;
+  /** Error Message */
+  readonly message: string;
+  /** Details */
+  readonly details?: Record<string, unknown>;
+}
+
+// =========================================
+// Pagination Types
+// =========================================
+
+/**
+ * Paged Response
+ */
+export interface PagedResponse<T> {
+  /** Data List */
+  readonly items: T[];
+  /** Total Count */
+  readonly total: number;
+  /** Current Page */
+  readonly page: number;
+  /** Page Size */
+  readonly pageSize: number;
+  /** Total Pages */
+  readonly totalPages: number;
+}
+
+/**
+ * Paged Request
+ */
+export interface PagedRequest {
+  /** Current Page */
+  readonly page: number;
+  /** Page Size */
+  readonly pageSize: number;
+  /** Sort Field */
+  readonly sort?: string;
+  /** Sort Direction */
+  readonly order?: 'asc' | 'desc';
+}

package/src/types/config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 Configuration Capability Type Definitions
+ * @description Defines core types for the configuration management system
+ * @module @brix/runtime-sdk-api-web/types/config
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file.
+ */
+/**
+ * Configuration Capability Type Identifier
+ */
+export declare const ConfigCapabilityType: unique symbol;
+/**
+ * Configuration Capability Contract
+ *
+ * <p>Provides runtime configuration reading capability for plugins.</p>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const config = context.getCapability<ConfigCapability>(ConfigCapabilityType);
+ * const apiBase = config.get<string>('api.baseUrl', '/api/v1');
+ * const timeout = config.get<number>('http.timeout', 30000);
+ * ```
+ *
+ * <h3>Configuration Sources</h3>
+ * <ul>
+ *   <li>Environment Variables</li>
+ *   <li>Configuration Center</li>
+ *   <li>Manifest Files</li>
+ * </ul>
+ */
+export interface ConfigCapability {
+    /**
+     * Get configuration item
+     *
+     * @param key Configuration key
+     * @param defaultValue Default value
+     * @returns Configuration value
+     */
+    get<T>(key: string, defaultValue?: T): T;
+    /**
+     * Get all configurations
+     *
+     * @returns Configuration object (supports sync/async)
+     */
+    getAll<T = Record<string, unknown>>(): T | Promise<T>;
+}
+//# sourceMappingURL=config.d.ts.map

package/src/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAMnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEzC;;;;OAIG;IACH,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvD"}

package/src/types/config.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 Configuration Capability Type Definitions
+ * @description Defines core types for the configuration management system
+ * @module @brix/runtime-sdk-api-web/types/config
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file.
+ *
+ * [v3.1 Changes]
+ * Added ConfigStoreCapability alias for Java/TS naming alignment.
+ * ConfigCapability is now deprecated, use ConfigStoreCapability instead.
+ */
+
+// =========================================
+// Configuration Capability Type Identifier
+// =========================================
+
+/**
+ * Configuration Capability Type Identifier
+ */
+export const ConfigCapabilityType = Symbol.for('ConfigCapability');
+
+/**
+ * Configuration Store Capability Type Identifier (Aligned with Java naming)
+ * @since 3.1.0
+ */
+export const ConfigStoreCapabilityType = Symbol.for('ConfigStoreCapability');
+
+// =========================================
+// Configuration Capability Contract
+// =========================================
+
+/**
+ * Configuration Store Capability Contract
+ *
+ * <p>Provides runtime configuration reading capability for plugins.</p>
+ *
+ * <p>This is the canonical name aligned with Java SDK (ConfigStoreCapability).</p>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const config = context.getCapability<ConfigStoreCapability>(ConfigStoreCapabilityType);
+ * const apiBase = config.get<string>('api.baseUrl', '/api/v1');
+ * const timeout = config.get<number>('http.timeout', 30000);
+ * ```
+ *
+ * <h3>Configuration Sources</h3>
+ * <ul>
+ *   <li>Environment Variables</li>
+ *   <li>Configuration Center</li>
+ *   <li>Manifest Files</li>
+ * </ul>
+ *
+ * @since 3.1.0
+ */
+export interface ConfigStoreCapability {
+  /**
+   * Get configuration item
+   *
+   * @param key Configuration key
+   * @param defaultValue Default value
+   * @returns Configuration value
+   */
+  get<T>(key: string, defaultValue?: T): T;
+
+  /**
+   * Get all configurations
+   *
+   * @returns Configuration object (supports sync/async)
+   */
+  getAll<T = Record<string, unknown>>(): T | Promise<T>;
+}
+
+/**
+ * Configuration Capability Contract
+ *
+ * @deprecated Use ConfigStoreCapability instead for Java/TS naming alignment.
+ * Will be removed in v4.0.0.
+ */
+export interface ConfigCapability extends ConfigStoreCapability {}

package/src/types/event.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 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 Event-Related Type Definitions
+ * @description Defines core types for the event system, including event messages, handlers, subscription options, etc.
+ * @module @brix/runtime-sdk-api-web/types/event
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file.
+ *
+ * [Design Principles]
+ * - Supports both simple Event Bus and Governed Event Bus modes
+ * - Governed Event Bus provides complete event metadata and audit information
+ */
+/**
+ * Event Message
+ *
+ * <p>Encapsulates complete event information including type, payload, timestamp, and source.</p>
+ */
+export interface EventMessage<T = unknown> {
+    /** Event Type */
+    readonly eventType: string;
+    /** Event Payload */
+    readonly payload: T;
+    /** Timestamp */
+    readonly timestamp: number;
+    /** Event Source (Plugin ID) */
+    readonly source?: string;
+}
+/**
+ * Event Subscription Options
+ */
+export interface SubscriptionOptions {
+    /** Whether to trigger only once */
+    readonly once?: boolean;
+    /** Filter function */
+    readonly filter?: (payload: unknown) => boolean;
+}
+/**
+ * Event Handler
+ *
+ * @typeParam T - Event payload type
+ */
+export type EventHandler<T = unknown> = (payload: T) => void;
+/**
+ * Unsubscribe Function
+ */
+export type Unsubscribe = () => void;
+/**
+ * Event Bus Capability Type Identifier
+ */
+export declare const EventBusCapabilityType: unique symbol;
+/**
+ * Event Bus Capability Contract
+ *
+ * <p>Provides cross-plugin communication capability for plugins.</p>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const eventBus = context.getCapability<EventBusCapability>(EventBusCapabilityType);
+ *
+ * // Emit event
+ * eventBus.emit('booking:selected', { bookingId: '123' });
+ *
+ * // Subscribe to event
+ * const unsubscribe = eventBus.on('booking:selected', (payload) => {
+ *   console.log('Booking selected:', payload);
+ * });
+ * ```
+ */
+export interface EventBusCapability {
+    /**
+     * Emit event
+     *
+     * @param eventType Event type
+     * @param payload Event payload
+     */
+    emit(eventType: string, payload: unknown): void;
+    /**
+     * Subscribe to event
+     *
+     * @param eventType Event type
+     * @param handler Event handler
+     * @returns Unsubscribe function
+     */
+    on(eventType: string, handler: EventHandler): () => void;
+    /**
+     * Unsubscribe from event
+     *
+     * @param eventType Event type
+     * @param handler Event handler
+     */
+    off(eventType: string, handler: EventHandler): void;
+}
+/**
+ * Governed Event Bus Capability Type Identifier
+ */
+export declare const GovernedEventBusCapabilityType: unique symbol;
+/**
+ * Governed Event
+ *
+ * <p>Event containing complete metadata for observability and auditing.</p>
+ */
+export interface GovernedEvent<T = unknown> {
+    /** Event Type */
+    readonly type: string;
+    /** Event Payload */
+    readonly payload: T;
+    /** Event Metadata */
+    readonly metadata: GovernedEventMetadata;
+}
+/**
+ * Governed Event Metadata
+ */
+export interface GovernedEventMetadata {
+    /** Event ID (Unique Identifier) */
+    readonly eventId: string;
+    /** Emit Timestamp */
+    readonly timestamp: number;
+    /** Sender (Plugin ID) */
+    readonly source: string;
+    /** Tenant ID */
+    readonly tenantId?: string;
+    /**
+     * Event Scope
+     * - 'plugin': Visible only within the plugin
+     * - 'host': Globally visible
+     */
+    readonly scope: 'plugin' | 'host';
+}
+/**
+ * Governed Event Handler Function
+ */
+export type GovernedEventHandler<T = unknown> = (event: GovernedEvent<T>) => void;
+/**
+ * Governed Event Bus Capability Contract
+ *
+ * <p>Unlike the simple EventBusCapability, GovernedEventBusCapability provides:</p>
+ * <ul>
+ *   <li>Automatic injection of event metadata (eventId, timestamp, source)</li>
+ *   <li>Event scope control (plugin/host)</li>
+ *   <li>Complete event audit information</li>
+ * </ul>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const eventBus = context.getCapability<GovernedEventBusCapability>(GovernedEventBusCapabilityType);
+ *
+ * // Emit global event
+ * eventBus.emit('booking:created', { bookingId: '123' }, 'host');
+ *
+ * // Subscribe to event (receive complete metadata)
+ * eventBus.on('booking:created', (event) => {
+ *   console.log(`Event ${event.metadata.eventId} from ${event.metadata.source}`);
+ *   console.log('Payload:', event.payload);
+ * });
+ * ```
+ */
+export interface GovernedEventBusCapability {
+    /**
+     * Emit Event
+     *
+     * @param eventType Event type
+     * @param payload Event payload
+     * @param scope Event scope (default 'host')
+     */
+    emit<T = unknown>(eventType: string, payload: T, scope?: 'plugin' | 'host'): void;
+    /**
+     * Subscribe to Event
+     *
+     * @param eventType Event type
+     * @param handler Event handler function, receives complete GovernedEvent
+     * @returns Unsubscribe function
+     */
+    on<T = unknown>(eventType: string, handler: GovernedEventHandler<T>): Unsubscribe;
+    /**
+     * Subscribe to Event Once
+     *
+     * @param eventType Event type
+     * @param handler Event handler function
+     * @returns Unsubscribe function
+     */
+    once<T = unknown>(eventType: string, handler: GovernedEventHandler<T>): Unsubscribe;
+    /**
+     * Unsubscribe from Event
+     *
+     * @param eventType Event type
+     * @param handler Event handler function
+     */
+    off<T = unknown>(eventType: string, handler: GovernedEventHandler<T>): void;
+}
+//# sourceMappingURL=event.d.ts.map

package/src/types/event.d.ts.map

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