@datalayer/core 1.1.59 → 1.1.66

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

@@ -0,0 +1,16 @@
+export * from './generated';
+export * from './attachments';
+export * from './bridges';
+export * from './sandboxUid';
+export * from './capabilities';
+export * from './cloudStorage';
+export * from './datasets';
+export * from './datasources';
+export * from './dataservers';
+export * from './mcp';
+export * from './objects';
+export * from './runtimeMounts';
+export * from './operations';
+export * from './sources';
+export * from './sync';
+export * from './transfers';

package/lib/api/contents/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './generated.js';
+export * from './attachments.js';
+export * from './bridges.js';
+export * from './sandboxUid.js';
+export * from './capabilities.js';
+export * from './cloudStorage.js';
+export * from './datasets.js';
+export * from './datasources.js';
+export * from './dataservers.js';
+export * from './mcp.js';
+export * from './objects.js';
+export * from './runtimeMounts.js';
+export * from './operations.js';
+export * from './sources.js';
+export * from './sync.js';
+export * from './transfers.js';

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

@@ -0,0 +1,46 @@
+import type { McpApproval, McpApprovalList, McpCall, McpCallCreate, McpCallList, McpHealth, McpSession, McpSessionCreate, McpSessionList, McpToolManifest } from './generated';
+export type McpCallStatus = McpCall['status'];
+export type McpApprovalStatus = McpApproval['status'];
+export type McpSessionStatus = McpSession['status'];
+/** A call the service has finished with, one way or another. */
+export declare const MCP_TERMINAL_CALL_STATUSES: ReadonlySet<McpCallStatus>;
+export declare const isMcpCallTerminal: (status: McpCallStatus) => boolean;
+/** The tools and resources the server behind a source offers. */
+export declare const discoverMcpTools: (token: string, sourceUid: string, baseUrl?: string) => Promise<McpToolManifest>;
+/** Does the server answer through this source, right now? */
+export declare const testMcpSource: (token: string, sourceUid: string, baseUrl?: string) => Promise<McpHealth>;
+/**
+ * Open a scoped connection to an MCP source on the caller's behalf.
+ *
+ * The session's allowlists are the source's, narrowed by `tools` when given.
+ */
+export declare const createMcpSession: (token: string, request: McpSessionCreate, idempotencyKey: string, baseUrl?: string) => Promise<McpSession>;
+export declare const getMcpSession: (token: string, sessionUid: string, baseUrl?: string) => Promise<McpSession>;
+/** Every session the caller opened. The contract lists them whole; a reader narrows. */
+export declare const listMcpSessions: (token: string, baseUrl?: string) => Promise<McpSessionList>;
+export declare const revokeMcpSession: (token: string, sessionUid: string, baseUrl?: string) => Promise<McpSession>;
+/**
+ * Invoke one tool through a session.
+ *
+ * The answer is the call record, not necessarily the result: under an
+ * `explicit` approval policy it comes back `pending-approval` with the
+ * approval to decide, and a bulk acquisition ends in artifacts that name a
+ * Transfer rather than carrying bytes. The arguments are the tool's own and
+ * go over as typed; only the envelope is converted.
+ */
+export declare const callMcpTool: (token: string, sessionUid: string, request: McpCallCreate, baseUrl?: string) => Promise<McpCall>;
+export declare const getMcpCall: (token: string, sessionUid: string, callUid: string, baseUrl?: string) => Promise<McpCall>;
+/**
+ * The calls made through a session, newest first.
+ *
+ * This is where provenance lives: a call whose result carries artifacts is
+ * an acquisition, and the artifact names the Transfer, object and version it
+ * became.
+ */
+export declare const listMcpCalls: (token: string, sessionUid: string, baseUrl?: string) => Promise<McpCallList>;
+/** The caller's approvals, in one status; the contract filters on nothing else. */
+export declare const listMcpApprovals: (token: string, options?: {
+    status?: McpApprovalStatus;
+}, baseUrl?: string) => Promise<McpApprovalList>;
+/** Approve or reject a pending call; the note travels with the decision. */
+export declare const decideMcpApproval: (token: string, approvalUid: string, decision: "approve" | "reject", note?: string, baseUrl?: string) => Promise<McpApproval>;

