@datalayer/core 0.0.12 → 0.0.13

package/lib/client/models/Item.js

@@ -0,0 +1,191 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Abstract base class for all Datalayer content items.
+ *
+ * @module client/models/Item
+ */
+import * as items from '../../api/spacer/items';
+/**
+ * Abstract base class for all Datalayer content items.
+ * Provides common functionality for content management including lifecycle tracking.
+ *
+ * @template TData - Raw data type from API
+ * @template TUpdateRequest - Update request type for API
+ */
+export class Item {
+    _data;
+    _sdk;
+    _deleted = false;
+    /**
+     * Create an Item instance.
+     * @param data - Item data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data, sdk) {
+        this._data = data;
+        this._sdk = sdk;
+    }
+    // ========================================================================
+    // Deletion State Management
+    // ========================================================================
+    /** Check if this item has been deleted. */
+    get isDeleted() {
+        return this._deleted;
+    }
+    /**
+     * Check if this item has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`${this.constructor.name} ${this._data.id} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Item ID. */
+    get id() {
+        this._checkDeleted();
+        return this._data.id;
+    }
+    /** Unique identifier for the item. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** 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/..."
+        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 item 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 ${this.constructor.name.toLowerCase()}`);
+        }
+        return new Date(dateStr);
+    }
+    /** The cached update time. */
+    get updatedAt() {
+        this._checkDeleted();
+        const dateStr = this._data.last_update_ts_dt ||
+            this._data.updated_at ||
+            this._data.creation_ts_dt ||
+            this._data.created_at;
+        if (!dateStr) {
+            throw new Error(`No update timestamp available for ${this.constructor.name.toLowerCase()}`);
+        }
+        return new Date(dateStr);
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this item permanently.
+     * After deletion, all subsequent method calls will throw errors.
+     */
+    async delete() {
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        await items.deleteItem(token, this.uid, spacerRunUrl);
+        this._deleted = true;
+    }
+    /** Get the document content from API. */
+    async getContent() {
+        this._checkDeleted();
+        // First try: CDN URL (fastest)
+        const cdnUrl = this._data.cdn_url_s;
+        if (cdnUrl) {
+            try {
+                const response = await fetch(cdnUrl);
+                if (!response.ok) {
+                    throw new Error('Failed to fetch content from CDN');
+                }
+                const data = await response.json();
+                if (data.content !== undefined && data.content !== null) {
+                    return data.content;
+                }
+            }
+            catch (error) {
+                console.error('Error fetching content from CDN:', error);
+            }
+        }
+        // Second try: Check if content is already loaded
+        const cachedContent = this.content;
+        if (cachedContent !== undefined && cachedContent !== null) {
+            return cachedContent;
+        }
+        // Third try: Fetch full item details from API
+        try {
+            const token = this._sdk.getToken();
+            const spacerRunUrl = this._sdk.getSpacerRunUrl();
+            const response = await items.getItem(token, this.uid, spacerRunUrl);
+            // Update internal data with full item details
+            if (response.success && response.item) {
+                this._data = response.item;
+                const freshContent = this.content;
+                if (freshContent !== undefined && freshContent !== null) {
+                    return freshContent;
+                }
+            }
+        }
+        catch (error) {
+            console.error('Error fetching full item details:', error);
+        }
+        throw new Error(`Content is not available for item ${this.uid}. The item may not have been fully loaded or the content is not yet available.`);
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /** Get raw item data object. */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the item. */
+    toString() {
+        this._checkDeleted();
+        const name = this.name || 'Unnamed';
+        return `${this.constructor.name}(${this.id}, ${name})`;
+    }
+    // ========================================================================
+    // Protected Helper Methods
+    // ========================================================================
+    /** Get SDK token for API calls. */
+    _getToken() {
+        return this._sdk.getToken();
+    }
+    /** Get spacer API URL for API calls. */
+    _getSpacerRunUrl() {
+        return this._sdk.getSpacerRunUrl();
+    }
+    /** Update internal data after API call. */
+    _updateData(newData) {
+        this._data = newData;
+    }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Lexical domain model for the Datalayer SDK.
+ *
+ * @module client/models/Lexical
+ */
+import type { Lexical as LexicalData } from '../../api/types/spacer';
+import type { DatalayerClient } from '../index';
+import { Item } from './Item';
+/**
+ * Stable public interface for Lexical data.
+ * This is the contract that SDK consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface LexicalJSON {
+    /** Unique identifier for the lexical document */
+    uid: string;
+    /** Unique identifier for the lexical document */
+    id: string;
+    /** Name of the lexical document */
+    name: string;
+    /** Description of the lexical document */
+    description: string;
+    /** Type of lexical document */
+    type: string;
+    /** File extension of the lexical document */
+    extension: string;
+    /** ISO 8601 timestamp when the document was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when the document was last updated */
+    updatedAt: string;
+    /** CDN URL for accessing the document */
+    cdnUrl: string;
+}
+/**
+ * Lexical domain model that extends the base Item class.
+ * Provides lexical document functionality for managing rich text documents.
+ *
+ * @example
+ * ```typescript
+ * const lexical = await sdk.createLexical(formData);
+ * await lexical.update({ name: 'Updated Documentation' });
+ * ```
+ */
+export declare class Lexical extends Item<LexicalData> {
+    /**
+     * Create a Lexical instance.
+     *
+     * @param data - Lexical data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: LexicalData, sdk: DatalayerClient);
+    /** Document type identifier. */
+    get type(): string;
+    /** The cached name of the document. */
+    get name(): string;
+    /** Get the current name of the document from API. */
+    getName(): Promise<string>;
+    /** The cached content. */
+    get content(): any;
+    /** Description of the lexical document. */
+    get description(): string;
+    /** Get the document extension. */
+    get extension(): string;
+    /** Get when the document was last updated from API. */
+    getUpdatedAt(): Promise<Date>;
+    /** Update the document. */
+    update(name?: string, description?: string): Promise<this>;
+    /**
+     * Get lexical document data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core lexical data with camelCase properties
+     */
+    toJSON(): LexicalJSON;
+    /**
+     * Get the raw lexical data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw lexical data from API
+     */
+    rawData(): LexicalData;
+}

package/lib/client/models/Lexical.js

@@ -0,0 +1,152 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as lexicals from '../../api/spacer/lexicals';
+import { Item } from './Item';
+import { ItemTypes } from '../constants';
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * Lexical domain model that extends the base Item class.
+ * Provides lexical document functionality for managing rich text documents.
+ *
+ * @example
+ * ```typescript
+ * const lexical = await sdk.createLexical(formData);
+ * await lexical.update({ name: 'Updated Documentation' });
+ * ```
+ */
+export class Lexical extends Item {
+    /**
+     * Create a Lexical instance.
+     *
+     * @param data - Lexical 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.LEXICAL;
+    }
+    /** The cached name of the document. */
+    get name() {
+        this._checkDeleted();
+        return this._data.name_t || this._data.name || '';
+    }
+    /** Get the current name of the document from API. */
+    async getName() {
+        this._checkDeleted();
+        const token = this._getToken();
+        const spacerRunUrl = this._getSpacerRunUrl();
+        const response = await lexicals.getLexical(token, this.uid, spacerRunUrl);
+        if (response.document) {
+            this._updateData(response.document);
+            return response.document.name_t || response.document.name || '';
+        }
+        return this.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;
+    }
+    /** Description of the lexical document. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description_t || '';
+    }
+    /** Get the document extension. */
+    get extension() {
+        this._checkDeleted();
+        const ext = this._data.document_extension_s;
+        return ext ? (ext.startsWith('.') ? ext : `.${ext}`) : '.lexical';
+    }
+    /** Get when the document was last updated from API. */
+    async getUpdatedAt() {
+        this._checkDeleted();
+        const token = this._getToken();
+        const spacerRunUrl = this._getSpacerRunUrl();
+        const response = await lexicals.getLexical(token, this.uid, spacerRunUrl);
+        if (response.document) {
+            this._updateData(response.document);
+            const dateStr = response.document.last_update_ts_dt ||
+                response.document.updated_at ||
+                response.document.creation_ts_dt ||
+                response.document.created_at;
+            if (!dateStr) {
+                throw new Error('No timestamp available for lexical document');
+            }
+            return new Date(dateStr);
+        }
+        const dateStr = this._data.last_update_ts_dt ||
+            this._data.updated_at ||
+            this._data.creation_ts_dt ||
+            this._data.created_at;
+        if (!dateStr) {
+            throw new Error('No timestamp available for lexical document');
+        }
+        return new Date(dateStr);
+    }
+    /** Update the document. */
+    async update(name, description) {
+        // FIXME: check if both are needed, and use the existing values if only one provided
+        this._checkDeleted();
+        const token = this._getToken();
+        const spacerRunUrl = this._getSpacerRunUrl();
+        const updateData = {};
+        if (name !== undefined)
+            updateData.name = name;
+        if (description !== undefined)
+            updateData.description = description;
+        const response = await lexicals.updateLexical(token, this.uid, updateData, spacerRunUrl);
+        this._updateData(response.document);
+        return this;
+    }
+    /**
+     * Get lexical document data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core lexical data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const obj = {
+            uid: this.uid,
+            id: this.id,
+            name: this.name,
+            description: this.description,
+            type: this.type,
+            extension: this.extension,
+            createdAt: this.createdAt.toDateString(),
+            updatedAt: this.updatedAt.toDateString(),
+            cdnUrl: this._data.cdn_url_s,
+        };
+        validateJSON(obj, 'Lexical');
+        return obj;
+    }
+    /**
+     * Get the raw lexical data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw lexical data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Notebook domain model for the Datalayer SDK.
+ *
+ * @module client/models/Notebook
+ */
+import type { Notebook as NotebookData } from '../../api/types/spacer';
+import type { DatalayerClient } from '../index';
+import { Item } from './Item';
+/**
+ * Stable public interface for Notebook data.
+ * This is the contract that SDK consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface NotebookJSON {
+    /** uuid of the notebook */
+    id: string;
+    /** ulid for of the notebook */
+    uid: string;
+    /** Name of the notebook */
+    name: string;
+    /** Description of the notebook */
+    description: string;
+    /** Type of notebook */
+    type: string;
+    /** File extension of the notebook */
+    extension: string;
+    /** CDN URL for accessing the notebook */
+    cdnUrl: string;
+}
+/**
+ * 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 declare class Notebook extends Item<NotebookData> {
+    /**
+     * Create a Notebook instance.
+     *
+     * @param data - Notebook data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: NotebookData, sdk: DatalayerClient);
+    /** Document type identifier. */
+    get type(): string;
+    /** The cached name of the notebook. */
+    get name(): string;
+    /** The cached content. */
+    get content(): any;
+    /** Get the current name from API. */
+    getName(): Promise<string>;
+    /** Get when the notebook was last updated from API. */
+    getUpdatedAt(): Promise<Date>;
+    /** Update the notebook. */
+    update(name?: string, description?: string): Promise<this>;
+    /** File path within the space. */
+    get path(): string;
+    /** Version number. */
+    get version(): number;
+    /** Notebook metadata. */
+    get metadata(): Record<string, any>;
+    /** Kernel specification (cached). */
+    get kernelSpec(): any;
+    /** Description of the notebook. */
+    get description(): string;
+    /** Get the notebook extension. */
+    get extension(): string;
+    /**
+     * 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(): NotebookJSON;
+    /**
+     * 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(): NotebookData;
+}

package/lib/client/models/Notebook.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 { Item } from './Item';
+import { ItemTypes } from '../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 Notebook extends Item {
+    /**
+     * 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;
+    }
+}