@datalayer/core 0.0.27 → 1.0.2

package/lib/hooks/useProjects.js

@@ -0,0 +1,166 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Hook for fetching and managing projects.
+ *
+ * Projects are backed by the Spacer service as spaces with type_s="project".
+ * Projects persist forever — only agents can terminate.
+ *
+ * Free tier limits: max 3 projects per user.
+ *
+ * @module hooks/useProjects
+ */
+import { useMemo, useCallback } from 'react';
+import { useCache } from './useCache';
+/** The space type value used to identify project spaces in Solr */
+export const PROJECT_SPACE_VARIANT = 'project';
+/**
+ * Hook to fetch user's projects (spaces with type "project").
+ *
+ * Uses the spacer service's spaces endpoint filtered by type.
+ */
+export function useProjects() {
+    const { useUserSpaces } = useCache();
+    const { data: allSpaces, ...rest } = useUserSpaces();
+    // Filter to only project-type spaces
+    const projects = useMemo(() => {
+        if (!allSpaces)
+            return [];
+        return allSpaces
+            .filter((space) => space.variant === PROJECT_SPACE_VARIANT ||
+            space.type_s === PROJECT_SPACE_VARIANT)
+            .map((space) => ({
+            uid: space.uid,
+            id: space.id ?? space.uid,
+            handle: space.handle ?? space.handle_s,
+            name: space.name ?? space.name_t,
+            description: space.description ?? space.description_t ?? '',
+            createdAt: space.created_at ? new Date(space.created_at) : new Date(),
+            isPublic: space.public ?? space.public_b ?? false,
+            attachedAgentPodName: space.attached_agent_pod_name_s || undefined,
+            attachedAgentSpecId: space.attached_agent_spec_id_s || undefined,
+        }));
+    }, [allSpaces]);
+    return { data: projects, ...rest };
+}
+/**
+ * Hook to fetch a single project by UID.
+ */
+export function useProject(uid) {
+    const { useSpace } = useCache();
+    // useSpace requires a string – pass empty string when uid is undefined
+    // (the query is disabled when spaceId is falsy inside useCache)
+    const { data: space, ...rest } = useSpace(uid ?? '');
+    const project = useMemo(() => {
+        if (!space)
+            return undefined;
+        const s = space;
+        return {
+            uid: s.uid,
+            id: s.id ?? s.uid,
+            handle: s.handle ?? s.handle_s,
+            name: s.name ?? s.name_t,
+            description: s.description ?? s.description_t ?? '',
+            createdAt: s.created_at ? new Date(s.created_at) : new Date(),
+            isPublic: s.public ?? s.public_b ?? false,
+            attachedAgentPodName: s.attached_agent_pod_name_s || undefined,
+            attachedAgentSpecId: s.attached_agent_spec_id_s || undefined,
+        };
+    }, [space]);
+    return { data: project, ...rest };
+}
+/**
+ * Hook to create a new project.
+ * Creates a space with type "project" via the spacer service.
+ */
+export function useCreateProject() {
+    const { useCreateSpace } = useCache();
+    const createSpaceMutation = useCreateSpace();
+    const createProject = useCallback(async (request) => {
+        const spaceHandle = request.name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '');
+        return createSpaceMutation.mutateAsync({
+            space: {
+                name: request.name,
+                description: request.description || '',
+                handle: spaceHandle || `project-${Date.now()}`,
+                variant: PROJECT_SPACE_VARIANT,
+                public: false,
+            },
+        });
+    }, [createSpaceMutation]);
+    return {
+        ...createSpaceMutation,
+        createProject,
+    };
+}
+/**
+ * Hook to update a project (e.g. persist the attached agent pod name).
+ * Uses the spacer PUT endpoint via useUpdateSpace.
+ */
+export function useUpdateProject() {
+    const { useUpdateSpace } = useCache();
+    const updateSpaceMutation = useUpdateSpace();
+    /** Assign an agent runtime to the project */
+    const assignAgent = useCallback(async (project, agentPodName, agentSpecId) => {
+        return updateSpaceMutation.mutateAsync({
+            id: project.id,
+            name: project.name,
+            description: project.description,
+            attached_agent_pod_name_s: agentPodName,
+            attached_agent_spec_id_s: agentSpecId || '',
+        });
+    }, [updateSpaceMutation]);
+    /** Rename a project */
+    const renameProject = useCallback(async (project, newName) => {
+        return updateSpaceMutation.mutateAsync({
+            id: project.id,
+            name: newName,
+            description: project.description,
+        });
+    }, [updateSpaceMutation]);
+    /** Remove the agent assignment from the project */
+    const unassignAgent = useCallback(async (project) => {
+        return updateSpaceMutation.mutateAsync({
+            id: project.id,
+            name: project.name,
+            description: project.description,
+            attached_agent_pod_name_s: '',
+            attached_agent_spec_id_s: '',
+        });
+    }, [updateSpaceMutation]);
+    return {
+        ...updateSpaceMutation,
+        assignAgent,
+        unassignAgent,
+        renameProject,
+    };
+}
+/**
+ * Hook to refresh the projects list.
+ */
+export function useRefreshProjects() {
+    const { useRefreshUserSpaces } = useCache();
+    return useRefreshUserSpaces();
+}
+/**
+ * Hook to delete a project (space) and all its contents.
+ */
+export function useDeleteProject() {
+    const { useDeleteSpace } = useCache();
+    return useDeleteSpace();
+}
+/**
+ * Hook to fetch the default notebook and document UIDs for a project.
+ *
+ * This calls the spacer `GET /spaces/{uid}/default-items` endpoint which
+ * returns the UID of the first notebook and first document in the space.
+ */
+export function useProjectDefaultItems(projectUid) {
+    const { useSpaceDefaultItems } = useCache();
+    return useSpaceDefaultItems(projectUid);
+}

