@beam-network/sdk 0.5.19 → 0.5.20

package/README.md

@@ -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; 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.js

@@ -120,8 +120,10 @@ export class BeamClient {
     async transferStatus(transferId) {
         validateId(transferId, "transferId");
         const status = await this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
-        if (["completed", "failed", "cancelled"].includes(status.status)) {
+        if (status.integrity_audit_challenge) {
             await this.submitIntegrityAuditGrantsIfPresent(status).catch(() => undefined);
+        }
+        if (["completed", "failed", "cancelled"].includes(status.status)) {
             this.control.releaseRecoveryLease(transferId);
             this.stopRecoverySigner(transferId);
         }
@@ -935,7 +937,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) {
@@ -958,12 +966,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,
@@ -972,6 +985,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,

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;

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.19",
+    "version": "0.5.20",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",