@datalayer/core 1.1.60 → 1.2.10

package/README.md

@@ -18,7 +18,7 @@
 
 ## Overview
 
-Datalayer Core is the foundational package that powers the [Datalayer AI Platform](https://datalayer.ai). It provides a TypesScript and Python packages as a Command Line Interface (CLI) for AI engineers, data scientists, and researchers to seamlessly integrate scalable compute runtimes into their workflows.
+Datalayer Core is the foundational package that powers the [Datalayer AI Platform](https://datalayer.app/). It provides a TypesScript and Python packages as a Command Line Interface (CLI) for AI engineers, data scientists, and researchers to seamlessly integrate scalable compute runtimes into their workflows.
 
 This package serves as the base foundation used by many other Datalayer packages, containing core application classes, configuration, and unified APIs for authentication, runtime management, and code execution in cloud-based environments.
 
@@ -66,6 +66,8 @@ npm install
 
 ## Quick Start with Python
 
+### 1. Authentication
+
 Set your Datalayer token as an environment variable:
 
 ```bash
@@ -87,19 +89,31 @@ if client.authenticate():
     print("Successfully authenticated!")
 ```
 
-## Architecture
+### 2. Runtime, Snapshots, and Evals
 
-Datalayer Core serves as the foundation for the entire Datalayer ecosystem:
+Runtime execution, snapshot workflows, and evals CLI are now documented and maintained in:
 
-- **Base Classes**: Core application classes inherited by other Datalayer packages
-- **Configuration Management**: Centralized configuration system for all Datalayer components
-- **Authentication Layer**: Unified authentication across all Datalayer services
-- **Runtime Abstraction**: Common interface for different types of compute runtimes
-- **Resource Management**: Automatic cleanup and lifecycle management
+- [agent-runtimes README](https://github.com/datalayer/agent-runtimes/blob/main/README.md)
+- [agent-runtimes CLI docs](https://agent-runtimes.datalayer.tech/cli)
+
+Use `agent-runtimes` for runtime workloads (`RuntimeClient`, `@datalayer`, snapshots, and evals), and use `datalayer-core` for account/platform operations (authentication, secrets, API keys, usage, profile).
 
 ## Examples
 
-- [OTEL example README](./examples/otel/README.md)
+Examples have moved to Agent Runtimes:
+
+- [Agent Runtimes examples README](https://github.com/datalayer/agent-runtimes/blob/main/examples/README.md)
+- [Agent Runtimes examples directory](https://github.com/datalayer/agent-runtimes/tree/main/examples)
+
+## 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.
+
+Key platform features accessible through this Client and CLI:
+
+- **Remote Runtimes**: Execute code on powerful remote machines with CPU, RAM, and GPU resources
+- **Multiple Interfaces**: Access and consume runtimes through Python Client, CLI, or other integrated tools
+- **Scalable Compute**: Dynamically scale your computational resources based on workload requirements
 
 ## Documentation
 
@@ -179,6 +193,16 @@ This Client is designed to be simple and extensible. We welcome contributions! P
 
 For issues and enhancement requests, please use the [GitHub issue tracker](https://github.com/datalayer/core/issues).
 
+## Architecture
+
+Datalayer Core serves as the foundation for the entire Datalayer ecosystem:
+
+- **Base Classes**: Core application classes inherited by other Datalayer packages
+- **Configuration Management**: Centralized configuration system for all Datalayer components
+- **Authentication Layer**: Unified authentication across all Datalayer services
+- **Runtime Abstraction**: Common interface for different types of compute runtimes
+- **Resource Management**: Automatic cleanup and lifecycle management
+
 ## Use Cases
 
 - **AI/ML Development**: Scale your machine learning workflows with cloud compute using Client or CLI
@@ -195,16 +219,15 @@ This project is licensed under the [BSD 3-Clause License](https://github.com/dat
 
 - **Documentation**: [Datalayer Platform Documentation](https://datalayer.ai/docs/)
 - **Issues**: [GitHub Issues](https://github.com/datalayer/core/issues)
-- **Community**: [Datalayer Platform](https://datalayer.ai)
+- **Community**: [Datalayer Platform](https://datalayer.app/)
 
 ---
 
-<div align="center">
-
-**If this project is helpful to you, please give us a ⭐️**
-
-Made with ❤️ by [Datalayer](https://datalayer.ai)
-
-<img src="https://assets.datalayer.tech/datalayer-25.svg" alt="Datalayer Logo" width="200"></img>
+<p align="center">
+  <img src="https://assets.datalayer.tech/datalayer-25.svg" alt="Datalayer Logo" width="200"></img>
+</p>
 
-</div>
+<p align="center">
+  <strong>🚀 AI Agents for Data Analysis</strong><br></br>
+  <a href="https://datalayer.app/">Get started with Datalayer today!</a>
+</p>

package/lib/api/DatalayerApi.d.ts

@@ -1,3 +1,4 @@
+import { AxiosRequestConfig } from 'axios';
 /**
  * Error wrapper for failed HTTP responses.
  * Includes response details, warnings, errors, and tracebacks.
@@ -53,6 +54,37 @@ export declare class NetworkError extends TypeError {
      */
     constructor(original: TypeError);
 }
+/**
+ * Thrown when a request is made with a JWT that has already expired.
+ *
+ * Raised in place of the `RunResponseError` a 401 would otherwise produce,
+ * and only when the token we sent says it has expired. That distinction is
+ * the point of the class: a 401 can mean a dozen things — a revoked token, a
+ * wrong audience, a permission the account never had — and none of them are
+ * fixed by the same action. An expired token has exactly one remedy, and a
+ * caller that can recognise it can offer that remedy instead of an error.
+ *
+ * Callers are expected to catch this by name:
+ *
+ * ```typescript
+ * try {
+ *   await requestDatalayerAPI({ url, token });
+ * } catch (error) {
+ *   if (error instanceof TokenExpiredError) {
+ *     showSignIn();
+ *     return;
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export declare class TokenExpiredError extends Error {
+    /** When the token expired, in milliseconds since the epoch. */
+    readonly expiredAt: number;
+    /** The URL the request was going to, for context in logs. */
+    readonly url: string;
+    constructor(url: string, expiredAt: number);
+}
 /**
  * Options for Datalayer API requests.
  */
@@ -69,6 +101,14 @@ export interface IRequestDatalayerAPIOptions {
     token?: string;
     /** AbortSignal for request cancellation */
     signal?: AbortSignal;
+    /** Axios response representation for binary or streaming transports. */
+    responseType?: AxiosRequestConfig['responseType'];
+}
+export interface IDatalayerAPIResponse<T> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
 }
 /**
  * Makes authenticated HTTP requests to Datalayer APIs.
@@ -88,4 +128,5 @@ export interface IRequestDatalayerAPIOptions {
  * });
  * ```
  */
-export declare function requestDatalayerAPI<T = any>({ url, method, body, token, signal, headers, }: IRequestDatalayerAPIOptions): Promise<T>;
+export declare function requestDatalayerAPIWithResponse<T = any>({ url, method, body, token, signal, responseType, headers, }: IRequestDatalayerAPIOptions): Promise<IDatalayerAPIResponse<T>>;
+export declare function requestDatalayerAPI<T = any>(options: IRequestDatalayerAPIOptions): Promise<T>;

package/lib/api/DatalayerApi.js

@@ -11,6 +11,7 @@
 import { URLExt } from '@jupyterlab/coreutils';
 import axios from 'axios';
 import { sleep } from '../utils/Sleep.js';
+import { getJwtExpiryMs, isJwtExpired } from '../utils/Jwt.js';
 function isFormDataBody(body) {
     if (!body || typeof body !== 'object') {
         return false;
@@ -119,6 +120,75 @@ export class NetworkError extends TypeError {
         this.stack = original.stack;
     }
 }
+/**
+ * Thrown when a request is made with a JWT that has already expired.
+ *
+ * Raised in place of the `RunResponseError` a 401 would otherwise produce,
+ * and only when the token we sent says it has expired. That distinction is
+ * the point of the class: a 401 can mean a dozen things — a revoked token, a
+ * wrong audience, a permission the account never had — and none of them are
+ * fixed by the same action. An expired token has exactly one remedy, and a
+ * caller that can recognise it can offer that remedy instead of an error.
+ *
+ * Callers are expected to catch this by name:
+ *
+ * ```typescript
+ * try {
+ *   await requestDatalayerAPI({ url, token });
+ * } catch (error) {
+ *   if (error instanceof TokenExpiredError) {
+ *     showSignIn();
+ *     return;
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export class TokenExpiredError extends Error {
+    /** When the token expired, in milliseconds since the epoch. */
+    expiredAt;
+    /** The URL the request was going to, for context in logs. */
+    url;
+    constructor(url, expiredAt) {
+        super(`The Datalayer token expired at ${new Date(expiredAt).toISOString()}; ` +
+            `not sending the request to ${url}.`);
+        // `name` rather than only the prototype, because a bundler that downlevels
+        // this class can break `instanceof` across package boundaries and a name
+        // check is the fallback every caller can still make.
+        this.name = 'TokenExpiredError';
+        this.expiredAt = expiredAt;
+        this.url = url;
+        // Restores the prototype chain when compiled down to ES5, without which
+        // `instanceof TokenExpiredError` is false — see TypeScript #13965.
+        Object.setPrototypeOf(this, TokenExpiredError.prototype);
+    }
+}
+/**
+ * Turn a 401 into a `TokenExpiredError` when the token is the reason for it.
+ *
+ * After the fact rather than before it. Checking the token up front would
+ * have meant deciding, at the door, which endpoints require one — and plenty
+ * here accept anonymous callers, so a pre-flight refusal would reject
+ * requests that were going to succeed. The server is the only thing that
+ * knows whether a given endpoint wanted credentials, and a 401 is it saying
+ * so.
+ *
+ * Asked only on a 401, and only when we actually hold a token that says it
+ * has expired. Every other 401 — a revoked token, a wrong audience, a
+ * permission the account never had, an anonymous call to a protected route —
+ * stays a `RunResponseError`, because those are not fixed by signing in
+ * again and should not be dressed up as though they were.
+ *
+ * Reading `exp` after the response has come back is also the more reliable
+ * moment: time has only moved forward, so a token the server judged expired
+ * reads as expired here too, with no clock-skew allowance to tune.
+ */
+function throwIfTokenExpired(status, token, url) {
+    if (status !== 401 || !token || !isJwtExpired(token)) {
+        return;
+    }
+    throw new TokenExpiredError(url, getJwtExpiryMs(token) ?? Date.now());
+}
 /**
  * Makes authenticated HTTP requests to Datalayer APIs.
  * Handles JSON and FormData, includes auth headers, and manages redirects.
@@ -137,7 +207,7 @@ export class NetworkError extends TypeError {
  * });
  * ```
  */
-export async function requestDatalayerAPI({ url, method, body, token, signal, headers = {}, }) {
+export async function requestDatalayerAPIWithResponse({ url, method, body, token, signal, responseType, headers = {}, }) {
     // Handle FormData differently from JSON
     const isFormData = isFormDataBody(body);
     // Prepare axios config
@@ -147,6 +217,7 @@ export async function requestDatalayerAPI({ url, method, body, token, signal, he
         headers: { ...headers },
         withCredentials: true, // equivalent to credentials: 'include'
         signal,
+        responseType,
         // CORS mode is handled automatically by axios
         // Cache control headers
     };
@@ -191,10 +262,17 @@ export async function requestDatalayerAPI({ url, method, body, token, signal, he
         if (response.status < 300) {
             // Handle redirections if needed.
             if (response.status === 202 && response.headers.location) {
-                return await handleAxiosRedirection(response, axiosConfig);
+                const data = await handleAxiosRedirection(response, axiosConfig);
+                return {
+                    data: data,
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: { ...response.headers },
+                };
             }
         }
         else {
+            throwIfTokenExpired(response.status, token, url);
             const adaptedResponse = {
                 ok: false,
                 status: response.status,
@@ -204,11 +282,17 @@ export async function requestDatalayerAPI({ url, method, body, token, signal, he
             };
             throw await RunResponseError.create(adaptedResponse);
         }
-        return response.data;
+        return {
+            data: response.data,
+            status: response.status,
+            statusText: response.statusText,
+            headers: { ...response.headers },
+        };
     }
     catch (error) {
         if (axios.isAxiosError(error)) {
             if (error.response) {
+                throwIfTokenExpired(error.response.status, token, url);
                 // Convert axios error to our RunResponseError format
                 const adaptedResponse = {
                     ok: false,
@@ -224,6 +308,9 @@ export async function requestDatalayerAPI({ url, method, body, token, signal, he
         throw error;
     }
 }
+export async function requestDatalayerAPI(options) {
+    return (await requestDatalayerAPIWithResponse(options)).data;
+}
 async function handleAxiosRedirection(response, originalConfig) {
     let redirect = response.headers.location;
     if (redirect) {

package/lib/api/constants.d.ts

@@ -3,7 +3,9 @@
  */
 export declare const API_BASE_PATHS: {
     readonly AI_AGENTS: "/api/ai-agents/v1";
+    readonly CONTENTS: "/api/contents/v1";
     readonly IAM: "/api/iam/v1";
+    readonly MCP: "/api/mcp/v1";
     readonly OTEL: "/api/otel/v1";
     readonly RUNTIMES: "/api/runtimes/v1";
     readonly SCHEDULER: "/api/scheduler/v1";
@@ -14,9 +16,25 @@ export declare const API_BASE_PATHS: {
  */
 export declare const DEFAULT_SERVICE_URLS: {
     /** Default URL for AI Agents (durable agent management) service */
-    readonly AI_AGENTS: "https://prod1.datalayer.run";
+    readonly AI_AGENTS: "https://r1.datalayer.run";
+    /**
+     * Default URL for the Contents service.
+     *
+     * The same host as RUNTIMES: Contents runs on the runtimes plane, where the NFS that backs the Home Folder and Volumes lives,
+     * so the service sits beside the storage it serves rather than a network
+     * away from it.
+     */
+    readonly CONTENTS: "https://r1.datalayer.run";
     /** Default URL for IAM (Identity and Access Management) service */
     readonly IAM: "https://prod1.datalayer.run";
+    /**
+     * Default URL of the Jupyter MCP Server, the hosted MCP endpoint.
+     *
+     * This is the MCP resource itself — the URL an agent connects to and the
+     * audience a token names — so it ends in `/mcp`. The gateway's REST
+     * routes (`/api/mcp/v1/...`) live on the same host, one path segment up.
+     */
+    readonly JUPYTER_MCP_SERVER: "https://mcp.datalayer.run/mcp";
     /** Default URL for OTEL (OpenTelemetry observability) service */
     readonly OTEL: "https://prod1.datalayer.run";
     /** Default URL for Runtimes service */

package/lib/api/constants.js

@@ -7,7 +7,9 @@
  */
 export const API_BASE_PATHS = {
     AI_AGENTS: '/api/ai-agents/v1',
+    CONTENTS: '/api/contents/v1',
     IAM: '/api/iam/v1',
+    MCP: '/api/mcp/v1',
     OTEL: '/api/otel/v1',
     RUNTIMES: '/api/runtimes/v1',
     SCHEDULER: '/api/scheduler/v1',
@@ -18,9 +20,25 @@ export const API_BASE_PATHS = {
  */
 export const DEFAULT_SERVICE_URLS = {
     /** Default URL for AI Agents (durable agent management) service */
-    AI_AGENTS: 'https://prod1.datalayer.run',
+    AI_AGENTS: 'https://r1.datalayer.run',
+    /**
+     * Default URL for the Contents service.
+     *
+     * The same host as RUNTIMES: Contents runs on the runtimes plane, where the NFS that backs the Home Folder and Volumes lives,
+     * so the service sits beside the storage it serves rather than a network
+     * away from it.
+     */
+    CONTENTS: 'https://r1.datalayer.run',
     /** Default URL for IAM (Identity and Access Management) service */
     IAM: 'https://prod1.datalayer.run',
+    /**
+     * Default URL of the Jupyter MCP Server, the hosted MCP endpoint.
+     *
+     * This is the MCP resource itself — the URL an agent connects to and the
+     * audience a token names — so it ends in `/mcp`. The gateway's REST
+     * routes (`/api/mcp/v1/...`) live on the same host, one path segment up.
+     */
+    JUPYTER_MCP_SERVER: 'https://mcp.datalayer.run/mcp',
     /** Default URL for OTEL (OpenTelemetry observability) service */
     OTEL: 'https://prod1.datalayer.run',
     /** Default URL for Runtimes service */

package/lib/api/contents/attachments.d.ts

@@ -0,0 +1,9 @@
+import type { AttachmentCreate, AttachmentList, ContentAttachment, ContentAttachmentManifest } from './generated';
+export declare const createAttachment: (token: string, request: AttachmentCreate, idempotencyKey: string, baseUrl?: string) => Promise<ContentAttachment>;
+export declare const listAttachments: (token: string, options?: {
+    sandboxUid?: string;
+    sourceUid?: string;
+    active?: boolean;
+}, baseUrl?: string) => Promise<AttachmentList>;
+export declare const getAttachmentManifest: (token: string, sandboxUid: string, baseUrl?: string) => Promise<ContentAttachmentManifest>;
+export declare const revokeAttachment: (token: string, attachmentUid: string, baseUrl?: string) => Promise<ContentAttachment>;

package/lib/api/contents/attachments.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase, contentsToSnakeCase, } from '../../models/contents/index.js';
+const convert = (value) => contentsToCamelCase(value);
+const url = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/attachments${suffix}`;
+export const createAttachment = async (token, request, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: url(baseUrl),
+    method: 'POST',
+    token,
+    headers: { 'Idempotency-Key': idempotencyKey },
+    body: contentsToSnakeCase(request),
+}));
+export const listAttachments = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    if (options.sandboxUid)
+        parameters.set('sandbox_uid', options.sandboxUid);
+    if (options.sourceUid)
+        parameters.set('source_uid', options.sourceUid);
+    parameters.set('active', String(options.active ?? false));
+    return convert(await requestDatalayerAPI({
+        url: `${url(baseUrl)}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const getAttachmentManifest = async (token, sandboxUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: url(baseUrl, `/manifest/${encodeURIComponent(sandboxUid)}`),
+    method: 'GET',
+    token,
+}));
+export const revokeAttachment = async (token, attachmentUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: url(baseUrl, `/${encodeURIComponent(attachmentUid)}`),
+    method: 'DELETE',
+    token,
+}));

package/lib/api/contents/bridges.d.ts

@@ -0,0 +1,22 @@
+import type { BridgeCreate, BridgeHeartbeat, BridgeList, BridgeOpened, BridgeSession } from './generated';
+export type BridgeState = BridgeSession['state'];
+/** The states a bridge does not leave on its own; polling stops on them. */
+export declare const ENDED_BRIDGE_STATES: ReadonlySet<BridgeState>;
+export declare const isBridgeEnded: (bridge: Pick<BridgeSession, "state">) => boolean;
+/** Open the session of a `local-bridge` attachment, or find it open. */
+export declare const openBridge: (token: string, attachmentUid: string, request: BridgeCreate, baseUrl?: string) => Promise<BridgeOpened>;
+/**
+ * The live session of one attachment, or `null` when none has been opened:
+ * an attachment asked for and not yet dialled has no session, which is an
+ * answer rather than a failure.
+ */
+export declare const getBridgeSession: (token: string, attachmentUid: string, baseUrl?: string) => Promise<BridgeSession | null>;
+/** The caller's sessions, newest first; `active` leaves out the ended ones. */
+export declare const listBridges: (token: string, options?: {
+    active?: boolean;
+}, baseUrl?: string) => Promise<BridgeList>;
+export declare const getBridge: (token: string, bridgeUid: string, baseUrl?: string) => Promise<BridgeSession>;
+/** Still here: the session stays alive and the answer carries a fresh client token. */
+export declare const heartbeatBridge: (token: string, bridgeUid: string, baseUrl?: string) => Promise<BridgeHeartbeat>;
+/** End a session: its tokens stop working before the sandbox side unmounts. */
+export declare const revokeBridge: (token: string, bridgeUid: string, baseUrl?: string) => Promise<BridgeSession>;

package/lib/api/contents/bridges.js

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The bridge session behind a `local-bridge` attachment.
+ *
+ * A session is what the attachment holds while a person's computer serves a
+ * folder to the sandbox through the relay. A browser never serves one — the
+ * CLI does — so what it does here is look: the session of an attachment,
+ * the caller's sessions, and the one thing it may do to them, revoke.
+ * Opening and heartbeating are here for completeness and for a desktop
+ * client that embeds this library; a page has no folder to bind.
+ */
+import { RunResponseError, requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase, contentsToSnakeCase } from '../../models/contents/index.js';
+/** The states a bridge does not leave on its own; polling stops on them. */
+export const ENDED_BRIDGE_STATES = new Set([
+    'revoked',
+    'expired',
+]);
+export const isBridgeEnded = (bridge) => ENDED_BRIDGE_STATES.has(bridge.state);
+const convert = (value) => contentsToCamelCase(value);
+const contentsUrl = (baseUrl, suffix) => `${baseUrl}${API_BASE_PATHS.CONTENTS}${suffix}`;
+/** Open the session of a `local-bridge` attachment, or find it open. */
+export const openBridge = async (token, attachmentUid, request, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: contentsUrl(baseUrl, `/attachments/${encodeURIComponent(attachmentUid)}/bridge`),
+    method: 'POST',
+    token,
+    body: contentsToSnakeCase(request),
+}));
+/**
+ * The live session of one attachment, or `null` when none has been opened:
+ * an attachment asked for and not yet dialled has no session, which is an
+ * answer rather than a failure.
+ */
+export const getBridgeSession = async (token, attachmentUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    try {
+        return convert(await requestDatalayerAPI({
+            url: contentsUrl(baseUrl, `/attachments/${encodeURIComponent(attachmentUid)}/bridge`),
+            method: 'GET',
+            token,
+        }));
+    }
+    catch (error) {
+        if (error instanceof RunResponseError && error.response.status === 404) {
+            return null;
+        }
+        throw error;
+    }
+};
+/** The caller's sessions, newest first; `active` leaves out the ended ones. */
+export const listBridges = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    parameters.set('active', String(options.active ?? false));
+    return convert(await requestDatalayerAPI({
+        url: `${contentsUrl(baseUrl, '/bridges')}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const getBridge = async (token, bridgeUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: contentsUrl(baseUrl, `/bridges/${encodeURIComponent(bridgeUid)}`),
+    method: 'GET',
+    token,
+}));
+/** Still here: the session stays alive and the answer carries a fresh client token. */
+export const heartbeatBridge = async (token, bridgeUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: contentsUrl(baseUrl, `/bridges/${encodeURIComponent(bridgeUid)}/heartbeat`),
+    method: 'POST',
+    token,
+}));
+/** End a session: its tokens stop working before the sandbox side unmounts. */
+export const revokeBridge = async (token, bridgeUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convert(await requestDatalayerAPI({
+    url: contentsUrl(baseUrl, `/bridges/${encodeURIComponent(bridgeUid)}`),
+    method: 'DELETE',
+    token,
+}));

package/lib/api/contents/capabilities.d.ts

@@ -0,0 +1,11 @@
+import type { ContentsCapabilities, OperationCapability, SourceKindCapability } from './generated';
+export type ContentsSourceKindCapability = SourceKindCapability;
+export type ContentsOperationCapability = OperationCapability;
+export type { ContentsCapabilities };
+/**
+ * Ask the service what this caller can reach, create and count.
+ *
+ * A client cannot answer either question on its own: it does not know which
+ * parts of Contents are deployed here, nor what this principal may use.
+ */
+export declare const getCapabilities: (token: string, baseUrl?: string) => Promise<ContentsCapabilities>;

package/lib/api/contents/capabilities.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase } from '../../models/contents/index.js';
+/**
+ * Ask the service what this caller can reach, create and count.
+ *
+ * A client cannot answer either question on its own: it does not know which
+ * parts of Contents are deployed here, nor what this principal may use.
+ */
+export const getCapabilities = async (token, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const value = await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.CONTENTS}/capabilities`,
+        method: 'GET',
+        token,
+    });
+    return contentsToCamelCase(value);
+};

package/lib/api/contents/cloudStorage.d.ts

@@ -0,0 +1,31 @@
+import type { CloudObjectList, CloudObjectView, ConnectionTest, CredentialDiagnostics, CatalogSource } from './generated';
+export interface PresignedObjectUrl {
+    url: string;
+    operation: 'get' | 'put';
+    expiresIn: number;
+}
+/** One page of a bucket under a prefix; `nextCursor` continues it. */
+export declare const listCloudObjects: (token: string, sourceUid: string, options?: {
+    prefix?: string;
+    cursor?: string;
+}, baseUrl?: string) => Promise<CloudObjectList>;
+export declare const statCloudObject: (token: string, sourceUid: string, path: string, baseUrl?: string) => Promise<CloudObjectView>;
+/** The bytes of one object, or a range of them. */
+export declare const downloadCloudObject: (token: string, sourceUid: string, path: string, options?: {
+    range?: string;
+}, baseUrl?: string) => Promise<{
+    body: ArrayBuffer;
+    status: number;
+    headers: Record<string, string>;
+}>;
+/** Can the bucket be reached with the credential attached: a verdict, not a stack trace. */
+export declare const testCloudConnection: (token: string, sourceUid: string, baseUrl?: string) => Promise<ConnectionTest>;
+/** A URL good for one path, one operation, a bounded time. A `put` needs the right to update. */
+export declare const presignCloudObject: (token: string, sourceUid: string, path: string, options?: {
+    operation?: "get" | "put";
+    expiresIn?: number;
+}, baseUrl?: string) => Promise<PresignedObjectUrl>;
+/** Whether the source's credential is referenced and resolvable — never its value. */
+export declare const getCredentialDiagnostics: (token: string, sourceUid: string, baseUrl?: string) => Promise<CredentialDiagnostics>;
+/** Point the source at another credential. Owner only, conditional on the ETag. */
+export declare const rotateSourceCredential: (token: string, sourceUid: string, credentialUid: string, etag: string, baseUrl?: string) => Promise<CatalogSource>;