@spooled/sdk 1.0.27 → 1.0.29

package/README.md

@@ -37,7 +37,7 @@ npm install @spooled/sdk
 import { SpooledClient } from '@spooled/sdk';
 
 const client = new SpooledClient({
-  apiKey: 'sk_live_your_api_key',
+  apiKey: 'sp_live_your_api_key',
   // For self-hosted: baseUrl: 'https://your-spooled-server.com'
 });
 
@@ -116,7 +116,7 @@ Process jobs with the built-in worker runtime:
 ```typescript
 import { SpooledClient, SpooledWorker } from '@spooled/sdk';
 
-const client = new SpooledClient({ apiKey: 'sk_live_...' });
+const client = new SpooledClient({ apiKey: 'sp_live_...' });
 
 const worker = new SpooledWorker(client, {
   queueName: 'my-queue',
@@ -293,7 +293,7 @@ const { exists } = await client.auth.checkEmail('user@example.com');
 
 // Exchange API key for JWT
 const { accessToken, refreshToken } = await client.auth.login({
-  apiKey: 'sk_live_...'
+  apiKey: 'sp_live_...'
 });
 
 // Use JWT for subsequent requests
@@ -323,13 +323,15 @@ All operations automatically enforce tier-based limits:
 When limits are exceeded, you'll receive a `403 Forbidden` response with details:
 
 ```typescript
