@thatopen/services 0.0.1

package/dist/core/client.d.ts

@@ -0,0 +1,682 @@
+import { ExecutionEntity, ExecutionSuscriptionReturnType } from '../types/execution';
+import { AppVersionProps, ComponentVersionProps, ComponentItem, AppItem, Item, ItemFolder, ItemVersion, ItemWithVersions } from '../types/items';
+import { CreateItemResponse, UpdateItemResponse } from '../types/response';
+import { CreateHiddenItemResult, HiddenFileEntity, Metadata } from '../types/files';
+import { ThatOpenContext } from '../types/context';
+
+declare global {
+    interface Window {
+        __THATOPEN_CONTEXT__?: ThatOpenContext;
+        ThatOpenCompany?: Record<string, unknown>;
+    }
+}
+/**
+ * Minimal shape of an OBC.Components-like object.
+ * Avoids hard-coupling to `@thatopen/components` at the public API level.
+ */
+export interface ComponentsLike {
+    get<T>(c: new (...args: any[]) => T): T;
+    init(): void;
+}
+/** Properties for creating a new item (file, component, or app). */
+export type CreateItemProps = {
+    /** The file to upload (File in browsers, Blob in Node.js). */
+    file: File | Blob;
+    /** Display name of the item. */
+    name: string;
+    /** Semantic version tag (e.g. "v1", "v1.0.0"). */
+    versionTag: string;
+    /** Optional folder ID to place the item in. */
+    parentFolderId?: string;
+    /** Optional project ID to associate the item with. */
+    projectId?: string;
+    /** Optional free-JSON metadata stored on the first version. */
+    metadata?: Metadata;
+};
+/** Properties for updating an existing item. Combines rename/move with optional new version upload. */
+export type UpdateItemProps = {
+    /** New display name. */
+    name?: string;
+    /** New parent folder ID (moves the item). */
+    parentFolderId?: string;
+    /** New file to upload as a new version (File in browsers, Blob in Node.js). */
+    file?: File | Blob;
+    /** Version tag for the new file version. */
+    versionTag?: string;
+    /** Optional free-JSON metadata stored on the new version. */
+    metadata?: Metadata;
+};
+/** Properties for creating an app. Extends {@link CreateItemProps} with app-specific version props. */
+export type CreateAppProps = CreateItemProps & {
+    /** App version properties (isOnline, url). */
+    appProps?: AppVersionProps;
+};
+/** Properties for creating a component. Extends {@link CreateItemProps} with component-specific version props. */
+export type CreateComponentProps = CreateItemProps & {
+    /** Component version properties (type, tier, isPublic, etc.). Required. */
+    componentProps: ComponentVersionProps;
+};
+/** Properties for updating a component. Extends {@link UpdateItemProps} with component-specific version props. */
+export type UpdateComponentProps = UpdateItemProps & {
+    /** Component version properties for the new version. */
+    componentProps?: ComponentVersionProps;
+};
+/** Options for retrieving a single item. */
+export type GetItemProps = {
+    /** If true, includes the item's version history. */
+    showVersions?: boolean;
+};
+/** Filter/query params for listing items. */
+export type GetItemsParams = {
+    /** Filter by folder. */
+    folderId?: string;
+    /** If true, includes version history for each item. */
+    ShowVersions?: boolean;
+};
+/** Parameters for downloading a specific item version. */
+export type DownloadItemFileParams = {
+    /** Download a specific version by tag instead of the latest. */
+    versionTag?: string;
+    /** If true, includes draft versions in resolution. */
+    withDraft?: boolean;
+};
+/** Configuration options for the {@link EngineServicesClient} constructor. */
+export type EngineServicesClientProps = {
+    /** Number of automatic retries on request failure. Default: 0. */
+    retries?: number;
+    /**
+     * If true, sends the token as an `Authorization: Bearer` header instead of
+     * an `accessToken` query parameter. Use this when authenticating with an
+     * Auth0 JWT (e.g. inside platform apps) rather than a platform API token.
+     */
+    useBearer?: boolean;
+    /**
+     * URL of a local execution server started with `thatopen local-server`.
+     * When set, execution methods (executeComponent, onExecutionProgress,
+     * listExecutions, getExecution, abortExecution) are routed to this server
+     * instead of the cloud API. All other methods remain unchanged.
+     *
+     * @example
+     * ```ts
+     * const client = new EngineServicesClient(token, apiUrl, {
+     *   localServerUrl: 'http://localhost:4001',
+     * });
+     * ```
+     */
+    localServerUrl?: string;
+};
+/**
+ * Client for the That Open Engine Services API.
+ *
+ * Provides methods for managing files, folders, components, apps,
+ * executions, hidden files, projects, and permissions.
+ *
+ * @example
+ * ```ts
+ * import { EngineServicesClient } from 'thatopen-services';
+ *
+ * const client = new EngineServicesClient('my-access-token', 'https://api.thatopen.com');
+ * const files = await client.listFiles();
+ * ```
+ */
+export declare class EngineServicesClient {
+    #private;
+    private apiUrl;
+    private accessToken;
+    private wsUrl;
+    private retries;
+    private useBearer;
+    private builtInGlobals;
+    /**
+     * URL of a local execution server (e.g. `http://localhost:4001`).
+     * When set, execution methods are routed to this server instead of the cloud API.
+     * Set to `null` to disable local routing and use the cloud API.
+     */
+    localServerUrl: string | null;
+    /**
+     * The platform context this client was created with.
+     * Contains `appId`, `projectId`, `accessToken`, and `apiUrl`.
+     * Populated automatically when using {@link fromPlatformContext}.
+     */
+    readonly context: ThatOpenContext;
+    /**
+     * Creates a client from the platform context injected into
+     * `window.__THATOPEN_CONTEXT__` by the That Open Platform.
+     *
+     * This is the recommended way to create a client inside platform apps.
+     * It automatically reads the auth context and sets `useBearer: true`.
+     *
+     * @param props - Optional configuration (retry count, local server URL, etc.).
+     * @returns A new EngineServicesClient instance.
+     *
+     * @example
+     * ```ts
+     * const client = EngineServicesClient.fromPlatformContext();
+     * console.log(client.context.projectId);
+     * ```
+     */
+    static fromPlatformContext(props?: Omit<EngineServicesClientProps, 'useBearer'>): EngineServicesClient;
+    /**
+     * Creates a new EngineServicesClient instance.
+     * @param accessToken - API access token (obtained from the platform dashboard)
+     *   or an Auth0 JWT (when using `useBearer: true`).
+     * @param apiUrl - Base URL of the API (e.g. "https://api.thatopen.com").
+     * @param props - Optional configuration (retry count, auth mode, etc.).
+     */
+    constructor(accessToken: string, apiUrl: string, props?: EngineServicesClientProps);
+    /**
+     * Sets the number of automatic retries for failed requests.
+     * @param retries - Number of retries (0 = no retries).
+     */
+    setRetries(retries: number): void;
+    /**
+     * Registers the global libraries that built-in components need at runtime.
+     *
+     * Call this once after importing your libraries. Then every subsequent
+     * {@link initBuiltInComponent} call will use these globals automatically
+     * — you no longer need to pass a `globals` argument to each one.
+     *
+     * @param globals - Map of global names to module namespaces.
+     *   Common keys: `OBC`, `OBF`, `BUI`, `CUI`, `THREE`, `FRAGS`, `MARKERJS`.
+     *
+     * @example
+     * ```ts
+     * import * as OBC from "@thatopen/components";
+     * import * as OBF from "@thatopen/components-front";
+     * import * as BUI from "@thatopen/ui";
+     * import * as CUI from "@thatopen/ui-obc";
+     * import * as THREE from "three";
+     * import * as FRAGS from "@thatopen/fragments";
+     *
+     * client.setBuiltInGlobals({ OBC, OBF, BUI, CUI, THREE, FRAGS });
+     *
+     * // Now just pass the component — no globals needed:
+     * await client.initBuiltInComponent(AppManager, components);
+     * await client.initBuiltInComponent(ViewerToolbar, components);
+     * await client.initBuiltInComponent(ModelsPanel, components);
+     * ```
+     */
+    setBuiltInGlobals(globals: Record<string, unknown>): void;
+    /**
+     * Protected extension point for subclasses that need dynamic tokens
+     * (e.g. `PlatformClient` with an auth provider callback). The default
+     * returns the static token captured at construction time.
+     *
+     * When a subclass overrides this to call an async refresh function,
+     * the new token is picked up on every request — expired tokens no
+     * longer stick around.
+     */
+    protected resolveAccessToken(): Promise<string>;
+    /**
+     * Protected extension hook for subclasses (e.g. `PlatformClient`) that
+     * need to add HTTP methods against additional backend routes. Delegates
+     * to the private `#requestApi` implementation so retry / auth / query-
+     * cleaning logic is applied identically.
+     */
+    protected request<T = object>(method: string, path: string, requestData?: {
+        body?: BodyInit;
+        query?: object;
+        contentType?: 'application/json' | 'multipart/form-data' | 'application/x-www-form-urlencoded';
+        retries?: number;
+    }): Promise<T>;
+    /**
+     * Lists all files accessible by the current token.
+     * @param filters - Optional filters for folder and archive status.
+     * @returns Array of file items.
+     */
+    listFiles(filters?: {
+        folderId?: string;
+        archived?: boolean;
+        /**
+         * Scope the listing to a project. Requires the token owner to have
+         * `STORAGE:READ` role in that project; otherwise the backend returns
+         * 403. Per-entity permission overrides are applied server-side.
+         */
+        projectId?: string;
+    }): Promise<Item[]>;
+    /**
+     * Gets a single file by ID, optionally including version history.
+     * @param fileId - The file's unique identifier.
+     * @param props - Options such as whether to include versions.
+     * @returns The file item, optionally with version history.
+     */
+    getFile(fileId: string, props?: GetItemProps): Promise<ItemWithVersions<ItemWithVersions<Item>>>;
+    /**
+     * Uploads a new file.
+     * @param fileData - File content, name, and version tag.
+     * @returns The created item and its first version.
+     */
+    createFile(fileData: CreateItemProps): Promise<CreateItemResponse<Item>>;
+    /**
+     * Updates an existing file. Can rename, move to a different folder,
+     * and/or upload a new version — all in a single call.
+     * @param fileId - The file's unique identifier.
+     * @param fileData - Properties to update (name, folderId, file, versionTag).
+     * @returns The updated item and/or the new version.
+     */
+    updateFile(fileId: string, fileData: UpdateItemProps): Promise<UpdateItemResponse>;
+    /**
+     * Archives (soft-deletes) a file. Can be recovered with {@link recoverFile}.
+     * @param fileId - The file's unique identifier.
+     */
+    archiveFile(fileId: string): Promise<Item>;
+    /**
+     * Recovers a previously archived file.
+     * @param fileId - The file's unique identifier.
+     */
+    recoverFile(fileId: string): Promise<Item>;
+    /**
+     * Downloads a file's content. Returns the raw fetch Response.
+     * @param fileId - The file's unique identifier.
+     * @param params - Optional version selection parameters.
+     * @returns A fetch Response containing the file data.
+     */
+    downloadFile(fileId: string, params?: DownloadItemFileParams): Promise<Response>;
+    /**
+     * Retrieves the free-JSON metadata for a specific file version.
+     * Returns `{}` when the version exists but has no metadata.
+     * @param fileId - The file's unique identifier.
+     * @param versionTag - The version tag (e.g. "v1").
+     * @param params - Optional flags such as `withDraft`.
+     */
+    getFileVersionMetadata(fileId: string, versionTag: string, params?: {
+        withDraft?: boolean;
+    }): Promise<Metadata>;
+    /**
+     * Replaces the metadata of a specific file version with the provided object.
+     * @param fileId - The file's unique identifier.
+     * @param versionTag - The version tag.
+     * @param metadata - Free-JSON object (max 200 fields, 50-char keys/values).
+     */
+    updateFileVersionMetadata(fileId: string, versionTag: string, metadata: Metadata): Promise<Metadata>;
+    /**
+     * Clears all metadata from a specific file version.
+     * @param fileId - The file's unique identifier.
+     * @param versionTag - The version tag.
+     */
+    deleteFileVersionMetadata(fileId: string, versionTag: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Lists all folders accessible by the current token.
+     * @param params - Optional filters for parent folder and archive status.
+     * @returns Array of folder items.
+     */
+    listFolders(params?: {
+        parentFolderId?: string;
+        archived?: boolean;
+        /**
+         * Scope the listing to a project. Requires the token owner to have
+         * `STORAGE:READ` in that project; returns 403 otherwise.
+         */
+        projectId?: string;
+    }): Promise<ItemFolder[]>;
+    /**
+     * Gets a single folder by ID.
+     * @param folderId - The folder's unique identifier.
+     */
+    getFolder(folderId: string): Promise<ItemFolder>;
+    /**
+     * Creates a new folder.
+     * @param name - Display name for the folder.
+     * @param parentId - Optional parent folder ID for nesting.
+     * @returns The created folder.
+     */
+    createFolder(name: string, parentId?: string, projectId?: string): Promise<ItemFolder>;
+    /**
+     * Renames a folder.
+     * @param folderId - The folder's unique identifier.
+     * @param updateFolderParams - New name for the folder.
+     * @returns The updated folder.
+     */
+    updateFolder(folderId: string, updateFolderParams: {
+        name?: string;
+    }): Promise<ItemFolder>;
+    /**
+     * Archives (soft-deletes) a folder. Can be recovered with {@link recoverFolder}.
+     * @param folderId - The folder's unique identifier.
+     */
+    archiveFolder(folderId: string): Promise<ItemFolder>;
+    /**
+     * Recovers a previously archived folder.
+     * @param folderId - The folder's unique identifier.
+     */
+    recoverFolder(folderId: string): Promise<ItemFolder>;
+    /**
+     * Downloads an entire folder as a ZIP archive.
+     * @param folderId - The folder's unique identifier.
+     * @returns A fetch Response containing the ZIP data.
+     */
+    downloadFolder(folderId: string): Promise<Response>;
+    /**
+     * Lists all components (tools) accessible by the current token.
+     * @param params - Optional filters for folder and version inclusion.
+     * @returns Array of component items.
+     */
+    listComponents(params?: GetItemsParams & {
+        projectId?: string;
+    }): Promise<ComponentItem[]>;
+    /**
+     * Gets a single component by ID, optionally including version history.
+     * @param componentId - The component's unique identifier.
+     * @param props - Options such as whether to include versions.
+     */
+    getComponent(componentId: string, props?: GetItemProps): Promise<ItemWithVersions<ItemWithVersions<ComponentItem>>>;
+    /**
+     * Creates a new component with the given file and version properties.
+     * @param componentData - File content, name, version tag, and component-specific props.
+     * @returns The created component item and its first version.
+     */
+    createComponent(componentData: CreateComponentProps): Promise<CreateItemResponse<ComponentItem>>;
+    /**
+     * Updates an existing component. Can rename, move, and/or upload a new version.
+     * @param componentId - The component's unique identifier.
+     * @param componentData - Properties to update, including optional new componentProps.
+     * @returns The updated item and/or new version.
+     */
+    updateComponent(componentId: string, componentData: UpdateComponentProps): Promise<UpdateItemResponse<ComponentItem>>;
+    /**
+     * Downloads a component's full ZIP file. Returns the raw fetch Response.
+     * @param componentId - The component's unique identifier.
+     * @param params - Optional version selection parameters.
+     * @returns A fetch Response containing the ZIP data.
+     */
+    downloadComponent(componentId: string, params?: DownloadItemFileParams): Promise<Response>;
+    /**
+     * Downloads only the JavaScript bundle from a component's ZIP.
+     * This is the extracted `bundle` entry, returned as text.
+     * @param componentId - The component's unique identifier.
+     * @param params - Optional version selection parameters.
+     * @returns A fetch Response containing the bundle JavaScript text.
+     */
+    downloadComponentBundle(componentId: string, params?: DownloadItemFileParams): Promise<Response>;
+    /**
+     * Archives (soft-deletes) a component. Can be recovered with {@link recoverComponent}.
+     * @param componentId - The component's unique identifier.
+     */
+    archiveComponent(componentId: string): Promise<ComponentItem>;
+    /**
+     * Recovers a previously archived component.
+     * @param componentId - The component's unique identifier.
+     */
+    recoverComponent(componentId: string): Promise<ComponentItem>;
+    /**
+     * Fetches a built-in component's JavaScript bundle by name.
+     * @param name - The built-in component name (e.g. "hello-world").
+     * @returns The component's JavaScript source code as a string.
+     */
+    getBuiltInComponent(name: string): Promise<string>;
+    /**
+     * Fetches a built-in component bundle, evaluates it, and registers it
+     * with the given `components` instance via `components.get()`.
+     *
+     * After calling this, retrieve the singleton instance with
+     * `components.get(ComponentClass)`.
+     *
+     * @param component - The component class stub (must have a static `uuid`).
+     * @param components - The OBC `Components` instance used to register the
+     *   component (must expose a `.get()` method).
+     * @param globals - Map of global names to values that the component source
+     *   expects in scope (e.g. `{ OBC, BUI }`). If omitted, falls back to
+     *   globals registered via {@link setBuiltInGlobals}, then to
+     *   `window.ThatOpenCompany`.
+     *
+     * @example
+     * ```ts
+     * // Option 1: register globals once, then init without passing them
+     * client.setBuiltInGlobals({ OBC, OBF, BUI, CUI, THREE, FRAGS });
+     * await client.initBuiltInComponent(AppManager, components);
+     * await client.initBuiltInComponent(ViewerToolbar, components);
+     *
+     * // Option 2: pass globals per component (still works)
+     * await client.initBuiltInComponent(HelloWorld, components, { OBC, BUI });
+     * ```
+     */
+    initBuiltInComponent(component: {
+        uuid: string;
+    }, components: ComponentsLike, globals?: Record<string, unknown>): Promise<void>;
+    /**
+     * Loads multiple built-in components in parallel.
+     *
+     * Convenience wrapper around {@link initBuiltInComponent} that fetches
+     * and registers all given component stubs concurrently.
+     *
+     * @param components - The OBC `Components` instance.
+     * @param stubs - One or more component stubs (e.g. `AppManager`, `ViewportManager`).
+     *
+     * @example
+     * ```ts
+     * await client.initBuiltInComponents(components, AppManager, ViewportManager);
+     * ```
+     */
+    initBuiltInComponents(components: ComponentsLike, ...stubs: {
+        uuid: string;
+    }[]): Promise<void>;
+    /**
+     * High-level helper that creates an OBC component system, initialises BUI,
+     * loads built-in components, and starts the engine — all in one call.
+     *
+     * @param globals - Map of global names to module namespaces
+     *   (must include at least `OBC` and `BUI`).
+     * @param builtIns - Built-in component stubs to load (e.g. `AppManager`, `ViewportManager`).
+     * @returns An object containing the initialised `components` instance.
+     *
+     * @example
+     * ```ts
+     * const { components } = await client.setup(
+     *   { OBC, OBF, BUI, CUI, THREE, FRAGS },
+     *   AppManager, ViewportManager,
+     * );
+     *
+     * const viewports = components.get(ViewportManager);
+     * const { element, world } = await viewports.create();
+     * ```
+     */
+    setup<TComponents extends ComponentsLike = ComponentsLike>(globals: Record<string, unknown>, ...builtIns: {
+        uuid: string;
+    }[]): Promise<{
+        components: TComponents;
+    }>;
+    /**
+     * Reports an error to the platform via the {@link AppEventOrchestrator.appError} callback.
+     * @param code - Numeric error code.
+     * @param data - Arbitrary error data to send to the platform.
+     */
+    throwError(code: number, data: Record<string, string>): void;
+    /**
+     * Lists all apps accessible by the current token.
+     * @param params - Optional filters for folder and version inclusion.
+     * @returns Array of app items.
+     */
+    listApps(params?: GetItemsParams & {
+        projectId?: string;
+    }): Promise<AppItem[]>;
+    /**
+     * Creates a new app with the given file and optional version properties.
+     * @param appData - File content, name, version tag, and optional app-specific props.
+     * @returns The created app item and its first version.
+     */
+    createApp(appData: CreateAppProps): Promise<CreateItemResponse<AppItem>>;
+    /**
+     * Downloads an app's full ZIP file. Returns the raw fetch Response.
+     * @param appId - The app's unique identifier.
+     * @param params - Optional version selection parameters.
+     * @returns A fetch Response containing the ZIP data.
+     */
+    downloadApp(appId: string, params?: DownloadItemFileParams): Promise<Response>;
+    /**
+     * Downloads only the JavaScript bundle from an app's ZIP.
+     * This is the extracted `bundle` entry, returned as text.
+     * @param appId - The app's unique identifier.
+     * @param params - Optional version selection parameters.
+     * @returns A fetch Response containing the bundle JavaScript text.
+     */
+    downloadAppBundle(appId: string, params?: DownloadItemFileParams): Promise<Response>;
+    /**
+     * Archives (soft-deletes) an app.
+     * @param appId - The app's unique identifier.
+     */
+    archiveApp(appId: string): Promise<AppItem>;
+    /**
+     * Triggers server-side execution of a cloud component.
+     *
+     * Pass `projectId` in `executionParams` when running the component in the
+     * context of a specific project. The backend validates that the component
+     * is linked to that project AND that the user has execute permission
+     * there; a foreign `projectId` is rejected with 403. Omit `projectId` for
+     * personal executions (ownership path).
+     *
+     * @param componentId - The component's unique identifier.
+     * @param executionParams - Arbitrary parameters passed to the component's `main()` function. Include `projectId` to scope the execution.
+     * @param versionTag - Optional version to execute (defaults to latest).
+     * @returns An object containing the `executionId` to track progress.
+     */
+    executeComponent(componentId: string, executionParams: {
+        projectId?: string;
+        [key: string]: unknown;
+    }, versionTag?: string): Promise<{
+        executionId: string;
+    }>;
+    /**
+     * Aborts a running execution.
+     * @param executionId - The execution's unique identifier.
+     */
+    abortExecution(executionId: string): Promise<ExecutionEntity>;
+    /**
+     * Lists all executions for a given component.
+     *
+     * When `projectId` is supplied, the backend scopes the query to that
+     * project — returning only executions launched in that context AND
+     * enforcing that the caller has access to the component there. Without
+     * `projectId`, the caller's personal executions for the component are
+     * returned.
+     *
+     * @param componentId - The component's unique identifier.
+     * @param projectId - Optional project scope.
+     * @returns Array of execution entities.
+     */
+    listExecutions(componentId: string, projectId?: string): Promise<ExecutionEntity[]>;
+    /**
+     * Gets details of a specific execution, including its messages.
+     * @param executionId - The execution's unique identifier.
+     * @returns The execution entity with progress and result info.
+     */
+    getExecution(executionId: string): Promise<ExecutionEntity>;
+    /**
+     * Subscribes to real-time execution progress via WebSocket.
+     * The callback fires on each progress update until the execution completes.
+     * @param executionId - The execution's unique identifier.
+     * @param onUpdateCallback - Callback invoked on each progress/result event.
+     */
+    onExecutionProgress(executionId: string, onUpdateCallback: (data: ExecutionSuscriptionReturnType) => void): Promise<void>;
+    /**
+     * Creates a hidden file attached to a parent item (e.g., dependencies, assets).
+     * @param file - The file to upload.
+     * @param parentFileId - The parent item's unique identifier.
+     * @returns The hidden file ID.
+     */
+    createHiddenFile(file: File | Blob, parentFileId: string): Promise<CreateHiddenItemResult>;
+    /**
+     * Deletes a hidden file by its ID.
+     * @param hiddenId - The hidden file's unique identifier.
+     */
+    deleteHiddenFile(hiddenId: string): Promise<Item>;
+    /**
+     * Gets metadata for a hidden file.
+     * @param hiddenId - The hidden file's unique identifier.
+     */
+    getHiddenFile(hiddenId: string): Promise<HiddenFileEntity>;
+    /**
+     * Downloads a hidden file's content. Returns the raw fetch Response.
+     * @param hiddenId - The hidden file's unique identifier.
+     */
+    downloadHiddenFile(hiddenId: string): Promise<Response>;
+    /**
+     * Lists all hidden files attached to a parent item.
+     * @param parentFileId - The parent item's unique identifier.
+     * @returns Array of hidden file entities.
+     */
+    getHiddenFilesByParent(parentFileId: string): Promise<HiddenFileEntity[]>;
+    /**
+     * Deletes all hidden files attached to a parent item.
+     * @param parentFileId - The parent item's unique identifier.
+     */
+    deleteHiddenFilesByParent(parentFileId: string): Promise<Item[]>;
+    /**
+     * Uploads or replaces the icon for an item (app, component, or file).
+     * Accepts PNG, WebP, or ICO images up to 512 KB.
+     * @param itemId - The item's unique identifier.
+     * @param icon - The icon image file (File in browsers, Blob in Node.js).
+     * @returns The updated item with `iconFileId` and `iconMimeType` set.
+     */
+    uploadItemIcon(itemId: string, icon: File | Blob): Promise<Item>;
+    /**
+     * Downloads the icon for an item as a binary stream.
+     * @param itemId - The item's unique identifier.
+     * @returns The raw Response (use `.blob()`, `.arrayBuffer()`, or pipe the body).
+     */
+    getItemIcon(itemId: string): Promise<Response>;
+    /**
+     * Removes the icon from an item.
+     * @param itemId - The item's unique identifier.
+     * @returns The updated item with icon fields removed.
+     */
+    removeItemIcon(itemId: string): Promise<Item>;
+    /**
+     * Renames or moves an item (file, component, or app) without creating a new version.
+     * @param itemId - The item's unique identifier.
+     * @param params - New name and/or new folder ID.
+     * @returns The updated item.
+     */
+    updateItem(itemId: string, params: {
+        name?: string;
+        folderId?: string;
+    }): Promise<Item>;
+    /**
+     * Creates a new version of an item by uploading a new file.
+     * For APP and TOOL types, `extraProps` is required by the backend.
+     * @param itemId - The item's unique identifier.
+     * @param file - The new file to upload.
+     * @param versionTag - Version tag for the new version (e.g. "v2").
+     * @param extraProps - Version-specific properties (required for APP/TOOL types).
+     * @param metadata - Optional free-JSON metadata to store on the new version.
+     * @returns The created version.
+     */
+    createVersion(itemId: string, file: File | Blob, versionTag: string, extraProps?: object, metadata?: Metadata): Promise<ItemVersion>;
+    /**
+     * Lists versions of an item. Pass `archived: true` to fetch only archived
+     * versions, `false` to fetch only active ones, or omit to receive both.
+     * @param itemId - The item's unique identifier.
+     * @param params - Optional `{ archived }` filter.
+     * @returns Array of versions, sorted by creation date descending.
+     */
+    listVersions(itemId: string, params?: {
+        archived?: boolean;
+    }): Promise<ItemVersion[]>;
+    /**
+     * Archives a version of an item. Archived versions remain available via
+     * `listVersions({ archived: true })` and can be recovered or permanently
+     * deleted. Cleanup runs daily and removes archived versions older than the
+     * platform retention period.
+     * @param itemId - The item's unique identifier.
+     * @param versionTag - The version's tag (e.g. "v2").
+     * @returns The archived version.
+     */
+    archiveVersion(itemId: string, versionTag: string): Promise<ItemVersion>;
+    /**
+     * Recovers a previously archived version, restoring it to the active list.
+     * @param itemId - The item's unique identifier.
+     * @param versionTag - The version's tag (e.g. "v2").
+     * @returns The recovered version.
+     */
+    recoverVersion(itemId: string, versionTag: string): Promise<ItemVersion>;
+    /**
+     * Permanently deletes a version, including its file in object storage.
+     * The version must be archived first; otherwise the call is rejected.
+     * @param itemId - The item's unique identifier.
+     * @param versionTag - The version's tag (e.g. "v2").
+     */
+    deleteVersion(itemId: string, versionTag: string): Promise<{
+        success: boolean;
+    }>;
+}

package/dist/core/client.test.d.ts

@@ -0,0 +1 @@
+export {};