@spooled/sdk 1.0.31 → 1.0.33

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-CfLL1w6Y.d.cts → index-QIsnz4Bc.d.cts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.31";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.33";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.31";
+declare const SDK_VERSION = "1.0.33";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -2315,6 +2315,26 @@ interface JobStatusChangedEvent extends RealtimeEventBase {
         newStatus: JobStatus;
     };
 }
+/** Queue stats update event (backend `QueueStats`) */
+interface QueueStatsEvent extends RealtimeEventBase {
+    type: 'queue.stats';
+    data: {
+        queueName: string;
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+    };
+}
+/** Worker heartbeat event (backend `WorkerHeartbeat`) */
+interface WorkerHeartbeatEvent extends RealtimeEventBase {
+    type: 'worker.heartbeat';
+    data: {
+        workerId: string;
+        status: string;
+        currentJobId?: string;
+    };
+}
 /** Queue paused event */
 interface QueuePausedEvent extends RealtimeEventBase {
     type: 'queue.paused';
@@ -2363,7 +2383,7 @@ interface HeartbeatEvent extends RealtimeEventBase {
     };
 }
 /** All realtime event types */
-type RealtimeEvent = JobCreatedEvent | JobStartedEvent | JobCompletedEvent | JobFailedEvent | JobProgressEvent | JobStatusChangedEvent | QueuePausedEvent | QueueResumedEvent | WorkerRegisteredEvent | WorkerDeregisteredEvent | ScheduleTriggeredEvent | HeartbeatEvent;
+type RealtimeEvent = JobCreatedEvent | JobStartedEvent | JobCompletedEvent | JobFailedEvent | JobProgressEvent | JobStatusChangedEvent | QueueStatsEvent | QueuePausedEvent | QueueResumedEvent | WorkerRegisteredEvent | WorkerDeregisteredEvent | WorkerHeartbeatEvent | ScheduleTriggeredEvent | HeartbeatEvent;
 /** Event type names */
 type RealtimeEventType = RealtimeEvent['type'];
 /** Extract event data type from event type name */

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

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.31";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.33";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.31";
+declare const SDK_VERSION = "1.0.33";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -2315,6 +2315,26 @@ interface JobStatusChangedEvent extends RealtimeEventBase {
         newStatus: JobStatus;
     };
 }
+/** Queue stats update event (backend `QueueStats`) */
+interface QueueStatsEvent extends RealtimeEventBase {
+    type: 'queue.stats';
+    data: {
+        queueName: string;
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+    };
+}
+/** Worker heartbeat event (backend `WorkerHeartbeat`) */
+interface WorkerHeartbeatEvent extends RealtimeEventBase {
+    type: 'worker.heartbeat';
+    data: {
+        workerId: string;
+        status: string;
+        currentJobId?: string;
+    };
+}
 /** Queue paused event */
 interface QueuePausedEvent extends RealtimeEventBase {
     type: 'queue.paused';
@@ -2363,7 +2383,7 @@ interface HeartbeatEvent extends RealtimeEventBase {
     };
 }
 /** All realtime event types */
-type RealtimeEvent = JobCreatedEvent | JobStartedEvent | JobCompletedEvent | JobFailedEvent | JobProgressEvent | JobStatusChangedEvent | QueuePausedEvent | QueueResumedEvent | WorkerRegisteredEvent | WorkerDeregisteredEvent | ScheduleTriggeredEvent | HeartbeatEvent;
+type RealtimeEvent = JobCreatedEvent | JobStartedEvent | JobCompletedEvent | JobFailedEvent | JobProgressEvent | JobStatusChangedEvent | QueueStatsEvent | QueuePausedEvent | QueueResumedEvent | WorkerRegisteredEvent | WorkerDeregisteredEvent | WorkerHeartbeatEvent | ScheduleTriggeredEvent | HeartbeatEvent;
 /** Event type names */
 type RealtimeEventType = RealtimeEvent['type'];
 /** Extract event data type from event type name */

package/dist/index.cjs

@@ -49,12 +49,19 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.0.31",
+  userAgent: "@spooled/sdk-nodejs/1.0.33",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.0.31";
+var SDK_VERSION = "1.0.33";
 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,
