@datalayer/core 0.0.12 → 0.0.13

package/lib/client/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Main Datalayer Client with intuitive mixin-based API.
+ * Provides unified, flat API for all Datalayer platform services through TypeScript mixins.
+ *
+ * @module client
+ *
+ * @example
+ * ```typescript
+ * const client = new DatalayerClient({
+ *   token: 'your-api-token'
+ * });
+ *
+ * const user = await client.whoami();
+ * const runtime = await client.createRuntime(config);
+ * ```
+ */
+import { DatalayerClientBase, type DatalayerClientConfig, type SDKHandlers } from './base';
+import type { User } from './models/User';
+import type { Credits } from './models/Credits';
+import type { Environment } from './models/Environment';
+import type { Runtime } from './models/Runtime';
+import type { Snapshot } from './models/Snapshot';
+import type { Space } from './models/Space';
+import type { Notebook } from './models/Notebook';
+import type { Lexical } from './models/Lexical';
+import type { HealthCheck } from './models/HealthCheck';
+declare const DatalayerClientWithMixins: typeof DatalayerClientBase;
+/**
+ * Main Datalayer Client providing unified access to all platform services.
+ * Uses TypeScript mixins to provide a flat, discoverable API.
+ *
+ * @example
+ * ```typescript
+ * const client = new DatalayerClient({
+ *   token: 'your-token'
+ * });
+ *
+ * const user = await client.whoami();
+ * const runtime = await client.createRuntime({
+ *   environment_name: 'python-cpu-env',
+ *   credits_limit: 100
+ * });
+ * ```
+ */
+export declare class DatalayerClient extends DatalayerClientWithMixins {
+    /**
+     * Create a DatalayerClient instance.
+     *
+     * @param config - Client configuration options
+     */
+    constructor(config: DatalayerClientConfig);
+}
+export type { DatalayerClientConfig, SDKHandlers };
+export { DatalayerClientBase };
+export { User } from './models/User';
+export type { UserJSON } from './models/User';
+export { Runtime } from './models/Runtime';
+export type { RuntimeJSON } from './models/Runtime';
+export { Environment } from './models/Environment';
+export type { EnvironmentJSON } from './models/Environment';
+export { Snapshot } from './models/Snapshot';
+export { Space } from './models/Space';
+export { Notebook } from './models/Notebook';
+export { Lexical } from './models/Lexical';
+export { Credits } from './models/Credits';
+export { Item } from './models/Item';
+export { HealthCheck } from './models/HealthCheck';
+export type { HealthCheckJSON } from './models/HealthCheck';
+export { ItemTypes } from './constants';
+export type { ItemType } from './constants';
+export interface DatalayerClient {
+    getToken(): string | undefined;
+    setToken(token: string): Promise<void>;
+    whoami(): Promise<User>;
+    login(token: string): Promise<User>;
+    logout(): Promise<void>;
+    getCredits(): Promise<Credits>;
+    calculateMaxRuntimeMinutes(availableCredits: number, burningRate: number): number;
+    calculateCreditsRequired(minutes: number, burningRate: number): number;
+    checkIAMHealth(): Promise<HealthCheck>;
+    listEnvironments(): Promise<Environment[]>;
+    ensureRuntime(environmentName?: string, creditsLimit?: number, waitForReady?: boolean, maxWaitTime?: number, reuseExisting?: boolean, snapshotId?: string): Promise<Runtime>;
+    createRuntime(environmentName: string, type: 'notebook' | 'terminal' | 'job', givenName: string, minutesLimit: number, fromSnapshotId?: string): Promise<Runtime>;
+    listRuntimes(): Promise<Runtime[]>;
+    getRuntime(podName: string): Promise<Runtime>;
+    deleteRuntime(podName: string): Promise<void>;
+    terminateAllRuntimes(): Promise<PromiseSettledResult<void>[]>;
+    createSnapshot(podName: string, name: string, description: string, stop?: boolean): Promise<Snapshot>;
+    listSnapshots(): Promise<Snapshot[]>;
+    getSnapshot(id: string): Promise<Snapshot>;
+    deleteSnapshot(id: string): Promise<void>;
+    checkRuntimesHealth(): Promise<HealthCheck>;
+    getMySpaces(): Promise<Space[]>;
+    createSpace(name: string, description: string, variant: string, spaceHandle: string, organizationId: string, seedSpaceId: string, isPublic: boolean): Promise<Space>;
+    createNotebook(spaceId: string, name: string, description: string, file?: File | Blob): Promise<Notebook>;
+    getNotebook(id: string): Promise<Notebook>;
+    updateNotebook(id: string, name?: string, description?: string): Promise<Notebook>;
+    createLexical(spaceId: string, name: string, description: string, file?: File | Blob): Promise<Lexical>;
+    getLexical(id: string): Promise<Lexical>;
+    updateLexical(id: string, name?: string, description?: string): Promise<Lexical>;
+    getSpaceItems(spaceId: string): Promise<(Notebook | Lexical)[]>;
+    getSpaceItem(itemId: string): Promise<Notebook | Lexical>;
+    deleteSpaceItem(itemId: string): Promise<void>;
+    getCollaborationSessionId(documentId: string): Promise<string>;
+    getContent(itemId: string): Promise<any>;
+    checkSpacerHealth(): Promise<HealthCheck>;
+    calculateCreditsFromMinutes(minutes: number, burningRate: number): number;
+}

