@datalayer/core 0.0.9 → 0.0.11

package/lib/sdk/client/mixins/SpacerMixin.js

@@ -0,0 +1,278 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * @module sdk/client/mixins/SpacerMixin
+ * @description Spacer mixin for the Datalayer SDK.
+ *
+ * This mixin provides intuitive methods for managing workspaces, notebooks,
+ * and content that are mixed into the main DatalayerSDK class.
+ */
+import { spaces, notebooks, users, lexicals, items } from '../../../api/spacer';
+import { Notebook } from '../models/Notebook';
+import { Lexical } from '../models/Lexical';
+import { Space } from '../models/Space';
+/**
+ * Spacer mixin that provides workspace and content management.
+ *
+ * This mixin is applied to the DatalayerSDK class to provide clean, intuitive
+ * methods for managing spaces, notebooks, and cells.
+ */
+export function SpacerMixin(Base) {
+    return class extends Base {
+        // ========================================================================
+        // User
+        // ========================================================================
+        /**
+         * Get all workspaces for the authenticated user.
+         *
+         * @returns Promise resolving to array of Space instances
+         *
+         * @example
+         * ```typescript
+         * const mySpaces = await sdk.getMySpaces();
+         * console.log('My spaces:', mySpaces.length);
+         * for (const space of mySpaces) {
+         *   const name = await space.getName();
+         *   console.log(`- ${name} (${space.visibility})`);
+         * }
+         * ```
+         */
+        async getMySpaces() {
+            const token = this.getToken();
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const response = await users.getMySpaces(token, spacerRunUrl);
+            return response.spaces.map(s => new Space(s, this));
+        }
+        // ========================================================================
+        // Spaces
+        // ========================================================================
+        /**
+         * Create a new workspace.
+         *
+         * @param data - Space creation parameters
+         * @returns Promise resolving to created Space instance
+         *
+         * @example
+         * ```typescript
+         * const space = await sdk.createSpace({
+         *   name: 'My Research Project',
+         *   description: 'Data analysis workspace',
+         *   variant: 'default',
+         *   spaceHandle: 'research-project',
+         *   organizationId: 'org-123',
+         *   seedSpaceId: 'seed-456',
+         *   public: false
+         * });
+         * const name = await space.getName();
+         * console.log('Space created:', name);
+         * ```
+         */
+        async createSpace(data) {
+            const token = this.getToken();
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const response = await spaces.createSpace(token, data, spacerRunUrl);
+            return new Space(response.space, this);
+        }
+        // ========================================================================
+        // Notebooks
+        // ========================================================================
+        // ========================================================================
+        // Helper Functions
+        // ========================================================================
+        _extractNotebookId(notebookIdOrInstance) {
+            return typeof notebookIdOrInstance === 'string'
+                ? notebookIdOrInstance
+                : notebookIdOrInstance.uid;
+        }
+        _extractLexicalId(lexicalIdOrInstance) {
+            return typeof lexicalIdOrInstance === 'string'
+                ? lexicalIdOrInstance
+                : lexicalIdOrInstance.uid;
+        }
+        /**
+         * Create a new notebook.
+         *
+         * @param data - Notebook creation parameters
+         * @returns Promise resolving to created Notebook instance
+         *
+         * @example
+         * ```typescript
+         * const notebook = await sdk.createNotebook({
+         *   spaceId: 'space-123',
+         *   name: 'Data Analysis',
+         *   description: 'Analysis notebook',
+         *   notebookType: 'jupyter',
+         * });
+         * ```
+         */
+        async createNotebook(data) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await notebooks.createNotebook(token, data, spacerRunUrl);
+            return new Notebook(response.notebook, this);
+        }
+        /**
+         * Get a notebook by ID or Notebook instance.
+         *
+         * @param idOrNotebook - Notebook ID (string) or Notebook instance
+         * @returns Promise resolving to Notebook instance
+         *
+         * @example
+         * ```typescript
+         * const notebook = await sdk.getNotebook('notebook-123');
+         * const refreshed = await sdk.getNotebook(notebook);
+         * ```
+         */
+        async getNotebook(idOrNotebook) {
+            const notebookId = this._extractNotebookId(idOrNotebook);
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await notebooks.getNotebook(token, notebookId, spacerRunUrl);
+            if (!response.notebook) {
+                throw new Error(`Notebook with ID '${notebookId}' not found`);
+            }
+            return new Notebook(response.notebook, this);
+        }
+        /**
+         * Update a notebook.
+         *
+         * @param idOrNotebook - Notebook ID (string) or Notebook instance
+         * @param data - Update data with optional name and/or description
+         * @returns Promise resolving to updated Notebook instance
+         *
+         * @example
+         * ```typescript
+         * const updated = await sdk.updateNotebook('notebook-123', {
+         *   name: 'Updated Analysis',
+         *   description: 'Updated description'
+         * });
+         * const updated2 = await sdk.updateNotebook(notebook, {
+         *   name: 'Updated Analysis',
+         *   description: 'Updated description'
+         * });
+         * ```
+         */
+        async updateNotebook(idOrNotebook, data) {
+            const notebookId = this._extractNotebookId(idOrNotebook);
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await notebooks.updateNotebook(token, notebookId, data, spacerRunUrl);
+            return new Notebook(response.notebook, this);
+        }
+        // ========================================================================
+        // Lexicals
+        // ========================================================================
+        /**
+         * Create a new lexical document.
+         *
+         * @param data - Document creation parameters
+         * @returns Promise resolving to created Lexical instance
+         *
+         * @example
+         * ```typescript
+         * const lexical = await sdk.createLexical({
+         *   spaceId: 'space-123',
+         *   name: 'Project Documentation',
+         *   description: 'Main project docs',
+         *   documentType: 'document',
+         * });
+         * ```
+         */
+        async createLexical(data) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await lexicals.createLexical(token, data, spacerRunUrl);
+            return new Lexical(response.document, this);
+        }
+        /**
+         * Get a lexical document by ID or Lexical instance.
+         *
+         * @param idOrLexical - Document ID (string) or Lexical instance
+         * @returns Promise resolving to Lexical instance
+         *
+         * @example
+         * ```typescript
+         * const lexical = await sdk.getLexical('lexical-123');
+         * const refreshed = await sdk.getLexical(lexical);
+         * ```
+         */
+        async getLexical(idOrLexical) {
+            const lexicalId = this._extractLexicalId(idOrLexical);
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await lexicals.getLexical(token, lexicalId, spacerRunUrl);
+            if (!response.document) {
+                throw new Error(`Lexical document with ID '${lexicalId}' not found`);
+            }
+            return new Lexical(response.document, this);
+        }
+        /**
+         * Update a lexical document.
+         *
+         * @param idOrLexical - Document ID (string) or Lexical instance
+         * @param data - Update data with optional name and/or description
+         * @returns Promise resolving to updated Lexical instance
+         *
+         * @example
+         * ```typescript
+         * const updated = await sdk.updateLexical('lexical-123', {
+         *   name: 'Updated Documentation',
+         *   description: 'Updated description'
+         * });
+         * const updated2 = await sdk.updateLexical(lexical, {
+         *   name: 'Updated Documentation',
+         *   description: 'Updated description'
+         * });
+         * ```
+         */
+        async updateLexical(idOrLexical, data) {
+            const lexicalId = this._extractLexicalId(idOrLexical);
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            const response = await lexicals.updateLexical(token, lexicalId, data, spacerRunUrl);
+            return new Lexical(response.document, this);
+        }
+        // ========================================================================
+        // Items
+        // ========================================================================
+        /**
+         * Get the items of a space.
+         *
+         * @param spaceId - Space ID
+         * @returns Promise resolving to space items
+         *
+         * @example
+         * ```typescript
+         * const response = await sdk.getSpaceItems('space-123');
+         * console.log('Space items:', response.items.length);
+         * response.items.forEach(item => {
+         *   console.log(`- ${item.name} (${item.type})`);
+         * });
+         * ```
+         */
+        async getSpaceItems(spaceId) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            return await items.getSpaceItems(token, spaceId, spacerRunUrl);
+        }
+        /**
+         * Delete an item from a space.
+         *
+         * @param itemId - Item ID to delete
+         * @returns Promise resolving when deletion is complete
+         *
+         * @example
+         * ```typescript
+         * const response = await sdk.deleteSpaceItem('item-123');
+         * console.log('Item deleted:', response.message);
+         * ```
+         */
+        async deleteSpaceItem(itemId) {
+            const spacerRunUrl = this.getSpacerRunUrl();
+            const token = this.getToken();
+            return await items.deleteItem(token, itemId, spacerRunUrl);
+        }
+    };
+}

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

