@spooled/sdk 1.0.34 → 1.0.36

package/README.md

@@ -321,7 +321,10 @@ All operations automatically enforce tier-based limits:
 - ✅ Webhook creation
 
 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`:
+`code: "QUOTA_EXCEEDED"`. The SDK reliably preserves the HTTP status, error code, message,
+request ID, and rate-limit headers. `error.details` is populated only when the server nests
+metadata under a JSON `details` field; quota fields sent at the top level of the server payload
+(such as `resource`, `current`, `limit`, and `plan`) are not currently exposed by the SDK.
 
 ```typescript
 import { RateLimitError } from '@spooled/sdk';
@@ -330,9 +333,10 @@ try {
   await client.jobs.create({ /* ... */ });
 } catch (error) {
   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);
+    console.log(`Request ID: ${error.requestId ?? 'not provided'}`);
+    // Present only if this server response included a nested `details` object.
+    if (error.details) console.log('Details:', error.details);
   }
 }
 ```
@@ -406,12 +410,13 @@ const { jobs } = await grpcClient.queue.dequeue({
   leaseDurationSecs: 300
 });
 
-// Process and complete
+// Process and complete. Echo leaseId when present so current servers can fence stale executions; legacy servers may omit it and then use worker-ID-only fencing.
 for (const job of jobs) {
   await processJob(job);
   await grpcClient.queue.complete({
     jobId: job.id,
     workerId,
+    leaseId: job.leaseId ?? undefined,
     result: { success: true }
   });
 }
@@ -441,6 +446,46 @@ import type {
 } from '@spooled/sdk';
 ```
 
+## Development and releases
+
+Before opening a pull request or tagging a release, run the same checks used by the package and publish workflow:
+
+```bash
+npm ci
+npm run lint
+npm run typecheck
+npm run build
+npm test
+```
+
+Production-safe API verification is separate and credentialed: `npm run verify:production`. Integration tests use `npm run test:integration` against a local or isolated test backend.
+
+Maintainers release by pushing a matching `vX.Y.Z` tag. The tag workflow verifies all same-artifact version surfaces before publishing through npm Trusted Publishing (OIDC) with provenance.
+
+### Maintainer release checklist (advisory)
+
+This checklist records evidence and does not block ordinary commits, experiments, or compatibility research. A mismatch among values that identify the same npm artifact is a release error and cannot be waived for publication. Publishing the SDK is not a service deployment; consumers report new metadata only after upgrading and restarting or redeploying their applications.
+
+Before pushing `vX.Y.Z`:
+
+- [ ] Set `package.json.version` to `X.Y.Z`.
+- [ ] Regenerate `package-lock.json`; verify both top-level `version` and `packages[""].version` are `X.Y.Z`.
+- [ ] Set `SDK_VERSION` and the default User-Agent in `src/config.ts` to `X.Y.Z`.
+- [ ] Confirm `SpooledWorker` derives its default registration version from `SDK_VERSION`.
+- [ ] Add `## [X.Y.Z] - YYYY-MM-DD` to `CHANGELOG.md` and review version-bearing worker documentation.
+- [ ] Run `npm ci`, lint, typecheck, build, tests, and `npm pack --dry-run`.
+- [ ] Review the packed file list and compiled output; confirm the package contains no local logs, caches, credentials, or unintended generated files.
+- [ ] Record any cross-repository compatibility difference separately; backend, SDK, and application versions are not required to match numerically.
+
+Publish and verify:
+
+- [ ] Create one immutable `vX.Y.Z` tag on the reviewed commit and never move or recreate a pushed tag. Fix forward with a new patch version after external visibility.
+- [ ] Record the tag commit and publish workflow URL.
+- [ ] Verify `npm view @spooled/sdk@X.Y.Z version gitHead dist.integrity dist.attestations --json` against the tag and commit.
+- [ ] Confirm `latest` points to `X.Y.Z` when intended and inspect the published tarball's `SDK_VERSION`, User-Agent, and worker registration default.
+- [ ] Confirm npm provenance names this repository, `.github/workflows/publish.yml`, `refs/tags/vX.Y.Z`, and the release commit.
+- [ ] Record registry publication separately from consumer rollout, backend deployment, or documentation deployment.
+
 ## License
 
 Apache-2.0 - see [LICENSE](LICENSE) for details.

