@datalayer/core 0.0.12 → 0.0.14

package/lib/api/runtimes/snapshots.d.ts

@@ -1,4 +1,4 @@
-import { CreateRuntimeSnapshotRequest, SnapshotsListResponse, SnapshotGetResponse, SnapshotCreateResponse } from '../types/runtimes';
+import { CreateRuntimeSnapshotRequest, ListRuntimeSnapshotsResponse, GetRuntimeSnapshotResponse, CreateRuntimeSnapshotResponse } from '../../models/RuntimeSnapshotDTO';
 /**
  * Create a snapshot of a runtime instance.
  * @param token - Authentication token
@@ -7,7 +7,7 @@ import { CreateRuntimeSnapshotRequest, SnapshotsListResponse, SnapshotGetRespons
  * @returns Promise resolving to the created snapshot response
  * @throws {Error} If authentication token is missing or invalid
  */
-export declare const createSnapshot: (token: string, data: CreateRuntimeSnapshotRequest, baseUrl?: string) => Promise<SnapshotCreateResponse>;
+export declare const createSnapshot: (token: string, data: CreateRuntimeSnapshotRequest, baseUrl?: string) => Promise<CreateRuntimeSnapshotResponse>;
 /**
  * List all runtime snapshots.
  * @param token - Authentication token
@@ -15,7 +15,7 @@ export declare const createSnapshot: (token: string, data: CreateRuntimeSnapshot
  * @returns Promise resolving to list of snapshots
  * @throws {Error} If authentication token is missing or invalid
  */
-export declare const listSnapshots: (token: string, baseUrl?: string) => Promise<SnapshotsListResponse>;
+export declare const listSnapshots: (token: string, baseUrl?: string) => Promise<ListRuntimeSnapshotsResponse>;
 /**
  * Get details for a specific runtime snapshot.
  * @param token - Authentication token
@@ -25,7 +25,7 @@ export declare const listSnapshots: (token: string, baseUrl?: string) => Promise
  * @throws {Error} If authentication token is missing or invalid
  * @throws {Error} If snapshot ID is missing or invalid
  */
-export declare const getSnapshot: (token: string, snapshotId: string, baseUrl?: string) => Promise<SnapshotGetResponse>;
+export declare const getSnapshot: (token: string, snapshotId: string, baseUrl?: string) => Promise<GetRuntimeSnapshotResponse>;
 /**
  * Delete a runtime snapshot.
  * @param token - Authentication token

package/lib/api/runtimes/snapshots.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/runtimes/snapshots
- * @description Runtime snapshots API functions for the Datalayer platform.
+ * Runtime snapshots API functions for the Datalayer platform.
  *
  * Provides functions for managing runtime snapshots (saved runtime states).
+ *
+ * @module api/runtimes/snapshots
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';

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

@@ -0,0 +1,12 @@
+import { CollaborationSessionResponse } from '../../models/SpaceDTO';
+/**
+ * Get collaboration session ID for a document.
+ *
+ * This function attempts to retrieve the collaboration session ID from the document API.
+ *
+ * @param token - Authentication token
+ * @param documentId - Document UID
+ * @param baseUrl - Base URL for the API (defaults to production)
+ * @returns Promise resolving to collaboration session response
+ */
+export declare const getCollaborationSessionId: (token: string, documentId: string, baseUrl?: string) => Promise<CollaborationSessionResponse>;

