@spooled/sdk 1.0.32 → 1.0.34

package/dist/{index-CfLL1w6Y.d.cts → index-CYEamGDj.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";
 /**
@@ -647,6 +647,13 @@ interface ClaimedJob {
     maxRetries: number;
     timeoutSeconds: number;
     leaseExpiresAt?: string;
+    /**
+     * Lease fencing token for this claim. Echo it back on
+     * complete/fail/heartbeat so the operation applies only to the lease this
+     * worker actually holds (backend rejects stale leases with 409
+     * LEASE_EXPIRED). Omitted = legacy behavior.
+     */
+    leaseId?: string;
 }
 /** Parameters for claiming jobs */
 interface ClaimJobsParams {
@@ -669,6 +676,8 @@ interface CompleteJobParams {
     workerId: string;
     /** Optional result payload */
     result?: JsonObject;
+    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    leaseId?: string;
 }
 /** Parameters for failing a job */
 interface FailJobParams {
@@ -676,6 +685,8 @@ interface FailJobParams {
     workerId: string;
     /** Error message (1-2048 chars) */
     error: string;
+    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    leaseId?: string;
 }
 /** Parameters for job heartbeat */
 interface HeartbeatJobParams {
@@ -683,6 +694,8 @@ interface HeartbeatJobParams {
     workerId: string;
     /** Lease duration in seconds (5-3600) */
     leaseDurationSecs: number;
+    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    leaseId?: string;
 }
 /** Response for priority boost */
 interface BoostPriorityResponse {
@@ -2315,6 +2328,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 +2396,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 */
@@ -2582,6 +2615,12 @@ interface GrpcJob {
     leaseExpiresAt?: GrpcTimestamp | string | null;
     assignedWorkerId?: string | null;
     idempotencyKey?: string | null;
+    /**
+     * Lease fencing token (proto `lease_id`). Returned on dequeue; echo it back
+     * in Complete/Fail/RenewLease so the operation applies only to the lease
+     * this worker actually holds (empty = legacy worker_id fence).
+     */
+    leaseId?: string;
 }
 /** Enqueue request */
 interface GrpcEnqueueRequest {
@@ -2617,6 +2656,8 @@ interface GrpcCompleteRequest {
     workerId: string;
     /** Result as object (will be converted to google.protobuf.Struct) */
     result?: Record<string, unknown>;
+    /** Lease fencing token from the dequeued job (proto `lease_id`) */
+    leaseId?: string;
 }
 /** Complete response */
 interface GrpcCompleteResponse {
@@ -2628,6 +2669,8 @@ interface GrpcFailRequest {
     workerId: string;
     error: string;
     retry?: boolean;
+    /** Lease fencing token from the dequeued job (proto `lease_id`) */
+    leaseId?: string;
 }
 /** Fail response */
 interface GrpcFailResponse {
@@ -2640,6 +2683,8 @@ interface GrpcRenewLeaseRequest {
     jobId: string;
     workerId: string;
     extensionSecs: number;
+    /** Lease fencing token from the dequeued job (proto `lease_id`) */
+    leaseId?: string;
 }
 /** Renew lease response */
 interface GrpcRenewLeaseResponse {

package/dist/{index-CfLL1w6Y.d.ts → index-CYEamGDj.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";
 /**
@@ -647,6 +647,13 @@ interface ClaimedJob {
     maxRetries: number;
     timeoutSeconds: number;
     leaseExpiresAt?: string;
+    /**
+     * Lease fencing token for this claim. Echo it back on
+     * complete/fail/heartbeat so the operation applies only to the lease this
+     * worker actually holds (backend rejects stale leases with 409
+     * LEASE_EXPIRED). Omitted = legacy behavior.
+     */
+    leaseId?: string;
 }
 /** Parameters for claiming jobs */
 interface ClaimJobsParams {
@@ -669,6 +676,8 @@ interface CompleteJobParams {
     workerId: string;
     /** Optional result payload */
     result?: JsonObject;
+    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    leaseId?: string;
 }
 /** Parameters for failing a job */
 interface FailJobParams {
@@ -676,6 +685,8 @@ interface FailJobParams {
     workerId: string;
     /** Error message (1-2048 chars) */
     error: string;
+    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    leaseId?: string;
 }
 /** Parameters for job heartbeat */
 interface HeartbeatJobParams {
@@ -683,6 +694,8 @@ interface HeartbeatJobParams {
     workerId: string;
     /** Lease duration in seconds (5-3600) */
     leaseDurationSecs: number;
+    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    leaseId?: string;
 }
 /** Response for priority boost */
 interface BoostPriorityResponse {
@@ -2315,6 +2328,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 +2396,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 */
@@ -2582,6 +2615,12 @@ interface GrpcJob {
     leaseExpiresAt?: GrpcTimestamp | string | null;
     assignedWorkerId?: string | null;
     idempotencyKey?: string | null;
+    /**
+     * Lease fencing token (proto `lease_id`). Returned on dequeue; echo it back
+     * in Complete/Fail/RenewLease so the operation applies only to the lease
+     * this worker actually holds (empty = legacy worker_id fence).
+     */
+    leaseId?: string;
 }
 /** Enqueue request */
 interface GrpcEnqueueRequest {
@@ -2617,6 +2656,8 @@ interface GrpcCompleteRequest {
     workerId: string;
     /** Result as object (will be converted to google.protobuf.Struct) */
     result?: Record<string, unknown>;
+    /** Lease fencing token from the dequeued job (proto `lease_id`) */
+    leaseId?: string;
 }
 /** Complete response */
 interface GrpcCompleteResponse {
@@ -2628,6 +2669,8 @@ interface GrpcFailRequest {
     workerId: string;
     error: string;
     retry?: boolean;
+    /** Lease fencing token from the dequeued job (proto `lease_id`) */
+    leaseId?: string;
 }
 /** Fail response */
 interface GrpcFailResponse {
@@ -2640,6 +2683,8 @@ interface GrpcRenewLeaseRequest {
     jobId: string;
     workerId: string;
     extensionSecs: number;
+    /** Lease fencing token from the dequeued job (proto `lease_id`) */
+    leaseId?: string;
 }
 /** Renew lease response */
 interface GrpcRenewLeaseResponse {

package/dist/index.cjs

@@ -49,10 +49,10 @@ 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) {
@@ -327,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;
 }
@@ -1848,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;
@@ -1863,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();
@@ -1968,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);
@@ -1980,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);
@@ -1993,7 +2026,7 @@ var WebSocketRealtimeClient = class {
     }
     this.subscriptions.delete(filterId);
     if (this.state === "connected") {
-      await this.sendCommand({ type: "unsubscribe", filter });
+      this.sendCommand("Unsubscribe", filter);
     }
   }
   /**
@@ -2046,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) => {
@@ -2074,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 {
@@ -2116,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***");
@@ -2351,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) => {
@@ -3277,7 +3288,7 @@ var SpooledWorker = class {
       ...DEFAULT_OPTIONS,
       hostname: os.hostname(),
       workerType: "nodejs",
-      version: "1.0.26",
+      version: "1.0.34",
       metadata: {},
       ...options
     };
@@ -3522,7 +3533,8 @@ var SpooledWorker = class {
     try {
       await this.client.jobs.complete(job.id, {
         workerId: this.workerId,
-        result
+        result,
+        ...job.leaseId !== void 0 && { leaseId: job.leaseId }
       });
       this.emit("job:completed", {
         jobId: job.id,
@@ -3539,7 +3551,8 @@ var SpooledWorker = class {
     try {
       await this.client.jobs.fail(job.id, {
         workerId: this.workerId,
-        error: errorMessage
+        error: errorMessage,
+        ...job.leaseId !== void 0 && { leaseId: job.leaseId }
       });
       this.emit("job:failed", {
         jobId: job.id,
@@ -3560,10 +3573,12 @@ var SpooledWorker = class {
   }
   async sendJobHeartbeat(jobId) {
     if (!this.workerId) return;
+    const leaseId = this.activeJobs.get(jobId)?.job.leaseId;
     try {
       await this.client.jobs.heartbeat(jobId, {
         workerId: this.workerId,
-        leaseDurationSecs: this.options.leaseDuration
+        leaseDurationSecs: this.options.leaseDuration,
+        ...leaseId !== void 0 && { leaseId }
       });
     } catch (error) {
       this.debug(`Job heartbeat failed for ${jobId}`, error);