@beam-network/sdk 0.1.0 → 0.2.0

package/README.md

@@ -34,13 +34,61 @@ const transfer = await beam.createTransfer({
       secret_access_key: "aws-secret-key"
     })
   ],
-  name: "r2-to-s3-report"
+  name: "r2-to-s3-report",
+  testMode: true
 });
 
 const status = await beam.waitForTransfer(transfer.transfer_id);
 console.log(status.status);
 ```
 
-The main `createTransfer` API is provider-aware and strictly typed for S3, R2, and Hippius configs.
+The main `createTransfer` API is provider-aware and strictly typed for S3, R2, S3-compatible, and Hippius configs.
+Use `testMode: true` to create a BeamCore test-mode transfer.
+
+## S3-Compatible Providers
+
+Use `S3CompatibleProviderConfig` for S3-compatible providers with custom
+endpoints, such as Wasabi, MinIO, Backblaze B2 S3 API, DigitalOcean Spaces,
+Scaleway Object Storage, and self-hosted S3-compatible systems.
+
+```ts
+import {
+  BeamClient,
+  S3CompatibleProviderConfig
+} from "@beam-network/sdk";
+
+const beam = new BeamClient({ apiKey: process.env.BEAM_API_KEY! });
+
+await beam.prepareProviderTransfer({
+  sources: [
+    S3CompatibleProviderConfig.create({
+      provider: "wasabi",
+      bucket: "my-bucket",
+      key: "input/file.bin",
+      region: "us-east-1",
+      endpoint_url: "https://s3.us-east-1.wasabisys.com",
+      access_key_id: process.env.WASABI_ACCESS_KEY_ID!,
+      secret_access_key: process.env.WASABI_SECRET_ACCESS_KEY!
+    })
+  ],
+  destinations: [
+    S3CompatibleProviderConfig.create({
+      provider: "minio",
+      bucket: "archive",
+      key: "file.bin",
+      endpoint_url: "https://minio.example.com",
+      force_path_style: true,
+      access_key_id: process.env.MINIO_ACCESS_KEY_ID!,
+      secret_access_key: process.env.MINIO_SECRET_ACCESS_KEY!
+    })
+  ],
+  name: "S3-compatible transfer"
+});
+```
+
+Use `S3ProviderConfig` for ordinary AWS S3 if preferred, and keep using
+`R2ProviderConfig` for existing Cloudflare R2 code. Use
+`S3CompatibleProviderConfig` when a provider needs a custom S3-compatible
+endpoint.
 
 For low-level BeamCore `/transfers/create` calls with raw HTTP-style configs, use `createRawTransfer`.

package/dist/client.js

@@ -112,7 +112,7 @@ export class BeamClient {
                     let upload = multipartUploads.get(multipartKey);
                     if (!upload) {
                         const multipartCreatedAt = nowIso();
-                        if (destination.provider === "hippius") {
+                        if (isHippiusDestination(destination)) {
                             upload = {
                                 destination,
                                 objectKey: finalObjectKey,
@@ -262,12 +262,15 @@ function validateId(value, name) {
 }
 async function abortCreatedUploads(uploads) {
     await Promise.all([...uploads.values()].map(async (upload) => {
-        if (!upload.uploadId || upload.destination.provider === "hippius") {
+        if (!upload.uploadId || isHippiusDestination(upload.destination)) {
             return;
         }
         await abortMultipartUpload(upload.destination, upload.objectKey, upload.uploadId);
     }));
 }
+function isHippiusDestination(destination) {
+    return destination.provider === "hippius" && "api_token" in destination;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/models.d.ts

@@ -54,6 +54,9 @@ export interface RawTransferCreateInput {
     merkleRoot?: string;
     chunkHashes?: string[];
     callbacks?: CallbackConfig[];
+    /**
+     * Maps to BeamCore test_mode.
+     */
     testMode?: boolean;
     progressiveMode?: boolean;
 }
@@ -137,6 +140,20 @@ export interface R2ProviderConfig {
     account_id?: string;
     endpoint_url?: string;
 }
+export interface S3CompatibleProviderConfig {
+    provider: string;
+    driver?: "s3-compatible";
+    id?: string;
+    bucket: string;
+    key: string;
+    region?: string;
+    endpoint_url?: string;
+    access_key_id: string;
+    secret_access_key: string;
+    session_token?: string;
+    force_path_style?: boolean;
+    account_id?: string;
+}
 export interface HippiusProviderConfig {
     provider: "hippius";
     id?: string;
@@ -145,11 +162,12 @@ export interface HippiusProviderConfig {
     api_token: string;
     base_url?: string;
 }
-export type ProviderConfig = S3ProviderConfig | R2ProviderConfig | HippiusProviderConfig;
+export type ProviderConfig = S3ProviderConfig | R2ProviderConfig | S3CompatibleProviderConfig | HippiusProviderConfig;
 export type ProviderSourceConfig = ProviderConfig;
 export type ProviderDestinationConfig = ProviderConfig;
 export type S3ProviderConfigInput = Omit<S3ProviderConfig, "provider">;
 export type R2ProviderConfigInput = Omit<R2ProviderConfig, "provider">;
+export type S3CompatibleProviderConfigInput = Omit<S3CompatibleProviderConfig, "driver">;
 export type HippiusProviderConfigInput = Omit<HippiusProviderConfig, "provider">;
 export declare const S3ProviderConfig: Readonly<{
     create(input: S3ProviderConfigInput): S3ProviderConfig;
@@ -157,6 +175,9 @@ export declare const S3ProviderConfig: Readonly<{
 export declare const R2ProviderConfig: Readonly<{
     create(input: R2ProviderConfigInput): R2ProviderConfig;
 }>;
+export declare const S3CompatibleProviderConfig: Readonly<{
+    create(input: S3CompatibleProviderConfigInput): S3CompatibleProviderConfig;
+}>;
 export declare const HippiusProviderConfig: Readonly<{
     create(input: HippiusProviderConfigInput): HippiusProviderConfig;
 }>;
@@ -164,6 +185,9 @@ export interface ProviderTransferCreateInput {
     sources: ProviderSourceConfig[];
     destinations: ProviderDestinationConfig[];
     name?: string;
+    /**
+     * Maps to BeamCore test_mode.
+     */
     testMode?: boolean;
     expiresIn?: number;
     /**

package/dist/models.js

@@ -13,6 +13,25 @@ export const R2ProviderConfig = Object.freeze({
         return { provider: "r2", ...input };
     }
 });
+export const S3CompatibleProviderConfig = Object.freeze({
+    create(input) {
+        requireFields(input.provider || "s3-compatible", input, [
+            "provider",
+            "bucket",
+            "key",
+            "access_key_id",
+            "secret_access_key"
+        ]);
+        const provider = input.provider.trim().toLowerCase();
+        if (provider === "r2" && !hasText(input.endpoint_url) && !hasText(input.account_id)) {
+            throw new Error("r2 config requires account_id or endpoint_url.");
+        }
+        if (provider !== "s3" && provider !== "r2" && !hasText(input.endpoint_url)) {
+            throw new Error(`${provider} config requires endpoint_url.`);
+        }
+        return { ...input, provider, driver: "s3-compatible" };
+    }
+});
 export const HippiusProviderConfig = Object.freeze({
     create(input) {
         requireFields("hippius", input, ["bucket", "key", "api_token"]);

package/dist/provider-signing.d.ts

@@ -1,4 +1,5 @@
-import type { ChunkDestinationSigningTarget, ChunkSigningPlanItem, PreparedDestination, PreparedHttpSource, ProviderDestinationConfig, ProviderSourceConfig, SignedChunkRoute } from "./models.js";
+import type { ChunkDestinationSigningTarget, ChunkSigningPlanItem, PreparedDestination, PreparedHttpSource, ProviderDestinationConfig, ProviderSourceConfig, R2ProviderConfig, S3CompatibleProviderConfig, S3ProviderConfig, SignedChunkRoute } from "./models.js";
+export type AnyS3CompatibleProviderConfig = S3ProviderConfig | R2ProviderConfig | S3CompatibleProviderConfig;
 export declare function nowIso(): string;
 export declare function expiresAtIso(expiresIn: number): string;
 export declare function prepareProviderSource(source: ProviderSourceConfig, options?: {
@@ -28,3 +29,7 @@ export declare function signDestinationRoute(input: {
     multipartCreatedAt?: string;
     fetchImpl?: typeof fetch;
 }): Promise<SignedChunkRoute>;
+export declare function isS3CompatibleProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is AnyS3CompatibleProviderConfig;
+export declare function s3CompatibleEndpoint(source: AnyS3CompatibleProviderConfig): string | undefined;
+export declare function s3CompatibleRegion(source: AnyS3CompatibleProviderConfig): string;
+export declare function s3CompatibleForcePathStyle(source: AnyS3CompatibleProviderConfig, endpoint?: string | undefined): boolean | undefined;

package/dist/provider-signing.js

@@ -9,37 +9,23 @@ export function expiresAtIso(expiresIn) {
 export async function prepareProviderSource(source, options = {}) {
     const index = options.index ?? 0;
     const expiresIn = options.expiresIn ?? 3600;
-    if (source.provider === "s3") {
-        const client = createS3Client(source);
-        const head = await client.send(new HeadObjectCommand({ Bucket: source.bucket, Key: source.key }));
-        const getUrl = await getSignedUrl(client, new GetObjectCommand({ Bucket: source.bucket, Key: source.key }), { expiresIn });
-        return {
-            source_id: source.id ?? `src_${index}`,
-            type: "http",
-            provider: "s3",
-            url: getUrl,
-            size: Number(head.ContentLength ?? 0),
-            filename: filename(source.key),
-            expires_at: expiresAtIso(expiresIn),
-            metadata: { bucket: source.bucket, key: source.key, region: source.region ?? "us-east-1" }
-        };
-    }
-    if (source.provider === "r2") {
-        const client = createR2Client(source);
+    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 getUrl = await getSignedUrl(client, new GetObjectCommand({ Bucket: source.bucket, Key: source.key }), { expiresIn });
         return {
             source_id: source.id ?? `src_${index}`,
             type: "http",
-            provider: "r2",
+            provider: source.provider,
             url: getUrl,
             size: Number(head.ContentLength ?? 0),
             filename: filename(source.key),
             expires_at: expiresAtIso(expiresIn),
-            metadata: { bucket: source.bucket, key: source.key, endpoint_url: r2Endpoint(source) }
+            metadata: s3CompatibleMetadata(source, endpoint)
         };
     }
-    if (source.provider === "hippius") {
+    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);
@@ -55,45 +41,33 @@ export async function prepareProviderSource(source, options = {}) {
             metadata: { bucket: source.bucket, key: source.key, base_url: baseUrl }
         };
     }
-    return assertNever(source);
+    return unsupportedProviderConfig(source);
 }
 export function prepareProviderDestination(destination, options = {}) {
     const index = options.index ?? 0;
     const destinationId = destination.id ?? `dst_${index}`;
-    if (destination.provider === "s3") {
+    if (isS3CompatibleProvider(destination)) {
+        const endpoint = s3CompatibleEndpoint(destination);
         return {
             destination_id: destinationId,
-            provider: "s3",
+            provider: destination.provider,
             logical_prefix: destination.key,
-            metadata: { bucket: destination.bucket, key: destination.key, region: destination.region ?? "us-east-1" }
+            metadata: s3CompatibleMetadata(destination, endpoint)
         };
     }
-    if (destination.provider === "r2") {
+    if (isHippiusProvider(destination)) {
         return {
             destination_id: destinationId,
-            provider: "r2",
-            logical_prefix: destination.key,
-            metadata: { bucket: destination.bucket, key: destination.key, endpoint_url: r2Endpoint(destination) }
+            provider: "hippius",
+            logical_prefix: destination.key.replace(/\/+$/, ""),
+            metadata: { bucket: destination.bucket, key: destination.key, base_url: destination.base_url ?? "https://api.hippius.com" }
         };
     }
-    return {
-        destination_id: destinationId,
-        provider: "hippius",
-        logical_prefix: destination.key.replace(/\/+$/, ""),
-        metadata: { bucket: destination.bucket, key: destination.key, base_url: destination.base_url ?? "https://api.hippius.com" }
-    };
+    return unsupportedProviderConfig(destination);
 }
 export async function createMultipartUpload(destination, objectKey) {
-    if (destination.provider === "s3") {
-        const client = createS3Client(destination);
-        const response = await client.send(new CreateMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey }));
-        if (!response.UploadId) {
-            throw new Error(`provider did not return UploadId for ${objectKey}`);
-        }
-        return response.UploadId;
-    }
-    if (destination.provider === "r2") {
-        const client = createR2Client(destination);
+    if (isS3CompatibleProvider(destination)) {
+        const client = createS3CompatibleClient(destination);
         const response = await client.send(new CreateMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey }));
         if (!response.UploadId) {
             throw new Error(`provider did not return UploadId for ${objectKey}`);
@@ -103,26 +77,22 @@ export async function createMultipartUpload(destination, objectKey) {
     throw new Error(`multipart upload is not supported for ${destination.provider}`);
 }
 export async function signCompleteMultipartUpload(destination, objectKey, uploadId, expiresIn) {
-    if (destination.provider === "s3" || destination.provider === "r2") {
-        const client = destination.provider === "s3" ? createS3Client(destination) : createR2Client(destination);
+    if (isS3CompatibleProvider(destination)) {
+        const client = createS3CompatibleClient(destination);
         return getSignedUrl(client, new CompleteMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }), { expiresIn });
     }
     throw new Error(`multipart completion is not supported for ${destination.provider}`);
 }
 export async function signAbortMultipartUpload(destination, objectKey, uploadId, expiresIn) {
-    if (destination.provider === "s3" || destination.provider === "r2") {
-        const client = destination.provider === "s3" ? createS3Client(destination) : createR2Client(destination);
+    if (isS3CompatibleProvider(destination)) {
+        const client = createS3CompatibleClient(destination);
         return getSignedUrl(client, new AbortMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }), { expiresIn });
     }
     throw new Error(`multipart abort is not supported for ${destination.provider}`);
 }
 export async function abortMultipartUpload(destination, objectKey, uploadId) {
-    if (destination.provider === "s3") {
-        await createS3Client(destination).send(new AbortMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }));
-        return;
-    }
-    if (destination.provider === "r2") {
-        await createR2Client(destination).send(new AbortMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }));
+    if (isS3CompatibleProvider(destination)) {
+        await createS3CompatibleClient(destination).send(new AbortMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }));
         return;
     }
     throw new Error(`multipart abort is not supported for ${destination.provider}`);
@@ -164,57 +134,88 @@ export async function signDestinationRoute(input) {
     };
 }
 async function signDestinationUrl(input) {
-    switch (input.destination.provider) {
-        case "s3":
-        case "r2": {
-            const client = input.destination.provider === "s3"
-                ? createS3Client(input.destination)
-                : createR2Client(input.destination);
-            if (input.uploadId && input.partNumber) {
-                return getSignedUrl(client, new UploadPartCommand({
-                    Bucket: input.destination.bucket,
-                    Key: input.uploadPartObjectKey,
-                    UploadId: input.uploadId,
-                    PartNumber: input.partNumber
-                }), { expiresIn: input.expiresIn });
-            }
-            return getSignedUrl(client, new PutObjectCommand({ Bucket: input.destination.bucket, Key: input.objectKey }), { expiresIn: input.expiresIn });
+    if (isS3CompatibleProvider(input.destination)) {
+        const client = createS3CompatibleClient(input.destination);
+        if (input.uploadId && input.partNumber) {
+            return getSignedUrl(client, new UploadPartCommand({
+                Bucket: input.destination.bucket,
+                Key: input.uploadPartObjectKey,
+                UploadId: input.uploadId,
+                PartNumber: input.partNumber
+            }), { expiresIn: input.expiresIn });
         }
-        case "hippius":
-            return hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.destination.base_url ?? "https://api.hippius.com", input.destination.api_token, input.destination.bucket, input.objectKey, "put", input.expiresIn);
-        default:
-            return assertNever(input.destination);
+        return getSignedUrl(client, new PutObjectCommand({ Bucket: input.destination.bucket, Key: input.objectKey }), { expiresIn: input.expiresIn });
     }
+    if (isHippiusProvider(input.destination)) {
+        return hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.destination.base_url ?? "https://api.hippius.com", input.destination.api_token, input.destination.bucket, input.objectKey, "put", input.expiresIn);
+    }
+    return unsupportedProviderConfig(input.destination);
 }
-function createS3Client(source) {
+function createS3CompatibleClient(source, endpoint = s3CompatibleEndpoint(source)) {
     return new S3Client({
-        region: source.region ?? "us-east-1",
-        endpoint: source.endpoint_url,
+        region: s3CompatibleRegion(source),
+        endpoint,
+        forcePathStyle: s3CompatibleForcePathStyle(source, endpoint),
         credentials: {
             accessKeyId: source.access_key_id,
             secretAccessKey: source.secret_access_key,
-            sessionToken: source.session_token
+            sessionToken: "session_token" in source ? source.session_token : undefined
         }
     });
 }
-function createR2Client(source) {
-    return new S3Client({
-        region: "auto",
-        endpoint: r2Endpoint(source),
-        credentials: {
-            accessKeyId: source.access_key_id,
-            secretAccessKey: source.secret_access_key
-        }
-    });
+export function isS3CompatibleProvider(config) {
+    if (config.provider === "s3" || config.provider === "r2") {
+        return true;
+    }
+    if ("driver" in config && config.driver === "s3-compatible") {
+        return true;
+    }
+    return "access_key_id" in config && "secret_access_key" in config;
 }
-function r2Endpoint(source) {
-    if (source.endpoint_url) {
+export function s3CompatibleEndpoint(source) {
+    if (hasText(source.endpoint_url)) {
         return source.endpoint_url;
     }
-    if (source.account_id) {
-        return `https://${source.account_id}.r2.cloudflarestorage.com`;
+    if (source.provider === "r2") {
+        if ("account_id" in source && hasText(source.account_id)) {
+            return `https://${source.account_id}.r2.cloudflarestorage.com`;
+        }
+        throw new Error("r2 config requires account_id or endpoint_url.");
+    }
+    if (source.provider !== "s3") {
+        throw new Error(`${source.provider} config requires endpoint_url.`);
+    }
+    return undefined;
+}
+export function s3CompatibleRegion(source) {
+    if ("region" in source && hasText(source.region)) {
+        return source.region;
+    }
+    if (source.provider === "r2") {
+        return "auto";
+    }
+    return "us-east-1";
+}
+export function s3CompatibleForcePathStyle(source, endpoint = s3CompatibleEndpoint(source)) {
+    if ("force_path_style" in source && typeof source.force_path_style === "boolean") {
+        return source.force_path_style;
+    }
+    if (source.provider === "s3") {
+        return undefined;
     }
-    throw new Error("R2 signing requires account_id or endpoint_url");
+    return Boolean(endpoint);
+}
+function s3CompatibleMetadata(source, endpoint = s3CompatibleEndpoint(source)) {
+    return compactMetadata({
+        driver: "s3-compatible",
+        bucket: source.bucket,
+        key: source.key,
+        region: s3CompatibleRegion(source),
+        endpoint_url: endpoint
+    });
+}
+function isHippiusProvider(config) {
+    return config.provider === "hippius" && "api_token" in config;
 }
 async function hippiusPresign(fetchImpl, baseUrl, token, bucket, key, action, expiresIn) {
     const url = new URL(`/api/objectstore/buckets/${bucket}/presigned-url/`, baseUrl);
@@ -245,6 +246,12 @@ async function hippiusObjectSize(fetchImpl, baseUrl, token, bucket, key) {
 function filename(key) {
     return key.split("/").filter(Boolean).at(-1) ?? key;
 }
-function assertNever(value) {
+function compactMetadata(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function unsupportedProviderConfig(value) {
     throw new Error(`Unsupported provider config: ${JSON.stringify(value)}`);
 }

package/package.json

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