@datalayer/core 0.0.12 → 0.0.13

package/lib/client/models/Space.js

@@ -0,0 +1,234 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as users from '../../api/spacer/users';
+import * as items from '../../api/spacer/items';
+import * as notebooks from '../../api/spacer/notebooks';
+import * as lexicals from '../../api/spacer/lexicals';
+import { Notebook } from './Notebook';
+import { Lexical } from './Lexical';
+import { ItemTypes } from '../constants';
+import { convertSpaceItemsToModels } from '../utils/spacerUtils';
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * 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 class Space {
+    _data;
+    _sdk;
+    _items = null;
+    _deleted = false;
+    /**
+     * Create a Space instance.
+     *
+     * @param data - Space data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data, sdk) {
+        this._data = data;
+        this._sdk = sdk;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this space has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Space ${this._data.uid} has been deleted and no longer exists`);
+        }
+    }
+    /**
+     * Refresh space data from the API by fetching user's spaces.
+     */
+    async refresh() {
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const response = await users.getMySpaces(token, spacerRunUrl);
+        const freshSpace = response.spaces.find(s => s.uid === this.uid);
+        if (freshSpace) {
+            this._data = freshSpace;
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Unique identifier for the space. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** URL-friendly handle for the space. */
+    get handle() {
+        this._checkDeleted();
+        return this._data.handle_s;
+    }
+    /** Space variant type. */
+    get variant() {
+        this._checkDeleted();
+        return this._data.variant_s;
+    }
+    /**
+     * The name of the space.
+     */
+    get name() {
+        return this._data.name_t;
+    }
+    /**
+     * The description of the space.
+     */
+    get description() {
+        return this._data.description_t;
+    }
+    // ========================================================================
+    // Space-specific Methods
+    // ========================================================================
+    /**
+     * Helper method to create items in this space.
+     *
+     * @param itemType - Type of item to create
+     * @param data - Creation configuration
+     * @returns Created model instance
+     * @internal
+     */
+    async _createItem(data) {
+        this._checkDeleted();
+        // Get necessary configuration from SDK
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        if (data.type === ItemTypes.NOTEBOOK) {
+            const requestData = {
+                spaceId: this.uid,
+                name: data.name,
+                description: data.description,
+                notebookType: data.type,
+                file: data.file,
+            };
+            const response = await notebooks.createNotebook(token, requestData, spacerRunUrl);
+            if (!response.notebook) {
+                throw new Error('Failed to create notebook: No notebook returned');
+            }
+            else {
+                return new Notebook(response.notebook, this._sdk);
+            }
+        }
+        else if (data.type === ItemTypes.LEXICAL) {
+            const requestData = {
+                spaceId: this.uid,
+                name: data.name,
+                description: data.description,
+                documentType: data.type,
+                file: data.file,
+            };
+            const response = await lexicals.createLexical(token, requestData, spacerRunUrl);
+            if (!response.document) {
+                throw new Error('Failed to create lexical document: No document returned');
+            }
+            else {
+                return new Lexical(response.document, this._sdk);
+            }
+        }
+        else {
+            throw new Error(`Unsupported item type: ${data.type}`);
+        }
+    }
+    /**
+     * Get all items in this space as model instances.
+     *
+     * @returns Array of Notebook and Lexical model instances
+     */
+    async getItems() {
+        this._checkDeleted();
+        const token = this._sdk.getToken();
+        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const response = await items.getSpaceItems(token, this.uid, spacerRunUrl);
+        // Use shared utility function to convert items to model instances
+        this._items = convertSpaceItemsToModels(response.items || [], this._sdk);
+        return this._items;
+    }
+    /**
+     * Create a new notebook in this space.
+     *
+     * @param data - Notebook creation configuration
+     * @returns Created Notebook instance
+     */
+    async createNotebook(data) {
+        return this._createItem({
+            name: data.name,
+            type: ItemTypes.NOTEBOOK,
+            description: data.description,
+            file: data.file,
+        });
+    }
+    /**
+     * Create a new lexical document in this space.
+     *
+     * @param data - Lexical creation configuration
+     * @returns Created Lexical instance
+     */
+    async createLexical(data) {
+        return this._createItem({
+            name: data.name,
+            type: ItemTypes.LEXICAL,
+            description: data.description,
+            file: data.file,
+        });
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * 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() {
+        this._checkDeleted();
+        const obj = {
+            uid: this.uid,
+            name: this.name,
+            description: this.description,
+            variant: this.variant,
+            handle: this.handle,
+            items: this._data.items
+                ? convertSpaceItemsToModels(this._data.items, this._sdk).map(item => item.toJSON())
+                : [],
+        };
+        validateJSON(obj, 'Space');
+        return obj;
+    }
+    /**
+     * 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() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the space. */
+    toString() {
+        this._checkDeleted();
+        return `Space(${this.uid}, ${this.name})`;
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * User model for the Datalayer SDK with rich functionality.
+ *
+ * @module client/models/User
+ */
+import type { User as UserData } from '../../api/types/iam';
+import type { DatalayerClient } from '../index';
+export interface UserJSON {
+    /** uuid for the user */
+    id: string;
+    /** ulid for the user */
+    uid: string;
+    /** First name of the user */
+    firstName: string;
+    /** Last name of the user */
+    lastName: string;
+    /** Display name of the user */
+    displayName: string;
+    /** Email address of the user */
+    email: string;
+    /** Description of the user */
+    handle: string;
+    /** URL to the user's avatar image */
+    avatarUrl: string;
+}
+/**
+ * User model representing a Datalayer platform user.
+ * Provides rich functionality for accessing user data and authentication providers.
+ */
+export declare class User {
+    protected _data: UserData;
+    /**
+     * Create a User instance.
+     *
+     * @param data - User data from API
+     * @param sdk - SDK instance (currently unused but kept for compatibility)
+     */
+    constructor(data: UserData, sdk?: DatalayerClient);
+    get id(): string;
+    get uid(): string;
+    get email(): string;
+    get handle(): string;
+    get firstName(): string;
+    get lastName(): string;
+    get displayName(): string;
+    get avatarUrl(): string;
+    /**
+     * Get user data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core user data with camelCase properties
+     */
+    toJSON(): UserJSON;
+    /**
+     * Get the raw user data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw user data from API
+     */
+    rawData(): UserData;
+    /** String representation of the user. */
+    toString(): string;
+}

package/lib/client/models/User.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * User model representing a Datalayer platform user.
+ * Provides rich functionality for accessing user data and authentication providers.
+ */
+export class User {
+    _data;
+    /**
+     * Create a User instance.
+     *
+     * @param data - User data from API
+     * @param sdk - SDK instance (currently unused but kept for compatibility)
+     */
+    constructor(data, sdk) {
+        this._data = data;
+    }
+    // Basic properties
+    get id() {
+        return this._data.id;
+    }
+    get uid() {
+        return this._data.uid;
+    }
+    get email() {
+        return this._data.email_s;
+    }
+    get handle() {
+        return this._data.handle_s;
+    }
+    get firstName() {
+        return this._data.first_name_t;
+    }
+    get lastName() {
+        return this._data.last_name_t;
+    }
+    get displayName() {
+        return `${this.firstName} ${this.lastName}`.trim();
+    }
+    get avatarUrl() {
+        return this._data.avatar_url_s;
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get user data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core user data with camelCase properties
+     */
+    toJSON() {
+        const obj = {
+            id: this.id,
+            uid: this.uid,
+            firstName: this.firstName,
+            lastName: this.lastName,
+            displayName: this.displayName,
+            email: this.email,
+            handle: this.handle,
+            avatarUrl: this.avatarUrl,
+        };
+        validateJSON(obj, 'User');
+        return obj;
+    }
+    /**
+     * Get the raw user data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw user data from API
+     */
+    rawData() {
+        return this._data;
+    }
+    /** String representation of the user. */
+    toString() {
+        return `User(${this.uid}, ${this.displayName})`;
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Domain model classes for the Datalayer SDK.
+ * These models wrap API responses with convenient methods and state management.
+ *
+ * @module client/models
+ *
+ * @example
+ * ```typescript
+ * const runtime = await sdk.createRuntime(config);
+ * const snapshot = await runtime.createSnapshot('checkpoint');
+ * ```
+ */
+export { Environment } from './Environment';
+export { Item } from './Item';
+export { Runtime } from './Runtime';
+export { Snapshot } from './Snapshot';
+export { Notebook } from './Notebook';
+export { Lexical } from './Lexical';
+export { Space } from './Space';
+export { Credits } from './Credits';
+export type { EnvironmentJSON } from './Environment';
+export type { RuntimeJSON } from './Runtime';
+export type { SnapshotJSON } from './Snapshot';
+export type { SpaceJSON } from './Space';
+export type { NotebookJSON } from './Notebook';
+export type { LexicalJSON } from './Lexical';

package/lib/client/models/index.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Domain model classes for the Datalayer SDK.
+ * These models wrap API responses with convenient methods and state management.
+ *
+ * @module client/models
+ *
+ * @example
+ * ```typescript
+ * const runtime = await sdk.createRuntime(config);
+ * const snapshot = await runtime.createSnapshot('checkpoint');
+ * ```
+ */
+// Export domain model classes
+export { Environment } from './Environment';
+export { Item } from './Item';
+export { Runtime } from './Runtime';
+export { Snapshot } from './Snapshot';
+export { Notebook } from './Notebook';
+export { Lexical } from './Lexical';
+export { Space } from './Space';
+export { Credits } from './Credits';

package/lib/client/utils/mixins.d.ts

@@ -0,0 +1,12 @@
+/**
+ * TypeScript mixin utilities for composing the DatalayerClient class.
+ * @module client/utils/mixins
+ */
+/** Type for a constructor function that can be used in mixins. */
+export type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Apply mixins to a base class.
+ * @param derivedCtor - The base class to extend
+ * @param constructors - Array of mixin classes to apply
+ */
+export declare function applyMixins(derivedCtor: any, constructors: any[]): void;

package/lib/{sdk/client → client}/utils/mixins.js

@@ -4,36 +4,8 @@
  */
 /**
  * Apply mixins to a base class.
- *
- * This utility function enables multiple inheritance-like behavior in TypeScript
- * by copying properties and methods from mixin classes to the target class.
- *
  * @param derivedCtor - The base class to extend
  * @param constructors - Array of mixin classes to apply
- *
- * @example
- * ```typescript
- * class Base {
- *   baseMethod() { return 'base'; }
- * }
- *
- * class MixinA {
- *   mixinAMethod() { return 'A'; }
- * }
- *
- * class MixinB {
- *   mixinBMethod() { return 'B'; }
- * }
- *
- * interface Combined extends Base, MixinA, MixinB {}
- * class Combined extends Base {}
- * applyMixins(Combined, [MixinA, MixinB]);
- *
- * const instance = new Combined();
- * instance.baseMethod(); // 'base'
- * instance.mixinAMethod(); // 'A'
- * instance.mixinBMethod(); // 'B'
- * ```
  */
 export function applyMixins(derivedCtor, constructors) {
     constructors.forEach(baseCtor => {

package/lib/client/utils/spacerUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility functions for Spacer-related operations to avoid code duplication.
+ * @module client/utils/spacerUtils
+ */
+import type { GetSpaceItemsResponse } from '../../api/types/spacer';
+import type { DatalayerClient } from '../index';
+import { Notebook } from '../models/Notebook';
+import { Lexical } from '../models/Lexical';
+/**
+ * Convert raw space items from API response to model instances.
+ * This utility function is shared between Space.getItems() and SpacerMixin.getSpaceItems()
+ * to avoid code duplication.
+ *
+ * @param response - Raw API response containing space items
+ * @param sdk - SDK instance to pass to model constructors
+ * @returns Array of Notebook and Lexical model instances
+ */
+export declare function convertSpaceItemsToModels(items: GetSpaceItemsResponse['items'], sdk: DatalayerClient): (Notebook | Lexical)[];

package/lib/client/utils/spacerUtils.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { Notebook } from '../models/Notebook';
+import { Lexical } from '../models/Lexical';
+import { ItemTypes } from '../constants';
+/**
+ * Convert raw space items from API response to model instances.
+ * This utility function is shared between Space.getItems() and SpacerMixin.getSpaceItems()
+ * to avoid code duplication.
+ *
+ * @param response - Raw API response containing space items
+ * @param sdk - SDK instance to pass to model constructors
+ * @returns Array of Notebook and Lexical model instances
+ */
+export function convertSpaceItemsToModels(items, sdk) {
+    const modelItems = [];
+    for (const item of items) {
+        // Check various possible type fields
+        const itemType = item.type_s;
+        // Only include notebooks and lexicals
+        if (itemType === ItemTypes.NOTEBOOK) {
+            modelItems.push(new Notebook(item, sdk));
+        }
+        else if (itemType === ItemTypes.LEXICAL) {
+            modelItems.push(new Lexical(item, sdk));
+        }
+        // Skip everything else (exercises, cells, etc.)
+    }
+    return modelItems;
+}

package/lib/collaboration/DatalayerCollaboration.d.ts

@@ -1,9 +1,14 @@
 type IFetchSessionId = {
     url: string;
     token?: string;
+    /**
+     * Custom fetch function to use instead of global fetch.
+     * Useful for proxying requests in environments with CORS restrictions (e.g., VS Code webviews).
+     */
+    fetchFn?: typeof fetch;
 };
 /**
  * Fetch the session ID of a collaborative documents from Datalayer.
  */
-export declare function requestDatalayerCollaborationSessionId({ url, token, }: IFetchSessionId): Promise<string>;
+export declare function requestDatalayerCollaborationSessionId({ url, token, fetchFn, }: IFetchSessionId): Promise<string>;
 export {};

package/lib/collaboration/DatalayerCollaboration.js

@@ -5,14 +5,14 @@
 /**
  * Fetch the session ID of a collaborative documents from Datalayer.
  */
-export async function requestDatalayerCollaborationSessionId({ url, token, }) {
+export async function requestDatalayerCollaborationSessionId({ url, token, fetchFn = fetch, }) {
     const headers = {
         Accept: 'application/json',
     };
     if (token) {
         headers['Authorization'] = `Bearer ${token}`;
     }
-    const response = await fetch(url, {
+    const response = await fetchFn(url, {
         method: 'GET',
         headers,
         credentials: token ? 'include' : 'omit',

package/lib/collaboration/DatalayerCollaborationProvider.d.ts

@@ -19,6 +19,11 @@ export interface IDatalayerCollaborationConfig {
      * Authentication token (optional, uses config from store if not provided)
      */
     token?: string;
+    /**
+     * Custom fetch function to use for HTTP requests.
+     * Useful for proxying requests in environments with CORS restrictions (e.g., VS Code webviews).
+     */
+    fetchFn?: typeof fetch;
 }
 /**
  * Datalayer collaboration provider

package/lib/collaboration/DatalayerCollaborationProvider.js

@@ -14,7 +14,6 @@ var CollaborationStatus;
     CollaborationStatus["Error"] = "error";
 })(CollaborationStatus || (CollaborationStatus = {}));
 import { requestDatalayerCollaborationSessionId } from './DatalayerCollaboration';
-import { coreStore } from '../state/substates/CoreState';
 /**
  * Datalayer collaboration provider
  *
@@ -64,24 +63,26 @@ export class DatalayerCollaborationProvider {
         }
         this.setStatus(CollaborationStatus.Connecting);
         try {
-            // Get configuration from store or use provided config
-            const { configuration } = coreStore.getState();
-            const runUrl = this._config.runUrl ?? configuration?.runUrl;
-            const token = this._config.token ?? configuration?.token;
+            // Use ONLY explicitly provided configuration
+            // NO fallback to coreStore - if config is wrong, we want to fail fast
+            // This is critical for VS Code extension where config must come from settings
+            const runUrl = this._config.runUrl;
+            const token = this._config.token;
             if (!runUrl) {
-                throw new Error('Datalayer runUrl is not configured');
+                throw new Error('Datalayer runUrl is not configured - must be explicitly provided in DatalayerCollaborationProvider config');
             }
             if (!token) {
-                throw new Error('Datalayer token is not configured');
+                throw new Error('Datalayer token is not configured - must be explicitly provided in DatalayerCollaborationProvider config');
             }
             const { ydoc, awareness } = sharedModel;
-            // Build WebSocket URL
+            // Build URLs.
             const documentURL = URLExt.join(runUrl, '/api/spacer/v1/documents');
-            const wsUrl = documentURL.replace(/^http/, 'ws');
+            const wsUrl = URLExt.join(runUrl, '/api/spacer/v1/documents/ws').replace(/^http/, 'ws');
             // Request collaboration session from Datalayer
             const sessionId = await requestDatalayerCollaborationSessionId({
                 url: URLExt.join(documentURL, documentId),
                 token,
+                fetchFn: this._config.fetchFn,
             });
             // Create WebSocket provider
             this._provider = new WebsocketProvider(wsUrl, documentId, ydoc, {

package/lib/components/progress/CreditsIndicator.d.ts

@@ -1,4 +1,4 @@
-import type { IRemoteServicesManager } from '../../sdk/stateful/runtimes';
+import type { IRemoteServicesManager } from '../../stateful/runtimes';
 type ICreditsIndicatorProps = {
     /**
      * Kernel service manager

package/lib/components/runtimes/RuntimeCellVariablesDialog.js

@@ -8,7 +8,7 @@ import { Dialog } from '@primer/react/experimental';
 import { nullTranslator } from '@jupyterlab/translation';
 import { JSONExt } from '@lumino/coreutils';
 import { KernelExecutor } from '@datalayer/jupyter-react';
-import { RuntimeSnippetsFacade } from '../../sdk/stateful/jupyter';
+import { RuntimeSnippetsFacade } from '../../stateful/jupyter';
 import { RuntimeCellVariables } from './RuntimeCellVariables';
 /**
  * Dialog to define the runtime cell variables to transfer

package/lib/components/runtimes/RuntimeLauncherDialog.d.ts

@@ -1,5 +1,5 @@
 import type { IMarkdownParser, IRenderMime } from '@jupyterlab/rendermime';
-import type { IRemoteServicesManager } from '../../sdk/stateful/runtimes';
+import type { IRemoteServicesManager } from '../../stateful/runtimes';
 import type { IRuntimeSnapshot, IRuntimeDesc } from '../../models';
 /**
  * {@link RuntimeLauncherDialog} properties.

package/lib/components/runtimes/RuntimePickerBase.d.ts

@@ -2,7 +2,7 @@ import { ReactElement, ReactNode } from 'react';
 import { ISessionContext } from '@jupyterlab/apputils';
 import { ITranslator } from '@jupyterlab/translation';
 import { IRuntimeDesc } from '../../models';
-import { IMultiServiceManager } from '../../sdk/stateful/runtimes';
+import { IMultiServiceManager } from '../../stateful/runtimes';
 type IDisplayMode = 'menu' | 'radio';
 /**
  * {@link RuntimePickerBase} properties

package/lib/components/runtimes/RuntimePickerBase.js

@@ -12,7 +12,7 @@ import { Box } from '@datalayer/primer-addons';
 import { CpuIcon } from '@primer/octicons-react';
 import { BrowserIcon, LaptopSimpleIcon } from '@datalayer/icons-react';
 import { CreditsIndicator } from '../../components/progress';
-import { isRuntimeRemote, } from '../../sdk/stateful/runtimes';
+import { isRuntimeRemote } from '../../stateful/runtimes';
 import { getGroupedRuntimeDescs } from './RuntimeUtils';
 /**
  * Maximal runtime display name length after which it is trimmed.