@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/api/runtimes/runtimes.js

@@ -0,0 +1,230 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Runtime instances API functions for the Datalayer platform.
+ *
+ * Provides functions for managing runtime instances (active compute containers).
+ *
+ * @module api/runtimes/runtimes
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken, validateRequiredString, } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Create a new runtime instance.
+ * @param token - Authentication token
+ * @param data - Runtime creation configuration
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the created runtime details
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} With status 404 if the environment is not found
+ * @throws {Error} With status 503 if no runtime is available
+ */
+export const createRuntime = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    try {
+        return await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes`,
+            method: 'POST',
+            body: data,
+            token,
+        });
+    }
+    catch (error) {
+        // Handle specific error cases
+        if (error.response) {
+            const status = error.response.status;
+            const responseData = error.response.data || {};
+            if (status === 404) {
+                // Environment not found
+                throw new Error(`Environment '${data.environment_name}' not found. ${responseData.message || 'Please check the environment name and try again.'}`);
+            }
+            else if (status === 503) {
+                // No runtime available
+                throw new Error(`No runtime available. ${responseData.message || 'The service is temporarily unavailable or at capacity. Please try again later.'}`);
+            }
+        }
+        // Re-throw the original error for other cases
+        throw error;
+    }
+};
+/**
+ * List all runtime instances.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to list of runtime instances
+ * @throws {Error} If authentication token is missing or invalid
+ */
+export const listRuntimes = async (token, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    const response = await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes`,
+        method: 'GET',
+        token,
+    });
+    // The API returns { success: true, message: string, runtimes: Runtime[] }
+    // The response already has the correct structure, just return it
+    return response;
+};
+/**
+ * Get details for a specific runtime instance.
+ * @param token - Authentication token
+ * @param podName - The unique pod name of the runtime
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to runtime details
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} With status 404 if the runtime is not found
+ */
+export const getRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(podName, 'Pod name');
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${podName}`,
+            method: 'GET',
+            token,
+        });
+        // The API returns { success: true, message: string, runtime: Runtime }
+        // (Previously used 'kernel' field, now uses 'runtime')
+        // Try 'runtime' field first (current API)
+        if (response.runtime) {
+            return {
+                ...response.runtime,
+                pod_name: response.runtime.pod_name || podName,
+            };
+        }
+        // Fallback to 'kernel' field (old API)
+        if (response.kernel) {
+            return {
+                ...response.kernel,
+                pod_name: response.kernel.pod_name || podName,
+            };
+        }
+        // Fallback if response structure is different
+        return response;
+    }
+    catch (error) {
+        // Handle specific error cases
+        if (error.response && error.response.status === 404) {
+            // Runtime not found
+            throw new Error(`Runtime with pod name '${podName}' not found. Please check the pod name and try again.`);
+        }
+        // Re-throw the original error for other cases
+        throw error;
+    }
+};
+/**
+ * Delete a runtime instance.
+ * @param token - Authentication token
+ * @param podName - The unique pod name of the runtime to delete
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving when deletion is complete
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} With status 404 if the runtime is not found
+ */
+export const deleteRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(podName, 'Pod name');
+    try {
+        return await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${podName}`,
+            method: 'DELETE',
+            token,
+        });
+    }
+    catch (error) {
+        // Handle specific error cases
+        if (error.response && error.response.status === 404) {
+            // Runtime not found
+            throw new Error(`Runtime with pod name '${podName}' not found. Cannot delete a non-existent runtime.`);
+        }
+        // Re-throw the original error for other cases
+        throw error;
+    }
+};
+/**
+ * Update a runtime instance.
+ * @param token - Authentication token
+ * @param podName - The unique pod name of the runtime
+ * @param from - The source to update from
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to updated runtime details
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} With status 404 if the runtime is not found
+ */
+export const updateRuntime = async (token, podName, from, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(podName, 'Pod name');
+    try {
+        return await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${podName}`,
+            method: 'PUT',
+            token,
+            body: { from },
+        });
+    }
+    catch (error) {
+        // Handle specific error cases
+        if (error.response && error.response.status === 404) {
+            // Runtime not found
+            throw new Error(`Runtime with pod name '${podName}' not found. Cannot update a non-existent runtime.`);
+        }
+        // Re-throw the original error for other cases
+        throw error;
+    }
+};
+/**
+ * Pause a runtime by creating a checkpoint (async, light mode by default).
+ *
+ * Returns immediately with a 202 Accepted response.  The actual checkpoint
+ * process runs in the background.  Use the returned `checkpoint_id` to
+ * poll for status via the runtime-checkpoints API.
+ *
+ * @param token - Authentication token
+ * @param podName - The unique pod name of the runtime to pause
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @param body - Optional metadata to store in the checkpoint record
+ * @returns Promise resolving with the checkpoint ID for status tracking
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If pod name is missing or invalid
+ */
+export const pauseRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, body) => {
+    validateToken(token);
+    validateRequiredString(podName, 'Pod name');
+    return await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${encodeURIComponent(podName)}/pause`,
+        method: 'POST',
+        token,
+        ...(body ? { body } : {}),
+    });
+};
+/**
+ * Resume a paused runtime by restoring from a checkpoint (async).
+ *
+ * Returns immediately with a 202 Accepted response.  The actual restore
+ * process runs in the background.  Use the returned `checkpoint_id` to
+ * poll for status.
+ *
+ * @param token - Authentication token
+ * @param podName - The unique pod name of the runtime to resume
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @param body - Optional body with agent_spec_id and restore options
+ * @returns Promise resolving with the checkpoint ID for status tracking
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If pod name is missing or invalid
+ */
+export const resumeRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, body) => {
+    validateToken(token);
+    validateRequiredString(podName, 'Pod name');
+    return await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${encodeURIComponent(podName)}/resume`,
+        method: 'POST',
+        token,
+        ...(body ? { body } : {}),
+    });
+};

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

@@ -0,0 +1,38 @@
+import { CreateCodeSandboxSnapshotRequest, ListCodeSandboxSnapshotsResponse, GetCodeSandboxSnapshotResponse, CreateCodeSandboxSnapshotResponse } from '../../models/CodeSandboxSnapshotDTO';
+/**
+ * Create a snapshot of a runtime instance.
+ * @param token - Authentication token
+ * @param data - Snapshot creation configuration
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the created snapshot response
+ * @throws {Error} If authentication token is missing or invalid
+ */
+export declare const createSnapshot: (token: string, data: CreateCodeSandboxSnapshotRequest, baseUrl?: string) => Promise<CreateCodeSandboxSnapshotResponse>;
+/**
+ * List all code sandbox snapshots.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to list of snapshots
+ * @throws {Error} If authentication token is missing or invalid
+ */
+export declare const listSnapshots: (token: string, baseUrl?: string) => Promise<ListCodeSandboxSnapshotsResponse>;
+/**
+ * Get details for a specific code sandbox snapshot.
+ * @param token - Authentication token
+ * @param snapshotId - The unique identifier of the snapshot
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to snapshot details wrapped in response
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If snapshot ID is missing or invalid
+ */
+export declare const getSnapshot: (token: string, snapshotId: string, baseUrl?: string) => Promise<GetCodeSandboxSnapshotResponse>;
+/**
+ * Delete a code sandbox snapshot.
+ * @param token - Authentication token
+ * @param snapshotId - The unique identifier of the snapshot to delete
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving when deletion is complete
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If snapshot ID is missing or invalid
+ */
+export declare const deleteSnapshot: (token: string, snapshotId: string, baseUrl?: string) => Promise<void>;

package/lib/api/runtimes/snapshots.js

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Code Sandbox snapshots API functions for the Datalayer platform.
+ *
+ * Provides functions for managing code sandbox snapshots (saved runtime states).
+ *
+ * @module api/runtimes/snapshots
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken, validateRequiredString, } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Create a snapshot of a runtime instance.
+ * @param token - Authentication token
+ * @param data - Snapshot creation configuration
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the created snapshot response
+ * @throws {Error} If authentication token is missing or invalid
+ */
+export const createSnapshot = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/sandbox-snapshots`,
+        method: 'POST',
+        token,
+        body: data,
+    });
+};
+/**
+ * List all code sandbox snapshots.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to list of snapshots
+ * @throws {Error} If authentication token is missing or invalid
+ */
+export const listSnapshots = async (token, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/sandbox-snapshots`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get details for a specific code sandbox snapshot.
+ * @param token - Authentication token
+ * @param snapshotId - The unique identifier of the snapshot
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to snapshot details wrapped in response
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If snapshot ID is missing or invalid
+ */
+export const getSnapshot = async (token, snapshotId, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(snapshotId, 'Snapshot ID');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/sandbox-snapshots/${snapshotId}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Delete a code sandbox snapshot.
+ * @param token - Authentication token
+ * @param snapshotId - The unique identifier of the snapshot to delete
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving when deletion is complete
+ * @throws {Error} If authentication token is missing or invalid
+ * @throws {Error} If snapshot ID is missing or invalid
+ */
+export const deleteSnapshot = async (token, snapshotId, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(snapshotId, 'Snapshot ID');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/sandbox-snapshots/${snapshotId}`,
+        method: 'DELETE',
+        token,
+    });
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Scheduler API module for the Datalayer platform.
+ *
+ * @module api/scheduler
+ */
+export * from './schedules';

