@datalayer/core 0.0.12 → 0.0.13

package/lib/client/mixins/RuntimesMixin.js

@@ -0,0 +1,229 @@
+/*
+ * Copyright (c) 2023-2025 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 { Environment } from '../models/Environment';
+import { Runtime } from '../models/Runtime';
+import { Snapshot } from '../models/Snapshot';
+import { HealthCheck } from '../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 runtimesRunUrl = this.getRuntimesRunUrl();
+            const response = await environments.listEnvironments(token, runtimesRunUrl);
+            // Save for later use after first call
+            this.environments = response.environments.map(env => new Environment(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 runtimesRunUrl = this.getRuntimesRunUrl();
+                    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, runtimesRunUrl);
+                    return new Runtime(response.runtime, this);
+                }
+            }
+            else {
+                throw new Error('Environments not loaded');
+            }
+        }
+        /**
+         * List all runtimes.
+         * @returns Array of runtimes
+         */
+        async listRuntimes() {
+            const token = this.getToken();
+            const runtimesRunUrl = this.getRuntimesRunUrl();
+            const response = await runtimes.listRuntimes(token, runtimesRunUrl);
+            return response.runtimes.map(r => new Runtime(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 runtimesRunUrl = this.getRuntimesRunUrl();
+            const runtimeData = await runtimes.getRuntime(token, podName, runtimesRunUrl);
+            return new Runtime(runtimeData, this);
+        }
+        /**
+         * Delete a runtime permanently.
+         * @param podName - Runtime pod name
+         */
+        async deleteRuntime(podName) {
+            const token = this.getToken();
+            const runtimesRunUrl = this.getRuntimesRunUrl();
+            await runtimes.deleteRuntime(token, podName, runtimesRunUrl);
+        }
+        /**
+         * 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 runtimesRunUrl = this.getRuntimesRunUrl();
+            // List all runtimes
+            const response = await runtimes.listRuntimes(token, runtimesRunUrl);
+            // Delete all runtimes in parallel
+            const deletePromises = response.runtimes.map(runtime => runtimes.deleteRuntime(token, runtime.pod_name, runtimesRunUrl));
+            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 runtimesRunUrl = this.getRuntimesRunUrl();
+            const data = {
+                pod_name: podName,
+                name,
+                description,
+                stop,
+            };
+            const response = await snapshots.createSnapshot(token, data, runtimesRunUrl);
+            return new Snapshot(response.snapshot, this);
+        }
+        /**
+         * List all runtime snapshots.
+         * @returns Array of snapshots
+         */
+        async listSnapshots() {
+            const token = this.getToken();
+            const runtimesRunUrl = this.getRuntimesRunUrl();
+            const response = await snapshots.listSnapshots(token, runtimesRunUrl);
+            return response.snapshots.map(s => new Snapshot(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 runtimesRunUrl = this.getRuntimesRunUrl();
+            const response = await snapshots.getSnapshot(token, id, runtimesRunUrl);
+            return new Snapshot(response.snapshot, this);
+        }
+        /**
+         * Delete a snapshot permanently.
+         * @param id - Snapshot ID
+         */
+        async deleteSnapshot(id) {
+            const token = this.getToken();
+            const runtimesRunUrl = this.getRuntimesRunUrl();
+            await snapshots.deleteSnapshot(token, id, runtimesRunUrl);
+        }
+        // ========================================================================
+        // 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,111 @@
+import type { Constructor } from '../utils/mixins';
+import { Notebook } from '../models/Notebook';
+import { Lexical } from '../models/Lexical';
+import { Space } from '../models/Space';
+import { HealthCheck } from '../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<Space[]>;
+        /**
+         * 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<Space>;
+        /**
+         * 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<Notebook>;
+        /**
+         * Get a notebook by ID.
+         * @param id - Notebook ID
+         * @returns Notebook instance
+         */
+        getNotebook(id: string): Promise<Notebook>;
+        /**
+         * 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<Notebook>;
+        /**
+         * 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<Lexical>;
+        /**
+         * Get a lexical document by ID.
+         * @param id - Document ID
+         * @returns Lexical instance
+         */
+        getLexical(id: string): Promise<Lexical>;
+        /**
+         * 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<Lexical>;
+        /**
+         * 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<(Notebook | Lexical)[]>;
+        /**
+         * 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<Notebook | Lexical>;
+        /**
+         * 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>;
+    };
+} & TBase;

package/lib/client/mixins/SpacerMixin.js

@@ -0,0 +1,340 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Spacer mixin for managing workspaces, notebooks, and content.
+ * @module client/mixins/SpacerMixin
+ */
+import * as spaces from '../../api/spacer/spaces';
+import * as notebooks from '../../api/spacer/notebooks';
+import * as users from '../../api/spacer/users';
+import * as lexicals from '../../api/spacer/lexicals';
+import * as documents from '../../api/spacer/documents';
+import * as items from '../../api/spacer/items';
+import { Notebook } from '../models/Notebook';
+import { Lexical } from '../models/Lexical';
+import { Space } from '../models/Space';
+import { HealthCheck } from '../models/HealthCheck';
+import { convertSpaceItemsToModels } from '../utils/spacerUtils';
+/** Spacer mixin providing workspace and content management. */
+export function SpacerMixin(Base) {
+    return class extends Base {
+        // ========================================================================
+        // User
+        // ========================================================================
+        /**
+         * Get all workspaces for the authenticated user.
+         * @returns Array of Space instances
+         */
+        async getMySpaces() {
+            const token = this.getToken();
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const response = await users.getMySpaces(token, spacerRunUrl);
+            return response.spaces.map(s => new Space(s, this));
+        }
+        // ========================================================================
+        // Spaces
+        // ========================================================================
+        /**
+         * 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
+         */
+        async createSpace(name, description, variant, spaceHandle, organizationId, seedSpaceId, isPublic) {
+            const token = this.getToken();
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const data = {
+                name,
+                description,
+                variant,
+                spaceHandle,
+                organizationId,
+                seedSpaceId,
+                public: isPublic,
+            };
+            const response = await spaces.createSpace(token, data, spacerRunUrl);
+            if (!response.space) {
+                throw new Error('Failed to create space: no space returned');
+            }
+            return new Space(response.space, this);
+        }
+        // ========================================================================
+        // Notebooks
+        // ========================================================================
+        /**
+         * 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
+         */
+        async createNotebook(spaceId, name, description, file) {
+            // Get the Space model instance
+            const spaces = await this.getMySpaces();
+            const spaceModel = spaces.find((s) => s.uid === spaceId);
+            if (!spaceModel) {
+                throw new Error(`Space with ID '${spaceId}' not found`);
+            }
+            // Use the Space model's createNotebook method
+            return await spaceModel.createNotebook({
+                name,
+                description,
+                file,
+            });
+        }
+        /**
+         * Get a notebook by ID.
+         * @param id - Notebook ID
+         * @returns Notebook instance
+         */
+        async getNotebook(id) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await notebooks.getNotebook(token, id, spacerRunUrl);
+            if (!response.notebook) {
+                throw new Error(`Notebook with ID '${id}' not found`);
+            }
+            return new Notebook(response.notebook, this);
+        }
+        /**
+         * 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
+         */
+        async updateNotebook(id, name, description) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const data = {};
+            if (name !== undefined)
+                data.name = name;
+            if (description !== undefined)
+                data.description = description;
+            const response = await notebooks.updateNotebook(token, id, data, spacerRunUrl);
+            if (!response.notebook) {
+                throw new Error('Failed to update notebook: no notebook returned');
+            }
+            return new Notebook(response.notebook, this);
+        }
+        // ========================================================================
+        // Lexicals
+        // ========================================================================
+        /**
+         * 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
+         */
+        async createLexical(spaceId, name, description, file) {
+            // Get the Space model instance
+            const spaces = await this.getMySpaces();
+            const spaceModel = spaces.find((s) => s.uid === spaceId);
+            if (!spaceModel) {
+                throw new Error(`Space with ID '${spaceId}' not found`);
+            }
+            // Use the Space model's createLexical method
+            return await spaceModel.createLexical({
+                name,
+                description,
+                file,
+            });
+        }
+        /**
+         * Get a lexical document by ID.
+         * @param id - Document ID
+         * @returns Lexical instance
+         */
+        async getLexical(id) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await lexicals.getLexical(token, id, spacerRunUrl);
+            if (!response.document) {
+                throw new Error(`Lexical document with ID '${id}' not found`);
+            }
+            return new Lexical(response.document, this);
+        }
+        /**
+         * 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
+         */
+        async updateLexical(id, name, description) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const data = {};
+            if (name !== undefined)
+                data.name = name;
+            if (description !== undefined)
+                data.description = description;
+            const response = await lexicals.updateLexical(token, id, data, spacerRunUrl);
+            return new Lexical(response.document, this);
+        }
+        // ========================================================================
+        // Items
+        // ========================================================================
+        /**
+         * Get the items of a space as model instances.
+         * @param spaceId - Space ID
+         * @returns Array of Notebook and Lexical model instances
+         */
+        async getSpaceItems(spaceId) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await items.getSpaceItems(token, spaceId, spacerRunUrl);
+            // Use shared utility function to convert items to model instances
+            return convertSpaceItemsToModels(response.items, this);
+        }
+        /**
+         * 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
+         */
+        async getSpaceItem(itemId) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await items.getItem(token, itemId, spacerRunUrl);
+            if (!response.success || !response.item) {
+                throw new Error(`Space item '${itemId}' not found`);
+            }
+            // Determine item type and create appropriate model
+            const item = response.item;
+            if (item.type_s === 'notebook' || item.notebook_name_s !== undefined) {
+                return new Notebook(item, this);
+            }
+            else if (item.type_s === 'lexical' ||
+                item.document_name_s !== undefined) {
+                return new Lexical(item, this);
+            }
+            else {
+                throw new Error(`Unknown item type for item '${itemId}'`);
+            }
+        }
+        /**
+         * Delete an item from a space.
+         * @param itemId - Item ID to delete
+         * @throws Error if deletion fails
+         */
+        async deleteSpaceItem(itemId) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            // First, check if the item exists
+            try {
+                const getResponse = await items.getItem(token, itemId, spacerRunUrl);
+                if (!getResponse.success || !getResponse.item) {
+                    throw new Error(`Space item '${itemId}' not found`);
+                }
+            }
+            catch (error) {
+                // If getItem throws (e.g., 404), wrap in descriptive error
+                if (error.message?.includes('404') ||
+                    error.message?.includes('not found')) {
+                    throw new Error(`Failed to delete space item '${itemId}': Item not found`);
+                }
+                throw new Error(`Failed to delete space item '${itemId}': ${error.message}`);
+            }
+            // Item exists, proceed with deletion
+            const response = await items.deleteItem(token, itemId, spacerRunUrl);
+            if (!response.success) {
+                throw new Error(`Failed to delete space item '${itemId}': ${response.message}`);
+            }
+            // Success - return void
+        }
+        // ========================================================================
+        // Content Loading with CDN Support
+        // ========================================================================
+        async getContent(itemId) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            // First, get the item to check for CDN URL
+            const response = await items.getItem(token, itemId, spacerRunUrl);
+            if (!response.success || !response.item) {
+                throw new Error(`Space item '${itemId}' not found`);
+            }
+            const item = response.item;
+            const cdnUrl = item.cdn_url_s;
+            if (cdnUrl) {
+                // Load content from CDN
+                const cdnResponse = await fetch(cdnUrl);
+                if (!cdnResponse.ok) {
+                    throw new Error(`Failed to load content from CDN: ${cdnResponse.statusText}`);
+                }
+                return await cdnResponse.json();
+            }
+            // No CDN URL, return content from item
+            return item.content;
+        }
+        // ========================================================================
+        // Service Health Checks
+        // ========================================================================
+        /**
+         * 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
+         */
+        async checkSpacerHealth() {
+            const startTime = Date.now();
+            const errors = [];
+            let status = 'unknown';
+            let healthy = false;
+            try {
+                // Test basic connectivity by getting user spaces (lightweight operation)
+                const spaces = await this.getMySpaces();
+                const responseTime = Date.now() - startTime;
+                if (Array.isArray(spaces)) {
+                    healthy = true;
+                    status = 'operational';
+                }
+                else {
+                    status = 'degraded';
+                    errors.push('Unexpected response format from spaces 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);
+            }
+        }
+        /**
+         * Get collaboration session ID for a document
+         */
+        async getCollaborationSessionId(documentId) {
+            const token = this.getToken();
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const response = await documents.getCollaborationSessionId(token, documentId, spacerRunUrl);
+            if (!response.success || !response.sessionId) {
+                throw new Error(`Failed to get collaboration session ID for document '${documentId}': ${response.error || 'Unknown error'}`);
+            }
+            return response.sessionId;
+        }
+    };
+}