package/lib/client/index.js

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Main Datalayer Client with intuitive mixin-based API.
+ * Provides unified, flat API for all Datalayer platform services through TypeScript mixins.
+ *
+ * @module client
+ *
+ * @example
+ * ```typescript
+ * const client = new DatalayerClient({
+ *   token: 'your-api-token'
+ * });
+ *
+ * const user = await client.whoami();
+ * const runtime = await client.createRuntime(config);
+ * ```
+ */
+import { DatalayerClientBase, } from './base';
+import { IAMMixin } from './mixins/IAMMixin';
+import { RuntimesMixin } from './mixins/RuntimesMixin';
+import { SpacerMixin } from './mixins/SpacerMixin';
+/**
+ * Helper function to compose mixins in a more readable way.
+ * Applies mixins in the order provided.
+ *
+ * @param mixins - Array of mixin functions to apply
+ * @returns The composed class with all mixins applied
+ */
+function composeMixins(...mixins) {
+    return mixins.reduce((base, mixin) => mixin(base), DatalayerClientBase);
+}
+// Apply mixins to the base class using the helper
+const DatalayerClientWithMixins = composeMixins(IAMMixin, RuntimesMixin, SpacerMixin);
+/**
+ * Main Datalayer Client providing unified access to all platform services.
+ * Uses TypeScript mixins to provide a flat, discoverable API.
+ *
+ * @example
+ * ```typescript
+ * const client = new DatalayerClient({
+ *   token: 'your-token'
+ * });
+ *
+ * const user = await client.whoami();
+ * const runtime = await client.createRuntime({
+ *   environment_name: 'python-cpu-env',
+ *   credits_limit: 100
+ * });
+ * ```
+ */
+export class DatalayerClient extends DatalayerClientWithMixins {
+    /**
+     * Create a DatalayerClient instance.
+     *
+     * @param config - Client configuration options
+     */
+    constructor(config) {
+        super(config);
+        // Wrap all methods with handlers if configured
+        this.wrapAllMethods();
+    }
+}
+export { DatalayerClientBase };
+// Export models for use by consumers
+export { User } from './models/User';
+export { Runtime } from './models/Runtime';
+export { Environment } from './models/Environment';
+export { Snapshot } from './models/Snapshot';
+export { Space } from './models/Space';
+export { Notebook } from './models/Notebook';
+export { Lexical } from './models/Lexical';
+export { Credits } from './models/Credits';
+export { Item } from './models/Item';
+export { HealthCheck } from './models/HealthCheck';
+// Export constants
+export { ItemTypes } from './constants';

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

