@datalayer/core 0.0.12 → 0.0.13

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

@@ -0,0 +1,122 @@
+import type { Runtime as RuntimeData } from '../../api/types/runtimes';
+import type { DatalayerClient } from '../index';
+import { Snapshot } from './Snapshot';
+/**
+ * Stable public interface for Runtime data.
+ * This is the contract that SDK consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface RuntimeJSON {
+    /** ulid for the runtime */
+    uid: string;
+    /** Kubernetes pod name for the runtime instance */
+    podName: string;
+    /** User-friendly name for the runtime */
+    givenName: string;
+    /** Name of the environment this runtime is based on */
+    environmentName: string;
+    /** Title of the environment for display */
+    environmentTitle: string;
+    /** Type of runtime - notebook, terminal, or job */
+    type: string;
+    /** Credits consumed per second */
+    burningRate: number;
+    /** Credits allocated/available to this runtime */
+    ingress: string;
+    /** Authentication token for accessing the runtime */
+    token: string;
+    /** When the runtime was started */
+    startedAt: string;
+    /** When the runtime will expire */
+    expiredAt: string;
+}
+/**
+ * Runtime domain model that wraps API responses with convenient methods.
+ * Provides state management and lifecycle operations for computational runtimes.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await sdk.createRuntime({ environment_name: 'python-cpu' });
+ * await runtime.waitUntilReady();
+ * ```
+ */
+export declare class Runtime {
+    /** @internal */
+    _data: RuntimeData;
+    private _sdk;
+    private _deleted;
+    /**
+     * Create a Runtime instance.
+     *
+     * @param data - Runtime data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: RuntimeData, sdk: DatalayerClient);
+    /**
+     * Check if this runtime has been deleted and throw error if so.
+     * @throws Error if 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;
+    /** Ingress URL for accessing the runtime. */
+    get ingress(): string;
+    /** Authentication token for accessing the runtime. */
+    get token(): string;
+    /** Credits consumed per second. */
+    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 started. */
+    get startedAt(): Date;
+    /** When the runtime will expire. */
+    get expiredAt(): Date;
+    /** Environment title for display. */
+    get environmentTitle(): string;
+    /**
+     * Delete this runtime permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    delete(): Promise<void>;
+    /**
+     * Update runtime from a snapshot.
+     *
+     * @param from - Snapshot identifier to restore from
+     * @returns Updated Runtime instance
+     */
+    update(from: string): Promise<Runtime>;
+    /**
+     * Create a snapshot of this runtime.
+     *
+     * @param name - Name for the snapshot
+     * @param description - Optional description
+     * @param stop - Whether to stop runtime after snapshotting
+     * @returns Created Snapshot instance
+     */
+    createSnapshot(name: string, description?: string, stop?: boolean): Promise<Snapshot>;
+    /**
+     * Get runtime data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Core runtime data with camelCase properties
+     */
+    toJSON(): RuntimeJSON;
+    /**
+     * Get the raw runtime data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Raw runtime data from API
+     */
+    rawData(): RuntimeData;
+    /** String representation of the runtime. */
+    toString(): string;
+}

package/lib/client/models/Runtime.js

