@datalayer/core 0.0.12 → 0.0.13

package/lib/api/types/spacer.d.ts

@@ -3,27 +3,14 @@
  * @interface Space
  */
 export interface Space {
-    id?: string;
     uid: string;
-    name?: string;
-    name_t?: string;
-    handle_s?: string;
-    variant_s?: string;
-    description?: string;
-    description_t?: string;
-    visibility?: 'public' | 'private' | 'organization';
-    owner_id?: string;
-    organization_id?: string;
-    created_at?: string;
-    updated_at?: string;
-    creation_ts_dt?: string;
-    last_update_ts_dt?: string;
-    notebooks_count?: number;
-    members_count?: number;
-    tags?: string[];
+    name_t: string;
+    handle_s: string;
+    variant_s: string;
+    description_t: string;
     tags_ss?: string[];
-    items?: any[];
     members?: any[];
+    items?: any[];
 }
 /**
  * Represents a Jupyter notebook document
@@ -32,46 +19,13 @@ export interface Space {
 export interface Notebook {
     id: string;
     uid: string;
-    name?: string;
-    name_t?: string;
-    path?: string;
-    content?: any;
-    space_id?: string;
-    owner_id?: string;
-    creator_uid?: string;
-    creator_handle_s?: string;
-    created_at?: string;
-    creation_ts_dt?: string;
-    updated_at?: string;
-    last_update_ts_dt?: string;
-    version?: number;
-    kernel_spec?: any;
-    metadata?: Record<string, any>;
-    type_s?: string;
-    public_b?: boolean;
-    description_t?: string;
-    notebook_name_s?: string;
-    notebook_extension_s?: string;
-    notebook_format_s?: string;
-    content_length_i?: number;
-    content_type_s?: string;
-    mime_type_s?: string;
-    s3_path_s?: string;
-    s3_url_s?: string;
-    cdn_url_s?: string;
-    model_s?: string;
-}
-/**
- * Represents a single cell in a Jupyter notebook
- * @interface Cell
- */
-export interface Cell {
-    id: string;
-    cell_type: 'code' | 'markdown' | 'raw';
-    source: string | string[];
-    outputs?: any[];
-    execution_count?: number | null;
-    metadata?: Record<string, any>;
+    name_t: string;
+    description_t: string;
+    type_s: string;
+    notebook_extension_s: string;
+    s3_path_s: string;
+    s3_url_s: string;
+    cdn_url_s: string;
 }
 /**
  * Request payload for creating a new space
@@ -86,6 +40,15 @@ export interface CreateSpaceRequest {
     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
@@ -93,7 +56,7 @@ export interface CreateSpaceRequest {
 export interface CreateSpaceResponse {
     success: boolean;
     message: string;
-    space: Space;
+    space?: Space;
 }
 /**
  * Request payload for creating a new notebook (multipart/form-data)
@@ -113,7 +76,7 @@ export interface CreateNotebookRequest {
 export interface CreateNotebookResponse {
     success: boolean;
     message: string;
-    notebook: Notebook;
+    notebook?: Notebook;
 }
 /**
  * Response from getting a notebook
@@ -150,7 +113,7 @@ export interface UpdateNotebookRequest {
 export interface UpdateNotebookResponse {
     success: boolean;
     message: string;
-    notebook: Notebook;
+    notebook?: Notebook;
 }
 /**
  * Represents an item within a space
@@ -158,7 +121,7 @@ export interface UpdateNotebookResponse {
  */
 export interface SpaceItem {
     id: string;
-    type: 'notebook' | 'lexical' | 'cell';
+    type_s: 'notebook' | 'lexical';
     space_id: string;
     item_id: string;
     name: string;
@@ -183,18 +146,18 @@ export interface Lexical {
     creation_ts_dt?: string;
     updated_at?: string;
     last_update_ts_dt?: string;
+    cdn_url_s: string;
     type_s?: string;
     public_b?: boolean;
     description_t?: string;
     document_name_s?: string;
-    document_extension_s?: string;
+    document_extension_s: string;
     document_format_s?: string;
     content_length_i?: number;
     content_type_s?: string;
     mime_type_s?: string;
     s3_path_s?: string;
     s3_url_s?: string;
-    cdn_url_s?: string;
     model_s?: string;
 }
 /**
@@ -215,7 +178,7 @@ export interface CreateLexicalRequest {
 export interface CreateLexicalResponse {
     success: boolean;
     message: string;
-    document: Lexical;
+    document?: Lexical;
 }
 /**
  * Response from getting a Lexical document
@@ -260,6 +223,15 @@ 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

package/lib/api/utils/validation.d.ts

@@ -1,6 +1,7 @@
 /**
+ * Utility functions for API parameter validation
+ *
  * @module api/utils/validation
- * @description Utility functions for API parameter validation
  */
 /**
  * Validates that an authentication token is provided and is a valid JWT format
@@ -22,3 +23,25 @@ export declare const validateRequired: (value: any, paramName: string) => void;
  * @throws {Error} If the value is missing, null, undefined, or empty/whitespace
  */
 export declare const validateRequiredString: (value: string | undefined | null, paramName: string) => void;
+/**
+ * Validates that all properties in an object are defined (not undefined).
+ * Recursively checks nested objects and arrays to ensure complete data integrity.
+ * This is used to validate model toJSON() outputs and ensure SDK contract compliance.
+ *
+ * @param obj - The object to validate
+ * @param modelName - Name of the model class for error messages (e.g., 'Runtime')
+ * @param path - Current property path for recursive validation (internal use)
+ * @throws {Error} If any property value is undefined, with full path to the undefined property
+ *
+ * @example
+ * ```typescript
+ * const runtimeData = {
+ *   uid: 'abc123',
+ *   podName: 'my-pod',
+ *   environmentName: undefined  // This will throw
+ * };
+ * validateJSON(runtimeData, 'Runtime');
+ * // Error: Runtime.toJSON(): Property 'environmentName' is undefined
+ * ```
+ */
+export declare const validateJSON: (obj: Record<string, any>, modelName: string, path?: string) => void;

package/lib/api/utils/validation.js

@@ -3,8 +3,9 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
+ * Utility functions for API parameter validation
+ *
  * @module api/utils/validation
- * @description Utility functions for API parameter validation
  */
 /**
  * Validates that an authentication token is provided and is a valid JWT format
@@ -131,3 +132,63 @@ export const validateRequiredString = (value, paramName) => {
         throw new Error(`${paramName} is required`);
     }
 };
+/**
+ * Validates that all properties in an object are defined (not undefined).
+ * Recursively checks nested objects and arrays to ensure complete data integrity.
+ * This is used to validate model toJSON() outputs and ensure SDK contract compliance.
+ *
+ * @param obj - The object to validate
+ * @param modelName - Name of the model class for error messages (e.g., 'Runtime')
+ * @param path - Current property path for recursive validation (internal use)
+ * @throws {Error} If any property value is undefined, with full path to the undefined property
+ *
+ * @example
+ * ```typescript
+ * const runtimeData = {
+ *   uid: 'abc123',
+ *   podName: 'my-pod',
+ *   environmentName: undefined  // This will throw
+ * };
+ * validateJSON(runtimeData, 'Runtime');
+ * // Error: Runtime.toJSON(): Property 'environmentName' is undefined
+ * ```
+ */
+export const validateJSON = (obj, modelName, path = '') => {
+    // Iterate over all enumerable properties
+    for (const key in obj) {
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+            continue;
+        }
+        const value = obj[key];
+        const currentPath = path ? `${path}.${key}` : key;
+        // Check if value is undefined - this is the error case
+        if (value === undefined) {
+            throw new Error(`${modelName}.toJSON(): Property '${currentPath}' is undefined`);
+        }
+        // Skip null, functions, and symbols - these are valid
+        if (value === null ||
+            typeof value === 'function' ||
+            typeof value === 'symbol') {
+            continue;
+        }
+        // Recursively validate arrays
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => {
+                if (item === undefined) {
+                    throw new Error(`${modelName}.toJSON(): Array element at '${currentPath}[${index}]' is undefined`);
+                }
+                // If array element is an object, recurse into it
+                if (item !== null && typeof item === 'object') {
+                    validateJSON(item, modelName, `${currentPath}[${index}]`);
+                }
+            });
+            continue;
+        }
+        // Recursively validate nested objects
+        // Note: typeof null === 'object', but we already checked for null above
+        if (typeof value === 'object') {
+            validateJSON(value, modelName, currentPath);
+        }
+        // Primitives (string, number, boolean) are valid - no further checks needed
+    }
+};