package/lib/api/scheduler/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Scheduler API module for the Datalayer platform.
+ *
+ * @module api/scheduler
+ */
+export * from './schedules';

package/lib/api/scheduler/schedules.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Raw schedule document as returned by the scheduler service.
+ *
+ * Fields follow the Solr suffix convention (`_s`, `_b`, `_dt`, `_i`).
+ */
+export interface ScheduleDoc {
+    uid?: string;
+    type_s?: string;
+    notebook_uid_s?: string;
+    owner_uid_s?: string;
+    cron_expression_s?: string;
+    preset_s?: string;
+    enabled_b?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Request payload to create or update a notebook schedule.
+ */
+export interface UpsertScheduleRequest {
+    /** Target notebook uid. */
+    notebookUid: string;
+    /** Cron expression (e.g. `* * * * *`). */
+    cronExpression: string;
+    /** Optional preset identifier (e.g. `every-minute`, `hourly`, `daily`, `custom`). */
+    preset?: string;
+    /** Whether the schedule is enabled. Defaults to `true`. */
+    enabled?: boolean;
+}
+/**
+ * Request payload to update an existing schedule by uid.
+ */
+export interface UpdateScheduleRequest {
+    cronExpression?: string;
+    preset?: string;
+    enabled?: boolean;
+}
+/**
+ * Response shape for listing schedules.
+ */
+export interface ListSchedulesResponse {
+    success: boolean;
+    message: string;
+    schedules: ScheduleDoc[];
+}
+/**
+ * Response shape for a single schedule mutation.
+ */
+export interface ScheduleResponse {
+    success: boolean;
+    message: string;
+    schedule: ScheduleDoc;
+}
+/**
+ * List the schedules owned by the authenticated user.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @param includeDisabled - Include disabled schedules in the result
+ * @returns Promise resolving to the list of schedules
+ */
+export declare const listSchedules: (token: string, baseUrl?: string, includeDisabled?: boolean) => Promise<ListSchedulesResponse>;
+/**
+ * Create or update the schedule for a notebook.
+ * @param token - Authentication token
+ * @param data - Schedule configuration
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @returns Promise resolving to the upserted schedule
+ */
+export declare const upsertSchedule: (token: string, data: UpsertScheduleRequest, baseUrl?: string) => Promise<ScheduleResponse>;
+/**
+ * Update an existing schedule by uid.
+ * @param token - Authentication token
+ * @param scheduleUid - The schedule uid
+ * @param data - Fields to update
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @returns Promise resolving to the updated schedule
+ */
+export declare const updateSchedule: (token: string, scheduleUid: string, data: UpdateScheduleRequest, baseUrl?: string) => Promise<ScheduleResponse>;
+/**
+ * Disable a schedule by uid.
+ * @param token - Authentication token
+ * @param scheduleUid - The schedule uid
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @returns Promise resolving to the disabled schedule
+ */
+export declare const disableSchedule: (token: string, scheduleUid: string, baseUrl?: string) => Promise<ScheduleResponse>;

package/lib/api/scheduler/schedules.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Scheduler schedules API functions for the Datalayer platform.
+ *
+ * Provides functions for listing, creating, and updating cron schedules that
+ * trigger automated notebook executions.
+ *
+ * @module api/scheduler/schedules
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+/**
+ * List the schedules owned by the authenticated user.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @param includeDisabled - Include disabled schedules in the result
+ * @returns Promise resolving to the list of schedules
+ */
+export const listSchedules = async (token, baseUrl = DEFAULT_SERVICE_URLS.SCHEDULER, includeDisabled = false) => {
+    const query = includeDisabled ? '?includeDisabled=true' : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.SCHEDULER}/schedules${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Create or update the schedule for a notebook.
+ * @param token - Authentication token
+ * @param data - Schedule configuration
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @returns Promise resolving to the upserted schedule
+ */
+export const upsertSchedule = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.SCHEDULER) => {
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.SCHEDULER}/schedules`,
+        method: 'POST',
+        token,
+        body: {
+            enabled: true,
+            preset: 'custom',
+            ...data,
+        },
+    });
+};
+/**
+ * Update an existing schedule by uid.
+ * @param token - Authentication token
+ * @param scheduleUid - The schedule uid
+ * @param data - Fields to update
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @returns Promise resolving to the updated schedule
+ */
+export const updateSchedule = async (token, scheduleUid, data, baseUrl = DEFAULT_SERVICE_URLS.SCHEDULER) => {
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.SCHEDULER}/schedules/${scheduleUid}`,
+        method: 'PUT',
+        token,
+        body: data,
+    });
+};
+/**
+ * Disable a schedule by uid.
+ * @param token - Authentication token
+ * @param scheduleUid - The schedule uid
+ * @param baseUrl - Base URL for the scheduler service (defaults to production)
+ * @returns Promise resolving to the disabled schedule
+ */
+export const disableSchedule = async (token, scheduleUid, baseUrl = DEFAULT_SERVICE_URLS.SCHEDULER) => {
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.SCHEDULER}/schedules/${scheduleUid}/disable`,
+        method: 'POST',
+        token,
+    });
+};

package/lib/api/spacer/documents.d.ts

@@ -0,0 +1,12 @@
+import { CollaborationSessionResponse } from '../../models/SpaceDTO';
+/**
+ * Get collaboration session ID for a document.
+ *
+ * This function attempts to retrieve the collaboration session ID from the document API.
+ *
+ * @param token - Authentication token
+ * @param documentId - Document UID
+ * @param baseUrl - Base URL for the API (defaults to production)
+ * @returns Promise resolving to collaboration session response
+ */
+export declare const getCollaborationSessionId: (token: string, documentId: string, baseUrl?: string) => Promise<CollaborationSessionResponse>;

package/lib/api/spacer/documents.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Documents API functions for the Datalayer platform.
+ *
+ * Provides functions for document operations including collaboration session management.
+ *
+ * @module api/spacer/documents
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+/**
+ * Get collaboration session ID for a document.
+ *
+ * This function attempts to retrieve the collaboration session ID from the document API.
+ *
+ * @param token - Authentication token
+ * @param documentId - Document UID
+ * @param baseUrl - Base URL for the API (defaults to production)
+ * @returns Promise resolving to collaboration session response
+ */
+export const getCollaborationSessionId = async (token, documentId, baseUrl = DEFAULT_SERVICE_URLS.SPACER) => {
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.SPACER}/documents/${documentId}`,
+            method: 'GET',
+            token,
+        });
+        return {
+            success: true,
+            sessionId: response.sessionId || documentId, // FIXME: is this ok?
+        };
+    }
+    catch (error) {
+        // FIXME: is this ok?
+        return {
+            success: true,
+            sessionId: documentId,
+        };
+    }
+};

