@datalayer/core 1.1.60 → 1.1.66

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.ai). It provides TypeScript 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.
 
@@ -99,7 +99,7 @@ Datalayer Core serves as the foundation for the entire Datalayer ecosystem:
 
 ## Examples
 
-- [OTEL example README](./examples/otel/README.md)
+- [OTEL example README](https://github.com/datalayer/core/blob/main/examples/otel/README.md)
 
 ## Documentation
 

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";
@@ -15,8 +17,24 @@ 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";
+    /**
+     * 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',
@@ -19,8 +21,24 @@ 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',
+    /**
+     * 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,43 @@
+/*
+ * 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';
+import { assertSandboxUid } from './sandboxUid.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', assertSandboxUid(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({
+    // Throws on a Pod name. Contents validates this while building its
+    // reply, so sending the wrong spelling produced a 500 the caller could
+    // not read; this fails where the caller can be seen.
+    url: url(baseUrl, `/manifest/${encodeURIComponent(assertSandboxUid(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>;

package/lib/api/contents/cloudStorage.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A bucket through the service: listed, stat'ed, read, tested and signed.
+ *
+ * The credential never comes this way. The service resolves it for each
+ * request and hands it to a provider adapter; what a browser gets back is
+ * objects, bytes, a verdict, or a URL good for one path, one operation and a
+ * bounded time.
+ */
+import { requestDatalayerAPI, requestDatalayerAPIWithResponse, } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase } from '../../models/contents/index.js';
+const convertResponse = (value) => contentsToCamelCase(value);
+const cloudUrl = (baseUrl, sourceUid, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/${encodeURIComponent(sourceUid)}/cloud${suffix}`;
+/** One page of a bucket under a prefix; `nextCursor` continues it. */
+export const listCloudObjects = async (token, sourceUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    if (options.prefix) {
+        parameters.set('prefix', options.prefix);
+    }
+    if (options.cursor) {
+        parameters.set('cursor', options.cursor);
+    }
+    const query = parameters.toString();
+    return convertResponse(await requestDatalayerAPI({
+        url: `${cloudUrl(baseUrl, sourceUid, '/objects')}${query ? `?${query}` : ''}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const statCloudObject = async (token, sourceUid, path, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: `${cloudUrl(baseUrl, sourceUid, '/objects/stat')}?path=${encodeURIComponent(path)}`,
+    method: 'GET',
+    token,
+}));
+/** The bytes of one object, or a range of them. */
+export const downloadCloudObject = async (token, sourceUid, path, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: `${cloudUrl(baseUrl, sourceUid, '/objects/content')}?path=${encodeURIComponent(path)}`,
+        method: 'GET',
+        token,
+        headers: options.range ? { Range: options.range } : undefined,
+        responseType: 'arraybuffer',
+    });
+    return {
+        body: response.data,
+        status: response.status,
+        headers: response.headers,
+    };
+};
+/** Can the bucket be reached with the credential attached: a verdict, not a stack trace. */
+export const testCloudConnection = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: cloudUrl(baseUrl, sourceUid, '/test'),
+    method: 'POST',
+    token,
+}));
+/** A URL good for one path, one operation, a bounded time. A `put` needs the right to update. */
+export const presignCloudObject = async (token, sourceUid, path, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams({ path, operation: options.operation ?? 'get' });
+    if (options.expiresIn) {
+        parameters.set('expires_in', String(options.expiresIn));
+    }
+    return convertResponse(await requestDatalayerAPI({
+        url: `${cloudUrl(baseUrl, sourceUid, '/objects/presign')}?${parameters.toString()}`,
+        method: 'POST',
+        token,
+    }));
+};
+/** Whether the source's credential is referenced and resolvable — never its value. */
+export const getCredentialDiagnostics = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/${encodeURIComponent(sourceUid)}/diagnostics`,
+    method: 'GET',
+    token,
+}));
+/** Point the source at another credential. Owner only, conditional on the ETag. */
+export const rotateSourceCredential = async (token, sourceUid, credentialUid, etag, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/${encodeURIComponent(sourceUid)}/credential`,
+    method: 'POST',
+    token,
+    headers: { 'If-Match': etag },
+    body: { credential_uid: credentialUid },
+}));

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

@@ -0,0 +1,37 @@
+import type { CertificateSigningRequest, DataServerConnectivity, DataServerStatus, EffectivePermissions, IssuedIdentity } from './generated';
+/** The states the service keeps a registration in. */
+export type DataserverState = DataServerStatus['state'];
+export declare const DATASERVER_STATES: ReadonlyArray<DataserverState>;
+/** The state as a person reads it. */
+export declare const DATASERVER_STATE_LABELS: Record<DataserverState, string>;
+export type DataserverAction = 'test' | 'rotateIdentity' | 'drain' | 'resume' | 'revoke' | 'archive' | 'delete';
+export interface DataserverActionAvailability {
+    enabled: boolean;
+    /** Why not, when not: the state or the permission that stands in the way. */
+    reason?: string;
+}
+/**
+ * Which actions a reader may take on a gateway in this state, and why not.
+ *
+ * `view` inspects; `execute` tests; owner or update-holder registers,
+ * rotates, drains, resumes, revokes, archives and deletes. A gateway that is
+ * revoked, or one that has gone quiet, keeps its record — the disabled
+ * actions name the state as the reason rather than disappearing.
+ */
+export declare const dataserverActionAvailability: (state: DataserverState | null | undefined, permissions: Pick<EffectivePermissions, "isOwner" | "update" | "execute">, options?: {
+    archived?: boolean;
+}) => Record<DataserverAction, DataserverActionAvailability>;
+/** The gateway as last heard: its lease, its connectors, its queue. */
+export declare const getDataserverStatus: (token: string, sourceUid: string, baseUrl?: string) => Promise<DataServerStatus>;
+/** Try the gateway on Flight and on the HTTPS fallback; the answer is a verdict per path. */
+export declare const testDataserver: (token: string, sourceUid: string, baseUrl?: string) => Promise<DataServerConnectivity>;
+/** Stop routing new queries; the ones running finish. */
+export declare const drainDataserver: (token: string, sourceUid: string, baseUrl?: string) => Promise<DataServerStatus>;
+/** Route to the gateway again. */
+export declare const resumeDataserver: (token: string, sourceUid: string, baseUrl?: string) => Promise<DataServerStatus>;
+/** Refuse the gateway's identity from now on. Nothing in its network changes. */
+export declare const revokeDataserver: (token: string, sourceUid: string, baseUrl?: string) => Promise<DataServerStatus>;
+/** A first certificate for the identity the CSR names. */
+export declare const issueDataserverIdentity: (token: string, sourceUid: string, request: CertificateSigningRequest, baseUrl?: string) => Promise<IssuedIdentity>;
+/** A new certificate that overlaps the current one, so nothing stops. */
+export declare const rotateDataserverIdentity: (token: string, sourceUid: string, request: CertificateSigningRequest, baseUrl?: string) => Promise<IssuedIdentity>;