@spooled/sdk 1.0.35 → 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-B96n0WUe.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.35";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.36";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.35";
+declare const SDK_VERSION = "1.0.36";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**

package/dist/{index-B96n0WUe.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.35";
+    readonly userAgent: "@spooled/sdk-nodejs/1.0.36";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.35";
+declare const SDK_VERSION = "1.0.36";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**

package/dist/index.cjs

@@ -49,10 +49,10 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.0.35",
+  userAgent: "@spooled/sdk-nodejs/1.0.36",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.0.35";
+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