@beam-network/sdk 0.2.15 → 0.2.17

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 {
@@ -44,7 +50,6 @@ export interface TransferCreateRequest {
     chunk_hashes?: string[];
     callbacks?: CallbackConfig[];
     test_mode?: boolean;
-    experimental?: boolean;
     progressive_mode?: boolean;
     signed_url_flow?: SignedUrlFlow;
 }
@@ -61,17 +66,13 @@ export interface RawTransferCreateInput {
      * Maps to BeamCore test_mode.
      */
     testMode?: boolean;
-    /**
-     * Experimental transfers keep positive evidence but exclude failures and overseer interventions from PRISM.
-     */
-    experimental?: boolean;
     progressiveMode?: boolean;
     signedUrlFlow?: SignedUrlFlow;
 }
 export interface TransferCreateResponse {
     success: boolean;
     transfer_id: string;
-    experimental?: boolean;
+    transfer_key?: string;
     total_chunks: number;
     total_sources: number;
     total_destinations: number;
@@ -113,11 +114,15 @@ 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";
@@ -164,26 +169,6 @@ export interface HippiusProviderConfig {
 }
 export type ProviderConfig = S3ProviderConfig | R2ProviderConfig | S3CompatibleProviderConfig | HippiusProviderConfig;
 export type ProviderSourceConfig = ProviderConfig;
-export interface ChunkChecksumProviderGetInput {
-    source: ProviderSourceConfig;
-    chunk: ChunkSigningPlanItem;
-    algorithm: "content-md5";
-}
-export interface ChunkChecksumProviderSetInput extends ChunkChecksumProviderGetInput {
-    contentMd5: string;
-}
-export interface ChunkChecksumProvider {
-    getContentMd5(input: ChunkChecksumProviderGetInput): Promise<string | null | undefined>;
-    setContentMd5?(input: ChunkChecksumProviderSetInput): Promise<void>;
-}
-export interface ChunkChecksumEvent {
-    event: "checksum_warmup_started" | "checksum_warmup_completed" | "checksum_cache_hit" | "checksum_cache_miss" | "checksum_cold_chunk_cached" | "checksum_cold_group_completed";
-    sourceId: string;
-    sourceChunkIndex?: number;
-    chunkCount?: number;
-    bytes?: number;
-    durationMs?: number;
-}
 export type ProviderDestinationConfig = ProviderConfig;
 export type S3ProviderConfigInput = Omit<S3ProviderConfig, "provider">;
 export type R2ProviderConfigInput = Omit<R2ProviderConfig, "provider">;
@@ -209,25 +194,15 @@ export interface ProviderTransferCreateInput {
      * Maps to BeamCore test_mode.
      */
     testMode?: boolean;
-    /**
-     * Experimental transfers keep positive evidence but exclude failures and overseer interventions from PRISM.
-     */
-    experimental?: boolean;
     expiresIn?: number;
     /**
-     * Defaults to true. Set to false to only prepare and attach signed URLs.
+     * Defaults to true. Set to false to only prepare and stream signed routes without distribution.
      */
     distribute?: boolean;
-    onPlanned?: (plan: TransferPlanResponse) => void | Promise<void>;
     onBeforeTransferPrepare?: () => void | Promise<void>;
     onPrepared?: (prepared: TransferPrepareResponse) => void | Promise<void>;
     throwIfCancelled?: (transferId?: string) => void | Promise<void>;
     signedUrlFlow?: SignedUrlFlow;
-    checksumProvider?: ChunkChecksumProvider;
-    checksumReadConcurrency?: number;
-    checksumGroupSizeBytes?: number;
-    checksumReadTimeoutMs?: number;
-    onChecksumEvent?: (event: ChunkChecksumEvent) => void | Promise<void>;
 }
 export interface PlanningHttpSource {
     source_id: string;
@@ -296,7 +271,6 @@ export interface TransferPrepareResponse {
     transfer_id: string;
     transfer_key?: string;
     test_mode?: boolean;
-    experimental?: boolean;
     chunk_size?: number;
     total_size?: number;
     total_sources?: number;

package/dist/nats-control.d.ts

@@ -0,0 +1,72 @@
+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 declare const BEAM_DEFAULT_MAX_PAYLOAD_BYTES: number;
+export declare const ROUTE_RECOVERY_SIGN_MESSAGE_TYPE = "transfer.route_recovery.sign";
+export type TransferClientMessageType = "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.route_stream.begin" | "transfer.route_stream.batch" | "transfer.route_stream.complete" | "transfer.distribute" | "transfer.status" | "transfer.cancel";
+export interface RouteRecoverySignChunk {
+    source_id: string;
+    destination_id: string;
+    chunk_index: number;
+    delivery_index: number;
+    source_offset: number;
+    chunk_size: number;
+    logical_attempt_index: number;
+    attempt_slot: 0 | 1 | 2;
+    part_number: number;
+    route_generation_id: string;
+    multipart_group_id: string;
+    final_object_key: string;
+    upload_id?: string;
+    urls_expires_at?: string;
+    multipart_created_at?: string;
+    source_metadata?: Record<string, unknown>;
+    destination_metadata?: Record<string, unknown>;
+}
+export interface RouteRecoverySignRequestPayload {
+    transfer_id: string;
+    route_generation_id: string;
+    requested_at?: string;
+    chunks: RouteRecoverySignChunk[];
+}
+export interface RouteRecoverySignReplyPayload {
+    transfer_id: string;
+    route_generation_id: string;
+    signed_at?: string;
+    chunk_routes: unknown[];
+}
+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);
+    serveRouteRecoverySigner(transferId: string, handler: (payload: RouteRecoverySignRequestPayload) => Promise<RouteRecoverySignReplyPayload>): Promise<() => void>;
+    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 routeRecoverySignSubject;
+    private buildRouteRecoveryReply;
+    private requestSubject;
+}
+export declare function transferShardId(transferId: string, shardCount: number): number;

package/dist/nats-control.js

@@ -0,0 +1,227 @@
+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";
+// NATS enforces max_payload per message. This guard splits signed-route control
+// messages before the broker rejects them; transfer bytes never flow through NATS.
+export const BEAM_DEFAULT_MAX_PAYLOAD_BYTES = 24 * 1024 * 1024;
+export const ROUTE_RECOVERY_SIGN_MESSAGE_TYPE = "transfer.route_recovery.sign";
+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 ?? BEAM_DEFAULT_MAX_PAYLOAD_BYTES;
+        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 serveRouteRecoverySigner(transferId, handler) {
+        const nc = await this.connection();
+        const subject = this.routeRecoverySignSubject(transferId);
+        const sub = nc.subscribe(subject);
+        let active = true;
+        void (async () => {
+            for await (const msg of sub) {
+                if (!active)
+                    break;
+                let request = null;
+                try {
+                    request = decode(msg.data);
+                    if (request.schema_version !== TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION ||
+                        request.environment !== this.environment ||
+                        request.key_prefix !== this.keyPrefix ||
+                        request.transfer_id !== transferId ||
+                        request.message_type !== ROUTE_RECOVERY_SIGN_MESSAGE_TYPE ||
+                        request.producer !== "transfer-runtime") {
+                        throw new Error("route recovery request envelope mismatch");
+                    }
+                    const payload = await handler(request.payload);
+                    msg.respond(encode(this.buildRouteRecoveryReply(request, true, 200, payload)));
+                }
+                catch (error) {
+                    const fallback = request ?? {
+                        message_id: "unknown",
+                        request_id: "unknown",
+                        transfer_id: transferId
+                    };
+                    msg.respond(encode(this.buildRouteRecoveryReply(fallback, false, 500, undefined, {
+                        code: "route_recovery_sign_failed",
+                        message: error instanceof Error ? error.message : String(error)
+                    })));
+                }
+            }
+        })();
+        return () => {
+            active = false;
+            sub.unsubscribe();
+        };
+    }
+    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`;
+    }
+    routeRecoverySignSubject(transferId) {
+        return `${this.subjectPrefix}.${this.environment}.sdk.${this.keyPrefix}.transfer.${transferId}.route_recovery_sign`;
+    }
+    buildRouteRecoveryReply(request, ok, status, payload, error) {
+        return {
+            message_id: request.message_id,
+            schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+            environment: this.environment,
+            key_prefix: this.keyPrefix,
+            transfer_id: request.transfer_id,
+            message_type: ROUTE_RECOVERY_SIGN_MESSAGE_TYPE,
+            request_id: request.request_id,
+            occurred_at: new Date().toISOString(),
+            producer: "sdk",
+            ok,
+            status,
+            ...(payload ? { payload } : {}),
+            ...(error ? { error } : {})
+        };
+    }
+    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/dist/provider-signing.d.ts

@@ -46,7 +46,6 @@ export declare function signDestinationRoute(input: {
     multipartGroupId?: string;
     multipartCreatedAt?: string;
     commitMethod?: "upload_part" | "upload_part_copy";
-    contentMd5?: string;
     partVerifyUrl?: string;
     listPageUrl?: string;
     stagingObjectKey?: string;
@@ -57,21 +56,6 @@ export declare function signDestinationRoute(input: {
     deleteUrl?: string;
     fetchImpl?: typeof fetch;
 }): Promise<SignedChunkRoute>;
-export declare function computeChunksContentMd5(input: {
-    source: ProviderSourceConfig;
-    chunks: ChunkSigningPlanItem[];
-    expiresIn: number;
-    fetchImpl?: typeof fetch;
-    groupSizeBytes?: number;
-    readTimeoutMs?: number;
-}): Promise<Map<number, string>>;
-export declare function computeChunkContentMd5(input: {
-    source: ProviderSourceConfig;
-    chunk: ChunkSigningPlanItem;
-    expiresIn: number;
-    fetchImpl?: typeof fetch;
-    readTimeoutMs?: number;
-}): Promise<string>;
 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;