@beam-network/sdk 0.5.1 → 0.5.3

package/README.md

@@ -98,7 +98,9 @@ For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport
 
 Provider transfers use `transfer-client-control/v5`. Every reply carries Runtime and transport epochs; prepare and every route-stream message carry a UUID route generation. S3, R2, and S3-compatible destinations retain direct multipart UploadPart/ListParts/HEAD handling.
 
-The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches, split only when encoded MessagePack requests exceed `maxPayloadBytes` (24 MiB by default). The stream ID derives from the transfer, selected flow, and immutable plan identity, and each ordered batch ID includes its route-coordinate checksum. Manual multi-destination attachment requires `delivery_index` on every route. Lifecycle mutations retry transient failures up to three times with the same request identity. `waitForTransfer` subscribes to the API-key-owned, at-most-once terminal signal before its first status read and reconciles every signal through authoritative status; subscription failure degrades to the same jittered 15-to-30-second status fallback. Call `close()` when the client is no longer needed; it also closes outstanding terminal waiters.
+The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches, split only when encoded MessagePack requests exceed `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). A single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
+
+The stream ID derives from the transfer, selected flow, and immutable plan identity, and each ordered batch ID includes its route-coordinate checksum. Manual multi-destination attachment requires `delivery_index` on every route. Lifecycle mutations retry transient failures up to three times with the same request identity. A non-recoverable provider setup or route failure raises `BeamProviderTransferError`, whose `errors`, `transferCancelled`, and `multipartCleanupComplete` fields retain the original provider, cancellation, and cleanup outcomes. `waitForTransfer` subscribes to the API-key-owned, at-most-once terminal signal before its first status read and reconciles every signal through authoritative status; subscription failure degrades to the same jittered 15-to-30-second status fallback. Call `close()` when the client is no longer needed; it also closes outstanding terminal waiters.
 
 Hippius uses genuine non-multipart v2 routes, so its manifest is empty and group-level final HEAD verification is not available from that provider flow.
 

package/dist/client.d.ts

@@ -1,6 +1,24 @@
 import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, MultipartGroupManifest, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo, TransferTerminalSignalWaiter } from "./models.js";
 import { BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
+export declare class BeamRouteRecoveryPendingError extends Error {
+    readonly transferId: string;
+    readonly cause: unknown;
+    constructor(transferId: string, cause: unknown);
+}
 export { BEAM_DEFAULT_NATS_URL };
+export declare const BEAM_DEFAULT_MULTIPART_CONTROL_CONCURRENCY = 2;
+export declare class BeamProviderTransferError extends AggregateError {
+    readonly transferId: string;
+    readonly transferCancelled: boolean;
+    readonly multipartCleanupComplete: boolean;
+    readonly cause: unknown;
+    constructor(input: {
+        transferId: string;
+        cause: unknown;
+        cancelError?: unknown;
+        cleanupError?: unknown;
+    });
+}
 export declare class BeamApiError extends Error {
     readonly status: number;
     readonly body: string;
@@ -13,6 +31,7 @@ export declare class BeamClient {
     private readonly control;
     private readonly routeSigningConcurrency;
     private readonly routeSigningConcurrencyOverridden;
+    private readonly multipartControlConcurrency;
     constructor(options?: BeamClientOptions);
     close(): Promise<void>;
     openTransferTerminalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;

package/dist/client.js

@@ -1,7 +1,39 @@
 import { abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes, isRecoverableRouteStreamError } from "./nats-control.js";
+export class BeamRouteRecoveryPendingError extends Error {
+    transferId;
+    cause;
+    constructor(transferId, cause) {
+        super(`Transfer ${transferId} is prepared and route recovery is continuing in the background.`);
+        this.name = "BeamRouteRecoveryPendingError";
+        this.transferId = transferId;
+        this.cause = cause;
+    }
+}
 import { multipartPartNumber } from "./multipart-limits.js";
 export { BEAM_DEFAULT_NATS_URL };
+export const BEAM_DEFAULT_MULTIPART_CONTROL_CONCURRENCY = 2;
+export class BeamProviderTransferError extends AggregateError {
+    transferId;
+    transferCancelled;
+    multipartCleanupComplete;
+    cause;
+    constructor(input) {
+        const errors = [input.cause];
+        if (input.cancelError !== undefined)
+            errors.push(input.cancelError);
+        if (input.cleanupError !== undefined)
+            errors.push(input.cleanupError);
+        const transferCancelled = input.cancelError === undefined;
+        const multipartCleanupComplete = input.cleanupError === undefined;
+        super(errors, `provider transfer failed for ${input.transferId} (transfer_cancelled=${transferCancelled}, multipart_cleanup_complete=${multipartCleanupComplete})`);
+        this.name = "BeamProviderTransferError";
+        this.transferId = input.transferId;
+        this.transferCancelled = transferCancelled;
+        this.multipartCleanupComplete = multipartCleanupComplete;
+        this.cause = input.cause;
+    }
+}
 export class BeamApiError extends Error {
     status;
     body;
@@ -19,6 +51,7 @@ export class BeamClient {
     control;
     routeSigningConcurrency;
     routeSigningConcurrencyOverridden;
+    multipartControlConcurrency;
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
@@ -27,6 +60,7 @@ export class BeamClient {
         this.natsUrl = options.natsUrl ?? options.natsWsUrl ?? BEAM_DEFAULT_NATS_URL;
         this.routeSigningConcurrency = positiveInteger(options.routeSigningConcurrency ?? 64, "routeSigningConcurrency");
         this.routeSigningConcurrencyOverridden = options.routeSigningConcurrency !== undefined;
+        this.multipartControlConcurrency = positiveInteger(options.multipartControlConcurrency ?? BEAM_DEFAULT_MULTIPART_CONTROL_CONCURRENCY, "multipartControlConcurrency");
         this.control = new BeamTransferControl({
             apiKey: this.apiKey,
             natsUrl: options.natsUrl,
@@ -192,10 +226,11 @@ export class BeamClient {
             return attached;
         }
         catch (error) {
-            if (isRecoverableRouteStreamError(error))
+            if (isRecoverableRouteStreamError(error)) {
                 this.control.continueRecoveryLease(transferId);
-            else
-                this.control.releaseRecoveryLease(transferId);
+                throw new BeamRouteRecoveryPendingError(transferId, error);
+            }
+            this.control.releaseRecoveryLease(transferId);
             throw error;
         }
         finally {
@@ -297,8 +332,7 @@ export class BeamClient {
                     multipartUploads,
                     expiresIn,
                     signedUrlFlow: requestedSignedUrlFlow,
-                    concurrency: this.routeSigningConcurrency,
-                    preserveUploadsOnFailure: recoveryReplay,
+                    concurrency: this.multipartControlConcurrency,
                     onGroupReady: async (state) => {
                         if (requestedSignedUrlFlow === "signed_url_v2") {
                             validateMultipartGroupManifest([state.manifest], prepared.transfer_id);
@@ -381,9 +415,13 @@ export class BeamClient {
                 if (multipartManifestTask)
                     await Promise.allSettled([multipartManifestTask]);
                 if (!recoveryReplay) {
-                    if (foregroundCancelled || isRecoverableRouteStreamError(error)) {
+                    if (foregroundCancelled) {
                         this.control.continueRecoveryLease(prepared.transfer_id);
                     }
+                    else if (isRecoverableRouteStreamError(error)) {
+                        this.control.continueRecoveryLease(prepared.transfer_id);
+                        throw new BeamRouteRecoveryPendingError(prepared.transfer_id, error);
+                    }
                     else {
                         this.control.releaseRecoveryLease(prepared.transfer_id);
                         await cancelAndAbortProviderFailure({
@@ -391,7 +429,8 @@ export class BeamClient {
                             transferId: prepared.transfer_id,
                             cause: error,
                             uploads: multipartUploads,
-                            abortBeforeCancel: !routeStreamBeginAttempted
+                            abortBeforeCancel: !routeStreamBeginAttempted,
+                            cleanupConcurrency: this.multipartControlConcurrency
                         });
                     }
                 }
@@ -919,7 +958,7 @@ async function cancelAndAbortProviderFailure(input) {
     let cancelError;
     if (input.abortBeforeCancel) {
         try {
-            await abortCreatedUploads(input.uploads);
+            await abortCreatedUploads(input.uploads, input.cleanupConcurrency);
         }
         catch (error) {
             cleanupError = error;
@@ -934,7 +973,7 @@ async function cancelAndAbortProviderFailure(input) {
     }
     if (!input.abortBeforeCancel || cleanupFailed) {
         try {
-            await abortCreatedUploads(input.uploads);
+            await abortCreatedUploads(input.uploads, input.cleanupConcurrency);
             cleanupError = undefined;
             cleanupFailed = false;
         }
@@ -943,14 +982,12 @@ async function cancelAndAbortProviderFailure(input) {
             cleanupFailed = true;
         }
     }
-    if (cancelError && cleanupFailed) {
-        throw new AggregateError([input.cause, cancelError, cleanupError], `provider transfer, transfer cancellation, and multipart cleanup failed for ${input.transferId}`);
-    }
-    if (cancelError)
-        throw cancelError;
-    if (cleanupFailed) {
-        throw new AggregateError([input.cause, cleanupError], `provider transfer failed and multipart cleanup failed for ${input.transferId}`);
-    }
+    throw new BeamProviderTransferError({
+        transferId: input.transferId,
+        cause: input.cause,
+        ...(cancelError !== undefined ? { cancelError } : {}),
+        ...(cleanupFailed ? { cleanupError } : {})
+    });
 }
 function safeErrorCode(error) {
     if (!(error instanceof Error))
@@ -1016,6 +1053,13 @@ async function createMultipartGroupManifest(input) {
                 metadata: finalObjectMetadata
             });
             const createdUpload = !retainedUpload;
+            if (createdUpload) {
+                input.multipartUploads.set(multipartGroupId, {
+                    destination: destinationConfig,
+                    objectKey: finalObjectKey,
+                    uploadId
+                });
+            }
             try {
                 const urlsExpiresAt = expiresAtIso(input.expiresIn);
                 const stagingObjectPrefix = buildStagingObjectPrefix({
@@ -1076,6 +1120,7 @@ async function createMultipartGroupManifest(input) {
                 if (createdUpload) {
                     try {
                         await abortMultipartUpload(destinationConfig, finalObjectKey, uploadId);
+                        input.multipartUploads.delete(multipartGroupId);
                     }
                     catch (abortError) {
                         throw new AggregateError([error, abortError], `multipart group setup and cleanup failed for ${multipartGroupId}`);
@@ -1092,16 +1137,6 @@ async function createMultipartGroupManifest(input) {
     });
     const failure = results.find((result) => !result.ok);
     if (failure && !failure.ok) {
-        if (input.preserveUploadsOnFailure)
-            throw failure.error;
-        try {
-            await abortCreatedUploads(input.multipartUploads);
-        }
-        catch (cleanupError) {
-            input.multipartUploads.clear();
-            throw new AggregateError([failure.error, cleanupError], "multipart manifest setup and cleanup failed");
-        }
-        input.multipartUploads.clear();
         throw failure.error;
     }
     return results.flatMap((result) => result.ok && result.state ? [result.state.manifest] : []);
@@ -1350,11 +1385,12 @@ function validateId(value, name) {
         throw new Error(`${name} is invalid`);
     }
 }
-async function abortCreatedUploads(uploads) {
-    const candidates = [...uploads.values()].filter((upload) => upload.uploadId && !isHippiusDestination(upload.destination));
-    const results = await mapOrderedWithConcurrency(candidates, Math.min(32, Math.max(1, candidates.length)), async (upload) => {
+async function abortCreatedUploads(uploads, concurrency) {
+    const candidates = [...uploads.entries()].filter(([, upload]) => upload.uploadId && !isHippiusDestination(upload.destination));
+    const results = await mapOrderedWithConcurrency(candidates, Math.min(concurrency, Math.max(1, candidates.length)), async ([groupId, upload]) => {
         try {
             await abortMultipartUpload(upload.destination, upload.objectKey, upload.uploadId);
+            uploads.delete(groupId);
             return null;
         }
         catch (error) {

package/dist/models.d.ts

@@ -9,6 +9,7 @@ export interface BeamClientOptions {
     requestTimeoutMs?: number;
     maxPayloadBytes?: number;
     routeSigningConcurrency?: number;
+    multipartControlConcurrency?: number;
     fetch?: typeof fetch;
 }
 export interface SourceConfig {

package/dist/nats-control.js

@@ -5,7 +5,7 @@ export const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
 export const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
 // NATS enforces max_payload per message. This guard splits signed-route control
 // messages before the broker rejects them; transfer bytes never flow through NATS.
-export const BEAM_DEFAULT_MAX_PAYLOAD_BYTES = 24 * 1024 * 1024;
+export const BEAM_DEFAULT_MAX_PAYLOAD_BYTES = 8 * 1024 * 1024;
 export function buildConnectionOptions(options) {
     const connectionOptions = {
         servers: options.natsUrl,

package/dist/provider-signing.js

@@ -347,6 +347,7 @@ function createS3CompatibleClient(source, endpoint = s3CompatibleEndpoint(source
         region: s3CompatibleRegion(source),
         endpoint,
         forcePathStyle: s3CompatibleForcePathStyle(source, endpoint),
+        maxAttempts: 5,
         credentials: {
             accessKeyId: source.access_key_id,
             secretAccessKey: source.secret_access_key,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@beam-network/sdk",
-    "version": "0.5.1",
+    "version": "0.5.3",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",
@@ -20,7 +20,7 @@
     "scripts": {
         "build": "tsc -p tsconfig.json",
         "test": "tsc -p tsconfig.json --noEmit && npm run test:functional",
-        "test:functional": "npm run build && node --test test/client.functional.test.mjs",
+        "test:functional": "npm run build && node --test test/*.test.mjs",
         "lint": "tsc -p tsconfig.json --noEmit"
     },
     "publishConfig": {