@beam-network/sdk 0.4.3 → 0.5.0

package/dist/client.d.ts

@@ -1,11 +1,6 @@
 import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, MultipartGroupManifest, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo, TransferTerminalSignalWaiter } from "./models.js";
 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 apiKey: string;
     readonly natsUrl: string;
@@ -13,6 +8,8 @@ export declare class BeamClient {
     private readonly control;
     private readonly routeSigningConcurrency;
     private readonly routeSigningConcurrencyOverridden;
+    /** Last credit state Beam reported. Null until the first request or connect. */
+    get creditStatus(): import("./models.js").CreditStatus | null;
     constructor(options?: BeamClientOptions);
     close(): Promise<void>;
     openTransferTerminalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;

package/dist/client.js

@@ -2,16 +2,9 @@ import { abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProvi
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes } from "./nats-control.js";
 import { multipartPartNumber } from "./multipart-limits.js";
 export { BEAM_DEFAULT_NATS_URL };
-export class BeamApiError extends Error {
-    status;
-    body;
-    constructor(message, status, body) {
-        super(message);
-        this.status = status;
-        this.body = body;
-        this.name = "BeamApiError";
-    }
-}
+// The error classes live in ./errors.js and are re-exported by ./index.js.
+// Re-exporting them here too would make `export *` in index.ts ambiguous, which
+// silently drops the names from the package's public types.
 export class BeamClient {
     apiKey;
     natsUrl;
@@ -19,6 +12,10 @@ export class BeamClient {
     control;
     routeSigningConcurrency;
     routeSigningConcurrencyOverridden;
+    /** Last credit state Beam reported. Null until the first request or connect. */
+    get creditStatus() {
+        return this.control.creditStatus;
+    }
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
@@ -35,7 +32,8 @@ export class BeamClient {
             subjectPrefix: options.transferClientSubjectPrefix,
             transferRuntimeShardCount: options.transferRuntimeShardCount,
             requestTimeoutMs: options.requestTimeoutMs,
-            maxPayloadBytes: options.maxPayloadBytes
+            maxPayloadBytes: options.maxPayloadBytes,
+            onCreditWarning: options.onCreditWarning
         });
         this.fetchImpl = options.fetch ?? globalThis.fetch;
         if (!this.fetchImpl) {

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+import type { CreditStatus } from "./models.js";
+export declare class BeamApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+/**
+ * Raised when Beam refuses a request because the organization is out of credits.
+ *
+ * Always terminal: 402 is outside the retryable status set, so the SDK fails fast
+ * rather than retrying a request that cannot succeed until the balance is topped up.
+ */
+export declare class BeamInsufficientCreditsError extends BeamApiError {
+    readonly code: string;
+    readonly credits: CreditStatus | null;
+    constructor(message: string, code: string, credits: CreditStatus | null, body: string);
+}

package/dist/errors.js

@@ -0,0 +1,26 @@
+export class BeamApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "BeamApiError";
+    }
+}
+/**
+ * Raised when Beam refuses a request because the organization is out of credits.
+ *
+ * Always terminal: 402 is outside the retryable status set, so the SDK fails fast
+ * rather than retrying a request that cannot succeed until the balance is topped up.
+ */
+export class BeamInsufficientCreditsError extends BeamApiError {
+    code;
+    credits;
+    constructor(message, code, credits, body) {
+        super(message, 402, body);
+        this.code = code;
+        this.credits = credits;
+        this.name = "BeamInsufficientCreditsError";
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/models.d.ts

@@ -1,4 +1,27 @@
 export type SignedUrlFlow = "signed_url_v1" | "signed_url_v2";
+export type CreditVerdict = "unlimited" | "ok" | "low" | "exhausted" | "unknown";
+/**
+ * Credit state for the API key that made the request.
+ *
+ * The verdict is computed server-side and is the single source of truth: never
+ * derive one client-side from `remaining` and `low_threshold`, or the SDK will
+ * warn at a different point than Beam actually blocks.
+ */
+export interface CreditStatus {
+    verdict: CreditVerdict;
+    /** Credits left in the organization pool. Null when unlimited or unknown. */
+    remaining: number | null;
+    /** Balance below which Beam warns. Display only. */
+    low_threshold: number | null;
+    billing_key_id: string | null;
+    billing_org_id: string | null;
+}
+export interface CreditWarning {
+    code: string;
+    message: string;
+    detail?: unknown;
+    credits?: CreditStatus;
+}
 export interface BeamClientOptions {
     apiKey?: string;
     natsUrl?: string;
@@ -10,6 +33,12 @@ export interface BeamClientOptions {
     maxPayloadBytes?: number;
     routeSigningConcurrency?: number;
     fetch?: typeof fetch;
+    /**
+     * Called when Beam reports a credit problem, including once at connect time
+     * from the auth token. Without a handler the SDK logs one line per verdict
+     * change rather than per request.
+     */
+    onCreditWarning?: (warning: CreditWarning) => void;
 }
 export interface SourceConfig {
     type: string;
@@ -72,6 +101,8 @@ export interface RawTransferCreateInput {
     idempotencyKey?: string;
 }
 export interface TransferCreateResponse {
+    /** Credit state after this request. */
+    credits?: CreditStatus;
     success: boolean;
     transfer_id: string;
     transfer_key?: string;
@@ -85,6 +116,8 @@ export interface TransferCreateResponse {
     message?: string;
 }
 export interface TransferCancelResponse {
+    /** Credit state after this request. */
+    credits?: CreditStatus;
     success: boolean;
     message?: string;
 }
@@ -115,6 +148,8 @@ export interface DestinationStatusInfo {
     location?: string;
 }
 export interface TransferStatusInfo {
+    /** Credit state after this request. */
+    credits?: CreditStatus;
     transfer_id: string;
     name?: string;
     status: string;
@@ -184,6 +219,14 @@ export interface S3CompatibleProviderCapabilities {
      * Beam-side timestamp instead of looping into multipart recovery.
      */
     multipart_part_last_modified?: boolean;
+    /**
+     * Per-destination override for Beam Core's assignment-recovery deadline
+     * (TRANSFER_ASSIGNMENT_TIMEOUT_MS), in milliseconds. Omit to use the global
+     * default (15s). Slower providers (e.g. Hippius) declare a larger value so
+     * their assignment waves aren't reassigned prematurely. Only integers >= 1000
+     * are honoured by Beam Core.
+     */
+    assignment_timeout_ms?: number;
 }
 export interface S3CompatibleProviderConfig {
     provider: string;
@@ -342,6 +385,8 @@ export interface MultipartGroupManifest {
     urls_expires_at: string;
 }
 export interface TransferPlanResponse {
+    /** Credit state after this request. */
+    credits?: CreditStatus;
     success: boolean;
     chunk_size?: number;
     total_size?: number;
@@ -355,6 +400,8 @@ export interface TransferPlanResponse {
     message?: string;
 }
 export interface TransferPrepareResponse {
+    /** Credit state after this request. */
+    credits?: CreditStatus;
     success: boolean;
     transfer_id: string;
     transfer_key?: string;

package/dist/nats-control.d.ts

@@ -1,4 +1,4 @@
-import type { MultipartGroupManifest, SignedChunkRoute, TransferTerminalSignalWaiter } from "./models.js";
+import type { CreditStatus, CreditWarning, MultipartGroupManifest, SignedChunkRoute, TransferTerminalSignalWaiter } from "./models.js";
 export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v4";
 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";
@@ -51,6 +51,7 @@ export interface TransferControlOptions {
     transferRuntimeShardCount?: number;
     requestTimeoutMs?: number;
     maxPayloadBytes?: number;
+    onCreditWarning?: (warning: CreditWarning) => void;
 }
 export interface LifecycleRequestOptions {
     transferId?: string;
@@ -72,6 +73,18 @@ export declare class BeamTransferControl {
     private authTokenExpiresAt;
     private authResolvePromise;
     private readonly terminalWaitCancellations;
+    private lastCredits;
+    private reportedVerdict;
+    private readonly onCreditWarning;
+    /** Last credit state Beam reported, for display without issuing a request. */
+    get creditStatus(): CreditStatus | null;
+    /**
+     * Records the credit state from a reply or auth token and surfaces a warning.
+     *
+     * Fires on verdict transitions, not per request, so a long-running client does
+     * not emit the same warning on every call.
+     */
+    private observeCredits;
     constructor(options: TransferControlOptions);
     close(): Promise<void>;
     request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, options?: LifecycleRequestOptions): Promise<T>;

package/dist/nats-control.js

@@ -1,5 +1,6 @@
 import { encode, decode } from "@msgpack/msgpack";
 import { connect } from "nats";
+import { BeamApiError, BeamInsufficientCreditsError } from "./errors.js";
 export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v4";
 export const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
 export const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
@@ -41,6 +42,42 @@ export class BeamTransferControl {
     authTokenExpiresAt = 0;
     authResolvePromise = null;
     terminalWaitCancellations = new Set();
+    lastCredits = null;
+    reportedVerdict = null;
+    onCreditWarning;
+    /** Last credit state Beam reported, for display without issuing a request. */
+    get creditStatus() {
+        return this.lastCredits;
+    }
+    /**
+     * Records the credit state from a reply or auth token and surfaces a warning.
+     *
+     * Fires on verdict transitions, not per request, so a long-running client does
+     * not emit the same warning on every call.
+     */
+    observeCredits(credits, warnings) {
+        if (!credits)
+            return this.lastCredits;
+        this.lastCredits = credits;
+        if (credits.verdict === this.reportedVerdict)
+            return credits;
+        this.reportedVerdict = credits.verdict;
+        if (credits.verdict !== "low" && credits.verdict !== "exhausted")
+            return credits;
+        const warning = warnings?.[0] ?? {
+            code: credits.verdict === "exhausted" ? "insufficient_credits" : "credits_low",
+            message: credits.remaining === null
+                ? "Beam credit balance is low."
+                : `Beam credit balance is low: ${credits.remaining} credits remaining.`,
+            credits
+        };
+        if (this.onCreditWarning) {
+            this.onCreditWarning({ ...warning, credits });
+            return credits;
+        }
+        console.warn(`[beam] ${warning.message}`);
+        return credits;
+    }
     constructor(options) {
         this.apiKey = options.apiKey;
         this.keyPrefix = options.apiKey.slice(0, 12);
@@ -50,6 +87,7 @@ export class BeamTransferControl {
         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;
+        this.onCreditWarning = options.onCreditWarning;
         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.");
         }
@@ -104,10 +142,19 @@ export class BeamTransferControl {
                 const nc = await this.connection();
                 const response = await nc.request(subject, bytes, { timeout: this.requestTimeoutMs });
                 const decoded = decode(response.data);
-                if (decoded.ok)
-                    return (decoded.payload ?? {});
+                const credits = this.observeCredits(decoded.credits, decoded.warnings);
+                if (decoded.ok) {
+                    const payload = (decoded.payload ?? {});
+                    // Credits ride on the envelope, not the payload, so they reach every
+                    // response type without a per-message-type model change.
+                    return (credits ? { ...payload, credits } : payload);
+                }
                 const body = JSON.stringify(decoded.error ?? {});
-                const error = new Error(`Beam lifecycle request failed with ${decoded.status}: ${body}`);
+                const code = decoded.error?.code ?? "lifecycle_error";
+                const message = decoded.error?.message ?? body;
+                const error = decoded.status === 402
+                    ? new BeamInsufficientCreditsError(message, code, credits, body)
+                    : new BeamApiError(`Beam lifecycle request failed with ${decoded.status}: ${body}`, decoded.status, body);
                 if (!isRetryableLifecycleStatus(decoded.status) || attempt + 1 >= LIFECYCLE_REQUEST_MAX_ATTEMPTS) {
                     throw error;
                 }
@@ -311,6 +358,9 @@ export class BeamTransferControl {
                 const claims = decodeJwtPayload(parsed.token);
                 this.authToken = parsed.token;
                 this.authTokenExpiresAt = claims.exp;
+                // Pre-flight: the token carries the verdict, so a low balance surfaces
+                // before the first lifecycle request is ever sent.
+                this.observeCredits(claims.credits);
                 return parsed.token;
             }
             catch (error) {

package/package.json

@@ -1,38 +1,38 @@
 {
-    "name": "@beam-network/sdk",
-    "version": "0.4.3",
-    "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/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"
+  "name": "@beam-network/sdk",
+  "version": "0.5.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/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"
+  }
 }