@kosdev-code/kos-ui-sdk 2.1.16 → 2.1.18

package/core/core/companion-instantiator.d.ts

@@ -0,0 +1,71 @@
+import { IKosRegistry } from './types';
+import { KosModelCacheHandler } from './model-cache';
+import { IKosModel } from './kosModel';
+import { DependencyLifecycle } from '../types';
+
+/**
+ * Handles creation and lifecycle management of companion models.
+ * Companions are models that extend or enhance parent models and can be
+ * created at specific lifecycle phases based on decorator configuration.
+ */
+export declare class KosCompanionInstantiator {
+    private registry;
+    private cache;
+    private createModel;
+    constructor(registry: IKosRegistry, cache: KosModelCacheHandler, createModel: (typeId: string, id: string, options: Record<string, any>) => any);
+    /**
+     * Creates companion models for a parent model, optionally filtered by lifecycle phase.
+     * Called automatically during instantiation for companions without lifecycle specified.
+     * Can be called from lifecycle hooks to create lifecycle-deferred companions.
+     *
+     * @param model The parent model
+     * @param options Options to pass to companion constructors
+     * @param lifecycle Optional lifecycle filter - only create companions matching this phase
+     */
+    createCompanionModels(model: IKosModel, options: Record<string, any>, lifecycle?: DependencyLifecycle): void;
+    /**
+     * Get companion definitions for a parent model type
+     */
+    private getCompanionDefinitions;
+    /**
+     * Resolve companion type from definition and extract lifecycle metadata
+     */
+    private resolveCompanionType;
+    /**
+     * Resolve factory companion by calling factory and extracting lifecycle
+     */
+    private resolveFactoryCompanion;
+    /**
+     * Resolve string companion using pre-extracted lifecycle from registration
+     */
+    private resolveStringCompanion;
+    /**
+     * Extract lifecycle metadata from companion model decorator
+     */
+    private extractLifecycleFromType;
+    /**
+     * Determine if companion should be created based on lifecycle filtering
+     */
+    private shouldCreateCompanion;
+    /**
+     * Instantiate and attach companion to parent model
+     */
+    private instantiateCompanion;
+    /**
+     * Generate unique companion ID
+     */
+    private generateCompanionId;
+    /**
+     * Check if companion already exists in cache
+     */
+    private companionAlreadyExists;
+    /**
+     * Create companion model instance with parent context
+     */
+    private createCompanionInstance;
+    /**
+     * Attach companion to parent model
+     */
+    private attachCompanionToParent;
+}
+//# sourceMappingURL=companion-instantiator.d.ts.map

package/core/core/companion-instantiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-instantiator.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/core/companion-instantiator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAIvE;;;;GAIG;AACH,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,WAAW;gBAFX,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,oBAAoB,EAC3B,WAAW,EAAE,CACnB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KACzB,GAAG;IAGV;;;;;;;;OAQG;IACH,qBAAqB,CACnB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,CAAC,EAAE,mBAAmB;IAyBjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAqB/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAU9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAWhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAe/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAOhC"}

package/core/core/decorators/fsm-injection-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Main coordinator for injecting FSM support into a model instance.
+ * Delegates to Zone 3 functions for actual implementation.
+ *
+ * @param modelInstance The model instance to inject FSM support into
+ */
+export declare function injectStateMachineSupport(modelInstance: any): void;
+/**
+ * Initialize the state machine at a specific lifecycle phase.
+ * Called from KosModel lifecycle hooks.
+ *
+ * @param modelInstance The model instance
+ * @param lifecycle The current lifecycle phase
+ */
+export declare function initializeStateMachine(modelInstance: any, lifecycle: string): void;
+//# sourceMappingURL=fsm-injection-utils.d.ts.map

package/core/core/decorators/fsm-injection-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm-injection-utils.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/fsm-injection-utils.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,GAAG,QAoB3D;AAmZD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,QA0B3E"}

package/core/core/decorators/index.d.ts

@@ -1,7 +1,9 @@
+export * from './fsm-injection-utils';
 export * from './kos-child';
 export * from './kos-companion';
 export * from './kos-container-aware';
 export * from './kos-context';
+export * from './kos-execution-context';
 export * from './kos-future-aware';
 export * from './kos-multiple-future-aware';
 export * from './kos-http-decorators';
@@ -10,6 +12,8 @@ export * from './kos-logger-aware';
 export * from './kos-model-effect';
 export * from './kos-parent';
 export * from './kos-reference';
