@datalayer/core 0.0.12 → 0.0.13

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

@@ -0,0 +1,91 @@
+/**
+ * Credits model for the Datalayer SDK.
+ *
+ * @module client/models/Credits
+ */
+import type { CreditsInfo, CreditReservation } from '../../api/iam/usage';
+/**
+ * Credits model representing user's available credits and usage.
+ *
+ * @example
+ * ```typescript
+ * const credits = await sdk.getCredits();
+ * console.log(`Available: ${credits.available}`);
+ * console.log(`Quota: ${credits.quota || 'unlimited'}`);
+ *
+ * // Calculate maximum runtime for an environment
+ * const maxMinutes = credits.calculateMaxRuntimeMinutes(environment.burningRate);
+ * ```
+ */
+export declare class Credits {
+    /** @internal */
+    _data: CreditsInfo;
+    private _reservations;
+    constructor(data: CreditsInfo, reservations?: CreditReservation[]);
+    /**
+     * Available credits for the user.
+     */
+    get available(): number;
+    /**
+     * Credit quota for the user.
+     * Returns null if unlimited.
+     */
+    get quota(): number | null;
+    /**
+     * Last update timestamp.
+     */
+    get lastUpdate(): string;
+    /**
+     * Active credit reservations.
+     */
+    get reservations(): CreditReservation[];
+    /**
+     * Total reserved credits across all reservations.
+     */
+    get totalReserved(): number;
+    /**
+     * Net available credits (available minus reserved).
+     */
+    get netAvailable(): number;
+    /**
+     * Get runtime reservations (reservations that start with 'runtime-').
+     */
+    get runtimeReservations(): CreditReservation[];
+    /**
+     * Check if there are any active runtime reservations.
+     */
+    get hasActiveRuntimes(): boolean;
+    /**
+     * Calculate maximum runtime in minutes based on environment burning rate.
+     *
+     * @param burningRate - Credits consumed per hour
+     * @returns Maximum runtime in minutes
+     */
+    calculateMaxRuntimeMinutes(burningRate: number): number;
+    /**
+     * Calculate credits needed for runtime duration.
+     *
+     * @param minutes - Runtime duration in minutes
+     * @param burningRate - Credits consumed per hour
+     * @returns Credits needed
+     */
+    calculateCreditsFromMinutes(minutes: number, burningRate: number): number;
+    /**
+     * Check if user has enough credits for runtime.
+     *
+     * @param minutes - Runtime duration in minutes
+     * @param burningRate - Credits consumed per hour
+     * @returns True if user has enough credits
+     */
+    hasEnoughCreditsForRuntime(minutes: number, burningRate: number): boolean;
+    /**
+     * Convert to JSON representation.
+     */
+    toJSON(): CreditsInfo & {
+        reservations: CreditReservation[];
+    };
+    /**
+     * String representation of credits.
+     */
+    toString(): string;
+}

package/lib/client/models/Credits.js

