@beam-network/sdk 0.2.14 → 0.2.16

package/README.md

@@ -91,4 +91,4 @@ Use `S3ProviderConfig` for ordinary AWS S3 if preferred, and keep using
 `S3CompatibleProviderConfig` when a provider needs a custom S3-compatible
 endpoint.
 
-For low-level BeamCore `/transfers/create` calls with raw HTTP-style configs, use `createRawTransfer`.
+For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport still goes through NATS.

package/dist/client.d.ts

@@ -1,15 +1,18 @@
 import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo } from "./models.js";
-export declare const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
+import { BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
+export { BEAM_DEFAULT_NATS_URL };
 export declare class BeamApiError extends Error {
     readonly status: number;
     readonly body: string;
     constructor(message: string, status: number, body: string);
 }
 export declare class BeamClient {
-    readonly baseUrl: string;
     readonly apiKey: string;
+    readonly natsUrl: string;
     private readonly fetchImpl;
+    private readonly control;
     constructor(options?: BeamClientOptions);
+    close(): Promise<void>;
     createRawTransfer(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
     createTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
@@ -45,7 +48,6 @@ export declare class BeamClient {
         timeoutMs?: number;
         pollIntervalMs?: number;
     }): Promise<TransferStatusInfo>;
-    private request;
 }
 export declare function calculateOptimalChunkSize(totalSize: number): number;
 export declare function buildStagingObjectPrefix(input: {

package/dist/client.js

@@ -1,5 +1,6 @@
 import { abortMultipartUpload, computeChunksContentMd5, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, prepareProviderSourceForPlan, isS3CompatibleProvider, listPartsPageMarker, listPartsVerifyMarker, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
-export const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
+import { BeamTransferControl, BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
+export { BEAM_DEFAULT_NATS_URL };
 export class BeamApiError extends Error {
     status;
     body;
@@ -11,26 +12,41 @@ export class BeamApiError extends Error {
     }
 }
 export class BeamClient {
-    baseUrl;
     apiKey;
+    natsUrl;
     fetchImpl;
+    control;
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
         }
-        this.baseUrl = normalizeBaseUrl(resolveBaseUrl(options));
         this.apiKey = options.apiKey;
+        this.natsUrl = options.natsUrl ?? options.natsWsUrl ?? BEAM_DEFAULT_NATS_URL;
+        this.control = new BeamTransferControl({
+            apiKey: this.apiKey,
+            natsUrl: options.natsUrl,
+            natsWsUrl: options.natsWsUrl,
+            environment: options.environment,
+            subjectPrefix: options.transferClientSubjectPrefix,
+            transferRuntimeShardCount: options.transferRuntimeShardCount,
+            requestTimeoutMs: options.requestTimeoutMs,
+            maxPayloadBytes: options.maxPayloadBytes
+        });
         this.fetchImpl = options.fetch ?? globalThis.fetch;
         if (!this.fetchImpl) {
             throw new Error("A fetch implementation is required.");
         }
     }
+    close() {
+        return this.control.close();
+    }
     createRawTransfer(input) {
         const body = compact({
+            transfer_id: newTransferId(),
             sources: input.sources,
             destinations: input.destinations,
             total_size: input.totalSize,
-            chunk_size: input.chunkSize ?? calculateOptimalChunkSize(input.totalSize),
+            chunk_size: input.chunkSize,
             name: input.name,
             merkle_root: input.merkleRoot,
             chunk_hashes: input.chunkHashes,
@@ -40,27 +56,25 @@ export class BeamClient {
             progressive_mode: input.progressiveMode || undefined,
             signed_url_flow: input.signedUrlFlow
         });
-        return this.request("POST", "/transfers/create", body);
+        return this.control.request("transfer.create", body);
     }
     createTransfer(input) {
         return this.prepareProviderTransfer(input);
     }
     transferStatus(transferId) {
         validateId(transferId, "transferId");
-        return this.request("GET", `/transfers/${encodeURIComponent(transferId)}/status`);
+        return this.control.request("transfer.status", { transfer_id: transferId }, transferId);
     }
     distributeTransfer(transferId) {
         validateId(transferId, "transferId");
-        return this.request("POST", "/transfers/distribute", {
-            transfer_id: transferId
-        });
+        return this.control.request("transfer.distribute", { transfer_id: transferId }, transferId);
     }
     cancelTransfer(transferId) {
         validateId(transferId, "transferId");
-        return this.request("DELETE", `/transfers/${encodeURIComponent(transferId)}`);
+        return this.control.request("transfer.cancel", { transfer_id: transferId }, transferId);
     }
     planTransfer(input) {
-        return this.request("POST", "/transfers/plan", compact({
+        return this.control.request("transfer.plan", compact({
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
@@ -71,7 +85,9 @@ export class BeamClient {
         }));
     }
     prepareTransfer(input) {
-        return this.request("POST", "/transfers/prepare", compact({
+        const transferId = newTransferId();
+        return this.control.request("transfer.prepare", compact({
+            transfer_id: transferId,
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
@@ -79,16 +95,33 @@ export class BeamClient {
             experimental: input.experimental || undefined,
             urls_expires_at: input.urlsExpiresAt,
             signed_url_flow: input.signedUrlFlow
-        }));
+        }), transferId);
     }
-    attachSignedUrls(transferId, input) {
+    async attachSignedUrls(transferId, input) {
         validateId(transferId, "transferId");
-        return this.request("POST", "/transfers/attach-signed-urls", compact({
+        const attachmentId = newTransferId();
+        await this.control.request("transfer.attach_signed_urls.begin", compact({
             transfer_id: transferId,
-            chunk_routes: input.chunkRoutes,
-            transfer_key: input.transferKey,
+            attachment_id: attachmentId,
+            total_routes: input.chunkRoutes.length,
             urls_expires_at: input.urlsExpiresAt
-        }));
+        }), transferId);
+        const chunks = this.control.splitRoutesForPayload("transfer.attach_signed_urls.chunk", {
+            transfer_id: transferId,
+            attachment_id: attachmentId
+        }, input.chunkRoutes);
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
+            await this.control.request("transfer.attach_signed_urls.chunk", {
+                transfer_id: transferId,
+                attachment_id: attachmentId,
+                chunk_index: chunkIndex,
+                chunk_routes: chunks[chunkIndex]
+            }, transferId);
+        }
+        return this.control.request("transfer.attach_signed_urls.commit", {
+            transfer_id: transferId,
+            attachment_id: attachmentId
+        }, transferId);
     }
     async prepareProviderTransfer(input) {
         const expiresIn = input.expiresIn ?? 3600;
@@ -108,6 +141,7 @@ export class BeamClient {
             fetchImpl: this.fetchImpl,
             provider: input.checksumProvider,
             groupSizeBytes: input.checksumGroupSizeBytes ?? 256 * 1024 * 1024,
+            readTimeoutMs: input.checksumReadTimeoutMs,
             onEvent: input.onChecksumEvent,
             throwIfCancelled: () => input.throwIfCancelled?.()
         });
@@ -408,27 +442,6 @@ export class BeamClient {
             await sleep(pollIntervalMs);
         }
     }
-    async request(method, path, body) {
-        const headers = {
-            Accept: "application/json",
-            "X-Api-Key": this.apiKey
-        };
-        let payload;
-        if (body !== undefined) {
-            headers["Content-Type"] = "application/json";
-            payload = JSON.stringify(body);
-        }
-        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-            method,
-            headers,
-            body: payload
-        });
-        const text = await response.text();
-        if (!response.ok) {
-            throw new BeamApiError(`BEAM API request failed with ${response.status}`, response.status, text);
-        }
-        return (text ? JSON.parse(text) : {});
-    }
 }
 function checksumChunksBySource(chunkPlan, destinationsById) {
     const chunksBySource = new Map();
@@ -580,7 +593,8 @@ class ChunkChecksumCache {
                 chunks: misses,
                 expiresIn: this.options.expiresIn,
                 fetchImpl: this.options.fetchImpl,
-                groupSizeBytes: this.options.groupSizeBytes
+                groupSizeBytes: this.options.groupSizeBytes,
+                readTimeoutMs: this.options.readTimeoutMs
             });
             for (const chunk of misses) {
                 await this.options.throwIfCancelled?.();
@@ -708,14 +722,11 @@ export function calculateOptimalChunkSize(totalSize) {
     }
     return maxChunk;
 }
-function resolveBaseUrl(options) {
-    if (options.baseUrl) {
-        return options.baseUrl;
-    }
-    return BEAM_DEFAULT_URL;
-}
-function normalizeBaseUrl(value) {
-    return value.replace(/\/+$/, "");
+function newTransferId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.randomUUID)
+        return cryptoApi.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 function compact(input) {
     return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));

package/dist/models.d.ts

@@ -1,7 +1,13 @@
 export type SignedUrlFlow = "signed_url_v1" | "signed_url_v2";
 export interface BeamClientOptions {
     apiKey?: string;
-    baseUrl?: string;
+    natsUrl?: string;
+    natsWsUrl?: string;
+    environment?: string;
+    transferClientSubjectPrefix?: string;
+    transferRuntimeShardCount?: number;
+    requestTimeoutMs?: number;
+    maxPayloadBytes?: number;
     fetch?: typeof fetch;
 }
 export interface SourceConfig {
@@ -71,6 +77,7 @@ export interface RawTransferCreateInput {
 export interface TransferCreateResponse {
     success: boolean;
     transfer_id: string;
+    transfer_key?: string;
     experimental?: boolean;
     total_chunks: number;
     total_sources: number;
@@ -113,11 +120,16 @@ export interface DestinationStatusInfo {
 }
 export interface TransferStatusInfo {
     transfer_id: string;
+    name?: string;
     status: string;
     error_message: string | null;
     experimental?: boolean;
     started_at: string | null;
     completed_at: string | null;
+    total_bytes?: number;
+    total_size?: number;
+    total_chunks?: number;
+    chunks_completed?: number;
 }
 export interface S3ProviderConfig {
     provider: "s3";
@@ -226,6 +238,7 @@ export interface ProviderTransferCreateInput {
     checksumProvider?: ChunkChecksumProvider;
     checksumReadConcurrency?: number;
     checksumGroupSizeBytes?: number;
+    checksumReadTimeoutMs?: number;
     onChecksumEvent?: (event: ChunkChecksumEvent) => void | Promise<void>;
 }
 export interface PlanningHttpSource {

package/dist/nats-control.d.ts

@@ -0,0 +1,36 @@
+export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v1";
+export declare const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
+export declare const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
+export type TransferClientMessageType = "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.attach_signed_urls.begin" | "transfer.attach_signed_urls.chunk" | "transfer.attach_signed_urls.commit" | "transfer.distribute" | "transfer.status" | "transfer.cancel";
+export interface TransferControlOptions {
+    apiKey: string;
+    natsUrl?: string;
+    natsWsUrl?: string;
+    environment?: string;
+    subjectPrefix?: string;
+    transferRuntimeShardCount?: number;
+    requestTimeoutMs?: number;
+    maxPayloadBytes?: number;
+}
+export declare class BeamTransferControl {
+    readonly environment: string;
+    readonly keyPrefix: string;
+    readonly shardCount: number;
+    readonly maxPayloadBytes: number;
+    private readonly subjectPrefix;
+    private readonly requestTimeoutMs;
+    private readonly natsUrl;
+    private readonly apiKey;
+    private nc;
+    private authToken;
+    private authTokenExpiresAt;
+    constructor(options: TransferControlOptions);
+    close(): Promise<void>;
+    request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, transferId?: string): Promise<T>;
+    splitRoutesForPayload(messageType: TransferClientMessageType, basePayload: Record<string, unknown>, routes: unknown[]): unknown[][];
+    private connection;
+    private resolveAuthToken;
+    private authSubject;
+    private requestSubject;
+}
+export declare function transferShardId(transferId: string, shardCount: number): number;

package/dist/nats-control.js

@@ -0,0 +1,162 @@
+import { encode, decode } from "@msgpack/msgpack";
+import { connect } from "nats";
+export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v1";
+export const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
+export const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
+export class BeamTransferControl {
+    environment;
+    keyPrefix;
+    shardCount;
+    maxPayloadBytes;
+    subjectPrefix;
+    requestTimeoutMs;
+    natsUrl;
+    apiKey;
+    nc = null;
+    authToken = null;
+    authTokenExpiresAt = 0;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.keyPrefix = options.apiKey.slice(0, 12);
+        this.environment = options.environment ?? "prod";
+        this.subjectPrefix = normalizeSubjectPrefix(options.subjectPrefix ?? "beam.transfer.client");
+        this.shardCount = options.transferRuntimeShardCount ?? 1;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.maxPayloadBytes = options.maxPayloadBytes ?? 6 * 1024 * 1024;
+        this.natsUrl = options.natsUrl ?? options.natsWsUrl ?? BEAM_DEFAULT_NATS_URL;
+        if (/^https?:\/\//i.test(this.natsUrl) || /^wss?:\/\//i.test(this.natsUrl) && !options.natsWsUrl) {
+            throw new Error("Beam SDK lifecycle endpoint must be nats://, tls://, or configured as natsWsUrl.");
+        }
+        if (!Number.isInteger(this.shardCount) || this.shardCount < 1) {
+            throw new Error("transferRuntimeShardCount must be a positive integer.");
+        }
+    }
+    async close() {
+        if (!this.nc)
+            return;
+        await this.nc.drain();
+        this.nc = null;
+    }
+    async request(messageType, payload, transferId) {
+        const nc = await this.connection();
+        const authToken = await this.resolveAuthToken();
+        const shardId = transferId ? transferShardId(transferId, this.shardCount) : 0;
+        const requestId = randomId();
+        const envelope = {
+            message_id: `${TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION}:${this.environment}:${this.keyPrefix}:${messageType}:${requestId}`,
+            schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+            environment: this.environment,
+            key_prefix: this.keyPrefix,
+            shard_id: shardId,
+            message_type: messageType,
+            request_id: requestId,
+            auth_token: authToken,
+            occurred_at: new Date().toISOString(),
+            producer: "sdk",
+            payload
+        };
+        const bytes = encode(envelope);
+        if (bytes.byteLength > this.maxPayloadBytes) {
+            throw new Error(`NATS lifecycle request is ${bytes.byteLength} bytes, above maxPayloadBytes=${this.maxPayloadBytes}`);
+        }
+        const subject = this.requestSubject(messageType, shardId);
+        const response = await nc.request(subject, bytes, { timeout: this.requestTimeoutMs });
+        const decoded = decode(response.data);
+        if (!decoded.ok) {
+            const body = JSON.stringify(decoded.error ?? {});
+            throw new Error(`Beam lifecycle request failed with ${decoded.status}: ${body}`);
+        }
+        return (decoded.payload ?? {});
+    }
+    splitRoutesForPayload(messageType, basePayload, routes) {
+        const chunks = [];
+        let current = [];
+        for (const route of routes) {
+            const candidate = [...current, route];
+            const encoded = encode({
+                schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+                environment: this.environment,
+                key_prefix: this.keyPrefix,
+                shard_id: 0,
+                message_type: messageType,
+                request_id: randomId(),
+                auth_token: "x".repeat(512),
+                occurred_at: new Date().toISOString(),
+                producer: "sdk",
+                payload: { ...basePayload, chunk_routes: candidate }
+            });
+            if (current.length > 0 && encoded.byteLength > this.maxPayloadBytes) {
+                chunks.push(current);
+                current = [route];
+            }
+            else {
+                current = candidate;
+            }
+        }
+        if (current.length > 0)
+            chunks.push(current);
+        return chunks;
+    }
+    async connection() {
+        if (this.nc && !this.nc.isClosed())
+            return this.nc;
+        this.nc = await connect({
+            servers: this.natsUrl,
+            user: this.keyPrefix,
+            pass: this.apiKey,
+            name: `beam-sdk-${this.keyPrefix}`
+        });
+        return this.nc;
+    }
+    async resolveAuthToken() {
+        const now = Math.floor(Date.now() / 1000);
+        if (this.authToken && this.authTokenExpiresAt - 5 > now)
+            return this.authToken;
+        const nc = await this.connection();
+        const response = await nc.request(this.authSubject(), new TextEncoder().encode("{}"), { timeout: this.requestTimeoutMs });
+        const parsed = JSON.parse(new TextDecoder().decode(response.data));
+        if (!parsed.ok || !parsed.token) {
+            throw new Error(`Beam SDK NATS auth resolve failed: ${parsed.error ?? "unknown_error"}`);
+        }
+        const claims = decodeJwtPayload(parsed.token);
+        this.authToken = parsed.token;
+        this.authTokenExpiresAt = claims.exp;
+        return parsed.token;
+    }
+    authSubject() {
+        return `${this.subjectPrefix}.${this.environment}.auth.${this.keyPrefix}.resolve`;
+    }
+    requestSubject(messageType, shardId) {
+        return `${this.subjectPrefix}.${this.environment}.sdk.${this.keyPrefix}.shard.${shardId}.${messageType.replace(/\./g, "_")}`;
+    }
+}
+export function transferShardId(transferId, shardCount) {
+    let hash = 2166136261;
+    for (let i = 0; i < transferId.length; i += 1) {
+        hash ^= transferId.charCodeAt(i);
+        hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    return hash % shardCount;
+}
+function decodeJwtPayload(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2)
+        throw new Error("invalid JWT");
+    return JSON.parse(base64UrlDecode(parts[1]));
+}
+function base64UrlDecode(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(padded, "base64").toString("utf8");
+    return atob(padded);
+}
+function normalizeSubjectPrefix(value) {
+    return value.replace(/^\.+|\.+$/g, "");
+}
+function randomId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.randomUUID)
+        return cryptoApi.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}

package/dist/provider-signing.d.ts

@@ -63,12 +63,14 @@ export declare function computeChunksContentMd5(input: {
     expiresIn: number;
     fetchImpl?: typeof fetch;
     groupSizeBytes?: number;
+    readTimeoutMs?: number;
 }): Promise<Map<number, string>>;
 export declare function computeChunkContentMd5(input: {
     source: ProviderSourceConfig;
     chunk: ChunkSigningPlanItem;
     expiresIn: number;
     fetchImpl?: typeof fetch;
+    readTimeoutMs?: number;
 }): Promise<string>;
 export declare function isS3CompatibleProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is AnyS3CompatibleProviderConfig;
 export declare function s3CompatibleEndpoint(source: AnyS3CompatibleProviderConfig): string | undefined;

package/dist/provider-signing.js

@@ -4,6 +4,7 @@ import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 export function nowIso() {
     return new Date().toISOString();
 }
+const DEFAULT_CHECKSUM_READ_TIMEOUT_MS = 300_000;
 export function expiresAtIso(expiresIn) {
     return new Date(Date.now() + expiresIn * 1000).toISOString();
 }
@@ -347,12 +348,13 @@ export async function computeChunksContentMd5(input) {
     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({
+        const groupOutput = await computeChunkGroupContentMd5Adaptive({
             source: input.source,
             chunks: group,
             expiresIn: input.expiresIn,
-            fetchImpl: input.fetchImpl
-        }));
+            fetchImpl: input.fetchImpl,
+            readTimeoutMs: input.readTimeoutMs
+        });
         for (const [sourceChunkIndex, checksum] of groupOutput) {
             output.set(sourceChunkIndex, checksum);
         }
@@ -365,7 +367,8 @@ export async function computeChunkContentMd5(input) {
         chunks: [input.chunk],
         expiresIn: input.expiresIn,
         fetchImpl: input.fetchImpl,
-        groupSizeBytes: input.chunk.chunk_size
+        groupSizeBytes: input.chunk.chunk_size,
+        readTimeoutMs: input.readTimeoutMs
     });
     const checksum = checksums.get(input.chunk.source_chunk_index);
     if (!checksum) {
@@ -400,6 +403,25 @@ function groupContiguousChunks(chunks, maxGroupSizeBytes) {
         groups.push(current);
     return groups;
 }
+async function computeChunkGroupContentMd5Adaptive(input) {
+    try {
+        return await retryChecksumRead(() => computeChunkGroupContentMd5(input));
+    }
+    catch (error) {
+        if (input.chunks.length <= 1) {
+            throw error;
+        }
+        const midpoint = Math.ceil(input.chunks.length / 2);
+        const output = new Map();
+        for (const chunks of [input.chunks.slice(0, midpoint), input.chunks.slice(midpoint)]) {
+            const partial = await computeChunkGroupContentMd5Adaptive({ ...input, chunks });
+            for (const [sourceChunkIndex, checksum] of partial) {
+                output.set(sourceChunkIndex, checksum);
+            }
+        }
+        return output;
+    }
+}
 async function computeChunkGroupContentMd5(input) {
     if (!input.chunks.length)
         return new Map();
@@ -408,36 +430,73 @@ async function computeChunkGroupContentMd5(input) {
     const last = chunks[chunks.length - 1];
     const sourceOffset = first.source_offset;
     const totalSize = last.source_offset + last.chunk_size - sourceOffset;
-    if (isS3CompatibleProvider(input.source)) {
-        const client = createS3CompatibleClient(input.source);
-        const response = await client.send(new GetObjectCommand({
-            Bucket: input.source.bucket,
-            Key: input.source.key,
-            Range: `bytes=${sourceOffset}-${sourceOffset + totalSize - 1}`
-        }));
-        if (!response.Body) {
-            throw new Error(`chunk checksum read returned no body for ${input.source.bucket}/${input.source.key}`);
+    return withChecksumReadTimeout(input.readTimeoutMs, async (abortSignal) => {
+        if (isS3CompatibleProvider(input.source)) {
+            const client = createS3CompatibleClient(input.source);
+            const response = await client.send(new GetObjectCommand({
+                Bucket: input.source.bucket,
+                Key: input.source.key,
+                Range: `bytes=${sourceOffset}-${sourceOffset + totalSize - 1}`
+            }), abortSignal ? { abortSignal } : undefined);
+            if (!response.Body) {
+                throw new Error(`chunk checksum read returned no body for ${input.source.bucket}/${input.source.key}`);
+            }
+            return hashChunkGroupContentMd5(chunks, totalSize, bodyToAsyncBytes(response.Body));
         }
-        return hashChunkGroupContentMd5(chunks, totalSize, bodyToAsyncBytes(response.Body));
-    }
-    const sourceRoute = await signSourceRangeRoute({
-        source: input.source,
-        fallbackUrl: first.source_url,
-        sourceOffset,
-        chunkSize: totalSize,
-        expiresIn: input.expiresIn,
-        fetchImpl: input.fetchImpl
+        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, signal: abortSignal });
+        if (!response.ok) {
+            const message = `chunk checksum fetch failed with ${response.status}: ${await response.text()}`;
+            throw Object.assign(new Error(message), { status: response.status });
+        }
+        if (response.body) {
+            return hashChunkGroupContentMd5(chunks, totalSize, readableStreamToAsyncBytes(response.body));
+        }
+        return hashChunkGroupContentMd5(chunks, totalSize, [new Uint8Array(await response.arrayBuffer())]);
     });
-    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 });
+}
+function normalizedChecksumReadTimeoutMs(value) {
+    if (value === undefined)
+        return DEFAULT_CHECKSUM_READ_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.floor(value);
+}
+async function withChecksumReadTimeout(readTimeoutMs, task) {
+    const timeoutMs = normalizedChecksumReadTimeoutMs(readTimeoutMs);
+    if (timeoutMs <= 0) {
+        return task(undefined);
+    }
+    const controller = new AbortController();
+    const timeoutError = Object.assign(new Error(`chunk checksum read timed out after ${timeoutMs}ms`), { code: "CHECKSUM_READ_TIMEOUT" });
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort(timeoutError);
+            reject(timeoutError);
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([task(controller.signal), timeout]);
     }
-    if (response.body) {
-        return hashChunkGroupContentMd5(chunks, totalSize, readableStreamToAsyncBytes(response.body));
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw timeoutError;
+        }
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
     }
-    return hashChunkGroupContentMd5(chunks, totalSize, [new Uint8Array(await response.arrayBuffer())]);
 }
 async function hashChunkGroupContentMd5(chunks, totalSize, body) {
     const output = new Map();
@@ -538,6 +597,8 @@ async function retryChecksumRead(task) {
         }
         catch (error) {
             lastError = error;
+            if (isChecksumReadTimeout(error))
+                break;
             const status = typeof error === "object" && error && "status" in error ? Number(error.status) : undefined;
             if (status && status >= 400 && status < 500 && status !== 408 && status !== 429)
                 break;
@@ -547,6 +608,12 @@ async function retryChecksumRead(task) {
     }
     throw lastError;
 }
+function isChecksumReadTimeout(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "CHECKSUM_READ_TIMEOUT");
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/package.json

@@ -1,36 +1,38 @@
 {
-  "name": "@beam-network/sdk",
-  "version": "0.2.14",
-  "description": "TypeScript SDK for BEAM transfer creation and management.",
-  "type": "module",
-  "license": "MIT",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.json --noEmit && npm run test:functional",
-    "test:functional": "npm run build && node --test test/*.test.mjs",
-    "lint": "tsc -p tsconfig.json --noEmit"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@aws-sdk/client-s3": "^3.806.0",
-    "@aws-sdk/s3-request-presigner": "^3.806.0"
-  },
-  "devDependencies": {
-    "typescript": "^5.5.0"
-  }
+    "name":  "@beam-network/sdk",
+    "version":  "0.2.16",
+    "description":  "TypeScript SDK for BEAM transfer creation and management.",
+    "type":  "module",
+    "license":  "MIT",
+    "sideEffects":  false,
+    "main":  "./dist/index.js",
+    "types":  "./dist/index.d.ts",
+    "exports":  {
+                    ".":  {
+                              "types":  "./dist/index.d.ts",
+                              "import":  "./dist/index.js"
+                          }
+                },
+    "files":  [
+                  "dist",
+                  "README.md"
+              ],
+    "scripts":  {
+                    "build":  "tsc -p tsconfig.json",
+                    "test":  "tsc -p tsconfig.json --noEmit \u0026\u0026 npm run test:functional",
+                    "test:functional":  "npm run build \u0026\u0026 node --test test/client.functional.test.mjs",
+                    "lint":  "tsc -p tsconfig.json --noEmit"
+                },
+    "publishConfig":  {
+                          "access":  "public"
+                      },
+    "dependencies":  {
+                         "@aws-sdk/client-s3":  "^3.806.0",
+                         "@aws-sdk/s3-request-presigner":  "^3.806.0",
+                         "@msgpack/msgpack":  "^3.0.0",
+                         "nats":  "^2.29.3"
+                     },
+    "devDependencies":  {
+                            "typescript":  "^5.5.0"
+                        }
 }