package/lib/client/base.d.ts

@@ -0,0 +1,75 @@
+import { Environment } from './models/Environment';
+/** Handlers for SDK method lifecycle events. */
+export interface SDKHandlers {
+    /** Called before any SDK method execution */
+    beforeCall?: (methodName: string, args: any[]) => void | Promise<void>;
+    /** Called after successful SDK method execution */
+    afterCall?: (methodName: string, result: any) => void | Promise<void>;
+    /** Called when an SDK method throws an error */
+    onError?: (methodName: string, error: any) => void | Promise<void>;
+}
+/** Configuration options for the Datalayer Client. */
+export interface DatalayerClientConfig {
+    /** Authentication token for API requests */
+    token?: string;
+    /** URL for the IAM service */
+    iamRunUrl?: string;
+    /** URL for the Runtimes service */
+    runtimesRunUrl?: string;
+    /** URL for the Spacer service */
+    spacerRunUrl?: string;
+    /** Handlers for intercepting SDK method calls */
+    handlers?: SDKHandlers;
+}
+/** Base Client class providing core configuration and token management. */
+export declare class DatalayerClientBase {
+    /** URL for IAM service */
+    readonly iamRunUrl: string;
+    /** URL for Runtimes service */
+    readonly runtimesRunUrl: string;
+    /** URL for Spacer service */
+    readonly spacerRunUrl: string;
+    /** Authentication token */
+    token?: string;
+    /** Environments */
+    readonly environments: Environment[];
+    /** Method lifecycle handlers */
+    readonly handlers?: SDKHandlers;
+    /**
+     * Create a DatalayerClient base instance.
+     * @param config - Client configuration options
+     */
+    constructor(config: DatalayerClientConfig);
+    /**
+     * Get the current configuration including service URLs and token.
+     * @returns Current configuration
+     */
+    getConfig(): DatalayerClientConfig;
+    /** Get the IAM service URL. */
+    getIamRunUrl(): string;
+    /** Get the Runtimes service URL. */
+    getRuntimesRunUrl(): string;
+    /** Get the Spacer service URL. */
+    getSpacerRunUrl(): string;
+    /** Get the current authentication token. */
+    getToken(): string | undefined;
+    /**
+     * set the authentication token for all API requests.
+     * @param token - New authentication token
+     */
+    setToken(token: string): Promise<void>;
+    /**
+     * Wrap all SDK methods with handlers for cross-cutting concerns.
+     * Called automatically by the DatalayerClient constructor.
+     *
+     * @internal
+     */
+    protected wrapAllMethods(): void;
+    /**
+     * Get all method names from mixins only.
+     * @returns Array of mixin method names to wrap
+     * @internal
+     */
+    private getAllMethodNames;
+    calculateCreditsFromMinutes(minutes: number, burningRate: number): number;
+}

