@spooled/sdk 1.0.29 → 1.0.31

package/dist/{index-CZorNMoD.d.cts → index-CfLL1w6Y.d.cts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.26";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.31";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.26";
+declare const SDK_VERSION = "1.0.31";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -1086,7 +1086,11 @@ interface CreateScheduleParams {
     timezone?: string;
     /** Target queue name */
     queueName: string;
-    /** Job payload template */
+    /**
+     * Job payload template. Required: the API rejects a create without it
+     * (HTTP 422), so this is typed as non-optional to surface the omission at
+     * compile time rather than as a runtime 422.
+     */
     payloadTemplate: JsonObject;
     /** Job priority (-100 to 100) */
     priority?: number;
@@ -2377,13 +2381,17 @@ interface RealtimeConnectionOptions {
     /** JWT token for authentication (used as a fallback when tokenProvider is not supplied) */
     token: string;
     /**
-     * Async provider that mints a fresh JWT for each (re)connect.
+     * Async provider that supplies a valid JWT for each (re)connect.
      *
-     * JWTs are short-lived, so a static token captured once will be stale by
-     * the time a long-running connection needs to reconnect. When provided,
-     * this is invoked before every connect/reconnect to obtain a valid token.
-     */
-    tokenProvider?: () => Promise<string>;
+     * JWTs are short-lived, so a static token captured once will be stale by the
+     * time a long-running connection needs to reconnect. When provided, this is
+     * invoked before every connect/reconnect to obtain a valid token. The
+     * provider is expected to cache and reuse the token itself (re-minting only
+     * near expiry), so calling it on every reconnect does not hammer the login
+     * endpoint. `forceRefresh` asks it to bypass that cache — the transport sets
+     * this after the server rejects a token (e.g. a 401 on the WS upgrade).
+     */
+    tokenProvider?: (forceRefresh?: boolean) => Promise<string>;
     /** Auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
     /** Maximum reconnect attempts (default: 10) */
@@ -2426,8 +2434,8 @@ interface FullRealtimeOptions extends SpooledRealtimeOptions {
     baseUrl: string;
     wsUrl: string;
     token: string;
-    /** Async provider that mints a fresh JWT for each (re)connect */
-    tokenProvider?: () => Promise<string>;
+    /** Async provider that supplies a valid JWT for each (re)connect */
+    tokenProvider?: (forceRefresh?: boolean) => Promise<string>;
     debug?: (message: string, meta?: unknown) => void;
 }
 /** Event handler type - simplified for internal use */
@@ -3086,6 +3094,18 @@ declare class SpooledClient {
     /** Token refresh state */
     private refreshPromise;
     private tokenExpiresAt;
+    /**
+     * Cached JWT for realtime connections (API-key auth path).
+     *
+     * The realtime layer requests a token on every (re)connect. Minting a brand
+     * new JWT via POST /auth/login each time trips the login rate limit (429)
+     * under a reconnect storm, after which realtime can never recover. We cache
+     * the token here — at the client level, shared across reconnects — and reuse
+     * it until it nears expiry.
+     */
+    private cachedJwt;
+    /** Deduplicates concurrent logins (e.g. WS + SSE reconnecting together). */
+    private jwtLoginPromise;
     constructor(options: SpooledClientConfig);
     /**
      * Real gRPC client for high-performance operations (HTTP/2 + Protobuf)
@@ -3128,9 +3148,26 @@ declare class SpooledClient {
      */
     realtime(options?: SpooledRealtimeOptions): Promise<SpooledRealtime>;
     /**
-     * Get or acquire a JWT token for realtime connections
+     * Get or acquire a JWT token for realtime connections.
+     *
+     * The realtime layer calls this on every (re)connect. We cache the JWT and
+     * reuse it until it nears expiry so a reconnect storm doesn't hammer
+     * /auth/login and trip its rate limit. A fresh login happens only when the
+     * cached token is absent, within ~60s of its `exp`, or a refresh is forced.
+     *
+     * @param forceRefresh Bypass the cache and mint a new token. Set by the
+     *   transport when the server rejected the current token (e.g. a 401 on the
+     *   WebSocket upgrade), so a stale/revoked token is replaced without waiting
+     *   for it to expire.
      */
     private getJwtToken;
+    /**
+     * Exchange the API key for a JWT via /auth/login and cache the result.
+     *
+     * Concurrent callers share a single in-flight login so a burst of reconnects
+     * (e.g. WebSocket and SSE at once) issues just one request.
+     */
+    private loginForJwt;
     /**
      * Check if token should be refreshed
      */

package/dist/{index-CZorNMoD.d.ts → index-CfLL1w6Y.d.ts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.26";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.31";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.26";
+declare const SDK_VERSION = "1.0.31";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -1086,7 +1086,11 @@ interface CreateScheduleParams {
     timezone?: string;
     /** Target queue name */
     queueName: string;
-    /** Job payload template */
+    /**
+     * Job payload template. Required: the API rejects a create without it
+     * (HTTP 422), so this is typed as non-optional to surface the omission at
+     * compile time rather than as a runtime 422.
+     */
     payloadTemplate: JsonObject;
     /** Job priority (-100 to 100) */
     priority?: number;
@@ -2377,13 +2381,17 @@ interface RealtimeConnectionOptions {
     /** JWT token for authentication (used as a fallback when tokenProvider is not supplied) */
     token: string;
     /**
-     * Async provider that mints a fresh JWT for each (re)connect.
+     * Async provider that supplies a valid JWT for each (re)connect.
      *
-     * JWTs are short-lived, so a static token captured once will be stale by
-     * the time a long-running connection needs to reconnect. When provided,
-     * this is invoked before every connect/reconnect to obtain a valid token.
-     */
-    tokenProvider?: () => Promise<string>;
+     * JWTs are short-lived, so a static token captured once will be stale by the
+     * time a long-running connection needs to reconnect. When provided, this is
+     * invoked before every connect/reconnect to obtain a valid token. The
+     * provider is expected to cache and reuse the token itself (re-minting only
+     * near expiry), so calling it on every reconnect does not hammer the login
+     * endpoint. `forceRefresh` asks it to bypass that cache — the transport sets
+     * this after the server rejects a token (e.g. a 401 on the WS upgrade).
+     */
+    tokenProvider?: (forceRefresh?: boolean) => Promise<string>;
     /** Auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
     /** Maximum reconnect attempts (default: 10) */
@@ -2426,8 +2434,8 @@ interface FullRealtimeOptions extends SpooledRealtimeOptions {
     baseUrl: string;
     wsUrl: string;
     token: string;
-    /** Async provider that mints a fresh JWT for each (re)connect */
-    tokenProvider?: () => Promise<string>;
+    /** Async provider that supplies a valid JWT for each (re)connect */
+    tokenProvider?: (forceRefresh?: boolean) => Promise<string>;
     debug?: (message: string, meta?: unknown) => void;
 }
 /** Event handler type - simplified for internal use */
@@ -3086,6 +3094,18 @@ declare class SpooledClient {
     /** Token refresh state */
     private refreshPromise;
     private tokenExpiresAt;
+    /**
+     * Cached JWT for realtime connections (API-key auth path).
+     *
+     * The realtime layer requests a token on every (re)connect. Minting a brand
+     * new JWT via POST /auth/login each time trips the login rate limit (429)
+     * under a reconnect storm, after which realtime can never recover. We cache
+     * the token here — at the client level, shared across reconnects — and reuse
+     * it until it nears expiry.
+     */
+    private cachedJwt;
+    /** Deduplicates concurrent logins (e.g. WS + SSE reconnecting together). */
+    private jwtLoginPromise;
     constructor(options: SpooledClientConfig);
     /**
      * Real gRPC client for high-performance operations (HTTP/2 + Protobuf)
@@ -3128,9 +3148,26 @@ declare class SpooledClient {
      */
     realtime(options?: SpooledRealtimeOptions): Promise<SpooledRealtime>;
     /**
-     * Get or acquire a JWT token for realtime connections
+     * Get or acquire a JWT token for realtime connections.
+     *
+     * The realtime layer calls this on every (re)connect. We cache the JWT and
+     * reuse it until it nears expiry so a reconnect storm doesn't hammer
+     * /auth/login and trip its rate limit. A fresh login happens only when the
+     * cached token is absent, within ~60s of its `exp`, or a refresh is forced.
+     *
+     * @param forceRefresh Bypass the cache and mint a new token. Set by the
+     *   transport when the server rejected the current token (e.g. a 401 on the
+     *   WebSocket upgrade), so a stale/revoked token is replaced without waiting
+     *   for it to expire.
      */
     private getJwtToken;
+    /**
+     * Exchange the API key for a JWT via /auth/login and cache the result.
+     *
+     * Concurrent callers share a single in-flight login so a burst of reconnects
+     * (e.g. WebSocket and SSE at once) issues just one request.
+     */
+    private loginForJwt;
     /**
      * Check if token should be refreshed
      */

package/dist/index.cjs

@@ -49,10 +49,10 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.0.26",
+  userAgent: "@spooled/sdk-nodejs/1.0.31",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.0.26";
+var SDK_VERSION = "1.0.31";
 var API_VERSION = "v1";
 var API_BASE_PATH = `/api/${API_VERSION}`;
 function resolveConfig(options) {
@@ -1849,6 +1849,12 @@ var WebSocketRealtimeClient = class {
   state = "disconnected";
   reconnectAttempts = 0;
   reconnectTimer = null;
+  /**
+   * Set when the server rejected our token on the upgrade (e.g. HTTP 401/403).
+   * The next (re)connect uses it to force the token provider to mint a fresh
+   * JWT instead of replaying the rejected one (which would loop forever).
+   */
+  authFailure = false;
   subscriptions = /* @__PURE__ */ new Map();
   pendingCommands = /* @__PURE__ */ new Map();
   // Event handlers
@@ -1857,16 +1863,16 @@ var WebSocketRealtimeClient = class {
   stateChangeHandlers = /* @__PURE__ */ new Set();
   constructor(options) {
     this.options = {
-      autoReconnect: true,
-      maxReconnectAttempts: 10,
-      reconnectDelay: 1e3,
-      maxReconnectDelay: 3e4,
-      debug: () => {
-      },
       ...options,
+      autoReconnect: options.autoReconnect ?? true,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+      reconnectDelay: options.reconnectDelay ?? 1e3,
+      maxReconnectDelay: options.maxReconnectDelay ?? 3e4,
       // Always resolve to a provider so reconnects can mint a fresh JWT.
       // Falls back to the static token when no provider is supplied.
-      tokenProvider: options.tokenProvider ?? (async () => options.token)
+      tokenProvider: options.tokenProvider ?? (async () => options.token),
+      debug: options.debug ?? (() => {
+      })
     };
   }
   /**
@@ -1930,6 +1936,9 @@ var WebSocketRealtimeClient = class {
         };
         this.ws.onerror = (event) => {
           this.options.debug("WebSocket error", event);
+          if (isAuthFailureEvent(event)) {
+            this.authFailure = true;
+          }
         };
       } catch (error) {
         this.setState("disconnected");
@@ -2016,7 +2025,9 @@ var WebSocketRealtimeClient = class {
   // Private methods
   async buildWsUrl() {
     const wsBase = this.options.wsUrl;
-    const token = await this.options.tokenProvider();
+    const forceRefresh = this.authFailure;
+    this.authFailure = false;
+    const token = await this.options.tokenProvider(forceRefresh);
     return `${wsBase}/api/v1/ws?token=${encodeURIComponent(token)}`;
   }
   setState(state) {
@@ -2139,6 +2150,17 @@ var WebSocketRealtimeClient = class {
 function redactToken(url) {
   return url.replace(/([?&](?:token|api_key)=)[^&]*/gi, "$1***");
 }
+function isAuthFailureEvent(event) {
+  if (!event) {
+    return false;
+  }
+  const status = event.status ?? event.statusCode ?? event.error?.status;
+  if (status === 401 || status === 403) {
+    return true;
+  }
+  const text = String(event.message ?? event.error?.message ?? event.reason ?? "");
+  return /\b(401|403)\b/.test(text);
+}
 
 // src/realtime/sse.ts
 var SseRealtimeClient = class {
@@ -2155,16 +2177,22 @@ var SseRealtimeClient = class {
   stateChangeHandlers = /* @__PURE__ */ new Set();
   constructor(options) {
     this.options = {
-      autoReconnect: true,
-      maxReconnectAttempts: 10,
-      reconnectDelay: 1e3,
-      maxReconnectDelay: 3e4,
-      debug: () => {
-      },
       ...options,
+      autoReconnect: options.autoReconnect ?? true,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+      reconnectDelay: options.reconnectDelay ?? 1e3,
+      maxReconnectDelay: options.maxReconnectDelay ?? 3e4,
       // Always resolve to a provider so reconnects can mint a fresh token.
       // Falls back to the static token when no provider is supplied.
-      tokenProvider: options.tokenProvider ?? (async () => options.token)
+      tokenProvider: options.tokenProvider ?? (async () => options.token),
+      // Coalesce debug to a no-op AFTER the spread. A caller that omits debug
+      // still passes `debug: undefined` explicitly (e.g. via SpooledRealtime),
+      // and spreading that would overwrite a pre-spread default with undefined,
+      // making connect() call `this.options.debug(...)` on undefined and throw
+      // "this.options.debug is not a function". Guarding here keeps it callable
+      // regardless of what the caller passes.
+      debug: options.debug ?? (() => {
+      })
     };
   }
   /**
@@ -2871,6 +2899,18 @@ var SpooledClient = class _SpooledClient {
   /** Token refresh state */
   refreshPromise = null;
   tokenExpiresAt = null;
+  /**
+   * Cached JWT for realtime connections (API-key auth path).
+   *
+   * The realtime layer requests a token on every (re)connect. Minting a brand
+   * new JWT via POST /auth/login each time trips the login rate limit (429)
+   * under a reconnect storm, after which realtime can never recover. We cache
+   * the token here — at the client level, shared across reconnects — and reuse
+   * it until it nears expiry.
+   */
+  cachedJwt = null;
+  /** Deduplicates concurrent logins (e.g. WS + SSE reconnecting together). */
+  jwtLoginPromise = null;
   constructor(options) {
     this.config = resolveConfig(options);
     validateConfig(this.config);
@@ -2958,31 +2998,72 @@ var SpooledClient = class _SpooledClient {
       baseUrl: this.config.baseUrl,
       wsUrl: this.config.wsUrl,
       token,
-      // Provider so each (re)connect mints a fresh JWT via login/refresh,
-      // rather than reusing the short-lived token captured above.
-      tokenProvider: () => this.getJwtToken(),
+      // Provider the realtime layer calls on every (re)connect. It returns a
+      // cached JWT and only re-logs-in when the token is absent, near expiry,
+      // or the transport asks to force a refresh (e.g. after a 401 upgrade).
+      tokenProvider: (forceRefresh) => this.getJwtToken(forceRefresh),
       ...options,
-      debug: this.config.debug ?? void 0
+      // Only forward debug when the client actually has a logger, so we never
+      // hand the realtime layer an explicit `debug: undefined`. The WS/SSE
+      // constructors also guard against this, but keeping the undefined out of
+      // the option object makes the intent clear at the call site.
+      ...this.config.debug ? { debug: this.config.debug } : {}
     });
   }
   /**
-   * Get or acquire a JWT token for realtime connections
+   * Get or acquire a JWT token for realtime connections.
+   *
+   * The realtime layer calls this on every (re)connect. We cache the JWT and
+   * reuse it until it nears expiry so a reconnect storm doesn't hammer
+   * /auth/login and trip its rate limit. A fresh login happens only when the
+   * cached token is absent, within ~60s of its `exp`, or a refresh is forced.
+   *
+   * @param forceRefresh Bypass the cache and mint a new token. Set by the
+   *   transport when the server rejected the current token (e.g. a 401 on the
+   *   WebSocket upgrade), so a stale/revoked token is replaced without waiting
+   *   for it to expire.
    */
-  async getJwtToken() {
+  async getJwtToken(forceRefresh = false) {
     if (this.config.accessToken) {
-      if (this.shouldRefreshToken()) {
+      if (forceRefresh || this.shouldRefreshToken()) {
         return this.refreshAccessToken();
       }
       return this.config.accessToken;
     }
     if (this.config.apiKey) {
+      if (forceRefresh) {
+        this.cachedJwt = null;
+      }
+      if (this.cachedJwt && !isJwtNearExpiry(this.cachedJwt)) {
+        return this.cachedJwt;
+      }
+      return this.loginForJwt();
+    }
+    throw new AuthenticationError("No authentication method available for realtime connection");
+  }
+  /**
+   * Exchange the API key for a JWT via /auth/login and cache the result.
+   *
+   * Concurrent callers share a single in-flight login so a burst of reconnects
+   * (e.g. WebSocket and SSE at once) issues just one request.
+   */
+  async loginForJwt() {
+    if (this.jwtLoginPromise) {
+      return this.jwtLoginPromise;
+    }
+    this.jwtLoginPromise = (async () => {
       const response = await this.auth.login({ apiKey: this.config.apiKey });
       this.http.setAuthToken(response.accessToken);
       this.tokenExpiresAt = Date.now() + response.expiresIn * 1e3;
       this.config.refreshToken = response.refreshToken;
+      this.cachedJwt = response.accessToken;
       return response.accessToken;
+    })();
+    try {
+      return await this.jwtLoginPromise;
+    } finally {
+      this.jwtLoginPromise = null;
     }
-    throw new AuthenticationError("No authentication method available for realtime connection");
   }
   /**
    * Check if token should be refreshed
@@ -3083,6 +3164,34 @@ var SpooledClient = class _SpooledClient {
 function createClient(options) {
   return new SpooledClient(options);
 }
+function decodeJwtExp(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(base64UrlDecode(parts[1]));
+    return typeof payload.exp === "number" ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+function isJwtNearExpiry(token, skewMs = 6e4) {
+  const exp = decodeJwtExp(token);
+  if (exp === null) {
+    return true;
+  }
+  return Date.now() >= exp * 1e3 - skewMs;
+}
+function base64UrlDecode(segment) {
+  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  if (typeof globalThis.Buffer !== "undefined") {
+    return globalThis.Buffer.from(b64, "base64").toString("utf8");
+  }
+  const binary = globalThis.atob(b64);
+  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  return new globalThis.TextDecoder().decode(bytes);
+}
 
 // src/types/common.ts
 function createPaginatedResponse(items, limit, offset = 0, total) {