package/dist/{index-CYEamGDj.d.cts → index-CNhKw4vH.d.cts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.33";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.36";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.33";
+declare const SDK_VERSION = "1.0.36";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -559,7 +559,7 @@ interface Job {
     parentJobId?: string;
     completionWebhook?: string;
     assignedWorkerId?: string;
-    leaseId?: string;
+    leaseId?: string | null;
     leaseExpiresAt?: string;
     idempotencyKey?: string;
     updatedAt: string;
@@ -653,7 +653,7 @@ interface ClaimedJob {
      * worker actually holds (backend rejects stale leases with 409
      * LEASE_EXPIRED). Omitted = legacy behavior.
      */
-    leaseId?: string;
+    leaseId?: string | null;
 }
 /** Parameters for claiming jobs */
 interface ClaimJobsParams {
@@ -2620,7 +2620,7 @@ interface GrpcJob {
      * in Complete/Fail/RenewLease so the operation applies only to the lease
      * this worker actually holds (empty = legacy worker_id fence).
      */
-    leaseId?: string;
+    leaseId?: string | null;
 }
 /** Enqueue request */
 interface GrpcEnqueueRequest {
@@ -3369,6 +3369,7 @@ interface WorkerEventData {
 }
 /** Active job tracking */
 interface ActiveJob {
+    readonly executionId: symbol;
     job: ClaimedJob;
     startedAt: Date;
     heartbeatTimer?: ReturnType<typeof setInterval>;

package/dist/{index-CYEamGDj.d.ts → index-CNhKw4vH.d.ts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.33";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.36";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.33";
+declare const SDK_VERSION = "1.0.36";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -559,7 +559,7 @@ interface Job {
     parentJobId?: string;
     completionWebhook?: string;
     assignedWorkerId?: string;
-    leaseId?: string;
+    leaseId?: string | null;
     leaseExpiresAt?: string;
     idempotencyKey?: string;
     updatedAt: string;
@@ -653,7 +653,7 @@ interface ClaimedJob {
      * worker actually holds (backend rejects stale leases with 409
      * LEASE_EXPIRED). Omitted = legacy behavior.
      */
-    leaseId?: string;
+    leaseId?: string | null;
 }
 /** Parameters for claiming jobs */
 interface ClaimJobsParams {
@@ -2620,7 +2620,7 @@ interface GrpcJob {
      * in Complete/Fail/RenewLease so the operation applies only to the lease
      * this worker actually holds (empty = legacy worker_id fence).
      */
-    leaseId?: string;
+    leaseId?: string | null;
 }
 /** Enqueue request */
 interface GrpcEnqueueRequest {
@@ -3369,6 +3369,7 @@ interface WorkerEventData {
 }
 /** Active job tracking */
 interface ActiveJob {
+    readonly executionId: symbol;
     job: ClaimedJob;
     startedAt: Date;
     heartbeatTimer?: ReturnType<typeof setInterval>;

package/dist/index.cjs

@@ -49,10 +49,10 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.0.33",
+  userAgent: "@spooled/sdk-nodejs/1.0.36",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.0.33";
+var SDK_VERSION = "1.0.36";
 var API_VERSION = "v1";
 var API_BASE_PATH = `/api/${API_VERSION}`;
 function normalizeCredential(value) {
@@ -774,15 +774,17 @@ var HttpClient = class {
    */
   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
+      retryOn: (error, attempt) => {
+        if (error instanceof RateLimitError) {
+          return base.retryOn ? base.retryOn(error, attempt) : true;
+        }
+        return false;
+      }
     };
   }
   /**
@@ -1964,8 +1966,9 @@ var WebSocketRealtimeClient = class {
         };
         this.ws.onclose = (event) => {
           this.options.debug(`WebSocket closed: ${event.code} ${event.reason}`);
+          const wasConnecting = this.state === "connecting";
           this.handleDisconnect();
-          if (this.state === "connecting") {
+          if (wasConnecting) {
             reject(new Error(`WebSocket connection failed: ${event.reason || "Unknown error"}`));
           }
         };
@@ -2127,6 +2130,11 @@ var WebSocketRealtimeClient = class {
         await this.connect();
       } catch (error) {
         this.options.debug("Reconnect failed", error);
+        if (this.options.autoReconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
+          this.scheduleReconnect();
+        } else {
+          this.setState("disconnected");
+        }
       }
     }, delay);
   }
@@ -2241,7 +2249,7 @@ var SseRealtimeClient = class {
     }
     let token;
     try {
-      token = await this.options.tokenProvider();
+      token = await this.options.tokenProvider(this.reconnectAttempts > 0);
     } catch (error) {
       this.setState("disconnected");
       throw new Error(`Failed to acquire realtime token: ${error}`);
@@ -2411,6 +2419,11 @@ var SseRealtimeClient = class {
         await this.connect(this.filter || void 0);
       } catch (error) {
         this.options.debug("SSE reconnect failed", error);
+        if (this.options.autoReconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
+          this.scheduleReconnect();
+        } else {
+          this.setState("disconnected");
+        }
       }
     }, delay);
   }
@@ -2682,6 +2695,77 @@ function createJobStream(call, options) {
 }
 
 // src/grpc/client.ts
+function encodeStruct(value) {
+  if (value == null) {
+    return void 0;
+  }
+  return {
+    fields: Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, encodeValue(entry)])
+    )
+  };
+}
+function encodeValue(value) {
+  if (value == null) {
+    return { nullValue: 0 };
+  }
+  if (Array.isArray(value)) {
+    return { listValue: { values: value.map(encodeValue) } };
+  }
+  switch (typeof value) {
+    case "number":
+      return { numberValue: value };
+    case "string":
+      return { stringValue: value };
+    case "boolean":
+      return { boolValue: value };
+    case "object":
+      return { structValue: encodeStruct(value) };
+    default:
+      return { stringValue: String(value) };
+  }
+}
+function decodeStruct(value) {
+  if (!value || typeof value !== "object" || !("fields" in value)) {
+    return value;
+  }
+  const fields = value.fields ?? {};
+  return Object.fromEntries(Object.entries(fields).map(([key, entry]) => [key, decodeValue(entry)]));
+}
+function decodeValue(value) {
+  if ("nullValue" in value) {
+    return null;
+  }
+  if ("numberValue" in value) {
+    return value.numberValue;
+  }
+  if ("stringValue" in value) {
+    return value.stringValue;
+  }
+  if ("boolValue" in value) {
+    return value.boolValue;
+  }
+  if ("structValue" in value) {
+    return decodeStruct(value.structValue);
+  }
+  if ("listValue" in value) {
+    return (value.listValue.values ?? []).map(decodeValue);
+  }
+  return void 0;
+}
+function encodeEnqueueRequest(params) {
+  return { ...params, payload: encodeStruct(params.payload) };
+}
+function encodeCompleteRequest(params) {
+  return { ...params, result: encodeStruct(params.result) };
+}
+function decodeJob(job) {
+  return {
+    ...job,
+    payload: decodeStruct(job.payload),
+    result: decodeStruct(job.result)
+  };
+}
 function promisify(client, method, request, metadata) {
   return new Promise((resolve, reject) => {
     method.call(client, request, metadata, (error, response) => {
@@ -2709,19 +2793,20 @@ var GrpcQueueOperations = class {
    * Enqueue a new job
    */
   async enqueue(params) {
-    return promisify(this.client, this.client.Enqueue, params, this.metadata);
+    return promisify(this.client, this.client.Enqueue, encodeEnqueueRequest(params), this.metadata);
   }
   /**
    * Dequeue a job (for workers)
    */
   async dequeue(params) {
-    return promisify(this.client, this.client.Dequeue, params, this.metadata);
+    const response = await promisify(this.client, this.client.Dequeue, params, this.metadata);
+    return { ...response, jobs: response.jobs.map(decodeJob) };
   }
   /**
    * Complete a job successfully
    */
   async complete(params) {
-    return promisify(this.client, this.client.Complete, params, this.metadata);
+    return promisify(this.client, this.client.Complete, encodeCompleteRequest(params), this.metadata);
   }
   /**
    * Fail a job
@@ -2739,7 +2824,8 @@ var GrpcQueueOperations = class {
    * Get a job by ID
    */
   async getJob(jobId) {
-    return promisify(this.client, this.client.GetJob, { jobId }, this.metadata);
+    const response = await promisify(this.client, this.client.GetJob, { jobId }, this.metadata);
+    return { ...response, job: response.job ? decodeJob(response.job) : response.job };
   }
   /**
    * Get queue statistics
@@ -3288,7 +3374,7 @@ var SpooledWorker = class {
       ...DEFAULT_OPTIONS,
       hostname: os.hostname(),
       workerType: "nodejs",
-      version: "1.0.34",
+      version: SDK_VERSION,
       metadata: {},
       ...options
     };
@@ -3395,11 +3481,11 @@ var SpooledWorker = class {
         this.waitForActiveJobs(),
         this.sleep(this.options.shutdownTimeout)
       ]);
-      const remaining = Array.from(this.activeJobs.entries());
-      for (const [jobId, active] of remaining) {
-        this.debug(`Force-failing job ${jobId} due to shutdown timeout`);
+      const remaining = Array.from(this.activeJobs.values());
+      for (const active of remaining) {
+        this.debug(`Force-failing job ${active.job.id} due to shutdown timeout`);
         await this.failJob(active.job, "Worker shutdown timeout");
-        this.cleanupJob(jobId);
+        this.cleanupJob(active);
       }
     }
     if (this.workerId) {
@@ -3482,14 +3568,15 @@ var SpooledWorker = class {
     this.emit("job:claimed", { jobId: job.id, queueName: job.queueName });
     const abortController = new AbortController();
     const activeJob = {
+      executionId: Symbol(job.id),
       job,
       startedAt: /* @__PURE__ */ new Date(),
       abortController
     };
-    this.activeJobs.set(job.id, activeJob);
+    this.activeJobs.set(activeJob.executionId, activeJob);
     const heartbeatInterval = this.options.leaseDuration * this.options.heartbeatFraction * 1e3;
     activeJob.heartbeatTimer = setInterval(() => {
-      this.sendJobHeartbeat(job.id);
+      this.sendJobHeartbeat(activeJob);
     }, heartbeatInterval);
     this.executeHandler(activeJob);
   }
@@ -3525,7 +3612,7 @@ var SpooledWorker = class {
       const errorMessage = error instanceof Error ? error.message : String(error);
       await this.failJob(job, errorMessage);
     } finally {
-      this.cleanupJob(job.id);
+      this.cleanupJob(activeJob);
     }
   }
   async completeJob(job, result) {
@@ -3534,7 +3621,7 @@ var SpooledWorker = class {
       await this.client.jobs.complete(job.id, {
         workerId: this.workerId,
         result,
-        ...job.leaseId !== void 0 && { leaseId: job.leaseId }
+        ...job.leaseId != null && { leaseId: job.leaseId }
       });
       this.emit("job:completed", {
         jobId: job.id,
@@ -3552,7 +3639,7 @@ var SpooledWorker = class {
       await this.client.jobs.fail(job.id, {
         workerId: this.workerId,
         error: errorMessage,
-        ...job.leaseId !== void 0 && { leaseId: job.leaseId }
+        ...job.leaseId != null && { leaseId: job.leaseId }
       });
       this.emit("job:failed", {
         jobId: job.id,
@@ -3564,24 +3651,26 @@ var SpooledWorker = class {
       this.debug(`Failed to fail job ${job.id}`, error);
     }
   }
-  cleanupJob(jobId) {
-    const activeJob = this.activeJobs.get(jobId);
-    if (activeJob?.heartbeatTimer) {
+  cleanupJob(activeJob) {
+    if (activeJob.heartbeatTimer) {
       clearInterval(activeJob.heartbeatTimer);
+      activeJob.heartbeatTimer = void 0;
+    }
+    if (this.activeJobs.get(activeJob.executionId) === activeJob) {
+      this.activeJobs.delete(activeJob.executionId);
     }
-    this.activeJobs.delete(jobId);
   }
-  async sendJobHeartbeat(jobId) {
+  async sendJobHeartbeat(activeJob) {
     if (!this.workerId) return;
-    const leaseId = this.activeJobs.get(jobId)?.job.leaseId;
+    const { job } = activeJob;
     try {
-      await this.client.jobs.heartbeat(jobId, {
+      await this.client.jobs.heartbeat(job.id, {
         workerId: this.workerId,
         leaseDurationSecs: this.options.leaseDuration,
-        ...leaseId !== void 0 && { leaseId }
+        ...job.leaseId != null && { leaseId: job.leaseId }
       });
     } catch (error) {
-      this.debug(`Job heartbeat failed for ${jobId}`, error);
+      this.debug(`Job heartbeat failed for ${job.id}`, error);
     }
   }
   async sendWorkerHeartbeat() {