@beam-network/sdk 0.7.0 → 0.9.0

package/README.md

@@ -39,8 +39,7 @@ const transfer = await beam.createTransfer({
       secret_access_key: "aws-secret-key"
     })
   ],
-  name: "r2-to-s3-report",
-  testMode: true
+  name: "r2-to-s3-report"
 });
 
 const status = await beam.waitForTransfer(transfer.transfer_id);
@@ -49,7 +48,32 @@ await beam.close();
 ```
 
 The main `createTransfer` API is provider-aware and strictly typed for S3, R2, S3-compatible, Hippius, and Hugging Face configs.
-Use `testMode: true` to create a BeamCore test-mode transfer.
+
+## Storage Credentials
+
+Source and destination credentials must not be restricted to specific IP addresses or networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different networks, so restricted credentials make the transfer fail.
+
+## Failed Transfers
+
+`waitForTransfer` rejects a failed transfer with `BeamTransferFailedError`, whose `errorMessage` is BeamCore's `error_message` verbatim. When the storage refused Beam's requests, the error is the `BeamStorageAccessError` subclass, with `code` set to `source_access_denied` or `destination_access_denied`:
+
+```ts
+import { BeamStorageAccessError, BeamTransferFailedError } from "@beam-network/sdk";
+
+try {
+  await beam.waitForTransfer(transfer.transfer_id);
+} catch (error) {
+  if (error instanceof BeamStorageAccessError) {
+    // For example: "destination_access_denied: The destination storage refused Beam's requests (403 AccessDenied). ..."
+    console.error(error.code, error.errorMessage);
+  } else if (error instanceof BeamTransferFailedError) {
+    console.error(error.errorMessage);
+  }
+  throw error;
+}
+```
+
+Callers that poll `transferStatus` themselves can pass a failed status to `transferFailedError(transferId, status.error_message)` to get the same classification.
 
 ## S3-Compatible Providers
 
@@ -145,7 +169,9 @@ Constraints, all of them the Hub's rather than Beam's — see
   Hub file, set `allow_source_rehash: true` to let the SDK read the source once to
   compute it.
 - **One source per Hugging Face destination**, because the Hub dictates the part
-  size and a plan carries a single chunk size.
+  size and a plan carries a single chunk size. The SDK sends that part size to
+  Beam as `provider_part_size`; Beam chooses the chunk size of every other
+  transfer.
 - If you do not call `waitForTransfer`, call `finalizeHuggingFaceUploads(transferId)`
   yourself once the transfer completes — without it the parts are uploaded but no
   commit is made and the file does not appear in the repo.

package/dist/client.d.ts

@@ -19,6 +19,33 @@ export declare class BeamProviderTransferError extends AggregateError {
         cleanupError?: unknown;
     });
 }
+/** Failure codes BeamCore reports when source or destination storage refuses Beam's requests. */
+export type BeamStorageAccessErrorCode = "source_access_denied" | "destination_access_denied";
+/** A transfer that BeamCore reported as failed. */
+export declare class BeamTransferFailedError extends Error {
+    readonly transferId: string;
+    /** The transfer's `error_message` from BeamCore, verbatim; null when BeamCore sent none. */
+    readonly errorMessage: string | null;
+    constructor(transferId: string, errorMessage: string | null);
+}
+/**
+ * The source or destination storage refused Beam's requests (`source_access_denied` or
+ * `destination_access_denied`). `errorMessage` carries BeamCore's explanation verbatim.
+ *
+ * Check that the credentials allow the operation on this bucket and path and are not restricted
+ * to specific IP addresses or networks (for example Cloudflare R2 API-token client IP filtering,
+ * S3 bucket policies with `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many
+ * workers on different networks, so restricted credentials make the transfer fail.
+ */
+export declare class BeamStorageAccessError extends BeamTransferFailedError {
+    readonly code: BeamStorageAccessErrorCode;
+    constructor(transferId: string, errorMessage: string, code: BeamStorageAccessErrorCode);
+}
+/**
+ * Builds the error for a failed transfer status: a {@link BeamStorageAccessError} when the
+ * server message starts with a storage access code, otherwise a {@link BeamTransferFailedError}.
+ */
+export declare function transferFailedError(transferId: string, errorMessage: string | null): BeamTransferFailedError;
 export declare class BeamApiError extends Error {
     readonly status: number;
     readonly body: string;
@@ -29,12 +56,10 @@ type TransferPrepareInput = {
     sources: PreparedHttpSource[];
     destinations: PreparedDestination[];
     name?: string;
-    testMode?: boolean;
     urlsExpiresAt?: string;
     signedUrlFlow?: SignedUrlFlow;
     idempotencyKey?: string;
     routeGenerationId?: string;
-    chunkSize?: number;
 };
 export declare class BeamClient {
     readonly apiKey: string;
@@ -54,22 +79,61 @@ export declare class BeamClient {
     constructor(options?: BeamClientOptions);
     close(): Promise<void>;
     openTransferTerminalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
+    /**
+     * Creates a transfer from raw source and destination configs (`transfer.create`).
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     createRawTransfer(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
+    /**
+     * Signs provider sources and destinations, prepares the transfer, streams its signed routes
+     * and, unless `distribute` is false, starts it. Alias of {@link prepareProviderTransfer}.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     createTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
+    /**
+     * Takes over a prepared provider transfer in a new process, reusing its multipart uploads.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     resumeProviderTransfer(input: ProviderTransferResumeInput): Promise<TransferPrepareResponse>;
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
     distributeTransfer(transferId: string): Promise<DistributeResponse>;
     private requestTransferCancellation;
     cancelTransfer(transferId: string): Promise<TransferCancelResponse>;
+    /**
+     * Asks BeamCore for the compact plan a transfer would use without creating it (`transfer.plan`).
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     planTransfer(input: {
         sources: PlanningHttpSource[];
         destinations: PreparedDestination[];
         name?: string;
-        testMode?: boolean;
         urlsExpiresAt?: string;
         signedUrlFlow?: SignedUrlFlow;
-        chunkSize?: number;
     }): Promise<TransferPlanResponse>;
+    /**
+     * Prepares a transfer from already-signed HTTP sources and destinations (`transfer.prepare`).
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     prepareTransfer(input: TransferPrepareInput): Promise<TransferPrepareResponse>;
     private prepareTransferWithRequestKey;
     attachSignedUrls(transferId: string, input: {
@@ -87,13 +151,23 @@ export declare class BeamClient {
         urlsExpiresAt?: string;
         autoDistribute?: boolean;
     }): Promise<AttachSignedUrlsResponse>;
+    /**
+     * Signs provider sources and destinations, prepares the transfer, streams its signed routes
+     * and, unless `distribute` is false, starts it.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     prepareProviderTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     private executeProviderTransfer;
     /**
      * Negotiate every Hugging Face destination before the plan exists.
      *
      * The Hub will not issue upload URLs without the object's sha256, and it chooses the part
-     * size itself, so this runs first and the plan is then requested at the Hub's chunk size.
+     * size itself, so this runs first and the prepare request then carries the Hub's part size
+     * as `provider_part_size`.
      */
     private planHuggingFaceUploads;
     /** Fail before any byte moves if BeamCore did not adopt the Hub's part layout. */
@@ -113,7 +187,21 @@ export declare class BeamClient {
     /** Stop a transfer's recovery and integrity signers; with `owner`, only if that owner installed them. */
     private stopRecoverySigner;
     private stopAllRecoverySigners;
+    /**
+     * Creates a raw transfer and distributes it.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     createAndDistribute(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
+    /**
+     * Waits until the transfer completes. A failed transfer rejects with a
+     * {@link BeamTransferFailedError} carrying BeamCore's `error_message` verbatim, or with its
+     * {@link BeamStorageAccessError} subclass when the source or destination storage refused
+     * Beam's requests (`source_access_denied`, `destination_access_denied`).
+     */
     waitForTransfer(transferId: string, options?: {
         timeoutMs?: number;
         pollIntervalMs?: number;

package/dist/client.js

@@ -36,6 +36,54 @@ export class BeamProviderTransferError extends AggregateError {
         this.cause = input.cause;
     }
 }
+const STORAGE_ACCESS_ERROR_CODES = [
+    "source_access_denied",
+    "destination_access_denied"
+];
+/** A transfer that BeamCore reported as failed. */
+export class BeamTransferFailedError extends Error {
+    transferId;
+    /** The transfer's `error_message` from BeamCore, verbatim; null when BeamCore sent none. */
+    errorMessage;
+    constructor(transferId, errorMessage) {
+        super(`Transfer ${transferId} failed: ${errorMessage ?? "unknown error"}`);
+        this.name = "BeamTransferFailedError";
+        this.transferId = transferId;
+        this.errorMessage = errorMessage;
+    }
+}
+/**
+ * The source or destination storage refused Beam's requests (`source_access_denied` or
+ * `destination_access_denied`). `errorMessage` carries BeamCore's explanation verbatim.
+ *
+ * Check that the credentials allow the operation on this bucket and path and are not restricted
+ * to specific IP addresses or networks (for example Cloudflare R2 API-token client IP filtering,
+ * S3 bucket policies with `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many
+ * workers on different networks, so restricted credentials make the transfer fail.
+ */
+export class BeamStorageAccessError extends BeamTransferFailedError {
+    code;
+    constructor(transferId, errorMessage, code) {
+        super(transferId, errorMessage);
+        this.name = "BeamStorageAccessError";
+        this.code = code;
+    }
+}
+/**
+ * Builds the error for a failed transfer status: a {@link BeamStorageAccessError} when the
+ * server message starts with a storage access code, otherwise a {@link BeamTransferFailedError}.
+ */
+export function transferFailedError(transferId, errorMessage) {
+    const code = errorMessage === null ? undefined : storageAccessErrorCode(errorMessage);
+    return code && errorMessage !== null
+        ? new BeamStorageAccessError(transferId, errorMessage, code)
+        : new BeamTransferFailedError(transferId, errorMessage);
+}
+function storageAccessErrorCode(errorMessage) {
+    const separator = errorMessage.indexOf(":");
+    const prefix = (separator === -1 ? errorMessage : errorMessage.slice(0, separator)).trim();
+    return STORAGE_ACCESS_ERROR_CODES.find((code) => code === prefix);
+}
 export class BeamApiError extends Error {
     status;
     body;
@@ -94,6 +142,14 @@ export class BeamClient {
         validateId(transferId, "transferId");
         return this.control.openTerminalSignalWaiter(transferId);
     }
+    /**
+     * Creates a transfer from raw source and destination configs (`transfer.create`).
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     async createRawTransfer(input) {
         const transferId = await transferIdForIdempotencyKey(input.idempotencyKey);
         const body = compact({
@@ -101,12 +157,10 @@ export class BeamClient {
             sources: input.sources,
             destinations: input.destinations,
             total_size: input.totalSize,
-            chunk_size: input.chunkSize,
             name: input.name,
             merkle_root: input.merkleRoot,
             chunk_hashes: input.chunkHashes,
             callbacks: input.callbacks,
-            test_mode: input.testMode || undefined,
             progressive_mode: input.progressiveMode || undefined,
             signed_url_flow: input.signedUrlFlow ?? "signed_url"
         });
@@ -115,9 +169,26 @@ export class BeamClient {
             idempotencyKey: `transfer:${transferId}:create`
         });
     }
+    /**
+     * Signs provider sources and destinations, prepares the transfer, streams its signed routes
+     * and, unless `distribute` is false, starts it. Alias of {@link prepareProviderTransfer}.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     createTransfer(input) {
         return this.prepareProviderTransfer(input);
     }
+    /**
+     * Takes over a prepared provider transfer in a new process, reusing its multipart uploads.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     async resumeProviderTransfer(input) {
         validateId(input.transferId, "transferId");
         return this.executeProviderTransfer(input, input);
@@ -159,13 +230,19 @@ export class BeamClient {
         this.stopRecoverySigner(transferId);
         return result;
     }
+    /**
+     * Asks BeamCore for the compact plan a transfer would use without creating it (`transfer.plan`).
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     async planTransfer(input) {
         const result = await this.control.request("transfer.plan", compact({
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
-            test_mode: input.testMode || undefined,
-            chunk_size: input.chunkSize,
             urls_expires_at: input.urlsExpiresAt,
             signed_url_flow: input.signedUrlFlow ?? "signed_url"
         }));
@@ -173,13 +250,21 @@ export class BeamClient {
             validateCompactTransferPlan(result.plan_descriptor, result.signed_url_flow);
         return result;
     }
+    /**
+     * Prepares a transfer from already-signed HTTP sources and destinations (`transfer.prepare`).
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     prepareTransfer(input) {
         return this.prepareTransferWithRequestKey(input);
     }
-    async prepareTransferWithRequestKey(input, requestKey) {
+    async prepareTransferWithRequestKey(input, options = {}) {
         const transferId = input.transferId ?? await transferIdForIdempotencyKey(input.idempotencyKey);
         validateId(transferId, "transferId");
-        const prepareIdempotencyKey = requestKey ?? `transfer:${transferId}:prepare`;
+        const prepareIdempotencyKey = options.requestKey ?? `transfer:${transferId}:prepare`;
         const routeGenerationId = input.routeGenerationId ?? await routeGenerationIdForPrepareIdempotencyKey(prepareIdempotencyKey);
         const result = await this.control.request("transfer.prepare", compact({
             transfer_id: transferId,
@@ -187,8 +272,7 @@ export class BeamClient {
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
-            test_mode: input.testMode || undefined,
-            chunk_size: input.chunkSize,
+            provider_part_size: options.providerPartSize,
             urls_expires_at: input.urlsExpiresAt,
             signed_url_flow: input.signedUrlFlow ?? "signed_url"
         }), {
@@ -274,6 +358,15 @@ export class BeamClient {
             releaseInitialStream();
         }
     }
+    /**
+     * Signs provider sources and destinations, prepares the transfer, streams its signed routes
+     * and, unless `distribute` is false, starts it.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     async prepareProviderTransfer(input) {
         return this.executeProviderTransfer(input);
     }
@@ -316,14 +409,13 @@ export class BeamClient {
             sources: preparedSources,
             destinations: preparedDestinations,
             name: input.name,
-            testMode: input.testMode,
-            chunkSize: huggingFace.chunkSize ?? input.chunkSize,
             signedUrlFlow: requestedSignedUrlFlow,
             ...(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);
+        const prepared = await this.prepareTransferWithRequestKey(prepareInput, {
+            requestKey: resume ? `transfer:${resume.transferId}:prepare:resume:${randomUuid()}` : undefined,
+            providerPartSize: huggingFace.providerPartSize
+        });
         if (resume && prepared.transfer_id !== resume.transferId)
             throw new Error("resumed provider transfer id mismatch");
         input.signal?.throwIfAborted();
@@ -610,7 +702,8 @@ export class BeamClient {
      * Negotiate every Hugging Face destination before the plan exists.
      *
      * The Hub will not issue upload URLs without the object's sha256, and it chooses the part
-     * size itself, so this runs first and the plan is then requested at the Hub's chunk size.
+     * size itself, so this runs first and the prepare request then carries the Hub's part size
+     * as `provider_part_size`.
      */
     async planHuggingFaceUploads(input) {
         const targets = input.destinations
@@ -629,7 +722,7 @@ export class BeamClient {
             ? typeof preparedSource.metadata?.sha256 === "string" ? preparedSource.metadata.sha256 : undefined
             : undefined;
         const states = [];
-        let chunkSize;
+        let providerPartSize;
         for (const { destination, index } of targets) {
             const preparedDestination = input.preparedDestinations[index];
             if ((destination.repo_type ?? "model") === "bucket") {
@@ -667,11 +760,11 @@ export class BeamClient {
                 size: preparedSource.size
             });
             if (plan.upload?.chunkSize !== undefined) {
-                if (chunkSize !== undefined && chunkSize !== plan.upload.chunkSize) {
-                    throw new Error(`huggingface destinations disagree on part size (${chunkSize} vs ${plan.upload.chunkSize}); `
+                if (providerPartSize !== undefined && providerPartSize !== plan.upload.chunkSize) {
+                    throw new Error(`huggingface destinations disagree on part size (${providerPartSize} vs ${plan.upload.chunkSize}); `
                         + "the plan carries a single chunk size");
                 }
-                chunkSize = plan.upload.chunkSize;
+                providerPartSize = plan.upload.chunkSize;
             }
             states.push({
                 destination: config,
@@ -692,7 +785,7 @@ export class BeamClient {
                     }).then((hashed) => hashed.partEtags)
             });
         }
-        return { states, chunkSize };
+        return { states, providerPartSize };
     }
     /** Fail before any byte moves if BeamCore did not adopt the Hub's part layout. */
     assertHuggingFacePlan(prepared, states) {
@@ -1135,6 +1228,14 @@ export class BeamClient {
         for (const transferId of [...this.recoverySigners.keys()])
             this.stopRecoverySigner(transferId);
     }
+    /**
+     * Creates a raw transfer and distributes it.
+     *
+     * Source and destination credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     async createAndDistribute(input) {
         const transfer = await this.createRawTransfer(input);
         if (transfer.success) {
@@ -1142,6 +1243,12 @@ export class BeamClient {
         }
         return transfer;
     }
+    /**
+     * Waits until the transfer completes. A failed transfer rejects with a
+     * {@link BeamTransferFailedError} carrying BeamCore's `error_message` verbatim, or with its
+     * {@link BeamStorageAccessError} subclass when the source or destination storage refused
+     * Beam's requests (`source_access_denied`, `destination_access_denied`).
+     */
     async waitForTransfer(transferId, options = {}) {
         const timeoutMs = options.timeoutMs ?? 300_000;
         const pollIntervalMs = options.pollIntervalMs ?? 15_000;
@@ -1174,7 +1281,7 @@ export class BeamClient {
                     return status;
                 }
                 if (status.status === "failed") {
-                    throw new Error(`Transfer failed: ${status.error_message ?? "unknown error"}`);
+                    throw transferFailedError(transferId, status.error_message);
                 }
                 if (status.status === "cancelled") {
                     throw new Error("Transfer cancelled");

package/dist/models.d.ts

@@ -34,6 +34,14 @@ export interface BeamClientOptions {
     multipartControlConcurrency?: number;
     fetch?: typeof fetch;
 }
+/**
+ * Raw transfer source.
+ *
+ * Source credentials must not be restricted to specific IP addresses or networks (for example
+ * Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface SourceConfig {
     type: string;
     bucket?: string;
@@ -47,6 +55,14 @@ export interface SourceConfig {
     url?: string;
     headers?: Record<string, string>;
 }
+/**
+ * Raw transfer destination.
+ *
+ * Destination credentials must not be restricted to specific IP addresses or networks (for
+ * example Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface DestConfig {
     type: string;
     bucket?: string;
@@ -68,12 +84,10 @@ export interface TransferCreateRequest {
     sources: SourceConfig[];
     destinations: DestConfig[];
     total_size: number;
-    chunk_size?: number;
     name?: string;
     merkle_root?: string;
     chunk_hashes?: string[];
     callbacks?: CallbackConfig[];
-    test_mode?: boolean;
     progressive_mode?: boolean;
     signed_url_flow: SignedUrlFlow;
 }
@@ -81,15 +95,10 @@ export interface RawTransferCreateInput {
     sources: SourceConfig[];
     destinations: DestConfig[];
     totalSize: number;
-    chunkSize?: number;
     name?: string;
     merkleRoot?: string;
     chunkHashes?: string[];
     callbacks?: CallbackConfig[];
-    /**
-     * Maps to BeamCore test_mode.
-     */
-    testMode?: boolean;
     progressiveMode?: boolean;
     signedUrlFlow?: SignedUrlFlow;
     idempotencyKey?: string;
@@ -254,6 +263,14 @@ export interface TransferTerminalSignalWaiter {
     wait(timeoutMs: number): Promise<TransferTerminalEvent | null>;
     close(): Promise<void>;
 }
+/**
+ * Amazon S3 source or destination.
+ *
+ * Credentials must not be restricted to specific IP addresses or networks (for example
+ * Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface S3ProviderConfig {
     /** Physical storage location; independent of the signing region. */
     storage_location?: string;
@@ -267,6 +284,14 @@ export interface S3ProviderConfig {
     session_token?: string;
     endpoint_url?: string;
 }
+/**
+ * Cloudflare R2 source or destination.
+ *
+ * Credentials must not be restricted to specific IP addresses or networks (for example
+ * Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface R2ProviderConfig {
     /** Physical storage location; independent of the signing region. */
     storage_location?: string;
@@ -279,6 +304,14 @@ export interface R2ProviderConfig {
     account_id?: string;
     endpoint_url?: string;
 }
+/**
+ * S3-compatible source or destination (MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces and others).
+ *
+ * Credentials must not be restricted to specific IP addresses or networks (for example
+ * Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface S3CompatibleProviderConfig {
     /** Physical storage location; independent of the signing region. */
     storage_location?: string;
@@ -295,6 +328,14 @@ export interface S3CompatibleProviderConfig {
     force_path_style?: boolean;
     account_id?: string;
 }
+/**
+ * Hippius source or destination.
+ *
+ * Credentials must not be restricted to specific IP addresses or networks (for example
+ * Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface HippiusProviderConfig {
     /** Physical storage location; independent of the signing region. */
     storage_location?: string;
@@ -306,6 +347,14 @@ export interface HippiusProviderConfig {
     base_url?: string;
 }
 export type HuggingFaceRepoType = "model" | "dataset" | "space" | "kernel" | "bucket";
+/**
+ * Hugging Face Hub source or destination.
+ *
+ * The token and any credentials must not be restricted to specific IP addresses or networks (for example
+ * Cloudflare R2 API-token client IP filtering, S3 bucket policies with `aws:SourceIp`, or
+ * VPC-only endpoints). Beam moves data through many workers on different networks, so
+ * restricted credentials make the transfer fail.
+ */
 export interface HuggingFaceProviderConfig {
     /** Physical storage location; independent of the signing region. */
     storage_location?: string;
@@ -360,13 +409,19 @@ export declare const HuggingFaceProviderConfig: Readonly<{
 export interface ProviderTransferCreateInput {
     /** Ownership fence. Aborting stops signing/replay without cancelling a replacement owner. */
     signal?: AbortSignal;
+    /**
+     * Storage to read from. Source credentials must not be restricted to specific IP addresses or
+     * networks (for example Cloudflare R2 API-token client IP filtering, S3 bucket policies with
+     * `aws:SourceIp`, or VPC-only endpoints). Beam moves data through many workers on different
+     * networks, so restricted credentials make the transfer fail.
+     */
     sources: ProviderSourceConfig[];
-    destinations: ProviderDestinationConfig[];
-    name?: string;
     /**
-     * Maps to BeamCore test_mode.
+     * Storage to write to. Destination credentials must not be restricted to specific IP addresses
+     * or networks, for the same reason as `sources`.
      */
-    testMode?: boolean;
+    destinations: ProviderDestinationConfig[];
+    name?: string;
     expiresIn?: number;
     /**
      * Defaults to true. Set to false to only prepare and stream signed routes without distribution.
@@ -386,8 +441,6 @@ export interface ProviderTransferCreateInput {
     idempotencyKey?: string;
     /** Internal recovery generation; callers normally omit this. */
     routeGenerationId?: string;
-    /** Requested plan chunk size. BeamCore may raise it; the response carries the effective value. */
-    chunkSize?: number;
 }
 export interface ProviderMultipartGroupIdentity {
     transferId: string;
@@ -400,6 +453,11 @@ export interface ProviderMultipartGroupIdentity {
     expectedPartCount: number;
     expiresAt: string;
 }
+/**
+ * HTTP source for planning and preparing. Its URL and headers must work from any network: Beam
+ * moves data through many workers on different networks, so IP- or network-restricted URLs make
+ * the transfer fail.
+ */
 export interface PlanningHttpSource {
     source_id: string;
     type: "http";
@@ -511,7 +569,6 @@ export interface TransferPrepareResponse {
     success: boolean;
     transfer_id: string;
     transfer_key?: string;
-    test_mode?: boolean;
     chunk_size?: number;
     total_size?: number;
     total_sources?: number;

package/package.json

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