@@ -0,0 +1,204 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Runtime domain model for the Datalayer SDK.
+ *
+ * @module client/models/Runtime
+ */
+import { updateRuntime } from '../../api/runtimes/runtimes';
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * Runtime domain model that wraps API responses with convenient methods.
+ * Provides state management and lifecycle operations for computational runtimes.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await sdk.createRuntime({ environment_name: 'python-cpu' });
+ * await runtime.waitUntilReady();
+ * ```
+ */
+export class Runtime {
+    /** @internal */
+    _data;
+    _sdk;
+    _deleted = false;
+    /**
+     * Create a Runtime instance.
+     *
+     * @param data - Runtime data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data, sdk) {
+        this._data = data;
+        this._sdk = sdk;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this runtime has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Runtime ${this._data.pod_name} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Kubernetes pod name for the runtime instance. */
+    get podName() {
+        this._checkDeleted();
+        return this._data.pod_name;
+    }
+    /** Unique identifier for the runtime. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** Name of the environment this runtime is based on. */
+    get environmentName() {
+        this._checkDeleted();
+        return this._data.environment_name;
+    }
+    /** Ingress URL for accessing the runtime. */
+    get ingress() {
+        this._checkDeleted();
+        return this._data.ingress;
+    }
+    /** Authentication token for accessing the runtime. */
+    get token() {
+        this._checkDeleted();
+        return this._data.token;
+    }
+    /** Credits consumed per second. */
+    get burningRate() {
+        this._checkDeleted();
+        return this._data.burning_rate;
+    }
+    /** User-friendly name for the runtime. */
+    get givenName() {
+        this._checkDeleted();
+        return this._data.given_name;
+    }
+    /** Type of runtime (notebook, terminal, or job). */
+    get type() {
+        this._checkDeleted();
+        return this._data.type;
+    }
+    /** When the runtime started. */
+    get startedAt() {
+        this._checkDeleted();
+        return new Date(Number(this._data.started_at) * 1000);
+    }
+    /** When the runtime will expire. */
+    get expiredAt() {
+        this._checkDeleted();
+        return new Date(Number(this._data.expired_at) * 1000);
+    }
+    /** Environment title for display. */
+    get environmentTitle() {
+        this._checkDeleted();
+        return this._data.environment_title || '';
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this runtime permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    async delete() {
+        await this._sdk.deleteRuntime(this.podName);
+        this._deleted = true;
+    }
+    /**
+     * Update runtime from a snapshot.
+     *
+     * @param from - Snapshot identifier to restore from
+     * @returns Updated Runtime instance
+     */
+    async update(from) {
+        this._checkDeleted();
+        const updated = await updateRuntime(this._sdk.getToken(), this.podName, from, this._sdk.getRuntimesRunUrl());
+        return new Runtime(updated, this._sdk);
+    }
+    /**
+     * Create a snapshot of this runtime.
+     *
+     * @param name - Name for the snapshot
+     * @param description - Optional description
+     * @param stop - Whether to stop runtime after snapshotting
+     * @returns Created Snapshot instance
+     */
+    async createSnapshot(name, description, stop) {
+        this._checkDeleted();
+        return await this._sdk.createSnapshot(this.podName, name, description, stop);
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get runtime data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Core runtime data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        // Safely convert dates to ISO strings, handling invalid dates
+        const safeToISO = (date) => {
+            try {
+                const iso = date.toISOString();
+                return iso;
+            }
+            catch {
+                // If date is invalid, return empty string or current time
+                return new Date().toISOString();
+            }
+        };
+        const obj = {
+            // Core identifiers
+            uid: this.uid,
+            podName: this.podName,
+            givenName: this.givenName,
+            // Environment info
+            environmentName: this.environmentName,
+            environmentTitle: this.environmentTitle,
+            // State and type
+            type: this.type,
+            // Burning
+            burningRate: this.burningRate,
+            // URLs and tokens
+            // FIXME: Consider renaming? jupyterServerUrl and jupyterServerToken
+            ingress: this.ingress,
+            token: this.token,
+            // Timing
+            startedAt: safeToISO(this.startedAt),
+            expiredAt: safeToISO(this.expiredAt),
+        };
+        validateJSON(obj, 'Runtime');
+        return obj;
+    }
+    /**
+     * Get the raw runtime data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Raw runtime data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the runtime. */
+    toString() {
+        this._checkDeleted();
+        return `Runtime(${this.podName}, ${this.environmentName})`;
+    }
+}

package/lib/client/models/Snapshot.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Snapshot domain model for the Datalayer SDK.
+ *
+ * @module client/models/Snapshot
+ */
+import type { RuntimeSnapshot as RuntimeSnapshotData } from '../../api/types/runtimes';
+import type { DatalayerClient } from '../index';
+import { Runtime } from './Runtime';
+/**
+ * Stable public interface for Snapshot data.
+ * This is the contract that SDK consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface SnapshotJSON {
+    /** Unique identifier for the snapshot */
+    uid: string;
+    /** Name of the snapshot */
+    name: string;
+    /** Optional description of the snapshot */
+    description?: string;
+    /** Name of the environment used by the runtime */
+    environment: string;
+    /** ISO 8601 timestamp when the snapshot was last updated */
+    updatedAt: string;
+}
+/**
+ * Snapshot domain model that wraps API responses with convenient methods.
+ * Provides runtime snapshot management with data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await runtime.createSnapshot('my-checkpoint');
+ * const runtime = await snapshot.restore();
+ * ```
+ */
+export declare class Snapshot {
+    protected _data: RuntimeSnapshotData;
+    private _sdk;
+    private _deleted;
+    /**
+     * Create a Snapshot instance.
+     *
+     * @param data - Snapshot data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: RuntimeSnapshotData, sdk: DatalayerClient);
+    /**
+     * Check if this snapshot has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    private _checkDeleted;
+    /** Unique identifier for the snapshot. */
+    get uid(): string;
+    /** Name of the snapshot. */
+    get name(): string;
+    /** Description of the snapshot. */
+    get description(): string;
+    /** Name of the environment used by the runtime. */
+    get environment(): string;
+    /** When the snapshot was last updated. */
+    get updatedAt(): Date;
+    /**
+     * Delete this snapshot permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    delete(): Promise<void>;
+    /**
+     * Create a runtime from this snapshot (restore functionality).
+     *
+     * @param config - Optional runtime configuration to override defaults
+     * @returns Created Runtime instance
+     */
+    restore(minutesLimit: number): Promise<Runtime>;
+    /**
+     * Get snapshot data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Note: Returns current cached state - call getStatus() first if you need fresh data.
+     *
+     * @returns Core snapshot data with camelCase properties
+     */
+    toJSON(): SnapshotJSON;
+    /**
+     * Get the raw snapshot data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw snapshot data from API
+     */
+    rawData(): RuntimeSnapshotData;
+    /** String representation of the snapshot. */
+    toString(): string;
+}

