@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/models/RuntimeDTO.js

@@ -0,0 +1,204 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Runtime domain model for the Datalayer Client.
+ *
+ * @module models/RuntimeDTO
+ */
+import { updateRuntime } from '../api/runtimes/runtimes';
+import { validateJSON } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Runtime domain model that wraps API responses with convenient methods.
+ * Provides state management and lifecycle operations for computational runtimes.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await client.createRuntime({ environment_name: 'python-cpu' });
+ * await runtime.waitUntilReady();
+ * ```
+ */
+export class RuntimeDTO {
+    /** @internal */
+    _data;
+    _client;
+    _deleted = false;
+    /**
+     * Create a Runtime instance.
+     *
+     * @param data - Runtime data from API
+     * @param client - Client instance
+     */
+    constructor(data, client) {
+        this._data = data;
+        this._client = client;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this runtime has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Runtime ${this._data.pod_name} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Kubernetes pod name for the runtime instance. */
+    get podName() {
+        this._checkDeleted();
+        return this._data.pod_name;
+    }
+    /** Unique identifier for the runtime. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** Name of the environment this runtime is based on. */
+    get environmentName() {
+        this._checkDeleted();
+        return this._data.environment_name;
+    }
+    /** Ingress URL for accessing the runtime. */
+    get ingress() {
+        this._checkDeleted();
+        return this._data.ingress;
+    }
+    /** Authentication token for accessing the runtime. */
+    get token() {
+        this._checkDeleted();
+        return this._data.token;
+    }
+    /** Credits consumed per second. */
+    get burningRate() {
+        this._checkDeleted();
+        return this._data.burning_rate;
+    }
+    /** User-friendly name for the runtime. */
+    get givenName() {
+        this._checkDeleted();
+        return this._data.given_name;
+    }
+    /** Type of runtime (notebook, terminal, or job). */
+    get type() {
+        this._checkDeleted();
+        return this._data.type;
+    }
+    /** When the runtime started. */
+    get startedAt() {
+        this._checkDeleted();
+        return new Date(Number(this._data.started_at) * 1000);
+    }
+    /** When the runtime will expire. */
+    get expiredAt() {
+        this._checkDeleted();
+        return new Date(Number(this._data.expired_at) * 1000);
+    }
+    /** Environment title for display. */
+    get environmentTitle() {
+        this._checkDeleted();
+        return this._data.environment_title || '';
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this runtime permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    async delete() {
+        await this._client.deleteRuntime(this.podName);
+        this._deleted = true;
+    }
+    /**
+     * Update runtime from a snapshot.
+     *
+     * @param from - Snapshot identifier to restore from
+     * @returns Updated Runtime instance
+     */
+    async update(from) {
+        this._checkDeleted();
+        const updated = await updateRuntime(this._client.getToken(), this.podName, from, this._client.getRuntimesUrl());
+        return new RuntimeDTO(updated, this._client);
+    }
+    /**
+     * Create a snapshot of this runtime.
+     *
+     * @param name - Name for the snapshot
+     * @param description - Optional description
+     * @param stop - Whether to stop runtime after snapshotting
+     * @returns Created Snapshot instance
+     */
+    async createSnapshot(name, description, stop) {
+        this._checkDeleted();
+        return await this._client.createSnapshot(this.podName, name, description, stop);
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get runtime data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Core runtime data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        // Safely convert dates to ISO strings, handling invalid dates
+        const safeToISO = (date) => {
+            try {
+                const iso = date.toISOString();
+                return iso;
+            }
+            catch {
+                // If date is invalid, return empty string or current time
+                return new Date().toISOString();
+            }
+        };
+        const obj = {
+            // Core identifiers
+            uid: this.uid,
+            podName: this.podName,
+            givenName: this.givenName,
+            // Environment info
+            environmentName: this.environmentName,
+            environmentTitle: this.environmentTitle,
+            // State and type
+            type: this.type,
+            // Burning
+            burningRate: this.burningRate,
+            // URLs and tokens
+            // FIXME: Consider renaming? jupyterServerUrl and jupyterServerToken
+            ingress: this.ingress,
+            token: this.token,
+            // Timing
+            startedAt: safeToISO(this.startedAt),
+            expiredAt: safeToISO(this.expiredAt),
+        };
+        validateJSON(obj, 'Runtime');
+        return obj;
+    }
+    /**
+     * Get the raw runtime data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Raw runtime data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the runtime. */
+    toString() {
+        this._checkDeleted();
+        return `Runtime(${this.podName}, ${this.environmentName})`;
+    }
+}

package/lib/models/Space.d.ts

@@ -0,0 +1,35 @@
+import { SpaceMember } from './SpaceMember';
+import { ISpaceItem } from './SpaceItem';
+import { ICourse as ICourse } from './Course';
+import { IOrganization } from '@datalayer/core/lib/models/Organization';
+import { IUser } from '@datalayer/core/lib/models/User';
+/**
+ * Convert the raw space object to {@link ISpace}.
+ *
+ * @param user Raw space object from DB
+ * @returns Space
+ */
+export declare const asSpace: (raw_space: any) => ISpace;
+export type ISpaceVariant = 'default' | 'course' | 'project';
+export type IAnySpace = ISpace | ICourse;
+export type IBaseSpace = {
+    id: string;
+    handle: string;
+    type: string;
+    variant: ISpaceVariant;
+    name: string;
+    description: string;
+    creationDate: Date;
+    public: boolean;
+    owner: IUser;
+    organization?: Partial<IOrganization>;
+    members?: SpaceMember[];
+    sharedOwnerUserUids?: string[];
+};
+export type ISpace = IBaseSpace & {
+    type: 'space';
+    variant: 'default';
+    items?: Array<ISpaceItem>;
+    itemIds?: Array<string>;
+};
+export default ISpace;

package/lib/models/Space.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { asUser } from '@datalayer/core/lib/models/User';
+import { asArray } from '@datalayer/core/lib/utils';
+/**
+ * Convert the raw space object to {@link ISpace}.
+ *
+ * @param user Raw space object from DB
+ * @returns Space
+ */
+export const asSpace = (raw_space) => {
+    const sharedOwnerUserUids = asArray(raw_space?.shared_owner_user_uids_ss ||
+        raw_space?.shared_ower_user_uids_ss ||
+        []).filter((uid) => typeof uid === 'string' && uid.length > 0);
+    // The backend resolves the canonical (friendly) account handles and exposes
+    // them as `space.owner` and `space.organization`. Trust those single sources
+    // of truth; do not invent fallbacks here.
+    const organizationHandle = raw_space?.organization?.handle;
+    const owner = raw_space?.owner
+        ? asUser(raw_space.owner)
+        : {
+            id: '',
+            handle: '',
+            email: '',
+            firstName: '',
+            lastName: '',
+            initials: '',
+            displayName: '',
+            roles: [],
+            iamProviders: [],
+            setRoles: () => { },
+            unsubscribedFromOutbounds: false,
+            onboarding: {},
+            events: [],
+            settings: {},
+        };
+    let members = new Array();
+    if (raw_space.members) {
+        members = asArray(raw_space.members).map(m => {
+            const member = asUser(m);
+            return member;
+        });
+    }
+    const space = {
+        id: raw_space.uid,
+        handle: raw_space.handle_s,
+        type: 'space',
+        variant: raw_space.variant_s,
+        name: raw_space.name_t,
+        description: raw_space.description_t,
+        public: raw_space.public_b,
+        members,
+        creationDate: new Date(raw_space.creation_ts_dt),
+        owner,
+        organization: organizationHandle
+            ? { handle: organizationHandle }
+            : undefined,
+        sharedOwnerUserUids,
+        // Preserve raw Solr fields so consumers can access dynamic fields
+        // (e.g. attached_agent_pod_name_s for project-agent assignment)
+        ...raw_space,
+    };
+    return space;
+};

package/lib/models/SpaceDTO.d.ts

@@ -0,0 +1,334 @@
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+import { NotebookDTO, type NotebookJSON } from './NotebookDTO';
+import { NotebookData } from './NotebookDTO';
+import { LexicalDTO, type LexicalJSON } from './LexicalDTO';
+/**
+ * Represents a workspace or project space in Datalayer
+ * @interface SpaceData
+ */
+export interface SpaceData {
+    uid: string;
+    id?: string;
+    name_t: string;
+    handle_s: string;
+    variant_s: string;
+    description_t: string;
+    tags_ss?: string[];
+    members?: any[];
+    items?: any[];
+    public_b?: boolean;
+    creation_ts_dt?: string;
+    attached_agent_pod_name_s?: string;
+    attached_agent_spec_id_s?: string;
+    attached_agent_given_name_s?: string;
+    shared_owner_user_uids_ss?: string[];
+    shared_ower_user_uids_ss?: string[];
+}
+/**
+ * Stable public interface for Space data.
+ * This is the contract that Client consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface SpaceJSON {
+    /** ulid for the space */
+    uid: string;
+    /** Name of the space */
+    name: string;
+    /** Handle for the space */
+    handle: string;
+    /** Variant of the space */
+    variant: string;
+    /** Description of the space */
+    description: string;
+    /** Items contained in the space (as JSON) */
+    items: Array<NotebookJSON | LexicalJSON>;
+    /** Owner user UIDs for this space */
+    ownerUserUids?: string[];
+}
+/**
+ * Space domain model that wraps API responses with convenient methods.
+ * Provides workspace management with data refresh and content creation operations.
+ *
+ * @example
+ * ```typescript
+ * const space = spaces[0];
+ * const items = await space.getItems();
+ * const notebook = await space.createNotebook({ name: 'Analysis' });
+ * ```
+ */
+export declare class SpaceDTO {
+    protected _data: SpaceData;
+    private _client;
+    private _items;
+    private _deleted;
+    /**
+     * Create a Space instance.
+     *
+     * @param data - Space data from API
+     * @param client - Client instance
+     */
+    constructor(data: SpaceData, client: DatalayerClient);
+    /**
+     * Check if this space has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    private _checkDeleted;
+    /**
+     * Refresh space data from the API by fetching user's spaces.
+     */
+    refresh(): Promise<void>;
+    /** Unique identifier for the space. */
+    get uid(): string;
+    /** URL-friendly handle for the space. */
+    get handle(): string;
+    /** Space variant type. */
+    get variant(): string;
+    /**
+     * The name of the space.
+     */
+    get name(): string;
+    /**
+     * The description of the space.
+     */
+    get description(): string;
+    /**
+     * Helper method to create items in this space.
+     *
+     * @param itemType - Type of item to create
+     * @param data - Creation configuration
+     * @returns Created model instance
+     * @internal
+     */
+    private _createItem;
+    /**
+     * Get all items in this space as model instances.
+     *
+     * @returns Array of Notebook and Lexical model instances
+     */
+    getItems(): Promise<(NotebookDTO | LexicalDTO)[]>;
+    /**
+     * Create a new notebook in this space.
+     *
+     * @param data - Notebook creation configuration
+     * @returns Created Notebook instance
+     */
+    createNotebook(data: {
+        name: string;
+        description: string;
+        file?: File | Blob;
+    }): Promise<NotebookDTO>;
+    /**
+     * Create a new lexical document in this space.
+     *
+     * @param data - Lexical creation configuration
+     * @returns Created Lexical instance
+     */
+    createLexical(data: {
+        name: string;
+        description: string;
+        file?: File | Blob;
+    }): Promise<LexicalDTO>;
+    /**
+     * Get raw space data object.
+     * Returns cached data without refreshing.
+     *
+     * @returns Raw space data object
+     */
+    /**
+     * Get space data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core space data with camelCase properties
+     */
+    toJSON(): SpaceJSON;
+    /**
+     * Get the raw space data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw space data from API
+     */
+    rawData(): SpaceData;
+    /** String representation of the space. */
+    toString(): string;
+}
+/**
+ * Request payload for creating a new space
+ * @interface CreateSpaceRequest
+ */
+export interface CreateSpaceRequest {
+    name: string;
+    description: string;
+    variant: string;
+    spaceHandle: string;
+    organizationId: string;
+    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
+ */
+export interface CreateSpaceResponse {
+    success: boolean;
+    message: string;
+    space?: SpaceData;
+}
+/**
+ * Request payload for creating a new notebook (multipart/form-data)
+ * @interface CreateNotebookRequest
+ */
+export interface CreateNotebookRequest {
+    spaceId: string;
+    notebookType: string;
+    name: string;
+    description: string;
+    file?: File | Blob;
+}
+/**
+ * Response from creating a notebook
+ * @interface CreateNotebookResponse
+ */
+export interface CreateNotebookResponse {
+    success: boolean;
+    message: string;
+    notebook?: NotebookData;
+}
+/**
+ * Response from getting a notebook
+ * @interface GetNotebookResponse
+ */
+export interface GetNotebookResponse {
+    success: boolean;
+    message: string;
+    notebook?: NotebookData;
+}
+/**
+ * Request payload for updating a notebook
+ * @interface UpdateNotebookRequest
+ */
+export interface UpdateNotebookRequest {
+    name?: string;
+    description?: string;
+}
+/**
+ * Response from updating a notebook
+ * @interface UpdateNotebookResponse
+ */
+export interface UpdateNotebookResponse {
+    success: boolean;
+    message: string;
+    notebook?: NotebookData;
+}
+/**
+ * Represents an item within a space
+ * @interface SpaceItem
+ */
+export interface SpaceItem {
+    id: string;
+    type_s: 'notebook' | 'lexical';
+    space_id: string;
+    item_id: string;
+    name: string;
+    created_at: string;
+    updated_at?: string;
+}
+/**
+ * Response from getting space items
+ * @interface GetSpaceItemsResponse
+ */
+export interface GetSpaceItemsResponse {
+    success: boolean;
+    message: string;
+    items: SpaceItem[];
+}
+/**
+ * Response from deleting a space item
+ * @interface DeleteSpaceItemResponse
+ */
+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
+ */
+export interface SpacesForUserResponse {
+    success: boolean;
+    message: string;
+    spaces: SpaceData[];
+}
+/**
+ * Request payload for updating a space.
+ * Supports arbitrary Solr fields via index signature.
+ * @interface UpdateSpaceRequest
+ */
+export interface UpdateSpaceRequest {
+    name?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * Response from getting a space by ID
+ * @interface GetSpaceResponse
+ */
+export interface GetSpaceResponse {
+    success: boolean;
+    message: string;
+    space?: SpaceData;
+}
+/**
+ * Response from updating a space
+ * @interface UpdateSpaceResponse
+ */
+export interface UpdateSpaceResponse {
+    success: boolean;
+    message: string;
+    space?: SpaceData;
+}
+/**
+ * Response from deleting a space
+ * @interface DeleteSpaceResponse
+ */
+export interface DeleteSpaceResponse {
+    success: boolean;
+    message: string;
+}
+/**
+ * Response from getting default items for a space
+ * @interface GetSpaceDefaultItemsResponse
+ */
+export interface GetSpaceDefaultItemsResponse {
+    success: boolean;
+    message: string;
+    default_notebook_uid: string | null;
+    default_document_uid: string | null;
+}
+/**
+ * Response from getting spaces by type
+ * @interface GetSpacesByTypeResponse
+ */
+export interface GetSpacesByTypeResponse {
+    success: boolean;
+    message: string;
+    spaces: SpaceData[];
+}