@spooled/sdk 1.4.0 → 1.5.0

package/README.md

@@ -590,12 +590,13 @@ import type {
 
 ## Development and releases
 
-Before opening a pull request or tagging a release, run the same checks used by the package and publish workflow:
+CI (`.github/workflows/ci.yml`) runs these checks on Node 22 and 24 for every push to `main` and every pull request; the publish workflow runs them again on Node 22 before publishing. Run them locally before opening a pull request or tagging a release:
 
 ```bash
 npm ci
 npm run lint
 npm run typecheck
+npm run typecheck:examples
 npm run build
 npm test
 ```

package/dist/{index-DzTC8ld3.d.cts → index-CSWlguB8.d.cts}

@@ -224,11 +224,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.4.0";
+    readonly userAgent: "@spooled/sdk-nodejs/1.5.0";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.4.0";
+declare const SDK_VERSION = "1.5.0";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -750,7 +750,17 @@ declare class AuthResource {
  */
 /** JSON primitive types */
 type JsonPrimitive = string | number | boolean | null;
-/** JSON value type */
+/**
+ * JSON value type.
+ *
+ * Inside user-owned JSON (`payload`, `result`, `tags`, and the other
+ * free-form fields) an integer whose magnitude is greater than 2^53 is
+ * returned as a decimal string, so the digits survive decoding. A float64
+ * cannot hold those integers, and a string is already a `JsonValue`. Every
+ * smaller number, and every number outside those fields, stays a `number`.
+ * gRPC payloads cannot do this: `google.protobuf.Struct` has already stored
+ * the value as a float64.
+ */
 type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 /** JSON object type */
 interface JsonObject {
@@ -3224,9 +3234,18 @@ interface GrpcJob {
     organizationId: string;
     queueName: string;
     status: GrpcJobStatus | string;
-    /** Payload as google.protobuf.Struct (object) */
+    /**
+     * Payload as google.protobuf.Struct (object).
+     *
+     * Struct stores every number as a float64, so an integer above 2^53 is
+     * already rounded before this SDK sees it. REST keeps those integers as
+     * decimal strings; send them as strings on this path.
+     */
     payload?: Record<string, unknown> | null;
-    /** Result as google.protobuf.Struct (object) */
+    /**
+     * Result as google.protobuf.Struct (object). Same float64 limit as
+     * `payload`: an integer above 2^53 cannot round-trip.
+     */
     result?: Record<string, unknown> | null;
     retryCount: number;
     maxRetries: number;
@@ -4004,10 +4023,13 @@ interface JobContext {
     /** Maximum retries */
     maxRetries: number;
     /**
-     * Abort signal. Aborted when the job exceeds its `timeoutSeconds` or when a
-     * stop outlives `shutdownTimeout`; NOT aborted merely because a stop was
-     * requested (the handler gets the grace period to finish and be acked).
-     * `signal.reason` carries the cause.
+     * Abort signal. Aborted when the job exceeds its `timeoutSeconds`, when a
+     * stop outlives `shutdownTimeout`, or when this worker loses the lease
+     * (a heartbeat of 409 `LEASE_EXPIRED`, which is also how a lease mismatch
+     * is reported). NOT aborted merely because a stop was requested (the
+     * handler gets the grace period to finish and be acked). `signal.reason`
+     * carries the cause. A lost lease is not acked: the handler's later result
+     * is discarded, because the scheduler has already given the job away.
      */
     signal: AbortSignal;
     /** Log local job progress (0-100); backend progress persistence is not yet available. */
@@ -4076,6 +4098,12 @@ interface ActiveJob {
      * else may ack it. Set when the handler settles or the shutdown fails it.
      */
     settled?: boolean;
+    /**
+     * Heartbeat returned 409 `LEASE_EXPIRED` (the lease timed out or the
+     * `lease_id` no longer matches). The scheduler has reclaimed the job, so
+     * this execution must not complete or fail it.
+     */
+    leaseLost?: boolean;
     /** The complete/fail request for this execution, once started. */
     ack?: Promise<void>;
 }
@@ -4190,6 +4218,11 @@ declare class SpooledWorker {
     private clearTimeoutTimer;
     private cleanupJob;
     private sendJobHeartbeat;
+    /**
+     * The lease is gone. Abort the handler if it listens, stop renewing, and
+     * refuse a later complete/fail with the stale lease.
+     */
+    private noteLeaseLost;
     private sendWorkerHeartbeat;
     /**
      * Resolve once no job is active, or after `timeoutMs`. The timer is always

package/dist/{index-DzTC8ld3.d.ts → index-CSWlguB8.d.ts}

@@ -224,11 +224,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.4.0";
+    readonly userAgent: "@spooled/sdk-nodejs/1.5.0";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.4.0";
+declare const SDK_VERSION = "1.5.0";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -750,7 +750,17 @@ declare class AuthResource {
  */
 /** JSON primitive types */
 type JsonPrimitive = string | number | boolean | null;
-/** JSON value type */
+/**
+ * JSON value type.
+ *
+ * Inside user-owned JSON (`payload`, `result`, `tags`, and the other
+ * free-form fields) an integer whose magnitude is greater than 2^53 is
+ * returned as a decimal string, so the digits survive decoding. A float64
+ * cannot hold those integers, and a string is already a `JsonValue`. Every
+ * smaller number, and every number outside those fields, stays a `number`.
+ * gRPC payloads cannot do this: `google.protobuf.Struct` has already stored
+ * the value as a float64.
+ */
 type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 /** JSON object type */
 interface JsonObject {
@@ -3224,9 +3234,18 @@ interface GrpcJob {
     organizationId: string;
     queueName: string;
     status: GrpcJobStatus | string;
-    /** Payload as google.protobuf.Struct (object) */
+    /**
+     * Payload as google.protobuf.Struct (object).
+     *
+     * Struct stores every number as a float64, so an integer above 2^53 is
+     * already rounded before this SDK sees it. REST keeps those integers as
+     * decimal strings; send them as strings on this path.
+     */
     payload?: Record<string, unknown> | null;
-    /** Result as google.protobuf.Struct (object) */
+    /**
+     * Result as google.protobuf.Struct (object). Same float64 limit as
+     * `payload`: an integer above 2^53 cannot round-trip.
+     */
     result?: Record<string, unknown> | null;
     retryCount: number;
     maxRetries: number;
@@ -4004,10 +4023,13 @@ interface JobContext {
     /** Maximum retries */
     maxRetries: number;
     /**
-     * Abort signal. Aborted when the job exceeds its `timeoutSeconds` or when a
-     * stop outlives `shutdownTimeout`; NOT aborted merely because a stop was
-     * requested (the handler gets the grace period to finish and be acked).
-     * `signal.reason` carries the cause.
+     * Abort signal. Aborted when the job exceeds its `timeoutSeconds`, when a
+     * stop outlives `shutdownTimeout`, or when this worker loses the lease
+     * (a heartbeat of 409 `LEASE_EXPIRED`, which is also how a lease mismatch
+     * is reported). NOT aborted merely because a stop was requested (the
+     * handler gets the grace period to finish and be acked). `signal.reason`
+     * carries the cause. A lost lease is not acked: the handler's later result
+     * is discarded, because the scheduler has already given the job away.
      */
     signal: AbortSignal;
     /** Log local job progress (0-100); backend progress persistence is not yet available. */
@@ -4076,6 +4098,12 @@ interface ActiveJob {
      * else may ack it. Set when the handler settles or the shutdown fails it.
      */
     settled?: boolean;
+    /**
+     * Heartbeat returned 409 `LEASE_EXPIRED` (the lease timed out or the
+     * `lease_id` no longer matches). The scheduler has reclaimed the job, so
+     * this execution must not complete or fail it.
+     */
+    leaseLost?: boolean;
     /** The complete/fail request for this execution, once started. */
     ack?: Promise<void>;
 }
@@ -4190,6 +4218,11 @@ declare class SpooledWorker {
     private clearTimeoutTimer;
     private cleanupJob;
     private sendJobHeartbeat;
+    /**
+     * The lease is gone. Abort the handler if it listens, stop renewing, and
+     * refuse a later complete/fail with the stale lease.
+     */
+    private noteLeaseLost;
     private sendWorkerHeartbeat;
     /**
      * Resolve once no job is active, or after `timeoutMs`. The timer is always

package/dist/index.cjs

@@ -48,10 +48,10 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.4.0",
+  userAgent: "@spooled/sdk-nodejs/1.5.0",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.4.0";
+var SDK_VERSION = "1.5.0";
 var API_VERSION = "v1";
 var API_BASE_PATH = `/api/${API_VERSION}`;
 function normalizeCredential(value) {
@@ -631,6 +631,175 @@ function createRetryWrapper(config) {
   };
 }
 
+// src/utils/json.ts
+var TWO_POW_53 = "9007199254740992";
+function parseApiJson(text) {
+  return JSON.parse(preserveExactIntegers(text));
+}
+function magnitudeExceedsTwoPow53(digits) {
+  let start = 0;
+  while (start < digits.length - 1 && digits.charCodeAt(start) === 48) {
+    start++;
+  }
+  const len = digits.length - start;
+  if (len !== TWO_POW_53.length) {
+    return len > TWO_POW_53.length;
+  }
+  for (let i = 0; i < len; i++) {
+    const digit = digits.charCodeAt(start + i);
+    const limit = TWO_POW_53.charCodeAt(i);
+    if (digit !== limit) {
+      return digit > limit;
+    }
+  }
+  return false;
+}
+function inExactValue(frames) {
+  const top = frames[frames.length - 1];
+  if (!top || top.expect !== "value") {
+    return false;
+  }
+  return top.exact || top.keyIsExact;
+}
+function preserveExactIntegers(text) {
+  const out = [];
+  const frames = [];
+  const n = text.length;
+  let i = 0;
+  const valueEnded = () => {
+    const top = frames[frames.length - 1];
+    if (top) {
+      top.expect = "after";
+    }
+  };
+  while (i < n) {
+    const c = text[i];
+    if (c === " " || c === "\n" || c === "\r" || c === "	") {
+      out.push(c);
+      i++;
+      continue;
+    }
+    if (c === "{") {
+      frames.push({
+        kind: "object",
+        exact: inExactValue(frames),
+        expect: "key",
+        keyIsExact: false
+      });
+      out.push(c);
+      i++;
+      continue;
+    }
+    if (c === "[") {
+      frames.push({
+        kind: "array",
+        exact: inExactValue(frames),
+        expect: "value",
+        keyIsExact: false
+      });
+      out.push(c);
+      i++;
+      continue;
+    }
+    if (c === "}" || c === "]") {
+      frames.pop();
+      out.push(c);
+      i++;
+      valueEnded();
+      continue;
+    }
+    if (c === ":") {
+      const top = frames[frames.length - 1];
+      if (top && top.kind === "object") {
+        top.expect = "value";
+      }
+      out.push(c);
+      i++;
+      continue;
+    }
+    if (c === ",") {
+      const top = frames[frames.length - 1];
+      if (top) {
+        top.expect = top.kind === "object" ? "key" : "value";
+        top.keyIsExact = false;
+      }
+      out.push(c);
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      const start = i;
+      i++;
+      while (i < n) {
+        if (text[i] === "\\") {
+          i++;
+          if (i < n) i++;
+          continue;
+        }
+        if (text[i] === '"') {
+          i++;
+          break;
+        }
+        i++;
+      }
+      const raw = text.slice(start, i);
+      const top = frames[frames.length - 1];
+      if (top && top.kind === "object" && top.expect === "key") {
+        let key = "";
+        try {
+          key = JSON.parse(raw);
+        } catch {
+          key = "";
+        }
+        top.keyIsExact = typeof key === "string" && SKIP_CONVERSION_KEYS.has(key);
+        top.expect = "colon";
+      } else {
+        valueEnded();
+      }
+      out.push(raw);
+      continue;
+    }
+    if (c === "-" || c >= "0" && c <= "9") {
+      const start = i;
+      if (text[i] === "-") i++;
+      const digitsAt = i;
+      while (i < n && text[i] >= "0" && text[i] <= "9") i++;
+      const digitsEnd = i;
+      let isInteger = true;
+      if (i < n && text[i] === ".") {
+        isInteger = false;
+        i++;
+        while (i < n && text[i] >= "0" && text[i] <= "9") i++;
+      }
+      if (i < n && (text[i] === "e" || text[i] === "E")) {
+        isInteger = false;
+        i++;
+        if (i < n && (text[i] === "+" || text[i] === "-")) i++;
+        while (i < n && text[i] >= "0" && text[i] <= "9") i++;
+      }
+      const raw = text.slice(start, i);
+      const digits = text.slice(digitsAt, digitsEnd);
+      if (isInteger && digits.length > 0 && inExactValue(frames) && magnitudeExceedsTwoPow53(digits)) {
+        out.push(`"${raw}"`);
+      } else {
+        out.push(raw);
+      }
+      valueEnded();
+      continue;
+    }
+    if (c >= "a" && c <= "z") {
+      const start = i;
+      while (i < n && text[i] >= "a" && text[i] <= "z") i++;
+      out.push(text.slice(start, i));
+      valueEnded();
+      continue;
+    }
+    out.push(c);
+    i++;
+  }
+  return out.join("");
+}
+
 // src/utils/http.ts
 var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
 var HttpClient = class {
@@ -831,7 +1000,7 @@ var HttpClient = class {
     if (response.status === 204) {
       data = void 0;
     } else if (contentType.includes("application/json")) {
-      const rawData = await response.json();
+      const rawData = parseApiJson(await response.text());
       data = options.skipResponseConversion ? rawData : convertResponse(rawData);
     } else {
       data = await response.text();
@@ -2589,7 +2758,7 @@ var WebSocketRealtimeClient = class {
   }
   handleMessage(data) {
     try {
-      const message = convertResponse(JSON.parse(data));
+      const message = convertResponse(parseApiJson(data));
       const eventType = mapEventType(String(message.type));
       message.type = eventType;
       const event = message;
@@ -2774,8 +2943,9 @@ var SseRealtimeClient = class {
     this.setState("connecting");
     const sseUrl = this.buildSseUrl(filter);
     this.options.debug(`Connecting to SSE: ${sseUrl}`);
+    const usingPlatformEventSource = typeof EventSource !== "undefined";
     let EventSourceImpl;
-    if (typeof EventSource !== "undefined") {
+    if (usingPlatformEventSource) {
       EventSourceImpl = EventSource;
     } else {
       try {
@@ -2799,16 +2969,20 @@ var SseRealtimeClient = class {
     }
     return new Promise((resolve, reject) => {
       try {
-        this.eventSource = new EventSourceImpl(sseUrl, {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          fetch: (input, init) => fetch(input, {
-            ...init,
-            headers: {
-              ...init?.headers,
-              Authorization: `Bearer ${token}`
-            }
-          })
-        });
+        const connectUrl = usingPlatformEventSource ? appendSseToken(sseUrl, token) : sseUrl;
+        this.eventSource = new EventSourceImpl(
+          connectUrl,
+          usingPlatformEventSource ? void 0 : {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            fetch: (input, init) => fetch(input, {
+              ...init,
+              headers: {
+                ...init?.headers,
+                Authorization: `Bearer ${token}`
+              }
+            })
+          }
+        );
         this.eventSource.onopen = () => {
           this.options.debug("SSE connected");
           this.setState("connected");
@@ -2920,7 +3094,7 @@ var SseRealtimeClient = class {
   }
   handleMessage(data) {
     try {
-      const parsed = convertResponse(JSON.parse(data));
+      const parsed = convertResponse(parseApiJson(data));
       const eventType = mapEventType(String(parsed.type));
       parsed.type = eventType;
       const event = parsed;
@@ -2995,6 +3169,10 @@ var SseRealtimeClient = class {
     }, delay);
   }
 };
+function appendSseToken(url, token) {
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}token=${encodeURIComponent(token)}`;
+}
 function isStreamEndingEvent(eventType, data) {
   if (eventType === "error" || eventType === "job.completed") {
     return true;
@@ -4460,6 +4638,10 @@ var SpooledWorker = class {
     };
     try {
       const outcome = await this.runHandler(activeJob, context);
+      if (activeJob.leaseLost) {
+        this.debug(`Job ${job.id} lost its lease; dropping late result`);
+        return;
+      }
       if (activeJob.settled) {
         this.debug(`Job ${job.id} was already settled; dropping late result`);
         return;
@@ -4467,11 +4649,14 @@ var SpooledWorker = class {
       activeJob.settled = true;
       switch (outcome.kind) {
         case "returned":
-          activeJob.ack = this.completeJob(job, outcome.value ?? void 0);
+          activeJob.ack = this.completeJob(
+            activeJob,
+            outcome.value ?? void 0
+          );
           break;
         case "threw":
           activeJob.ack = this.failJob(
-            job,
+            activeJob,
             outcome.error instanceof Error ? outcome.error.message : String(outcome.error)
           );
           break;
@@ -4481,7 +4666,7 @@ var SpooledWorker = class {
             jobId: job.id,
             queueName: job.queueName
           });
-          activeJob.ack = this.failJob(job, JOB_TIMEOUT_MESSAGE);
+          activeJob.ack = this.failJob(activeJob, JOB_TIMEOUT_MESSAGE);
           break;
       }
       await activeJob.ack;
@@ -4521,12 +4706,13 @@ var SpooledWorker = class {
     this.debug(`Force-failing job ${activeJob.job.id} due to shutdown timeout`);
     activeJob.settled = true;
     activeJob.abortController.abort(new Error(SHUTDOWN_TIMEOUT_MESSAGE));
-    activeJob.ack = this.failJob(activeJob.job, SHUTDOWN_TIMEOUT_MESSAGE);
+    activeJob.ack = this.failJob(activeJob, SHUTDOWN_TIMEOUT_MESSAGE);
     await activeJob.ack;
     this.cleanupJob(activeJob);
   }
-  async completeJob(job, result) {
-    if (!this.workerId) return;
+  async completeJob(activeJob, result) {
+    if (!this.workerId || activeJob.leaseLost) return;
+    const { job } = activeJob;
     try {
       await this.client.jobs.complete(job.id, {
         workerId: this.workerId,
@@ -4539,12 +4725,17 @@ var SpooledWorker = class {
         result
       });
     } catch (error) {
+      if (isLeaseExpired(error)) {
+        this.noteLeaseLost(activeJob, error);
+        return;
+      }
       this.debug(`Failed to complete job ${job.id}`, error);
       this.emit("error", { error });
     }
   }
-  async failJob(job, errorMessage) {
-    if (!this.workerId) return;
+  async failJob(activeJob, errorMessage) {
+    if (!this.workerId || activeJob.leaseLost) return;
+    const { job } = activeJob;
     const willRetry = job.retryCount < job.maxRetries;
     const message = coerceFailureMessage(errorMessage);
     try {
@@ -4560,6 +4751,10 @@ var SpooledWorker = class {
         willRetry
       });
     } catch (error) {
+      if (isLeaseExpired(error)) {
+        this.noteLeaseLost(activeJob, error);
+        return;
+      }
       this.debug(`Failed to fail job ${job.id}`, error);
       this.emit("error", { error });
     }
@@ -4584,7 +4779,7 @@ var SpooledWorker = class {
     }
   }
   async sendJobHeartbeat(activeJob) {
-    if (!this.workerId) return;
+    if (!this.workerId || activeJob.leaseLost) return;
     const { job } = activeJob;
     try {
       await this.client.jobs.heartbeat(job.id, {
@@ -4593,9 +4788,34 @@ var SpooledWorker = class {
         ...job.leaseId != null && { leaseId: job.leaseId }
       });
     } catch (error) {
+      if (isLeaseExpired(error)) {
+        this.noteLeaseLost(activeJob, error);
+        return;
+      }
       this.debug(`Job heartbeat failed for ${job.id}`, error);
     }
   }
+  /**
+   * The lease is gone. Abort the handler if it listens, stop renewing, and
+   * refuse a later complete/fail with the stale lease.
+   */
+  noteLeaseLost(activeJob, error) {
+    if (activeJob.leaseLost) return;
+    activeJob.leaseLost = true;
+    if (activeJob.heartbeatTimer) {
+      clearInterval(activeJob.heartbeatTimer);
+      activeJob.heartbeatTimer = void 0;
+    }
+    this.clearTimeoutTimer(activeJob);
+    const reason = error instanceof Error ? error : new Error("Job lease expired");
+    activeJob.abortController.abort(reason);
+    this.debug(
+      `Job lease lost for ${activeJob.job.id}; stopping handler`,
+      error
+    );
+    activeJob.settled = true;
+    this.cleanupJob(activeJob);
+  }
   async sendWorkerHeartbeat() {
     if (!this.workerId || this.state !== "running" && this.state !== "stopping") {
       return;
@@ -4630,6 +4850,9 @@ var SpooledWorker = class {
     });
   }
 };
+function isLeaseExpired(error) {
+  return error instanceof SpooledError && error.statusCode === 409 && error.code.toUpperCase() === "LEASE_EXPIRED";
+}
 
 exports.API_VERSION = API_VERSION;
 exports.AdminResource = AdminResource;