@beam-network/sdk 0.5.14 → 0.5.15

package/README.md

@@ -98,7 +98,7 @@ For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport
 
 Provider transfers use `transfer-client-control/v6`. Every reply carries Runtime and transport epochs; prepare and every route-stream message carry a UUID route generation. S3, R2, and S3-compatible destinations retain direct multipart UploadPart/ListParts/HEAD handling.
 
-The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches. Encoded MessagePack requests target 4 MiB physical batches under `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. A single route above the 4 MiB target but within the configured guard publishes alone; a single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
+The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches. Encoded MessagePack requests target 4 MiB physical batches under `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. Lifecycle control refreshes cached SDK auth before the final 30 seconds of token lifetime and retries `auth_token_expired` replies with the same request identity and payload but a fresh token, preserving Core request-conflict protection during large route streams. A single route above the 4 MiB target but within the configured guard publishes alone; a single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
 
 The stream ID derives from the transfer, selected flow, and immutable plan identity, and each ordered batch ID includes its route-coordinate checksum. Manual multi-destination attachment requires `delivery_index` on every route. Lifecycle mutations retry transient failures up to three times with the same request identity. A non-recoverable provider setup or route failure raises `BeamProviderTransferError`, whose `errors`, `transferCancelled`, and `multipartCleanupComplete` fields retain the original provider, cancellation, and cleanup outcomes. `waitForTransfer` subscribes to the API-key-owned, at-most-once terminal signal before its first status read and reconciles every signal through authoritative status; subscription failure degrades to the same jittered 15-to-30-second status fallback. Call `close()` when the client is no longer needed; it also closes outstanding terminal waiters.
 

package/dist/nats-control.js

@@ -8,6 +8,7 @@ export const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
 export const BEAM_DEFAULT_MAX_PAYLOAD_BYTES = 8 * 1024 * 1024;
 export const BEAM_ROUTE_TARGET_PAYLOAD_BYTES = 4 * 1024 * 1024;
 const ROUTE_BATCH_AUTH_TOKEN_ESTIMATE_BYTES = 64 * 1024;
+const AUTH_TOKEN_REFRESH_SAFETY_SECONDS = 30;
 export const ROUTE_RECOVERY_SIGN_MESSAGE_TYPE = "transfer.route_recovery.sign";
 export function buildConnectionOptions(options) {
     const connectionOptions = {
@@ -199,32 +200,33 @@ export class BeamTransferControl {
         void this.recoverLease(lease);
     }
     async request(messageType, payload, options = {}) {
-        const authToken = await this.resolveAuthToken();
         const shardId = options.shardId ?? (options.transferId ? transferShardId(options.transferId, this.shardCount) : 0);
         const requestId = options.idempotencyKey
             ? await stableRequestId(`${messageType}:${options.idempotencyKey}`)
             : 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 occurredAt = new Date().toISOString();
         const subject = this.requestSubject(messageType, shardId);
         let lastError;
         for (let attempt = 0; attempt < LIFECYCLE_REQUEST_MAX_ATTEMPTS; attempt += 1) {
             try {
+                const authToken = await this.resolveAuthToken();
+                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: occurredAt,
+                    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 nc = await this.connection();
                 const response = await nc.request(subject, bytes, { timeout: this.requestTimeoutMs });
                 const decoded = decode(response.data);
@@ -233,6 +235,13 @@ export class BeamTransferControl {
                     return (decoded.payload ?? {});
                 const body = JSON.stringify(decoded.error ?? {});
                 const error = new LifecycleRequestError(decoded.status, `Beam lifecycle request failed with ${decoded.status}: ${body}`);
+                if (isExpiredAuthTokenReply(decoded) && attempt + 1 < LIFECYCLE_REQUEST_MAX_ATTEMPTS) {
+                    this.authToken = null;
+                    this.authTokenExpiresAt = 0;
+                    lastError = error;
+                    await sleepWithJitter(LIFECYCLE_REQUEST_RETRY_DELAYS_MS[attempt] ?? 1_000);
+                    continue;
+                }
                 if (!isRetryableLifecycleStatus(decoded.status) || attempt + 1 >= LIFECYCLE_REQUEST_MAX_ATTEMPTS) {
                     throw error;
                 }
@@ -507,7 +516,7 @@ export class BeamTransferControl {
     }
     async resolveAuthToken() {
         const now = Math.floor(Date.now() / 1000);
-        if (this.authToken && this.authTokenExpiresAt - 5 > now)
+        if (this.authToken && this.authTokenExpiresAt - AUTH_TOKEN_REFRESH_SAFETY_SECONDS > now)
             return this.authToken;
         if (this.authResolvePromise)
             return this.authResolvePromise;
@@ -707,6 +716,9 @@ const LIFECYCLE_REQUEST_RETRY_DELAYS_MS = [150, 500];
 function isRetryableLifecycleStatus(status) {
     return status === 408 || status === 425 || status === 429 || status >= 500;
 }
+function isExpiredAuthTokenReply(reply) {
+    return reply.status === 401 && reply.error?.code === "auth_token_expired";
+}
 export function isRetryableLifecycleError(error) {
     if (error instanceof LifecycleRequestError)
         return isRetryableLifecycleStatus(error.status);

package/package.json

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