@beam-network/sdk 0.2.9 → 0.2.11

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, TransferCancelResponse, TransferCreateResponse, TransferPrepareResponse, TransferStatusInfo } from "./models.js";
+import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo } from "./models.js";
 export declare const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
 export declare class BeamApiError extends Error {
     readonly status: number;
@@ -15,12 +15,23 @@ export declare class BeamClient {
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
     distributeTransfer(transferId: string): Promise<DistributeResponse>;
     cancelTransfer(transferId: string): Promise<TransferCancelResponse>;
+    planTransfer(input: {
+        sources: PreparedHttpSource[];
+        destinations: PreparedDestination[];
+        name?: string;
+        testMode?: boolean;
+        experimental?: boolean;
+        urlsExpiresAt?: string;
+        signedUrlFlow?: SignedUrlFlow;
+    }): Promise<TransferPlanResponse>;
     prepareTransfer(input: {
         sources: PreparedHttpSource[];
         destinations: PreparedDestination[];
         name?: string;
         testMode?: boolean;
+        experimental?: boolean;
         urlsExpiresAt?: string;
+        signedUrlFlow?: SignedUrlFlow;
     }): Promise<TransferPrepareResponse>;
     attachSignedUrls(transferId: string, input: {
         chunkRoutes: SignedChunkRoute[];

package/dist/client.js

@@ -1,4 +1,4 @@
-import { abortMultipartUpload, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signUploadPartCopy } from "./provider-signing.js";
+import { abortMultipartUpload, computeChunksContentMd5, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, isS3CompatibleProvider, listPartsPageMarker, listPartsVerifyMarker, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signUploadPartCopy } from "./provider-signing.js";
 export const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
 export class BeamApiError extends Error {
     status;
@@ -36,7 +36,9 @@ export class BeamClient {
             chunk_hashes: input.chunkHashes,
             callbacks: input.callbacks,
             test_mode: input.testMode || undefined,
-            progressive_mode: input.progressiveMode || undefined
+            experimental: input.experimental || undefined,
+            progressive_mode: input.progressiveMode || undefined,
+            signed_url_flow: input.signedUrlFlow
         });
         return this.request("POST", "/transfers/create", body);
     }
@@ -57,13 +59,26 @@ export class BeamClient {
         validateId(transferId, "transferId");
         return this.request("DELETE", `/transfers/${encodeURIComponent(transferId)}`);
     }
+    planTransfer(input) {
+        return this.request("POST", "/transfers/plan", compact({
+            sources: input.sources,
+            destinations: input.destinations,
+            name: input.name,
+            test_mode: input.testMode || undefined,
+            experimental: input.experimental || undefined,
+            urls_expires_at: input.urlsExpiresAt,
+            signed_url_flow: input.signedUrlFlow
+        }));
+    }
     prepareTransfer(input) {
         return this.request("POST", "/transfers/prepare", compact({
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
             test_mode: input.testMode || undefined,
-            urls_expires_at: input.urlsExpiresAt
+            experimental: input.experimental || undefined,
+            urls_expires_at: input.urlsExpiresAt,
+            signed_url_flow: input.signedUrlFlow
         }));
     }
     attachSignedUrls(transferId, input) {
@@ -83,7 +98,9 @@ export class BeamClient {
             sources: preparedSources,
             destinations: preparedDestinations,
             name: input.name,
-            testMode: input.testMode
+            testMode: input.testMode,
+            experimental: input.experimental,
+            signedUrlFlow: input.signedUrlFlow
         });
         if (!prepared.success) {
             return prepared;
@@ -92,12 +109,48 @@ export class BeamClient {
         await input.throwIfCancelled?.(prepared.transfer_id);
         const destinationsById = new Map();
         preparedDestinations.forEach((preparedDestination, index) => {
-            destinationsById.set(preparedDestination.destination_id, input.destinations[index]);
+            const destination = input.destinations[index];
+            if (!destination) {
+                throw new Error(`missing provider destination config for prepared destination ${preparedDestination.destination_id}`);
+            }
+            destinationsById.set(preparedDestination.destination_id, destination);
         });
         const sourcesById = new Map();
         preparedSources.forEach((preparedSource, index) => {
-            sourcesById.set(preparedSource.source_id, input.sources[index]);
+            const source = input.sources[index];
+            if (!source) {
+                throw new Error(`missing provider source config for prepared source ${preparedSource.source_id}`);
+            }
+            sourcesById.set(preparedSource.source_id, source);
+        });
+        const signedUrlFlow = prepared.signed_url_flow ?? input.signedUrlFlow ?? "signed_url_v1";
+        const checksumCache = new ChunkChecksumCache({
+            concurrency: input.checksumReadConcurrency ?? 8,
+            expiresIn,
+            fetchImpl: this.fetchImpl,
+            provider: input.checksumProvider,
+            groupSizeBytes: input.checksumGroupSizeBytes ?? 256 * 1024 * 1024,
+            onEvent: input.onChecksumEvent
         });
+        if (signedUrlFlow === "signed_url_v1") {
+            const chunksBySource = new Map();
+            for (const chunk of prepared.chunk_plan) {
+                const needsChecksum = chunk.destinations.some((target) => {
+                    const destination = destinationsById.get(target.destination_id);
+                    return destination ? isS3CompatibleProvider(destination) : false;
+                });
+                if (!needsChecksum)
+                    continue;
+                const chunks = chunksBySource.get(chunk.source_id) ?? [];
+                chunks.push(chunk);
+                chunksBySource.set(chunk.source_id, chunks);
+            }
+            for (const [sourceId, chunks] of chunksBySource) {
+                const source = sourcesById.get(sourceId);
+                if (source)
+                    checksumCache.preloadMany(source, chunks);
+            }
+        }
         const routes = [];
         const multipartUploads = new Map();
         try {
@@ -161,7 +214,9 @@ export class BeamClient {
                         finalObjectKey,
                         partNumber: typeof metadata.part_number === "number"
                             ? metadata.part_number
-                            : chunk.source_chunk_index + 1
+                            : chunk.source_chunk_index + 1,
+                        signedUrlFlow,
+                        checksumCache
                     }));
                 }
             }
@@ -207,6 +262,32 @@ export class BeamClient {
         if (!input.target.object_key) {
             throw new Error("destination signing target is missing object_key");
         }
+        if (input.signedUrlFlow === "signed_url_v1") {
+            const contentMd5 = await input.checksumCache.get(input.source, input.chunk);
+            const partVerifyUrl = await signListMultipartUpload(input.destination, input.finalObjectKey, input.upload.uploadId, input.expiresIn, { maxParts: 1, partNumberMarker: listPartsVerifyMarker(input.partNumber) });
+            const listPageUrl = await signListMultipartUpload(input.destination, input.finalObjectKey, input.upload.uploadId, input.expiresIn, { maxParts: 1000, partNumberMarker: listPartsPageMarker(input.partNumber) });
+            return signDestinationRoute({
+                chunk: input.chunk,
+                target: input.target,
+                source: input.source,
+                destination: input.destination,
+                expiresIn: input.expiresIn,
+                uploadId: input.upload.uploadId,
+                partNumber: input.partNumber,
+                multipartObjectKey: input.finalObjectKey,
+                completeUrl: input.upload.completeUrl,
+                abortUrl: input.upload.abortUrl,
+                listUrl: input.upload.listUrl,
+                partVerifyUrl,
+                listPageUrl,
+                contentMd5,
+                transferId: input.transferId,
+                multipartGroupId: input.upload.multipartGroupId,
+                multipartCreatedAt: input.upload.multipartCreatedAt,
+                commitMethod: "upload_part",
+                fetchImpl: this.fetchImpl
+            });
+        }
         const stagingObjectKey = buildStagingObjectKey({
             finalObjectKey: input.finalObjectKey,
             transferId: input.transferId,
@@ -292,6 +373,159 @@ export class BeamClient {
         return (text ? JSON.parse(text) : {});
     }
 }
+class ChunkChecksumCache {
+    options;
+    queue = [];
+    cache = new Map();
+    active = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    preloadMany(source, chunks) {
+        const pending = this.uniqueChunks(chunks).filter((chunk) => !this.cache.has(this.key(chunk)));
+        for (const chunk of pending) {
+            this.cache.set(this.key(chunk), deferredChecksum());
+        }
+        for (const group of this.groupChunks(pending)) {
+            void this.run(() => this.fillGroup(source, group)).catch(() => undefined);
+        }
+    }
+    get(source, chunk) {
+        const key = this.key(chunk);
+        let existing = this.cache.get(key);
+        if (!existing) {
+            existing = deferredChecksum();
+            this.cache.set(key, existing);
+            void this.run(() => this.fillGroup(source, [chunk])).catch(() => undefined);
+        }
+        return existing.promise;
+    }
+    async fillGroup(source, chunks) {
+        const unresolved = new Set(chunks.map((chunk) => this.key(chunk)));
+        try {
+            const misses = [];
+            for (const chunk of chunks) {
+                const key = this.key(chunk);
+                const deferred = this.cache.get(key);
+                if (!deferred)
+                    continue;
+                const cached = await this.options.provider?.getContentMd5({ source, chunk, algorithm: "content-md5" }).catch(() => undefined);
+                if (cached) {
+                    this.emit({ event: "checksum_cache_hit", sourceId: chunk.source_id, sourceChunkIndex: chunk.source_chunk_index, bytes: chunk.chunk_size });
+                    deferred.resolve(cached);
+                    unresolved.delete(key);
+                }
+                else {
+                    this.emit({ event: "checksum_cache_miss", sourceId: chunk.source_id, sourceChunkIndex: chunk.source_chunk_index, bytes: chunk.chunk_size });
+                    misses.push(chunk);
+                }
+            }
+            if (!misses.length)
+                return;
+            const startedAt = Date.now();
+            const checksums = await computeChunksContentMd5({
+                source,
+                chunks: misses,
+                expiresIn: this.options.expiresIn,
+                fetchImpl: this.options.fetchImpl,
+                groupSizeBytes: this.options.groupSizeBytes
+            });
+            for (const chunk of misses) {
+                const checksum = checksums.get(chunk.source_chunk_index);
+                if (!checksum)
+                    throw new Error(`checksum missing for source chunk ${chunk.source_chunk_index}`);
+                await this.options.provider?.setContentMd5?.({ source, chunk, algorithm: "content-md5", contentMd5: checksum });
+                const deferred = this.cache.get(this.key(chunk));
+                deferred?.resolve(checksum);
+                unresolved.delete(this.key(chunk));
+                this.emit({ event: "checksum_cold_chunk_cached", sourceId: chunk.source_id, sourceChunkIndex: chunk.source_chunk_index, bytes: chunk.chunk_size });
+            }
+            this.emit({
+                event: "checksum_cold_group_completed",
+                sourceId: misses[0]?.source_id ?? source.id ?? "source",
+                chunkCount: misses.length,
+                bytes: misses.reduce((sum, chunk) => sum + chunk.chunk_size, 0),
+                durationMs: Date.now() - startedAt
+            });
+        }
+        catch (error) {
+            for (const key of unresolved) {
+                this.cache.get(key)?.reject(error);
+            }
+            throw error;
+        }
+    }
+    uniqueChunks(chunks) {
+        const seen = new Set();
+        const output = [];
+        for (const chunk of chunks) {
+            const key = this.key(chunk);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            output.push(chunk);
+        }
+        return output.sort((a, b) => a.source_offset - b.source_offset || a.source_chunk_index - b.source_chunk_index);
+    }
+    groupChunks(chunks) {
+        const groups = [];
+        let current = [];
+        let groupStart = 0;
+        let groupEnd = 0;
+        const maxBytes = Math.max(1, Math.floor(this.options.groupSizeBytes));
+        for (const chunk of chunks) {
+            const chunkStart = chunk.source_offset;
+            const chunkEnd = chunk.source_offset + chunk.chunk_size;
+            const startsNewGroup = current.length === 0 || chunkStart !== groupEnd || chunkEnd - groupStart > maxBytes;
+            if (startsNewGroup) {
+                if (current.length)
+                    groups.push(current);
+                current = [chunk];
+                groupStart = chunkStart;
+                groupEnd = chunkEnd;
+            }
+            else {
+                current.push(chunk);
+                groupEnd = chunkEnd;
+            }
+        }
+        if (current.length)
+            groups.push(current);
+        return groups;
+    }
+    key(chunk) {
+        return `${chunk.source_id}:${chunk.source_chunk_index}`;
+    }
+    run(task) {
+        return new Promise((resolve, reject) => {
+            const start = () => {
+                this.active += 1;
+                task().then(resolve, reject).finally(() => {
+                    this.active -= 1;
+                    this.queue.shift()?.();
+                });
+            };
+            if (this.active < Math.max(1, this.options.concurrency))
+                start();
+            else
+                this.queue.push(start);
+        });
+    }
+    emit(event) {
+        if (!this.options.onEvent)
+            return;
+        void Promise.resolve(this.options.onEvent(event)).catch(() => undefined);
+    }
+}
+function deferredChecksum() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
 export function calculateOptimalChunkSize(totalSize) {
     const mb = 1024 * 1024;
     const gb = 1024 * mb;

package/dist/models.d.ts

@@ -1,3 +1,4 @@
+export type SignedUrlFlow = "signed_url_v1" | "signed_url_v2";
 export interface BeamClientOptions {
     apiKey?: string;
     baseUrl?: string;
@@ -43,7 +44,9 @@ export interface TransferCreateRequest {
     chunk_hashes?: string[];
     callbacks?: CallbackConfig[];
     test_mode?: boolean;
+    experimental?: boolean;
     progressive_mode?: boolean;
+    signed_url_flow?: SignedUrlFlow;
 }
 export interface RawTransferCreateInput {
     sources: SourceConfig[];
@@ -58,11 +61,17 @@ export interface RawTransferCreateInput {
      * Maps to BeamCore test_mode.
      */
     testMode?: boolean;
+    /**
+     * Experimental transfers keep positive evidence but exclude failures and overseer interventions from PRISM.
+     */
+    experimental?: boolean;
     progressiveMode?: boolean;
+    signedUrlFlow?: SignedUrlFlow;
 }
 export interface TransferCreateResponse {
     success: boolean;
     transfer_id: string;
+    experimental?: boolean;
     total_chunks: number;
     total_sources: number;
     total_destinations: number;
@@ -106,6 +115,7 @@ export interface TransferStatusInfo {
     transfer_id: string;
     status: string;
     error_message: string | null;
+    experimental?: boolean;
     started_at: string | null;
     completed_at: string | null;
 }
@@ -154,6 +164,26 @@ export interface HippiusProviderConfig {
 }
 export type ProviderConfig = S3ProviderConfig | R2ProviderConfig | S3CompatibleProviderConfig | HippiusProviderConfig;
 export type ProviderSourceConfig = ProviderConfig;
+export interface ChunkChecksumProviderGetInput {
+    source: ProviderSourceConfig;
+    chunk: ChunkSigningPlanItem;
+    algorithm: "content-md5";
+}
+export interface ChunkChecksumProviderSetInput extends ChunkChecksumProviderGetInput {
+    contentMd5: string;
+}
+export interface ChunkChecksumProvider {
+    getContentMd5(input: ChunkChecksumProviderGetInput): Promise<string | null | undefined>;
+    setContentMd5?(input: ChunkChecksumProviderSetInput): Promise<void>;
+}
+export interface ChunkChecksumEvent {
+    event: "checksum_cache_hit" | "checksum_cache_miss" | "checksum_cold_chunk_cached" | "checksum_cold_group_completed";
+    sourceId: string;
+    sourceChunkIndex?: number;
+    chunkCount?: number;
+    bytes?: number;
+    durationMs?: number;
+}
 export type ProviderDestinationConfig = ProviderConfig;
 export type S3ProviderConfigInput = Omit<S3ProviderConfig, "provider">;
 export type R2ProviderConfigInput = Omit<R2ProviderConfig, "provider">;
@@ -179,6 +209,10 @@ export interface ProviderTransferCreateInput {
      * Maps to BeamCore test_mode.
      */
     testMode?: boolean;
+    /**
+     * Experimental transfers keep positive evidence but exclude failures and overseer interventions from PRISM.
+     */
+    experimental?: boolean;
     expiresIn?: number;
     /**
      * Defaults to true. Set to false to only prepare and attach signed URLs.
@@ -186,6 +220,11 @@ export interface ProviderTransferCreateInput {
     distribute?: boolean;
     onPrepared?: (prepared: TransferPrepareResponse) => void | Promise<void>;
     throwIfCancelled?: (transferId: string) => void | Promise<void>;
+    signedUrlFlow?: SignedUrlFlow;
+    checksumProvider?: ChunkChecksumProvider;
+    checksumReadConcurrency?: number;
+    checksumGroupSizeBytes?: number;
+    onChecksumEvent?: (event: ChunkChecksumEvent) => void | Promise<void>;
 }
 export interface PreparedHttpSource {
     source_id: string;
@@ -230,13 +269,28 @@ export interface SignedChunkRoute {
     chunk_size: number;
     expires_at?: string;
     headers?: Record<string, string>;
+    dest_headers?: Record<string, string>;
     metadata?: Record<string, unknown>;
 }
+export interface TransferPlanResponse {
+    success: boolean;
+    chunk_size?: number;
+    total_size?: number;
+    total_sources?: number;
+    total_destinations?: number;
+    logical_chunks?: number;
+    total_chunks?: number;
+    chunk_plan: ChunkSigningPlanItem[];
+    signed_url_flow?: SignedUrlFlow;
+    error?: string;
+    message?: string;
+}
 export interface TransferPrepareResponse {
     success: boolean;
     transfer_id: string;
     transfer_key?: string;
     test_mode?: boolean;
+    experimental?: boolean;
     chunk_size?: number;
     total_size?: number;
     total_sources?: number;
@@ -244,6 +298,7 @@ export interface TransferPrepareResponse {
     logical_chunks?: number;
     total_chunks?: number;
     chunk_plan: ChunkSigningPlanItem[];
+    signed_url_flow?: SignedUrlFlow;
     error?: string;
     message?: string;
 }

package/dist/provider-signing.d.ts

@@ -13,7 +13,12 @@ export declare function prepareProviderDestination(destination: ProviderDestinat
 export declare function createMultipartUpload(destination: ProviderDestinationConfig, objectKey: string): Promise<string>;
 export declare function signCompleteMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number): Promise<string>;
 export declare function signAbortMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number): Promise<string>;
-export declare function signListMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number): Promise<string>;
+export declare function signListMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number, options?: {
+    maxParts?: number;
+    partNumberMarker?: number;
+}): Promise<string>;
+export declare function listPartsPageMarker(partNumber: number, pageSize?: number): number | undefined;
+export declare function listPartsVerifyMarker(partNumber: number): number | undefined;
 export declare function signUploadPartCopy(destination: ProviderDestinationConfig, finalObjectKey: string, stagingObjectKey: string, uploadId: string, partNumber: number, expiresIn: number, copySourceRange?: string): Promise<{
     copyUrl: string;
     copySource: string;
@@ -35,7 +40,10 @@ export declare function signDestinationRoute(input: {
     transferId?: string;
     multipartGroupId?: string;
     multipartCreatedAt?: string;
-    commitMethod?: "upload_part_copy";
+    commitMethod?: "upload_part" | "upload_part_copy";
+    contentMd5?: string;
+    partVerifyUrl?: string;
+    listPageUrl?: string;
     stagingObjectKey?: string;
     copyUrl?: string;
     copySource?: string;
@@ -43,6 +51,19 @@ export declare function signDestinationRoute(input: {
     deleteUrl?: string;
     fetchImpl?: typeof fetch;
 }): Promise<SignedChunkRoute>;
+export declare function computeChunksContentMd5(input: {
+    source: ProviderSourceConfig;
+    chunks: ChunkSigningPlanItem[];
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+    groupSizeBytes?: number;
+}): Promise<Map<number, string>>;
+export declare function computeChunkContentMd5(input: {
+    source: ProviderSourceConfig;
+    chunk: ChunkSigningPlanItem;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
 export declare function isS3CompatibleProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is AnyS3CompatibleProviderConfig;
 export declare function s3CompatibleEndpoint(source: AnyS3CompatibleProviderConfig): string | undefined;
 export declare function s3CompatibleRegion(source: AnyS3CompatibleProviderConfig): string;

package/dist/provider-signing.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListPartsCommand, PutObjectCommand, S3Client, UploadPartCopyCommand, UploadPartCommand } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 export function nowIso() {
@@ -22,7 +23,13 @@ export async function prepareProviderSource(source, options = {}) {
             size: Number(head.ContentLength ?? 0),
             filename: filename(source.key),
             expires_at: expiresAtIso(expiresIn),
-            metadata: s3CompatibleMetadata(source, endpoint)
+            metadata: {
+                ...s3CompatibleMetadata(source, endpoint),
+                content_length: Number(head.ContentLength ?? 0),
+                ...(head.ETag ? { etag: head.ETag } : {}),
+                ...(head.LastModified ? { last_modified: head.LastModified.toISOString() } : {}),
+                ...(head.VersionId ? { version_id: head.VersionId } : {})
+            }
         };
     }
     if (isHippiusProvider(source)) {
@@ -96,13 +103,26 @@ export async function signAbortMultipartUpload(destination, objectKey, uploadId,
     }
     throw new Error(`multipart abort is not supported for ${destination.provider}`);
 }
-export async function signListMultipartUpload(destination, objectKey, uploadId, expiresIn) {
+export async function signListMultipartUpload(destination, objectKey, uploadId, expiresIn, options = {}) {
     if (isS3CompatibleProvider(destination)) {
         const client = createS3CompatibleClient(destination);
-        return getSignedUrl(client, new ListPartsCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }), { expiresIn });
+        return getSignedUrl(client, new ListPartsCommand({
+            Bucket: destination.bucket,
+            Key: objectKey,
+            UploadId: uploadId,
+            MaxParts: options.maxParts,
+            PartNumberMarker: options.partNumberMarker === undefined ? undefined : String(options.partNumberMarker)
+        }), { expiresIn });
     }
     throw new Error(`multipart list-parts is not supported for ${destination.provider}`);
 }
+export function listPartsPageMarker(partNumber, pageSize = 1000) {
+    const marker = Math.floor((Math.max(1, partNumber) - 1) / pageSize) * pageSize;
+    return marker > 0 ? marker : undefined;
+}
+export function listPartsVerifyMarker(partNumber) {
+    return partNumber > 1 ? partNumber - 1 : undefined;
+}
 export async function signUploadPartCopy(destination, finalObjectKey, stagingObjectKey, uploadId, partNumber, expiresIn, copySourceRange) {
     if (isS3CompatibleProvider(destination)) {
         const client = createS3CompatibleClient(destination);
@@ -163,7 +183,8 @@ export async function signDestinationRoute(input) {
         uploadId: input.uploadId,
         partNumber: input.partNumber,
         useStagingPut: input.commitMethod === "upload_part_copy",
-        fetchImpl: input.fetchImpl
+        fetchImpl: input.fetchImpl,
+        contentMd5: input.contentMd5
     });
     const sourceRoute = await signSourceRoute({
         source: input.source,
@@ -182,6 +203,7 @@ export async function signDestinationRoute(input) {
         chunk_size: input.chunk.chunk_size,
         expires_at: expiresAtIso(input.expiresIn),
         headers: sourceRoute.headers,
+        ...(input.contentMd5 ? { dest_headers: { "Content-MD5": input.contentMd5 } } : {}),
         metadata: {
             ...(input.target.metadata ?? {}),
             ...(input.transferId ? { transfer_id: input.transferId } : {}),
@@ -195,6 +217,9 @@ export async function signDestinationRoute(input) {
             ...(input.deleteUrl ? { delete_url: input.deleteUrl } : {}),
             ...(input.uploadId ? { upload_id: input.uploadId } : {}),
             ...(input.partNumber ? { part_number: input.partNumber } : {}),
+            ...(input.contentMd5 ? { checksum_algorithm: "content-md5", checksum_value: input.contentMd5 } : {}),
+            ...(input.partVerifyUrl ? { part_verify_url: input.partVerifyUrl } : {}),
+            ...(input.listPageUrl ? { list_page_url: input.listPageUrl } : {}),
             ...(input.completeUrl ? { complete_url: input.completeUrl } : {}),
             ...(input.abortUrl ? { abort_url: input.abortUrl } : {}),
             ...(input.listUrl ? { list_url: input.listUrl } : {})
@@ -202,8 +227,11 @@ export async function signDestinationRoute(input) {
     };
 }
 function rangeHeaderForChunk(chunk) {
-    const start = Math.max(0, Math.floor(chunk.source_offset));
-    const size = Math.max(1, Math.floor(chunk.chunk_size));
+    return rangeHeaderForRange(chunk.source_offset, chunk.chunk_size);
+}
+function rangeHeaderForRange(sourceOffset, chunkSize) {
+    const start = Math.max(0, Math.floor(sourceOffset));
+    const size = Math.max(1, Math.floor(chunkSize));
     return `bytes=${start}-${start + size - 1}`;
 }
 async function signSourceRoute(input) {
@@ -230,6 +258,27 @@ async function signSourceRoute(input) {
     }
     return unsupportedProviderConfig(input.source);
 }
+async function signSourceRangeRoute(input) {
+    const range = rangeHeaderForRange(input.sourceOffset, input.chunkSize);
+    if (isS3CompatibleProvider(input.source)) {
+        const client = createS3CompatibleClient(input.source);
+        return {
+            url: await getSignedUrl(client, new GetObjectCommand({
+                Bucket: input.source.bucket,
+                Key: input.source.key,
+                Range: range
+            }), { expiresIn: input.expiresIn }),
+            headers: { Range: range }
+        };
+    }
+    if (isHippiusProvider(input.source)) {
+        return {
+            url: await hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.source.base_url ?? "https://api.hippius.com", input.source.api_token, input.source.bucket, input.source.key, "get", input.expiresIn),
+            headers: { Range: range }
+        };
+    }
+    return { url: input.fallbackUrl, headers: { Range: range } };
+}
 async function signDestinationUrl(input) {
     if (isS3CompatibleProvider(input.destination)) {
         const client = createS3CompatibleClient(input.destination);
@@ -238,7 +287,8 @@ async function signDestinationUrl(input) {
                 Bucket: input.destination.bucket,
                 Key: input.uploadPartObjectKey,
                 UploadId: input.uploadId,
-                PartNumber: input.partNumber
+                PartNumber: input.partNumber,
+                ContentMD5: input.contentMd5
             }), { expiresIn: input.expiresIn });
         }
         return getSignedUrl(client, new PutObjectCommand({ Bucket: input.destination.bucket, Key: input.objectKey }), { expiresIn: input.expiresIn });
@@ -248,8 +298,168 @@ async function signDestinationUrl(input) {
     }
     return unsupportedProviderConfig(input.destination);
 }
+export async function computeChunksContentMd5(input) {
+    const output = new Map();
+    const chunks = [...input.chunks].sort((a, b) => a.source_offset - b.source_offset || a.source_chunk_index - b.source_chunk_index);
+    const groups = groupContiguousChunks(chunks, input.groupSizeBytes ?? 256 * 1024 * 1024);
+    for (const group of groups) {
+        const groupOutput = await retryChecksumRead(() => computeChunkGroupContentMd5({
+            source: input.source,
+            chunks: group,
+            expiresIn: input.expiresIn,
+            fetchImpl: input.fetchImpl
+        }));
+        for (const [sourceChunkIndex, checksum] of groupOutput) {
+            output.set(sourceChunkIndex, checksum);
+        }
+    }
+    return output;
+}
+export async function computeChunkContentMd5(input) {
+    const checksums = await computeChunksContentMd5({
+        source: input.source,
+        chunks: [input.chunk],
+        expiresIn: input.expiresIn,
+        fetchImpl: input.fetchImpl,
+        groupSizeBytes: input.chunk.chunk_size
+    });
+    const checksum = checksums.get(input.chunk.source_chunk_index);
+    if (!checksum) {
+        throw new Error(`chunk checksum missing for source chunk ${input.chunk.source_chunk_index}`);
+    }
+    return checksum;
+}
+function groupContiguousChunks(chunks, maxGroupSizeBytes) {
+    const groups = [];
+    let current = [];
+    let groupStart = 0;
+    let groupEnd = 0;
+    const maxBytes = Math.max(1, Math.floor(maxGroupSizeBytes));
+    for (const chunk of chunks) {
+        const chunkStart = Math.max(0, Math.floor(chunk.source_offset));
+        const chunkEnd = chunkStart + Math.max(1, Math.floor(chunk.chunk_size));
+        const startsNewGroup = current.length === 0 ||
+            chunkStart !== groupEnd ||
+            chunkEnd - groupStart > maxBytes;
+        if (startsNewGroup) {
+            if (current.length)
+                groups.push(current);
+            current = [chunk];
+            groupStart = chunkStart;
+            groupEnd = chunkEnd;
+            continue;
+        }
+        current.push(chunk);
+        groupEnd = chunkEnd;
+    }
+    if (current.length)
+        groups.push(current);
+    return groups;
+}
+async function computeChunkGroupContentMd5(input) {
+    if (!input.chunks.length)
+        return new Map();
+    const chunks = [...input.chunks].sort((a, b) => a.source_offset - b.source_offset || a.source_chunk_index - b.source_chunk_index);
+    const first = chunks[0];
+    const last = chunks[chunks.length - 1];
+    const sourceOffset = first.source_offset;
+    const totalSize = last.source_offset + last.chunk_size - sourceOffset;
+    const sourceRoute = await signSourceRangeRoute({
+        source: input.source,
+        fallbackUrl: first.source_url,
+        sourceOffset,
+        chunkSize: totalSize,
+        expiresIn: input.expiresIn,
+        fetchImpl: input.fetchImpl
+    });
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(sourceRoute.url, { method: "GET", headers: sourceRoute.headers });
+    if (!response.ok) {
+        const message = `chunk checksum fetch failed with ${response.status}: ${await response.text()}`;
+        throw Object.assign(new Error(message), { status: response.status });
+    }
+    const output = new Map();
+    let chunkIndex = 0;
+    let bytesInChunk = 0;
+    let totalRead = 0;
+    let hash = createHash("md5");
+    const consume = (value) => {
+        let offset = 0;
+        while (offset < value.byteLength) {
+            const chunk = chunks[chunkIndex];
+            if (!chunk) {
+                throw new Error(`chunk checksum fetch size mismatch: read more than ${totalSize} bytes`);
+            }
+            const remainingInChunk = chunk.chunk_size - bytesInChunk;
+            const take = Math.min(remainingInChunk, value.byteLength - offset);
+            hash.update(value.subarray(offset, offset + take));
+            offset += take;
+            totalRead += take;
+            bytesInChunk += take;
+            if (bytesInChunk === chunk.chunk_size) {
+                output.set(chunk.source_chunk_index, hash.digest("base64"));
+                chunkIndex += 1;
+                bytesInChunk = 0;
+                hash = createHash("md5");
+            }
+        }
+    };
+    if (response.body) {
+        const reader = response.body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                consume(value);
+        }
+    }
+    else {
+        consume(new Uint8Array(await response.arrayBuffer()));
+    }
+    if (totalRead !== totalSize || output.size !== chunks.length) {
+        throw new Error(`chunk checksum fetch size mismatch: expected ${totalSize}, got ${totalRead}`);
+    }
+    return output;
+}
+async function retryChecksumRead(task) {
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            return await task();
+        }
+        catch (error) {
+            lastError = error;
+            const status = typeof error === "object" && error && "status" in error ? Number(error.status) : undefined;
+            if (status && status >= 400 && status < 500 && status !== 408 && status !== 429)
+                break;
+            if (attempt < 2)
+                await sleep(250 * (attempt + 1));
+        }
+    }
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const s3ClientCache = new Map();
+function s3ClientCacheKey(source, endpoint) {
+    return JSON.stringify({
+        provider: source.provider,
+        endpoint,
+        region: s3CompatibleRegion(source),
+        forcePathStyle: s3CompatibleForcePathStyle(source, endpoint),
+        accessKeyId: source.access_key_id,
+        secretAccessKey: source.secret_access_key,
+        sessionToken: "session_token" in source ? source.session_token : undefined
+    });
+}
 function createS3CompatibleClient(source, endpoint = s3CompatibleEndpoint(source)) {
-    return new S3Client({
+    const cacheKey = s3ClientCacheKey(source, endpoint);
+    const cached = s3ClientCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const client = new S3Client({
         region: s3CompatibleRegion(source),
         endpoint,
         forcePathStyle: s3CompatibleForcePathStyle(source, endpoint),
@@ -259,6 +469,8 @@ function createS3CompatibleClient(source, endpoint = s3CompatibleEndpoint(source
             sessionToken: "session_token" in source ? source.session_token : undefined
         }
     });
+    s3ClientCache.set(cacheKey, client);
+    return client;
 }
 export function isS3CompatibleProvider(config) {
     if (config.provider === "s3" || config.provider === "r2") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beam-network/sdk",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "TypeScript SDK for BEAM transfer creation and management.",
   "type": "module",
   "license": "MIT",