@@ -0,0 +1,156 @@
+/**
+ * @module sdk/client/models/Lexical
+ * @description Lexical domain model for the Datalayer SDK.
+ *
+ * This model provides a rich, object-oriented interface for working with
+ * Lexical documents, including content management and lifecycle operations.
+ */
+import type { Lexical as LexicalData, UpdateLexicalRequest } from '../../../api/types/spacer';
+import type { DatalayerSDK } from '../index';
+/**
+ * Lexical domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing Lexical documents
+ * with automatic data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const formData = new FormData();
+ * formData.append('spaceId', 'space-123');
+ * formData.append('name', 'Project Documentation');
+ * const lexical = await sdk.createLexical(formData);
+ *
+ * // Static properties - instant access
+ * console.log(lexical.id);
+ * console.log(lexical.spaceId);
+ *
+ * // Dynamic data - always fresh from API
+ * const currentName = await lexical.getName();
+ * const content = await lexical.getContent();
+ *
+ * // Update document
+ * const updated = await lexical.update({ name: 'Updated Documentation' });
+ * ```
+ */
+export declare class Lexical {
+    protected _data: LexicalData;
+    private _sdk;
+    private _deleted;
+    private _freshData;
+    private _lastFetch;
+    private _cacheTimeout;
+    /**
+     * Create a Lexical instance.
+     *
+     * @param data - Raw lexical data from API
+     * @param sdk - DatalayerSDK instance for making API calls
+     */
+    constructor(data: LexicalData, sdk: DatalayerSDK);
+    /**
+     * Check if this lexical document has been deleted.
+     */
+    get isDeleted(): boolean;
+    /**
+     * Check if this lexical document has been deleted and throw error if so.
+     * @throws Error if the document has been deleted
+     */
+    private _checkDeleted;
+    /**
+     * Get fresh data from API with caching to avoid redundant calls.
+     * @returns Current LexicalData from API or cache
+     */
+    private _getFreshData;
+    /**
+     * Lexical document ID.
+     */
+    get id(): string;
+    /**
+     * Unique identifier for the document.
+     */
+    get uid(): string;
+    /**
+     * Parent space ID.
+     */
+    get spaceId(): string;
+    /**
+     * Owner user ID.
+     */
+    get ownerId(): string;
+    /**
+     * When the document was created.
+     */
+    get createdAt(): Date;
+    /**
+     * Get the current name of the document.
+     *
+     * 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 document name
+     * @throws Error if the document has been deleted
+     */
+    getName(): Promise<string>;
+    /**
+     * Get the document content.
+     *
+     * @returns Promise resolving to document content
+     */
+    getContent(): Promise<any>;
+    /**
+     * Get when the document was last updated.
+     *
+     * @returns Promise resolving to last update time
+     */
+    getUpdatedAt(): Promise<Date>;
+    /**
+     * Update the document name and/or description.
+     *
+     * @param data - Update data containing name and/or description
+     * @returns Promise resolving to updated Lexical instance
+     *
+     * @example
+     * ```typescript
+     * const updated = await lexical.update({
+     *   name: 'Updated Documentation',
+     *   description: 'Updated document description'
+     * });
+     * ```
+     */
+    update(data: UpdateLexicalRequest): Promise<Lexical>;
+    /**
+     * Delete this document permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await lexical.delete();
+     * console.log('Document deleted');
+     * // lexical.getName() will now throw an error
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Get raw document 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 document data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await lexical.toJSON();
+     * console.log('Current name:', latestData.name);
+     * ```
+     */
+    toJSON(): Promise<LexicalData>;
+    /**
+     * String representation of the document.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString(): string;
+}
+export type { LexicalData };

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

@@ -0,0 +1,275 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { lexicals } from '../../../api/spacer';
+import { items } from '../../../api/spacer';
+/**
+ * Lexical domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing Lexical documents
+ * with automatic data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const formData = new FormData();
+ * formData.append('spaceId', 'space-123');
+ * formData.append('name', 'Project Documentation');
+ * const lexical = await sdk.createLexical(formData);
+ *
+ * // Static properties - instant access
+ * console.log(lexical.id);
+ * console.log(lexical.spaceId);
+ *
+ * // Dynamic data - always fresh from API
+ * const currentName = await lexical.getName();
+ * const content = await lexical.getContent();
+ *
+ * // Update document
+ * const updated = await lexical.update({ name: 'Updated Documentation' });
+ * ```
+ */
+export class Lexical {
+    _data;
+    _sdk;
+    _deleted = false;
+    _freshData = null;
+    _lastFetch = 0;
+    _cacheTimeout = 5000; // 5 seconds cache timeout
+    /**
+     * Create a Lexical instance.
+     *
+     * @param data - Raw lexical 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 lexical document has been deleted.
+     */
+    get isDeleted() {
+        return this._deleted;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this lexical document has been deleted and throw error if so.
+     * @throws Error if the document has been deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Lexical ${this._data.id} has been deleted and no longer exists`);
+        }
+    }
+    /**
+     * Get fresh data from API with caching to avoid redundant calls.
+     * @returns Current LexicalData 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 lexicals.getLexical(token, this.uid, spacerRunUrl);
+        if (response.document) {
+            this._freshData = response.document;
+            this._data = response.document; // 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)
+    // ========================================================================
+    /**
+     * Lexical document ID.
+     */
+    get id() {
+        this._checkDeleted();
+        return this._data.id;
+    }
+    /**
+     * Unique identifier for the document.
+     */
+    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/documents/..."
+        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 document 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 lexical document');
+        }
+        return new Date(dateStr);
+    }
+    // ========================================================================
+    // Dynamic Methods (always fetch fresh data and update internal state)
+    // ========================================================================
+    /**
+     * Get the current name of the document.
+     *
+     * 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 document name
+     * @throws Error if the document has been deleted
+     */
+    async getName() {
+        const freshData = await this._getFreshData();
+        return freshData.name_t || freshData.name || '';
+    }
+    /**
+     * Get the document content.
+     *
+     * @returns Promise resolving to document 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 when the document 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 lexical document');
+        }
+        return new Date(dateStr);
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Update the document name and/or description.
+     *
+     * @param data - Update data containing name and/or description
+     * @returns Promise resolving to updated Lexical instance
+     *
+     * @example
+     * ```typescript
+     * const updated = await lexical.update({
+     *   name: 'Updated Documentation',
+     *   description: 'Updated document description'
+     * });
+     * ```
+     */
+    async update(data) {
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const response = await lexicals.updateLexical(token, this.uid, data, spacerRunUrl);
+        return new Lexical(response.document, this._sdk);
+    }
+    /**
+     * Delete this document permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await lexical.delete();
+     * console.log('Document deleted');
+     * // lexical.getName() will now throw an error
+     * ```
+     */
+    async delete() {
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        await items.deleteItem(token, this.uid, spacerRunUrl);
+        this._deleted = true;
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get raw document 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 document data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await lexical.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 document.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString() {
+        this._checkDeleted();
+        const name = this._data.name_t || this._data.name || 'Unnamed';
+        return `Lexical(${this.id}, ${name})`;
+    }
+}