+import { AuthorizationError } from '@spooled/sdk';
+
 try {
   await client.jobs.create({ /* ... */ });
 } catch (error) {
-  if (error.statusCode === 403 && error.code === 'limit_exceeded') {
-    console.log(`Limit: ${error.message}`);
-    console.log(`Current: ${error.current}, Max: ${error.limit}`);
-    console.log(`Upgrade to: ${error.upgradeTo}`);
+  if (error instanceof AuthorizationError) {
+    // Plan limit reached (HTTP 403); the message describes the limit
+    console.log(`Plan limit: ${error.message}`);
+    console.log('Details:', error.details);
   }
 }
 ```
@@ -343,7 +345,7 @@ import {
   NotFoundError,
   RateLimitError,
   ValidationError,
-  LimitExceededError,
+  AuthorizationError,
   isSpooledError,
 } from '@spooled/sdk';
 
@@ -352,9 +354,8 @@ try {
 } catch (error) {
   if (error instanceof NotFoundError) {
     console.log('Job not found');
-  } else if (error instanceof LimitExceededError) {
-    console.log(`Plan limit: ${error.message}`);
-    console.log(`Upgrade to ${error.upgradeTo} for more capacity`);
+  } else if (error instanceof AuthorizationError) {
+    console.log(`Forbidden (e.g. plan limit): ${error.message}`);
   } else if (error instanceof RateLimitError) {
     console.log(`Retry after ${error.getRetryAfter()} seconds`);
   } else if (isSpooledError(error)) {
@@ -375,7 +376,7 @@ import { SpooledGrpcClient } from '@spooled/sdk';
 // useTls: false if connecting to localhost or direct backend
 const grpcClient = new SpooledGrpcClient({
   address: 'grpc.spooled.cloud:443',
-  apiKey: 'sk_live_your_key',
+  apiKey: 'sp_live_your_key',
   useTls: true
 });
 

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

@@ -285,15 +285,22 @@ declare class HttpClient {
     private readonly debug;
     /** Current authentication token (API key or JWT) */
     private authToken;
+    /** Optional function to mint a fresh access token (set when auto-refresh is enabled) */
+    private refreshTokenFn;
+    /** Guard to prevent a refresh request from recursively triggering another refresh */
+    private isRefreshing;
     constructor(config: ResolvedConfig, circuitBreaker: CircuitBreaker);
     /**
      * Set the authentication token
      */
     setAuthToken(token: string): void;
     /**
-     * Set the token refresh function (for future use)
+     * Set the token refresh function.
+     *
+     * When set, an expired-token 401 on the data plane triggers a single
+     * refresh + retry of the original request with the new token.
      */
-    setRefreshTokenFn(_fn: () => Promise<string>): void;
+    setRefreshTokenFn(fn: () => Promise<string>): void;
     /**
      * Build full URL with query parameters
      */
@@ -314,6 +321,22 @@ declare class HttpClient {
      * Make an HTTP request with retry and circuit breaker
      */
     request<T>(path: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Determine whether a request carries an idempotency key (making a
+     * non-idempotent method safe to retry).
+     */
+    private hasIdempotencyKey;
+    /**
+     * Resolve the retry configuration for a request.
+     *
+     * Idempotent methods (GET/PUT/DELETE) and any request carrying an
+     * idempotency key retry normally. Non-idempotent methods (POST/PATCH)
+     * without an idempotency key must NOT be retried on ambiguous failures
+     * (network/timeout/5xx) — doing so risks duplicate jobs, double claims,
+     * etc. They are still retried on 429, which is rejected before the
+     * server processes the request and is therefore side-effect-free.
+     */
+    private resolveRetryConfig;
     /**
      * Make a GET request
      */
@@ -401,7 +424,11 @@ interface ValidateTokenResponse {
 
 declare class AuthResource {
     private readonly http;
-    constructor(http: HttpClient);
+    /** Optional accessor for the client's current refresh token (used by logout) */
+    private readonly getRefreshToken?;
+    constructor(http: HttpClient, 
+    /** Optional accessor for the client's current refresh token (used by logout) */
+    getRefreshToken?: (() => string | undefined) | undefined);
     /**
      * Exchange API key for JWT tokens
      */
@@ -411,9 +438,13 @@ declare class AuthResource {
      */
     refresh(params: RefreshTokenParams): Promise<RefreshTokenResponse>;
     /**
-     * Logout and invalidate current token
+     * Logout and revoke the refresh token server-side.
+     *
+     * The backend requires the refresh token in the body to invalidate the
+     * session. When omitted, the client's current refresh token (if any) is
+     * used automatically.
      */
-    logout(): Promise<void>;
+    logout(refreshToken?: string): Promise<void>;
     /**
      * Get current user/session info
      */
@@ -2343,8 +2374,16 @@ interface RealtimeConnectionOptions {
     baseUrl: string;
     /** WebSocket URL for realtime connection (e.g., wss://api.spooled.cloud) - used for WebSocket */
     wsUrl: string;
-    /** JWT token for authentication */
+    /** 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.
+     *
+     * 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>;
     /** Auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
     /** Maximum reconnect attempts (default: 10) */
@@ -2387,6 +2426,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>;
     debug?: (message: string, meta?: unknown) => void;
 }
 /** Event handler type - simplified for internal use */

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

@@ -285,15 +285,22 @@ declare class HttpClient {
     private readonly debug;
     /** Current authentication token (API key or JWT) */
     private authToken;
+    /** Optional function to mint a fresh access token (set when auto-refresh is enabled) */
+    private refreshTokenFn;
+    /** Guard to prevent a refresh request from recursively triggering another refresh */
+    private isRefreshing;
     constructor(config: ResolvedConfig, circuitBreaker: CircuitBreaker);
     /**
      * Set the authentication token
      */
     setAuthToken(token: string): void;
     /**
-     * Set the token refresh function (for future use)
+     * Set the token refresh function.
+     *
+     * When set, an expired-token 401 on the data plane triggers a single
+     * refresh + retry of the original request with the new token.
      */
-    setRefreshTokenFn(_fn: () => Promise<string>): void;
+    setRefreshTokenFn(fn: () => Promise<string>): void;
     /**
      * Build full URL with query parameters
      */
@@ -314,6 +321,22 @@ declare class HttpClient {
      * Make an HTTP request with retry and circuit breaker
      */
     request<T>(path: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Determine whether a request carries an idempotency key (making a
+     * non-idempotent method safe to retry).
+     */
+    private hasIdempotencyKey;
+    /**
+     * Resolve the retry configuration for a request.
+     *
+     * Idempotent methods (GET/PUT/DELETE) and any request carrying an
+     * idempotency key retry normally. Non-idempotent methods (POST/PATCH)
+     * without an idempotency key must NOT be retried on ambiguous failures
+     * (network/timeout/5xx) — doing so risks duplicate jobs, double claims,
+     * etc. They are still retried on 429, which is rejected before the
+     * server processes the request and is therefore side-effect-free.
+     */
+    private resolveRetryConfig;
     /**
      * Make a GET request
      */
@@ -401,7 +424,11 @@ interface ValidateTokenResponse {
 
 declare class AuthResource {
     private readonly http;
-    constructor(http: HttpClient);
+    /** Optional accessor for the client's current refresh token (used by logout) */
+    private readonly getRefreshToken?;
+    constructor(http: HttpClient, 
+    /** Optional accessor for the client's current refresh token (used by logout) */
+    getRefreshToken?: (() => string | undefined) | undefined);
     /**
      * Exchange API key for JWT tokens
      */
@@ -411,9 +438,13 @@ declare class AuthResource {
      */
     refresh(params: RefreshTokenParams): Promise<RefreshTokenResponse>;
     /**
-     * Logout and invalidate current token
+     * Logout and revoke the refresh token server-side.
+     *
+     * The backend requires the refresh token in the body to invalidate the
+     * session. When omitted, the client's current refresh token (if any) is
+     * used automatically.
      */
-    logout(): Promise<void>;
+    logout(refreshToken?: string): Promise<void>;
     /**
      * Get current user/session info
      */
@@ -2343,8 +2374,16 @@ interface RealtimeConnectionOptions {
     baseUrl: string;
     /** WebSocket URL for realtime connection (e.g., wss://api.spooled.cloud) - used for WebSocket */
     wsUrl: string;
-    /** JWT token for authentication */
+    /** 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.
+     *
+     * 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>;
     /** Auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
     /** Maximum reconnect attempts (default: 10) */
@@ -2387,6 +2426,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>;
     debug?: (message: string, meta?: unknown) => void;
 }
 /** Event handler type - simplified for internal use */

package/dist/index.cjs

@@ -328,9 +328,10 @@ async function parseErrorBody(response) {
   try {
     const body = await response.json();
     if (typeof body === "object" && body !== null) {
+      const message = (body.message ?? body.error) || response.statusText;
       return {
         code: body.code || "UNKNOWN_ERROR",
-        message: body.message || response.statusText,
+        message,
         details: body.details
       };
     }
@@ -548,12 +549,17 @@ function createRetryWrapper(config) {
 }
 
 // src/utils/http.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
 var HttpClient = class {
   config;
   circuitBreaker;
   debug;
   /** Current authentication token (API key or JWT) */
   authToken;
+  /** Optional function to mint a fresh access token (set when auto-refresh is enabled) */
+  refreshTokenFn = null;
+  /** Guard to prevent a refresh request from recursively triggering another refresh */
+  isRefreshing = false;
   constructor(config, circuitBreaker) {
     this.config = config;
     this.circuitBreaker = circuitBreaker;
@@ -567,9 +573,13 @@ var HttpClient = class {
     this.authToken = token;
   }
   /**
-   * Set the token refresh function (for future use)
+   * Set the token refresh function.
+   *
+   * When set, an expired-token 401 on the data plane triggers a single
+   * refresh + retry of the original request with the new token.
    */
-  setRefreshTokenFn(_fn) {
+  setRefreshTokenFn(fn) {
+    this.refreshTokenFn = fn;
   }
   /**
    * Build full URL with query parameters
@@ -639,7 +649,7 @@ var HttpClient = class {
   /**
    * Execute a single HTTP request (no retry)
    */
-  async executeRequest(url, options) {
+  async executeRequest(url, options, hasRefreshed = false) {
     const method = options.method ?? "GET";
     const headers = this.buildHeaders(options.headers);
     const timeout = options.timeout ?? this.config.timeout;
@@ -668,6 +678,23 @@ var HttpClient = class {
     }
     this.debug?.(`Response: ${response.status}`, { url });
     if (!response.ok) {
+      if (response.status === 401 && this.refreshTokenFn && !hasRefreshed && !this.isRefreshing) {
+        let refreshed = false;
+        this.isRefreshing = true;
+        try {
+          const newToken = await this.refreshTokenFn();
+          this.setAuthToken(newToken);
+          refreshed = true;
+        } catch (refreshError) {
+          const message = refreshError instanceof Error ? refreshError.message : "unknown";
+          this.debug?.("Token refresh failed", { error: message });
+        } finally {
+          this.isRefreshing = false;
+        }
+        if (refreshed) {
+          return this.executeRequest(url, options, true);
+        }
+      }
       const apiError = await createErrorFromResponse(response);
       throw apiError;
     }
@@ -692,6 +719,7 @@ var HttpClient = class {
    */
   async request(path, options = {}) {
     const url = this.buildUrl(path, options.params, options.skipApiPrefix);
+    const method = options.method ?? "GET";
     const execute = async () => {
       return this.circuitBreaker.execute(() => this.executeRequest(url, options));
     };
@@ -699,13 +727,46 @@ var HttpClient = class {
       return execute();
     }
     return withRetry(execute, {
-      config: this.config.retry,
+      config: this.resolveRetryConfig(method, options),
       signal: options.signal,
       onRetry: (attempt, error, delayMs) => {
         this.debug?.(`Retry attempt ${attempt} after ${delayMs}ms`, { error: error.message });
       }
     });
   }
+  /**
+   * Determine whether a request carries an idempotency key (making a
+   * non-idempotent method safe to retry).
+   */
+  hasIdempotencyKey(options) {
+    if (!options.headers) {
+      return false;
+    }
+    return Object.keys(options.headers).some((key) => key.toLowerCase() === "idempotency-key");
+  }
+  /**
+   * Resolve the retry configuration for a request.
+   *
+   * Idempotent methods (GET/PUT/DELETE) and any request carrying an
+   * idempotency key retry normally. Non-idempotent methods (POST/PATCH)
+   * without an idempotency key must NOT be retried on ambiguous failures
+   * (network/timeout/5xx) — doing so risks duplicate jobs, double claims,
+   * etc. They are still retried on 429, which is rejected before the
+   * server processes the request and is therefore side-effect-free.
+   */
+  resolveRetryConfig(method, options) {
+    const base = this.config.retry;
+    if (base.retryOn) {
+      return base;
+    }
+    if (IDEMPOTENT_METHODS.has(method) || this.hasIdempotencyKey(options)) {
+      return base;
+    }
+    return {
+      ...base,
+      retryOn: (error) => error instanceof RateLimitError
+    };
+  }
   /**
    * Make a GET request
    */
@@ -907,8 +968,9 @@ function createCircuitBreaker(config) {
 
 // src/resources/auth.ts
 var AuthResource = class {
-  constructor(http) {
+  constructor(http, getRefreshToken) {
     this.http = http;
+    this.getRefreshToken = getRefreshToken;
   }
   /**
    * Exchange API key for JWT tokens
@@ -923,10 +985,15 @@ var AuthResource = class {
     return this.http.post("/auth/refresh", params);
   }
   /**
-   * Logout and invalidate current token
+   * Logout and revoke the refresh token server-side.
+   *
+   * The backend requires the refresh token in the body to invalidate the
+   * session. When omitted, the client's current refresh token (if any) is
+   * used automatically.
    */
-  async logout() {
-    await this.http.post("/auth/logout");
+  async logout(refreshToken) {
+    const token = refreshToken ?? this.getRefreshToken?.();
+    await this.http.post("/auth/logout", token ? { refreshToken: token } : void 0);
   }
   /**
    * Get current user/session info
@@ -1796,7 +1863,10 @@ var WebSocketRealtimeClient = class {
       maxReconnectDelay: 3e4,
       debug: () => {
       },
-      ...options
+      ...options,
+      // 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)
     };
   }
   /**
@@ -1823,8 +1893,14 @@ var WebSocketRealtimeClient = class {
       return;
     }
     this.setState("connecting");
-    const wsUrl = this.buildWsUrl();
-    this.options.debug(`Connecting to ${wsUrl}`);
+    let wsUrl;
+    try {
+      wsUrl = await this.buildWsUrl();
+    } catch (error) {
+      this.setState("disconnected");
+      throw new Error(`Failed to acquire realtime token: ${error}`);
+    }
+    this.options.debug(`Connecting to ${redactToken(wsUrl)}`);
     let WebSocketImpl;
     try {
       WebSocketImpl = await this.getWebSocketImpl();
@@ -1938,9 +2014,10 @@ var WebSocketRealtimeClient = class {
     return () => this.stateChangeHandlers.delete(handler);
   }
   // Private methods
-  buildWsUrl() {
+  async buildWsUrl() {
     const wsBase = this.options.wsUrl;
-    return `${wsBase}/api/v1/ws?token=${encodeURIComponent(this.options.token)}`;
+    const token = await this.options.tokenProvider();
+    return `${wsBase}/api/v1/ws?token=${encodeURIComponent(token)}`;
   }
   setState(state) {
     if (this.state !== state) {
@@ -1950,7 +2027,7 @@ var WebSocketRealtimeClient = class {
   }
   handleMessage(data) {
     try {
-      const message = JSON.parse(data);
+      const message = convertResponse(JSON.parse(data));
       if (message.type === "subscribed" || message.type === "unsubscribed" || message.type === "error") {
         this.handleCommandResponse(message);
         return;
@@ -2007,10 +2084,11 @@ var WebSocketRealtimeClient = class {
   scheduleReconnect() {
     this.setState("reconnecting");
     this.reconnectAttempts++;
-    const delay = Math.min(
+    const baseDelay = Math.min(
       this.options.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
       this.options.maxReconnectDelay
     );
+    const delay = Math.floor(baseDelay + Math.random() * baseDelay * 0.25);
     this.options.debug(`Scheduling reconnect attempt ${this.reconnectAttempts} in ${delay}ms`);
     this.reconnectTimer = setTimeout(async () => {
       try {
@@ -2058,6 +2136,9 @@ var WebSocketRealtimeClient = class {
     return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
   }
 };
+function redactToken(url) {
+  return url.replace(/([?&](?:token|api_key)=)[^&]*/gi, "$1***");
+}
 
 // src/realtime/sse.ts
 var SseRealtimeClient = class {
@@ -2080,7 +2161,10 @@ var SseRealtimeClient = class {
       maxReconnectDelay: 3e4,
       debug: () => {
       },
-      ...options
+      ...options,
+      // 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)
     };
   }
   /**
@@ -2112,9 +2196,15 @@ var SseRealtimeClient = class {
         throw new Error("eventsource package is required for SSE in Node.js. Install it with: npm install eventsource");
       }
     }
+    let token;
+    try {
+      token = await this.options.tokenProvider();
+    } catch (error) {
+      this.setState("disconnected");
+      throw new Error(`Failed to acquire realtime token: ${error}`);
+    }
     return new Promise((resolve, reject) => {
       try {
-        const token = this.options.token;
         this.eventSource = new EventSourceImpl(sseUrl, {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           fetch: (input, init) => fetch(input, {
@@ -2138,6 +2228,10 @@ var SseRealtimeClient = class {
           this.options.debug("SSE error");
           if (this.state === "connecting") {
             this.setState("disconnected");
+            if (this.eventSource) {
+              this.eventSource.close();
+              this.eventSource = null;
+            }
             reject(new Error("SSE connection failed"));
             return;
           }
@@ -2222,7 +2316,7 @@ var SseRealtimeClient = class {
   }
   handleMessage(data) {
     try {
-      const event = JSON.parse(data);
+      const event = convertResponse(JSON.parse(data));
       this.options.debug(`Received SSE event: ${event.type}`, event);
       const handlers = this.eventHandlers.get(event.type);
       if (handlers) {
@@ -2260,10 +2354,11 @@ var SseRealtimeClient = class {
   scheduleReconnect() {
     this.setState("reconnecting");
     this.reconnectAttempts++;
-    const delay = Math.min(
+    const baseDelay = Math.min(
       this.options.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
       this.options.maxReconnectDelay
     );
+    const delay = Math.floor(baseDelay + Math.random() * baseDelay * 0.25);
     this.options.debug(`Scheduling SSE reconnect attempt ${this.reconnectAttempts} in ${delay}ms`);
     this.reconnectTimer = setTimeout(async () => {
       try {
@@ -2284,6 +2379,7 @@ var SpooledRealtime = class {
       baseUrl: options.baseUrl,
       wsUrl: options.wsUrl,
       token: options.token,
+      tokenProvider: options.tokenProvider,
       autoReconnect: options.autoReconnect,
       maxReconnectAttempts: options.maxReconnectAttempts,
       reconnectDelay: options.reconnectDelay,
@@ -2783,7 +2879,7 @@ var SpooledClient = class _SpooledClient {
     if (this.config.accessToken && this.config.refreshToken && this.config.autoRefreshToken) {
       this.http.setRefreshTokenFn(this.refreshAccessToken.bind(this));
     }
-    this.auth = new AuthResource(this.http);
+    this.auth = new AuthResource(this.http, () => this.config.refreshToken);
     this.jobs = new JobsResource(this.http);
     this.queues = new QueuesResource(this.http);
     this.workers = new WorkersResource(this.http);
@@ -2862,6 +2958,9 @@ 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(),
       ...options,
       debug: this.config.debug ?? void 0
     });
@@ -3169,9 +3268,11 @@ var SpooledWorker = class {
         this.waitForActiveJobs(),
         this.sleep(this.options.shutdownTimeout)
       ]);
-      for (const [jobId, active] of this.activeJobs.entries()) {
+      const remaining = Array.from(this.activeJobs.entries());
+      for (const [jobId, active] of remaining) {
         this.debug(`Force-failing job ${jobId} due to shutdown timeout`);
         await this.failJob(active.job, "Worker shutdown timeout");
+        this.cleanupJob(jobId);
       }
     }
     if (this.workerId) {