@datalayer/core 0.0.12 → 0.0.14

package/lib/models/RuntimeSnapshotDTO.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Snapshot domain model for the Datalayer SDK.
+ *
+ * @module models/RuntimeSnapshotDTO
+ */
+import type { DatalayerClient } from '../index';
+import { RuntimeDTO } from './RuntimeDTO';
+/**
+ * Represents a runthime snapshot of a runtime's state and files.
+ * @interface RuntimeSnapshotData
+ */
+export interface RuntimeSnapshotData {
+    /** 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;
+    /** Metadata associated with the snapshot */
+    metadata?: {
+        version?: string;
+        language_info?: any;
+        [key: string]: any;
+    };
+    /** Size of the snapshot in bytes */
+    size?: number;
+    /** Format of the snapshot */
+    format?: string;
+    /** Format version of the snapshot */
+    format_version?: string;
+    /** Status of the snapshot */
+    status?: string;
+    /** ISO 8601 timestamp when the snapshot was last updated */
+    updated_at: string;
+    /** List of files included in the snapshot */
+    files?: any[];
+}
+/**
+ * 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 RuntimeSnapshotJSON {
+    /** 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;
+}
+/**
+ * Request payload for creating a runtime snapshot
+ * @interface CreateRuntimeSnapshotRequest
+ */
+export interface CreateRuntimeSnapshotRequest {
+    /** Pod name of the runtime to snapshot */
+    pod_name: string;
+    /** Name for the snapshot */
+    name: string;
+    /** Description of the snapshot */
+    description: string;
+    /** Whether to stop the runtime after creating snapshot */
+    stop: boolean;
+}
+/**
+ * Response for getting a specific runtime snapshot
+ * @interface GetRuntimeSnapshotResponse
+ */
+export interface GetRuntimeSnapshotResponse {
+    /** Indicates if the request was successful */
+    success: boolean;
+    /** Response message */
+    message: string;
+    /** The snapshot details */
+    snapshot: RuntimeSnapshotData;
+}
+/**
+ * Response for creating a runtime snapshot
+ * @interface CreateRuntimeSnapshotResponse
+ */
+export interface CreateRuntimeSnapshotResponse {
+    /** Indicates if the request was successful */
+    success: boolean;
+    /** Response message */
+    message: string;
+    /** The created snapshot details */
+    snapshot: RuntimeSnapshotData;
+}
+/**
+ * Response from listing runtime snapshots
+ * @interface RuntimeSnapshotsListResponse
+ */
+export interface ListRuntimeSnapshotsResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** Array of runtime snapshots */
+    snapshots: RuntimeSnapshotData[];
+}
+/**
+ * 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 RuntimeSnapshotDTO {
+    protected _data: RuntimeSnapshotData;
+    private _sdk;
+    private _deleted;
+    /**
+     * Create a Runtime 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<RuntimeDTO>;
+    /**
+     * 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(): RuntimeSnapshotJSON;
+    /**
+     * 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/models/RuntimeSnapshotDTO.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 RuntimeSnapshotDTO {
+    _data;
+    _sdk;
+    _deleted = false;
+    /**
+     * Create a Runtime 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/models/SpaceDTO.d.ts

@@ -0,0 +1,280 @@
+import type { DatalayerClient } from '../index';
+import { NotebookDTO, type NotebookJSON } from './NotebookDTO';
+import { NotebookData } from './NotebookDTO';
+import { LexicalDTO, type LexicalJSON } from './LexicalDTO';
+/**
+ * Represents a workspace or project space in Datalayer
+ * @interface SpaceData
+ */
+export interface SpaceData {
+    uid: string;
+    name_t: string;
+    handle_s: string;
+    variant_s: string;
+    description_t: string;
+    tags_ss?: string[];
+    members?: any[];
+    items?: any[];
+}
+/**
+ * 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 SpaceDTO {
+    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<(NotebookDTO | LexicalDTO)[]>;
+    /**
+     * 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<NotebookDTO>;
+    /**
+     * 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<LexicalDTO>;
+    /**
+     * 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;
+}
+/**
+ * Request payload for creating a new space
+ * @interface CreateSpaceRequest
+ */
+export interface CreateSpaceRequest {
+    name: string;
+    description: string;
+    variant: string;
+    spaceHandle: string;
+    organizationId: string;
+    seedSpaceId: string;
+    public: boolean;
+}
+/**
+ * Response from getting a collaboration session ID
+ * @interface CollaborationSessionResponse
+ */
+export interface CollaborationSessionResponse {
+    success: boolean;
+    sessionId?: string;
+    error?: string;
+}
+/**
+ * Response from creating a space
+ * @interface CreateSpaceResponse
+ */
+export interface CreateSpaceResponse {
+    success: boolean;
+    message: string;
+    space?: SpaceData;
+}
+/**
+ * Request payload for creating a new notebook (multipart/form-data)
+ * @interface CreateNotebookRequest
+ */
+export interface CreateNotebookRequest {
+    spaceId: string;
+    notebookType: string;
+    name: string;
+    description: string;
+    file?: File | Blob;
+}
+/**
+ * Response from creating a notebook
+ * @interface CreateNotebookResponse
+ */
+export interface CreateNotebookResponse {
+    success: boolean;
+    message: string;
+    notebook?: NotebookData;
+}
+/**
+ * Response from getting a notebook
+ * @interface GetNotebookResponse
+ */
+export interface GetNotebookResponse {
+    success: boolean;
+    message: string;
+    notebook?: NotebookData;
+}
+/**
+ * Request payload for creating a notebook
+ * @interface CreateNotebookRequest
+ */
+export interface CreateNotebookRequest {
+    spaceId: string;
+    notebookType: string;
+    name: string;
+    description: string;
+    file?: File | Blob;
+}
+/**
+ * Request payload for updating a notebook
+ * @interface UpdateNotebookRequest
+ */
+export interface UpdateNotebookRequest {
+    name?: string;
+    description?: string;
+}
+/**
+ * Response from updating a notebook
+ * @interface UpdateNotebookResponse
+ */
+export interface UpdateNotebookResponse {
+    success: boolean;
+    message: string;
+    notebook?: NotebookData;
+}
+/**
+ * Represents an item within a space
+ * @interface SpaceItem
+ */
+export interface SpaceItem {
+    id: string;
+    type_s: 'notebook' | 'lexical';
+    space_id: string;
+    item_id: string;
+    name: string;
+    created_at: string;
+    updated_at?: string;
+}
+/**
+ * Response from getting space items
+ * @interface GetSpaceItemsResponse
+ */
+export interface GetSpaceItemsResponse {
+    success: boolean;
+    message: string;
+    items: SpaceItem[];
+}
+/**
+ * Response from deleting a space item
+ * @interface DeleteSpaceItemResponse
+ */
+export interface DeleteSpaceItemResponse {
+    success: boolean;
+    message: string;
+}
+/**
+ * Response from getting a single space item
+ * @interface GetSpaceItemResponse
+ */
+export interface GetSpaceItemResponse {
+    success: boolean;
+    message: string;
+    item?: any;
+}
+/**
+ * Response from getting spaces for a user
+ * @interface SpacesForUserResponse
+ */
+export interface SpacesForUserResponse {
+    success: boolean;
+    message: string;
+    spaces: SpaceData[];
+}