@spooled/sdk 1.3.0 → 1.4.0

package/dist/index.cjs

@@ -48,10 +48,10 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.3.0",
+  userAgent: "@spooled/sdk-nodejs/1.4.0",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.3.0";
+var SDK_VERSION = "1.4.0";
 var API_VERSION = "v1";
 var API_BASE_PATH = `/api/${API_VERSION}`;
 function normalizeCredential(value) {
@@ -364,6 +364,10 @@ function parseRateLimitHeaders(headers) {
       info.reset = new Date(timestamp * 1e3);
     }
   }
+  const scope = headers.get("X-RateLimit-Scope");
+  if (scope) {
+    info.scope = scope.trim();
+  }
   return info;
 }
 var MAX_RAW_ERROR_BODY_CHARS = 500;
@@ -643,6 +647,8 @@ var HttpClient = class {
    * refresh and fail even though the token was about to be replaced.
    */
   refreshInFlight = null;
+  /** Rate-limit headers of the most recent response that carried them */
+  lastRateLimit;
   constructor(config, circuitBreaker) {
     this.config = config;
     this.circuitBreaker = circuitBreaker;
@@ -655,6 +661,14 @@ var HttpClient = class {
   setAuthToken(token) {
     this.authToken = token;
   }
+  /**
+   * The `X-RateLimit-*` (and `Retry-After`) values of the most recent
+   * response that carried them, successful or not. `undefined` until such a
+   * response arrives. With concurrent requests it is the last one to finish.
+   */
+  getLastRateLimitInfo() {
+    return this.lastRateLimit ? { ...this.lastRateLimit } : void 0;
+  }
   /**
    * Set the token refresh function.
    *
@@ -801,6 +815,7 @@ var HttpClient = class {
       );
     }
     this.debug?.(`Response: ${response.status}`, { url });
+    this.recordRateLimit(response.headers);
     if (!response.ok) {
       if (response.status === 401 && this.refreshTokenFn && !hasRefreshed && !options.skipAuthRefresh) {
         const alreadyRefreshed = this.authToken !== tokenUsed;
@@ -827,6 +842,13 @@ var HttpClient = class {
       data
     };
   }
+  /** Remember the rate-limit headers of a response that has them. */
+  recordRateLimit(headers) {
+    if (!headers || typeof headers.get !== "function" || headers.get("X-RateLimit-Limit") === null && headers.get("X-RateLimit-Remaining") === null) {
+      return;
+    }
+    this.lastRateLimit = parseRateLimitHeaders(headers);
+  }
   /**
    * Make an HTTP request with retry and circuit breaker
    */
@@ -954,6 +976,12 @@ var CircuitState = /* @__PURE__ */ ((CircuitState2) => {
   CircuitState2["HALF_OPEN"] = "HALF_OPEN";
   return CircuitState2;
 })(CircuitState || {});
+function isCircuitBreakerFailure(error) {
+  if (error instanceof RateLimitError) {
+    return false;
+  }
+  return isRetryableError(error);
+}
 var CircuitBreaker = class {
   state = "CLOSED" /* CLOSED */;
   failureCount = 0;
@@ -1014,7 +1042,7 @@ var CircuitBreaker = class {
     if (!this.config.enabled) {
       return;
     }
-    const shouldCount = this.config.isFailure ? this.config.isFailure(error) : isRetryableError(error);
+    const shouldCount = this.config.isFailure ? this.config.isFailure(error) : isCircuitBreakerFailure(error);
     if (!shouldCount) {
       return;
     }
@@ -1212,12 +1240,31 @@ function coerceFailureMessage(message) {
   return codePoints.length <= MAX_FAILURE_MESSAGE_CHARS ? text : codePoints.slice(0, MAX_FAILURE_MESSAGE_CHARS).join("");
 }
 
+// src/utils/paging.ts
+var HAS_MORE_HEADER = "X-Has-More";
+function hasMoreFromHeaders(headers, count, limit, defaultLimit, maxLimit) {
+  const header = headers.get(HAS_MORE_HEADER);
+  if (header !== null) {
+    return header.trim().toLowerCase() === "true";
+  }
+  const applied = Math.min(Math.max(limit ?? defaultLimit, 1), maxLimit);
+  return count >= applied;
+}
+function toQueryTimestamp(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
+
 // src/resources/jobs.ts
+var JOB_LIST_DEFAULT_LIMIT = 50;
+var JOB_LIST_MAX_LIMIT = 100;
+var JOB_HISTORY_DEFAULT_LIMIT = 100;
+var JOB_HISTORY_MAX_LIMIT = 500;
 var JobsResource = class {
   constructor(http) {
     this.http = http;
     this.dlq = {
       list: this.listDlq.bind(this),
+      listPage: this.listDlqPage.bind(this),
       retry: this.retryDlq.bind(this),
       purge: this.purgeDlq.bind(this)
     };
@@ -1241,15 +1288,36 @@ var JobsResource = class {
   }
   /**
    * List jobs with optional filtering
+   *
+   * `status` takes one status or several, and `q`, `jobType`, `createdAfter`
+   * and `createdBefore` filter on the server (API 0.1.122+). Use
+   * {@link JobsResource.listPage} to also learn whether another page follows.
    */
   async list(params) {
-    const rows = await this.http.get("/jobs", {
-      params
-    });
-    return rows.map((row) => ({
-      ...row,
-      jobType: row.jobType ?? jobTypeFromPayload(row)
-    }));
+    return (await this.listPage(params)).data;
+  }
+  /**
+   * List one page of jobs with `hasMore` from the `X-Has-More` header
+   * (API 0.1.122+). Takes the same filters as {@link JobsResource.list}.
+   *
+   * @example
+   * ```typescript
+   * let offset = 0;
+   * for (;;) {
+   *   const page = await client.jobs.listPage({
+   *     status: ["failed", "deadletter"],
+   *     createdAfter: new Date(Date.now() - 86_400_000),
+   *     limit: 100,
+   *     offset,
+   *   });
+   *   handle(page.data);
+   *   if (!page.hasMore) break;
+   *   offset += page.data.length;
+   * }
+   * ```
+   */
+  async listPage(params) {
+    return this.listSummaries("/jobs", params);
   }
   /**
    * Get a job by ID
@@ -1279,6 +1347,46 @@ var JobsResource = class {
       priority
     });
   }
+  /**
+   * Get the recorded lifecycle events of a job (`GET /jobs/{id}/history`,
+   * API 0.1.122+), oldest first unless `order: "desc"`.
+   *
+   * The history is sparse: the server records REST claims (`processing`),
+   * completions (`completed`) and failures (`retry_scheduled`,
+   * `deadlettered`) and the scheduler's dead-letter sweeps, so a job settled
+   * over gRPC may have few or no events. An unknown job is a `NotFoundError`.
+   */
+  async history(id, params) {
+    return (await this.historyPage(id, params)).data;
+  }
+  /**
+   * One page of {@link JobsResource.history} with `hasMore` from the
+   * `X-Has-More` header. `limit` defaults to 100 (at most 500).
+   */
+  async historyPage(id, params) {
+    const response = await this.http.request(
+      `/jobs/${id}/history`,
+      {
+        method: "GET",
+        params: {
+          order: params?.order,
+          limit: params?.limit,
+          offset: params?.offset
+        }
+      }
+    );
+    const data = response.data ?? [];
+    return {
+      data,
+      hasMore: hasMoreFromHeaders(
+        response.headers,
+        data.length,
+        params?.limit,
+        JOB_HISTORY_DEFAULT_LIMIT,
+        JOB_HISTORY_MAX_LIMIT
+      )
+    };
+  }
   /**
    * Get job statistics
    */
@@ -1355,13 +1463,30 @@ var JobsResource = class {
   }
   // DLQ operations (private implementations)
   async listDlq(params) {
-    const rows = await this.http.get("/jobs/dlq", {
-      params
+    return (await this.listDlqPage(params)).data;
+  }
+  async listDlqPage(params) {
+    return this.listSummaries("/jobs/dlq", params);
+  }
+  async listSummaries(path, params) {
+    const response = await this.http.request(path, {
+      method: "GET",
+      params: jobListQuery(params)
     });
-    return rows.map((row) => ({
-      ...row,
-      jobType: row.jobType ?? jobTypeFromPayload(row)
-    }));
+    const rows = response.data ?? [];
+    return {
+      data: rows.map((row) => ({
+        ...row,
+        jobType: row.jobType ?? jobTypeFromPayload(row)
+      })),
+      hasMore: hasMoreFromHeaders(
+        response.headers,
+        rows.length,
+        params?.limit,
+        JOB_LIST_DEFAULT_LIMIT,
+        JOB_LIST_MAX_LIMIT
+      )
+    };
   }
   async retryDlq(params) {
     return this.http.post("/jobs/dlq/retry", params);
@@ -1370,6 +1495,24 @@ var JobsResource = class {
     return this.http.post("/jobs/dlq/purge", params);
   }
 };
+function jobListQuery(params) {
+  if (!params) {
+    return void 0;
+  }
+  const { status: status2, createdAfter, createdBefore, ...rest } = params;
+  let statusParam;
+  if (typeof status2 === "string") {
+    statusParam = status2;
+  } else if (status2 && status2.length > 0) {
+    statusParam = status2.join(",");
+  }
+  return {
+    ...rest,
+    status: statusParam,
+    createdAfter: toQueryTimestamp(createdAfter),
+    createdBefore: toQueryTimestamp(createdBefore)
+  };
+}
 function withJobType(job) {
   return {
     ...job,
@@ -2193,6 +2336,31 @@ var WebhookIngestionResource = class {
       status: raw.status
     };
   }
+  /**
+   * The inbound webhook log: accepted requests to
+   * `POST /webhooks/{org_id}/custom`, newest first
+   * (`GET /webhooks/deliveries`, API 0.1.122+).
+   *
+   * Needs an API key without a queue restriction (a queue-scoped key gets a
+   * 403 `AuthorizationError`). Entries carry no payload and no signature;
+   * requests that were rejected are not logged. `limit` defaults to 50 (at
+   * most 100); an invalid filter is a 400 `ValidationError`.
+   */
+  async listDeliveries(params) {
+    const rows = await this.http.get(
+      "/webhooks/deliveries",
+      {
+        params: {
+          status: params?.status,
+          since: toQueryTimestamp(params?.since),
+          queueName: params?.queueName,
+          limit: params?.limit,
+          offset: params?.offset
+        }
+      }
+    );
+    return rows ?? [];
+  }
 };
 
 // src/realtime/event-map.ts
@@ -3030,6 +3198,120 @@ function clearProtoCache() {
 function encodeFailRequest(params) {
   return { ...params, retry: params.retry ?? true };
 }
+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) {
+  const encoded = {
+    queueName: params.queueName,
+    payload: encodeStruct(params.payload)
+  };
+  if (params.priority !== void 0) {
+    encoded.priority = params.priority;
+  }
+  if (params.maxRetries !== void 0) {
+    encoded.maxRetries = params.maxRetries;
+  }
+  if (params.timeoutSeconds !== void 0) {
+    encoded.timeoutSeconds = params.timeoutSeconds;
+  }
+  if (params.idempotencyKey !== void 0 && params.idempotencyKey !== "") {
+    encoded.idempotencyKey = params.idempotencyKey;
+  }
+  if (params.scheduledAt !== void 0) {
+    encoded.scheduledAt = params.scheduledAt;
+  }
+  if (params.tags !== void 0) {
+    encoded.tags = params.tags;
+  }
+  return encoded;
+}
+function encodeCompleteRequest(params) {
+  return {
+    ...params,
+    result: encodeStruct(params.result)
+  };
+}
+function decodeJob(job) {
+  return {
+    ...job,
+    // proto-loader keeps an enum number it does not know (a status added to
+    // the server's proto after this SDK) as a number; keep it a string so
+    // `status` always matches its type.
+    status: typeof job.status === "number" ? String(job.status) : job.status,
+    payload: decodeStruct(job.payload),
+    result: decodeStruct(job.result)
+  };
+}
+function encodeProcessRequest(request) {
+  if (request.fail) {
+    return { ...request, fail: encodeFailRequest(request.fail) };
+  }
+  if (request.complete) {
+    return { ...request, complete: encodeCompleteRequest(request.complete) };
+  }
+  return request;
+}
+function decodeProcessResponse(response) {
+  return response.job ? { ...response, job: decodeJob(response.job) } : response;
+}
 
 // src/grpc/streaming.ts
 async function* asyncIterableFromStream(stream, options) {
@@ -3048,21 +3330,39 @@ async function* asyncIterableFromStream(stream, options) {
 var AsyncIterableStream = class {
   stream;
   options;
-  constructor(stream, options = {}) {
+  decode;
+  constructor(stream, options = {}, decode = (item) => item) {
     this.stream = stream;
     this.options = options;
+    this.decode = decode;
   }
   async *[Symbol.asyncIterator]() {
     const { onConnected, onError, onEnd } = this.options;
     const queue = [];
     let error = null;
     let ended = false;
+    let decodeFailed = false;
     let resolve = null;
     this.stream.on("data", (data) => {
-      queue.push(data);
+      if (decodeFailed) {
+        return;
+      }
+      try {
+        queue.push(this.decode(data));
+      } catch (decodeError) {
+        decodeFailed = true;
+        error = decodeError instanceof Error ? decodeError : new Error(String(decodeError));
+        try {
+          this.stream.cancel?.();
+        } catch {
+        }
+      }
       resolve?.();
     });
     this.stream.on("error", (err) => {
+      if (decodeFailed) {
+        return;
+      }
       error = err;
       onError?.(err);
       resolve?.();
@@ -3103,12 +3403,14 @@ function createProcessJobsStream(call, options) {
   }
   return {
     send(request) {
-      call.write(
-        request.fail ? { ...request, fail: encodeFailRequest(request.fail) } : request
-      );
+      call.write(encodeProcessRequest(request));
     },
     receive() {
-      return new AsyncIterableStream(call, { onError, onEnd });
+      return new AsyncIterableStream(
+        call,
+        { onError, onEnd },
+        decodeProcessResponse
+      );
     },
     end() {
       call.end();
@@ -3125,11 +3427,11 @@ function createJobStream(call, options) {
       call.cancel();
     });
   }
-  const iterable = new AsyncIterableStream(call, {
-    onConnected,
-    onError,
-    onEnd
-  });
+  const iterable = new AsyncIterableStream(
+    call,
+    { onConnected, onError, onEnd },
+    decodeJob
+  );
   return {
     [Symbol.asyncIterator]() {
       return iterable[Symbol.asyncIterator]();
@@ -3141,104 +3443,6 @@ 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) {
-  const encoded = {
-    queueName: params.queueName,
-    payload: encodeStruct(params.payload)
-  };
-  if (params.priority !== void 0) {
-    encoded.priority = params.priority;
-  }
-  if (params.maxRetries !== void 0) {
-    encoded.maxRetries = params.maxRetries;
-  }
-  if (params.timeoutSeconds !== void 0) {
-    encoded.timeoutSeconds = params.timeoutSeconds;
-  }
-  if (params.idempotencyKey !== void 0 && params.idempotencyKey !== "") {
-    encoded.idempotencyKey = params.idempotencyKey;
-  }
-  if (params.scheduledAt !== void 0) {
-    encoded.scheduledAt = params.scheduledAt;
-  }
-  if (params.tags !== void 0) {
-    encoded.tags = params.tags;
-  }
-  return encoded;
-}
-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, timeoutMs) {
   return new Promise((resolve, reject) => {
     const callback = (error, response) => {
@@ -3818,6 +4022,17 @@ var SpooledClient = class _SpooledClient {
   getConfig() {
     return this.config;
   }
+  /**
+   * Rate-limit state from the most recent response that carried
+   * `X-RateLimit-*` headers (API 0.1.122+): `limit`, `remaining`, `reset`
+   * (from the Unix-seconds header), `scope` and, after a 429, `retryAfter`.
+   * `undefined` until such a response arrives, and for servers or routes that
+   * do not send the headers. A 429 also carries the same values on
+   * `RateLimitError.rateLimitInfo`.
+   */
+  getRateLimitInfo() {
+    return this.http.getLastRateLimitInfo();
+  }
   /**
    * Get circuit breaker statistics
    */
@@ -4478,6 +4693,7 @@ exports.createProcessJobsStream = createProcessJobsStream;
 exports.createRetryWrapper = createRetryWrapper;
 exports.dateToTimestamp = dateToTimestamp;
 exports.getProtoPath = getProtoPath;
+exports.isCircuitBreakerFailure = isCircuitBreakerFailure;
 exports.isRetryableError = isRetryableError;
 exports.isSpooledError = isSpooledError;
 exports.loadProtoDefinition = loadProtoDefinition;