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

package/README.md

@@ -12,7 +12,7 @@ Example:
 import { BeamClient, R2ProviderConfig, S3ProviderConfig } from "@beam-network/sdk";
 
 const beam = new BeamClient({
-  apiKey: "bk_your_key"
+  apiKey: "b1m_your_key"
 });
 
 const transfer = await beam.createTransfer({
@@ -161,7 +161,7 @@ Create and resume accept an ownership `signal`. Aborting it stops initial routes
 
 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.
+During the pre-completion `integrity_check` phase, Runtime may include an `integrity_audit_challenge` in status. The TypeScript client signs exact read-only source and final-destination GET ranges and submits `transfer.integrity_audit_grants`. S3-compatible source and destination grants use the prepared source ETag and Runtime-verified final-object ETag as `If-Match` conditions. Submission failures retry on the next status poll and appear as a URL-safe `integrity_audit_submission_error` on that status response; the transfer completes with a warning if the check cannot finish by its deadline.
 
 Hippius uses canonical non-multipart `signed_url` routes, so its manifest is empty and group-level final HEAD verification is not available from that provider flow.
 

package/dist/client.d.ts

@@ -56,6 +56,7 @@ export declare class BeamClient {
     resumeProviderTransfer(input: ProviderTransferResumeInput): Promise<TransferPrepareResponse>;
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
     distributeTransfer(transferId: string): Promise<DistributeResponse>;
+    private requestTransferCancellation;
     cancelTransfer(transferId: string): Promise<TransferCancelResponse>;
     planTransfer(input: {
         sources: PlanningHttpSource[];

package/dist/client.js

@@ -120,8 +120,15 @@ export class BeamClient {
     async transferStatus(transferId) {
         validateId(transferId, "transferId");
         const status = await this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
+        if (status.integrity_audit_challenge) {
+            try {
+                await this.submitIntegrityAuditGrantsIfPresent(status);
+            }
+            catch (error) {
+                status.integrity_audit_submission_error = integrityAuditErrorSummary(error);
+            }
+        }
         if (["completed", "failed", "cancelled"].includes(status.status)) {
-            await this.submitIntegrityAuditGrantsIfPresent(status).catch(() => undefined);
             this.control.releaseRecoveryLease(transferId);
             this.stopRecoverySigner(transferId);
         }
@@ -134,12 +141,15 @@ export class BeamClient {
             idempotencyKey: `transfer:${transferId}:distribute`
         });
     }
-    async cancelTransfer(transferId) {
+    requestTransferCancellation(transferId) {
         validateId(transferId, "transferId");
-        const result = await this.control.request("transfer.cancel", { transfer_id: transferId }, {
+        return this.control.request("transfer.cancel", { transfer_id: transferId }, {
             transferId,
             idempotencyKey: `transfer:${transferId}:cancel`
         });
+    }
+    async cancelTransfer(transferId) {
+        const result = await this.requestTransferCancellation(transferId);
         this.control.releaseRecoveryLease(transferId);
         this.stopRecoverySigner(transferId);
         return result;
@@ -486,15 +496,22 @@ export class BeamClient {
                         throw new BeamRouteRecoveryPendingError(prepared.transfer_id, error);
                     }
                     else {
-                        this.control.releaseRecoveryLease(prepared.transfer_id);
-                        await cancelAndAbortProviderFailure({
-                            client: this,
-                            transferId: prepared.transfer_id,
-                            cause: error,
-                            uploads: multipartUploads,
-                            abortBeforeCancel: !routeStreamBeginAttempted,
-                            cleanupConcurrency: this.multipartControlConcurrency
-                        });
+                        try {
+                            await cancelAndAbortProviderFailure({
+                                cancelTransfer: () => this.requestTransferCancellation(prepared.transfer_id),
+                                transferId: prepared.transfer_id,
+                                cause: error,
+                                uploads: multipartUploads,
+                                abortBeforeCancel: !routeStreamBeginAttempted,
+                                cleanupConcurrency: this.multipartControlConcurrency
+                            });
+                        }
+                        finally {
+                            // The retained recovery input owns the same destination objects used by
+                            // multipart cleanup. Releasing it earlier scrubs their scoped credentials
+                            // before abortMultipartUpload can clean up already-created uploads.
+                            this.control.releaseRecoveryLease(prepared.transfer_id);
+                        }
                     }
                 }
                 throw error;
@@ -917,7 +934,7 @@ export class BeamClient {
             return;
         const signer = this.integrityAuditSigners.get(challenge.transfer_id);
         if (!signer)
-            return;
+            throw new Error("integrity audit signer unavailable");
         const existing = this.integrityAuditSubmissions.get(challenge.audit_id);
         if (existing) {
             await existing;
@@ -925,7 +942,13 @@ export class BeamClient {
         }
         const submission = signer(challenge);
         this.integrityAuditSubmissions.set(challenge.audit_id, submission);
-        await submission;
+        try {
+            await submission;
+        }
+        catch (error) {
+            this.integrityAuditSubmissions.delete(challenge.audit_id);
+            throw error;
+        }
     }
     async submitProviderIntegrityAuditGrants(input) {
         if (input.challenge.transfer_id !== input.prepared.transfer_id) {
@@ -948,12 +971,17 @@ export class BeamClient {
             }
             const source = input.sourcesById.get(chunk.source_id);
             const destination = input.destinationsById.get(chunk.destination_id);
+            const plannedSource = input.prepared.plan_descriptor.sources.find((candidate) => candidate.source_id === chunk.source_id);
             if (!source || !destination) {
                 throw new Error("integrity audit provider configuration is unavailable");
             }
+            const sourceEtag = plannedSource?.metadata?.etag;
+            const sourceVersionId = plannedSource?.metadata?.version_id;
             const [sourceGrant, destinationGrant] = await Promise.all([
                 signSourceReadRange({
                     source,
+                    ...(typeof sourceEtag === "string" ? { ifMatch: sourceEtag } : {}),
+                    ...(typeof sourceVersionId === "string" ? { versionId: sourceVersionId } : {}),
                     offset: chunk.source_offset,
                     length: chunk.range_length,
                     expiresIn: input.expiresIn,
@@ -962,6 +990,7 @@ export class BeamClient {
                 signDestinationReadRange({
                     destination,
                     objectKey: chunk.final_object_key,
+                    ...(chunk.final_object_etag ? { ifMatch: chunk.final_object_etag } : {}),
                     offset: chunk.destination_offset,
                     length: chunk.range_length,
                     expiresIn: input.expiresIn,
@@ -1333,6 +1362,15 @@ async function mapOrderedWithConcurrency(values, concurrency, map) {
     await Promise.all(workers);
     return results;
 }
+function integrityAuditErrorSummary(error) {
+    if (!(error instanceof Error))
+        return "unknown_error";
+    const message = error.message.trim();
+    if (!message || /https?:\/\/|x-amz|password|secret|token|authorization|credential/i.test(message)) {
+        return error.name || "unknown_error";
+    }
+    return message.slice(0, 200);
+}
 function positiveInteger(value, label) {
     if (!Number.isInteger(value) || value < 1)
         throw new Error(`${label} must be a positive integer.`);
@@ -1393,9 +1431,9 @@ async function sha256Bytes(value) {
 function hex(bytes) {
     return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-async function cancelTransferAfterProviderFailure(client, transferId, cause) {
+async function cancelTransferAfterProviderFailure(cancelTransfer, transferId, cause) {
     try {
-        const result = await client.cancelTransfer(transferId);
+        const result = await cancelTransfer();
         if (!result.success) {
             throw new Error(result.message ?? `Beam rejected cancellation for ${transferId}`);
         }
@@ -1418,7 +1456,7 @@ async function cancelAndAbortProviderFailure(input) {
         }
     }
     try {
-        await cancelTransferAfterProviderFailure(input.client, input.transferId, input.cause);
+        await cancelTransferAfterProviderFailure(input.cancelTransfer, input.transferId, input.cause);
     }
     catch (error) {
         cancelError = error;

package/dist/models.d.ts

@@ -132,6 +132,7 @@ export interface IntegrityAuditChallengeChunk {
     destination_offset: number;
     range_length: number;
     final_object_key: string;
+    final_object_etag: string | null;
 }
 export interface IntegrityAuditChallenge {
     audit_id: string;
@@ -170,6 +171,7 @@ export interface TransferStatusInfo {
         completedDestinationIds: string[];
     };
     integrity_audit_challenge?: IntegrityAuditChallenge;
+    integrity_audit_submission_error?: string;
 }
 export interface ProviderTransferResumeInput extends Omit<ProviderTransferCreateInput, "idempotencyKey" | "routeGenerationId"> {
     transferId: string;

package/dist/provider-signing.d.ts

@@ -91,6 +91,7 @@ export declare function signSourceReadRange(input: {
 export declare function signDestinationReadRange(input: {
     destination: ProviderDestinationConfig;
     objectKey: string;
+    ifMatch?: string;
     offset: number;
     length: number;
     expiresIn: number;

package/dist/provider-signing.js

@@ -337,11 +337,14 @@ export async function signDestinationReadRange(input) {
             url: await getSignedUrl(client, new GetObjectCommand({
                 Bucket: input.destination.bucket,
                 Key: input.objectKey,
-                Range: range
+                Range: range,
+                IfMatch: input.ifMatch
             }), { expiresIn: input.expiresIn }),
-            headers: { Range: range }
+            headers: { Range: range, ...(input.ifMatch ? { "If-Match": input.ifMatch } : {}) }
         };
     }
+    if (input.ifMatch)
+        throw new Error("conditional destination ranges require S3-compatible storage");
     if (isHippiusProvider(input.destination)) {
         return {
             url: await hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.destination.base_url ?? "https://api.hippius.com", input.destination.api_token, input.destination.bucket, input.objectKey, "get", input.expiresIn),

package/package.json

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