@beam-network/sdk 0.5.17-dev.1 → 0.5.17-dev.2

package/README.md

@@ -155,6 +155,10 @@ The client signs up to 64 routes concurrently by default and emits 2,048-route l
 
 Callers that need durable recovery accounting can provide `onMultipartGroupReady`. The SDK invokes it after creating a multipart upload and before streaming that group’s signed routes. Its payload contains transfer, source, destination, object-key, upload, size, part-count, and expiry identities only; it never includes credentials, request headers, or signed URLs. A rejected callback aborts the newly created upload and fails preparation closed.
 
+`resumeProviderTransfer` requires the complete saved callback payloads in `multipartGroups`. It validates every transfer/source/destination/object/size/part coordinate, then uses the same route-stream implementation as creation with those upload IDs. Missing, duplicate, or changed identities fail before new provider uploads or route publication. If a process died before recording an upload identity, treat it as uncertain cleanup instead of inventing a replacement. The `onPrepared` callback also runs during resume, before routes are streamed.
+
+Create and resume accept an ownership `signal`. Aborting it stops initial routes, multipart creation, and recovery signing/replay; it does not cancel the transfer or abort a replacement owner's uploads. User cancellation still uses `cancelTransfer` and verified provider cleanup. `prepareProviderSource` accepts the same signal for metadata requests.
+
 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.
 
 On completed provider transfers, Runtime may include an `integrity_audit_challenge` in status. Before releasing provider signing state, the TypeScript client signs exact read-only source and final-destination GET ranges and submits `transfer.integrity_audit_grants`; audit submission failures are best-effort and do not change transfer completion.

package/dist/client.d.ts

@@ -84,6 +84,7 @@ export declare class BeamClient {
         autoDistribute?: boolean;
     }): Promise<AttachSignedUrlsResponse>;
     prepareProviderTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
