@spooled/sdk 1.0.40 → 1.1.0

package/README.md

@@ -120,6 +120,7 @@ const client = new SpooledClient({ apiKey: "sp_live_..." });
 
 const worker = new SpooledWorker(client, {
   queueName: "my-queue",
+  workerId: "my-queue-worker-01", // stable id — see below
   concurrency: 10,
 });
 
@@ -135,6 +136,11 @@ await worker.start();
 process.on("SIGTERM", () => worker.stop());
 ```
 
+Give any worker that restarts a stable `workerId` (1-128 chars, `[A-Za-z0-9._-]`). Registration then
+upserts a single row instead of minting a new UUID each start, which otherwise leaves the previous
+registration counting against your plan's worker limit until the stale-worker reaper clears it
+(~2 minutes).
+
 ### Workflows (DAGs)
 
 Orchestrate multiple jobs with dependencies:
@@ -215,19 +221,32 @@ Configure outgoing webhooks for job events:
 ```typescript
 // Create webhook
 const webhook = await client.webhooks.create({
+  name: "App notifications",
   url: "https://your-app.com/webhooks/spooled",
   events: ["job.completed", "job.failed"],
-  queueName: "my-queue",
   secret: "webhook_secret_key",
 });
 
 // Retry a failed delivery
 await client.webhooks.retryDelivery(webhookId, deliveryId);
 