@@ -0,0 +1,54 @@
+import type { Constructor } from '../utils/mixins';
+import { User } from '../models/User';
+import { Credits } from '../models/Credits';
+import { HealthCheck } from '../models/HealthCheck';
+/** IAM mixin providing authentication and user management. */
+export declare function IAMMixin<TBase extends Constructor>(Base: TBase): {
+    new (...args: any[]): {
+        currentUserCache?: User;
+        /**
+         * Get the current user's profile information.
+         * @returns User model instance
+         */
+        whoami(): Promise<User>;
+        /**
+         * Authenticate the user with a token.
+         * @param token - Authentication token
+         * @returns User object on successful login
+         * @throws Error if token is invalid
+         */
+        login(token: string): Promise<User>;
+        /** Log out the current user. */
+        logout(): Promise<void>;
+        /**
+         * Get the current user's available credits and usage information.
+         * @returns Credits model instance
+         */
+        getCredits(): Promise<Credits>;
+        /**
+         * Calculate the maximum runtime duration in minutes based on available credits and burning rate.
+         * @param availableCredits - The amount of credits available
+         * @param burningRate - The burning rate per second for the environment
+         * @returns Maximum runtime duration in minutes
+         */
+        calculateMaxRuntimeMinutes(availableCredits: number, burningRate: number): number;
+        /**
+         * Calculate the credits required for a given runtime duration.
+         * @param minutes - Runtime duration in minutes
+         * @param burningRate - The burning rate per second for the environment
+         * @returns Credits required (rounded up to nearest integer)
+         */
+        calculateCreditsRequired(minutes: number, burningRate: number): number;
+        /**
+         * Calculate the burning rate per minute from the per-second rate.
+         * @param burningRatePerSecond - The burning rate per second
+         * @returns Burning rate per minute
+         */
+        calculateBurningRatePerMinute(burningRatePerSecond: number): number;
+        /**
+         * Check the health status of the IAM service.
+         * @returns Health check model instance
+         */
+        checkIAMHealth(): Promise<HealthCheck>;
+    };
+} & TBase;

package/lib/client/mixins/IAMMixin.js

