@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/client/SdkAgentRuntimesClient.js

@@ -13,7 +13,7 @@
  * import { AgentsMixin, SdkAgentRuntimesClient } from '@datalayer/agent-runtimes';
  *
  * const ClientWithAgents = AgentsMixin(DatalayerClient);
- * const sdk = new ClientWithAgents({ iamRunUrl, runtimesRunUrl, spacerRunUrl });
+ * const sdk = new ClientWithAgents({ iamUrl, runtimesUrl, spacerUrl });
  * const client = new SdkAgentRuntimesClient(sdk);
  * ```
  */

package/lib/client/mixins/RuntimesMixin.d.ts

@@ -0,0 +1,93 @@
+import type { Constructor } from '@datalayer/core/lib/client/utils/mixins';
+import { EnvironmentDTO } from '../../models/EnvironmentDTO';
+import { RuntimeDTO } from '../../models/RuntimeDTO';
+import { CodeSandboxSnapshotDTO } from '../../models/CodeSandboxSnapshotDTO';
+import { HealthCheck } from '@datalayer/core/lib/models/HealthCheck';
+/** Options for ensuring a runtime is available. */
+export interface EnsureRuntimeOptions {
+    /** Name of the environment to use */
+    environmentName?: string;
+    /** Maximum credits to allocate */
+    creditsLimit?: number;
+    /** Whether to wait for runtime to be ready */
+    waitForReady?: boolean;
+    /** Maximum time to wait for ready state (ms) */
+    maxWaitTime?: number;
+    /** Whether to reuse existing suitable runtime */
+    reuseExisting?: boolean;
+    /** Snapshot ID to create runtime from */
+    snapshotId?: string;
+}
+/** Runtimes mixin providing computational environment and runtime management. */
+export declare function RuntimesMixin<TBase extends Constructor>(Base: TBase): {
+    new (...args: any[]): {
+        _extractRuntimePodName(runtimePodNameOrInstance: string | RuntimeDTO): string;
+        _extractSnapshotId(snapshotIdOrInstance: string | CodeSandboxSnapshotDTO): string;
+        /**
+         * List all available computational environments.
+         * @returns Array of Environment model instances
+         */
+        listEnvironments(): Promise<EnvironmentDTO[]>;
+        /**
+         * Create a new computational runtime.
+         * @param environmentName - Name of the environment to use
+         * @param type - Type of runtime
+         * @param givenName - User-friendly name for the runtime
+         * @param creditsLimit - Credits limit
+         * @returns Created runtime
+         */
+        createRuntime(environmentName: string, type: "notebook" | "terminal" | "job", givenName: string, minutesLimit: number, fromSnapshotId?: string): Promise<RuntimeDTO>;
+        /**
+         * List all runtimes.
+         * @returns Array of runtimes
+         */
+        listRuntimes(): Promise<RuntimeDTO[]>;
+        /**
+         * Get details for a specific runtime by pod name.
+         * @param podName - Runtime pod name
+         * @returns Runtime details
+         */
+        getRuntime(podName: string): Promise<RuntimeDTO>;
+        /**
+         * Delete a runtime permanently.
+         * @param podName - Runtime pod name
+         */
+        deleteRuntime(podName: string): Promise<void>;
+        /**
+         * Terminate all runtimes.
+         * Lists all runtimes and deletes them in parallel.
+         * @returns Array of results for each deletion (fulfilled or rejected)
+         */
+        terminateAllRuntimes(): Promise<PromiseSettledResult<void>[]>;
+        /**
+         * Create a snapshot of a runtime.
+         * @param podName - Pod name of the runtime to snapshot
+         * @param name - Name for the snapshot
+         * @param description - Description of the snapshot
+         * @param stop - Whether to stop the runtime after creating snapshot (defaults to false)
+         * @returns Created snapshot
+         */
+        createSnapshot(podName: string, name: string, description: string, stop?: boolean): Promise<CodeSandboxSnapshotDTO>;
+        /**
+         * List all code sandbox snapshots.
+         * @returns Array of snapshots
+         */
+        listSnapshots(): Promise<CodeSandboxSnapshotDTO[]>;
+        /**
+         * Get details for a specific snapshot by ID.
+         * @param id - Snapshot ID
+         * @returns Snapshot details
+         */
+        getSnapshot(id: string): Promise<CodeSandboxSnapshotDTO>;
+        /**
+         * Delete a snapshot permanently.
+         * @param id - Snapshot ID
+         */
+        deleteSnapshot(id: string): Promise<void>;
+        /**
+         * Check the health status of the Runtimes service.
+         * @returns Health check result with status and response time
+         */
+        checkRuntimesHealth(): Promise<HealthCheck>;
+    };
+} & TBase;

package/lib/client/mixins/RuntimesMixin.js

@@ -0,0 +1,229 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Runtimes mixin for managing computational environments and runtime instances.
+ * @module client/mixins/RuntimesMixin
+ */
+import * as environments from '../../api/runtimes/environments';
+import * as runtimes from '../../api/runtimes/runtimes';
+import * as snapshots from '../../api/runtimes/snapshots';
+import { EnvironmentDTO } from '../../models/EnvironmentDTO';
+import { RuntimeDTO } from '../../models/RuntimeDTO';
+import { CodeSandboxSnapshotDTO } from '../../models/CodeSandboxSnapshotDTO';
+import { HealthCheck } from '@datalayer/core/lib/models/HealthCheck';
+/** Runtimes mixin providing computational environment and runtime management. */
+export function RuntimesMixin(Base) {
+    return class extends Base {
+        // ========================================================================
+        // Helper Functions
+        // ========================================================================
+        _extractRuntimePodName(runtimePodNameOrInstance) {
+            return typeof runtimePodNameOrInstance === 'string'
+                ? runtimePodNameOrInstance
+                : runtimePodNameOrInstance.podName;
+        }
+        _extractSnapshotId(snapshotIdOrInstance) {
+            return typeof snapshotIdOrInstance === 'string'
+                ? snapshotIdOrInstance
+                : snapshotIdOrInstance.uid;
+        }
+        // ========================================================================
+        // Environments
+        // ========================================================================
+        /**
+         * List all available computational environments.
+         * @returns Array of Environment model instances
+         */
+        async listEnvironments() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await environments.listEnvironments(token, runtimesUrl);
+            // Save for later use after first call
+            this.environments = response.environments.map(env => new EnvironmentDTO(env, this));
+            return this.environments;
+        }
+        // ========================================================================
+        // Runtimes
+        // ========================================================================
+        /**
+         * Create a new computational runtime.
+         * @param environmentName - Name of the environment to use
+         * @param type - Type of runtime
+         * @param givenName - User-friendly name for the runtime
+         * @param creditsLimit - Credits limit
+         * @returns Created runtime
+         */
+        async createRuntime(environmentName, type, givenName, minutesLimit, fromSnapshotId) {
+            if (!this.environments) {
+                await this.listEnvironments();
+            }
+            if (this.environments) {
+                const env = this.environments.find((e) => e.name === environmentName);
+                if (!env) {
+                    throw new Error(`Environment "${environmentName}" not found. Available environments: ${this.environments.map((e) => e.name).join(', ')}`);
+                }
+                else {
+                    const token = this.getToken();
+                    const runtimesUrl = this.getRuntimesUrl();
+                    const creditsLimit = this.calculateCreditsFromMinutes(minutesLimit, env.burningRate);
+                    const data = {
+                        environment_name: environmentName,
+                        type,
+                        given_name: givenName,
+                        credits_limit: creditsLimit,
+                        from: fromSnapshotId,
+                    };
+                    const response = await runtimes.createRuntime(token, data, runtimesUrl);
+                    return new RuntimeDTO(response.runtime, this);
+                }
+            }
+            else {
+                throw new Error('Environments not loaded');
+            }
+        }
+        /**
+         * List all runtimes.
+         * @returns Array of runtimes
+         */
+        async listRuntimes() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await runtimes.listRuntimes(token, runtimesUrl);
+            return response.runtimes.map(r => new RuntimeDTO(r, this));
+        }
+        /**
+         * Get details for a specific runtime by pod name.
+         * @param podName - Runtime pod name
+         * @returns Runtime details
+         */
+        async getRuntime(podName) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const runtimeData = await runtimes.getRuntime(token, podName, runtimesUrl);
+            return new RuntimeDTO(runtimeData, this);
+        }
+        /**
+         * Delete a runtime permanently.
+         * @param podName - Runtime pod name
+         */
+        async deleteRuntime(podName) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            await runtimes.deleteRuntime(token, podName, runtimesUrl);
+        }
+        /**
+         * Terminate all runtimes.
+         * Lists all runtimes and deletes them in parallel.
+         * @returns Array of results for each deletion (fulfilled or rejected)
+         */
+        async terminateAllRuntimes() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            // List all runtimes
+            const response = await runtimes.listRuntimes(token, runtimesUrl);
+            // Delete all runtimes in parallel
+            const deletePromises = response.runtimes.map(runtime => runtimes.deleteRuntime(token, runtime.pod_name, runtimesUrl));
+            return Promise.allSettled(deletePromises);
+        }
+        // ========================================================================
+        // Snapshots
+        // ========================================================================
+        /**
+         * Create a snapshot of a runtime.
+         * @param podName - Pod name of the runtime to snapshot
+         * @param name - Name for the snapshot
+         * @param description - Description of the snapshot
+         * @param stop - Whether to stop the runtime after creating snapshot (defaults to false)
+         * @returns Created snapshot
+         */
+        async createSnapshot(podName, name, description, stop = false) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const data = {
+                pod_name: podName,
+                name,
+                description,
+                stop,
+            };
+            const response = await snapshots.createSnapshot(token, data, runtimesUrl);
+            return new CodeSandboxSnapshotDTO(response.snapshot, this);
+        }
+        /**
+         * List all code sandbox snapshots.
+         * @returns Array of snapshots
+         */
+        async listSnapshots() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await snapshots.listSnapshots(token, runtimesUrl);
+            return response.snapshots.map(s => new CodeSandboxSnapshotDTO(s, this));
+        }
+        /**
+         * Get details for a specific snapshot by ID.
+         * @param id - Snapshot ID
+         * @returns Snapshot details
+         */
+        async getSnapshot(id) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await snapshots.getSnapshot(token, id, runtimesUrl);
+            return new CodeSandboxSnapshotDTO(response.snapshot, this);
+        }
+        /**
+         * Delete a snapshot permanently.
+         * @param id - Snapshot ID
+         */
+        async deleteSnapshot(id) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            await snapshots.deleteSnapshot(token, id, runtimesUrl);
+        }
+        // ========================================================================
+        // Service Health Checks
+        // ========================================================================
+        /**
+         * Check the health status of the Runtimes service.
+         * @returns Health check result with status and response time
+         */
+        async checkRuntimesHealth() {
+            const startTime = Date.now();
+            const errors = [];
+            let status = 'unknown';
+            let healthy = false;
+            try {
+                // Test basic connectivity by listing environments (lightweight operation)
+                const environments = await this.listEnvironments();
+                const responseTime = Date.now() - startTime;
+                if (Array.isArray(environments)) {
+                    healthy = true;
+                    status = 'operational';
+                }
+                else {
+                    status = 'degraded';
+                    errors.push('Unexpected response format from environments endpoint');
+                }
+                return new HealthCheck({
+                    healthy,
+                    status,
+                    responseTime,
+                    errors,
+                    timestamp: new Date(),
+                }, this);
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                status = 'down';
+                errors.push(`Service unreachable: ${error}`);
+                return new HealthCheck({
+                    healthy: false,
+                    status,
+                    responseTime,
+                    errors,
+                    timestamp: new Date(),
+                }, this);
+            }
+        }
+    };
+}

package/lib/client/mixins/SpacerMixin.d.ts

@@ -0,0 +1,210 @@
+import type { UpdateSpaceRequest } from '../../models/SpaceDTO';
+import type { Constructor } from '@datalayer/core/lib/client/utils/mixins';
+import { NotebookDTO } from '../../models/NotebookDTO';
+import { LexicalDTO } from '../../models/LexicalDTO';
+import { SpaceDTO } from '../../models/SpaceDTO';
+import { ProjectDTO, type ProjectDefaultItems } from '../../models/ProjectDTO';
+import { HealthCheck } from '@datalayer/core/lib/models/HealthCheck';
+/** Options for content loading with CDN support. */
+export interface ContentLoadingOptions {
+    /** Whether to try CDN first before API (default: true) */
+    preferCDN?: boolean;
+    /** CDN base URL (default: https://cdn.datalayer.run) */
+    cdnBaseUrl?: string;
+}
+/** Spacer mixin providing workspace and content management. */
+export declare function SpacerMixin<TBase extends Constructor>(Base: TBase): {
+    new (...args: any[]): {
+        /**
+         * Get all workspaces for the authenticated user.
+         * @returns Array of Space instances
+         */
+        getMySpaces(): Promise<SpaceDTO[]>;
+        /**
+         * Create a new workspace.
+         * @param name - Space name
+         * @param description - Space description
+         * @param variant - Space variant type
+         * @param spaceHandle - Unique handle for the space
+         * @param organizationId - Organization ID
+         * @param seedSpaceId - Seed space ID for initialization
+         * @param isPublic - Whether the space is public
+         * @returns Created Space instance
+         */
+        createSpace(name: string, description: string, variant: string, spaceHandle: string, organizationId: string, seedSpaceId: string, isPublic: boolean): Promise<SpaceDTO>;
+        /**
+         * Create a new notebook.
+         * @param spaceId - ID of the space to create the notebook in
+         * @param name - Name of the notebook
+         * @param description - Description of the notebook
+         * @param file - Optional file for notebook content
+         * @returns Created Notebook instance
+         */
+        createNotebook(spaceId: string, name: string, description: string, file?: File | Blob): Promise<NotebookDTO>;
+        /**
+         * Get a notebook by ID.
+         * @param id - Notebook ID
+         * @returns Notebook instance
+         */
+        getNotebook(id: string): Promise<NotebookDTO>;
+        /**
+         * Update a notebook.
+         * @param id - Notebook ID
+         * @param name - Optional new name for the notebook
+         * @param description - Optional new description for the notebook
+         * @returns Updated Notebook instance
+         */
+        updateNotebook(id: string, name?: string, description?: string): Promise<NotebookDTO>;
+        /**
+         * Create a new lexical document.
+         * @param spaceId - ID of the space to create the lexical document in
+         * @param name - Name of the lexical document
+         * @param description - Description of the lexical document
+         * @param file - Optional file for document content
+         * @returns Created Lexical instance
+         */
+        createLexical(spaceId: string, name: string, description: string, file?: File | Blob): Promise<LexicalDTO>;
+        /**
+         * Get a lexical document by ID.
+         * @param id - Document ID
+         * @returns Lexical instance
+         */
+        getLexical(id: string): Promise<LexicalDTO>;
+        /**
+         * Update a lexical document.
+         * @param id - Document ID
+         * @param name - Optional new name for the lexical document
+         * @param description - Optional new description for the lexical document
+         * @returns Updated Lexical instance
+         */
+        updateLexical(id: string, name?: string, description?: string): Promise<LexicalDTO>;
+        /**
+         * Get the items of a space as model instances.
+         * @param spaceId - Space ID
+         * @returns Array of Notebook and Lexical model instances
+         */
+        getSpaceItems(spaceId: string): Promise<(NotebookDTO | LexicalDTO)[]>;
+        /**
+         * Get a single item from a space.
+         * @param itemId - Item ID to retrieve
+         * @returns Notebook or Lexical model instance
+         * @throws Error if item not found
+         */
+        getSpaceItem(itemId: string): Promise<NotebookDTO | LexicalDTO>;
+        /**
+         * Delete an item from a space.
+         * @param itemId - Item ID to delete
+         * @throws Error if deletion fails
+         */
+        deleteSpaceItem(itemId: string): Promise<void>;
+        getContent(itemId: string): Promise<any>;
+        /**
+         * Check the health status of the Spacer service.
+         * Performs a lightweight check to verify service accessibility.
+         *
+         * @returns Health check result with status and response time
+         */
+        checkSpacerHealth(): Promise<HealthCheck>;
+        /**
+         * Get collaboration session ID for a document
+         */
+        getCollaborationSessionId(documentId: string): Promise<string>;
+        /**
+         * Get a space by UID.
+         * @param uid - Space UID
+         * @returns Space instance
+         */
+        getSpace(uid: string): Promise<SpaceDTO>;
+        /**
+         * Update a space (owner updating their own space).
+         * @param uid - Space UID
+         * @param data - Update data (supports arbitrary Solr fields)
+         * @returns Updated Space instance
+         */
+        updateSpace(uid: string, data: UpdateSpaceRequest): Promise<SpaceDTO>;
+        /**
+         * Update a user-specific space (e.g., org admin context).
+         * @param uid - Space UID
+         * @param userId - User ID
+         * @param data - Update data (supports arbitrary Solr fields)
+         * @returns Updated Space instance
+         */
+        updateUserSpace(uid: string, userId: string, data: UpdateSpaceRequest): Promise<SpaceDTO>;
+        /**
+         * Delete a space and all its contents.
+         * @param uid - Space UID
+         */
+        deleteSpace(uid: string): Promise<void>;
+        /**
+         * Make a space public.
+         * @param uid - Space UID
+         * @returns Updated Space instance
+         */
+        makeSpacePublic(uid: string): Promise<SpaceDTO>;
+        /**
+         * Make a space private.
+         * @param uid - Space UID
+         * @returns Updated Space instance
+         */
+        makeSpacePrivate(uid: string): Promise<SpaceDTO>;
+        /**
+         * Export a space and its contents.
+         * @param uid - Space UID
+         * @returns Export data
+         */
+        exportSpace(uid: string): Promise<any>;
+        /**
+         * Clone a notebook.
+         * @param id - Notebook ID to clone
+         * @returns Cloned Notebook instance
+         */
+        cloneNotebook(id: string): Promise<NotebookDTO>;
+        /**
+         * Clone a lexical document.
+         * @param id - Document ID to clone
+         * @returns Cloned Lexical instance
+         */
+        cloneLexical(id: string): Promise<LexicalDTO>;
+        /**
+         * Get all projects for the authenticated user.
+         * Projects are spaces with variant='project'.
+         * @returns Array of Project instances
+         */
+        getProjects(): Promise<ProjectDTO[]>;
+        /**
+         * Get a project by UID.
+         * @param uid - Project UID
+         * @returns Project instance
+         */
+        getProject(uid: string): Promise<ProjectDTO>;
+        /**
+         * Create a new project.
+         * @param name - Project name
+         * @param description - Project description
+         * @returns Created Project instance
+         */
+        createProject(name: string, description?: string): Promise<ProjectDTO>;
+        /**
+         * Update a project.
+         * @param uid - Project UID
+         * @param data - Update data (supports arbitrary Solr fields)
+         * @returns Updated Project instance
+         */
+        updateProject(uid: string, data: UpdateSpaceRequest): Promise<ProjectDTO>;
+        /**
+         * Rename a project.
+         * @param uid - Project UID
+         * @param newName - New project name
+         * @param description - Project description to preserve.
+         * @param userId - Authenticated user ID for user-scoped update.
+         * @returns Updated Project instance
+         */
+        renameProject(uid: string, newName: string, description?: string): Promise<ProjectDTO>;
+        /**
+         * Get default items (notebook UID and document UID) for a project.
+         * @param uid - Project UID
+         * @returns Default notebook and document UIDs
+         */
+        getProjectDefaultItems(uid: string): Promise<ProjectDefaultItems>;
+    };
+} & TBase;