package/lib/api/spacer/healthz.d.ts

@@ -0,0 +1,15 @@
+import type { HealthzPingResponse } from '@datalayer/core/lib/models/Common';
+/**
+ * Health check ping endpoint for Spacer service
+ * @param baseUrl - Base URL for the API (defaults to production Spacer URL)
+ * @returns Health check response
+ * @throws {Error} If the health check fails
+ *
+ * @remarks
+ * This endpoint provides a basic health check for the Spacer service.
+ * It returns the current status of the service.
+ *
+ * Expected status codes:
+ * - 200: Service is healthy
+ */
+export declare const ping: (baseUrl?: string) => Promise<HealthzPingResponse>;

package/lib/api/spacer/healthz.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Health check API functions for the Datalayer Spacer service.
+ *
+ * Provides functions for checking the health status of the Spacer service.
+ *
+ * @module api/spacer/healthz
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+/**
+ * Health check ping endpoint for Spacer service
+ * @param baseUrl - Base URL for the API (defaults to production Spacer URL)
+ * @returns Health check response
+ * @throws {Error} If the health check fails
+ *
+ * @remarks
+ * This endpoint provides a basic health check for the Spacer service.
+ * It returns the current status of the service.
+ *
+ * Expected status codes:
+ * - 200: Service is healthy
+ */
+export const ping = async (baseUrl = DEFAULT_SERVICE_URLS.SPACER) => {
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.SPACER}/ping`,
+            method: 'GET',
+        });
+        return response;
+    }
+    catch (error) {
+        // Check if it's a response error with status code information
+        if (error.response) {
+            const status = error.response.status;
+            throw new Error(`Health check failed: Service unhealthy (status ${status}) - ${error.message}`);
+        }
+        // Re-throw other errors (network errors, etc.)
+        throw new Error(`Health check failed: ${error.message}`);
+    }
+};

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

@@ -0,0 +1,15 @@
+/**
+ * Spacer API exports.
+ *
+ * Provides organized access to spacer functionality including
+ * spaces, notebooks, cells, lexical documents, and agent runtimes.
+ *
+ * @module api/spacer
+ */
+export * as documents from './documents';
+export * as healthz from './healthz';
+export * as items from './items';
+export * as lexicals from './lexicals';
+export * as notebooks from './notebooks';
+export * as spaces from './spaces';
+export * as users from './users';