-// Get delivery history
+// Get delivery history (retention-bounded: free 1 day, starter 7, pro 30,
+// enterprise 90 — and only the newest 100 deliveries per webhook)
 const deliveries = await client.webhooks.getDeliveries(webhookId);
 ```
 
+After 20 consecutive failed deliveries a webhook is disabled automatically (`enabled: false`,
+`lastStatus: "auto_disabled"`) and stops receiving events until you turn it back on:
+
+```typescript
+await client.webhooks.update(webhookId, { enabled: true });
+```
+
+Updating changes only the fields you send. `secret` is three-state — omit it to keep the current
+secret, pass a string to replace it, or pass `null` to clear it. Clearing is destructive: deliveries
+then go out unsigned, with no `X-Spooled-Signature` header. Do not serialise unchanged fields as
+`null`.
+
 ### Dead Letter Queue (DLQ)
 
 Manage jobs that have exhausted all retries:
@@ -329,9 +348,9 @@ All operations automatically enforce tier-based limits:
 - ✅ Workflow creation (counts all jobs in workflow)
 - ✅ Schedule triggers
 - ✅ DLQ retry operations
-- ✅ Worker registration
+- ✅ Worker registration (re-registering your own stable `workerId` is not charged again)
 - ✅ Queue creation
-- ✅ Webhook creation
+- ✅ Webhook creation, and re-enabling a disabled webhook
 
 When a plan quota or limit is exceeded, you'll receive an `HTTP 429` response with
 `code: "QUOTA_EXCEEDED"`. The SDK reliably preserves the HTTP status, error code, message,

package/dist/{index-DA_znF4h.d.cts → index-D_MpLQYY.d.cts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.40";
+    readonly userAgent: "@spooled/sdk-nodejs/1.1.0";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.40";
+declare const SDK_VERSION = "1.1.0";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -1006,6 +1006,18 @@ interface WorkerSummary {
 interface RegisterWorkerParams {
     /** Queue name to process */
     queueName: string;
+    /**
+     * Stable worker identifier (1-128 chars, `[A-Za-z0-9._-]`).
+     *
+     * Supplying one makes registration an upsert, so a restarting worker reuses
+     * a single row and re-registering an id you already own is not charged
+     * against the plan worker cap. Omit it and the server mints a UUID, which
+     * means every restart leaves the old row occupying the cap until the
+     * stale-worker reaper clears it (~2 minutes) — enough for a crash-looping
+     * worker on a tight plan to 429 itself out of registering. An id owned by a
+     * different organization is rejected with HTTP 409.
+     */
+    workerId?: string;
     /** Worker hostname */
     hostname: string;
     /** Worker type identifier */
@@ -1485,9 +1497,24 @@ interface OutgoingWebhook {
     url: string;
     events: WebhookEventType[];
     enabled: boolean;
+    /**
+     * Consecutive failed deliveries.
+     *
+     * Counted once per DELIVERY, not once per retry attempt, so for the same
+     * real-world failures this is roughly 5x smaller than a per-attempt count.
+     * A successful delivery resets it to 0, including a successful manual retry
+     * via `retryDelivery()`. At 20 the webhook is disabled automatically.
+     */
     failureCount: number;
     lastTriggeredAt?: string;
-    lastStatus?: "success" | "failed";
+    /**
+     * Outcome of the most recent delivery.
+     *
+     * `"auto_disabled"` means 20 consecutive failed deliveries disabled the
+     * webhook: `enabled` is now false and no further events are delivered until
+     * it is re-enabled with `update(id, { enabled: true })`.
+     */
+    lastStatus?: "success" | "failed" | "auto_disabled";
     createdAt: string;
     updatedAt: string;
 }
@@ -1504,12 +1531,34 @@ interface CreateOutgoingWebhookParams {
     /** Whether enabled (default: true) */
     enabled?: boolean;
 }
-/** Parameters for updating an outgoing webhook */
+/**
+ * Parameters for updating an outgoing webhook.
+ *
+ * Every field is optional and only the fields you send are changed.
+ */
 interface UpdateOutgoingWebhookParams {
     name?: string;
     url?: string;
     events?: WebhookEventType[];
-    secret?: string;
+    /**
+     * HMAC secret used to sign deliveries.
+     *
+     * Omit the field to keep the current secret, pass a string to replace it, or
+     * pass `null` to CLEAR it. Clearing is destructive: deliveries then go out
+     * unsigned, with no `X-Spooled-Signature` header, and the old secret cannot
+     * be recovered. Client code that reserialises an unchanged webhook must send
+     * `undefined` (or drop the key) rather than `null`, or it will wipe a live
+     * secret.
+     */
+    secret?: string | null;
+    /**
+     * Whether the webhook receives events.
+     *
+     * Setting this to `true` is the recovery path for a webhook that was
+     * auto-disabled after 20 consecutive failed deliveries. Re-enabling is
+     * charged against the plan webhook cap, so it can fail with HTTP 429
+     * `QUOTA_EXCEEDED` even though no webhook is being created.
+     */
     enabled?: boolean;
 }
 /** Response for webhook test */
@@ -1519,7 +1568,15 @@ interface TestWebhookResponse {
     responseTimeMs: number;
     error?: string;
 }
-/** Webhook delivery record */
+/**
+ * Webhook delivery record.
+ *
+ * Delivery history is retained, not permanent: rows are removed by the
+ * per-organization retention sweep using the plan's history retention window
+ * (free 1 day, starter 7, pro 30, enterprise 90). Only the newest 100
+ * deliveries per webhook are readable through the API in any case, so copy
+ * anything you need as a durable audit record into your own store.
+ */
 interface OutgoingWebhookDelivery {
     id: string;
     webhookId: string;
@@ -1593,6 +1650,12 @@ interface ApiKeySummary {
     rateLimit?: number;
     isActive: boolean;
     createdAt: string;
+    /**
+     * Coarse last-use timestamp, written at most once per key per 5 minutes
+     * rather than on every request. Treat it as "used recently", not as a live
+     * signal: it can lag actual use by up to 5 minutes, so it cannot answer
+     * "is this key in use right now" and idle-key checks must allow for the lag.
+     */
     lastUsed?: string;
     expiresAt?: string;
 }
@@ -3292,6 +3355,16 @@ declare function createClient(options: SpooledClientConfig): SpooledClient;
 interface SpooledWorkerOptions {
     /** Queue name to process */
     queueName: string;
+    /**
+     * Stable worker identifier (1-128 chars, `[A-Za-z0-9._-]`).
+     *
+     * Set this on any worker that restarts or redeploys: registration becomes an
+     * upsert, so the process reuses one row instead of leaving the previous
+     * registration to occupy the plan worker cap until the stale-worker reaper
+     * clears it (~2 minutes). Omit it and the server mints a UUID on every
+     * start. An id owned by a different organization is rejected with HTTP 409.
+     */
+    workerId?: string;
     /** Worker hostname (default: auto-detected) */
     hostname?: string;
     /** Worker type identifier */
@@ -3422,6 +3495,11 @@ type EventHandler<E extends WorkerEvent> = (data: WorkerEventData[E]) => void;
  */
 declare class SpooledWorker {
     private readonly client;
+    /**
+     * Options with every defaultable field filled in. `workerId` stays optional:
+     * there is no sensible default for it, and omitting it is what makes the
+     * server mint a UUID.
+     */
     private readonly options;
     private readonly debug;
     private state;

package/dist/{index-DA_znF4h.d.ts → index-D_MpLQYY.d.ts}

@@ -107,11 +107,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.0.40";
+    readonly userAgent: "@spooled/sdk-nodejs/1.1.0";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.0.40";
+declare const SDK_VERSION = "1.1.0";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -1006,6 +1006,18 @@ interface WorkerSummary {
 interface RegisterWorkerParams {
     /** Queue name to process */
     queueName: string;
+    /**
+     * Stable worker identifier (1-128 chars, `[A-Za-z0-9._-]`).
+     *
+     * Supplying one makes registration an upsert, so a restarting worker reuses
+     * a single row and re-registering an id you already own is not charged
+     * against the plan worker cap. Omit it and the server mints a UUID, which
+     * means every restart leaves the old row occupying the cap until the
+     * stale-worker reaper clears it (~2 minutes) — enough for a crash-looping
+     * worker on a tight plan to 429 itself out of registering. An id owned by a
+     * different organization is rejected with HTTP 409.
+     */
+    workerId?: string;
     /** Worker hostname */
     hostname: string;
     /** Worker type identifier */
@@ -1485,9 +1497,24 @@ interface OutgoingWebhook {
     url: string;
     events: WebhookEventType[];
     enabled: boolean;
+    /**
+     * Consecutive failed deliveries.
+     *
+     * Counted once per DELIVERY, not once per retry attempt, so for the same
+     * real-world failures this is roughly 5x smaller than a per-attempt count.
+     * A successful delivery resets it to 0, including a successful manual retry
+     * via `retryDelivery()`. At 20 the webhook is disabled automatically.
+     */
     failureCount: number;
     lastTriggeredAt?: string;
-    lastStatus?: "success" | "failed";
+    /**
+     * Outcome of the most recent delivery.
+     *
+     * `"auto_disabled"` means 20 consecutive failed deliveries disabled the
+     * webhook: `enabled` is now false and no further events are delivered until
+     * it is re-enabled with `update(id, { enabled: true })`.
+     */
+    lastStatus?: "success" | "failed" | "auto_disabled";
     createdAt: string;
     updatedAt: string;
 }
@@ -1504,12 +1531,34 @@ interface CreateOutgoingWebhookParams {
     /** Whether enabled (default: true) */
     enabled?: boolean;
 }
-/** Parameters for updating an outgoing webhook */
+/**
+ * Parameters for updating an outgoing webhook.
+ *
+ * Every field is optional and only the fields you send are changed.
+ */
 interface UpdateOutgoingWebhookParams {
     name?: string;
     url?: string;
     events?: WebhookEventType[];
-    secret?: string;
+    /**
+     * HMAC secret used to sign deliveries.
+     *
+     * Omit the field to keep the current secret, pass a string to replace it, or
+     * pass `null` to CLEAR it. Clearing is destructive: deliveries then go out
+     * unsigned, with no `X-Spooled-Signature` header, and the old secret cannot
+     * be recovered. Client code that reserialises an unchanged webhook must send
+     * `undefined` (or drop the key) rather than `null`, or it will wipe a live
+     * secret.
+     */
+    secret?: string | null;
+    /**
+     * Whether the webhook receives events.
+     *
+     * Setting this to `true` is the recovery path for a webhook that was
+     * auto-disabled after 20 consecutive failed deliveries. Re-enabling is
+     * charged against the plan webhook cap, so it can fail with HTTP 429
+     * `QUOTA_EXCEEDED` even though no webhook is being created.
+     */
     enabled?: boolean;
 }
 /** Response for webhook test */
@@ -1519,7 +1568,15 @@ interface TestWebhookResponse {
     responseTimeMs: number;
     error?: string;
 }
-/** Webhook delivery record */
+/**
+ * Webhook delivery record.
+ *
+ * Delivery history is retained, not permanent: rows are removed by the
+ * per-organization retention sweep using the plan's history retention window
+ * (free 1 day, starter 7, pro 30, enterprise 90). Only the newest 100
+ * deliveries per webhook are readable through the API in any case, so copy
+ * anything you need as a durable audit record into your own store.
+ */
 interface OutgoingWebhookDelivery {
     id: string;
     webhookId: string;
@@ -1593,6 +1650,12 @@ interface ApiKeySummary {
     rateLimit?: number;
     isActive: boolean;
     createdAt: string;
+    /**
+     * Coarse last-use timestamp, written at most once per key per 5 minutes
+     * rather than on every request. Treat it as "used recently", not as a live
+     * signal: it can lag actual use by up to 5 minutes, so it cannot answer
+     * "is this key in use right now" and idle-key checks must allow for the lag.
+     */
     lastUsed?: string;
     expiresAt?: string;
 }
@@ -3292,6 +3355,16 @@ declare function createClient(options: SpooledClientConfig): SpooledClient;
 interface SpooledWorkerOptions {
     /** Queue name to process */
     queueName: string;
+    /**
+     * Stable worker identifier (1-128 chars, `[A-Za-z0-9._-]`).
+     *
+     * Set this on any worker that restarts or redeploys: registration becomes an
+     * upsert, so the process reuses one row instead of leaving the previous
+     * registration to occupy the plan worker cap until the stale-worker reaper
+     * clears it (~2 minutes). Omit it and the server mints a UUID on every
+     * start. An id owned by a different organization is rejected with HTTP 409.
+     */
+    workerId?: string;
     /** Worker hostname (default: auto-detected) */
     hostname?: string;
     /** Worker type identifier */
@@ -3422,6 +3495,11 @@ type EventHandler<E extends WorkerEvent> = (data: WorkerEventData[E]) => void;
  */
 declare class SpooledWorker {
     private readonly client;
+    /**
+     * Options with every defaultable field filled in. `workerId` stays optional:
+     * there is no sensible default for it, and omitting it is what makes the
+     * server mint a UUID.
+     */
     private readonly options;
     private readonly debug;
     private state;

package/dist/index.cjs

@@ -50,10 +50,10 @@ var DEFAULT_CONFIG = {
     successThreshold: 3,
     timeout: 3e4
   },
-  userAgent: "@spooled/sdk-nodejs/1.0.40",
+  userAgent: "@spooled/sdk-nodejs/1.1.0",
   autoRefreshToken: true
 };
-var SDK_VERSION = "1.0.40";
+var SDK_VERSION = "1.1.0";
 var API_VERSION = "v1";
 var API_BASE_PATH = `/api/${API_VERSION}`;
 function normalizeCredential(value) {
@@ -3661,6 +3661,11 @@ var DEFAULT_OPTIONS = {
 };
 var SpooledWorker = class {
   client;
+  /**
+   * Options with every defaultable field filled in. `workerId` stays optional:
+   * there is no sensible default for it, and omitting it is what makes the
+   * server mint a UUID.
+   */
   options;
   debug;
   state = "idle";
@@ -3731,6 +3736,7 @@ var SpooledWorker = class {
     try {
       const registration = await this.client.workers.register({
         queueName: this.options.queueName,
+        workerId: this.options.workerId,
         hostname: this.options.hostname,
         workerType: this.options.workerType,
         maxConcurrency: this.options.concurrency,