package/lib/api/contents/mcp.js

@@ -0,0 +1,157 @@
+/*
+ * 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.
+ */
+/**
+ * An MCP source through the service: discovered, tested, used.
+ *
+ * Nothing here talks to the MCP server. Contents does, with the credential
+ * it holds, through a session it opens for the caller and narrows to the
+ * source's allowlists. What a browser gets back is tool definitions, call
+ * records and approvals — and for a call that moved bytes, the Transfer or
+ * object that holds them rather than the bytes.
+ *
+ * The wire types are the generated ones; what is declared here is what the
+ * contract does not name — the status unions as standalone types, and which
+ * of them are terminal.
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase, contentsToSnakeCase } from '../../models/contents/index.js';
+/** A call the service has finished with, one way or another. */
+export const MCP_TERMINAL_CALL_STATUSES = new Set([
+    'denied',
+    'succeeded',
+    'failed',
+    'refused',
+]);
+export const isMcpCallTerminal = (status) => MCP_TERMINAL_CALL_STATUSES.has(status);
+const convertRequest = (value) => contentsToSnakeCase(value);
+const convertResponse = (value) => contentsToCamelCase(value);
+/**
+ * A tool's input schema is JSON Schema: its property names are the tool's
+ * argument names and must survive as typed, so the discovery answer is
+ * converted around them rather than through them.
+ */
+const convertDiscovery = (value) => {
+    const raw = (value ?? {});
+    const tools = (raw.tools ?? []).map(tool => ({
+        name: String(tool.name ?? ''),
+        description: tool.description ?? null,
+        inputSchema: tool.input_schema ??
+            tool.inputSchema ??
+            {},
+    }));
+    const resources = (raw.resources ?? []).map(resource => ({
+        uri: String(resource.uri ?? ''),
+        name: resource.name ?? null,
+        mediaType: resource.media_type ?? null,
+    }));
+    return { tools, resources, discoveredAt: raw.discovered_at ?? '' };
+};
+const contentsUrl = (baseUrl, suffix) => `${baseUrl}${API_BASE_PATHS.CONTENTS}${suffix}`;
+const sourceMcpUrl = (baseUrl, sourceUid, suffix = '') => contentsUrl(baseUrl, `/sources/${encodeURIComponent(sourceUid)}/mcp${suffix}`);
+const sessionUrl = (baseUrl, sessionUid, suffix = '') => contentsUrl(baseUrl, `/mcp-sessions/${encodeURIComponent(sessionUid)}${suffix}`);
+/** The tools and resources the server behind a source offers. */
+export const discoverMcpTools = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertDiscovery(await requestDatalayerAPI({
+    url: sourceMcpUrl(baseUrl, sourceUid, '/tools'),
+    method: 'GET',
+    token,
+}));
+/** Does the server answer through this source, right now? */
+export const testMcpSource = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sourceMcpUrl(baseUrl, sourceUid, '/health'),
+    method: 'POST',
+    token,
+}));
+/**
+ * Open a scoped connection to an MCP source on the caller's behalf.
+ *
+ * The session's allowlists are the source's, narrowed by `tools` when given.
+ */
+export const createMcpSession = async (token, request, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: contentsUrl(baseUrl, '/mcp-sessions'),
+    method: 'POST',
+    token,
+    headers: { 'Idempotency-Key': idempotencyKey },
+    body: convertRequest(request),
+}));
+export const getMcpSession = async (token, sessionUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sessionUrl(baseUrl, sessionUid),
+    method: 'GET',
+    token,
+}));
+/** Every session the caller opened. The contract lists them whole; a reader narrows. */
+export const listMcpSessions = async (token, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: contentsUrl(baseUrl, '/mcp-sessions'),
+    method: 'GET',
+    token,
+}));
+export const revokeMcpSession = async (token, sessionUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sessionUrl(baseUrl, sessionUid),
+    method: 'DELETE',
+    token,
+}));
+/**
+ * Invoke one tool through a session.
+ *
+ * The answer is the call record, not necessarily the result: under an
+ * `explicit` approval policy it comes back `pending-approval` with the
+ * approval to decide, and a bulk acquisition ends in artifacts that name a
+ * Transfer rather than carrying bytes. The arguments are the tool's own and
+ * go over as typed; only the envelope is converted.
+ */
+export const callMcpTool = async (token, sessionUid, request, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sessionUrl(baseUrl, sessionUid, '/calls'),
+    method: 'POST',
+    token,
+    body: {
+        tool: request.tool,
+        arguments: request.arguments ?? {},
+        ...(request.destinationUri ? { destination_uri: request.destinationUri } : {}),
+    },
+}));
+export const getMcpCall = async (token, sessionUid, callUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sessionUrl(baseUrl, sessionUid, `/calls/${encodeURIComponent(callUid)}`),
+    method: 'GET',
+    token,
+}));
+/**
+ * The calls made through a session, newest first.
+ *
+ * This is where provenance lives: a call whose result carries artifacts is
+ * an acquisition, and the artifact names the Transfer, object and version it
+ * became.
+ */
+export const listMcpCalls = async (token, sessionUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sessionUrl(baseUrl, sessionUid, '/calls'),
+    method: 'GET',
+    token,
+}));
+/** The caller's approvals, in one status; the contract filters on nothing else. */
+export const listMcpApprovals = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    if (options.status) {
+        parameters.set('status', options.status);
+    }
+    const query = parameters.toString();
+    return convertResponse(await requestDatalayerAPI({
+        url: `${contentsUrl(baseUrl, '/mcp-approvals')}${query ? `?${query}` : ''}`,
+        method: 'GET',
+        token,
+    }));
+};
+/** Approve or reject a pending call; the note travels with the decision. */
+export const decideMcpApproval = async (token, approvalUid, decision, note, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const body = note ? { note } : {};
+    return convertResponse(await requestDatalayerAPI({
+        url: contentsUrl(baseUrl, `/mcp-approvals/${encodeURIComponent(approvalUid)}/${decision}`),
+        method: 'POST',
+        token,
+        body,
+    }));
+};

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

