@spooled/sdk 1.0.30 → 1.0.32

package/README.md

@@ -157,7 +157,7 @@ Run jobs on a cron schedule:
 ```typescript
 const schedule = await client.schedules.create({
   name: 'Daily Report',
-  cronExpression: '0 0 9 * * *',    // 6-field cron
+  cronExpression: '0 9 * * *',      // 9 AM daily; 5-field (min hour dom mon dow) or 6-field (leading seconds) both work
   timezone: 'America/New_York',
   queueName: 'reports',
   payloadTemplate: { type: 'daily' },
@@ -320,22 +320,25 @@ All operations automatically enforce tier-based limits:
 - ✅ Queue creation
 - ✅ Webhook creation
 
-When limits are exceeded, you'll receive a `403 Forbidden` response with details:
+When a plan quota or limit is exceeded, you'll receive an `HTTP 429` response with
+`code: "QUOTA_EXCEEDED"` and a body describing the `resource`, `current`, `limit`, and `plan`:
 
 ```typescript
-import { AuthorizationError } from '@spooled/sdk';
+import { RateLimitError } from '@spooled/sdk';
 
 try {
   await client.jobs.create({ /* ... */ });
 } catch (error) {
-  if (error instanceof AuthorizationError) {
-    // Plan limit reached (HTTP 403); the message describes the limit
+  if (error instanceof RateLimitError && error.code === 'QUOTA_EXCEEDED') {
+    // Plan quota reached (HTTP 429); details carry resource/current/limit/plan
     console.log(`Plan limit: ${error.message}`);
     console.log('Details:', error.details);
   }
 }
 ```
 
+(Per-second rate limiting also returns `429`, as a `RateLimitError` with the default `RATE_LIMIT_EXCEEDED` code.)
+
 ## Error Handling
 
 All errors extend `SpooledError` with specific subclasses:
@@ -355,8 +358,9 @@ try {
   if (error instanceof NotFoundError) {
     console.log('Job not found');
   } else if (error instanceof AuthorizationError) {
-    console.log(`Forbidden (e.g. plan limit): ${error.message}`);
+    console.log(`Forbidden: ${error.message}`);
   } else if (error instanceof RateLimitError) {
+    // 429: either a plan quota (code "QUOTA_EXCEEDED") or per-second rate limiting
     console.log(`Retry after ${error.getRetryAfter()} seconds`);
   } else if (isSpooledError(error)) {
     console.log(`API error: ${error.code} - ${error.message}`);

package/dist/{index-Dv2jBkfc.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";
 /**
@@ -2381,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) */
@@ -2430,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 */
@@ -3090,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)
@@ -3132,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-Dv2jBkfc.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";
 /**
@@ -2381,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) */
@@ -2430,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 */
@@ -3090,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)
@@ -3132,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,12 +49,19 @@ 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 normalizeCredential(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
 function resolveConfig(options) {
   let debugFn = null;
   if (options.debug === true) {
@@ -84,10 +91,10 @@ function resolveConfig(options) {
   const derivedWsUrl = baseUrl.replace(/^http/, "ws");
   const wsUrl = options.wsUrl ?? derivedWsUrl;
   return {
-    apiKey: options.apiKey,
-    accessToken: options.accessToken,
-    refreshToken: options.refreshToken,
-    adminKey: options.adminKey,
+    apiKey: normalizeCredential(options.apiKey),
+    accessToken: normalizeCredential(options.accessToken),
+    refreshToken: normalizeCredential(options.refreshToken),
+    adminKey: normalizeCredential(options.adminKey),
     baseUrl,
     wsUrl,
     grpcAddress: options.grpcAddress ?? DEFAULT_CONFIG.grpcAddress,
@@ -1849,6 +1856,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
@@ -1930,6 +1943,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 +2032,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 +2157,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 {
@@ -2877,6 +2906,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);
@@ -2964,9 +3005,10 @@ 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,
       // Only forward debug when the client actually has a logger, so we never
       // hand the realtime layer an explicit `debug: undefined`. The WS/SSE
@@ -2976,23 +3018,59 @@ var SpooledClient = class _SpooledClient {
     });
   }
   /**
-   * 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
@@ -3093,6 +3171,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) {