package/lib/api/spacer/documents.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Documents API functions for the Datalayer platform.
+ *
+ * Provides functions for document operations including collaboration session management.
+ *
+ * @module api/spacer/documents
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+/**
+ * Get collaboration session ID for a document.
+ *
+ * This function attempts to retrieve the collaboration session ID from the document API.
+ *
+ * @param token - Authentication token
+ * @param documentId - Document UID
+ * @param baseUrl - Base URL for the API (defaults to production)
+ * @returns Promise resolving to collaboration session response
+ */
+export const getCollaborationSessionId = async (token, documentId, baseUrl = DEFAULT_SERVICE_URLS.SPACER) => {
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.SPACER}/documents/${documentId}`,
+            method: 'GET',
+            token,
+        });
+        return {
+            success: true,
+            sessionId: response.sessionId || documentId, // FIXME: is this ok?
+        };
+    }
+    catch (error) {
+        // FIXME: is this ok?
+        return {
+            success: true,
+            sessionId: documentId,
+        };
+    }
+};

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

@@ -1,25 +1,15 @@
-/**
- * Health check response from the Spacer service
- */
-export interface SpacerHealthzPingResponse {
-    success: boolean;
-    message: string;
-    status?: {
-        status: string;
-    };
-    version?: string;
-}
+import type { HealthzPingResponse } from '../../models/Common';
 /**
  * Health check ping endpoint for Spacer service
  * @param baseUrl - Base URL for the API (defaults to production Spacer URL)
  * @returns Health check response
  * @throws {Error} If the health check fails
  *
- * @description
+ * @remarks
  * This endpoint provides a basic health check for the Spacer service.
  * It returns the current status of the service.
  *
  * Expected status codes:
  * - 200: Service is healthy
  */
-export declare const ping: (baseUrl?: string) => Promise<SpacerHealthzPingResponse>;
+export declare const ping: (baseUrl?: string) => Promise<HealthzPingResponse>;

package/lib/api/spacer/healthz.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer/healthz
- * @description Health check API functions for the Datalayer Spacer service.
+ * Health check API functions for the Datalayer Spacer service.
  *
  * Provides functions for checking the health status of the Spacer service.
+ *
+ * @module api/spacer/healthz
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
@@ -16,7 +17,7 @@ import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
  * @returns Health check response
  * @throws {Error} If the health check fails
  *
- * @description
+ * @remarks
  * This endpoint provides a basic health check for the Spacer service.
  * It returns the current status of the service.
  *

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

@@ -1,10 +1,12 @@
 /**
- * @module api/spacer
- * @description Spacer API exports.
+ * Spacer API exports.
  *
  * Provides organized access to spacer functionality including
  * spaces, notebooks, cells, and lexical documents.
+ *
+ * @module api/spacer
  */
+export * as documents from './documents';
 export * as healthz from './healthz';
 export * as items from './items';
 export * as lexicals from './lexicals';

package/lib/api/spacer/index.js

@@ -3,12 +3,14 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer
- * @description Spacer API exports.
+ * Spacer API exports.
  *
  * Provides organized access to spacer functionality including
  * spaces, notebooks, cells, and lexical documents.
+ *
+ * @module api/spacer
  */
+export * as documents from './documents';
 export * as healthz from './healthz';
 export * as items from './items';
 export * as lexicals from './lexicals';

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

@@ -1,4 +1,4 @@
-import { DeleteSpaceItemResponse, GetSpaceItemsResponse } from '../types/spacer';
+import { DeleteSpaceItemResponse, GetSpaceItemResponse, GetSpaceItemsResponse } from '../../models/SpaceDTO';
 /**
  * Get the items of a space.
  * @param token - Authentication token
@@ -7,6 +7,14 @@ import { DeleteSpaceItemResponse, GetSpaceItemsResponse } from '../types/spacer'
  * @returns Promise resolving to the items response
  */
 export declare const getSpaceItems: (token: string, spaceId: string, baseUrl?: string) => Promise<GetSpaceItemsResponse>;
+/**
+ * Get a single item from a space.
+ * @param token - Authentication token
+ * @param id - The item ID to retrieve
+ * @param baseUrl - Base URL for the API (defaults to production)
+ * @returns Promise resolving to the item response
+ */
+export declare const getItem: (token: string, id: string, baseUrl?: string) => Promise<GetSpaceItemResponse>;
 /**
  * Delete an item from a space.
  * @param token - Authentication token

package/lib/api/spacer/items.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer/items
- * @description Items API functions for the Datalayer platform.
+ * Items API functions for the Datalayer platform.
  *
  * Provides functions for managing items in spaces.
+ *
+ * @module api/spacer/items
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
@@ -24,6 +25,20 @@ export const getSpaceItems = async (token, spaceId, baseUrl = DEFAULT_SERVICE_UR
         token,
     });
 };
+/**
+ * Get a single item from a space.
+ * @param token - Authentication token
+ * @param id - The item ID to retrieve
+ * @param baseUrl - Base URL for the API (defaults to production)
+ * @returns Promise resolving to the item response
+ */
+export const getItem = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.SPACER) => {
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.SPACER}/spaces/items/${id}`,
+        method: 'GET',
+        token,
+    });
+};
 /**
  * Delete an item from a space.
  * @param token - Authentication token

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

@@ -1,4 +1,4 @@
-import { CreateLexicalRequest, CreateLexicalResponse, GetLexicalResponse, UpdateLexicalRequest, UpdateLexicalResponse } from '../types/spacer';
+import { CreateLexicalRequest, CreateLexicalResponse, GetLexicalResponse, UpdateLexicalRequest, UpdateLexicalResponse } from '../../models/LexicalDTO';
 /**
  * Create a new lexical document.
  * @param token - Authentication token

package/lib/api/spacer/lexicals.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer/lexicals
- * @description Lexical documents API functions for the Datalayer platform.
+ * Lexical documents API functions for the Datalayer platform.
  *
  * Provides functions for creating, retrieving, and updating lexical (rich text) documents.
+ *
+ * @module api/spacer/lexicals
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';

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

@@ -1,4 +1,4 @@
-import { CreateNotebookRequest, CreateNotebookResponse, GetNotebookResponse, UpdateNotebookRequest, UpdateNotebookResponse } from '../types/spacer';
+import { CreateNotebookRequest, CreateNotebookResponse, GetNotebookResponse, UpdateNotebookRequest, UpdateNotebookResponse } from '../../models/SpaceDTO';
 /**
  * Create a new Jupyter notebook.
  * @param token - Authentication token

package/lib/api/spacer/notebooks.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer/notebooks
- * @description Jupyter notebooks API functions for the Datalayer platform.
+ * Jupyter notebooks API functions for the Datalayer platform.
  *
  * Provides functions for creating and retrieving Jupyter notebooks within workspaces.
+ *
+ * @module api/spacer/notebooks
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';

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

@@ -1,4 +1,4 @@
-import { CreateSpaceRequest, CreateSpaceResponse } from '../types/spacer';
+import { CreateSpaceRequest, CreateSpaceResponse } from '../../models/SpaceDTO';
 /**
  * Create a new workspace space.
  * @param token - Authentication token

package/lib/api/spacer/spaces.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer/spaces
- * @description Workspace spaces API functions for the Datalayer platform.
+ * Workspace spaces API functions for the Datalayer platform.
  *
  * Provides function for creating workspace spaces.
+ *
+ * @module api/spacer/spaces
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';

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

@@ -1,4 +1,4 @@
-import { SpacesForUserResponse } from '../types/spacer';
+import { SpacesForUserResponse } from '../../models/SpaceDTO';
 /**
  * Get all spaces for the current authenticated user.
  * @param token - Authentication token

package/lib/api/spacer/users.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/spacer/users
- * @description User-related Spacer API functions for the Datalayer platform.
+ * User-related Spacer API functions for the Datalayer platform.
  *
  * Provides functions for user-specific operations in the Spacer service.
+ *
+ * @module api/spacer/users
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';

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 { EnvironmentDTO } from '../models/EnvironmentDTO';
+/** 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: EnvironmentDTO[];
+    /** 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;
+}