@@ -0,0 +1,31 @@
+import type { HomeFolderFileList, ContentObject, ObjectList, RestoreRequest, HomeFolderQuota, VersionList } from './generated';
+export type HomeFolderObjectListOptions = {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    order?: 'path' | 'updated';
+};
+export declare const getHomeFolderQuota: (token: string, baseUrl?: string) => Promise<HomeFolderQuota>;
+export declare const listHomeFolderObjects: (token: string, options?: HomeFolderObjectListOptions, baseUrl?: string) => Promise<ObjectList>;
+export declare const statHomeFolderObject: (token: string, path: string, baseUrl?: string) => Promise<ContentObject>;
+export declare const listHomeFolderObjectVersions: (token: string, objectUid: string, options?: {
+    cursor?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<VersionList>;
+export declare const deleteHomeFolderObject: (token: string, objectUid: string, idempotencyKey: string, baseUrl?: string) => Promise<ContentObject>;
+export declare const restoreHomeFolderObject: (token: string, objectUid: string, request: RestoreRequest, idempotencyKey: string, baseUrl?: string) => Promise<ContentObject>;
+/**
+ * The files under a path of the caller's Home Folders — what a sandbox
+ * wrote as well as what was uploaded — as the shared filesystem holds them.
+ * The root lists the folders the caller reaches: their own, and one per
+ * organization and team.
+ */
+export declare const listHomeFolderFiles: (token: string, path?: string, baseUrl?: string) => Promise<HomeFolderFileList>;
+/** The bytes of one Home Folder file, or a range of them, from the shared filesystem. */
+export declare const readHomeFolderFile: (token: string, path: string, options?: {
+    range?: string;
+}, baseUrl?: string) => Promise<{
+    body: ArrayBuffer;
+    status: number;
+    headers: Record<string, string>;
+}>;

package/lib/api/contents/objects.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { requestDatalayerAPI, requestDatalayerAPIWithResponse, } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase, contentsToSnakeCase } from '../../models/contents/index.js';
+const homeFolderUrl = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/home-folder${suffix}`;
+const convertResponse = (value) => contentsToCamelCase(value);
+const homeFolderObjectsUrl = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/home-folder/objects${suffix}`;
+export const getHomeFolderQuota = async (token, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/home-folder/quota`,
+    method: 'GET',
+    token,
+}));
+export const listHomeFolderObjects = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    parameters.set('limit', String(options.limit ?? 100));
+    if (options.prefix) {
+        parameters.set('prefix', options.prefix);
+    }
+    if (options.cursor) {
+        parameters.set('cursor', options.cursor);
+    }
+    if (options.order) {
+        parameters.set('order', options.order);
+    }
+    return convertResponse(await requestDatalayerAPI({
+        url: `${homeFolderObjectsUrl(baseUrl)}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const statHomeFolderObject = async (token, path, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams({ path });
+    return convertResponse(await requestDatalayerAPI({
+        url: `${homeFolderObjectsUrl(baseUrl, '/stat')}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const listHomeFolderObjectVersions = async (token, objectUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    parameters.set('limit', String(options.limit ?? 100));
+    if (options.cursor) {
+        parameters.set('cursor', options.cursor);
+    }
+    return convertResponse(await requestDatalayerAPI({
+        url: `${homeFolderObjectsUrl(baseUrl, `/${encodeURIComponent(objectUid)}/versions`)}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const deleteHomeFolderObject = async (token, objectUid, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: homeFolderObjectsUrl(baseUrl, `/${encodeURIComponent(objectUid)}`),
+    method: 'DELETE',
+    token,
+    headers: { 'Idempotency-Key': idempotencyKey },
+}));
+export const restoreHomeFolderObject = async (token, objectUid, request, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: homeFolderObjectsUrl(baseUrl, `/${encodeURIComponent(objectUid)}/restore`),
+    method: 'POST',
+    token,
+    headers: { 'Idempotency-Key': idempotencyKey },
+    body: contentsToSnakeCase(request),
+}));
+/**
+ * The files under a path of the caller's Home Folders — what a sandbox
+ * wrote as well as what was uploaded — as the shared filesystem holds them.
+ * The root lists the folders the caller reaches: their own, and one per
+ * organization and team.
+ */
+export const listHomeFolderFiles = async (token, path = '', baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: `${homeFolderUrl(baseUrl, '/files')}?path=${encodeURIComponent(path)}`,
+    method: 'GET',
+    token,
+}));
+/** The bytes of one Home Folder file, or a range of them, from the shared filesystem. */
+export const readHomeFolderFile = async (token, path, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: `${homeFolderUrl(baseUrl, '/files/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 };
+};

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

@@ -0,0 +1,3 @@
+import type { OperationView } from './generated';
+export declare const getOperation: (token: string, operationUid: string, baseUrl?: string) => Promise<OperationView>;
+export declare const cancelOperation: (token: string, operationUid: string, baseUrl?: string) => Promise<OperationView>;

package/lib/api/contents/operations.js

@@ -0,0 +1,19 @@
+/*
+ * 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';
+const operationUrl = (baseUrl, operationUid) => `${baseUrl}${API_BASE_PATHS.CONTENTS}/operations/${encodeURIComponent(operationUid)}`;
+const convertResponse = (value) => contentsToCamelCase(value);
+export const getOperation = async (token, operationUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: operationUrl(baseUrl, operationUid),
+    method: 'GET',
+    token,
+}));
+export const cancelOperation = async (token, operationUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: `${operationUrl(baseUrl, operationUid)}/cancel`,
+    method: 'POST',
+    token,
+}));

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

@@ -0,0 +1,40 @@
+/** One folder bound into a running Runtime. */
+export type RuntimeMount = {
+    /** The single path segment it appears under, and the account's handle. */
+    target: string;
+    /** Where it comes from on the shared filesystem. Informational. */
+    source: string;
+    mode: 'ro' | 'rw';
+    allowExec: boolean;
+    uid?: string;
+    kind?: string;
+};
+/** What the platform reports about a Runtime's mounts. */
+export type RuntimeMounts = {
+    success: boolean;
+    message: string;
+    /**
+     * `ready` when everything asked for is mounted, `degraded` when some of it
+     * is, `failed` or `GATEWAY_NOT_READY` when none of it is yet.
+     */
+    state: string;
+    /** What has been granted. */
+    mounts: RuntimeMount[];
+    /** Of those, what has actually arrived in the sandbox. */
+    mounted: string[];
+    /** Those that could not be mounted, by target, with the reason. */
+    failed: Record<string, string>;
+};
+/** What this Runtime is granted, and what has arrived. */
+export declare const getRuntimeMounts: (token: string, runtimeName: string, baseUrl?: string) => Promise<RuntimeMounts>;
+/**
+ * Mount the caller's home folders into a Runtime that is already running.
+ *
+ * Which folders is not a parameter: the platform resolves the caller's own
+ * memberships and mounts those.
+ */
+export declare const attachRuntimeMounts: (token: string, runtimeName: string, baseUrl?: string) => Promise<RuntimeMounts>;
+/** Take one folder out of a running Runtime, by the name it appears under. */
+export declare const detachRuntimeMount: (token: string, runtimeName: string, target: string, baseUrl?: string) => Promise<RuntimeMounts>;
+/** Whether the platform has finished applying what was asked for. */
+export declare const isRuntimeMountsSettled: (mounts?: RuntimeMounts) => boolean;

package/lib/api/contents/runtimeMounts.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The folders mounted into a Runtime that is already running.
+ *
+ * A Pod's volumes are fixed when it is created, so for most of a sandbox's
+ * life its mounts were decided before it existed. The mount gateway lifts
+ * that for the Home Folder: the platform binds a folder into a running pod
+ * and the sandbox sees it at `/home/jovyan/{handle}` within a second or two,
+ * with no restart.
+ *
+ * Not every Runtime can take one — a pod created before the gateway cannot,
+ * and neither can a sandbox at an external provider — which is why a Runtime
+ * carries `mountGateway` and why attaching answers with a reason rather than
+ * appearing to work. The folders themselves are never named here: they are
+ * resolved from the caller's memberships by the platform, and a client naming
+ * one is not a way to mount it.
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase } from '../../models/contents/index.js';
+const convert = (value) => {
+    const converted = contentsToCamelCase(value);
+    return {
+        ...converted,
+        mounts: converted.mounts ?? [],
+        mounted: converted.mounted ?? [],
+        failed: converted.failed ?? {},
+    };
+};
+const runtimesUrl = (baseUrl, suffix) => `${baseUrl}${API_BASE_PATHS.RUNTIMES}${suffix}`;
+/** What this Runtime is granted, and what has arrived. */
+export const getRuntimeMounts = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => convert(await requestDatalayerAPI({
+    url: runtimesUrl(baseUrl, `/runtimes/${encodeURIComponent(runtimeName)}/mounts`),
+    method: 'GET',
+    token,
+}));
+/**
+ * Mount the caller's home folders into a Runtime that is already running.
+ *
+ * Which folders is not a parameter: the platform resolves the caller's own
+ * memberships and mounts those.
+ */
+export const attachRuntimeMounts = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => convert(await requestDatalayerAPI({
+    url: runtimesUrl(baseUrl, `/runtimes/${encodeURIComponent(runtimeName)}/mounts`),
+    method: 'POST',
+    token,
+    body: {},
+}));
+/** Take one folder out of a running Runtime, by the name it appears under. */
+export const detachRuntimeMount = async (token, runtimeName, target, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => convert(await requestDatalayerAPI({
+    url: runtimesUrl(baseUrl, `/runtimes/${encodeURIComponent(runtimeName)}/mounts/${encodeURIComponent(target)}`),
+    method: 'DELETE',
+    token,
+}));
+/** Whether the platform has finished applying what was asked for. */
+export const isRuntimeMountsSettled = (mounts) => mounts ? mounts.state === 'ready' || mounts.state === 'degraded' : false;

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

@@ -0,0 +1,53 @@
+/**
+ * A sandbox is identified by its uid, never by its runtime's Pod name.
+ *
+ * A Datalayer runtime has a ULID; its Kubernetes Pod is named
+ * `runtime-<ulid>`, because a Pod name has to be a DNS label. Route
+ * parameters and `runtime_name` fields carry the Pod name, and every Contents
+ * record keyed on a sandbox is keyed on the ULID.
+ *
+ * Passing the Pod name where a uid belongs used to *work* at the call site
+ * and fail far away: Contents validates `sandbox_uid` while building its
+ * reply, so a Pod name became an unhandled 500 that reached the browser as
+ * "Network Error", with nothing readable in it and nothing pointing at the
+ * caller. Throwing here names the caller in the stack instead.
+ *
+ * The server half of this is `datalayer_common.runtime_names`.
+ */
+/** What a runtime Pod's name is prefixed with. */
+export declare const RUNTIME_NAME_PREFIX = "runtime-";
+/** Thrown when a Pod name is given where a sandbox uid is required. */
+export declare class RuntimeNameNotAUid extends Error {
+    readonly value: string;
+    constructor(value: string);
+}
+/**
+ * Assert that a value is a sandbox uid, and return it.
+ *
+ * Use this wherever a `sandbox_uid` is sent. A non-Datalayer identifier —
+ * Daytona, E2B and Modal name their own sandboxes — passes through: there is
+ * no ULID to check it against, and inventing one would be worse.
+ */
+export declare function assertSandboxUid(value: string): string;
+/**
+ * The Pod name for a sandbox uid, converting on purpose.
+ *
+ * The mirror of {@link sandboxUidFromRuntimeName}, and the direction that was
+ * missing: route parameters and `runtime_name` fields carry the **Pod name**,
+ * so anything addressing `/runtimes/{name}/…` needs one. Without this, a
+ * caller holding only a uid either wrote the prefix itself or — the version
+ * that was here — passed the uid and hoped, which is a `404` from a route
+ * whose parameter looked plausible.
+ *
+ * Idempotent, like the server's `runtime_name()`: a name that has been
+ * through here stays one name rather than growing a second prefix.
+ */
+export declare function runtimeNameFromSandboxUid(value: string): string;
+/**
+ * The sandbox uid for a Pod name, converting on purpose.
+ *
+ * For the few callers that genuinely only hold the Pod name — a route
+ * parameter, a label read off a Pod. Everywhere else should already have the
+ * uid, and {@link assertSandboxUid} is what says so.
+ */
+export declare function sandboxUidFromRuntimeName(value: string): string;

package/lib/api/contents/sandboxUid.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A sandbox is identified by its uid, never by its runtime's Pod name.
+ *
+ * A Datalayer runtime has a ULID; its Kubernetes Pod is named
+ * `runtime-<ulid>`, because a Pod name has to be a DNS label. Route
+ * parameters and `runtime_name` fields carry the Pod name, and every Contents
+ * record keyed on a sandbox is keyed on the ULID.
+ *
+ * Passing the Pod name where a uid belongs used to *work* at the call site
+ * and fail far away: Contents validates `sandbox_uid` while building its
+ * reply, so a Pod name became an unhandled 500 that reached the browser as
+ * "Network Error", with nothing readable in it and nothing pointing at the
+ * caller. Throwing here names the caller in the stack instead.
+ *
+ * The server half of this is `datalayer_common.runtime_names`.
+ */
+/** What a runtime Pod's name is prefixed with. */
+export const RUNTIME_NAME_PREFIX = 'runtime-';
+/** Thrown when a Pod name is given where a sandbox uid is required. */
+export class RuntimeNameNotAUid extends Error {
+    value;
+    constructor(value) {
+        super(`'${value}' is a runtime Pod name, not a sandbox uid. A sandbox is ` +
+            `identified by its ULID ('${value.slice(RUNTIME_NAME_PREFIX.length)}'). ` +
+            'If all you hold is the Pod name, convert it deliberately with ' +
+            'sandboxUidFromRuntimeName().');
+        this.name = 'RuntimeNameNotAUid';
+        this.value = value;
+    }
+}
+/**
+ * Assert that a value is a sandbox uid, and return it.
+ *
+ * Use this wherever a `sandbox_uid` is sent. A non-Datalayer identifier —
+ * Daytona, E2B and Modal name their own sandboxes — passes through: there is
+ * no ULID to check it against, and inventing one would be worse.
+ */
+export function assertSandboxUid(value) {
+    if (value.startsWith(RUNTIME_NAME_PREFIX)) {
+        throw new RuntimeNameNotAUid(value);
+    }
+    return value;
+}
+/**
+ * The Pod name for a sandbox uid, converting on purpose.
+ *
+ * The mirror of {@link sandboxUidFromRuntimeName}, and the direction that was
+ * missing: route parameters and `runtime_name` fields carry the **Pod name**,
+ * so anything addressing `/runtimes/{name}/…` needs one. Without this, a
+ * caller holding only a uid either wrote the prefix itself or — the version
+ * that was here — passed the uid and hoped, which is a `404` from a route
+ * whose parameter looked plausible.
+ *
+ * Idempotent, like the server's `runtime_name()`: a name that has been
+ * through here stays one name rather than growing a second prefix.
+ */
+export function runtimeNameFromSandboxUid(value) {
+    if (!value || value.startsWith(RUNTIME_NAME_PREFIX)) {
+        return value;
+    }
+    return `${RUNTIME_NAME_PREFIX}${value}`;
+}
+/**
+ * The sandbox uid for a Pod name, converting on purpose.
+ *
+ * For the few callers that genuinely only hold the Pod name — a route
+ * parameter, a label read off a Pod. Everywhere else should already have the
+ * uid, and {@link assertSandboxUid} is what says so.
+ */
+export function sandboxUidFromRuntimeName(value) {
+    return value.startsWith(RUNTIME_NAME_PREFIX)
+        ? value.slice(RUNTIME_NAME_PREFIX.length)
+        : value;
+}

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

@@ -0,0 +1,19 @@
+import type { CatalogSource, ContentSourceCreate, ContentSourceUpdate, EffectivePermissions, Sharing, SourceList } from './generated';
+export interface ConditionalCatalogSource {
+    value: CatalogSource;
+    etag: string;
+}
+export declare const listSources: (token: string, options?: {
+    kind?: string;
+    spaceUid?: string;
+    cursor?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<SourceList>;
+export declare const createSource: (token: string, source: ContentSourceCreate, idempotencyKey: string, baseUrl?: string) => Promise<ConditionalCatalogSource>;
+export declare const getSource: (token: string, sourceUid: string, baseUrl?: string) => Promise<ConditionalCatalogSource>;
+export declare const getHomeFolder: (token: string, baseUrl?: string) => Promise<ConditionalCatalogSource>;
+export declare const updateSource: (token: string, sourceUid: string, update: ContentSourceUpdate, etag: string, baseUrl?: string) => Promise<ConditionalCatalogSource>;
+export declare const archiveSource: (token: string, sourceUid: string, etag: string, baseUrl?: string) => Promise<ConditionalCatalogSource>;
+export declare const getSourcePermissions: (token: string, sourceUid: string, baseUrl?: string) => Promise<EffectivePermissions>;
+export declare const getSourceSharing: (token: string, sourceUid: string, baseUrl?: string) => Promise<Sharing>;
+export declare const replaceSourceSharing: (token: string, sourceUid: string, sharing: Sharing, etag: string, baseUrl?: string) => Promise<ConditionalCatalogSource>;