+export * from './kos-service-request';
+export * from './kos-state-machine';
 export * from './kos-trouble-aware';
 export * from './kosDependency';
 export * from './kosModel';

package/core/core/decorators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/core/core/decorators/kos-companion.d.ts

@@ -1,4 +1,5 @@
 import { IKosDataModel } from '../kosModel';
+import { DependencyLifecycle } from '../../types';
 
 export interface KosCompanionOptions {
     /**
@@ -11,6 +12,20 @@ export interface KosCompanionOptions {
     excludeProperties?: string[];
     /** Custom parent property name. Default: 'companionParent' */
     parentProperty?: string;
+    /**
+     * Lifecycle phase at which this companion should be created.
+     * Defaults to INIT (created immediately during parent instantiation).
+     * Use LOAD to create after parent's load() completes, READY for after ready(), etc.
+     *
+     * @example
+     * ```typescript
+     * @kosCompanion({ lifecycle: DependencyLifecycle.LOAD })
+     * class CarbAgitatorModel implements IKosDataModel {
+     *   // Created after assembly.load() completes
+     * }
+     * ```
+     */
+    lifecycle?: DependencyLifecycle;
 }
 /**
  * Base interface for all companion models.
@@ -119,6 +134,10 @@ export interface KosCompanionDecorator<TParent extends IKosDataModel = IKosDataM
  * // Decorator mode with exclusions
  * @kosCompanion({ mode: 'decorator', excludeProperties: ['internalState'] })
  * class MyCompanion { }
+ *
+ * // Lifecycle-deferred companion creation
+ * @kosCompanion({ lifecycle: DependencyLifecycle.LOAD })
+ * class DataDrivenCompanion { }
  * ```
  *
  * @category KOS Model Decorator

package/core/core/decorators/kos-companion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-companion.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-companion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IACnC,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,aAAa,GAAG,aAAa;IAE7C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB,CACtC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAAG;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAmB1E"}
+{"version":3,"file":"kos-companion.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-companion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IACnC,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,aAAa,GAAG,aAAa;IAE7C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB,CACtC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAAG;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAqB1E"}

package/core/core/decorators/kos-execution-context.d.ts

@@ -0,0 +1,60 @@
+import { ServiceRequestExecutor, HttpMethod } from './kos-service-request';
+
+/**
+ * Symbol used to uniquely identify KosExecutionContext objects.
+ * Decorators use this to reliably detect if the last parameter is an execution context.
+ * @internal
+ */
+export declare const KOS_EXECUTION_CONTEXT: unique symbol;
+/**
+ * Execution context passed to decorated methods for accessing decorator-injected functionality.
+ *
+ * This context provides a type-safe way for decorators to inject runtime functionality
+ * into methods without polluting the class interface or relying on magic parameters.
+ *
+ * Currently used by @kosServiceRequest to inject the $request executor.
+ * Designed to be extensible for future decorators that need to inject runtime functionality.
+ *
+ * @example Using with @kosServiceRequest
+ * ```typescript
+ * @kosServiceRequest({
+ *   path: PATH_VM_INSTALL,
+ *   method: 'post'
+ * })
+ * async createRelease(
+ *   path: string,
+ *   keysetId?: string,
+ *   ctx: KosExecutionContext<paths, typeof PATH_VM_INSTALL, 'post'>
+ * ): Promise<void> {
+ *   const [error, response] = await ctx.$request({
+ *     queryParams: { keySetId: keysetId },
+ *     body: { path }
+ *   });
+ *   if (error) throw new Error(error);
+ *   return response?.data;
+ * }
+ * ```
+ */
+export interface KosExecutionContext<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get"> {
+    /**
+     * Symbol marker to identify this as a KosExecutionContext
+     * @internal
+     */
+    [KOS_EXECUTION_CONTEXT]: true;
+    /**
+     * Service request executor (injected by @kosServiceRequest)
+     * Executes the service request defined in the decorator configuration.
+     */
+    $request?: ServiceRequestExecutor<Paths, Path, Method>;
+    /**
+     * Future tracker ID string (injected by @kosFuture when trackerPolicy is 'context')
+     * This is the tracker ID that can be used with future management utilities.
+     */
+    $tracker?: string;
+}
+/**
+ * Type guard to check if an object is a KosExecutionContext
+ * @internal
+ */
+export declare function isKosExecutionContext(obj: any): obj is KosExecutionContext;
+//# sourceMappingURL=kos-execution-context.d.ts.map

