@beam-network/sdk 0.2.15 → 0.2.16

package/README.md

@@ -91,4 +91,4 @@ Use `S3ProviderConfig` for ordinary AWS S3 if preferred, and keep using
 `S3CompatibleProviderConfig` when a provider needs a custom S3-compatible
 endpoint.
 
-For low-level BeamCore `/transfers/create` calls with raw HTTP-style configs, use `createRawTransfer`.
+For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport still goes through NATS.

package/dist/client.d.ts

@@ -1,15 +1,18 @@
 import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo } from "./models.js";
-export declare const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
+import { BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
+export { BEAM_DEFAULT_NATS_URL };
 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;
+    readonly natsUrl: string;
     private readonly fetchImpl;
+    private readonly control;
     constructor(options?: BeamClientOptions);
+    close(): Promise<void>;
     createRawTransfer(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
     createTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
@@ -45,7 +48,6 @@ export declare class BeamClient {
         timeoutMs?: number;
         pollIntervalMs?: number;
     }): Promise<TransferStatusInfo>;
-    private request;
 }
 export declare function calculateOptimalChunkSize(totalSize: number): number;
 export declare function buildStagingObjectPrefix(input: {

package/dist/client.js

@@ -1,5 +1,6 @@
 import { abortMultipartUpload, computeChunksContentMd5, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, prepareProviderSourceForPlan, isS3CompatibleProvider, listPartsPageMarker, listPartsVerifyMarker, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
-export const BEAM_DEFAULT_URL = "https://beamcore.b1m.ai";
+import { BeamTransferControl, BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
+export { BEAM_DEFAULT_NATS_URL };
 export class BeamApiError extends Error {
     status;
     body;
@@ -11,26 +12,41 @@ export class BeamApiError extends Error {
     }
 }
 export class BeamClient {
-    baseUrl;
     apiKey;
+    natsUrl;
     fetchImpl;
+    control;
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
         }
-        this.baseUrl = normalizeBaseUrl(resolveBaseUrl(options));
         this.apiKey = options.apiKey;
+        this.natsUrl = options.natsUrl ?? options.natsWsUrl ?? BEAM_DEFAULT_NATS_URL;
+        this.control = new BeamTransferControl({
+            apiKey: this.apiKey,
+            natsUrl: options.natsUrl,
+            natsWsUrl: options.natsWsUrl,
+            environment: options.environment,
+            subjectPrefix: options.transferClientSubjectPrefix,
+            transferRuntimeShardCount: options.transferRuntimeShardCount,
+            requestTimeoutMs: options.requestTimeoutMs,
+            maxPayloadBytes: options.maxPayloadBytes
+        });
         this.fetchImpl = options.fetch ?? globalThis.fetch;
         if (!this.fetchImpl) {
             throw new Error("A fetch implementation is required.");
         }
     }
+    close() {
+        return this.control.close();
+    }
     createRawTransfer(input) {
         const body = compact({
+            transfer_id: newTransferId(),
             sources: input.sources,
             destinations: input.destinations,
             total_size: input.totalSize,
-            chunk_size: input.chunkSize ?? calculateOptimalChunkSize(input.totalSize),
+            chunk_size: input.chunkSize,
             name: input.name,
             merkle_root: input.merkleRoot,
             chunk_hashes: input.chunkHashes,
@@ -40,27 +56,25 @@ export class BeamClient {
             progressive_mode: input.progressiveMode || undefined,
             signed_url_flow: input.signedUrlFlow
         });
-        return this.request("POST", "/transfers/create", body);
+        return this.control.request("transfer.create", body);
     }
     createTransfer(input) {
         return this.prepareProviderTransfer(input);
     }
     transferStatus(transferId) {
         validateId(transferId, "transferId");
-        return this.request("GET", `/transfers/${encodeURIComponent(transferId)}/status`);
+        return this.control.request("transfer.status", { transfer_id: transferId }, transferId);
     }
     distributeTransfer(transferId) {
         validateId(transferId, "transferId");
-        return this.request("POST", "/transfers/distribute", {
-            transfer_id: transferId
-        });
+        return this.control.request("transfer.distribute", { transfer_id: transferId }, transferId);
     }
     cancelTransfer(transferId) {
         validateId(transferId, "transferId");
-        return this.request("DELETE", `/transfers/${encodeURIComponent(transferId)}`);
+        return this.control.request("transfer.cancel", { transfer_id: transferId }, transferId);
     }
     planTransfer(input) {
-        return this.request("POST", "/transfers/plan", compact({
+        return this.control.request("transfer.plan", compact({
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
@@ -71,7 +85,9 @@ export class BeamClient {
         }));
     }
     prepareTransfer(input) {
-        return this.request("POST", "/transfers/prepare", compact({
+        const transferId = newTransferId();
+        return this.control.request("transfer.prepare", compact({
+            transfer_id: transferId,
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
@@ -79,16 +95,33 @@ export class BeamClient {
             experimental: input.experimental || undefined,
             urls_expires_at: input.urlsExpiresAt,
             signed_url_flow: input.signedUrlFlow
-        }));
+        }), transferId);
     }
-    attachSignedUrls(transferId, input) {
+    async attachSignedUrls(transferId, input) {
         validateId(transferId, "transferId");
-        return this.request("POST", "/transfers/attach-signed-urls", compact({
+        const attachmentId = newTransferId();
+        await this.control.request("transfer.attach_signed_urls.begin", compact({
             transfer_id: transferId,
-            chunk_routes: input.chunkRoutes,
-            transfer_key: input.transferKey,
+            attachment_id: attachmentId,
+            total_routes: input.chunkRoutes.length,
             urls_expires_at: input.urlsExpiresAt
-        }));
+        }), transferId);
+        const chunks = this.control.splitRoutesForPayload("transfer.attach_signed_urls.chunk", {
+            transfer_id: transferId,
+            attachment_id: attachmentId
+        }, input.chunkRoutes);
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
+            await this.control.request("transfer.attach_signed_urls.chunk", {
+                transfer_id: transferId,
+                attachment_id: attachmentId,
+                chunk_index: chunkIndex,
+                chunk_routes: chunks[chunkIndex]
+            }, transferId);
+        }
+        return this.control.request("transfer.attach_signed_urls.commit", {
+            transfer_id: transferId,
+            attachment_id: attachmentId
+        }, transferId);
     }
     async prepareProviderTransfer(input) {
         const expiresIn = input.expiresIn ?? 3600;
@@ -409,27 +442,6 @@ export class BeamClient {
             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) : {});
-    }
 }
 function checksumChunksBySource(chunkPlan, destinationsById) {
     const chunksBySource = new Map();
@@ -710,14 +722,11 @@ export function calculateOptimalChunkSize(totalSize) {
     }
     return maxChunk;
 }
-function resolveBaseUrl(options) {
-    if (options.baseUrl) {
-        return options.baseUrl;
-    }
-    return BEAM_DEFAULT_URL;
-}
-function normalizeBaseUrl(value) {
-    return value.replace(/\/+$/, "");
+function newTransferId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.randomUUID)
+        return cryptoApi.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 function compact(input) {
     return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));

package/dist/models.d.ts

@@ -1,7 +1,13 @@
 export type SignedUrlFlow = "signed_url_v1" | "signed_url_v2";
 export interface BeamClientOptions {
     apiKey?: string;
-    baseUrl?: string;
+    natsUrl?: string;
+    natsWsUrl?: string;
+    environment?: string;
+    transferClientSubjectPrefix?: string;
+    transferRuntimeShardCount?: number;
+    requestTimeoutMs?: number;
+    maxPayloadBytes?: number;
     fetch?: typeof fetch;
 }
 export interface SourceConfig {
@@ -71,6 +77,7 @@ export interface RawTransferCreateInput {
 export interface TransferCreateResponse {
     success: boolean;
     transfer_id: string;
+    transfer_key?: string;
     experimental?: boolean;
     total_chunks: number;
     total_sources: number;
@@ -113,11 +120,16 @@ export interface DestinationStatusInfo {
 }
 export interface TransferStatusInfo {
     transfer_id: string;
+    name?: string;
     status: string;
     error_message: string | null;
     experimental?: boolean;
     started_at: string | null;
     completed_at: string | null;
+    total_bytes?: number;
+    total_size?: number;
+    total_chunks?: number;
+    chunks_completed?: number;
 }
 export interface S3ProviderConfig {
     provider: "s3";

package/dist/nats-control.d.ts

@@ -0,0 +1,36 @@
+export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v1";
+export declare const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
+export declare const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
+export type TransferClientMessageType = "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.attach_signed_urls.begin" | "transfer.attach_signed_urls.chunk" | "transfer.attach_signed_urls.commit" | "transfer.distribute" | "transfer.status" | "transfer.cancel";
+export interface TransferControlOptions {
+    apiKey: string;
+    natsUrl?: string;
+    natsWsUrl?: string;
+    environment?: string;
+    subjectPrefix?: string;
+    transferRuntimeShardCount?: number;
+    requestTimeoutMs?: number;
+    maxPayloadBytes?: number;
+}
+export declare class BeamTransferControl {
+    readonly environment: string;
+    readonly keyPrefix: string;
+    readonly shardCount: number;
+    readonly maxPayloadBytes: number;
+    private readonly subjectPrefix;
+    private readonly requestTimeoutMs;
+    private readonly natsUrl;
+    private readonly apiKey;
+    private nc;
+    private authToken;
+    private authTokenExpiresAt;
+    constructor(options: TransferControlOptions);
+    close(): Promise<void>;
+    request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, transferId?: string): Promise<T>;
+    splitRoutesForPayload(messageType: TransferClientMessageType, basePayload: Record<string, unknown>, routes: unknown[]): unknown[][];
+    private connection;
+    private resolveAuthToken;
+    private authSubject;
+    private requestSubject;
+}
+export declare function transferShardId(transferId: string, shardCount: number): number;

package/dist/nats-control.js

@@ -0,0 +1,162 @@
+import { encode, decode } from "@msgpack/msgpack";
+import { connect } from "nats";
+export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v1";
+export const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
+export const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
+export class BeamTransferControl {
+    environment;
+    keyPrefix;
+    shardCount;
+    maxPayloadBytes;
+    subjectPrefix;
+    requestTimeoutMs;
+    natsUrl;
+    apiKey;
+    nc = null;
+    authToken = null;
+    authTokenExpiresAt = 0;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.keyPrefix = options.apiKey.slice(0, 12);
+        this.environment = options.environment ?? "prod";
+        this.subjectPrefix = normalizeSubjectPrefix(options.subjectPrefix ?? "beam.transfer.client");
+        this.shardCount = options.transferRuntimeShardCount ?? 1;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.maxPayloadBytes = options.maxPayloadBytes ?? 6 * 1024 * 1024;
+        this.natsUrl = options.natsUrl ?? options.natsWsUrl ?? BEAM_DEFAULT_NATS_URL;
+        if (/^https?:\/\//i.test(this.natsUrl) || /^wss?:\/\//i.test(this.natsUrl) && !options.natsWsUrl) {
+            throw new Error("Beam SDK lifecycle endpoint must be nats://, tls://, or configured as natsWsUrl.");
+        }
+        if (!Number.isInteger(this.shardCount) || this.shardCount < 1) {
+            throw new Error("transferRuntimeShardCount must be a positive integer.");
+        }
+    }
+    async close() {
+        if (!this.nc)
+            return;
+        await this.nc.drain();
+        this.nc = null;
+    }
+    async request(messageType, payload, transferId) {
+        const nc = await this.connection();
+        const authToken = await this.resolveAuthToken();
+        const shardId = transferId ? transferShardId(transferId, this.shardCount) : 0;
+        const requestId = randomId();
+        const envelope = {
+            message_id: `${TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION}:${this.environment}:${this.keyPrefix}:${messageType}:${requestId}`,
+            schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+            environment: this.environment,
+            key_prefix: this.keyPrefix,
+            shard_id: shardId,
+            message_type: messageType,
+            request_id: requestId,
+            auth_token: authToken,
+            occurred_at: new Date().toISOString(),
+            producer: "sdk",
+            payload
+        };
+        const bytes = encode(envelope);
+        if (bytes.byteLength > this.maxPayloadBytes) {
+            throw new Error(`NATS lifecycle request is ${bytes.byteLength} bytes, above maxPayloadBytes=${this.maxPayloadBytes}`);
+        }
+        const subject = this.requestSubject(messageType, shardId);
+        const response = await nc.request(subject, bytes, { timeout: this.requestTimeoutMs });
+        const decoded = decode(response.data);
+        if (!decoded.ok) {
+            const body = JSON.stringify(decoded.error ?? {});
+            throw new Error(`Beam lifecycle request failed with ${decoded.status}: ${body}`);
+        }
+        return (decoded.payload ?? {});
+    }
+    splitRoutesForPayload(messageType, basePayload, routes) {
+        const chunks = [];
+        let current = [];
+        for (const route of routes) {
+            const candidate = [...current, route];
+            const encoded = encode({
+                schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+                environment: this.environment,
+                key_prefix: this.keyPrefix,
+                shard_id: 0,
+                message_type: messageType,
+                request_id: randomId(),
+                auth_token: "x".repeat(512),
+                occurred_at: new Date().toISOString(),
+                producer: "sdk",
+                payload: { ...basePayload, chunk_routes: candidate }
+            });
+            if (current.length > 0 && encoded.byteLength > this.maxPayloadBytes) {
+                chunks.push(current);
+                current = [route];
+            }
+            else {
+                current = candidate;
+            }
+        }
+        if (current.length > 0)
+            chunks.push(current);
+        return chunks;
+    }
+    async connection() {
+        if (this.nc && !this.nc.isClosed())
+            return this.nc;
+        this.nc = await connect({
+            servers: this.natsUrl,
+            user: this.keyPrefix,
+            pass: this.apiKey,
+            name: `beam-sdk-${this.keyPrefix}`
+        });
+        return this.nc;
+    }
+    async resolveAuthToken() {
+        const now = Math.floor(Date.now() / 1000);
+        if (this.authToken && this.authTokenExpiresAt - 5 > now)
+            return this.authToken;
+        const nc = await this.connection();
+        const response = await nc.request(this.authSubject(), new TextEncoder().encode("{}"), { timeout: this.requestTimeoutMs });
+        const parsed = JSON.parse(new TextDecoder().decode(response.data));
+        if (!parsed.ok || !parsed.token) {
+            throw new Error(`Beam SDK NATS auth resolve failed: ${parsed.error ?? "unknown_error"}`);
+        }
+        const claims = decodeJwtPayload(parsed.token);
+        this.authToken = parsed.token;
+        this.authTokenExpiresAt = claims.exp;
+        return parsed.token;
+    }
+    authSubject() {
+        return `${this.subjectPrefix}.${this.environment}.auth.${this.keyPrefix}.resolve`;
+    }
+    requestSubject(messageType, shardId) {
+        return `${this.subjectPrefix}.${this.environment}.sdk.${this.keyPrefix}.shard.${shardId}.${messageType.replace(/\./g, "_")}`;
+    }
+}
+export function transferShardId(transferId, shardCount) {
+    let hash = 2166136261;
+    for (let i = 0; i < transferId.length; i += 1) {
+        hash ^= transferId.charCodeAt(i);
+        hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    return hash % shardCount;
+}
+function decodeJwtPayload(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2)
+        throw new Error("invalid JWT");
+    return JSON.parse(base64UrlDecode(parts[1]));
+}
+function base64UrlDecode(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(padded, "base64").toString("utf8");
+    return atob(padded);
+}
+function normalizeSubjectPrefix(value) {
+    return value.replace(/^\.+|\.+$/g, "");
+}
+function randomId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.randomUUID)
+        return cryptoApi.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}

package/package.json

@@ -1,36 +1,38 @@
 {
-  "name": "@beam-network/sdk",
-  "version": "0.2.15",
-  "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"
-  }
+    "name":  "@beam-network/sdk",
+    "version":  "0.2.16",
+    "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 \u0026\u0026 npm run test:functional",
+                    "test:functional":  "npm run build \u0026\u0026 node --test test/client.functional.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",
+                         "@msgpack/msgpack":  "^3.0.0",
+                         "nats":  "^2.29.3"
+                     },
+    "devDependencies":  {
+                            "typescript":  "^5.5.0"
+                        }
 }