@datalayer/core 0.0.9 → 0.0.11

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

@@ -0,0 +1,192 @@
+/**
+ * @module sdk/client
+ * @description Main Datalayer SDK client with intuitive mixin-based API.
+ *
+ * The DatalayerSDK class provides a unified, flat API for all Datalayer platform
+ * services through TypeScript mixins. This design offers the best discoverability
+ * and ease of use compared to nested service objects.
+ *
+ * @example
+ * ```typescript
+ * import { DatalayerSDK } from '@datalayer/core/sdk';
+ *
+ * // Initialize SDK
+ * const sdk = new DatalayerSDK({
+ *   token: 'your-api-token',
+ *   baseUrl: 'https://prod1.datalayer.run'
+ * });
+ *
+ * // Flat, intuitive API
+ * const user = await sdk.whoami();
+ * const environments = await sdk.listEnvironments();
+ * const notebook = await sdk.createNotebook(data);
+ * const runtime = await sdk.createRuntime(config);
+ * await sdk.startRuntime(podName);
+ * ```
+ */
+import { DatalayerSDKBase, type DatalayerSDKConfig } from './base';
+declare const DatalayerSDKWithMixins: {
+    new (...args: any[]): {
+        getMySpaces(): Promise<import("./models").Space[]>;
+        createSpace(data: import("../..").CreateSpaceRequest): Promise<import("./models").Space>;
+        _extractNotebookId(notebookIdOrInstance: string | import("./models").Notebook): string;
+        _extractLexicalId(lexicalIdOrInstance: string | import("./models").Lexical): string;
+        createNotebook(data: import("../..").CreateNotebookRequest): Promise<import("./models").Notebook>;
+        getNotebook(idOrNotebook: string | import("./models").Notebook): Promise<import("./models").Notebook>;
+        updateNotebook(idOrNotebook: string | import("./models").Notebook, data: import("../..").UpdateNotebookRequest): Promise<import("./models").Notebook>;
+        createLexical(data: import("../..").CreateLexicalRequest): Promise<import("./models").Lexical>;
+        getLexical(idOrLexical: string | import("./models").Lexical): Promise<import("./models").Lexical>;
+        updateLexical(idOrLexical: string | import("./models").Lexical, data: import("../..").UpdateLexicalRequest): Promise<import("./models").Lexical>;
+        getSpaceItems(spaceId: string): Promise<import("../..").GetSpaceItemsResponse>;
+        deleteSpaceItem(itemId: string): Promise<import("../..").DeleteSpaceItemResponse>;
+    };
+} & {
+    new (...args: any[]): {
+        _extractRuntimePodName(runtimePodNameOrInstance: string | import("./models").Runtime): string;
+        _extractSnapshotId(snapshotIdOrInstance: string | import("./models").Snapshot): string;
+        listEnvironments(): Promise<import("../..").Environment[]>;
+        createRuntime(data: import("../..").CreateRuntimeRequest): Promise<import("./models").Runtime>;
+        listRuntimes(): Promise<import("./models").Runtime[]>;
+        getRuntime(podNameOrRuntime: string | import("./models").Runtime): Promise<import("./models").Runtime>;
+        deleteRuntime(podNameOrRuntime: string | import("./models").Runtime): Promise<void>;
+        createSnapshot(data: import("../..").CreateRuntimeSnapshotRequest): Promise<import("./models").Snapshot>;
+        listSnapshots(): Promise<import("./models").Snapshot[]>;
+        getSnapshot(idOrSnapshot: string | import("./models").Snapshot): Promise<import("./models").Snapshot>;
+        deleteSnapshot(idOrSnapshot: string | import("./models").Snapshot): Promise<void>;
+    };
+} & {
+    new (...args: any[]): {
+        whoami(): Promise<import("../..").User>;
+        login(data: import("../..").LoginRequest): Promise<import("../..").LoginResponse>;
+        logout(): Promise<void>;
+    };
+} & {
+    new (...args: any[]): {
+        isIAMHealthy(): Promise<boolean>;
+        isRuntimesHealthy(): Promise<boolean>;
+        isSpacerHealthy(): Promise<boolean>;
+        areAllServicesHealthy(): Promise<boolean>;
+        getHealthStatus(): Promise<{
+            iam: {
+                healthy: boolean;
+                details?: any;
+                error?: string;
+                version?: string;
+            };
+            runtimes: {
+                healthy: boolean;
+                details?: any;
+                error?: string;
+                version?: string;
+            };
+            spacer: {
+                healthy: boolean;
+                details?: any;
+                error?: string;
+                version?: string;
+            };
+            allHealthy: boolean;
+        }>;
+        readonly iamRunUrl: string;
+        readonly runtimesRunUrl: string;
+        readonly spacerRunUrl: string;
+        token?: string;
+        updateToken(token: string): void;
+        getConfig(): DatalayerSDKConfig;
+        updateConfig(config: Partial<DatalayerSDKConfig>): void;
+        getIamRunUrl(): string;
+        getRuntimesRunUrl(): string;
+        getSpacerRunUrl(): string;
+        getToken(): string | undefined;
+    };
+} & typeof DatalayerSDKBase;
+/**
+ * Main Datalayer SDK client providing unified access to all platform services.
+ *
+ * This class uses TypeScript mixins to provide a flat, discoverable API where
+ * all methods are directly accessible on the SDK instance. This design offers
+ * superior developer experience compared to nested service objects.
+ *
+ * **Key Features:**
+ * - **Flat API**: All methods directly on `sdk.` (e.g., `sdk.createNotebook()`)
+ * - **Intuitive naming**: Descriptive method names (e.g., `whoami()` vs `iam.users.me()`)
+ * - **Perfect discoverability**: IDE shows all available methods immediately
+ * - **Type safety**: Full TypeScript support with comprehensive interfaces
+ *
+ * **Authentication Methods:**
+ * - `whoami()` - Get current user profile
+ * - `login(credentials)` - Authenticate with credentials
+ * - `logout()` - Log out current user
+ *
+ * **Environment Methods:**
+ * - `listEnvironments()` - List available compute environments
+ *
+ * **Runtime Methods:**
+ * - `createRuntime(config)` - Create new computational runtime
+ * - `listRuntimes()` - List all runtimes
+ * - `getRuntime(podName)` - Get runtime details
+ * - `deleteRuntime(podName)` - Delete runtime
+ *
+ * **Workspace Methods:**
+ * - `createSpace(data)` - Create new workspace
+ * - `listSpaces()` - List all workspaces
+ * - `getSpace(spaceId)` - Get workspace details
+ * - `deleteSpace(spaceId)` - Delete workspace
+ *
+ * **Notebook Methods:**
+ * - `createNotebook(data)` - Create new notebook
+ * - `listNotebooks(spaceId?)` - List notebooks
+ * - `getNotebook(notebookId)` - Get notebook details
+ * - `getNotebookByUid(uid)` - Get notebook by UID
+ * - `updateNotebook(notebookId, data)` - Update notebook
+ * - `cloneNotebook(data)` - Clone existing notebook
+ * - `getNotebookContent(notebookId)` - Get notebook content
+ * - `updateNotebookContent(notebookId, content)` - Update notebook content
+ * - `deleteNotebook(notebookId)` - Delete notebook
+ *
+ * **Cell Methods:**
+ * - `createCell(notebookId, cell)` - Create new cell
+ * - `getCell(notebookId, cellId)` - Get cell details
+ * - `deleteCell(notebookId, cellId)` - Delete cell
+ *
+ * @example
+ * ```typescript
+ * // Initialize SDK
+ * const sdk = new DatalayerSDK({
+ *   token: 'your-token',
+ *   baseUrl: 'https://prod1.datalayer.run'
+ * });
+ *
+ * // Authentication
+ * const user = await sdk.whoami();
+ * console.log('Logged in as:', user.email);
+ *
+ * // Create workspace and notebook
+ * const space = await sdk.createSpace({
+ *   name: 'My Project'
+ * });
+ *
+ * const notebook = await sdk.createNotebook({
+ *   space_id: space.id,
+ *   name: 'Analysis'
+ * });
+ *
+ * // Create and start runtime
+ * const runtime = await sdk.createRuntime({
+ *   environment_name: 'python-cpu-env',
+ *   credits_limit: 100
+ * });
+ *
+ * console.log('Setup complete!');
+ * ```
+ */
+export declare class DatalayerSDK extends DatalayerSDKWithMixins {
+    /**
+     * Create a DatalayerSDK instance.
+     *
+     * @param config - SDK configuration options
+     */
+    constructor(config: DatalayerSDKConfig);
+}
+export type { DatalayerSDKConfig };
+export { DatalayerSDKBase };

