@datalayer/core 0.0.12 → 0.0.14

package/lib/models/NotebookDTO.js

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as notebooks from '../api/spacer/notebooks';
+import { ItemDTO } from './ItemDTO';
+import { ItemTypes } from '../client/constants';
+import { validateJSON } from '../api/utils/validation';
+/**
+ * Notebook domain model that extends the base Item class.
+ * Provides notebook-specific functionality for managing Jupyter notebooks.
+ *
+ * @example
+ * ```typescript
+ * const notebook = await sdk.createNotebook(formData);
+ * const kernelSpec = await notebook.getKernelSpec();
+ * ```
+ */
+export class NotebookDTO extends ItemDTO {
+    /**
+     * Create a Notebook instance.
+     *
+     * @param data - Notebook data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data, sdk) {
+        super(data, sdk);
+    }
+    // ========================================================================
+    // Abstract Method Implementations
+    // ========================================================================
+    /** Document type identifier. */
+    get type() {
+        this._checkDeleted();
+        return ItemTypes.NOTEBOOK;
+    }
+    /** The cached name of the notebook. */
+    get name() {
+        this._checkDeleted();
+        return (this._data.name_t ||
+            this._data.notebook_name_s ||
+            this._data.name ||
+            '');
+    }
+    /** The cached content. */
+    get content() {
+        this._checkDeleted();
+        if (!this._data.content && this._data.model_s) {
+            try {
+                return JSON.parse(this._data.model_s);
+            }
+            catch {
+                return this._data.model_s;
+            }
+        }
+        return this._data.content;
+    }
+    /** Get the current name from API. */
+    async getName() {
+        this._checkDeleted();
+        // For now, return cached value - implement API call if needed
+        return this.name;
+    }
+    /** Get when the notebook was last updated from API. */
+    async getUpdatedAt() {
+        this._checkDeleted();
+        const dateStr = this._data.updated_at || this._data.update_ts_dt;
+        if (!dateStr) {
+            throw new Error('No update timestamp available for notebook');
+        }
+        return new Date(dateStr);
+    }
+    /** Update the notebook. */
+    async update(name, description) {
+        // FIXME: check if both are needed, and use the existing values if only one provided
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const updateData = {};
+        if (name !== undefined)
+            updateData.name = name;
+        if (description !== undefined)
+            updateData.description = description;
+        await notebooks.updateNotebook(token, this.uid, updateData, spacerRunUrl);
+        // FIXME: handle partial updates
+        return this;
+    }
+    // ========================================================================
+    // Notebook-specific Properties
+    // ========================================================================
+    /** File path within the space. */
+    get path() {
+        this._checkDeleted();
+        return this._data.path || '';
+    }
+    /** Version number. */
+    get version() {
+        this._checkDeleted();
+        return this._data.version || 0;
+    }
+    /** Notebook metadata. */
+    get metadata() {
+        this._checkDeleted();
+        return this._data.metadata || {};
+    }
+    /** Kernel specification (cached). */
+    get kernelSpec() {
+        this._checkDeleted();
+        return this._data.kernel_spec;
+    }
+    /** Description of the notebook. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description_t || '';
+    }
+    /** Get the notebook extension. */
+    get extension() {
+        this._checkDeleted();
+        const ext = this._data.notebook_extension_s;
+        return ext ? (ext.startsWith('.') ? ext : `.${ext}`) : '.ipynb';
+    }
+    /**
+     * Get notebook data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core notebook data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const obj = {
+            id: this.id,
+            uid: this.uid,
+            name: this.name,
+            description: this.description,
+            type: this.type,
+            extension: this.extension,
+            cdnUrl: this._data.cdn_url_s,
+        };
+        validateJSON(obj, 'Notebook');
+        return obj;
+    }
+    /**
+     * Get the raw notebook data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw notebook data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+}

package/lib/models/Profile.d.ts

@@ -1 +1,66 @@
 export type IProfileType = 'user' | 'organization' | undefined;
+/**
+ * Represents a user profile in the Datalayer platform
+ * @interface Profile
+ */
+export interface Profile {
+    /** ISO 8601 timestamp of when the user was created */
+    creation_ts_dt: string;
+    /** Unique identifier for the user */
+    id: string;
+    /** ISO 8601 timestamp of when the user requested to join */
+    join_request_ts_dt: string | null;
+    /** ISO 8601 timestamp of when the user joined */
+    join_ts_dt: string;
+    /** ISO 8601 timestamp of last update */
+    last_update_ts_dt: string;
+    /** Origin of the user account */
+    origin_s: string;
+    /** Type of the record */
+    type_s: string;
+    /** User ID */
+    uid: string;
+    /** Email address */
+    email_s: string;
+    /** First name */
+    first_name_t: string;
+    /** User handle */
+    handle_s: string;
+    /** Last name */
+    last_name_t: string;
+    /** User roles array */
+    roles_ss?: string[];
+    /** Avatar URL */
+    avatar_url_s?: string;
+    /** Onboarding state as JSON string */
+    onboarding_s?: string;
+    /** New password request timestamp */
+    new_password_request_ts_dt?: string | null;
+    /** New password confirmation timestamp */
+    new_password_confirmation_ts_dt?: string | null;
+    /** Customer UID */
+    customer_uid?: string | null;
+    /** Credits customer UID for billing */
+    credits_customer_uid?: string | null;
+    /** Email unsubscription status */
+    unsubscribed_from_outbounds_b?: boolean;
+    /** Linked contact UID */
+    linked_contact_uid?: string | null;
+    /** MFA URL */
+    mfa_url_s?: string | null;
+    /** MFA secret */
+    mfa_secret_s?: string | null;
+    /** Email verification token */
+    email_token_s?: string | null;
+    /** Pending email update */
+    email_update_s?: string | null;
+    /** IAM providers (nested structure - not typed in detail) */
+    iam_providers?: any[];
+    /** User settings (nested structure - not typed in detail) */
+    settings?: any;
+    /** User events (nested structure - not typed in detail) */
+    events?: any[];
+    /** Allow additional fields that may come from the server */
+    [key: string]: any;
+}
+export default Profile;

package/lib/models/RuntimeDTO.d.ts

@@ -0,0 +1,191 @@
+import type { DatalayerClient } from '../index';
+import { RuntimeSnapshotDTO } from './RuntimeSnapshotDTO';
+/**
+ * Represents a running instance of a computing environment.
+ * @interface RuntimeData
+ */
+export interface RuntimeData {
+    /** Kubernetes pod name for the runtime instance */
+    pod_name: string;
+    /** Unique identifier for the runtime */
+    uid: string;
+    /** Name of the environment this runtime is based on */
+    environment_name: string;
+    /** Title of the environment for display */
+    environment_title: string;
+    /** Type of runtime - notebook, terminal, or job */
+    type: string;
+    /** Credits consumed per second */
+    burning_rate: number;
+    /** User-friendly name for the runtime */
+    given_name: string;
+    /** Authentication token for accessing the runtime */
+    token: string;
+    /** Ingress URL for accessing the runtime */
+    ingress: string;
+    /** ISO 8601 timestamp of when the runtime started */
+    started_at: string;
+    /** ISO 8601 timestamp of when the runtime will expire */
+    expired_at: string;
+}
+/**
+ * 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;
+}
+/**
+ * Request payload for creating a new runtime
+ * @interface CreateRuntimeRequest
+ */
+export interface CreateRuntimeRequest {
+    /** Name of the environment to use */
+    environment_name: string;
+    /** Type of runtime (e.g., 'notebook', 'terminal', 'job') */
+    type?: 'notebook' | 'terminal' | 'job';
+    /** Optional given name for the runtime */
+    given_name?: string;
+    /** Maximum credits this runtime can consume */
+    credits_limit?: number;
+    /** Optional capabilities for the runtime */
+    capabilities?: string[];
+    /** Optional source to create runtime from (e.g., snapshot ID) */
+    from?: string;
+}
+/**
+ * Response from creating a new runtime
+ * @interface CreateRuntimeResponse
+ */
+export interface CreateRuntimeResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** The created runtime instance */
+    runtime: RuntimeData;
+}
+/**
+ * Response from listing runtimes
+ * @interface ListRuntimesResponse
+ */
+export interface ListRuntimesResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** Array of runtime instances */
+    runtimes: RuntimeData[];
+}
+/**
+ * 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 RuntimeDTO {
+    /** @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<RuntimeDTO>;
+    /**
+     * 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<RuntimeSnapshotDTO>;
+    /**
+     * 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/models/RuntimeDTO.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 models/RuntimeDTO
+ */
+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 RuntimeDTO {
+    /** @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 RuntimeDTO(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})`;
+    }
+}