package/lib/index.d.ts

@@ -5,7 +5,6 @@ export * from './collaboration';
 export * from './services';
 export * from './navigation';
 export * from './hooks';
-export * from './theme';
 export { requestDatalayerAPI, RunResponseError, NetworkError, } from './api/DatalayerApi';
 export type { IRequestDatalayerAPIOptions } from './api/DatalayerApi';
 export { API_BASE_PATHS } from './api/constants';

package/lib/index.js

@@ -11,8 +11,6 @@ export * from './services';
 // Export navigation before hooks to avoid conflicts
 export * from './navigation';
 export * from './hooks';
-// Export Theme.
-export * from './theme';
 // Export APIs.
 export { requestDatalayerAPI, RunResponseError, NetworkError, } from './api/DatalayerApi';
 export { API_BASE_PATHS } from './api/constants';

package/lib/models/CreditsDTO.d.ts

@@ -42,7 +42,7 @@ export interface CreditsResponse {
  *
  * @example
  * ```typescript
- * const credits = await sdk.getCredits();
+ * const credits = await client.getCredits();
  * console.log(`Available: ${credits.available}`);
  * console.log(`Quota: ${credits.quota || 'unlimited'}`);
  *

package/lib/models/CreditsDTO.js

@@ -13,7 +13,7 @@ import { validateJSON } from '../api/utils/validation';
  *
  * @example
  * ```typescript
- * const credits = await sdk.getCredits();
+ * const credits = await client.getCredits();
  * console.log(`Available: ${credits.available}`);
  * console.log(`Quota: ${credits.quota || 'unlimited'}`);
  *

package/lib/models/Datasource.d.ts

@@ -126,7 +126,7 @@ export interface UpdateDatasourceResponse {
  *
  * @example
  * ```typescript
- * const datasource = await sdk.createDatasource({
+ * const datasource = await client.createDatasource({
  *   type: 'Amazon Athena',
  *   name: 'my-athena-datasource',
  *   description: 'Production Athena datasource',
@@ -141,14 +141,14 @@ export interface UpdateDatasourceResponse {
 export declare class DatasourceDTO {
     /** @internal */
     _data: DatasourceData;
-    private _sdk;
+    private _client;
     private _deleted;
     /**
      * Create a Datasource instance.
      * @param data - Datasource data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data: DatasourceData, sdk: DatalayerClient);
+    constructor(data: DatasourceData, client: DatalayerClient);
     private _checkDeleted;
     get uid(): string;
     get type(): DatasourceType;

package/lib/models/Datasource.js

@@ -25,7 +25,7 @@ import { validateJSON } from '../api/utils/validation';
  *
  * @example
  * ```typescript
- * const datasource = await sdk.createDatasource({
+ * const datasource = await client.createDatasource({
  *   type: 'Amazon Athena',
  *   name: 'my-athena-datasource',
  *   description: 'Production Athena datasource',
@@ -40,16 +40,16 @@ import { validateJSON } from '../api/utils/validation';
 export class DatasourceDTO {
     /** @internal */
     _data;
-    _sdk;
+    _client;
     _deleted = false;
     /**
      * Create a Datasource instance.
      * @param data - Datasource data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data, sdk) {
+    constructor(data, client) {
         this._data = data;
-        this._sdk = sdk;
+        this._client = client;
     }
     // ========================================================================
     // Helper Methods
@@ -108,7 +108,7 @@ export class DatasourceDTO {
      */
     async update(updates) {
         this._checkDeleted();
-        const updated = await this._sdk.updateDatasource(this.uid, updates);
+        const updated = await this._client.updateDatasource(this.uid, updates);
         return updated;
     }
     /**
@@ -116,7 +116,7 @@ export class DatasourceDTO {
      */
     async delete() {
         this._checkDeleted();
-        await this._sdk.deleteDatasource(this.uid);
+        await this._client.deleteDatasource(this.uid);
         this._deleted = true;
     }
     // ========================================================================

package/lib/models/EnvironmentDTO.d.ts

@@ -80,7 +80,7 @@ export interface ListEnvironmentsResponse {
  *
  * @example
  * ```typescript
- * const environments = await sdk.listEnvironments();
+ * const environments = await client.listEnvironments();
  * const aiEnv = environments.find(env => env.name === 'ai-env');
  * console.log(aiEnv.title); // "AI Environment"
  * ```
@@ -92,9 +92,9 @@ export declare class EnvironmentDTO {
      * Create an Environment instance.
      *
      * @param data - Environment data from API
-     * @param _sdk - Client instance (not currently used but kept for consistency)
+     * @param _client - Client instance (not currently used but kept for consistency)
      */
-    constructor(data: EnvironmentData, _sdk: DatalayerClient);
+    constructor(data: EnvironmentData, _client: 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'). */

package/lib/models/EnvironmentDTO.js

@@ -9,7 +9,7 @@ import { validateJSON } from '../api/utils/validation';
  *
  * @example
  * ```typescript
- * const environments = await sdk.listEnvironments();
+ * const environments = await client.listEnvironments();
  * const aiEnv = environments.find(env => env.name === 'ai-env');
  * console.log(aiEnv.title); // "AI Environment"
  * ```
@@ -21,9 +21,9 @@ export class EnvironmentDTO {
      * Create an Environment instance.
      *
      * @param data - Environment data from API
-     * @param _sdk - Client instance (not currently used but kept for consistency)
+     * @param _client - Client instance (not currently used but kept for consistency)
      */
-    constructor(data, _sdk) {
+    constructor(data, _client) {
         this._data = data;
         // Client instance not currently used but kept for future extensibility
     }

package/lib/models/HealthCheck.d.ts

@@ -11,9 +11,9 @@ export declare class HealthCheck {
     /**
      * Create a HealthCheck instance.
      * @param data - The health check data
-     * @param sdk - Reference to the Client instance (unused but kept for consistency)
+     * @param client - Reference to the Client instance (unused but kept for consistency)
      */
-    constructor(data: any, sdk: any);
+    constructor(data: any, client: any);
     /**
      * Check if the service is healthy.
      * @returns True if the service is healthy

package/lib/models/HealthCheck.js

@@ -17,9 +17,9 @@ export class HealthCheck {
     /**
      * Create a HealthCheck instance.
      * @param data - The health check data
-     * @param sdk - Reference to the Client instance (unused but kept for consistency)
+     * @param client - Reference to the Client instance (unused but kept for consistency)
      */
-    constructor(data, sdk) {
+    constructor(data, client) {
         // Initialize properties
         this.healthy = data.healthy || false;
         this.status = data.status || 'unknown';

package/lib/models/ItemDTO.d.ts

@@ -13,14 +13,14 @@ import type { DatalayerClient } from '../index';
  */
 export declare abstract class ItemDTO<TData> {
     protected _data: TData;
-    private _sdk;
+    private _client;
     private _deleted;
     /**
      * Create an Item instance.
      * @param data - Item data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data: TData, sdk: DatalayerClient);
+    constructor(data: TData, client: DatalayerClient);
     /** Check if this item has been deleted. */
     get isDeleted(): boolean;
     /**

package/lib/models/ItemDTO.js

@@ -12,16 +12,16 @@ import * as items from '../api/spacer/items';
  */
 export class ItemDTO {
     _data;
-    _sdk;
+    _client;
     _deleted = false;
     /**
      * Create an Item instance.
      * @param data - Item data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data, sdk) {
+    constructor(data, client) {
         this._data = data;
-        this._sdk = sdk;
+        this._client = client;
     }
     // ========================================================================
     // Deletion State Management
@@ -105,8 +105,8 @@ export class ItemDTO {
      */
     async delete() {
         this._checkDeleted();
-        const token = this._sdk.getToken();
-        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const token = this._client.getToken();
+        const spacerRunUrl = this._client.getSpacerRunUrl();
         await items.deleteItem(token, this.uid, spacerRunUrl);
         this._deleted = true;
     }
@@ -137,8 +137,8 @@ export class ItemDTO {
         }
         // Third try: Fetch full item details from API
         try {
-            const token = this._sdk.getToken();
-            const spacerRunUrl = this._sdk.getSpacerRunUrl();
+            const token = this._client.getToken();
+            const spacerRunUrl = this._client.getSpacerRunUrl();
             const response = await items.getItem(token, this.uid, spacerRunUrl);
             // Update internal data with full item details
             if (response.success && response.item) {
@@ -173,11 +173,11 @@ export class ItemDTO {
     // ========================================================================
     /** Get Client token for API calls. */
     _getToken() {
-        return this._sdk.getToken();
+        return this._client.getToken();
     }
     /** Get spacer API URL for API calls. */
     _getSpacerRunUrl() {
-        return this._sdk.getSpacerRunUrl();
+        return this._client.getSpacerRunUrl();
     }
     /** Update internal data after API call. */
     _updateData(newData) {

package/lib/models/LexicalDTO.d.ts

@@ -109,7 +109,7 @@ export interface LexicalJSON {
  *
  * @example
  * ```typescript
- * const lexical = await sdk.createLexical(formData);
+ * const lexical = await client.createLexical(formData);
  * await lexical.update({ name: 'Updated Documentation' });
  * ```
  */
@@ -118,9 +118,9 @@ export declare class LexicalDTO extends ItemDTO<LexicalData> {
      * Create a Lexical instance.
      *
      * @param data - Lexical data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data: LexicalData, sdk: DatalayerClient);
+    constructor(data: LexicalData, client: DatalayerClient);
     /** Document type identifier. */
     get type(): string;
     /** The cached name of the document. */

package/lib/models/LexicalDTO.js

@@ -17,7 +17,7 @@ import { validateJSON } from '../api/utils/validation';
  *
  * @example
  * ```typescript
- * const lexical = await sdk.createLexical(formData);
+ * const lexical = await client.createLexical(formData);
  * await lexical.update({ name: 'Updated Documentation' });
  * ```
  */
@@ -26,10 +26,10 @@ export class LexicalDTO extends ItemDTO {
      * Create a Lexical instance.
      *
      * @param data - Lexical data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data, sdk) {
-        super(data, sdk);
+    constructor(data, client) {
+        super(data, client);
     }
     // ========================================================================
     // Abstract Method Implementations

package/lib/models/NotebookDTO.d.ts

@@ -42,7 +42,7 @@ export interface NotebookJSON {
  *
  * @example
  * ```typescript
- * const notebook = await sdk.createNotebook(formData);
+ * const notebook = await client.createNotebook(formData);
  * const kernelSpec = await notebook.getKernelSpec();
  * ```
  */
@@ -51,9 +51,9 @@ export declare class NotebookDTO extends ItemDTO<NotebookData> {
      * Create a Notebook instance.
      *
      * @param data - Notebook data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data: NotebookData, sdk: DatalayerClient);
+    constructor(data: NotebookData, client: DatalayerClient);
     /** Document type identifier. */
     get type(): string;
     /** The cached name of the notebook. */

package/lib/models/NotebookDTO.js

@@ -12,7 +12,7 @@ import { validateJSON } from '../api/utils/validation';
  *
  * @example
  * ```typescript
- * const notebook = await sdk.createNotebook(formData);
+ * const notebook = await client.createNotebook(formData);
  * const kernelSpec = await notebook.getKernelSpec();
  * ```
  */
@@ -21,10 +21,10 @@ export class NotebookDTO extends ItemDTO {
      * Create a Notebook instance.
      *
      * @param data - Notebook data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data, sdk) {
-        super(data, sdk);
+    constructor(data, client) {
+        super(data, client);
     }
     // ========================================================================
     // Abstract Method Implementations
@@ -74,8 +74,8 @@ export class NotebookDTO extends ItemDTO {
     async update(name, description) {
         // FIXME: check if both are needed, and use the existing values if only one provided
         this._checkDeleted();
-        const token = this._sdk.getToken();
-        const spacerRunUrl = this._sdk.getSpacerRunUrl();
+        const token = this._client.getToken();
+        const spacerRunUrl = this._client.getSpacerRunUrl();
         const updateData = {};
         if (name !== undefined)
             updateData.name = name;

package/lib/models/Page.d.ts

@@ -31,6 +31,8 @@ export type IPage = {
     creatorId?: string;
     kernelSnapshot?: IRuntimeSnapshot;
     kernelSnapshotId?: string;
+    createdAt?: string;
+    updatedAt?: string;
 };
 export declare const asPage: (s: any) => IPage;
 export default IPage;

package/lib/models/RuntimeDTO.d.ts

@@ -105,22 +105,22 @@ export interface ListRuntimesResponse {
  *
  * @example
  * ```typescript
- * const runtime = await sdk.createRuntime({ environment_name: 'python-cpu' });
+ * const runtime = await client.createRuntime({ environment_name: 'python-cpu' });
  * await runtime.waitUntilReady();
  * ```
  */
 export declare class RuntimeDTO {
     /** @internal */
     _data: RuntimeData;
-    private _sdk;
+    private _client;
     private _deleted;
     /**
      * Create a Runtime instance.
      *
      * @param data - Runtime data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data: RuntimeData, sdk: DatalayerClient);
+    constructor(data: RuntimeData, client: DatalayerClient);
     /**
      * Check if this runtime has been deleted and throw error if so.
      * @throws Error if deleted

package/lib/models/RuntimeDTO.js

@@ -15,24 +15,24 @@ import { validateJSON } from '../api/utils/validation';
  *
  * @example
  * ```typescript
- * const runtime = await sdk.createRuntime({ environment_name: 'python-cpu' });
+ * const runtime = await client.createRuntime({ environment_name: 'python-cpu' });
  * await runtime.waitUntilReady();
  * ```
  */
 export class RuntimeDTO {
     /** @internal */
     _data;
-    _sdk;
+    _client;
     _deleted = false;
     /**
      * Create a Runtime instance.
      *
      * @param data - Runtime data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data, sdk) {
+    constructor(data, client) {
         this._data = data;
-        this._sdk = sdk;
+        this._client = client;
     }
     // ========================================================================
     // Helper Methods
@@ -112,7 +112,7 @@ export class RuntimeDTO {
      * After deletion, subsequent calls to dynamic methods will throw errors.
      */
     async delete() {
-        await this._sdk.deleteRuntime(this.podName);
+        await this._client.deleteRuntime(this.podName);
         this._deleted = true;
     }
     /**
@@ -123,8 +123,8 @@ export class RuntimeDTO {
      */
     async update(from) {
         this._checkDeleted();
-        const updated = await updateRuntime(this._sdk.getToken(), this.podName, from, this._sdk.getRuntimesRunUrl());
-        return new RuntimeDTO(updated, this._sdk);
+        const updated = await updateRuntime(this._client.getToken(), this.podName, from, this._client.getRuntimesRunUrl());
+        return new RuntimeDTO(updated, this._client);
     }
     /**
      * Create a snapshot of this runtime.
@@ -136,7 +136,7 @@ export class RuntimeDTO {
      */
     async createSnapshot(name, description, stop) {
         this._checkDeleted();
-        return await this._sdk.createSnapshot(this.podName, name, description, stop);
+        return await this._client.createSnapshot(this.podName, name, description, stop);
     }
     // ========================================================================
     // Utility Methods

package/lib/models/RuntimeSnapshotDTO.d.ts

@@ -116,15 +116,15 @@ export interface ListRuntimeSnapshotsResponse {
  */
 export declare class RuntimeSnapshotDTO {
     protected _data: RuntimeSnapshotData;
-    private _sdk;
+    private _client;
     private _deleted;
     /**
      * Create a Runtime Snapshot instance.
      *
      * @param data - Snapshot data from API
-     * @param sdk - Client instance
+     * @param client - Client instance
      */
-    constructor(data: RuntimeSnapshotData, sdk: DatalayerClient);
+    constructor(data: RuntimeSnapshotData, client: DatalayerClient);
     /**
      * Check if this snapshot has been deleted and throw error if so.
      * @throws Error if deleted