@datalayer/core 0.0.2 → 0.0.4

package/README.md

@@ -37,26 +37,44 @@ This package serves as the base foundation used by many other Datalayer packages
 - **📸 Snapshot Management**: Create and manage compute snapshots of your runtimes for reproducible environments
 - **🔒 Secrets Management**: Securely handle sensitive data and credentials in your workflows
 - **🐍 Python SDK**: Programmatic access to Datalayer platform with context managers and clean resource management
+- **🌐 TypeScript/React SDK**: React components and services for building Jupyter-based applications
 - **💻 Command Line Interface**: CLI tools for managing runtimes, snapshots, and platform resources
 - **🔧 Base Classes**: Core application classes and configuration inherited by other Datalayer projects
+- **📓 Jupyter Integration**: ServiceManager and collaboration providers for notebook experiences
+- **🧭 Universal Navigation**: Smart navigation hooks that auto-detect and work with React Router, Next.js, or native browser
 
 ## Installation
 
+### Python SDK
+
 Install Datalayer Core using pip:
 
 ```bash
 pip install datalayer-core
 ```
 
-For development installation:
+### TypeScript/React SDK
+
+Install as an npm package:
+
+```bash
+npm install @datalayer/core
+```
+
+### Development Installation
 
 ```bash
 git clone https://github.com/datalayer/core.git
 cd core
+
+# Python development
 pip install -e .[test]
+
+# TypeScript development
+npm install
 ```
 
-## Quick Start
+## Quick Start with Python
 
 ### 1. Authentication
 
@@ -114,6 +132,60 @@ datalayer runtime exec my-script.py --runtime <runtime-id>
 datalayer snapshots create <pod-name> my-snapshot 'AI work!' False
 ```
 
+## Examples
+
+### Python Examples
+
+For comprehensive Python usage examples, see the [`examples/`](https://github.com/datalayer/core/tree/main/examples) directory which includes:
+
+- **FastAPI + scikit-learn**: Web application with ML models
+- **Streamlit + scikit-learn**: Interactive data science apps
+- **PyTorch GPU workloads**: High-performance computing examples
+- **Decorator patterns**: Remote function execution with `@datalayer`
+- **And more**: Complete examples with documentation and setup instructions
+
+### TypeScript/React Examples
+
+Run the interactive examples locally:
+
+```bash
+# Install dependencies
+npm install
+
+# Set your Datalayer API token in .env
+echo "VITE_DATALAYER_API_TOKEN=your-token-here" > .env
+
+# Start the examples server
+npm run example
+```
+
+Available at http://localhost:3000/:
+
+- **DatalayerNotebookExample**: Full integration with Datalayer services and collaboration
+- **NotebookExample**: Basic Jupyter notebook in React
+- **CellExample**: Individual code cell execution
+- **ReactRouterAdvancedExample**: Comprehensive navigation demo with React Router integration
+- **ReactRouterNavigationExample**: Basic navigation with route parameters
+- **NativeNavigationExample**: Browser-native navigation fallback
+
+### Next.js Application Example
+
+A complete Next.js application demonstrating platform integration:
+
+```bash
+cd examples/nextjs-notebook
+npm install
+npm run dev
+```
+
+Features:
+
+- Token authentication with Datalayer IAM
+- Browse and create notebooks from your workspace
+- Select compute environments for execution
+- Interactive notebook viewer with real-time outputs
+- Clean, responsive UI with GitHub Primer components
+
 ## Platform Integration
 
 Datalayer adds AI capabilities and scalable compute runtimes to your development workflows. The platform is designed to seamlessly integrate into your existing processes and supercharge your computations with the processing power you need.
@@ -133,11 +205,61 @@ Key platform features accessible through this SDK and CLI:
 
 ## Development
 
+### Building the Library
+
+```bash
+# Build TypeScript library
+npm run build:lib
+
+# Build Python package
+python -m build
+```
+
+### Setup
+
+```bash
+# Install Python dependencies
+pip install -e .[test]
+
+# Install TypeScript dependencies
+npm install
+```
+
+### Code Quality
+
+This project maintains high code quality standards with automated linting, formatting, and type checking:
+
+```bash
+# Run all checks (format, lint, type-check)
+npm run check
+
+# Auto-fix all issues
+npm run check:fix
+
+# Individual commands
+npm run lint          # ESLint with React/TypeScript rules
+npm run lint:fix      # Auto-fix linting issues
+npm run format        # Prettier formatting
+npm run format:check  # Check formatting without changes
+npm run type-check    # TypeScript compilation check
+```
+
+Pre-commit hooks automatically run formatting and linting on staged files via Husky and lint-staged.
+
 ### Running Tests
 
 ```bash
