@datalayer/core 0.0.13 → 0.0.14

package/lib/{client/models/Snapshot.js → models/RuntimeSnapshotDTO.js}

@@ -2,8 +2,8 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { snapshots } from '../../api/runtimes';
-import { validateJSON } from '../../api/utils/validation';
+import { snapshots } from '../api/runtimes';
+import { validateJSON } from '../api/utils/validation';
 /**
  * Snapshot domain model that wraps API responses with convenient methods.
  * Provides runtime snapshot management with data refresh and lifecycle operations.
@@ -14,12 +14,12 @@ import { validateJSON } from '../../api/utils/validation';
  * const runtime = await snapshot.restore();
  * ```
  */
-export class Snapshot {
+export class RuntimeSnapshotDTO {
     _data;
     _sdk;
     _deleted = false;
     /**
-     * Create a Snapshot instance.
+     * Create a Runtime Snapshot instance.
      *
      * @param data - Snapshot data from API
      * @param sdk - SDK instance

package/lib/models/SpaceDTO.d.ts

@@ -0,0 +1,280 @@
+import type { DatalayerClient } from '../index';
+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;
+    name_t: string;
+    handle_s: string;
+    variant_s: string;
+    description_t: string;
+    tags_ss?: string[];
+    members?: any[];
+    items?: any[];
+}
+/**
+ * Stable public interface for Space data.
+ * This is the contract that SDK 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>;
+}
+/**
+ * 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 _sdk;
+    private _items;
+    private _deleted;
+    /**
+     * Create a Space instance.
+     *
+     * @param data - Space data from API
+     * @param sdk - SDK instance
+     */
+    constructor(data: SpaceData, sdk: 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 creating a notebook
+ * @interface CreateNotebookRequest
+ */
+export interface CreateNotebookRequest {
+    spaceId: string;
+    notebookType: string;
+    name: string;
+    description: string;
+    file?: File | Blob;
+}
+/**
+ * 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[];
+}

package/lib/{client/models/Space.js → models/SpaceDTO.js}

@@ -2,15 +2,20 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import * as users from '../../api/spacer/users';
-import * as items from '../../api/spacer/items';
-import * as notebooks from '../../api/spacer/notebooks';
-import * as lexicals from '../../api/spacer/lexicals';
-import { Notebook } from './Notebook';
-import { Lexical } from './Lexical';
-import { ItemTypes } from '../constants';
-import { convertSpaceItemsToModels } from '../utils/spacerUtils';
-import { validateJSON } from '../../api/utils/validation';
+/**
+ * Space domain model for the Datalayer SDK.
+ *
+ * @module models/SpaceDTO
+ */
+import * as users from '../api/spacer/users';
+import * as items from '../api/spacer/items';
+import * as notebooks from '../api/spacer/notebooks';
+import * as lexicals from '../api/spacer/lexicals';
+import { NotebookDTO } from './NotebookDTO';
+import { LexicalDTO } from './LexicalDTO';
+import { ItemTypes } from '../client/constants';
+import { convertSpaceItemsToModels } from '../client/utils/spacerUtils';
+import { validateJSON } from '../api/utils/validation';
 /**
  * Space domain model that wraps API responses with convenient methods.
  * Provides workspace management with data refresh and content creation operations.
@@ -22,7 +27,7 @@ import { validateJSON } from '../../api/utils/validation';
  * const notebook = await space.createNotebook({ name: 'Analysis' });
  * ```
  */
-export class Space {
+export class SpaceDTO {
     _data;
     _sdk;
     _items = null;
@@ -120,7 +125,7 @@ export class Space {
                 throw new Error('Failed to create notebook: No notebook returned');
             }
             else {
-                return new Notebook(response.notebook, this._sdk);
+                return new NotebookDTO(response.notebook, this._sdk);
             }
         }
         else if (data.type === ItemTypes.LEXICAL) {
@@ -136,7 +141,7 @@ export class Space {
                 throw new Error('Failed to create lexical document: No document returned');
             }
             else {
-                return new Lexical(response.document, this._sdk);
+                return new LexicalDTO(response.document, this._sdk);
             }
         }
         else {

package/lib/{client/models/User.d.ts → models/UserDTO.d.ts}

@@ -1,10 +1,31 @@
 /**
  * User model for the Datalayer SDK with rich functionality.
  *
- * @module client/models/User
+ * @module models/UserDTO
  */
-import type { User as UserData } from '../../api/types/iam';
 import type { DatalayerClient } from '../index';
+/**
+ * Represents a user in the Datalayer platform
+ * @interface UserData
+ */
+export interface UserData {
+    /** uuid for the user */
+    id: string;
+    /** ulid for the user */
+    uid: string;
+    /** User's handle or nickname */
+    handle_s: string;
+    /** User's email address */
+    email_s: string;
+    /** User's first name */
+    first_name_t: string;
+    /** User's last name */
+    last_name_t: string;
+    /** Display name shown in the UI */
+    avatar_url_s: string;
+    /** Additional fields that may be present in the response */
+    [key: string]: any;
+}
 export interface UserJSON {
     /** uuid for the user */
     id: string;
@@ -27,7 +48,7 @@ export interface UserJSON {
  * User model representing a Datalayer platform user.
  * Provides rich functionality for accessing user data and authentication providers.
  */
-export declare class User {
+export declare class UserDTO {
     protected _data: UserData;
     /**
      * Create a User instance.
@@ -62,3 +83,4 @@ export declare class User {
     /** String representation of the user. */
     toString(): string;
 }
+export default UserDTO;

package/lib/{client/models/User.js → models/UserDTO.js}

@@ -2,12 +2,12 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { validateJSON } from '../../api/utils/validation';
+import { validateJSON } from '../api/utils/validation';
 /**
  * User model representing a Datalayer platform user.
  * Provides rich functionality for accessing user data and authentication providers.
  */
-export class User {
+export class UserDTO {
     _data;
     /**
      * Create a User instance.
@@ -81,3 +81,4 @@ export class User {
         return `User(${this.uid}, ${this.displayName})`;
     }
 }
+export default UserDTO;

package/lib/models/index.d.ts

@@ -1,9 +1,40 @@
+/**
+ * Models definitions for all Datalayer API services.
+ *
+ * This module consolidates all type definitions used by the SDK, providing
+ * comprehensive TypeScript support for requests, responses, and data models
+ * across all Datalayer services.
+ *
+ * These types follow the exact backend API format (snake_case naming) to
+ * ensure compatibility. For frontend business logic types with camelCase
+ * naming, see the models in `/src/models/`.
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   Runtime,
+ *   Environment,
+ *   Space,
+ *   Notebook,
+ *   User,
+ *   LoginRequest
+ * } from '@datalayer/core/api/types';
+ *
+ * // Use types for function parameters and return values
+ * function createRuntime(config: CreateRuntimeRequest): Promise<Runtime> {
+ *   // Implementation
+ * }
+ * ```
+ *
+ * @module models
+ */
 export * from './AIAgent';
-export * from './Base';
 export * from './Assignment';
+export * from './Base';
 export * from './Cell';
 export * from './CodeBlock';
 export * from './CodefeedBlocks';
+export * from './Common';
 export * from './Contact';
 export * from './ContactEvent';
 export * from './ContactIAMProvider';
@@ -11,29 +42,35 @@ export * from './ContactTags';
 export * from './Content';
 export * from './Course';
 export * from './Credits';
-export * from './Datasource';
+export * from './CreditsDTO';
 export * from './Dataset';
+export * from './Datasource';
 export * from './Dean';
 export * from './Document';
 export * from './Environment';
+export * from './EnvironmentDTO';
 export * from './Errors';
 export * from './Exercise';
 export * from './GrowthKPI';
+export * from './IAM';
 export * from './IAMProviderLinked';
 export * from './IAMProviderPost';
-export * from './IAMProvidersSpecs';
 export * from './IAMProviderUsers';
-export * from './Instructor';
+export * from './IAMProvidersSpecs';
 export * from './IAMToken';
 export * from './Inbound';
+export * from './Instructor';
 export * from './Invite';
 export * from './Item';
+export * from './ItemDTO';
 export * from './ItemType';
 export * from './LandingRoles';
 export * from './Lesson';
+export * from './LexicalDTO';
 export * from './Library';
 export * from './Member';
 export * from './Notebook';
+export * from './NotebookDTO';
 export * from './Organization';
 export * from './OrganizationMember';
 export * from './Outbound';
@@ -45,10 +82,13 @@ export * from './RolesOrganization';
 export * from './RolesPlatform';
 export * from './RolesTeam';
 export * from './Runtime';
+export * from './RuntimeDTO';
 export * from './RuntimeSnapshot';
+export * from './RuntimeSnapshotDTO';
 export * from './School';
 export * from './Secret';
 export * from './Space';
+export * from './SpaceDTO';
 export * from './SpaceItem';
 export * from './SpaceMember';
 export * from './Student';
@@ -59,6 +99,7 @@ export * from './TeamMember';
 export * from './URN';
 export * from './Usage';
 export * from './User';
+export * from './UserDTO';
 export * from './UserEvent';
 export * from './UserOnboarding';
 export * from './UserSettings';

package/lib/models/index.js

@@ -2,12 +2,43 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/**
+ * Models definitions for all Datalayer API services.
+ *
+ * This module consolidates all type definitions used by the SDK, providing
+ * comprehensive TypeScript support for requests, responses, and data models
+ * across all Datalayer services.
+ *
+ * These types follow the exact backend API format (snake_case naming) to
+ * ensure compatibility. For frontend business logic types with camelCase
+ * naming, see the models in `/src/models/`.
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   Runtime,
+ *   Environment,
+ *   Space,
+ *   Notebook,
+ *   User,
+ *   LoginRequest
+ * } from '@datalayer/core/api/types';
+ *
+ * // Use types for function parameters and return values
+ * function createRuntime(config: CreateRuntimeRequest): Promise<Runtime> {
+ *   // Implementation
+ * }
+ * ```
+ *
+ * @module models
+ */
 export * from './AIAgent';
-export * from './Base';
 export * from './Assignment';
+export * from './Base';
 export * from './Cell';
 export * from './CodeBlock';
 export * from './CodefeedBlocks';
+export * from './Common';
 export * from './Contact';
 export * from './ContactEvent';
 export * from './ContactIAMProvider';
@@ -15,29 +46,35 @@ export * from './ContactTags';
 export * from './Content';
 export * from './Course';
 export * from './Credits';
-export * from './Datasource';
+export * from './CreditsDTO';
 export * from './Dataset';
+export * from './Datasource';
 export * from './Dean';
 export * from './Document';
 export * from './Environment';
+export * from './EnvironmentDTO';
 export * from './Errors';
 export * from './Exercise';
 export * from './GrowthKPI';
+export * from './IAM';
 export * from './IAMProviderLinked';
 export * from './IAMProviderPost';
-export * from './IAMProvidersSpecs';
 export * from './IAMProviderUsers';
-export * from './Instructor';
+export * from './IAMProvidersSpecs';
 export * from './IAMToken';
 export * from './Inbound';
+export * from './Instructor';
 export * from './Invite';
 export * from './Item';
+export * from './ItemDTO';
 export * from './ItemType';
 export * from './LandingRoles';
 export * from './Lesson';
+export * from './LexicalDTO';
 export * from './Library';
 export * from './Member';
 export * from './Notebook';
+export * from './NotebookDTO';
 export * from './Organization';
 export * from './OrganizationMember';
 export * from './Outbound';
@@ -49,10 +86,13 @@ export * from './RolesOrganization';
 export * from './RolesPlatform';
 export * from './RolesTeam';
 export * from './Runtime';
+export * from './RuntimeDTO';
 export * from './RuntimeSnapshot';
+export * from './RuntimeSnapshotDTO';
 export * from './School';
 export * from './Secret';
 export * from './Space';
+export * from './SpaceDTO';
 export * from './SpaceItem';
 export * from './SpaceMember';
 export * from './Student';
@@ -63,6 +103,7 @@ export * from './TeamMember';
 export * from './URN';
 export * from './Usage';
 export * from './User';
+export * from './UserDTO';
 export * from './UserEvent';
 export * from './UserOnboarding';
 export * from './UserSettings';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/core",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "type": "module",
   "workspaces": [
     ".",
@@ -103,6 +103,7 @@
     "@primer/react": "^37.19.0",
     "@primer/react-brand": "^0.58.0",
     "@stripe/react-stripe-js": "^2.7.1",
+    "@tanstack/react-query": "^5.90.6",
     "axios": "^1.7.7",
     "boring-avatars": "^2.0.1",
     "buffer": "^6.0.3",

package/lib/api/types/index.d.ts

@@ -1,34 +0,0 @@
-/**
- * TypeScript type definitions for all Datalayer API services.
- *
- * This module consolidates all type definitions used by the SDK, providing
- * comprehensive TypeScript support for requests, responses, and data models
- * across all Datalayer services.
- *
- * These types follow the exact backend API format (snake_case naming) to
- * ensure compatibility. For frontend business logic types with camelCase
- * naming, see the models in `/src/models/`.
- *
- * @example
- * ```typescript
- * import type {
- *   Runtime,
- *   Environment,
- *   Space,
- *   Notebook,
- *   User,
- *   LoginRequest
- * } from '@datalayer/core/api/types';
- *
- * // Use types for function parameters and return values
- * function createRuntime(config: CreateRuntimeRequest): Promise<Runtime> {
- *   // Implementation
- * }
- * ```
- *
- * @module types
- */
-export * from './common';
-export * from './runtimes';
-export * from './iam';
-export * from './spacer';