@beam-network/sdk 0.2.22 → 0.3.0

package/README.md

@@ -40,6 +40,7 @@ const transfer = await beam.createTransfer({
 
 const status = await beam.waitForTransfer(transfer.transfer_id);
 console.log(status.status);
+await beam.close();
 ```
 
 The main `createTransfer` API is provider-aware and strictly typed for S3, R2, S3-compatible, and Hippius configs.
@@ -95,6 +96,10 @@ For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport
 
 ## Route Streaming And Payload Size
 
-Provider transfers materialize the compact Runtime plan lazily, sign up to 64 routes concurrently by default, and stream a 256-route bootstrap batch followed by 2,048-route steady batches. Set `routeSigningConcurrency` on `BeamClientOptions` to tune the signing bound. Completed batches are sent FIFO while signing continues. Shared route fields use compact dictionaries, and encoded MessagePack requests split under `maxPayloadBytes`, which defaults to 24 MiB.
+Provider transfers use `signed_url_v2` and `transfer-client-control/v3`. Before route streaming, S3, R2, and S3-compatible destinations create one metadata-bearing multipart upload per source/destination object. Its deduplicated manifest contains complete/abort and final HEAD controls, expected object size/count, required Beam object metadata, and exactly `ceil(max_part_number / 1000)` unique URLs in each of `list_page_urls` and `staging_list_urls`. Staging pages fix `MaxKeys=1000`; keys are ordered by unsigned UTF-8 bytes, page zero omits `StartAfter`, and later pages start after the preceding page's last key. Per-route batches carry only the stable group ID and route-attempt metadata. Part number is `source_chunk_index + 1`, and retries overwrite that same part.
+
+The client signs up to 64 routes concurrently by default and emits a 32-route bootstrap batch followed by 256-route steady batches. Out-of-order signing completions are buffered until the next deterministic delivery index, keeping batch contents reproducible. The stream ID derives from the transfer and immutable plan identity, and each ordered batch ID includes its route-coordinate checksum. Manual multi-destination attachment requires `delivery_index` on every route. Encoded MessagePack requests still split under `maxPayloadBytes` (24 MiB by default), and 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.
+
+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.
 
 NATS requires this guard because the broker rejects messages above its configured `max_payload`. This limit applies only to lifecycle/control metadata; transfer file bytes do not flow through NATS.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo } from "./models.js";
+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 { BEAM_DEFAULT_NATS_URL };
 export declare class BeamApiError extends Error {
@@ -12,9 +12,9 @@ export declare class BeamClient {
     private readonly fetchImpl;
     private readonly control;
     private readonly routeSigningConcurrency;
-    private readonly recoverySigners;
     constructor(options?: BeamClientOptions);
     close(): Promise<void>;
+    openTransferTerminalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
     createRawTransfer(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
     createTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
@@ -35,23 +35,22 @@ export declare class BeamClient {
         testMode?: boolean;
         urlsExpiresAt?: string;
         signedUrlFlow?: SignedUrlFlow;
+        idempotencyKey?: string;
     }): Promise<TransferPrepareResponse>;
     attachSignedUrls(transferId: string, input: {
         chunkRoutes: SignedChunkRoute[];
+        multipartGroupManifest: MultipartGroupManifest[];
         transferKey?: string;
         urlsExpiresAt?: string;
-        signedUrlFlow?: SignedUrlFlow;
         autoDistribute?: boolean;
     }): Promise<AttachSignedUrlsResponse>;
     prepareProviderTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     private signProviderRoute;
-    private startProviderRouteRecoverySigner;
-    private stopRecoverySigner;
-    private stopAllRecoverySigners;
     createAndDistribute(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
     waitForTransfer(transferId: string, options?: {
         timeoutMs?: number;
         pollIntervalMs?: number;
+        maxPollIntervalMs?: number;
     }): Promise<TransferStatusInfo>;
 }
 export declare function buildStagingObjectPrefix(input: {