@@ -320,22 +327,33 @@ function parseRateLimitHeaders(headers) {
   }
   return info;
 }
+var MAX_RAW_ERROR_BODY_CHARS = 500;
 async function parseErrorBody(response) {
   const contentType = response.headers.get("Content-Type") || "";
-  if (!contentType.includes("application/json")) {
+  let raw;
+  try {
+    raw = await response.text();
+  } catch {
     return null;
   }
-  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,
-        details: body.details
-      };
+  if (contentType.includes("application/json")) {
+    try {
+      const body = JSON.parse(raw);
+      if (typeof body === "object" && body !== null) {
+        const message = (body.message ?? body.error) || response.statusText;
+        return {
+          code: body.code || "UNKNOWN_ERROR",
+          message,
+          details: body.details
+        };
+      }
+    } catch {
     }
-  } catch {
+  }
+  const trimmed = raw.trim();
+  if (trimmed) {
+    const message = trimmed.length > MAX_RAW_ERROR_BODY_CHARS ? `${trimmed.slice(0, MAX_RAW_ERROR_BODY_CHARS)}\u2026` : trimmed;
+    return { code: "UNKNOWN_ERROR", message };
   }
   return null;
 }
@@ -1841,6 +1859,24 @@ var WebhookIngestionResource = class {
   }
 };
 