package/core/core/decorators/kos-execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-execution-context.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,eAAgC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,mBAAmB,CAClC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvD,IAAI,SAAS,MAAM,KAAK,GAAG,MAAM,EACjC,MAAM,SAAS,UAAU,GAAG,KAAK;IAEjC;;;OAGG;IACH,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAEvD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,mBAAmB,CAE1E"}

package/core/core/decorators/kos-service-request.d.ts

@@ -0,0 +1,381 @@
+import { KosExecutionContext } from './kos-execution-context';
+import { KosModelRegistrationType } from '../registration/model-registration';
+import { IKosDataModel } from '../kosModel';
+import { ClientBody, ClientParams } from '../../util/kos-service-request';
+import { ResponseCacheConfig } from '../../types/service-response-store';
+import { DependencyLifecycle } from '../../types';
+
+export type { KosExecutionContext };
+/**
+ * Symbol for storing service request handlers metadata on model instances
+ * @internal
+ */
+export declare const ServiceRequestHandlers: unique symbol;
+/**
+ * HTTP methods supported by kosServiceRequest
+ */
+export type HttpMethod = "get" | "GET" | "post" | "POST" | "put" | "PUT" | "delete" | "DELETE" | "patch" | "PATCH";
+/**
+ * API path type - string representing an API endpoint
+ */
+export type ApiPath = string;
+/**
+ * Configuration for field mapping in data transformation
+ */
+export interface FieldMapping {
+    /**
+     * Source field path (dot notation supported, e.g., 'data.user.name')
+     */
+    from: string;
+    /**
+     * Target field name in the model
+     */
+    to: string;
+    /**
+     * Optional transformation to apply
+     * Built-in: 'string', 'number', 'boolean', 'date', 'json'
+     * Custom: function name or transformer function
+     */
+    transform?: string | ((value: any) => any);
+    /**
+     * Whether this field is required
+     */
+    required?: boolean;
+    /**
+     * Default value if field is missing
+     */
+    default?: any;
+}
+/**
+ * Configuration for extension points during transformation
+ */
+export interface ExtensionConfig {
+    /**
+     * Type of extension point
+     */
+    type: "loader" | "data-mapper" | "validator";
+    /**
+     * Extension identifier (e.g., ExtensionType.IngredientMapper)
+     */
+    extension: any;
+    /**
+     * When to execute the extension
+     */
+    phase?: "before" | "after" | "transform";
+}
+/**
+ * Error handling strategy for service requests
+ */
+export interface ErrorHandlerConfig {
+    /**
+     * How to handle errors
+     * - 'throw': Re-throw error (default)
+     * - 'log': Log error and continue
+     * - 'ignore': Silently ignore errors
+     * - 'default': Return default value
+     */
+    strategy: "throw" | "log" | "ignore" | "default";
+    /**
+     * Default value to return when strategy is 'default'
+     */
+    defaultValue?: any;
+    /**
+     * Custom error handler function
+     */
+    onError?: (error: Error, model: IKosDataModel) => void;
+}
+/**
+ * Configuration parameters for @kosServiceRequest decorator
+ * Enables lifecycle-driven HTTP requests with declarative data transformation
+ *
+ * @typeparam Paths - The OpenAPI paths type (from your OpenAPI schema)
+ * @typeparam Path - The specific API path being requested
+ * @typeparam Method - The HTTP method type
+ * @typeparam Response - The raw response type from the API
+ * @typeparam TransformedResponse - The transformed response type after mappings
+ */
+export interface IKosServiceRequestParams<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get", Response = any, TransformedResponse = Response> {
+    /**
+     * API path to request
+     *
+     * @example
+     * path: '/api/kos/ingredients'
+     * path: `/api/devices/${PROP_DEVICE_ID}/status` // with PropKey
+     */
+    path: Path;
+    /**
+     * HTTP method
+     *
+     * @default 'get'
+     */
+    method?: Method;
+    /**
+     * When to execute this request during model lifecycle
+     *
+     * If omitted, the request executes when the decorated method is called (method-driven).
+     * If specified, the request executes automatically during the given lifecycle phase (lifecycle-driven).
+     *
+     * @example
+     * // Lifecycle-driven (auto-execute during LOAD phase)
+     * lifecycle: DependencyLifecycle.LOAD
+     *
+     * @example
+     * // Method-driven (execute when method is called)
+     * lifecycle: undefined  // or omit entirely
+     */
+    lifecycle?: DependencyLifecycle;
+    /**
+     * Path parameters to expand in the URL
+     * Strongly typed from OpenAPI schema
+     * Can be static values or PropKey references
+     *
+     * @example
+     * // Static value
+     * pathParams: { deviceId: 'device-123' }
+     *
+     * @example
+     * // PropKey reference (use PROP_ prefix)
+     * pathParams: { deviceId: PROP_DEVICE_ID }
+     *
+     * @example
+     * // Dynamic from method arguments
+     * pathParams: (model, deviceId, status) => ({ deviceId })
+     */
+    pathParams?: (ClientParams<Paths, Path, Method> extends {
+        path?: infer P;
+    } ? P : never) | ((model: IKosDataModel, ...args: any[]) => ClientParams<Paths, Path, Method> extends {
+        path?: infer P;
+    } ? P : never);
+    /**
+     * Query parameters
+     * Strongly typed from OpenAPI schema
+     *
+     * @example
+     * // Static
+     * queryParams: { includeMetadata: true, format: 'json' }
+     *
+     * @example
+     * // Dynamic from method arguments
+     * queryParams: (model, deviceId, debug) => ({ debug })
+     */
+    queryParams?: (ClientParams<Paths, Path, Method> extends {
+        query?: infer Q;
+    } ? Q : never) | ((model: IKosDataModel, ...args: any[]) => ClientParams<Paths, Path, Method> extends {
+        query?: infer Q;
+    } ? Q : never);
+    /**
+     * Request body (for POST/PUT/PATCH)
+     * Strongly typed from OpenAPI schema
+     *
+     * @example
+     * // Static body
+     * body: { action: 'start' }
+     *
+     * @example
+     * // Dynamic from method arguments
+     * body: (model, vehicleType, speed) => ({ vehicleType, speed })
+     */
+    body?: ClientBody<Paths, Path, Method> | ((model: IKosDataModel, ...args: any[]) => ClientBody<Paths, Path, Method>);
+    /**
+     * JSON path to iterate over in response
+     * Creates models for each item in the array
+     *
+     * @example
+     * iterateOver: 'data.ingredients' // Iterates response.data.ingredients array
+     */
+    iterateOver?: string;
+    /**
+     * Model registration object for creating instances from array items
+     * Used with iterateOver to create child models using the builder pattern
+     *
+     * @example
+     * modelFactory: IngredientModel  // The registration object itself
+     *
+     * deprecated The old curried function signature is deprecated:
+     * modelFactory?: (id: string) => (options: any) => IKosDataModel
+     */
+    modelFactory?: KosModelRegistrationType<IKosDataModel, Record<string, unknown>> | ((id: string) => (options: unknown) => IKosDataModel);
+    /**
+     * Function to extract the model ID from response data items
+     * Required when using modelFactory if items don't have an 'id' field
+     *
+     * @example
+     * idExtractor: (item) => item.ingredientId
+     * idExtractor: (item) => `${item.type}-${item.index}`
+     */
+    idExtractor?: (item: any) => string;
+    /**
+     * Field mappings for data transformation
+     * Same format as @kosTopicHandler mappings
+     *
+     * @example
+     * mappings: [
+     *   { from: 'id', to: 'id' },
+     *   { from: 'ingredientId', to: 'ingredientId' },
+     *   { from: 'metadata.calories', to: 'calories', transform: 'number' }
+     * ]
+     */
+    mappings?: FieldMapping[];
+    /**
+     * Extension points to execute during transformation
+     *
+     * @example
+     * extensions: [
+     *   { type: 'data-mapper', extension: ExtensionType.IngredientMapper }
+     * ]
+     */
+    extensions?: ExtensionConfig[];
+    /**
+     * Transformation function for response data
+     * Applied before mappings
+     *
+     * @example
+     * transform: (response) => response.data
+     */
+    transform?: (response: Response) => TransformedResponse;
+    /**
+     * Condition to determine if request should execute
+     *
+     * @example
+     * condition: (model) => model.isInitialized
+     */
+    condition?: (model: IKosDataModel) => boolean;
+    /**
+     * Error handling strategy
+     *
+     * @example
+     * errorHandler: {
+     *   strategy: 'default',
+     *   defaultValue: [],
+     *   onError: (error, model) => model.logger.error('Failed to load', error)
+     * }
+     */
+    errorHandler?: ErrorHandlerConfig;
+    /**
+     * Response caching configuration
+     * Controls how long responses are stored and when they're cleaned up
+     *
+     * @default { retention: ResponseRetention.SINGLE }
+     *
+     * @example
+     * // No caching - clear immediately after handler
+     * cache: { retention: ResponseRetention.IMMEDIATE }
+     *
+     * @example
+     * // Cache for 5 minutes
+     * cache: { retention: ResponseRetention.TTL, ttl: 5 * 60 * 1000 }
+     *
+     * @example
+     * // Keep for model lifetime
+     * cache: { retention: ResponseRetention.PERMANENT }
+     */
+    cache?: ResponseCacheConfig;
+}
+/**
+ * Metadata stored for each service request handler
+ * @internal
+ */
+export interface ServiceRequestMetadata<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get", Response = any, TransformedResponse = Response> extends IKosServiceRequestParams<Paths, Path, Method, Response, TransformedResponse> {
+    /**
+     * The method name that handles the response
+     */
+    handlerMethod: string;
+    /**
+     * The original handler function
+     */
+    originalHandler: Function;
+}
+/**
+ * Runtime service request executor injected into method context
+ * Allows imperative execution of the service request defined by the decorator
+ */
+export interface ServiceRequestExecutor<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get"> {
+    (options?: {
+        pathParams?: ClientParams<Paths, Path, Method> extends {
+            path?: infer P;
+        } ? P : never;
+        queryParams?: ClientParams<Paths, Path, Method> extends {
+            query?: infer Q;
+        } ? Q : never;
+        body?: ClientBody<Paths, Path, Method>;
+    }): Promise<[string | null, any]>;
+}
+/**
+ * Type alias for the service request executor function signature.
+ * This executor is automatically passed as the last parameter to methods
+ * decorated with @kosServiceRequest (without lifecycle).
+ *
+ * @example
+ * ```typescript
+ * type CreateReleaseExecutor = ServiceRequestExecutor<paths, typeof PATH_VM_INSTALL, 'post'>;
+ * ```
+ */
+export type ServiceRequestExecutorFn<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get"> = ServiceRequestExecutor<Paths, Path, Method>;
+/**
+ * Decorator for lifecycle-driven service requests within KOS models
+ *
+ * Eliminates service boilerplate by integrating HTTP requests directly into
+ * the model lifecycle. Responses are cached in ServiceResponseStore for access
+ * via utility functions, avoiding "magic last parameter" patterns.
+ *
+ * @param params - Configuration for the service request
+ * @returns Method decorator
+ *
+ * @example Basic GET request during LOAD
+ * ```typescript
+ * @kosServiceRequest({
+ *   path: PATH_DEVICE_STATUS,
+ *   method: 'get',
+ *   lifecycle: DependencyLifecycle.LOAD,
+ *   cache: { retention: ResponseRetention.SINGLE }
+ * })
+ * private onStatusLoaded(): void {
+ *   const response = getServiceResponse(this, PATH_DEVICE_STATUS, 'get');
+ *   this.status = response?.status;
+ * }
+ * ```
+ *
+ * @example Method-driven request with execution context
+ * ```typescript
+ * @kosServiceRequest({
+ *   path: PATH_VM_INSTALL,
+ *   method: 'post'
+ * })
+ * async createRelease(
+ *   path: string,
+ *   keysetId?: string,
+ *   ctx: KosExecutionContext<paths, typeof PATH_VM_INSTALL, 'post'>
+ * ): Promise<void> {
+ *   const [error, response] = await ctx.$request({
+ *     queryParams: { keySetId: keysetId },
+ *     body: { path }
+ *   });
+ *   if (error) throw new Error(error);
+ *   return response?.data;
+ * }
+ * ```
+ *
+ * @example Container model with iteration
+ * ```typescript
+ * @kosServiceRequest({
+ *   path: PATH_INGREDIENTS,
+ *   method: 'get',
+ *   lifecycle: DependencyLifecycle.LOAD,
+ *   iterateOver: 'data.ingredients',
+ *   modelFactory: Ingredient.factory,
+ *   mappings: [
+ *     { from: 'id', to: 'id' },
+ *     { from: 'name', to: 'name' }
+ *   ]
+ * })
+ * private onIngredientsLoaded(): void {
+ *   const response = getServiceResponse(this, PATH_INGREDIENTS, 'get');
+ *   // Mappings already applied to response data
+ *   response?.forEach(i => this.ingredients.addModel(i));
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ */
+export declare function kosServiceRequest<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get", Response = any, TransformedResponse = Response>(params: IKosServiceRequestParams<Paths, Path, Method, Response, TransformedResponse>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//# sourceMappingURL=kos-service-request.d.ts.map

package/core/core/decorators/kos-service-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-service-request.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-service-request.ts"],"names":[],"mappings":"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"}