+    private executeProviderTransfer;
     /**
      * Negotiate every Hugging Face destination before the plan exists.
      *

package/dist/client.js

@@ -115,62 +115,7 @@ export class BeamClient {
     }
     async resumeProviderTransfer(input) {
         validateId(input.transferId, "transferId");
-        const expiresIn = input.expiresIn ?? 3600;
-        const requestedSignedUrlFlow = input.signedUrlFlow ?? "signed_url";
-        const retainedRecoveryInput = {
-            ...input,
-            sources: input.sources.map((source) => ({ ...source })),
-            destinations: input.destinations.map((destination) => ({ ...destination }))
-        };
-        const preparedDestinations = retainedRecoveryInput.destinations.map((destination, index) => prepareProviderDestination(destination, { index }));
-        const destinationsById = new Map();
-        preparedDestinations.forEach((preparedDestination, index) => {
-            const destination = retainedRecoveryInput.destinations[index];
-            if (!destination) {
-                throw new Error(`missing provider destination config for prepared destination ${preparedDestination.destination_id}`);
-            }
-            destinationsById.set(preparedDestination.destination_id, destination);
-        });
-        const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
-        const resumePrepareRequestKey = `transfer:${input.transferId}:prepare:resume:${randomUuid()}`;
-        const prepared = await this.prepareTransferWithRequestKey({
-            transferId: input.transferId,
-            sources: preparedSources,
-            destinations: preparedDestinations,
-            name: input.name,
-            testMode: input.testMode,
-            signedUrlFlow: requestedSignedUrlFlow
-        }, resumePrepareRequestKey);
-        if (!prepared.success)
-            return prepared;
-        if (prepared.transfer_id !== input.transferId) {
-            throw new Error("resumed provider transfer id mismatch");
-        }
-        const sourcesById = new Map();
-        preparedSources.forEach((preparedSource, index) => {
-            const source = retainedRecoveryInput.sources[index];
-            if (!source) {
-                throw new Error(`missing provider source config for prepared source ${preparedSource.source_id}`);
-            }
-            sourcesById.set(preparedSource.source_id, source);
-        });
-        await this.startProviderRouteRecoverySigner({
-            prepared,
-            sourcesById,
-            destinationsById,
-            multipartUploads: new Map(),
-            expiresIn
-        });
-        this.control.registerRecoveryLease({
-            transferId: prepared.transfer_id,
-            planFingerprint: prepared.plan_fingerprint,
-            coordinateChecksum: prepared.coordinate_checksum,
-            replayRoutes: async () => {
-                throw new Error("route replay is unavailable after provider action resume; route signing remains available");
-            },
-            disposeSecrets: () => clearProviderResumeSecrets(retainedRecoveryInput)
-        });
-        return prepared;
+        return this.executeProviderTransfer(input, input);
     }
     async transferStatus(transferId) {
         validateId(transferId, "transferId");
@@ -314,6 +259,10 @@ export class BeamClient {
         }
     }
     async prepareProviderTransfer(input) {
+        return this.executeProviderTransfer(input);
+    }
+    async executeProviderTransfer(input, resume) {
+        input.signal?.throwIfAborted();
         const expiresIn = input.expiresIn ?? 3600;
         const requestedSignedUrlFlow = input.signedUrlFlow ?? "signed_url";
         const retainedRecoveryInput = {
@@ -335,7 +284,7 @@ export class BeamClient {
             destinationsById.set(preparedDestination.destination_id, destination);
         });
         await input.throwIfCancelled?.();
-        const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
+        const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl, signal: input.signal })));
         await input.throwIfCancelled?.();
         const huggingFace = await this.planHuggingFaceUploads({
             sources: retainedRecoveryInput.sources,
@@ -345,16 +294,22 @@ export class BeamClient {
         });
         await input.throwIfCancelled?.();
         await input.onBeforeTransferPrepare?.();
-        const prepared = await this.prepareTransfer({
+        input.signal?.throwIfAborted();
+        const prepareInput = {
             sources: preparedSources,
             destinations: preparedDestinations,
             name: input.name,
             testMode: input.testMode,
             chunkSize: huggingFace.chunkSize ?? input.chunkSize,
             signedUrlFlow: requestedSignedUrlFlow,
-            idempotencyKey: input.idempotencyKey,
-            routeGenerationId: input.routeGenerationId
-        });
+            ...(resume ? { transferId: resume.transferId } : { idempotencyKey: input.idempotencyKey, routeGenerationId: input.routeGenerationId })
+        };
+        const prepared = resume
+            ? await this.prepareTransferWithRequestKey(prepareInput, `transfer:${resume.transferId}:prepare:resume:${randomUuid()}`)
+            : await this.prepareTransfer(prepareInput);
+        if (resume && prepared.transfer_id !== resume.transferId)
+            throw new Error("resumed provider transfer id mismatch");
+        input.signal?.throwIfAborted();
         if (!prepared.success) {
             return prepared;
         }
@@ -372,9 +327,12 @@ export class BeamClient {
             sourcesById.set(preparedSource.source_id, source);
         });
         const multipartUploads = new Map();
+        if (resume)
+            restoreProviderMultipartIdentities(prepared, destinationsById, resume.multipartGroups, multipartUploads);
         const recoveryMultipartUploads = new Map();
         const autoDistribute = input.distribute !== false;
         let initialThrowIfCancelled = input.throwIfCancelled;
+        const assertOwnership = () => input.signal?.throwIfAborted();
         const routeStreamLock = new AsyncMutex();
         const releaseInitialStream = await routeStreamLock.acquire();
         const streamPreparedRoutes = async (routeGenerationId, recoveryReplay) => {
@@ -387,9 +345,12 @@ export class BeamClient {
             let multipartManifestTask = null;
             let multipartGroupWaiters = new Map();
             let foregroundCancelled = false;
-            const throwIfCancelled = recoveryReplay || !initialThrowIfCancelled ? undefined : async (transferId) => {
+            assertOwnership();
+            const throwIfCancelled = async (transferId) => {
                 try {
-                    await initialThrowIfCancelled?.(transferId);
+                    assertOwnership();
+                    if (!recoveryReplay)
+                        await initialThrowIfCancelled?.(transferId);
                 }
                 catch (error) {
                     foregroundCancelled = true;
@@ -424,7 +385,9 @@ export class BeamClient {
                     expiresIn,
                     signedUrlFlow: requestedSignedUrlFlow,
                     concurrency: this.multipartControlConcurrency,
+                    signal: input.signal,
                     onGroupReady: async (state) => {
+                        assertOwnership();
                         recoveryMultipartUploads.set(state.manifest.multipart_group_id, state);
                         validateMultipartGroupManifest([state.manifest], prepared.transfer_id);
                         await input.onMultipartGroupReady?.(multipartGroupIdentity(prepared.transfer_id, state.manifest));
@@ -436,6 +399,7 @@ export class BeamClient {
                 const streamNextCompletedRoute = async () => {
                     const settled = await Promise.race([...pendingRoutes].map((pending) => pending.then((route) => ({ pending, route }))));
                     pendingRoutes.delete(settled.pending);
+                    assertOwnership();
                     await routeStream.addRoute(settled.route);
                     signedInWindow += 1;
                     if (signedInWindow === ROUTE_STREAM_BATCH_ROUTES) {
@@ -493,12 +457,21 @@ export class BeamClient {
                     await streamNextCompletedRoute();
                 const multipartGroupManifest = await multipartManifestTask;
                 validateMultipartGroupManifest(multipartGroupManifest, prepared.transfer_id);
+                assertOwnership();
                 const attached = await routeStream.complete();
                 if (!attached.success) {
                     throw new Error(attached.error ?? attached.message ?? "route stream failed");
                 }
             }
             catch (error) {
+                if (input.signal?.aborted) {
+                    this.stopRecoverySigner(prepared.transfer_id);
+                    this.control.releaseRecoveryLease(prepared.transfer_id);
+                    await Promise.allSettled(pendingRoutes);
+                    if (multipartManifestTask)
+                        await Promise.allSettled([multipartManifestTask]);
+                    throw input.signal.reason;
+                }
                 if (routeStream)
                     await routeStream.abort().catch(() => undefined);
                 await Promise.allSettled(pendingRoutes);
@@ -532,8 +505,14 @@ export class BeamClient {
             sourcesById,
             destinationsById,
             multipartUploads: recoveryMultipartUploads,
+            signal: input.signal,
             expiresIn
         });
+        const stopOwnedRecovery = () => {
+            this.stopRecoverySigner(prepared.transfer_id);
+            this.control.releaseRecoveryLease(prepared.transfer_id);
+        };
+        input.signal?.addEventListener("abort", stopOwnedRecovery, { once: true });
         this.control.registerRecoveryLease({
             transferId: prepared.transfer_id,
             planFingerprint: prepared.plan_fingerprint,
@@ -541,10 +520,14 @@ export class BeamClient {
             replayRoutes: async (routeGenerationId) => {
                 await routeStreamLock.run(() => streamPreparedRoutes(routeGenerationId, true));
             },
-            disposeSecrets: () => clearRecoverySecrets(retainedRecoveryInput)
+            disposeSecrets: () => {
+                input.signal?.removeEventListener("abort", stopOwnedRecovery);
+                clearRecoverySecrets(retainedRecoveryInput);
+            }
         });
         try {
             try {
+                assertOwnership();
                 await input.onPrepared?.(prepared);
             }
             catch (error) {
@@ -788,9 +771,11 @@ export class BeamClient {
     async startProviderRouteRecoverySigner(input) {
         this.stopRecoverySigner(input.prepared.transfer_id);
         const stop = await this.control.serveRouteRecoverySigner(input.prepared.transfer_id, async (payload) => {
+            input.signal?.throwIfAborted();
             if (payload.route_generation_id.length === 0)
                 throw new Error("route recovery generation is required");
             const routes = await mapOrderedWithConcurrency(payload.chunks, this.routeSigningConcurrency, async (requested) => {
+                input.signal?.throwIfAborted();
                 if (requested.route_generation_id !== payload.route_generation_id) {
                     throw new Error("route recovery chunk generation mismatch");
                 }
@@ -1505,6 +1490,37 @@ function createMultipartGroupWaiters(prepared, destinationsById) {
     }
     return waiters;
 }
+function restoreProviderMultipartIdentities(prepared, destinations, identities, uploads) {
+    if (!Array.isArray(identities))
+        throw new Error("provider_multipart_recovery_identity_required");
+    const expected = new Map();
+    for (const source of prepared.plan_descriptor.sources) {
+        for (const target of prepared.plan_descriptor.destinations) {
+            const destination = destinations.get(target.destination_id);
+            if (!destination)
+                throw new Error("provider_multipart_recovery_destination_invalid");
+            if (isDirectPutDestination(destination))
+                continue;
+            const objectKey = target.final_object_keys[source.source_id];
+            if (!objectKey)
+                throw new Error("provider_multipart_recovery_object_invalid");
+            const key = multipartGroupStateKey(prepared.transfer_id, target.destination_id, source.source_id, objectKey);
+            expected.set(key, { destination, objectKey, source, destinationId: target.destination_id });
+        }
+    }
+    if (expected.size !== identities.length)
+        throw new Error("provider_multipart_recovery_incomplete");
+    for (const identity of identities) {
+        const group = expected.get(identity.multipartGroupId);
+        if (!group || uploads.has(identity.multipartGroupId) || identity.transferId !== prepared.transfer_id ||
+            identity.sourceId !== group.source.source_id || identity.destinationId !== group.destinationId ||
+            identity.objectKey !== group.objectKey || identity.expectedObjectSize !== group.source.size ||
+            identity.expectedPartCount !== group.source.chunk_count || !identity.uploadId?.trim()) {
+            throw new Error("provider_multipart_recovery_identity_invalid");
+        }
+        uploads.set(identity.multipartGroupId, { destination: group.destination, objectKey: group.objectKey, uploadId: identity.uploadId });
+    }
+}
 async function createMultipartGroupManifest(input) {
     const groups = input.prepared.plan_descriptor.sources.flatMap((source) => input.prepared.plan_descriptor.destinations.map((destination) => ({ source, destination })));
     const results = await mapOrderedWithConcurrency(groups, input.concurrency, async ({ source, destination }) => {
@@ -1523,11 +1539,13 @@ async function createMultipartGroupManifest(input) {
             }
             multipartGroupId = multipartGroupStateKey(input.prepared.transfer_id, destination.destination_id, source.source_id, finalObjectKey);
             const finalObjectMetadata = { "beam-transfer-id": input.prepared.transfer_id };
+            input.signal?.throwIfAborted();
             const retainedUpload = input.multipartUploads.get(multipartGroupId);
             const uploadId = retainedUpload?.uploadId ?? await createMultipartUpload({
                 destination: destinationConfig,
                 objectKey: finalObjectKey,
-                metadata: finalObjectMetadata
+                metadata: finalObjectMetadata,
+                signal: input.signal
             });
             const createdUpload = !retainedUpload;
             if (createdUpload) {
@@ -1574,7 +1592,7 @@ async function createMultipartGroupManifest(input) {
                 return { ok: true, state };
             }
             catch (error) {
-                if (createdUpload) {
+                if (createdUpload && !input.signal?.aborted) {
                     try {
                         await abortMultipartUpload(destinationConfig, finalObjectKey, uploadId);
                         input.multipartUploads.delete(multipartGroupId);
@@ -1858,13 +1876,3 @@ function clearRecoverySecrets(input) {
         }
     }
 }
-function clearProviderResumeSecrets(input) {
-    const secretKeys = new Set(["access_key_id", "secret_access_key", "session_token", "api_token", "token", "password"]);
-    for (const provider of [...input.sources, ...input.destinations]) {
-        const record = provider;
-        for (const key of secretKeys) {
-            if (key in record)
-                record[key] = "";
-        }
-    }
-}

package/dist/models.d.ts

@@ -171,19 +171,10 @@ export interface TransferStatusInfo {
     };
     integrity_audit_challenge?: IntegrityAuditChallenge;
 }
-export interface ProviderTransferResumeInput {
+export interface ProviderTransferResumeInput extends Omit<ProviderTransferCreateInput, "idempotencyKey" | "routeGenerationId"> {
     transferId: string;
-    sources: ProviderSourceConfig[];
-    destinations: ProviderDestinationConfig[];
-    name?: string;
-    /**
-     * Maps to BeamCore test_mode. Must match the original prepared transfer.
-     */
-    testMode?: boolean;
-    expiresIn?: number;
-    signedUrlFlow?: SignedUrlFlow;
-    /** Requested plan chunk size. BeamCore may raise it; the response carries the effective value. */
-    chunkSize?: number;
+    /** Complete durable multipart identities from onMultipartGroupReady; resume never creates replacement uploads. */
+    multipartGroups: ProviderMultipartGroupIdentity[];
 }
 export interface TransferTerminalEvent {
     schema_version: "transfer-client-control/v6";
@@ -290,6 +281,8 @@ export declare const HuggingFaceProviderConfig: Readonly<{
     create(input: HuggingFaceProviderConfigInput): HuggingFaceProviderConfig;
 }>;
 export interface ProviderTransferCreateInput {
+    /** Ownership fence. Aborting stops signing/replay without cancelling a replacement owner. */
+    signal?: AbortSignal;
     sources: ProviderSourceConfig[];
     destinations: ProviderDestinationConfig[];
     name?: string;

package/dist/provider-signing.d.ts

@@ -6,6 +6,7 @@ export declare function prepareProviderSource(source: ProviderSourceConfig, opti
     index?: number;
     expiresIn?: number;
     fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
 }): Promise<PreparedHttpSource>;
 export declare function prepareProviderSourceForPlan(source: ProviderSourceConfig, options?: {
     index?: number;

package/dist/provider-signing.js

@@ -10,10 +10,15 @@ export function expiresAtIso(expiresIn) {
 export async function prepareProviderSource(source, options = {}) {
     const index = options.index ?? 0;
     const expiresIn = options.expiresIn ?? 3600;
+    options.signal?.throwIfAborted();
+    const baseFetch = options.fetchImpl ?? globalThis.fetch;
+    const fetchImpl = options.signal
+        ? (input, init) => baseFetch(input, { ...init, signal: AbortSignal.any([options.signal, ...(init?.signal ? [init.signal] : [])]) })
+        : baseFetch;
     if (isS3CompatibleProvider(source)) {
         const endpoint = s3CompatibleEndpoint(source);
         const client = createS3CompatibleClient(source, endpoint);
-        const head = await client.send(new HeadObjectCommand({ Bucket: source.bucket, Key: source.key }));
+        const head = await client.send(new HeadObjectCommand({ Bucket: source.bucket, Key: source.key }), { abortSignal: options.signal });
         const getUrl = await getSignedUrl(client, new GetObjectCommand({ Bucket: source.bucket, Key: source.key }), { expiresIn });
         return {
             source_id: source.id ?? `src_${index}`,
@@ -33,7 +38,6 @@ export async function prepareProviderSource(source, options = {}) {
         };
     }
     if (isHippiusProvider(source)) {
-        const fetchImpl = options.fetchImpl ?? globalThis.fetch;
         const baseUrl = source.base_url ?? "https://api.hippius.com";
         const size = await hippiusObjectSize(fetchImpl, baseUrl, source.api_token, source.bucket, source.key);
         const url = await hippiusPresign(fetchImpl, baseUrl, source.api_token, source.bucket, source.key, "get", expiresIn);
@@ -49,7 +53,7 @@ export async function prepareProviderSource(source, options = {}) {
         };
     }
     if (isHuggingFaceProvider(source)) {
-        const metadata = await huggingFaceFileMetadata(options.fetchImpl ?? globalThis.fetch, source);
+        const metadata = await huggingFaceFileMetadata(fetchImpl, source);
         return {
             source_id: source.id ?? `src_${index}`,
             type: "http",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@beam-network/sdk",
-    "version": "0.5.17-dev.1",
+    "version": "0.5.17-dev.2",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",