+// src/realtime/event-map.ts
+var BACKEND_EVENT_TYPE_MAP = {
+  JobStatusChange: "job.status_changed",
+  JobCreated: "job.created",
+  JobCompleted: "job.completed",
+  JobFailed: "job.failed",
+  QueueStats: "queue.stats",
+  WorkerHeartbeat: "worker.heartbeat",
+  WorkerRegistered: "worker.registered",
+  WorkerDeregistered: "worker.deregistered",
+  SystemHealth: "system.health",
+  Ping: "ping",
+  Error: "error"
+};
+function mapEventType(type) {
+  return BACKEND_EVENT_TYPE_MAP[type] ?? type;
+}
+
 // src/realtime/websocket.ts
 var WebSocketRealtimeClient = class {
   options;
@@ -1856,7 +1892,6 @@ var WebSocketRealtimeClient = class {
    */
   authFailure = false;
   subscriptions = /* @__PURE__ */ new Map();
-  pendingCommands = /* @__PURE__ */ new Map();
   // Event handlers
   eventHandlers = /* @__PURE__ */ new Map();
   allEventsHandlers = /* @__PURE__ */ new Set();
@@ -1961,10 +1996,13 @@ var WebSocketRealtimeClient = class {
     }
     this.setState("disconnected");
     this.subscriptions.clear();
-    this.clearPendingCommands();
   }
   /**
-   * Subscribe to events matching a filter
+   * Subscribe to events matching a filter.
+   *
+   * The server applies filtering itself and sends no acknowledgement, so this
+   * resolves as soon as the command has been written to the socket. The filter
+   * is tracked locally so it is replayed automatically on reconnect.
    */
   async subscribe(filter) {
     const filterId = this.filterToId(filter);
@@ -1973,11 +2011,13 @@ var WebSocketRealtimeClient = class {
     }
     this.subscriptions.set(filterId, filter);
     if (this.state === "connected") {
-      await this.sendCommand({ type: "subscribe", filter });
+      this.sendCommand("Subscribe", filter);
     }
   }
   /**
-   * Unsubscribe from events matching a filter
+   * Unsubscribe from events matching a filter.
+   *
+   * Fire-and-forget, like {@link subscribe} — the server sends no ack.
    */
   async unsubscribe(filter) {
     const filterId = this.filterToId(filter);
@@ -1986,7 +2026,7 @@ var WebSocketRealtimeClient = class {
     }
     this.subscriptions.delete(filterId);
     if (this.state === "connected") {
-      await this.sendCommand({ type: "unsubscribe", filter });
+      this.sendCommand("Unsubscribe", filter);
     }
   }
   /**
@@ -2039,13 +2079,11 @@ var WebSocketRealtimeClient = class {
   handleMessage(data) {
     try {
       const message = convertResponse(JSON.parse(data));
-      if (message.type === "subscribed" || message.type === "unsubscribed" || message.type === "error") {
-        this.handleCommandResponse(message);
-        return;
-      }
+      const eventType = mapEventType(String(message.type));
+      message.type = eventType;
       const event = message;
-      this.options.debug(`Received event: ${event.type}`, event);
-      const handlers = this.eventHandlers.get(event.type);
+      this.options.debug(`Received event: ${eventType}`, event);
+      const handlers = this.eventHandlers.get(eventType);
       if (handlers) {
         const eventData = event.data;
         handlers.forEach((handler) => {
@@ -2067,25 +2105,8 @@ var WebSocketRealtimeClient = class {
       this.options.debug("Failed to parse message", { data, error });
     }
   }
-  handleCommandResponse(response) {
-    if (!response.requestId) {
-      return;
-    }
-    const pending = this.pendingCommands.get(response.requestId);
-    if (!pending) {
-      return;
-    }
-    clearTimeout(pending.timeout);
-    this.pendingCommands.delete(response.requestId);
-    if (response.type === "error") {
-      pending.reject(new Error(response.error || "Unknown error"));
-    } else {
-      pending.resolve();
-    }
-  }
   handleDisconnect() {
     this.ws = null;
-    this.clearPendingCommands();
     if (this.options.autoReconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
       this.scheduleReconnect();
     } else {
@@ -2109,43 +2130,37 @@ var WebSocketRealtimeClient = class {
       }
     }, delay);
   }
-  async resubscribeAll() {
+  resubscribeAll() {
     for (const filter of this.subscriptions.values()) {
       try {
-        await this.sendCommand({ type: "subscribe", filter });
+        this.sendCommand("Subscribe", filter);
       } catch (error) {
         this.options.debug("Failed to resubscribe", { filter, error });
       }
     }
   }
-  async sendCommand(command) {
+  /**
+   * Send a subscribe/unsubscribe command to the server.
+   *
+   * The backend `ClientCommand` shape is `{ cmd, queue, job_id }` and it sends
+   * no acknowledgement, so this is fire-and-forget — it writes to the socket
+   * and returns. The `SubscriptionFilter`'s `workerId`/`scheduleId` have no
+   * server-side equivalent and are ignored.
+   */
+  sendCommand(cmd, filter) {
     if (!this.ws || this.state !== "connected") {
       throw new Error("WebSocket not connected");
     }
-    const requestId = this.generateRequestId();
-    const fullCommand = { ...command, requestId };
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.pendingCommands.delete(requestId);
-        reject(new Error("Command timeout"));
-      }, 1e4);
-      this.pendingCommands.set(requestId, { resolve, reject, timeout });
-      this.ws.send(JSON.stringify(fullCommand));
-    });
-  }
-  clearPendingCommands() {
-    for (const pending of this.pendingCommands.values()) {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error("Connection closed"));
-    }
-    this.pendingCommands.clear();
+    const command = {
+      cmd,
+      queue: filter.queueName,
+      job_id: filter.jobId
+    };
+    this.ws.send(JSON.stringify(command));
   }
   filterToId(filter) {
     return JSON.stringify(filter);
   }
-  generateRequestId() {
-    return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
-  }
 };
 function redactToken(url) {
   return url.replace(/([?&](?:token|api_key)=)[^&]*/gi, "$1***");
@@ -2344,9 +2359,12 @@ var SseRealtimeClient = class {
   }
   handleMessage(data) {
     try {
-      const event = convertResponse(JSON.parse(data));
-      this.options.debug(`Received SSE event: ${event.type}`, event);
-      const handlers = this.eventHandlers.get(event.type);
+      const parsed = convertResponse(JSON.parse(data));
+      const eventType = mapEventType(String(parsed.type));
+      parsed.type = eventType;
+      const event = parsed;
+      this.options.debug(`Received SSE event: ${eventType}`, event);
+      const handlers = this.eventHandlers.get(eventType);
       if (handlers) {
         const eventData = event.data;
         handlers.forEach((handler) => {