@datalayer/core 0.0.9 → 0.0.11

package/lib/sdk/client/models/Notebook.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @module sdk/client/models/Notebook
+ * @description Notebook domain model for the Datalayer SDK.
+ *
+ * This model provides a rich, object-oriented interface for working with
+ * Jupyter notebooks, including content management and lifecycle operations.
+ */
+import type { Notebook as NotebookData, UpdateNotebookRequest } from '../../../api/types/spacer';
+import type { DatalayerSDK } from '../index';
+/**
+ * Notebook domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing Jupyter notebooks
+ * with automatic data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const formData = new FormData();
+ * formData.append('spaceId', 'space-123');
+ * formData.append('name', 'Data Analysis');
+ * const notebook = await sdk.createNotebook(formData);
+ *
+ * // Static properties - instant access
+ * console.log(notebook.id);
+ * console.log(notebook.spaceId);
+ *
+ * // Dynamic data - always fresh from API
+ * const currentName = await notebook.getName();
+ * const content = await notebook.getContent();
+ *
+ * // Update notebook
+ * const updated = await notebook.update({ name: 'New Analysis' });
+ * ```
+ */
+export declare class Notebook {
+    protected _data: NotebookData;
+    private _sdk;
+    private _deleted;
+    private _freshData;
+    private _lastFetch;
+    private _cacheTimeout;
+    /**
+     * Create a Notebook instance.
+     *
+     * @param data - Raw notebook data from API
+     * @param sdk - DatalayerSDK instance for making API calls
+     */
+    constructor(data: NotebookData, sdk: DatalayerSDK);
+    /**
+     * Check if this notebook has been deleted.
+     */
+    get isDeleted(): boolean;
+    /**
+     * Check if this notebook has been deleted and throw error if so.
+     * @throws Error if the notebook has been deleted
+     */
+    private _checkDeleted;
+    /**
+     * Get fresh data from API with caching to avoid redundant calls.
+     * @returns Current NotebookData from API or cache
+     */
+    private _getFreshData;
+    /**
+     * Notebook ID.
+     */
+    get id(): string;
+    /**
+     * Unique identifier for the notebook.
+     */
+    get uid(): string;
+    /**
+     * File path within the space.
+     */
+    get path(): string;
+    /**
+     * Parent space ID.
+     */
+    get spaceId(): string;
+    /**
+     * Owner user ID.
+     */
+    get ownerId(): string;
+    /**
+     * When the notebook was created.
+     */
+    get createdAt(): Date;
+    /**
+     * Version number.
+     */
+    get version(): number;
+    /**
+     * Notebook metadata.
+     */
+    get metadata(): Record<string, any>;
+    /**
+     * Get the current name of the notebook.
+     *
+     * This method fetches fresh data from the API (with caching) and updates
+     * the internal data to keep everything in sync.
+     *
+     * @returns Promise resolving to current notebook name
+     * @throws Error if the notebook has been deleted
+     */
+    getName(): Promise<string>;
+    /**
+     * Get the notebook content (cells, etc.).
+     *
+     * @returns Promise resolving to notebook content
+     */
+    getContent(): Promise<any>;
+    /**
+     * Get the kernel specification.
+     *
+     * @returns Promise resolving to kernel spec
+     */
+    getKernelSpec(): Promise<any>;
+    /**
+     * Get when the notebook was last updated.
+     *
+     * @returns Promise resolving to last update time
+     */
+    getUpdatedAt(): Promise<Date>;
+    /**
+     * Update the notebook name and/or description.
+     *
+     * @param data - Update data containing name and/or description
+     * @returns Promise resolving to updated Notebook instance
+     *
+     * @example
+     * ```typescript
+     * const updated = await notebook.update({
+     *   name: 'Advanced Analysis',
+     *   description: 'Updated analysis notebook'
+     * });
+     * ```
+     */
+    update(data: UpdateNotebookRequest): Promise<Notebook>;
+    /**
+     * Delete this notebook permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await notebook.delete();
+     * console.log('Notebook deleted');
+     * // notebook.getName() will now throw an error
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Get raw notebook data object with latest information.
+     *
+     * This method ensures the returned data includes the most recent information
+     * by refreshing from the API before returning.
+     *
+     * @returns Promise resolving to raw notebook data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await notebook.toJSON();
+     * console.log('Current name:', latestData.name);
+     * ```
+     */
+    toJSON(): Promise<NotebookData>;
+    /**
+     * String representation of the notebook.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString(): string;
+}
+export type { NotebookData };

package/lib/sdk/client/models/Notebook.js

@@ -0,0 +1,311 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { notebooks } from '../../../api/spacer';
+import { items } from '../../../api/spacer';
+/**
+ * Notebook domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing Jupyter notebooks
+ * with automatic data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const formData = new FormData();
+ * formData.append('spaceId', 'space-123');
+ * formData.append('name', 'Data Analysis');
+ * const notebook = await sdk.createNotebook(formData);
+ *
+ * // Static properties - instant access
+ * console.log(notebook.id);
+ * console.log(notebook.spaceId);
+ *
+ * // Dynamic data - always fresh from API
+ * const currentName = await notebook.getName();
+ * const content = await notebook.getContent();
+ *
+ * // Update notebook
+ * const updated = await notebook.update({ name: 'New Analysis' });
+ * ```
+ */
+export class Notebook {
+    _data;
+    _sdk;
+    _deleted = false;
+    _freshData = null;
+    _lastFetch = 0;
+    _cacheTimeout = 5000; // 5 seconds cache timeout
+    /**
+     * Create a Notebook instance.
+     *
+     * @param data - Raw notebook data from API
+     * @param sdk - DatalayerSDK instance for making API calls
+     */
+    constructor(data, sdk) {
+        this._data = data;
+        this._sdk = sdk;
+    }
+    // ========================================================================
+    // Deletion State
+    // ========================================================================
+    /**
+     * Check if this notebook has been deleted.
+     */
+    get isDeleted() {
+        return this._deleted;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this notebook has been deleted and throw error if so.
+     * @throws Error if the notebook has been deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Notebook ${this._data.id} has been deleted and no longer exists`);
+        }
+    }
+    /**
+     * Get fresh data from API with caching to avoid redundant calls.
+     * @returns Current NotebookData from API or cache
+     */
+    async _getFreshData() {
+        this._checkDeleted();
+        const now = Date.now();
+        if (this._freshData && now - this._lastFetch < this._cacheTimeout) {
+            // Return cached data if recent enough
+            return this._freshData;
+        }
+        // Fetch fresh data from API
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const response = await notebooks.getNotebook(token, this.uid, spacerRunUrl);
+        if (response.notebook) {
+            this._freshData = response.notebook;
+            this._data = response.notebook; // Keep internal data up to date
+            this._lastFetch = now;
+            return this._freshData;
+        }
+        return this._data; // Fallback to existing data
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /**
+     * Notebook ID.
+     */
+    get id() {
+        this._checkDeleted();
+        return this._data.id;
+    }
+    /**
+     * Unique identifier for the notebook.
+     */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /**
+     * File path within the space.
+     */
+    get path() {
+        this._checkDeleted();
+        return this._data.path || '';
+    }
+    /**
+     * Parent space ID.
+     */
+    get spaceId() {
+        this._checkDeleted();
+        // Try the direct field first (if API provides it)
+        if (this._data.space_id) {
+            return this._data.space_id;
+        }
+        // Extract from s3_path_s if available: "datalayer.app/SPACE_ID/nbformat/..."
+        const s3Path = this._data.s3_path_s;
+        if (s3Path && typeof s3Path === 'string') {
+            const match = s3Path.match(/^datalayer\.app\/([^/]+)\//);
+            if (match) {
+                return match[1];
+            }
+        }
+        // Fallback to empty string if no space ID can be determined
+        return '';
+    }
+    /**
+     * Owner user ID.
+     */
+    get ownerId() {
+        this._checkDeleted();
+        return this._data.owner_id || this._data.creator_uid || '';
+    }
+    /**
+     * When the notebook was created.
+     */
+    get createdAt() {
+        this._checkDeleted();
+        const dateStr = this._data.creation_ts_dt || this._data.created_at;
+        if (!dateStr) {
+            throw new Error('No creation timestamp available for notebook');
+        }
+        return new Date(dateStr);
+    }
+    /**
+     * Version number.
+     */
+    get version() {
+        this._checkDeleted();
+        return this._data.version || 0;
+    }
+    /**
+     * Notebook metadata.
+     */
+    get metadata() {
+        this._checkDeleted();
+        return this._data.metadata || {};
+    }
+    // ========================================================================
+    // Dynamic Methods (always fetch fresh data and update internal state)
+    // ========================================================================
+    /**
+     * Get the current name of the notebook.
+     *
+     * This method fetches fresh data from the API (with caching) and updates
+     * the internal data to keep everything in sync.
+     *
+     * @returns Promise resolving to current notebook name
+     * @throws Error if the notebook has been deleted
+     */
+    async getName() {
+        const freshData = await this._getFreshData();
+        return (freshData.name_t ||
+            freshData.notebook_name_s ||
+            freshData.name ||
+            '');
+    }
+    /**
+     * Get the notebook content (cells, etc.).
+     *
+     * @returns Promise resolving to notebook content
+     */
+    async getContent() {
+        const freshData = await this._getFreshData();
+        // Try to parse model_s if content is not available
+        if (!freshData.content && freshData.model_s) {
+            try {
+                return JSON.parse(freshData.model_s);
+            }
+            catch {
+                // Fall back to raw model_s if parsing fails
+                return freshData.model_s;
+            }
+        }
+        return freshData.content;
+    }
+    /**
+     * Get the kernel specification.
+     *
+     * @returns Promise resolving to kernel spec
+     */
+    async getKernelSpec() {
+        const freshData = await this._getFreshData();
+        return freshData.kernel_spec;
+    }
+    /**
+     * Get when the notebook was last updated.
+     *
+     * @returns Promise resolving to last update time
+     */
+    async getUpdatedAt() {
+        const freshData = await this._getFreshData();
+        const dateStr = freshData.last_update_ts_dt ||
+            freshData.updated_at ||
+            freshData.creation_ts_dt ||
+            freshData.created_at;
+        if (!dateStr) {
+            throw new Error('No timestamp available for notebook');
+        }
+        return new Date(dateStr);
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Update the notebook name and/or description.
+     *
+     * @param data - Update data containing name and/or description
+     * @returns Promise resolving to updated Notebook instance
+     *
+     * @example
+     * ```typescript
+     * const updated = await notebook.update({
+     *   name: 'Advanced Analysis',
+     *   description: 'Updated analysis notebook'
+     * });
+     * ```
+     */
+    async update(data) {
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const response = await notebooks.updateNotebook(token, this.uid, data, spacerRunUrl);
+        return new Notebook(response.notebook, this._sdk);
+    }
+    /**
+     * Delete this notebook permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await notebook.delete();
+     * console.log('Notebook deleted');
+     * // notebook.getName() will now throw an error
+     * ```
+     */
+    async delete() {
+        this._checkDeleted(); // Add check to prevent double deletion
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        await items.deleteItem(token, this.uid, spacerRunUrl);
+        this._deleted = true;
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get raw notebook data object with latest information.
+     *
+     * This method ensures the returned data includes the most recent information
+     * by refreshing from the API before returning.
+     *
+     * @returns Promise resolving to raw notebook data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await notebook.toJSON();
+     * console.log('Current name:', latestData.name);
+     * ```
+     */
+    async toJSON() {
+        this._checkDeleted();
+        await this.getName(); // This updates internal data
+        return this._data;
+    }
+    /**
+     * String representation of the notebook.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString() {
+        this._checkDeleted();
+        const name = this._data.name_t ||
+            this._data.notebook_name_s ||
+            this._data.name ||
+            'Unnamed';
+        return `Notebook(${this.id}, ${name})`;
+    }
+}

package/lib/sdk/client/models/Runtime.d.ts

@@ -0,0 +1,221 @@
+import type { Runtime as RuntimeData } from '../../../api/types/runtimes';
+import type { DatalayerSDK } from '../index';
+import { Snapshot } from './Snapshot';
+/**
+ * Runtime domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing computational runtimes
+ * with automatic state refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await sdk.createRuntime({
+ *   environment_name: 'python-cpu'
+ * });
+ *
+ * // Static properties - instant access
+ * console.log(runtime.podName);
+ * console.log(runtime.jupyterUrl);
+ *
+ * // Dynamic state - always fresh from API
+ * if (await runtime.isRunning()) {
+ *   console.log('Runtime is ready!');
+ * }
+ *
+ * // Wait for runtime to be ready
+ * await runtime.waitUntilReady();
+ *
+ * // Create snapshot
+ * const snapshot = await runtime.createSnapshot('my-snapshot');
+ * ```
+ */
+export declare class Runtime {
+    protected _data: RuntimeData;
+    private _sdk;
+    private _deleted;
+    /**
+     * Create a Runtime instance.
+     *
+     * @param data - Raw runtime data from API
+     * @param sdk - DatalayerSDK instance for making API calls
+     */
+    constructor(data: RuntimeData, sdk: DatalayerSDK);
+    /**
+     * Check if this runtime has been deleted and throw error if so.
+     * @throws Error if the runtime has been deleted
+     */
+    private _checkDeleted;
+    /**
+     * Kubernetes pod name for the runtime instance.
+     */
+    get podName(): string;
+    /**
+     * Unique identifier for the runtime.
+     */
+    get uid(): string;
+    /**
+     * Name of the environment this runtime is based on.
+     */
+    get environmentName(): string;
+    /**
+     * URL for accessing Jupyter server.
+     */
+    get jupyterUrl(): string;
+    /**
+     * Token for Jupyter server authentication.
+     */
+    get jupyterToken(): string;
+    /**
+     * Credits consumed per hour.
+     */
+    get burningRate(): number;
+    /**
+     * User-friendly name for the runtime.
+     */
+    get givenName(): string;
+    /**
+     * Type of runtime (notebook, terminal, or job).
+     */
+    get type(): string;
+    /**
+     * When the runtime was created.
+     */
+    get createdAt(): Date;
+    /**
+     * When the runtime started.
+     */
+    get startedAt(): Date;
+    /**
+     * When the runtime will expire.
+     */
+    get expiredAt(): Date;
+    /**
+     * Get the current state of the runtime.
+     *
+     * This method always fetches fresh data from the API and updates
+     * the internal data to keep everything in sync.
+     *
+     * @returns Promise resolving to current runtime state
+     * @throws Error if the runtime has been deleted
+     */
+    getState(): Promise<string>;
+    /**
+     * Check if runtime is in running state.
+     *
+     * @returns Promise resolving to true if runtime is running
+     *
+     * @example
+     * ```typescript
+     * if (await runtime.isRunning()) {
+     *   console.log('Runtime is ready for use');
+     * }
+     * ```
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Check if runtime is in starting state.
+     *
+     * @returns Promise resolving to true if runtime is starting
+     */
+    isStarting(): Promise<boolean>;
+    /**
+     * Check if runtime is in stopping state.
+     *
+     * @returns Promise resolving to true if runtime is stopping
+     */
+    isStopping(): Promise<boolean>;
+    /**
+     * Check if runtime is in stopped state.
+     *
+     * @returns Promise resolving to true if runtime is stopped
+     */
+    isStopped(): Promise<boolean>;
+    /**
+     * Check if runtime is in error state.
+     *
+     * @returns Promise resolving to true if runtime has error
+     */
+    hasError(): Promise<boolean>;
+    /**
+     * Delete this runtime permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await runtime.delete();
+     * console.log('Runtime deleted');
+     * // runtime.getState() will now throw an error
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Update runtime from a snapshot.
+     *
+     * @param from - Snapshot identifier to restore from
+     * @returns Promise resolving to updated Runtime instance
+     *
+     * @example
+     * ```typescript
+     * const updatedRuntime = await runtime.update('snapshot-uid');
+     * ```
+     */
+    update(from: string): Promise<Runtime>;
+    /**
+     * Create a snapshot of this runtime.
+     *
+     * @param name - Name for the snapshot
+     * @param description - Optional description for the snapshot
+     * @param stop - Whether to stop the runtime after snapshotting
+     * @returns Promise resolving to created Snapshot instance
+     *
+     * @example
+     * ```typescript
+     * const snapshot = await runtime.createSnapshot(
+     *   'my-checkpoint',
+     *   'Before major changes'
+     * );
+     * ```
+     */
+    createSnapshot(name: string, description?: string, stop?: boolean): Promise<Snapshot>;
+    /**
+     * Wait for runtime to reach running state.
+     *
+     * Polls the runtime state until it becomes 'running' or throws on error/timeout.
+     *
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 60000)
+     * @returns Promise resolving to this Runtime instance when ready
+     * @throws Error if runtime enters error state or timeout is reached
+     *
+     * @example
+     * ```typescript
+     * const runtime = await sdk.createRuntime(config);
+     * await runtime.waitUntilReady();
+     * console.log('Runtime is ready to use!');
+     * ```
+     */
+    waitUntilReady(timeoutMs?: number): Promise<Runtime>;
+    /**
+     * Get raw runtime data object with latest state.
+     *
+     * This method ensures the returned data includes the most recent state
+     * by refreshing from the API before returning.
+     *
+     * @returns Promise resolving to raw runtime data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await runtime.toJSON();
+     * console.log('Current state:', latestData.state);
+     * ```
+     */
+    toJSON(): Promise<RuntimeData>;
+    /**
+     * String representation of the runtime.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString(): string;
+}
+export type { RuntimeData };