package/lib/sdk/client/index.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * @module sdk/client
+ * @description Main Datalayer SDK client with intuitive mixin-based API.
+ *
+ * The DatalayerSDK class provides a unified, flat API for all Datalayer platform
+ * services through TypeScript mixins. This design offers the best discoverability
+ * and ease of use compared to nested service objects.
+ *
+ * @example
+ * ```typescript
+ * import { DatalayerSDK } from '@datalayer/core/sdk';
+ *
+ * // Initialize SDK
+ * const sdk = new DatalayerSDK({
+ *   token: 'your-api-token',
+ *   baseUrl: 'https://prod1.datalayer.run'
+ * });
+ *
+ * // Flat, intuitive API
+ * const user = await sdk.whoami();
+ * const environments = await sdk.listEnvironments();
+ * const notebook = await sdk.createNotebook(data);
+ * const runtime = await sdk.createRuntime(config);
+ * await sdk.startRuntime(podName);
+ * ```
+ */
+import { DatalayerSDKBase } from './base';
+import { HealthMixin } from './mixins/HealthMixin';
+import { IAMMixin } from './mixins/IAMMixin';
+import { RuntimesMixin } from './mixins/RuntimesMixin';
+import { SpacerMixin } from './mixins/SpacerMixin';
+// Apply mixins to the base class
+const DatalayerSDKWithMixins = SpacerMixin(RuntimesMixin(IAMMixin(HealthMixin(DatalayerSDKBase))));
+/**
+ * Main Datalayer SDK client providing unified access to all platform services.
+ *
+ * This class uses TypeScript mixins to provide a flat, discoverable API where
+ * all methods are directly accessible on the SDK instance. This design offers
+ * superior developer experience compared to nested service objects.
+ *
+ * **Key Features:**
+ * - **Flat API**: All methods directly on `sdk.` (e.g., `sdk.createNotebook()`)
+ * - **Intuitive naming**: Descriptive method names (e.g., `whoami()` vs `iam.users.me()`)
+ * - **Perfect discoverability**: IDE shows all available methods immediately
+ * - **Type safety**: Full TypeScript support with comprehensive interfaces
+ *
+ * **Authentication Methods:**
+ * - `whoami()` - Get current user profile
+ * - `login(credentials)` - Authenticate with credentials
+ * - `logout()` - Log out current user
+ *
+ * **Environment Methods:**
+ * - `listEnvironments()` - List available compute environments
+ *
+ * **Runtime Methods:**
+ * - `createRuntime(config)` - Create new computational runtime
+ * - `listRuntimes()` - List all runtimes
+ * - `getRuntime(podName)` - Get runtime details
+ * - `deleteRuntime(podName)` - Delete runtime
+ *
+ * **Workspace Methods:**
+ * - `createSpace(data)` - Create new workspace
+ * - `listSpaces()` - List all workspaces
+ * - `getSpace(spaceId)` - Get workspace details
+ * - `deleteSpace(spaceId)` - Delete workspace
+ *
+ * **Notebook Methods:**
+ * - `createNotebook(data)` - Create new notebook
+ * - `listNotebooks(spaceId?)` - List notebooks
+ * - `getNotebook(notebookId)` - Get notebook details
+ * - `getNotebookByUid(uid)` - Get notebook by UID
+ * - `updateNotebook(notebookId, data)` - Update notebook
+ * - `cloneNotebook(data)` - Clone existing notebook
+ * - `getNotebookContent(notebookId)` - Get notebook content
+ * - `updateNotebookContent(notebookId, content)` - Update notebook content
+ * - `deleteNotebook(notebookId)` - Delete notebook
+ *
+ * **Cell Methods:**
+ * - `createCell(notebookId, cell)` - Create new cell
+ * - `getCell(notebookId, cellId)` - Get cell details
+ * - `deleteCell(notebookId, cellId)` - Delete cell
+ *
+ * @example
+ * ```typescript
+ * // Initialize SDK
+ * const sdk = new DatalayerSDK({
+ *   token: 'your-token',
+ *   baseUrl: 'https://prod1.datalayer.run'
+ * });
+ *
+ * // Authentication
+ * const user = await sdk.whoami();
+ * console.log('Logged in as:', user.email);
+ *
+ * // Create workspace and notebook
+ * const space = await sdk.createSpace({
+ *   name: 'My Project'
+ * });
+ *
+ * const notebook = await sdk.createNotebook({
+ *   space_id: space.id,
+ *   name: 'Analysis'
+ * });
+ *
+ * // Create and start runtime
+ * const runtime = await sdk.createRuntime({
+ *   environment_name: 'python-cpu-env',
+ *   credits_limit: 100
+ * });
+ *
+ * console.log('Setup complete!');
+ * ```
+ */
+export class DatalayerSDK extends DatalayerSDKWithMixins {
+    /**
+     * Create a DatalayerSDK instance.
+     *
+     * @param config - SDK configuration options
+     */
+    constructor(config) {
+        super(config);
+    }
+}
+export { DatalayerSDKBase };

