@beam-network/sdk 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# BEAM SDK for TypeScript
+
+Install:
+
+```bash
+npm install @beam-network/sdk
+```
+
+Example:
+
+```ts
+import { BeamClient, R2ProviderConfig, S3ProviderConfig } from "@beam-network/sdk";
+
+const beam = new BeamClient({
+  apiKey: "bk_your_key"
+});
+
+const transfer = await beam.createTransfer({
+  sources: [
+    R2ProviderConfig.create({
+      bucket: "source-bucket",
+      key: "exports/report.parquet",
+      account_id: "cloudflare-account-id",
+      access_key_id: "r2-access-key",
+      secret_access_key: "r2-secret-key"
+    })
+  ],
+  destinations: [
+    S3ProviderConfig.create({
+      bucket: "destination-bucket",
+      key: "imports/report.parquet",
+      region: "us-east-1",
+      access_key_id: "aws-access-key",
+      secret_access_key: "aws-secret-key"
+    })
+  ],
+  name: "r2-to-s3-report"
+});
+
+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.
+
+For low-level BeamCore `/transfers/create` calls with raw HTTP-style configs, use `createRawTransfer`.

package/dist/client.d.ts

@@ -0,0 +1,38 @@
+import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, TransferCancelResponse, TransferCreateResponse, TransferPrepareResponse, TransferStatusInfo } from "./models.js";
+export declare const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
+export declare class BeamApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export declare class BeamClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    private readonly fetchImpl;
+    constructor(options?: BeamClientOptions);
+    createRawTransfer(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
+    createTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
+    transferStatus(transferId: string): Promise<TransferStatusInfo>;
+    distributeTransfer(transferId: string): Promise<DistributeResponse>;
+    cancelTransfer(transferId: string): Promise<TransferCancelResponse>;
+    prepareTransfer(input: {
+        sources: PreparedHttpSource[];
+        destinations: PreparedDestination[];
+        name?: string;
+        testMode?: boolean;
+        urlsExpiresAt?: string;
+    }): Promise<TransferPrepareResponse>;
+    attachSignedUrls(transferId: string, input: {
+        chunkRoutes: SignedChunkRoute[];
+        transferKey?: string;
+        urlsExpiresAt?: string;
+    }): Promise<AttachSignedUrlsResponse>;
+    prepareProviderTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
+    createAndDistribute(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
+    waitForTransfer(transferId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<TransferStatusInfo>;
+    private request;
+}
+export declare function calculateOptimalChunkSize(totalSize: number): number;

package/dist/client.js

@@ -0,0 +1,273 @@
+import { abortMultipartUpload, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationRoute } from "./provider-signing.js";
+export const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
+export class BeamApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "BeamApiError";
+    }
+}
+export class BeamClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(options = {}) {
+        if (!options.apiKey?.trim()) {
+            throw new Error("apiKey is required.");
+        }
+        this.baseUrl = normalizeBaseUrl(resolveBaseUrl(options));
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("A fetch implementation is required.");
+        }
+    }
+    createRawTransfer(input) {
+        const body = compact({
+            sources: input.sources,
+            destinations: input.destinations,
+            total_size: input.totalSize,
+            chunk_size: input.chunkSize ?? calculateOptimalChunkSize(input.totalSize),
+            name: input.name,
+            merkle_root: input.merkleRoot,
+            chunk_hashes: input.chunkHashes,
+            callbacks: input.callbacks,
+            test_mode: input.testMode || undefined,
+            progressive_mode: input.progressiveMode || undefined
+        });
+        return this.request("POST", "/transfers/create", body);
+    }
+    createTransfer(input) {
+        return this.prepareProviderTransfer(input);
+    }
+    transferStatus(transferId) {
+        validateId(transferId, "transferId");
+        return this.request("GET", `/transfers/${encodeURIComponent(transferId)}/status`);
+    }
+    distributeTransfer(transferId) {
+        validateId(transferId, "transferId");
+        return this.request("POST", "/transfers/distribute", {
+            transfer_id: transferId
+        });
+    }
+    cancelTransfer(transferId) {
+        validateId(transferId, "transferId");
+        return this.request("DELETE", `/transfers/${encodeURIComponent(transferId)}`);
+    }
+    prepareTransfer(input) {
+        return this.request("POST", "/transfers/prepare", compact({
+            sources: input.sources,
+            destinations: input.destinations,
+            name: input.name,
+            test_mode: input.testMode || undefined,
+            urls_expires_at: input.urlsExpiresAt
+        }));
+    }
+    attachSignedUrls(transferId, input) {
+        validateId(transferId, "transferId");
+        return this.request("POST", "/transfers/attach-signed-urls", compact({
+            transfer_id: transferId,
+            chunk_routes: input.chunkRoutes,
+            transfer_key: input.transferKey,
+            urls_expires_at: input.urlsExpiresAt
+        }));
+    }
+    async prepareProviderTransfer(input) {
+        const expiresIn = input.expiresIn ?? 3600;
+        const preparedSources = await Promise.all(input.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
+        const preparedDestinations = input.destinations.map((destination, index) => prepareProviderDestination(destination, { index }));
+        const prepared = await this.prepareTransfer({
+            sources: preparedSources,
+            destinations: preparedDestinations,
+            name: input.name,
+            testMode: input.testMode
+        });
+        if (!prepared.success) {
+            return prepared;
+        }
+        const destinationsById = new Map();
+        preparedDestinations.forEach((preparedDestination, index) => {
+            destinationsById.set(preparedDestination.destination_id, input.destinations[index]);
+        });
+        const routes = [];
+        const multipartUploads = new Map();
+        try {
+            for (const chunk of prepared.chunk_plan) {
+                for (const target of chunk.destinations) {
+                    const destination = destinationsById.get(target.destination_id);
+                    if (!destination) {
+                        throw new Error(`BeamCore returned unknown destination_id: ${target.destination_id}`);
+                    }
+                    const metadata = target.metadata ?? {};
+                    const finalObjectKey = typeof metadata.final_object_key === "string"
+                        ? metadata.final_object_key
+                        : target.object_key;
+                    if (!finalObjectKey) {
+                        throw new Error("destination signing target is missing object_key");
+                    }
+                    const multipartKey = `${prepared.transfer_id}:${target.destination_id}:${chunk.source_id}:${finalObjectKey}`;
+                    let upload = multipartUploads.get(multipartKey);
+                    if (!upload) {
+                        const multipartCreatedAt = nowIso();
+                        if (destination.provider === "hippius") {
+                            upload = {
+                                destination,
+                                objectKey: finalObjectKey,
+                                uploadId: "",
+                                completeUrl: "",
+                                abortUrl: "",
+                                multipartGroupId: multipartKey,
+                                multipartCreatedAt
+                            };
+                        }
+                        else {
+                            const uploadId = await createMultipartUpload(destination, finalObjectKey);
+                            upload = {
+                                destination,
+                                objectKey: finalObjectKey,
+                                uploadId,
+                                completeUrl: await signCompleteMultipartUpload(destination, finalObjectKey, uploadId, expiresIn),
+                                abortUrl: await signAbortMultipartUpload(destination, finalObjectKey, uploadId, expiresIn),
+                                multipartGroupId: multipartKey,
+                                multipartCreatedAt
+                            };
+                        }
+                        multipartUploads.set(multipartKey, upload);
+                    }
+                    routes.push(await signDestinationRoute({
+                        chunk,
+                        target,
+                        destination,
+                        expiresIn,
+                        uploadId: upload.uploadId,
+                        partNumber: typeof metadata.part_number === "number"
+                            ? metadata.part_number
+                            : chunk.source_chunk_index + 1,
+                        multipartObjectKey: finalObjectKey,
+                        completeUrl: upload.completeUrl,
+                        abortUrl: upload.abortUrl,
+                        transferId: prepared.transfer_id,
+                        multipartGroupId: upload.multipartGroupId,
+                        multipartCreatedAt: upload.multipartCreatedAt,
+                        fetchImpl: this.fetchImpl
+                    }));
+                }
+            }
+        }
+        catch (error) {
+            await abortCreatedUploads(multipartUploads);
+            throw error;
+        }
+        try {
+            const attached = await this.attachSignedUrls(prepared.transfer_id, {
+                chunkRoutes: routes,
+                transferKey: prepared.transfer_key
+            });
+            if (!attached.success) {
+                throw new Error(attached.error ?? attached.message ?? "attach signed URLs failed");
+            }
+        }
+        catch (error) {
+            await abortCreatedUploads(multipartUploads);
+            throw error;
+        }
+        if (input.distribute !== false) {
+            await this.distributeTransfer(prepared.transfer_id);
+        }
+        return prepared;
+    }
+    async createAndDistribute(input) {
+        const transfer = await this.createRawTransfer(input);
+        if (transfer.success) {
+            await this.distributeTransfer(transfer.transfer_id);
+        }
+        return transfer;
+    }
+    async waitForTransfer(transferId, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 300_000;
+        const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+        const startedAt = Date.now();
+        while (true) {
+            const status = await this.transferStatus(transferId);
+            if (status.status === "completed") {
+                return status;
+            }
+            if (status.status === "failed") {
+                throw new Error(`Transfer failed: ${status.error_message ?? "unknown error"}`);
+            }
+            if (status.status === "cancelled") {
+                throw new Error("Transfer cancelled");
+            }
+            if (Date.now() - startedAt >= timeoutMs) {
+                throw new Error(`Transfer ${transferId} did not complete within ${timeoutMs}ms`);
+            }
+            await sleep(pollIntervalMs);
+        }
+    }
+    async request(method, path, body) {
+        const headers = {
+            Accept: "application/json",
+            "X-Api-Key": this.apiKey
+        };
+        let payload;
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(body);
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: payload
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new BeamApiError(`BEAM API request failed with ${response.status}`, response.status, text);
+        }
+        return (text ? JSON.parse(text) : {});
+    }
+}
+export function calculateOptimalChunkSize(totalSize) {
+    const mb = 1024 * 1024;
+    const gb = 1024 * mb;
+    const minChunk = 5 * mb;
+    const maxChunk = 5 * mb;
+    const targetChunks = 10;
+    if (totalSize <= minChunk) {
+        return totalSize;
+    }
+    if (totalSize < gb) {
+        return Math.max(minChunk, Math.min(maxChunk, Math.floor(totalSize / targetChunks)));
+    }
+    return maxChunk;
+}
+function resolveBaseUrl(options) {
+    if (options.baseUrl) {
+        return options.baseUrl;
+    }
+    return BEAM_DEFAULT_URL;
+}
+function normalizeBaseUrl(value) {
+    return value.replace(/\/+$/, "");
+}
+function compact(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function validateId(value, name) {
+    if (!value || value.includes("/") || value.includes("..")) {
+        throw new Error(`${name} is invalid`);
+    }
+}
+async function abortCreatedUploads(uploads) {
+    await Promise.all([...uploads.values()].map(async (upload) => {
+        if (!upload.uploadId || upload.destination.provider === "hippius") {
+            return;
+        }
+        await abortMultipartUpload(upload.destination, upload.objectKey, upload.uploadId);
+    }));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./models.js";
+export * from "./provider-signing.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./models.js";
+export * from "./provider-signing.js";

package/dist/models.d.ts

@@ -0,0 +1,241 @@
+export interface BeamClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface SourceConfig {
+    type: string;
+    bucket?: string;
+    key?: string;
+    region?: string;
+    project_id?: string;
+    account_id?: string;
+    endpoint_url?: string;
+    access_key_id?: string;
+    secret_access_key?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}
+export interface DestConfig {
+    type: string;
+    bucket?: string;
+    key?: string;
+    region?: string;
+    project_id?: string;
+    account_id?: string;
+    endpoint_url?: string;
+    access_key_id?: string;
+    secret_access_key?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}
+export interface CallbackConfig {
+    url: string;
+    headers?: Record<string, string>;
+}
+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;
+}
+export interface RawTransferCreateInput {
+    sources: SourceConfig[];
+    destinations: DestConfig[];
+    totalSize: number;
+    chunkSize?: number;
+    name?: string;
+    merkleRoot?: string;
+    chunkHashes?: string[];
+    callbacks?: CallbackConfig[];
+    testMode?: boolean;
+    progressiveMode?: boolean;
+}
+export interface TransferCreateResponse {
+    success: boolean;
+    transfer_id: string;
+    total_chunks: number;
+    total_sources: number;
+    total_destinations: number;
+    source_urls?: Array<Record<string, string>>;
+    dest_urls?: Array<Record<string, string>>;
+    upload_ids?: Array<string | null>;
+    error?: string;
+    message?: string;
+}
+export interface TransferCancelResponse {
+    success: boolean;
+    message?: string;
+}
+export interface DistributeResponse {
+    success: boolean;
+    transfer_id: string;
+    orchestrators_assigned?: number;
+    message?: string;
+    error?: string;
+}
+export interface SourceStatusInfo {
+    source_index: number;
+    source_type: string;
+    bucket?: string;
+    key?: string;
+    region?: string;
+}
+export interface DestinationStatusInfo {
+    dest_index: number;
+    dest_type: string;
+    status: string;
+    chunks_delivered?: number;
+    chunks_pending?: number;
+    chunks_in_progress?: number;
+    chunks_completed?: number;
+    chunks_failed?: number;
+    bytes_delivered?: number;
+    location?: string;
+}
+export interface TransferStatusInfo {
+    transfer_id: string;
+    name?: string;
+    status: string;
+    total_size: number;
+    total_chunks: number;
+    total_sources?: number;
+    total_destinations?: number;
+    chunks_completed?: number;
+    destinations_completed?: number;
+    sources?: SourceStatusInfo[];
+    destinations?: DestinationStatusInfo[];
+    created_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    error_message?: string;
+}
+export interface S3ProviderConfig {
+    provider: "s3";
+    id?: string;
+    bucket: string;
+    key: string;
+    region?: string;
+    access_key_id: string;
+    secret_access_key: string;
+    session_token?: string;
+    endpoint_url?: string;
+}
+export interface R2ProviderConfig {
+    provider: "r2";
+    id?: string;
+    bucket: string;
+    key: string;
+    access_key_id: string;
+    secret_access_key: string;
+    account_id?: string;
+    endpoint_url?: string;
+}
+export interface HippiusProviderConfig {
+    provider: "hippius";
+    id?: string;
+    bucket: string;
+    key: string;
+    api_token: string;
+    base_url?: string;
+}
+export type ProviderConfig = S3ProviderConfig | R2ProviderConfig | HippiusProviderConfig;
+export type ProviderSourceConfig = ProviderConfig;
+export type ProviderDestinationConfig = ProviderConfig;
+export type S3ProviderConfigInput = Omit<S3ProviderConfig, "provider">;
+export type R2ProviderConfigInput = Omit<R2ProviderConfig, "provider">;
+export type HippiusProviderConfigInput = Omit<HippiusProviderConfig, "provider">;
+export declare const S3ProviderConfig: Readonly<{
+    create(input: S3ProviderConfigInput): S3ProviderConfig;
+}>;
+export declare const R2ProviderConfig: Readonly<{
+    create(input: R2ProviderConfigInput): R2ProviderConfig;
+}>;
+export declare const HippiusProviderConfig: Readonly<{
+    create(input: HippiusProviderConfigInput): HippiusProviderConfig;
+}>;
+export interface ProviderTransferCreateInput {
+    sources: ProviderSourceConfig[];
+    destinations: ProviderDestinationConfig[];
+    name?: string;
+    testMode?: boolean;
+    expiresIn?: number;
+    /**
+     * Defaults to true. Set to false to only prepare and attach signed URLs.
+     */
+    distribute?: boolean;
+}
+export interface PreparedHttpSource {
+    source_id: string;
+    type: "http";
+    provider?: string;
+    url: string;
+    size: number;
+    filename?: string;
+    headers?: Record<string, string>;
+    expires_at?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PreparedDestination {
+    destination_id: string;
+    provider: string;
+    mode?: "object_chunks" | "http_chunks";
+    logical_prefix?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ChunkDestinationSigningTarget {
+    destination_id: string;
+    provider?: string;
+    object_key?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ChunkSigningPlanItem {
+    chunk_index: number;
+    source_id: string;
+    source_chunk_index: number;
+    source_offset: number;
+    chunk_size: number;
+    source_url: string;
+    destinations: ChunkDestinationSigningTarget[];
+}
+export interface SignedChunkRoute {
+    source_id: string;
+    destination_id: string;
+    chunk_index: number;
+    source_url: string;
+    dest_url: string;
+    source_offset: number;
+    chunk_size: number;
+    expires_at?: string;
+    headers?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+export interface TransferPrepareResponse {
+    success: boolean;
+    transfer_id: string;
+    transfer_key?: string;
+    test_mode?: boolean;
+    chunk_size?: number;
+    total_size?: number;
+    total_sources?: number;
+    total_destinations?: number;
+    logical_chunks?: number;
+    total_chunks?: number;
+    chunk_plan: ChunkSigningPlanItem[];
+    error?: string;
+    message?: string;
+}
+export interface AttachSignedUrlsResponse {
+    success: boolean;
+    transfer_id: string;
+    total_routes?: number;
+    urls_expires_at?: string;
+    error?: string;
+    message?: string;
+}

package/dist/models.js

@@ -0,0 +1,31 @@
+export const S3ProviderConfig = Object.freeze({
+    create(input) {
+        requireFields("s3", input, ["bucket", "key", "access_key_id", "secret_access_key"]);
+        return { provider: "s3", ...input };
+    }
+});
+export const R2ProviderConfig = Object.freeze({
+    create(input) {
+        requireFields("r2", input, ["bucket", "key", "access_key_id", "secret_access_key"]);
+        if (!hasText(input.account_id) && !hasText(input.endpoint_url)) {
+            throw new Error("r2 config requires account_id or endpoint_url.");
+        }
+        return { provider: "r2", ...input };
+    }
+});
+export const HippiusProviderConfig = Object.freeze({
+    create(input) {
+        requireFields("hippius", input, ["bucket", "key", "api_token"]);
+        return { provider: "hippius", ...input };
+    }
+});
+function requireFields(provider, input, fields) {
+    for (const field of fields) {
+        if (!hasText(input[field])) {
+            throw new Error(`${provider} config requires ${field}.`);
+        }
+    }
+}
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/provider-signing.d.ts

@@ -0,0 +1,30 @@
+import type { ChunkDestinationSigningTarget, ChunkSigningPlanItem, PreparedDestination, PreparedHttpSource, ProviderDestinationConfig, ProviderSourceConfig, SignedChunkRoute } from "./models.js";
+export declare function nowIso(): string;
+export declare function expiresAtIso(expiresIn: number): string;
+export declare function prepareProviderSource(source: ProviderSourceConfig, options?: {
+    index?: number;
+    expiresIn?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<PreparedHttpSource>;
+export declare function prepareProviderDestination(destination: ProviderDestinationConfig, options?: {
+    index?: number;
+}): PreparedDestination;
+export declare function createMultipartUpload(destination: ProviderDestinationConfig, objectKey: string): Promise<string>;
+export declare function signCompleteMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number): Promise<string>;
+export declare function signAbortMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number): Promise<string>;
+export declare function abortMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string): Promise<void>;
+export declare function signDestinationRoute(input: {
+    chunk: ChunkSigningPlanItem;
+    target: ChunkDestinationSigningTarget;
+    destination: ProviderDestinationConfig;
+    expiresIn: number;
+    uploadId?: string;
+    partNumber?: number;
+    multipartObjectKey?: string;
+    completeUrl?: string;
+    abortUrl?: string;
+    transferId?: string;
+    multipartGroupId?: string;
+    multipartCreatedAt?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<SignedChunkRoute>;

package/dist/provider-signing.js

@@ -0,0 +1,250 @@
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, UploadPartCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function expiresAtIso(expiresIn) {
+    return new Date(Date.now() + expiresIn * 1000).toISOString();
+}
+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);
+        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",
+            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) }
+        };
+    }
+    if (source.provider === "hippius") {
+        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);
+        return {
+            source_id: source.id ?? `src_${index}`,
+            type: "http",
+            provider: "hippius",
+            url,
+            size,
+            filename: filename(source.key),
+            expires_at: expiresAtIso(expiresIn),
+            metadata: { bucket: source.bucket, key: source.key, base_url: baseUrl }
+        };
+    }
+    return assertNever(source);
+}
+export function prepareProviderDestination(destination, options = {}) {
+    const index = options.index ?? 0;
+    const destinationId = destination.id ?? `dst_${index}`;
+    if (destination.provider === "s3") {
+        return {
+            destination_id: destinationId,
+            provider: "s3",
+            logical_prefix: destination.key,
+            metadata: { bucket: destination.bucket, key: destination.key, region: destination.region ?? "us-east-1" }
+        };
+    }
+    if (destination.provider === "r2") {
+        return {
+            destination_id: destinationId,
+            provider: "r2",
+            logical_prefix: destination.key,
+            metadata: { bucket: destination.bucket, key: destination.key, endpoint_url: r2Endpoint(destination) }
+        };
+    }
+    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" }
+    };
+}
+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);
+        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;
+    }
+    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);
+        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);
+        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 }));
+        return;
+    }
+    throw new Error(`multipart abort is not supported for ${destination.provider}`);
+}
+export async function signDestinationRoute(input) {
+    const objectKey = input.target.object_key;
+    if (!objectKey) {
+        throw new Error("destination signing target is missing object_key");
+    }
+    const uploadPartObjectKey = input.multipartObjectKey ?? objectKey;
+    const destUrl = await signDestinationUrl({
+        destination: input.destination,
+        objectKey,
+        uploadPartObjectKey,
+        expiresIn: input.expiresIn,
+        uploadId: input.uploadId,
+        partNumber: input.partNumber,
+        fetchImpl: input.fetchImpl
+    });
+    return {
+        source_id: input.chunk.source_id,
+        destination_id: input.target.destination_id,
+        chunk_index: input.chunk.chunk_index,
+        source_url: input.chunk.source_url,
+        dest_url: destUrl,
+        source_offset: input.chunk.source_offset,
+        chunk_size: input.chunk.chunk_size,
+        expires_at: expiresAtIso(input.expiresIn),
+        metadata: {
+            ...(input.target.metadata ?? {}),
+            ...(input.transferId ? { transfer_id: input.transferId } : {}),
+            ...(input.multipartGroupId ? { multipart_group_id: input.multipartGroupId } : {}),
+            ...(input.multipartCreatedAt ? { multipart_created_at: input.multipartCreatedAt } : {}),
+            ...(input.uploadId ? { upload_id: input.uploadId } : {}),
+            ...(input.partNumber ? { part_number: input.partNumber } : {}),
+            ...(input.completeUrl ? { complete_url: input.completeUrl } : {}),
+            ...(input.abortUrl ? { abort_url: input.abortUrl } : {})
+        }
+    };
+}
+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 });
+        }
+        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);
+    }
+}
+function createS3Client(source) {
+    return new S3Client({
+        region: source.region ?? "us-east-1",
+        endpoint: source.endpoint_url,
+        credentials: {
+            accessKeyId: source.access_key_id,
+            secretAccessKey: source.secret_access_key,
+            sessionToken: source.session_token
+        }
+    });
+}
+function createR2Client(source) {
+    return new S3Client({
+        region: "auto",
+        endpoint: r2Endpoint(source),
+        credentials: {
+            accessKeyId: source.access_key_id,
+            secretAccessKey: source.secret_access_key
+        }
+    });
+}
+function r2Endpoint(source) {
+    if (source.endpoint_url) {
+        return source.endpoint_url;
+    }
+    if (source.account_id) {
+        return `https://${source.account_id}.r2.cloudflarestorage.com`;
+    }
+    throw new Error("R2 signing requires account_id or endpoint_url");
+}
+async function hippiusPresign(fetchImpl, baseUrl, token, bucket, key, action, expiresIn) {
+    const url = new URL(`/api/objectstore/buckets/${bucket}/presigned-url/`, baseUrl);
+    url.searchParams.set("key", key);
+    url.searchParams.set("action", action);
+    url.searchParams.set("expires_in", String(expiresIn));
+    const response = await fetchImpl(url, { headers: { Authorization: `Token ${token}` } });
+    if (!response.ok) {
+        throw new Error(`Hippius presigned URL failed with ${response.status}: ${await response.text()}`);
+    }
+    return String((await response.json()).url);
+}
+async function hippiusObjectSize(fetchImpl, baseUrl, token, bucket, key) {
+    const url = new URL(`/api/objectstore/buckets/${bucket}/objects/`, baseUrl);
+    url.searchParams.set("prefix", key);
+    url.searchParams.set("max_keys", "1");
+    const response = await fetchImpl(url, { headers: { Authorization: `Token ${token}` } });
+    if (!response.ok) {
+        throw new Error(`Hippius object lookup failed with ${response.status}: ${await response.text()}`);
+    }
+    const payload = await response.json();
+    const contents = payload.Contents ?? payload.contents ?? [];
+    if (!contents.length) {
+        throw new Error(`Object not found: hippius://${bucket}/${key}`);
+    }
+    return Number(contents[0].Size ?? contents[0].size);
+}
+function filename(key) {
+    return key.split("/").filter(Boolean).at(-1) ?? key;
+}
+function assertNever(value) {
+    throw new Error(`Unsupported provider config: ${JSON.stringify(value)}`);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@beam-network/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for BEAM transfer creation and management.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json --noEmit && npm run test:functional",
+    "test:functional": "npm run build && node --test test/*.test.mjs",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.806.0",
+    "@aws-sdk/s3-request-presigner": "^3.806.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}