@kosdev-code/kos-ui-sdk 3.0.7 → 3.0.8

package/models/models/software-info/services/software-info-services.d.ts

@@ -35,7 +35,7 @@ export declare const getSoftwareInfos: (signal?: AbortSignal) => Promise<DeviceS
  * }
  * ```
  */
-export declare const getSoftwareInfosWithCancel: import('../../../utils/cancellable-service').CancellableFunction<() => Promise<{
+export declare const getSoftwareInfosWithCancel: import('../../../utils').CancellableFunction<() => Promise<{
     nodes?: import('../../../utils/types').components["schemas"]["a7a680dc-5c50-468d-8063-704a7bf4e167"];
 }>>;
 //# sourceMappingURL=software-info-services.d.ts.map

package/models/types/cancellable-promise.d.ts

@@ -1,37 +1,61 @@
 /**
- * A Promise that can be cancelled and provides progress/state tracking
+ * A long-running operation whose progress can be observed imperatively.
+ *
+ * This is the consumer-facing contract for progress surfaces (progress
+ * notifications, status indicators, modals): they depend on this interface,
+ * never on the producer. Producers adapt their source to it — e.g.
+ * `awaitFutureCall` adapts a KOS Future, but an XHR upload or an aggregate
+ * over several operations can implement it just as well.
  */
-export interface CancellablePromise<T> extends Promise<T> {
+export interface ProgressOperation<T = unknown> extends Promise<T> {
     /**
-     * Cancel this specific operation
+     * Percent complete, 0-100. Values <= 0 mean the operation has not reported
+     * real progress yet — consumers should render an indeterminate state.
      */
-    cancel(): Promise<void>;
+    readonly progress: number;
     /**
-     * Get the underlying AbortController for this operation
+     * Current status of the operation.
+     * Common values: "NOT_ACTIVE", "IN_PROGRESS", a terminal end state
+     * ("SUCCESS" | "FAIL" | "ABORT" | "CANCEL"), or consumer-defined.
      */
-    getController(): AbortController | undefined;
+    readonly status: string;
     /**
-     * Check if this operation is cancelled
+     * Whether the operation is currently running
      */
-    isCancelled(): boolean;
+    readonly isRunning: boolean;
     /**
-     * Current progress of the operation (0-1)
+     * Human-readable time remaining (e.g. "2 minutes"), when the source can
+     * estimate it. Empty/undefined when unknown.
      */
-    readonly progress: number;
+    readonly timeRemaining?: string;
     /**
-     * Current status of the operation
+     * Cancel this specific operation
      */
-    readonly status: string;
+    cancel(): Promise<void>;
     /**
-     * Whether the operation is currently running
+     * Check if this operation was cancelled. Optional — consumers must treat
+     * a missing implementation as "unknown".
      */
-    readonly isRunning: boolean;
+    isCancelled?(): boolean;
     /**
      * Subscribe to progress updates
      * Returns a dispose function to clean up the subscription
      */
     onProgressUpdate(callback: (progress: number, status: string) => void): () => void;
 }
+/**
+ * A Promise that can be cancelled and provides progress/state tracking
+ */
+export interface CancellablePromise<T> extends ProgressOperation<T> {
+    /**
+     * Get the underlying AbortController for this operation
+     */
+    getController(): AbortController | undefined;
+    /**
+     * Check if this operation is cancelled
+     */
+    isCancelled(): boolean;
+}
 /**
  * Options for creating a cancellable promise with progress tracking
  */

package/models/types/cancellable-promise.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cancellable-promise.d.ts","sourceRoot":"","sources":["../../../../../packages/kos-ui-sdk/src/models/types/cancellable-promise.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACvD;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,aAAa,IAAI,eAAe,GAAG,SAAS,CAAC;IAE7C;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,gBAAgB,CACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACnD,MAAM,IAAI,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,GAAG,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,eAAe,CAAC,EAAE,eAAe,EACjC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAClC,MAAM,CAAC,EAAE,GAAG,GACX,kBAAkB,CAAC,CAAC,CAAC,CAAC;AACzB,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,kBAAkB,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cancellable-promise.d.ts","sourceRoot":"","sources":["../../../../../packages/kos-ui-sdk/src/models/types/cancellable-promise.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAChE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;OAGG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC;IAExB;;;OAGG;IACH,gBAAgB,CACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACnD,MAAM,IAAI,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IACjE;;OAEG;IACH,aAAa,IAAI,eAAe,GAAG,SAAS,CAAC;IAE7C;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,GAAG,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,eAAe,CAAC,EAAE,eAAe,EACjC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAClC,MAAM,CAAC,EAAE,GAAG,GACX,kBAAkB,CAAC,CAAC,CAAC,CAAC;AACzB,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,kBAAkB,CAAC,CAAC,CAAC,CAAC"}

package/models/utils/await-future-call.d.ts

@@ -0,0 +1,62 @@
+import { FutureContainer } from '../models/future/future-types';
+import { FutureEndState } from '../services/future';
+import { CancellablePromise } from '../types/cancellable-promise';
+/**
+ * Rejection raised when the awaited future ends in FAIL / ABORT / CANCEL.
+ * `reason` carries the backend's reason code (e.g. a ReasonException id),
+ * so callers can map it to user-facing messages.
+ */
+export declare class FutureCallError extends Error {
+    readonly endState: FutureEndState;
+    readonly reason?: string;
+    readonly futureId?: string;
+    constructor(endState: FutureEndState, reason?: string, futureId?: string);
+    get isCancelled(): boolean;
+}
+export interface AwaitFutureCallOptions {
+    /** Alias the wrapped method registers its future under (@kosFuture alias). */
+    alias?: string;
+    /**
+     * Reject with a timeout error if the future has not reached an end state
+     * within this window. Unset = wait indefinitely.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Invoke a @kosFuture method on a future-aware model and return a
+ * CancellablePromise that settles from the future's end state:
+ *
+ * - resolves with the method's response once the future ends in SUCCESS
+ * - rejects with {@link FutureCallError} on FAIL / ABORT / CANCEL
+ * - rejects with the service error if the call itself throws
+ * - resolves with the response when the call turns out not to be
+ *   future-tracked (no future was produced)
+ *
+ * The future created by the call is captured reactively (the @kosFuture
+ * wrapper registers it on the model's futureHandler before the request is
+ * sent), so no timing hacks are needed and concurrent operations on other
+ * aliases are unaffected.
+ *
+ * @example Awaiting real completion from a command
+ * ```typescript
+ * try {
+ *   await awaitFutureCall(artifact, (a) =>
+ *     a.publishImportedKab(path, version, qualifier)
+ *   );
+ *   studio.notifications.success("Published");
+ * } catch (e) {
+ *   if (e instanceof FutureCallError && !e.isCancelled) {
+ *     studio.notifications.error(mapReason(e.reason));
+ *   }
+ * }
+ * ```
+ *
+ * @example Cancellation and progress
+ * ```typescript
+ * const call = awaitFutureCall(model, (m) => m.performOperation());
+ * const stop = call.onProgressUpdate((p, status) => render(p, status));
+ * // later: await call.cancel();
+ * ```
+ */
+export declare function awaitFutureCall<T extends FutureContainer, R>(model: T, methodCall: (model: T) => Promise<R>, options?: AwaitFutureCallOptions): CancellablePromise<R>;
+//# sourceMappingURL=await-future-call.d.ts.map

package/models/utils/await-future-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"await-future-call.d.ts","sourceRoot":"","sources":["../../../../../packages/kos-ui-sdk/src/models/utils/await-future-call.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAIvE;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAEf,QAAQ,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAQxE,IAAI,WAAW,YAKd;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EAAE,CAAC,EAC1D,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACpC,OAAO,GAAE,sBAA2B,GACnC,kBAAkB,CAAC,CAAC,CAAC,CAuKvB"}

package/models/utils/index.d.ts

@@ -1,3 +1,6 @@
+export * from './await-future-call';
+export * from './cancellable-future-call';
+export * from './cancellable-service';
 export * from './client';
 export * from './conversion-utils';
 export * from './core-registration-manager';

package/models/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/kos-ui-sdk/src/models/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/kos-ui-sdk/src/models/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-ui-sdk",
-  "version": "3.0.7",
+  "version": "3.0.8",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -49,7 +49,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "65e37c8c2fa31716451cc469c9d23f1e4871b818"
+      "gitHash": "29a870c61fdd44a1dbbef550f682c9d991e98146"
     }
   }
 }