@beam-network/sdk 0.2.23 → 0.3.0

package/dist/models.d.ts

@@ -1,4 +1,4 @@
-export type SignedUrlFlow = "signed_url_v1" | "signed_url_v2";
+export type SignedUrlFlow = "signed_url_v2";
 export interface BeamClientOptions {
     apiKey?: string;
     natsUrl?: string;
@@ -52,7 +52,7 @@ export interface TransferCreateRequest {
     callbacks?: CallbackConfig[];
     test_mode?: boolean;
     progressive_mode?: boolean;
-    signed_url_flow?: SignedUrlFlow;
+    signed_url_flow: SignedUrlFlow;
 }
 export interface RawTransferCreateInput {
     sources: SourceConfig[];
@@ -69,6 +69,7 @@ export interface RawTransferCreateInput {
     testMode?: boolean;
     progressiveMode?: boolean;
     signedUrlFlow?: SignedUrlFlow;
+    idempotencyKey?: string;
 }
 export interface TransferCreateResponse {
     success: boolean;
@@ -120,10 +121,31 @@ export interface TransferStatusInfo {
     error_message: string | null;
     started_at: string | null;
     completed_at: string | null;
+    runtime?: boolean;
     total_bytes?: number;
     total_size?: number;
     total_chunks?: number;
     chunks_completed?: number;
+    total_destinations?: number;
+    destinations_completed?: number;
+    destination_groups?: {
+        totalGroups: number;
+        completedGroups: number;
+        pendingGroups: number;
+        totalDestinations: number;
+        completedDestinations: number;
+    };
+}
+export interface TransferTerminalEvent {
+    schema_version: "transfer-client-control/v3";
+    producer: "transfer-runtime";
+    transfer_id: string;
+    status: "completed" | "failed" | "cancelled";
+    occurred_at: string;
+}
+export interface TransferTerminalSignalWaiter {
+    wait(timeoutMs: number): Promise<TransferTerminalEvent | null>;
+    close(): Promise<void>;
 }
 export interface S3ProviderConfig {
     provider: "s3";
@@ -204,6 +226,8 @@ export interface ProviderTransferCreateInput {
     onPrepared?: (prepared: TransferPrepareResponse) => void | Promise<void>;
     throwIfCancelled?: (transferId?: string) => void | Promise<void>;
     signedUrlFlow?: SignedUrlFlow;
+    /** Stable caller identity used to derive the transfer and lifecycle request ids. */
+    idempotencyKey?: string;
 }
 export interface PlanningHttpSource {
     source_id: string;
@@ -257,13 +281,12 @@ export interface CompactTransferPlanDescriptor {
     destinations: CompactTransferPlanDestination[];
     logical_chunk_count: number;
     delivery_route_count: number;
-    multipart_attempt_slots: number;
     formulas: {
         source_offset: "source_chunk_index * chunk_size";
         delivery_index: "chunk_index * destination_count + destination_index";
-        part_number: "chunk_index * multipart_attempt_slots + attempt_slot + 1";
+        part_number: "source_chunk_index + 1";
         route_generation_id: "initial-{chunk_index}-{destination_id}";
-        staging_object_key: "{final_object_key}/{plan_nonce}/chunk-{source_chunk_index:6}";
+        staging_object_key: "{final_object_key}.beam-staging/{transfer_id}/{source_id}/{destination_id}/part-{part_number}-chunk-{chunk_index}";
     };
 }
 export interface SignedChunkRoute {
@@ -280,6 +303,26 @@ export interface SignedChunkRoute {
     dest_headers?: Record<string, string>;
     metadata?: Record<string, unknown>;
 }
+export interface MultipartGroupManifest {
+    multipart_group_id: string;
+    source_id: string;
+    destination_id: string;
+    final_object_key: string;
+    upload_id: string;
+    expected_object_size: number;
+    expected_part_count: number;
+    max_part_number: number;
+    complete_url: string;
+    abort_url: string;
+    list_page_urls: string[];
+    staging_list_urls: string[];
+    final_head_url: string;
+    final_object_metadata: {
+        "beam-transfer-id": string;
+        "beam-multipart-group-id": string;
+    };
+    urls_expires_at: string;
+}
 export interface TransferPlanResponse {
     success: boolean;
     chunk_size?: number;
@@ -289,7 +332,7 @@ export interface TransferPlanResponse {
     logical_chunks?: number;
     total_chunks?: number;
     plan_descriptor: CompactTransferPlanDescriptor;
-    signed_url_flow?: SignedUrlFlow;
+    signed_url_flow: SignedUrlFlow;
     error?: string;
     message?: string;
 }
@@ -305,7 +348,7 @@ export interface TransferPrepareResponse {
     logical_chunks?: number;
     total_chunks?: number;
     plan_descriptor: CompactTransferPlanDescriptor;
-    signed_url_flow?: SignedUrlFlow;
+    signed_url_flow: SignedUrlFlow;
     error?: string;
     message?: string;
 }

package/dist/multipart-limits.d.ts

@@ -1,4 +1,3 @@
-export declare const DIRECT_MULTIPART_ATTEMPT_SLOT_COUNT = 2;
-export declare const DIRECT_MULTIPART_MAX_PART_NUMBER = 10000;
-export declare const DIRECT_MULTIPART_MAX_LOGICAL_CHUNKS: number;
-export declare function directMultipartInitialPartNumber(chunkIndex: number): number;
+export declare const MULTIPART_MAX_PART_NUMBER = 10000;
+export declare const MULTIPART_MAX_SOURCE_CHUNKS = 10000;
+export declare function multipartPartNumber(sourceChunkIndex: number): number;

package/dist/multipart-limits.js

@@ -1,12 +1,11 @@
-export const DIRECT_MULTIPART_ATTEMPT_SLOT_COUNT = 2;
-export const DIRECT_MULTIPART_MAX_PART_NUMBER = 10_000;
-export const DIRECT_MULTIPART_MAX_LOGICAL_CHUNKS = Math.floor(DIRECT_MULTIPART_MAX_PART_NUMBER / DIRECT_MULTIPART_ATTEMPT_SLOT_COUNT);
-export function directMultipartInitialPartNumber(chunkIndex) {
-    if (!Number.isInteger(chunkIndex) || chunkIndex < 0) {
-        throw new Error("chunk_index must be a non-negative integer");
+export const MULTIPART_MAX_PART_NUMBER = 10_000;
+export const MULTIPART_MAX_SOURCE_CHUNKS = MULTIPART_MAX_PART_NUMBER;
+export function multipartPartNumber(sourceChunkIndex) {
+    if (!Number.isInteger(sourceChunkIndex) || sourceChunkIndex < 0) {
+        throw new Error("source_chunk_index must be a non-negative integer");
     }
-    if (chunkIndex >= DIRECT_MULTIPART_MAX_LOGICAL_CHUNKS) {
-        throw new Error(`chunk_index must be less than ${DIRECT_MULTIPART_MAX_LOGICAL_CHUNKS}`);
+    if (sourceChunkIndex >= MULTIPART_MAX_SOURCE_CHUNKS) {
+        throw new Error(`source_chunk_index must be less than ${MULTIPART_MAX_SOURCE_CHUNKS}`);
     }
-    return chunkIndex * DIRECT_MULTIPART_ATTEMPT_SLOT_COUNT + 1;
+    return sourceChunkIndex + 1;
 }

package/dist/nats-control.d.ts

@@ -1,41 +1,9 @@
-import type { SignedChunkRoute } from "./models.js";
-export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v2";
+import type { MultipartGroupManifest, SignedChunkRoute, TransferTerminalSignalWaiter } from "./models.js";
+export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v3";
 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 declare const BEAM_DEFAULT_MAX_PAYLOAD_BYTES: number;
-export declare const ROUTE_RECOVERY_SIGN_MESSAGE_TYPE = "transfer.route_recovery.sign";
 export type TransferClientMessageType = "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.route_stream.begin" | "transfer.route_stream.batch" | "transfer.route_stream.complete" | "transfer.distribute" | "transfer.status" | "transfer.cancel";
-export interface RouteRecoverySignChunk {
-    source_id: string;
-    destination_id: string;
-    chunk_index: number;
-    delivery_index: number;
-    source_offset: number;
-    chunk_size: number;
-    logical_attempt_index: number;
-    attempt_slot: 0 | 1 | 2;
-    part_number: number;
-    route_generation_id: string;
-    multipart_group_id: string;
-    final_object_key: string;
-    upload_id?: string;
-    urls_expires_at?: string;
-    multipart_created_at?: string;
-    source_metadata?: Record<string, unknown>;
-    destination_metadata?: Record<string, unknown>;
-}
-export interface RouteRecoverySignRequestPayload {
-    transfer_id: string;
-    route_generation_id: string;
-    requested_at?: string;
-    chunks: RouteRecoverySignChunk[];
-}
-export interface RouteRecoverySignReplyPayload {
-    transfer_id: string;
-    route_generation_id: string;
-    signed_at?: string;
-    route_batch: CompactSignedRouteBatch;
-}
 export interface CompactSignedRouteBatch {
     source_chunks: Array<{
         source_ref: number;
@@ -47,10 +15,6 @@ export interface CompactSignedRouteBatch {
         expires_at?: string;
         headers?: Record<string, string>;
     }>;
-    multipart_groups: Array<{
-        group_ref: number;
-        metadata: Record<string, unknown>;
-    }>;
     routes: Array<{
         source_ref: number;
         destination_id: string;
@@ -58,10 +22,21 @@ export interface CompactSignedRouteBatch {
         dest_url: string;
         expires_at?: string;
         dest_headers?: Record<string, string>;
-        multipart_group_ref?: number;
+        multipart_group_id?: string;
         metadata?: Record<string, unknown>;
     }>;
 }
+export interface RouteStreamBeginPayload {
+    transfer_id: string;
+    stream_id: string;
+    total_routes: number;
+    total_chunks: number;
+    route_contract_version: "signed_url_v2";
+    multipart_group_manifest: MultipartGroupManifest[];
+    urls_expires_at?: string;
+    signed_url_flow: "signed_url_v2";
+    auto_distribute: boolean;
+}
 export interface TransferControlOptions {
     apiKey: string;
     natsUrl?: string;
@@ -72,6 +47,10 @@ export interface TransferControlOptions {
     requestTimeoutMs?: number;
     maxPayloadBytes?: number;
 }
+export interface LifecycleRequestOptions {
+    transferId?: string;
+    idempotencyKey?: string;
+}
 export declare class BeamTransferControl {
     readonly environment: string;
     readonly keyPrefix: string;
@@ -82,19 +61,23 @@ export declare class BeamTransferControl {
     private readonly natsUrl;
     private readonly apiKey;
     private nc;
+    private connectionPromise;
+    private closed;
     private authToken;
     private authTokenExpiresAt;
+    private authResolvePromise;
+    private readonly terminalWaitCancellations;
     constructor(options: TransferControlOptions);
-    serveRouteRecoverySigner(transferId: string, handler: (payload: RouteRecoverySignRequestPayload) => Promise<RouteRecoverySignReplyPayload>): Promise<() => void>;
     close(): Promise<void>;
-    request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, transferId?: string): Promise<T>;
+    request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, options?: LifecycleRequestOptions): Promise<T>;
+    openTerminalSignalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
     splitRoutesForPayload(messageType: TransferClientMessageType, basePayload: Record<string, unknown>, routes: SignedChunkRoute[]): SignedChunkRoute[][];
     private connection;
     private resolveAuthToken;
+    private resolveAuthTokenFresh;
     private authSubject;
-    private routeRecoverySignSubject;
-    private buildRouteRecoveryReply;
     private requestSubject;
+    private terminalSubject;
 }
 export declare function compactSignedRoutes(routes: SignedChunkRoute[]): CompactSignedRouteBatch;
 export declare function transferShardId(transferId: string, shardCount: number): number;