@beam-network/sdk 0.5.2 → 0.5.4

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` (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. 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 approach `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. 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

@@ -6,6 +6,19 @@ export declare class BeamRouteRecoveryPendingError extends Error {
     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;
@@ -18,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

@@ -12,6 +12,28 @@ export class BeamRouteRecoveryPendingError extends Error {
 }
 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;
@@ -29,6 +51,7 @@ export class BeamClient {
     control;
     routeSigningConcurrency;
     routeSigningConcurrencyOverridden;
+    multipartControlConcurrency;
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
@@ -37,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,
@@ -308,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);
@@ -406,7 +429,8 @@ export class BeamClient {
                             transferId: prepared.transfer_id,
                             cause: error,
                             uploads: multipartUploads,
-                            abortBeforeCancel: !routeStreamBeginAttempted
+                            abortBeforeCancel: !routeStreamBeginAttempted,
+                            cleanupConcurrency: this.multipartControlConcurrency
                         });
                     }
                 }
@@ -934,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;
@@ -949,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;
         }
@@ -958,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))
@@ -1031,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({
@@ -1091,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}`);
@@ -1107,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] : []);
@@ -1365,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

@@ -6,6 +6,7 @@ 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 = 8 * 1024 * 1024;
+const ROUTE_BATCH_AUTH_TOKEN_ESTIMATE_BYTES = 64 * 1024;
 export function buildConnectionOptions(options) {
     const connectionOptions = {
         servers: options.natsUrl,
@@ -284,6 +285,7 @@ export class BeamTransferControl {
         }
     }
     splitRoutesForPayload(messageType, basePayload, routes) {
+        const authTokenEstimateBytes = Math.min(ROUTE_BATCH_AUTH_TOKEN_ESTIMATE_BYTES, Math.max(512, Math.floor(this.maxPayloadBytes / 128)));
         const encodedBytes = (candidate) => {
             const encoded = encode({
                 schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
@@ -292,7 +294,10 @@ export class BeamTransferControl {
                 shard_id: 0,
                 message_type: messageType,
                 request_id: "00000000-0000-4000-8000-000000000000",
-                auth_token: "x".repeat(512),
+                // The live JWT is larger than the compact placeholder once claims and
+                // signatures are encoded. Reserve enough space for token and envelope
+                // growth so a batch accepted by the estimator stays below the guard.
+                auth_token: "x".repeat(authTokenEstimateBytes),
                 occurred_at: new Date().toISOString(),
                 producer: "sdk",
                 payload: { ...basePayload, route_batch: compactSignedRoutes(candidate) }

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.2",
+    "version": "0.5.4",
     "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": {