package/lib/sdk/client/mixins/HealthMixin.d.ts

@@ -0,0 +1,100 @@
+import type { DatalayerSDKBase } from '../base';
+/**
+ * Interface for health check methods.
+ */
+export interface HealthMixinInterface {
+    /** Check if IAM service is healthy */
+    isIAMHealthy(): Promise<boolean>;
+    /** Check if Runtimes service is healthy */
+    isRuntimesHealthy(): Promise<boolean>;
+    /** Check if Spacer service is healthy */
+    isSpacerHealthy(): Promise<boolean>;
+    /** Check if all services are healthy */
+    areAllServicesHealthy(): Promise<boolean>;
+    /** Get detailed health status for all services */
+    getHealthStatus(): Promise<{
+        iam: {
+            healthy: boolean;
+            details?: any;
+            error?: string;
+        };
+        runtimes: {
+            healthy: boolean;
+            details?: any;
+            error?: string;
+        };
+        spacer: {
+            healthy: boolean;
+            details?: any;
+            error?: string;
+        };
+    }>;
+}
+/**
+ * Mixin that provides health check functionality for the SDK.
+ */
+export declare function HealthMixin<T extends new (...args: any[]) => DatalayerSDKBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Check if the IAM service is healthy.
+         *
+         * @returns True if service is healthy, false otherwise
+         */
+        isIAMHealthy(): Promise<boolean>;
+        /**
+         * Check if the Runtimes service is healthy.
+         *
+         * @returns True if service is healthy, false otherwise
+         */
+        isRuntimesHealthy(): Promise<boolean>;
+        /**
+         * Check if the Spacer service is healthy.
+         *
+         * @returns True if service is healthy, false otherwise
+         */
+        isSpacerHealthy(): Promise<boolean>;
+        /**
+         * Check if all Datalayer services are healthy.
+         *
+         * @returns True if all services are healthy, false otherwise
+         */
+        areAllServicesHealthy(): Promise<boolean>;
+        /**
+         * Get detailed health status for all services.
+         *
+         * @returns Object containing health status and details for each service
+         */
+        getHealthStatus(): Promise<{
+            iam: {
+                healthy: boolean;
+                details?: any;
+                error?: string;
+                version?: string;
+            };
+            runtimes: {
+                healthy: boolean;
+                details?: any;
+                error?: string;
+                version?: string;
+            };
+            spacer: {
+                healthy: boolean;
+                details?: any;
+                error?: string;
+                version?: string;
+            };
+            allHealthy: boolean;
+        }>;
+        readonly iamRunUrl: string;
+        readonly runtimesRunUrl: string;
+        readonly spacerRunUrl: string;
+        token?: string;
+        updateToken(token: string): void;
+        getConfig(): import("..").DatalayerSDKConfig;
+        updateConfig(config: Partial<import("..").DatalayerSDKConfig>): void;
+        getIamRunUrl(): string;
+        getRuntimesRunUrl(): string;
+        getSpacerRunUrl(): string;
+        getToken(): string | undefined;
+    };
+} & T;

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

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * @module sdk/client/mixins/HealthMixin
+ * @description Health check functionality for the Datalayer SDK.
+ *
+ * Provides methods to check the health status of all Datalayer services.
+ */
+import { iam, runtimes, spacer } from '../../../api';
+/**
+ * Mixin that provides health check functionality for the SDK.
+ */
+export function HealthMixin(Base) {
+    return class extends Base {
+        /**
+         * Check if the IAM service is healthy.
+         *
+         * @returns True if service is healthy, false otherwise
+         */
+        async isIAMHealthy() {
+            try {
+                await iam.healthz.ping(this.iamRunUrl);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        /**
+         * Check if the Runtimes service is healthy.
+         *
+         * @returns True if service is healthy, false otherwise
+         */
+        async isRuntimesHealthy() {
+            try {
+                await runtimes.healthz.ping(this.runtimesRunUrl);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        /**
+         * Check if the Spacer service is healthy.
+         *
+         * @returns True if service is healthy, false otherwise
+         */
+        async isSpacerHealthy() {
+            try {
+                await spacer.healthz.ping(this.spacerRunUrl);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        /**
+         * Check if all Datalayer services are healthy.
+         *
+         * @returns True if all services are healthy, false otherwise
+         */
+        async areAllServicesHealthy() {
+            const [iamHealthy, runtimesHealthy, spacerHealthy] = await Promise.all([
+                this.isIAMHealthy(),
+                this.isRuntimesHealthy(),
+                this.isSpacerHealthy(),
+            ]);
+            return iamHealthy && runtimesHealthy && spacerHealthy;
+        }
+        /**
+         * Get detailed health status for all services.
+         *
+         * @returns Object containing health status and details for each service
+         */
+        async getHealthStatus() {
+            const [iamStatus, runtimesStatus, spacerStatus] = await Promise.allSettled([
+                iam.healthz.ping(this.iamRunUrl),
+                runtimes.healthz.ping(this.runtimesRunUrl),
+                spacer.healthz.ping(this.spacerRunUrl),
+            ]);
+            const result = {
+                iam: {
+                    healthy: false,
+                    details: undefined,
+                    error: undefined,
+                },
+                runtimes: {
+                    healthy: false,
+                    details: undefined,
+                    error: undefined,
+                },
+                spacer: {
+                    healthy: false,
+                    details: undefined,
+                    error: undefined,
+                },
+            };
+            // Process IAM status
+            if (iamStatus.status === 'fulfilled') {
+                result.iam.healthy = true;
+                result.iam.details = iamStatus.value;
+            }
+            else {
+                result.iam.error = iamStatus.reason?.message || 'Unknown error';
+            }
+            // Process Runtimes status
+            if (runtimesStatus.status === 'fulfilled') {
+                result.runtimes.healthy = true;
+                result.runtimes.details = runtimesStatus.value;
+            }
+            else {
+                result.runtimes.error =
+                    runtimesStatus.reason?.message || 'Unknown error';
+            }
+            // Process Spacer status
+            if (spacerStatus.status === 'fulfilled') {
+                result.spacer.healthy = true;
+                result.spacer.details = spacerStatus.value;
+            }
+            else {
+                result.spacer.error = spacerStatus.reason?.message || 'Unknown error';
+            }
+            return {
+                ...result,
+                allHealthy: result.iam.healthy &&
+                    result.runtimes.healthy &&
+                    result.spacer.healthy,
+            };
+        }
+    };
+}

package/lib/sdk/client/mixins/IAMMixin.d.ts

@@ -0,0 +1,59 @@
+import type { User, LoginRequest, LoginResponse } from '../../../api/types/iam';
+import type { Constructor } from '../utils/mixins';
+/**
+ * IAM mixin that provides authentication and user management functionality.
+ *
+ */
+export declare function IAMMixin<TBase extends Constructor>(Base: TBase): {
+    new (...args: any[]): {
+        /**
+         * Get the current user's profile information.
+         *
+         * @returns Promise resolving to the current user's profile
+         *
+         * @example
+         * ```typescript
+         * const user = await sdk.whoami();
+         * console.log('Current user:', user.username);
+         * ```
+         */
+        whoami(): Promise<User>;
+        /**
+         * Authenticate a user with credentials or token.
+         *
+         * @param data - Login credentials (either handle+password or token)
+         * @returns Promise resolving to login response with tokens
+         *
+         * @example
+         * ```typescript
+         * // Login with handle and password
+         * const loginResponse = await sdk.login({
+         *   handle: 'user@example.com',
+         *   password: 'secure-password'
+         * });
+         *
+         * // Or login with token
+         * const tokenResponse = await sdk.login({
+         *   token: 'existing-auth-token'
+         * });
+         *
+         * // Update SDK with new token
+         * sdk.updateToken(loginResponse.token);
+         * ```
+         */
+        login(data: LoginRequest): Promise<LoginResponse>;
+        /**
+         * Log out the current user.
+         *
+         * This method performs a logout operation on the server and clears
+         * the authentication token from the SDK.
+         *
+         * @example
+         * ```typescript
+         * await sdk.logout();
+         * console.log('User logged out successfully');
+         * ```
+         */
+        logout(): Promise<void>;
+    };
+} & TBase;

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

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * @module sdk/client/mixins/IAMMixin
+ * @description IAM (Identity and Access Management) mixin for the Datalayer SDK.
+ *
+ * This mixin provides intuitive authentication and user management methods
+ * that are mixed into the main DatalayerSDK class.
+ */
+import { authentication, profile } from '../../../api/iam';
+/**
+ * IAM mixin that provides authentication and user management functionality.
+ *
+ */
+export function IAMMixin(Base) {
+    return class extends Base {
+        /**
+         * Get the current user's profile information.
+         *
+         * @returns Promise resolving to the current user's profile
+         *
+         * @example
+         * ```typescript
+         * const user = await sdk.whoami();
+         * console.log('Current user:', user.username);
+         * ```
+         */
+        async whoami() {
+            const token = this.getToken();
+            const iamRunUrl = this.getIamRunUrl();
+            const response = await profile.me(token, iamRunUrl);
+            return response.me;
+        }
+        /**
+         * Authenticate a user with credentials or token.
+         *
+         * @param data - Login credentials (either handle+password or token)
+         * @returns Promise resolving to login response with tokens
+         *
+         * @example
+         * ```typescript
+         * // Login with handle and password
+         * const loginResponse = await sdk.login({
+         *   handle: 'user@example.com',
+         *   password: 'secure-password'
+         * });
+         *
+         * // Or login with token
+         * const tokenResponse = await sdk.login({
+         *   token: 'existing-auth-token'
+         * });
+         *
+         * // Update SDK with new token
+         * sdk.updateToken(loginResponse.token);
+         * ```
+         */
+        async login(data) {
+            const iamRunUrl = this.getIamRunUrl();
+            return await authentication.login(data, iamRunUrl);
+        }
+        /**
+         * Log out the current user.
+         *
+         * This method performs a logout operation on the server and clears
+         * the authentication token from the SDK.
+         *
+         * @example
+         * ```typescript
+         * await sdk.logout();
+         * console.log('User logged out successfully');
+         * ```
+         */
+        async logout() {
+            const token = this.getToken();
+            const iamRunUrl = this.getIamRunUrl();
+            await authentication.logout(token, iamRunUrl);
+            // Clear the token from the SDK
+            this.updateToken('');
+        }
+    };
+}