@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * Credits model representing user's available credits and usage.
+ *
+ * @example
+ * ```typescript
+ * const credits = await sdk.getCredits();
+ * console.log(`Available: ${credits.available}`);
+ * console.log(`Quota: ${credits.quota || 'unlimited'}`);
+ *
+ * // Calculate maximum runtime for an environment
+ * const maxMinutes = credits.calculateMaxRuntimeMinutes(environment.burningRate);
+ * ```
+ */
+export class Credits {
+    /** @internal */
+    _data;
+    _reservations;
+    constructor(data, reservations = []) {
+        this._data = data;
+        this._reservations = reservations;
+    }
+    /**
+     * Available credits for the user.
+     */
+    get available() {
+        return this._data.credits;
+    }
+    /**
+     * Credit quota for the user.
+     * Returns null if unlimited.
+     */
+    get quota() {
+        return this._data.quota;
+    }
+    /**
+     * Last update timestamp.
+     */
+    get lastUpdate() {
+        return this._data.last_update;
+    }
+    /**
+     * Active credit reservations.
+     */
+    get reservations() {
+        return [...this._reservations];
+    }
+    /**
+     * Total reserved credits across all reservations.
+     */
+    get totalReserved() {
+        return this._reservations.reduce((sum, r) => sum + r.credits, 0);
+    }
+    /**
+     * Net available credits (available minus reserved).
+     */
+    get netAvailable() {
+        return Math.max(0, this.available - this.totalReserved);
+    }
+    /**
+     * Get runtime reservations (reservations that start with 'runtime-').
+     */
+    get runtimeReservations() {
+        return this._reservations.filter(r => r.id.startsWith('runtime-'));
+    }
+    /**
+     * Check if there are any active runtime reservations.
+     */
+    get hasActiveRuntimes() {
+        return this.runtimeReservations.length > 0;
+    }
+    /**
+     * Calculate maximum runtime in minutes based on environment burning rate.
+     *
+     * @param burningRate - Credits consumed per hour
+     * @returns Maximum runtime in minutes
+     */
+    calculateMaxRuntimeMinutes(burningRate) {
+        if (burningRate <= 0)
+            return 0;
+        const burningRatePerMinute = burningRate * 60;
+        return Math.floor(this.netAvailable / burningRatePerMinute);
+    }
+    /**
+     * Calculate credits needed for runtime duration.
+     *
+     * @param minutes - Runtime duration in minutes
+     * @param burningRate - Credits consumed per hour
+     * @returns Credits needed
+     */
+    calculateCreditsFromMinutes(minutes, burningRate) {
+        const burningRatePerMinute = burningRate * 60;
+        return minutes * burningRatePerMinute;
+    }
+    /**
+     * Check if user has enough credits for runtime.
+     *
+     * @param minutes - Runtime duration in minutes
+     * @param burningRate - Credits consumed per hour
+     * @returns True if user has enough credits
+     */
+    hasEnoughCreditsForRuntime(minutes, burningRate) {
+        const creditsNeeded = this.calculateCreditsFromMinutes(minutes, burningRate);
+        return this.netAvailable >= creditsNeeded;
+    }
+    /**
+     * Convert to JSON representation.
+     */
+    toJSON() {
+        // FIXME
+        const obj = {
+            ...this._data,
+            reservations: this._reservations,
+        };
+        validateJSON(obj, 'Credits');
+        return obj;
+    }
+    /**
+     * String representation of credits.
+     */
+    toString() {
+        const quotaStr = this.quota !== null ? ` of ${this.quota}` : '';
+        const reservedStr = this.totalReserved > 0 ? ` (${this.totalReserved} reserved)` : '';
+        return `Credits: ${this.available}${quotaStr}${reservedStr}`;
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Environment domain model for the Datalayer SDK.
+ *
+ * @module client/models/Environment
+ */
+import type { Environment as EnvironmentData } from '../../api/types/runtimes';
+import type { DatalayerClient } from '../index';
+/**
+ * Stable public interface for Environment data.
+ * This is the contract that SDK consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface EnvironmentJSON {
+    /** Human-readable title for the environment */
+    title: string;
+    /** Unique name identifier for the environment */
+    name: string;
+    /** Credits consumed per hour for this environment */
+    burningRate: number;
+    /** Description of the environment (contains HTML markup) */
+    description: string;
+    /** Rich description of the environment (contains HTML markup) */
+    richDescription: string;
+}
+/**
+ * Environment domain model that wraps API responses with convenient methods.
+ * Provides information about available computational environments.
+ *
+ * @example
+ * ```typescript
+ * const environments = await sdk.listEnvironments();
+ * const aiEnv = environments.find(env => env.name === 'ai-env');
+ * console.log(aiEnv.title); // "AI Environment"
+ * ```
+ */
+export declare class Environment {
+    /** @internal */
+    _data: EnvironmentData;
+    /**
+     * Create an Environment instance.
+     *
+     * @param data - Environment data from API
+     * @param _sdk - SDK instance (not currently used but kept for consistency)
+     */
+    constructor(data: EnvironmentData, _sdk: DatalayerClient);
+    /** Human-readable title for the environment (e.g., 'AI Environment', 'Python CPU Environment'). */
+    get title(): string;
+    /** Unique name identifier for the environment (e.g., 'ai-env', 'python-cpu-env'). */
+    get name(): string;
+    /** Credits consumed per hour for this environment. */
+    get burningRate(): number;
+    /** Rich description of the environment (contains HTML markup). */
+    get richDescription(): string;
+    /** Clean description without HTML tags. */
+    get description(): string;
+    /**
+     * Get environment data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core environment data with camelCase properties
+     */
+    toJSON(): EnvironmentJSON;
+    /**
+     * Get the raw environment data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw environment data from API
+     */
+    rawData(): EnvironmentData;
+    /** String representation of the environment. */
+    toString(): string;
+}

package/lib/client/models/Environment.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * Environment domain model that wraps API responses with convenient methods.
+ * Provides information about available computational environments.
+ *
+ * @example
+ * ```typescript
+ * const environments = await sdk.listEnvironments();
+ * const aiEnv = environments.find(env => env.name === 'ai-env');
+ * console.log(aiEnv.title); // "AI Environment"
+ * ```
+ */
+export class Environment {
+    /** @internal */
+    _data;
+    /**
+     * Create an Environment instance.
+     *
+     * @param data - Environment data from API
+     * @param _sdk - SDK instance (not currently used but kept for consistency)
+     */
+    constructor(data, _sdk) {
+        this._data = data;
+        // SDK instance not currently used but kept for future extensibility
+    }
+    // ========================================================================
+    // Properties
+    // ========================================================================
+    /** Human-readable title for the environment (e.g., 'AI Environment', 'Python CPU Environment'). */
+    get title() {
+        return this._data.title;
+    }
+    /** Unique name identifier for the environment (e.g., 'ai-env', 'python-cpu-env'). */
+    get name() {
+        return this._data.name;
+    }
+    /** Credits consumed per hour for this environment. */
+    get burningRate() {
+        return this._data.burning_rate;
+    }
+    /** Rich description of the environment (contains HTML markup). */
+    get richDescription() {
+        return this._data.description;
+    }
+    /** Clean description without HTML tags. */
+    get description() {
+        // Simple HTML tag removal
+        return this._data.description.replace(/<[^>]*>/g, '').trim();
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get environment data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core environment data with camelCase properties
+     */
+    toJSON() {
+        const obj = {
+            title: this.title,
+            name: this.name,
+            burningRate: this.burningRate,
+            description: this.description,
+            richDescription: this.richDescription,
+        };
+        validateJSON(obj, 'Environment');
+        return obj;
+    }
+    /**
+     * Get the raw environment data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw environment data from API
+     */
+    rawData() {
+        return this._data;
+    }
+    /** String representation of the environment. */
+    toString() {
+        return `Environment(${this.name}, ${this.title})`;
+    }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Represents a health check response from a Datalayer service.
+ * Provides standardized health status information across all services.
+ */
+export declare class HealthCheck {
+    healthy: boolean;
+    status: string;
+    responseTime: number;
+    errors: string[];
+    timestamp: Date;
+    /**
+     * Create a HealthCheck instance.
+     * @param data - The health check data
+     * @param sdk - Reference to the SDK instance (unused but kept for consistency)
+     */
+    constructor(data: any, sdk: any);
+    /**
+     * Check if the service is healthy.
+     * @returns True if the service is healthy
+     */
+    isHealthy(): boolean;
+    /**
+     * Get the service status.
+     * @returns The status string
+     */
+    getStatus(): string;
+    /**
+     * Get the response time in milliseconds.
+     * @returns The response time
+     */
+    getResponseTime(): number;
+    /**
+     * Get any errors reported during the health check.
+     * @returns Array of error messages
+     */
+    getErrors(): string[];
+    /**
+     * Get the timestamp of the health check.
+     * @returns The timestamp
+     */
+    getTimestamp(): Date;
+    /**
+     * Check if there are any errors.
+     * @returns True if there are errors
+     */
+    hasErrors(): boolean;
+    /**
+     * Get a human-readable summary of the health check.
+     * @returns Summary string
+     */
+    getSummary(): string;
+    /**
+     * Convert to a plain object.
+     * @returns Plain object representation
+     */
+    toJSON(): Promise<HealthCheckJSON>;
+    /**
+     * Get a string representation.
+     * @returns String representation
+     */
+    toString(): string;
+}
+/**
+ * JSON representation of a HealthCheck.
+ */
+export interface HealthCheckJSON {
+    healthy: boolean;
+    status: string;
+    responseTime: number;
+    errors: string[];
+    timestamp: string;
+}

package/lib/client/models/HealthCheck.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { validateJSON } from '../../api/utils/validation';
+/**
+ * Represents a health check response from a Datalayer service.
+ * Provides standardized health status information across all services.
+ */
+export class HealthCheck {
+    // Properties
+    healthy;
+    status;
+    responseTime;
+    errors;
+    timestamp;
+    /**
+     * Create a HealthCheck instance.
+     * @param data - The health check data
+     * @param sdk - Reference to the SDK instance (unused but kept for consistency)
+     */
+    constructor(data, sdk) {
+        // Initialize properties
+        this.healthy = data.healthy || false;
+        this.status = data.status || 'unknown';
+        this.responseTime = data.responseTime || 0;
+        this.errors = data.errors || [];
+        this.timestamp = data.timestamp ? new Date(data.timestamp) : new Date();
+    }
+    /**
+     * Check if the service is healthy.
+     * @returns True if the service is healthy
+     */
+    isHealthy() {
+        return this.healthy;
+    }
+    /**
+     * Get the service status.
+     * @returns The status string
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Get the response time in milliseconds.
+     * @returns The response time
+     */
+    getResponseTime() {
+        return this.responseTime;
+    }
+    /**
+     * Get any errors reported during the health check.
+     * @returns Array of error messages
+     */
+    getErrors() {
+        return this.errors;
+    }
+    /**
+     * Get the timestamp of the health check.
+     * @returns The timestamp
+     */
+    getTimestamp() {
+        return this.timestamp;
+    }
+    /**
+     * Check if there are any errors.
+     * @returns True if there are errors
+     */
+    hasErrors() {
+        return this.errors.length > 0;
+    }
+    /**
+     * Get a human-readable summary of the health check.
+     * @returns Summary string
+     */
+    getSummary() {
+        if (this.healthy) {
+            return `Service is healthy (${this.responseTime}ms response time)`;
+        }
+        else {
+            const errorCount = this.errors.length;
+            return `Service is unhealthy: ${this.status} (${errorCount} error${errorCount !== 1 ? 's' : ''})`;
+        }
+    }
+    /**
+     * Convert to a plain object.
+     * @returns Plain object representation
+     */
+    async toJSON() {
+        const obj = {
+            healthy: this.healthy,
+            status: this.status,
+            responseTime: this.responseTime,
+            errors: this.errors,
+            timestamp: this.timestamp.toISOString(),
+        };
+        validateJSON(obj, 'HealthCheck');
+        return obj;
+    }
+    /**
+     * Get a string representation.
+     * @returns String representation
+     */
+    toString() {
+        return `HealthCheck(${this.status}, healthy=${this.healthy}, responseTime=${this.responseTime}ms)`;
+    }
+}

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

@@ -0,0 +1,69 @@
+import type { DatalayerClient } from '../index';
+/**
+ * Abstract base class for all Datalayer content items.
+ * Provides common functionality for content management including lifecycle tracking.
+ *
+ * @template TData - Raw data type from API
+ * @template TUpdateRequest - Update request type for API
+ */
+export declare abstract class Item<TData> {
+    protected _data: TData;
+    private _sdk;
+    private _deleted;
+    /**
+     * Create an Item instance.
+     * @param data - Item data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: TData, sdk: DatalayerClient);
+    /** Check if this item has been deleted. */
+    get isDeleted(): boolean;
+    /**
+     * Check if this item has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    protected _checkDeleted(): void;
+    /** Item ID. */
+    get id(): string;
+    /** Unique identifier for the item. */
+    get uid(): string;
+    /** Parent space ID. */
+    get spaceId(): string;
+    /** Owner user ID. */
+    get ownerId(): string;
+    /** When the item was created. */
+    get createdAt(): Date;
+    /** The cached update time. */
+    get updatedAt(): Date;
+    /** Get the item type identifier. */
+    abstract get type(): string;
+    /** The cached name. */
+    abstract get name(): string;
+    /** Get the current name from API. */
+    abstract getName(): Promise<string>;
+    /** The cached content. */
+    abstract get content(): any;
+    /** Get when the item was last updated from API. */
+    abstract getUpdatedAt(): Promise<Date>;
+    /** Update the item. */
+    abstract update(...args: any[]): Promise<this>;
+    /**
+     * Delete this item permanently.
+     * After deletion, all subsequent method calls will throw errors.
+     */
+    delete(): Promise<void>;
+    /** Get the document content from API. */
+    getContent(): Promise<any>;
+    /** Get raw item data object. */
+    rawData(): TData;
+    /** Convert to JSON representation - must be implemented by subclasses. */
+    abstract toJSON(): any;
+    /** String representation of the item. */
+    toString(): string;
+    /** Get SDK token for API calls. */
+    protected _getToken(): string;
+    /** Get spacer API URL for API calls. */
+    protected _getSpacerRunUrl(): string;
+    /** Update internal data after API call. */
+    protected _updateData(newData: TData): void;
+}