@@ -0,0 +1,181 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * IAM mixin providing authentication and user management functionality.
+ * @module client/mixins/IAMMixin
+ */
+import * as authentication from '../../api/iam/authentication';
+import * as profile from '../../api/iam/profile';
+import * as usage from '../../api/iam/usage';
+import { User } from '../models/User';
+import { Credits } from '../models/Credits';
+import { HealthCheck } from '../models/HealthCheck';
+/** IAM mixin providing authentication and user management. */
+export function IAMMixin(Base) {
+    return class extends Base {
+        // Cache for current user
+        currentUserCache;
+        /**
+         * Get the current user's profile information.
+         * @returns User model instance
+         */
+        async whoami() {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const token = this.getToken();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const iamRunUrl = this.getIamRunUrl();
+            const response = await profile.whoami(token, iamRunUrl);
+            // Handle the whoami response format
+            let userData;
+            if (!response) {
+                throw new Error(`No response from profile.whoami API`);
+            }
+            // Check if response has the expected wrapper structure with profile
+            if (response.profile) {
+                // Transform the API response to match the User model's expected data structure
+                // Note: whoami returns fields with suffixes like _s, _t
+                userData = {
+                    id: response.profile.id,
+                    uid: response.profile.uid,
+                    // User model expects fields with suffixes from API types
+                    handle_s: response.profile.handle_s || response.profile.handle,
+                    email_s: response.profile.email_s || response.profile.email,
+                    first_name_t: response.profile.first_name_t || response.profile.first_name || '',
+                    last_name_t: response.profile.last_name_t || response.profile.last_name || '',
+                    // Use avatar_url_s if available, otherwise leave undefined for fallback
+                    avatar_url_s: response.profile.avatar_url_s || response.profile.avatar_url,
+                };
+            }
+            // Fallback for unexpected format
+            else {
+                throw new Error(`Unexpected response format from profile.whoami API: ${JSON.stringify(response)}`);
+            }
+            // Create new User instance (User model is immutable, no update method)
+            this.currentUserCache = new User(userData, this);
+            return this.currentUserCache;
+        }
+        /**
+         * Authenticate the user with a token.
+         * @param token - Authentication token
+         * @returns User object on successful login
+         * @throws Error if token is invalid
+         */
+        async login(token) {
+            // For token-based login, we simply set the token and verify it works
+            await this.setToken(token);
+            // Verify the token by calling whoami
+            try {
+                const user = await this.whoami();
+                return user;
+            }
+            catch (error) {
+                // Clear the invalid token
+                await this.setToken('');
+                throw new Error(`Invalid token: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        /** Log out the current user. */
+        async logout() {
+            const token = this.getToken();
+            const iamRunUrl = this.getIamRunUrl();
+            await authentication.logout(token, iamRunUrl);
+            // Clear the token from the SDK and cached user
+            this.setToken('');
+            this.currentUserCache = undefined;
+        }
+        /**
+         * Get the current user's available credits and usage information.
+         * @returns Credits model instance
+         */
+        async getCredits() {
+            const token = this.getToken();
+            const iamRunUrl = this.getIamRunUrl();
+            const response = await usage.getCredits(token, iamRunUrl);
+            if (!response || !response.credits) {
+                throw new Error('Invalid response from credits API');
+            }
+            return new Credits(response.credits, response.reservations || []);
+        }
+        // ========================================================================
+        // Credits Calculation Utilities
+        // ========================================================================
+        /**
+         * Calculate the maximum runtime duration in minutes based on available credits and burning rate.
+         * @param availableCredits - The amount of credits available
+         * @param burningRate - The burning rate per second for the environment
+         * @returns Maximum runtime duration in minutes
+         */
+        calculateMaxRuntimeMinutes(availableCredits, burningRate) {
+            if (!burningRate || burningRate <= 0)
+                return 0;
+            const burningRatePerMinute = burningRate * 60;
+            return Math.floor(availableCredits / burningRatePerMinute);
+        }
+        /**
+         * Calculate the credits required for a given runtime duration.
+         * @param minutes - Runtime duration in minutes
+         * @param burningRate - The burning rate per second for the environment
+         * @returns Credits required (rounded up to nearest integer)
+         */
+        calculateCreditsRequired(minutes, burningRate) {
+            if (!burningRate || burningRate <= 0 || !minutes || minutes <= 0)
+                return 0;
+            return Math.ceil(minutes * this.calculateBurningRatePerMinute(burningRate));
+        }
+        /**
+         * Calculate the burning rate per minute from the per-second rate.
+         * @param burningRatePerSecond - The burning rate per second
+         * @returns Burning rate per minute
+         */
+        calculateBurningRatePerMinute(burningRatePerSecond) {
+            return burningRatePerSecond * 60;
+        }
+        // ========================================================================
+        // Service Health Checks
+        // ========================================================================
+        /**
+         * Check the health status of the IAM service.
+         * @returns Health check model instance
+         */
+        async checkIAMHealth() {
+            const startTime = Date.now();
+            const errors = [];
+            let status = 'unknown';
+            let healthy = false;
+            try {
+                // Test basic connectivity and authentication by getting user profile
+                const user = await this.whoami();
+                const responseTime = Date.now() - startTime;
+                if (user && user.uid) {
+                    healthy = true;
+                    status = 'operational';
+                }
+                else {
+                    status = 'degraded';
+                    errors.push('Unexpected response format from profile endpoint');
+                }
+                return new HealthCheck({
+                    healthy,
+                    status,
+                    responseTime,
+                    errors,
+                    timestamp: new Date(),
+                }, this);
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                status = 'down';
+                errors.push(`Service unreachable: ${error}`);
+                return new HealthCheck({
+                    healthy: false,
+                    status,
+                    responseTime,
+                    errors,
+                    timestamp: new Date(),
+                }, this);
+            }
+        }
+    };
+}

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

@@ -0,0 +1,93 @@
+import type { Constructor } from '../utils/mixins';
+import { Environment } from '../models/Environment';
+import { Runtime } from '../models/Runtime';
+import { Snapshot } from '../models/Snapshot';
+import { HealthCheck } from '../models/HealthCheck';
+/** Options for ensuring a runtime is available. */
+export interface EnsureRuntimeOptions {
+    /** Name of the environment to use */
+    environmentName?: string;
+    /** Maximum credits to allocate */
+    creditsLimit?: number;
+    /** Whether to wait for runtime to be ready */
+    waitForReady?: boolean;
+    /** Maximum time to wait for ready state (ms) */
+    maxWaitTime?: number;
+    /** Whether to reuse existing suitable runtime */
+    reuseExisting?: boolean;
+    /** Snapshot ID to create runtime from */
+    snapshotId?: string;
+}
+/** Runtimes mixin providing computational environment and runtime management. */
+export declare function RuntimesMixin<TBase extends Constructor>(Base: TBase): {
+    new (...args: any[]): {
+        _extractRuntimePodName(runtimePodNameOrInstance: string | Runtime): string;
+        _extractSnapshotId(snapshotIdOrInstance: string | Snapshot): string;
+        /**
+         * List all available computational environments.
+         * @returns Array of Environment model instances
+         */
+        listEnvironments(): Promise<Environment[]>;
+        /**
+         * Create a new computational runtime.
+         * @param environmentName - Name of the environment to use
+         * @param type - Type of runtime
+         * @param givenName - User-friendly name for the runtime
+         * @param creditsLimit - Credits limit
+         * @returns Created runtime
+         */
+        createRuntime(environmentName: string, type: "notebook" | "terminal" | "job", givenName: string, minutesLimit: number, fromSnapshotId?: string): Promise<Runtime>;
+        /**
+         * List all runtimes.
+         * @returns Array of runtimes
+         */
+        listRuntimes(): Promise<Runtime[]>;
+        /**
+         * Get details for a specific runtime by pod name.
+         * @param podName - Runtime pod name
+         * @returns Runtime details
+         */
+        getRuntime(podName: string): Promise<Runtime>;
+        /**
+         * Delete a runtime permanently.
+         * @param podName - Runtime pod name
+         */
+        deleteRuntime(podName: string): Promise<void>;
+        /**
+         * Terminate all runtimes.
+         * Lists all runtimes and deletes them in parallel.
+         * @returns Array of results for each deletion (fulfilled or rejected)
+         */
+        terminateAllRuntimes(): Promise<PromiseSettledResult<void>[]>;
+        /**
+         * Create a snapshot of a runtime.
+         * @param podName - Pod name of the runtime to snapshot
+         * @param name - Name for the snapshot
+         * @param description - Description of the snapshot
+         * @param stop - Whether to stop the runtime after creating snapshot (defaults to false)
+         * @returns Created snapshot
+         */
+        createSnapshot(podName: string, name: string, description: string, stop?: boolean): Promise<Snapshot>;
+        /**
+         * List all runtime snapshots.
+         * @returns Array of snapshots
+         */
+        listSnapshots(): Promise<Snapshot[]>;
+        /**
+         * Get details for a specific snapshot by ID.
+         * @param id - Snapshot ID
+         * @returns Snapshot details
+         */
+        getSnapshot(id: string): Promise<Snapshot>;
+        /**
+         * Delete a snapshot permanently.
+         * @param id - Snapshot ID
+         */
+        deleteSnapshot(id: string): Promise<void>;
+        /**
+         * Check the health status of the Runtimes service.
+         * @returns Health check result with status and response time
+         */
+        checkRuntimesHealth(): Promise<HealthCheck>;
+    };
+} & TBase;