@datalayer/core 1.1.60 → 1.2.10

package/lib/api/contents/sources.js

@@ -0,0 +1,119 @@
+/*
+ * 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 convertRequest = (value) => contentsToSnakeCase(value);
+const convertResponse = (value) => contentsToCamelCase(value);
+const sourceUrl = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources${suffix}`;
+const requiredEtag = (headers) => {
+    const etag = headers.etag ?? headers.ETag;
+    if (!etag) {
+        throw new Error('Contents response did not include an ETag');
+    }
+    return etag;
+};
+export const listSources = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    parameters.set('limit', String(options.limit ?? 50));
+    if (options.kind) {
+        parameters.set('kind', options.kind);
+    }
+    if (options.spaceUid) {
+        parameters.set('space_uid', options.spaceUid);
+    }
+    if (options.cursor) {
+        parameters.set('cursor', options.cursor);
+    }
+    const value = await requestDatalayerAPI({
+        url: `${sourceUrl(baseUrl)}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    });
+    return convertResponse(value);
+};
+export const createSource = async (token, source, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: sourceUrl(baseUrl),
+        method: 'POST',
+        token,
+        headers: { 'Idempotency-Key': idempotencyKey },
+        body: convertRequest(source),
+    });
+    return {
+        value: convertResponse(response.data),
+        etag: requiredEtag(response.headers),
+    };
+};
+export const getSource = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: sourceUrl(baseUrl, `/${encodeURIComponent(sourceUid)}`),
+        method: 'GET',
+        token,
+    });
+    return {
+        value: convertResponse(response.data),
+        etag: requiredEtag(response.headers),
+    };
+};
+export const getHomeFolder = async (token, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: sourceUrl(baseUrl, '/home-folder'),
+        method: 'GET',
+        token,
+    });
+    return {
+        value: convertResponse(response.data),
+        etag: requiredEtag(response.headers),
+    };
+};
+export const updateSource = async (token, sourceUid, update, etag, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: sourceUrl(baseUrl, `/${encodeURIComponent(sourceUid)}`),
+        method: 'PATCH',
+        token,
+        headers: { 'If-Match': etag },
+        body: convertRequest(update),
+    });
+    return {
+        value: convertResponse(response.data),
+        etag: requiredEtag(response.headers),
+    };
+};
+export const archiveSource = async (token, sourceUid, etag, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: sourceUrl(baseUrl, `/${encodeURIComponent(sourceUid)}`),
+        method: 'DELETE',
+        token,
+        headers: { 'If-Match': etag },
+    });
+    return {
+        value: convertResponse(response.data),
+        etag: requiredEtag(response.headers),
+    };
+};
+export const getSourcePermissions = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sourceUrl(baseUrl, `/${encodeURIComponent(sourceUid)}/permissions`),
+    method: 'GET',
+    token,
+}));
+export const getSourceSharing = async (token, sourceUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: sourceUrl(baseUrl, `/${encodeURIComponent(sourceUid)}/sharing`),
+    method: 'GET',
+    token,
+}));
+export const replaceSourceSharing = async (token, sourceUid, sharing, etag, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const response = await requestDatalayerAPIWithResponse({
+        url: sourceUrl(baseUrl, `/${encodeURIComponent(sourceUid)}/sharing`),
+        method: 'PUT',
+        token,
+        headers: { 'If-Match': etag },
+        body: convertRequest(sharing),
+    });
+    return {
+        value: convertResponse(response.data),
+        etag: requiredEtag(response.headers),
+    };
+};

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

@@ -0,0 +1,18 @@
+import type { ConflictResolution, SyncConflictList, SyncCreate, SyncReconcile, SyncReport, SyncSessionList, SyncSessionView } from './generated';
+/** Open a synchronization session; the answer carries the first plan. */
+export declare const createSyncSession: (token: string, request: SyncCreate, idempotencyKey: string, baseUrl?: string) => Promise<SyncSessionView>;
+export declare const getSyncSession: (token: string, sessionUid: string, baseUrl?: string) => Promise<SyncSessionView>;
+export declare const listSyncSessions: (token: string, options?: {
+    active?: boolean;
+    cursor?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<SyncSessionList>;
+/** A fresh local manifest; a fresh plan. A watch pass and a reconnect both. */
+export declare const reconcileSyncSession: (token: string, sessionUid: string, request: SyncReconcile, baseUrl?: string) => Promise<SyncSessionView>;
+export declare const heartbeatSyncSession: (token: string, sessionUid: string, baseUrl?: string) => Promise<SyncSessionView>;
+export declare const reportSyncSession: (token: string, sessionUid: string, request: SyncReport, baseUrl?: string) => Promise<SyncSessionView>;
+export declare const cancelSyncSession: (token: string, sessionUid: string, baseUrl?: string) => Promise<SyncSessionView>;
+export declare const listSyncConflicts: (token: string, sessionUid: string, options?: {
+    openOnly?: boolean;
+}, baseUrl?: string) => Promise<SyncConflictList>;
+export declare const resolveSyncConflict: (token: string, sessionUid: string, conflictUid: string, request: ConflictResolution, baseUrl?: string) => Promise<SyncSessionView>;

package/lib/api/contents/sync.js

@@ -0,0 +1,69 @@
+/*
+ * 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 convertResponse = (value) => contentsToCamelCase(value);
+const convertRequest = (value) => contentsToSnakeCase(value);
+const syncUrl = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/sync${suffix}`;
+/** Open a synchronization session; the answer carries the first plan. */
+export const createSyncSession = async (token, request, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl),
+    method: 'POST',
+    token,
+    headers: { 'Idempotency-Key': idempotencyKey },
+    body: convertRequest(request),
+}));
+export const getSyncSession = async (token, sessionUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}`),
+    method: 'GET',
+    token,
+}));
+export const listSyncSessions = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    parameters.set('active', String(options.active ?? false));
+    parameters.set('limit', String(options.limit ?? 50));
+    if (options.cursor)
+        parameters.set('cursor', options.cursor);
+    return convertResponse(await requestDatalayerAPI({
+        url: `${syncUrl(baseUrl)}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+/** A fresh local manifest; a fresh plan. A watch pass and a reconnect both. */
+export const reconcileSyncSession = async (token, sessionUid, request, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}/reconcile`),
+    method: 'POST',
+    token,
+    body: convertRequest(request),
+}));
+export const heartbeatSyncSession = async (token, sessionUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}/heartbeat`),
+    method: 'POST',
+    token,
+}));
+export const reportSyncSession = async (token, sessionUid, request, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}/report`),
+    method: 'POST',
+    token,
+    body: convertRequest(request),
+}));
+export const cancelSyncSession = async (token, sessionUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}`),
+    method: 'DELETE',
+    token,
+}));
+export const listSyncConflicts = async (token, sessionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}/conflicts?open_only=${String(options.openOnly ?? false)}`),
+    method: 'GET',
+    token,
+}));
+export const resolveSyncConflict = async (token, sessionUid, conflictUid, request, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: syncUrl(baseUrl, `/${encodeURIComponent(sessionUid)}/conflicts/${encodeURIComponent(conflictUid)}/resolve`),
+    method: 'POST',
+    token,
+    body: convertRequest(request),
+}));

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

@@ -0,0 +1,38 @@
+import type { TransferCreate, TransferList, TransferView } from './generated';
+export declare const createTransfer: (token: string, request: TransferCreate, idempotencyKey: string, baseUrl?: string) => Promise<TransferView>;
+export declare const getTransfer: (token: string, transferUid: string, baseUrl?: string) => Promise<TransferView>;
+export declare const listTransfers: (token: string, options?: {
+    active?: boolean;
+    cursor?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<TransferList>;
+export declare const uploadTransferPart: (token: string, transferUid: string, partNumber: number, content: Uint8Array, checksum: string, baseUrl?: string) => Promise<TransferView>;
+export declare const completeTransfer: (token: string, transferUid: string, baseUrl?: string) => Promise<TransferView>;
+export declare const cancelTransfer: (token: string, transferUid: string, baseUrl?: string) => Promise<TransferView>;
+export type DownloadedObject = {
+    data: ArrayBuffer;
+    status: number;
+    headers: Record<string, string>;
+};
+export declare const downloadHomeFolderObject: (token: string, objectUid: string, options?: {
+    versionUid?: string;
+    range?: string;
+}, baseUrl?: string) => Promise<DownloadedObject>;
+export type UploadProgress = {
+    transferUid: string;
+    uploadedBytes: number;
+    totalBytes: number;
+};
+export type UploadOptions = {
+    idempotencyKey: string;
+    mediaType?: string;
+    overwrite?: 'reject' | 'replace' | 'new-version';
+    chunkSize?: number;
+    onProgress?: (progress: UploadProgress) => void;
+};
+/** Create or resume a checksummed multipart upload into the Home Folder and atomically finalize it. */
+export declare const uploadHomeFolderFile: (token: string, path: string, content: Blob | Uint8Array | ArrayBuffer, options: UploadOptions, baseUrl?: string) => Promise<TransferView>;
+/** Capture a file into a Dataset: the same transfer, landing as a version a revision can pin. */
+export declare const uploadDatasetFile: (token: string, datasetUid: string, path: string, content: Blob | Uint8Array | ArrayBuffer, options: UploadOptions, baseUrl?: string) => Promise<TransferView>;
+/** Create or resume a checksummed multipart upload to any destination the service accepts. */
+export declare const uploadFile: (token: string, destinationUri: string, content: Blob | Uint8Array | ArrayBuffer, options: UploadOptions, baseUrl?: string) => Promise<TransferView>;

package/lib/api/contents/transfers.js

@@ -0,0 +1,123 @@
+/*
+ * 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 convertResponse = (value) => contentsToCamelCase(value);
+const transferUrl = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.CONTENTS}/transfers${suffix}`;
+export const createTransfer = async (token, request, idempotencyKey, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: transferUrl(baseUrl),
+    method: 'POST',
+    token,
+    headers: { 'Idempotency-Key': idempotencyKey },
+    body: contentsToSnakeCase(request),
+}));
+export const getTransfer = async (token, transferUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: transferUrl(baseUrl, `/${encodeURIComponent(transferUid)}`),
+    method: 'GET',
+    token,
+}));
+export const listTransfers = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    parameters.set('active', String(options.active ?? false));
+    parameters.set('limit', String(options.limit ?? 50));
+    if (options.cursor)
+        parameters.set('cursor', options.cursor);
+    return convertResponse(await requestDatalayerAPI({
+        url: `${transferUrl(baseUrl)}?${parameters.toString()}`,
+        method: 'GET',
+        token,
+    }));
+};
+export const uploadTransferPart = async (token, transferUid, partNumber, content, checksum, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: transferUrl(baseUrl, `/${encodeURIComponent(transferUid)}/parts/${partNumber}`),
+    method: 'PUT',
+    token,
+    headers: {
+        'Content-Type': 'application/octet-stream',
+        'Content-SHA256': checksum,
+    },
+    body: content,
+}));
+export const completeTransfer = async (token, transferUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: transferUrl(baseUrl, `/${encodeURIComponent(transferUid)}/complete`),
+    method: 'POST',
+    token,
+}));
+export const cancelTransfer = async (token, transferUid, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => convertResponse(await requestDatalayerAPI({
+    url: transferUrl(baseUrl, `/${encodeURIComponent(transferUid)}`),
+    method: 'DELETE',
+    token,
+}));
+export const downloadHomeFolderObject = async (token, objectUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const parameters = new URLSearchParams();
+    if (options.versionUid)
+        parameters.set('version_uid', options.versionUid);
+    const query = parameters.size ? `?${parameters.toString()}` : '';
+    const response = await requestDatalayerAPIWithResponse({
+        url: `${baseUrl}${API_BASE_PATHS.CONTENTS}/sources/home-folder/objects/${encodeURIComponent(objectUid)}/download${query}`,
+        method: 'GET',
+        token,
+        headers: options.range ? { Range: options.range } : {},
+        responseType: 'arraybuffer',
+    });
+    return {
+        data: response.data,
+        status: response.status,
+        headers: response.headers,
+    };
+};
+const bytes = async (content) => {
+    if (content instanceof Uint8Array)
+        return content;
+    if (content instanceof ArrayBuffer)
+        return new Uint8Array(content);
+    return new Uint8Array(await content.arrayBuffer());
+};
+const sha256 = async (content) => {
+    const copy = new Uint8Array(content.byteLength);
+    copy.set(content);
+    const digest = await crypto.subtle.digest('SHA-256', copy.buffer);
+    return Array.from(new Uint8Array(digest), value => value.toString(16).padStart(2, '0')).join('');
+};
+/** Create or resume a checksummed multipart upload into the Home Folder and atomically finalize it. */
+export const uploadHomeFolderFile = async (token, path, content, options, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => uploadFile(token, `home-folder:///${path.replace(/^\/+/, '')}`, content, options, baseUrl);
+/** Capture a file into a Dataset: the same transfer, landing as a version a revision can pin. */
+export const uploadDatasetFile = async (token, datasetUid, path, content, options, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => uploadFile(token, `dataset://${datasetUid}/${path.replace(/^\/+/, '')}`, content, options, baseUrl);
+/** Create or resume a checksummed multipart upload to any destination the service accepts. */
+export const uploadFile = async (token, destinationUri, content, options, baseUrl = DEFAULT_SERVICE_URLS.CONTENTS) => {
+    const payload = await bytes(content);
+    const checksum = await sha256(payload);
+    const transfer = await createTransfer(token, {
+        destinationUri,
+        size: payload.byteLength,
+        checksum,
+        mediaType: options.mediaType ?? 'application/octet-stream',
+        overwrite: options.overwrite ?? 'reject',
+    }, options.idempotencyKey, baseUrl);
+    // Resuming: the parts already verified fix the part size. Cutting the file
+    // differently would number the bytes differently, and a "verified" part
+    // would then be the wrong bytes.
+    const chunkSize = transfer.parts?.length
+        ? transfer.parts[0].size
+        : Math.max(256 * 1024, options.chunkSize ?? 8 * 1024 * 1024);
+    const verified = new Set((transfer.parts ?? []).map(part => part.number));
+    let uploadedBytes = (transfer.parts ?? []).reduce((total, part) => total + part.size, 0);
+    for (let offset = 0, number = 0; offset < payload.byteLength; number += 1) {
+        const end = Math.min(offset + chunkSize, payload.byteLength);
+        const part = payload.slice(offset, end);
+        if (!verified.has(number)) {
+            await uploadTransferPart(token, transfer.uid, number, part, await sha256(part), baseUrl);
+            uploadedBytes += part.byteLength;
+            options.onProgress?.({
+                transferUid: transfer.uid,
+                uploadedBytes,
+                totalBytes: payload.byteLength,
+            });
+        }
+        offset = end;
+    }
+    return completeTransfer(token, transfer.uid, baseUrl);
+};