package/lib/client/base.js

@@ -0,0 +1,199 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Base SDK class providing core configuration and token management.
+ * @module client/base
+ */
+import { DEFAULT_SERVICE_URLS } from '../api/constants';
+/** Base Client class providing core configuration and token management. */
+export class DatalayerClientBase {
+    /** URL for IAM service */
+    iamRunUrl;
+    /** URL for Runtimes service */
+    runtimesRunUrl;
+    /** URL for Spacer service */
+    spacerRunUrl;
+    /** Authentication token */
+    token;
+    /** Environments */
+    environments = [];
+    /** Method lifecycle handlers */
+    handlers;
+    /**
+     * Create a DatalayerClient base instance.
+     * @param config - Client configuration options
+     */
+    constructor(config) {
+        this.iamRunUrl = config.iamRunUrl || DEFAULT_SERVICE_URLS.IAM;
+        this.runtimesRunUrl =
+            config.runtimesRunUrl || DEFAULT_SERVICE_URLS.RUNTIMES;
+        this.spacerRunUrl = config.spacerRunUrl || DEFAULT_SERVICE_URLS.SPACER;
+        this.token = config.token;
+        this.handlers = config.handlers;
+    }
+    /**
+     * Get the current configuration including service URLs and token.
+     * @returns Current configuration
+     */
+    getConfig() {
+        return {
+            iamRunUrl: this.iamRunUrl,
+            runtimesRunUrl: this.runtimesRunUrl,
+            spacerRunUrl: this.spacerRunUrl,
+            token: this.token,
+        };
+    }
+    /** Get the IAM service URL. */
+    getIamRunUrl() {
+        return this.iamRunUrl;
+    }
+    /** Get the Runtimes service URL. */
+    getRuntimesRunUrl() {
+        return this.runtimesRunUrl;
+    }
+    /** Get the Spacer service URL. */
+    getSpacerRunUrl() {
+        return this.spacerRunUrl;
+    }
+    /** Get the current authentication token. */
+    getToken() {
+        return this.token;
+    }
+    /**
+     * set the authentication token for all API requests.
+     * @param token - New authentication token
+     */
+    async setToken(token) {
+        this.token = token;
+    }
+    /**
+     * Wrap all SDK methods with handlers for cross-cutting concerns.
+     * Called automatically by the DatalayerClient constructor.
+     *
+     * @internal
+     */
+    wrapAllMethods() {
+        if (!this.handlers) {
+            return; // No handlers configured, nothing to wrap
+        }
+        // Get all method names from the prototype chain
+        const methodNames = this.getAllMethodNames();
+        // Wrap each method with handlers
+        methodNames.forEach(methodName => {
+            const original = this[methodName];
+            if (typeof original !== 'function') {
+                return;
+            }
+            // Detect if the original method is async by checking if it's an AsyncFunction
+            const isAsync = original.constructor.name === 'AsyncFunction';
+            if (isAsync) {
+                // Create async wrapped version for originally async methods
+                this[methodName] = async (...args) => {
+                    // Call beforeCall handler if defined
+                    if (this.handlers?.beforeCall) {
+                        await Promise.resolve(this.handlers.beforeCall(methodName, args));
+                    }
+                    try {
+                        // Call the original async method
+                        const result = await original.apply(this, args);
+                        // Call afterCall handler if defined
+                        if (this.handlers?.afterCall) {
+                            await Promise.resolve(this.handlers.afterCall(methodName, result));
+                        }
+                        return result;
+                    }
+                    catch (error) {
+                        // Call onError handler if defined
+                        if (this.handlers?.onError) {
+                            await Promise.resolve(this.handlers.onError(methodName, error));
+                        }
+                        throw error;
+                    }
+                };
+            }
+            else {
+                // Create sync wrapped version for originally sync methods
+                this[methodName] = (...args) => {
+                    // Call beforeCall handler if defined (sync version)
+                    if (this.handlers?.beforeCall) {
+                        const beforeResult = this.handlers.beforeCall(methodName, args);
+                        // If beforeCall returns a Promise, we can't await it in sync context
+                        if (beforeResult instanceof Promise) {
+                            // Promise ignored in sync context
+                        }
+                    }
+                    try {
+                        // Call the original sync method
+                        const result = original.apply(this, args);
+                        // Call afterCall handler if defined (sync version)
+                        if (this.handlers?.afterCall) {
+                            const afterResult = this.handlers.afterCall(methodName, result);
+                            if (afterResult instanceof Promise) {
+                                // Promise ignored in sync context
+                            }
+                        }
+                        return result;
+                    }
+                    catch (error) {
+                        // Call onError handler if defined (sync version)
+                        if (this.handlers?.onError) {
+                            const errorResult = this.handlers.onError(methodName, error);
+                            if (errorResult instanceof Promise) {
+                                // Promise ignored in sync context
+                            }
+                        }
+                        throw error;
+                    }
+                };
+            }
+        });
+    }
+    /**
+     * Get all method names from mixins only.
+     * @returns Array of mixin method names to wrap
+     * @internal
+     */
+    getAllMethodNames() {
+        const methodNames = new Set();
+        // First, collect all base class methods to exclude
+        const baseClassMethods = new Set();
+        const basePrototype = DatalayerClientBase.prototype;
+        Object.getOwnPropertyNames(basePrototype).forEach(name => {
+            baseClassMethods.add(name);
+        });
+        // Also exclude methods from the concrete SDK class itself
+        const sdkPrototype = Object.getPrototypeOf(this).constructor.prototype;
+        Object.getOwnPropertyNames(sdkPrototype).forEach(name => {
+            baseClassMethods.add(name);
+        });
+        // Now walk the prototype chain and only include mixin methods
+        let obj = Object.getPrototypeOf(this);
+        while (obj && obj !== Object.prototype) {
+            const names = Object.getOwnPropertyNames(obj);
+            names.forEach(name => {
+                // Only include if:
+                // 1. Not a constructor
+                // 2. Not a private method (starts with _)
+                // 3. Not a base class method
+                // 4. Is actually a function
+                if (name !== 'constructor' &&
+                    !name.startsWith('_') &&
+                    !baseClassMethods.has(name)) {
+                    const descriptor = Object.getOwnPropertyDescriptor(obj, name);
+                    if (descriptor && typeof descriptor.value === 'function') {
+                        methodNames.add(name);
+                    }
+                }
+            });
+            obj = Object.getPrototypeOf(obj);
+        }
+        return Array.from(methodNames);
+    }
+    // Utility Methods
+    calculateCreditsFromMinutes(minutes, burningRate) {
+        const burningRatePerMinute = burningRate * 60;
+        return Math.ceil(minutes * burningRatePerMinute);
+    }
+}

package/lib/client/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Constants for the Datalayer SDK.
+ *
+ * @module client/constants
+ */
+/**
+ * Item types used throughout the SDK and consuming applications.
+ * These constants define the type identifiers for different Datalayer items.
+ * Values match what the Datalayer API returns.
+ */
+export declare const ItemTypes: {
+    readonly NOTEBOOK: "notebook";
+    readonly LEXICAL: "document";
+    readonly EXERCISE: "exercise";
+    readonly CELL: "cell";
+    readonly SPACE: "space";
+    readonly UNKNOWN: "unknown";
+};
+/**
+ * Type representing valid item types.
+ */
+export type ItemType = (typeof ItemTypes)[keyof typeof ItemTypes];

package/lib/client/constants.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Constants for the Datalayer SDK.
+ *
+ * @module client/constants
+ */
+/**
+ * Item types used throughout the SDK and consuming applications.
+ * These constants define the type identifiers for different Datalayer items.
+ * Values match what the Datalayer API returns.
+ */
+export const ItemTypes = {
+    NOTEBOOK: 'notebook',
+    LEXICAL: 'document',
+    EXERCISE: 'exercise',
+    CELL: 'cell',
+    SPACE: 'space',
+    UNKNOWN: 'unknown',
+};