package/lib/client/models/Snapshot.js

@@ -0,0 +1,139 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { snapshots } from '../../api/runtimes';
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * Snapshot domain model that wraps API responses with convenient methods.
+ * Provides runtime snapshot management with data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await runtime.createSnapshot('my-checkpoint');
+ * const runtime = await snapshot.restore();
+ * ```
+ */
+export class Snapshot {
+    _data;
+    _sdk;
+    _deleted = false;
+    /**
+     * Create a Snapshot instance.
+     *
+     * @param data - Snapshot data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data, sdk) {
+        this._data = data;
+        this._sdk = sdk;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this snapshot has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Snapshot ${this._data.uid} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Unique identifier for the snapshot. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** Name of the snapshot. */
+    get name() {
+        this._checkDeleted();
+        return this._data.name;
+    }
+    /** Description of the snapshot. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description || '';
+    }
+    /** Name of the environment used by the runtime. */
+    get environment() {
+        this._checkDeleted();
+        return this._data.environment;
+    }
+    /** When the snapshot was last updated. */
+    get updatedAt() {
+        this._checkDeleted();
+        return new Date(this._data.updated_at);
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this snapshot permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    async delete() {
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const runtimesRunUrl = this._sdk.getRuntimesRunUrl();
+        await snapshots.deleteSnapshot(token, this.uid, runtimesRunUrl);
+        this._deleted = true;
+    }
+    /**
+     * Create a runtime from this snapshot (restore functionality).
+     *
+     * @param config - Optional runtime configuration to override defaults
+     * @returns Created Runtime instance
+     */
+    async restore(minutesLimit) {
+        this._checkDeleted();
+        return await this._sdk.createRuntime({
+            environmentName: this.environment,
+            type: 'notebook',
+            givenName: `Restored from ${this.name}`,
+            minutesLimit: minutesLimit,
+            fromSnapshotId: this.uid,
+        });
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get snapshot data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Note: Returns current cached state - call getStatus() first if you need fresh data.
+     *
+     * @returns Core snapshot data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const obj = {
+            uid: this.uid,
+            name: this.name,
+            description: this.description,
+            environment: this.environment,
+            updatedAt: this.updatedAt.toISOString(),
+        };
+        validateJSON(obj, 'Snapshot');
+        return obj;
+    }
+    /**
+     * Get the raw snapshot data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw snapshot data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the snapshot. */
+    toString() {
+        this._checkDeleted();
+        return `Snapshot(${this.uid}, ${this.name})`;
+    }
+}

package/lib/client/models/Space.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Space domain model for the Datalayer SDK.
+ *
+ * @module client/models/Space
+ */
+import type { Space as SpaceData } from '../../api/types/spacer';
+import type { DatalayerClient } from '../index';
+import { Notebook, type NotebookJSON } from './Notebook';
+import { Lexical, type LexicalJSON } from './Lexical';
+/**
+ * Stable public interface for Space data.
+ * This is the contract that SDK consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface SpaceJSON {
+    /** ulid for the space */
+    uid: string;
+    /** Name of the space */
+    name: string;
+    /** Handle for the space */
+    handle: string;
+    /** Variant of the space */
+    variant: string;
+    /** Description of the space */
+    description: string;
+    /** Items contained in the space (as JSON) */
+    items: Array<NotebookJSON | LexicalJSON>;
+}
+/**
+ * Space domain model that wraps API responses with convenient methods.
+ * Provides workspace management with data refresh and content creation operations.
+ *
+ * @example
+ * ```typescript
+ * const space = spaces[0];
+ * const items = await space.getItems();
+ * const notebook = await space.createNotebook({ name: 'Analysis' });
+ * ```
+ */
+export declare class Space {
+    protected _data: SpaceData;
+    private _sdk;
+    private _items;
+    private _deleted;
+    /**
+     * Create a Space instance.
+     *
+     * @param data - Space data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: SpaceData, sdk: DatalayerClient);
+    /**
+     * Check if this space has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    private _checkDeleted;
+    /**
+     * Refresh space data from the API by fetching user's spaces.
+     */
+    refresh(): Promise<void>;
+    /** Unique identifier for the space. */
+    get uid(): string;
+    /** URL-friendly handle for the space. */
+    get handle(): string;
+    /** Space variant type. */
+    get variant(): string;
+    /**
+     * The name of the space.
+     */
+    get name(): string;
+    /**
+     * The description of the space.
+     */
+    get description(): string;
+    /**
+     * Helper method to create items in this space.
+     *
+     * @param itemType - Type of item to create
+     * @param data - Creation configuration
+     * @returns Created model instance
+     * @internal
+     */
+    private _createItem;
+    /**
+     * Get all items in this space as model instances.
+     *
+     * @returns Array of Notebook and Lexical model instances
+     */
+    getItems(): Promise<(Notebook | Lexical)[]>;
+    /**
+     * Create a new notebook in this space.
+     *
+     * @param data - Notebook creation configuration
+     * @returns Created Notebook instance
+     */
+    createNotebook(data: {
+        name: string;
+        description: string;
+        file?: File | Blob;
+    }): Promise<Notebook>;
+    /**
+     * Create a new lexical document in this space.
+     *
+     * @param data - Lexical creation configuration
+     * @returns Created Lexical instance
+     */
+    createLexical(data: {
+        name: string;
+        description: string;
+        file?: File | Blob;
+    }): Promise<Lexical>;
+    /**
+     * Get raw space data object.
+     * Returns cached data without refreshing.
+     *
+     * @returns Raw space data object
+     */
+    /**
+     * Get space data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core space data with camelCase properties
+     */
+    toJSON(): SpaceJSON;
+    /**
+     * Get the raw space data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw space data from API
+     */
+    rawData(): SpaceData;
+    /** String representation of the space. */
+    toString(): string;
+}