+# Python tests
 pip install -e .[test]
 pytest datalayer_core/tests/
+
+# TypeScript tests
+npm run test
+
+# TypeScript type checking
+npm run type-check
+npm run test:watch    # Watch mode
+npm run test:coverage # With coverage
 ```
 
 ### Contributing

package/lib/App.css

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  /*  text-align: center; */
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

package/lib/App.js

@@ -3,12 +3,24 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
 import { useState } from 'react';
 import reactLogo from './assets/react.svg';
-import viteLogo from '/vite.svg';
+import { useJupyter, JupyterReactTheme } from '@datalayer/jupyter-react';
+import { CellExample } from './examples/CellExample';
+import { NotebookExample } from './examples/NotebookExample';
 import './App.css';
 export function App() {
+    const { serviceManager } = useJupyter({
+        jupyterServerUrl: 'https://oss.datalayer.run/api/jupyter-server',
+        jupyterServerToken: '60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6',
+        startDefaultKernel: true,
+    });
     const [count, setCount] = useState(0);
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { children: [_jsx("a", { href: "https://vite.dev", target: "_blank", children: _jsx("img", { src: viteLogo, className: "logo", alt: "Vite logo" }) }), _jsx("a", { href: "https://react.dev", target: "_blank", children: _jsx("img", { src: reactLogo, className: "logo react", alt: "React logo" }) })] }), _jsx("h1", { children: "Vite + React" }), _jsxs("div", { className: "card", children: [_jsxs("button", { onClick: () => setCount((count) => count + 1), children: ["count is ", count] }), _jsxs("p", { children: ["Edit ", _jsx("code", { children: "src/App.tsx" }), " and save to test HMR"] })] }), _jsx("p", { className: "read-the-docs", children: "Click on the Vite and React logos to learn more" })] }));
+    return (_jsxs("div", { className: "App", children: [_jsx(_Fragment, { children: _jsxs(JupyterReactTheme, { children: [serviceManager && _jsx(CellExample, { serviceManager: serviceManager }), serviceManager && (_jsx(NotebookExample, { serviceManager: serviceManager }))] }) }), _jsxs("div", { children: [_jsx("a", { href: "https://reactjs.org", target: "_blank", rel: "noreferrer", children: _jsx("img", { src: reactLogo, className: "logo react", alt: "React logo" }) }), _jsx("a", { href: "https://vitejs.dev", target: "_blank", rel: "noreferrer", children: _jsx("img", { src: "/vite.svg", className: "logo", alt: "Vite logo" }) })] }), _jsx("h1", { children: "React + Vite" }), _jsx("h2", { children: "On CodeSandbox!" }), _jsxs("div", { className: "card", children: [_jsxs("button", { onClick: () => setCount(count => count + 1), children: ["count is ", count] }), _jsxs("p", { children: ["Edit ", _jsx("code", { children: "src/App.tsx" }), " and save to test HMR."] }), _jsx("p", { children: "Tip: you can use the inspector button next to address bar to click on components in the preview and open the code in the editor!" })] }), _jsx("p", { className: "read-the-docs", children: "Click on the Vite and React logos to learn more" })] }));
 }
 export default App;

package/lib/__tests__/index.test.js

@@ -5,22 +5,23 @@
 import { describe, it, expect } from 'vitest';
 import * as coreIndex from '../index';
 describe('@datalayer/core - index', () => {
-    it('should export App', () => {
-        expect(coreIndex.App).toBeDefined();
-        expect(typeof coreIndex.App).toBe('function');
-    });
     it('should export BackdropContext from hooks', () => {
         expect(coreIndex.BackdropContext).toBeDefined();
-        expect(coreIndex.BackdropContext).toBe('lkj');
+        expect(coreIndex.BackdropContext).toHaveProperty('$$typeof');
+        expect(typeof coreIndex.BackdropContext).toBe('object');
     });
     it('should export utils functions', () => {
         expect(coreIndex.convertToLargestUnit).toBeDefined();
         expect(coreIndex.asArray).toBeDefined();
     });
+    it('should export DatalayerServiceManager from services', () => {
+        expect(coreIndex.createDatalayerServiceManager).toBeDefined();
+        expect(typeof coreIndex.createDatalayerServiceManager).toBe('function');
+    });
     it('should have all expected exports', () => {
         const exports = Object.keys(coreIndex);
-        expect(exports).toContain('App');
         expect(exports).toContain('convertToLargestUnit');
         expect(exports).toContain('asArray');
+        expect(exports).toContain('createDatalayerServiceManager');
     });
 });

package/lib/api/{RunApi.d.ts → DatalayerApi.d.ts}

@@ -3,8 +3,8 @@
  */
 export declare class RunResponseError extends Error {
     /**
-     * Create a RunResponseError from a response, handling the traceback and message
-     * as appropriate.
+     * Create a RunResponseError from a response,
+     * handling the traceback and message as appropriate.
      *
      * @param response The response object.
      *
@@ -46,7 +46,7 @@ export declare class NetworkError extends TypeError {
      */
     constructor(original: TypeError);
 }
-export interface IRequestRunAPIOptions {
+export interface IRequestDatalayerAPIOptions {
     /**
      * URL to request
      */
@@ -72,4 +72,4 @@ export interface IRequestRunAPIOptions {
      */
     signal?: AbortSignal;
 }
-export declare function requestRunAPI<T = any>({ url, method, body, token, signal, headers }: IRequestRunAPIOptions): Promise<T>;
+export declare function requestDatalayerAPI<T = any>({ url, method, body, token, signal, headers, }: IRequestDatalayerAPIOptions): Promise<T>;

package/lib/api/{RunApi.js → DatalayerApi.js}

@@ -2,11 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 import { URLExt } from '@jupyterlab/coreutils';
 import { sleep } from '../utils';
 /**
@@ -14,8 +9,8 @@ import { sleep } from '../utils';
  */
 export class RunResponseError extends Error {
     /**
-     * Create a RunResponseError from a response, handling the traceback and message
-     * as appropriate.
+     * Create a RunResponseError from a response,
+     * handling the traceback and message as appropriate.
      *
      * @param response The response object.
      *
@@ -85,7 +80,7 @@ export class NetworkError extends TypeError {
         this.stack = original.stack;
     }
 }
-export async function requestRunAPI({ url, method, body, token, signal, headers = {} }) {
+export async function requestDatalayerAPI({ url, method, body, token, signal, headers = {}, }) {
     const headers_ = new Headers(headers);
     if (!headers_.has('Accept')) {
         headers_.set('Accept', 'application/json');
@@ -103,11 +98,11 @@ export async function requestRunAPI({ url, method, body, token, signal, headers
             method: method ?? 'GET',
             headers: headers_,
             body: body ? JSON.stringify(body) : undefined,
-            //      credentials: token ? 'include' : 'omit',
+            // credentials: token ? 'include' : 'omit',
             credentials: 'include',
             mode: 'cors',
             cache: 'no-store',
-            signal
+            signal,
         });
     }
     catch (error) {
@@ -140,7 +135,7 @@ async function wait_for_redirection(response, url, headers_) {
             headers: headers_,
             credentials: 'include',
             mode: 'cors',
-            cache: 'no-store'
+            cache: 'no-store',
         });
         if (!response.ok) {
             throw await RunResponseError.create(response);

package/lib/api/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./runtimes";
-export * from "./RunApi";
+export * from './jupyter';
+export * from './runtimes';
+export * from './DatalayerApi';

package/lib/api/index.js

@@ -2,10 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
-export * from "./runtimes";
-export * from "./RunApi";
+export * from './jupyter';
+export * from './runtimes';
+export * from './DatalayerApi';

package/lib/api/{runtimes → jupyter}/exec/Python.js

@@ -2,11 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 export function listVariables() {
     return `
 def _list_variables():

package/lib/api/{runtimes → jupyter}/exec/Snippets.js

@@ -2,11 +2,6 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 import * as Python from './Python';
 /**
  * Facade to interact with kernels by requesting code execution.

package/lib/api/{runtimes → jupyter}/exec/index.js

@@ -2,10 +2,5 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 export * from './Python';
 export * from './Snippets';

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

@@ -0,0 +1,2 @@
+export * from './exec';
+export * from './kernelsHandler';

package/lib/api/jupyter/index.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './exec';
+export * from './kernelsHandler';

package/lib/api/{runtimes → jupyter}/kernelsHandler.d.ts

@@ -1,5 +1,5 @@
 /**
- * Call the Runtimes extension
+ * Call the jupyter_kernels extension
  *
  * @param endPoint API REST end point for the extension
  * @param init Initial values for the request

package/lib/api/{runtimes → jupyter}/kernelsHandler.js

@@ -2,15 +2,10 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2024 Datalayer, Inc.
- *
- * Datalayer License
- */
 import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 /**
- * Call the Runtimes extension
+ * Call the jupyter_kernels extension
  *
  * @param endPoint API REST end point for the extension
  * @param init Initial values for the request

package/lib/api/runtimes/actions.d.ts

@@ -0,0 +1,102 @@
+import { IRuntimeOptions } from '..';
+import type { IRuntimeSnapshot, IDatalayerEnvironment, IRuntimePod } from '../../models';
+/**
+ * Get available Environments.
+ */
+export declare function getEnvironments(): Promise<IDatalayerEnvironment[]>;
+/**
+ * Create a Runtime.
+ */
+export declare function createRuntime(options: IRuntimeOptions): Promise<IRuntimePod>;
+/**
+ * Get the Runtimes.
+ */
+export declare function getRuntimes(): Promise<IRuntimePod[]>;
+/**
+ * Delete a Runtime
+ */
+export declare function deleteRuntime(options: {
+    /**
+     * Runtime ID
+     */
+    id: string;
+    /**
+     * Deletion reason
+     */
+    reason?: string;
+}): Promise<void>;
+/**
+ * Snapshot a Runtime.
+ */
+export declare function snapshotRuntime(options: {
+    /**
+     * Runtime ID.
+     */
+    id: string;
+    /**
+     * Snapshot name.
+     */
+    name?: string;
+    /**
+     * Snapshot description.
+     */
+    description?: string;
+    /**
+     * Whether to stop the kernel after the snapshot completion or not.
+     */
+    stop?: boolean;
+}): Promise<IRuntimeSnapshot>;
+/**
+ * Get Runtime Snapshots.
+ */
+export declare function getRuntimeSnapshots(): Promise<IRuntimeSnapshot[]>;
+/**
+ * Load a Runtime Snapshot within a kernel.
+ */
+export declare function loadRuntimeSnapshot(options: {
+    /**
+     * Runtime ID
+     */
+    id: string;
+    /**
+     * Snapshot UID
+     */
+    from: string;
+}): Promise<void>;
+/**
+ * Returns the Runtime Snapshot download URL.
+ *
+ * @param id Snapshot UID to download
+ * @returns The download URL
+ */
+export declare function createRuntimeSnapshotDownloadURL(id: string): string;
+/**
+ * Export a Runtime Snapshot.
+ *
+ * @param id Runtime snapshot UID to download
+ */
+export declare function exportRuntimeSnapshot(id: string): void;
+/**
+ * Delete a Runtime Snapshot.
+ */
+export declare function deleteRuntimeSnapshot(id: string): Promise<void>;
+/**
+ * Update Runtime Snapshot metadata.
+ */
+export declare function updateRuntimeSnapshot(id: string, metadata: {
+    name?: string;
+    description?: string;
+}): Promise<void>;
+/**
+ * Upload a Runtime Snapshot.
+ *
+ * Note: The promise will be rejected if the runtime state is empty.
+ */
+export declare function uploadRuntimeSnapshot(options: {
+    file: File | Blob;
+    metadata: {
+        filename: string;
+        [key: string]: string;
+    };
+    onProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+}): Promise<void>;