@nimbusnexus/webhooks-sdk 0.3.0 → 0.5.0

package/README.md

@@ -35,12 +35,24 @@ try {
     { orderId: "ord_123", total: 4200 },
     { idempotencyKey: "order-123" }, // makes the publish safe to retry
   );
-  console.log(event.eventUid, event.deliveriesCreated);
+  console.log(event.eventUid, event.projectId, event.deliveriesCreated);
 } catch (e) {
   if (e instanceof WebhookdApiError) console.error(e.statusCode, e.code, e.message);
 }
 ```
 
+**Projects.** A project is addressed by its **id** (`prj_…`), not a slug. Omit `projectId` — as
+above — to publish into your workspace's **default** project; the server resolves it. Pass one only to
+target a specific project:
+
+```ts
+await wh.publish("order.created", { orderId: "ord_123" }, { projectId: "prj_3f9a…" });
+```
+
+The id is opaque and per-workspace, so there is no client-side sentinel for "the default project":
+leaving `projectId` unset omits the field entirely. The response (`event.projectId`) always carries
+the id the event actually landed in.
+
 Transient failures (network errors, `429`, `5xx`) are retried with backoff (a `429` honours
 `Retry-After`); other `4xx` throw `WebhookdApiError` carrying the `{error:{code,message}}` envelope.
 
@@ -84,6 +96,10 @@ webhookd returns the original event without re-fanning-out. A record that keeps
 with capped exponential backoff up to `maxAttempts` (default 10), then parked **dead** (never retried
 again, retrievable via `store.listDead()`) and passed to the optional `onDead` callback.
 
+`enqueue` takes the same optional `projectId` as `publish` (omit it for the default project). It is
+persisted on the buffered record as a nullable `project_id` — `null` means "the workspace's default
+project", and `drain` then omits the field from the publish body.
+
 **Built-in stores** — pass one as `store` in `ClientOptions`:
 
 | Store | Durable? | Extra needed |
@@ -111,13 +127,15 @@ const wh = new WebhookdClient({ baseUrl: "https://webhooks.example.com", apiKey:
 
 // --- Endpoints ---------------------------------------------------------------
 // Create a receiver — its signing secret is in the response exactly once, so persist it now.
+// Omit `projectId` (here and on listEndpoints) for the workspace's default project.
 const ep = await wh.createEndpoint("https://your-app.example/webhooks", {
   subscriptions: [{ match_kind: "prefix", pattern: "order." }],
   description: "orders service",
 });
 const { id: endpointId, secret: signingSecret } = ep;
 
-await wh.listEndpoints({ environment: "prod" }); // { items, next_offset }
+await wh.listEndpoints();                          // default project — { items, next_offset }
+await wh.listEndpoints({ projectId: "prj_3f9a…" }); // a specific project, by id
 await wh.getEndpoint(endpointId);
 
 // PATCH — send only the keys you want to change (omitted = unchanged, null = cleared):

package/dist/index.cjs

@@ -38,9 +38,9 @@ __export(src_exports, {
   RedisStore: () => RedisStore,
   SqliteStore: () => SqliteStore,
   VERSION: () => VERSION,
-  WebhookdApiError: () => WebhookdApiError,
-  WebhookdClient: () => WebhookdClient,
-  WebhookdError: () => WebhookdError,
+  WebhooksApiError: () => WebhooksApiError,
+  WebhooksClient: () => WebhooksClient,
+  WebhooksError: () => WebhooksError,
   isDead: () => isDead,
   sign: () => sign,
   verify: () => verify
@@ -83,18 +83,18 @@ function verify(secret, rawBody, signature, opts = {}) {
 var import_node_crypto3 = require("crypto");
 
 // src/errors.ts
-var WebhookdError = class extends Error {
+var WebhooksError = class extends Error {
   constructor(message) {
     super(message);
-    this.name = "WebhookdError";
+    this.name = "WebhooksError";
   }
 };
-var WebhookdApiError = class extends WebhookdError {
+var WebhooksApiError = class extends WebhooksError {
   statusCode;
   code;
   constructor(statusCode, code, message) {
     super(`[${statusCode} ${code}] ${message}`);
-    this.name = "WebhookdApiError";
+    this.name = "WebhooksApiError";
     this.statusCode = statusCode;
     this.code = code;
   }
@@ -201,8 +201,7 @@ function rowToRecord(row) {
     id: row.id,
     eventType: row.event_type,
     payload: row.payload,
-    environment: row.environment,
-    application: row.application,
+    projectId: row.project_id,
     source: row.source,
     createdAt: Number(row.created_at),
     attempts: row.attempts,
@@ -239,8 +238,7 @@ var PostgresStore = class {
           id TEXT PRIMARY KEY,
           event_type TEXT NOT NULL,
           payload JSONB NOT NULL,
-          environment TEXT NOT NULL,
-          application TEXT NOT NULL,
+          project_id TEXT,
           source TEXT,
           sent BOOLEAN NOT NULL DEFAULT FALSE,
           attempts INTEGER NOT NULL,
@@ -257,13 +255,12 @@ var PostgresStore = class {
     const pool = await this.ensure();
     await pool.query(
       `INSERT INTO ${this.table}
-        (id, event_type, payload, environment, application, source, sent, attempts, last_error, next_attempt_at, created_at)
-       VALUES ($1, $2, $3, $4, $5, $6, FALSE, $7, $8, $9, $10)
+        (id, event_type, payload, project_id, source, sent, attempts, last_error, next_attempt_at, created_at)
+       VALUES ($1, $2, $3, $4, $5, FALSE, $6, $7, $8, $9)
        ON CONFLICT (id) DO UPDATE SET
          event_type = EXCLUDED.event_type,
          payload = EXCLUDED.payload,
-         environment = EXCLUDED.environment,
-         application = EXCLUDED.application,
+         project_id = EXCLUDED.project_id,
          source = EXCLUDED.source,
          sent = EXCLUDED.sent,
          attempts = EXCLUDED.attempts,
@@ -274,8 +271,7 @@ var PostgresStore = class {
         record.id,
         record.eventType,
         JSON.stringify(record.payload),
-        record.environment,
-        record.application,
+        record.projectId,
         record.source,
         record.attempts,
         record.lastError,
@@ -432,8 +428,7 @@ function rowToRecord2(row) {
     id: row.id,
     eventType: row.event_type,
     payload: JSON.parse(row.payload),
-    environment: row.environment,
-    application: row.application,
+    projectId: row.project_id,
     source: row.source,
     createdAt: row.created_at,
     attempts: row.attempts,
@@ -460,12 +455,14 @@ var SqliteStore = class {
     }
     this.db = new DatabaseSync(path);
     this.db.exec(
+      // `project_id` is NULLABLE: NULL = the workspace's default project (the publish body simply
+      // omits the field). Renamed from the legacy `project` slug column — this store has no
+      // schema-versioning mechanism, so a table created by an older SDK build is not upgraded.
       `CREATE TABLE IF NOT EXISTS webhookd_outbox (
         id TEXT PRIMARY KEY,
         event_type TEXT NOT NULL,
         payload TEXT NOT NULL,
-        environment TEXT NOT NULL,
-        application TEXT NOT NULL,
+        project_id TEXT,
         source TEXT,
         created_at INTEGER NOT NULL,
         attempts INTEGER NOT NULL,
@@ -477,13 +474,12 @@ var SqliteStore = class {
   save(record) {
     this.db.prepare(
       `INSERT INTO webhookd_outbox
-          (id, event_type, payload, environment, application, source, created_at, attempts, last_error, next_attempt_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          (id, event_type, payload, project_id, source, created_at, attempts, last_error, next_attempt_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(id) DO UPDATE SET
            event_type = excluded.event_type,
            payload = excluded.payload,
-           environment = excluded.environment,
-           application = excluded.application,
+           project_id = excluded.project_id,
            source = excluded.source,
            created_at = excluded.created_at,
            attempts = excluded.attempts,
@@ -493,8 +489,7 @@ var SqliteStore = class {
       record.id,
       record.eventType,
       JSON.stringify(record.payload),
-      record.environment,
-      record.application,
+      record.projectId,
       record.source,
       record.createdAt,
       record.attempts,
@@ -539,7 +534,7 @@ var SqliteStore = class {
 
 // src/client.ts
 var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
-var WebhookdClient = class {
+var WebhooksClient = class {
   baseUrl;
   apiKey;
   timeoutMs;
@@ -567,10 +562,10 @@ var WebhookdClient = class {
   async publish(eventType, payload, opts = {}) {
     const body = {
       event_type: eventType,
-      payload,
-      environment: opts.environment ?? "prod",
-      application: opts.application ?? "default"
+      payload
     };
+    const projectId = normalizeProjectId(opts.projectId);
+    if (projectId !== null) body.project_id = projectId;
     if (opts.source !== void 0) body.source = opts.source;
     const headers = {};
     if (opts.idempotencyKey !== void 0) headers["Idempotency-Key"] = opts.idempotencyKey;
@@ -580,8 +575,7 @@ var WebhookdClient = class {
       id: String(data.id),
       eventUid: String(data.event_uid),
       eventType: String(data.event_type),
-      application: String(data.application ?? "default"),
-      environment: String(data.environment ?? "prod"),
+      projectId: String(data.project_id),
       deliveriesCreated: Number(data.deliveries_created ?? 0),
       source: data.source ?? null
     };
@@ -599,8 +593,8 @@ var WebhookdClient = class {
       id: opts.idempotencyKey ?? (0, import_node_crypto3.randomUUID)(),
       eventType,
       payload,
-      environment: opts.environment ?? "prod",
-      application: opts.application ?? "default",
+      // null = the workspace's default project (the field is omitted from the publish body on drain).
+      projectId: normalizeProjectId(opts.projectId),
       source: opts.source ?? null,
       createdAt: now,
       attempts: 0,
@@ -627,10 +621,9 @@ var WebhookdClient = class {
     for (const record of rows) {
       const body = {
         event_type: record.eventType,
-        payload: record.payload,
-        environment: record.environment,
-        application: record.application
+        payload: record.payload
       };
+      if (record.projectId !== null) body.project_id = record.projectId;
       if (record.source !== null) body.source = record.source;
       try {
         await this.request("POST", "/v1/events", {
@@ -690,18 +683,16 @@ var WebhookdClient = class {
   }
   requireStore() {
     if (!this.store) {
-      throw new WebhookdError("no outbox store configured \u2014 pass `store` in ClientOptions");
+      throw new WebhooksError("no outbox store configured \u2014 pass `store` in ClientOptions");
     }
     return this.store;
   }
   // ── Endpoints ──────────────────────────────────────────────────────────────
   /** Create an endpoint. The response includes the signing `secret` exactly once — persist it. */
   async createEndpoint(url, opts = {}) {
-    const body = {
-      url,
-      environment: opts.environment ?? "prod",
-      application: opts.application ?? "default"
-    };
+    const body = { url };
+    const projectId = normalizeProjectId(opts.projectId);
+    if (projectId !== null) body.project_id = projectId;
     if (opts.subscriptions !== void 0) body.subscriptions = opts.subscriptions;
     if (opts.secret !== void 0) body.secret = opts.secret;
     if (opts.maxAttempts !== void 0) body.max_attempts = opts.maxAttempts;
@@ -711,9 +702,11 @@ var WebhookdClient = class {
     if (opts.deliveryTimeoutMs !== void 0) body.delivery_timeout_ms = opts.deliveryTimeoutMs;
     return this.requestJson("POST", "/v1/endpoints", { body });
   }
-  /** List endpoints for an environment (defaults to `prod`). */
+  /** List endpoints for a project. Omit `projectId` for the workspace's default project. */
   async listEndpoints(opts = {}) {
-    const query = { environment: opts.environment ?? "prod" };
+    const query = {};
+    const projectId = normalizeProjectId(opts.projectId);
+    if (projectId !== null) query.project_id = projectId;
     if (opts.offset !== void 0) query.offset = opts.offset;
     if (opts.limit !== void 0) query.limit = opts.limit;
     return this.requestJson("GET", "/v1/endpoints", { query });
@@ -787,7 +780,7 @@ var WebhookdClient = class {
   /**
    * The single request path used by every method: builds the URL (+ query), attaches auth, and runs
    * the shared retry loop (connection errors + 429 honoring Retry-After + 5xx, capped exponential
-   * backoff), raising a typed {@link WebhookdApiError} on other 4xx/5xx. The caller reads the body.
+   * backoff), raising a typed {@link WebhooksApiError} on other 4xx/5xx. The caller reads the body.
    */
   async request(method, path, opts = {}) {
     let url = `${this.baseUrl}${path}`;
@@ -824,7 +817,7 @@ var WebhookdClient = class {
           await sleep(backoffMs(attempt));
           continue;
         }
-        throw new WebhookdError(`request failed: ${String(err)}`);
+        throw new WebhooksError(`request failed: ${String(err)}`);
       }
       if (RETRY_STATUSES.has(resp.status) && attempt < this.maxRetries) {
         await sleep(retryAfterMs(resp) ?? backoffMs(attempt));
@@ -833,9 +826,12 @@ var WebhookdClient = class {
       if (resp.status >= 400) throw await apiError(resp);
       return resp;
     }
-    throw new WebhookdError(`request failed after retries: ${String(lastErr)}`);
+    throw new WebhooksError(`request failed after retries: ${String(lastErr)}`);
   }
 };
+function normalizeProjectId(projectId) {
+  return projectId === void 0 || projectId === null || projectId === "" ? null : projectId;
+}
 function backoffMs(attempt) {
   return Math.min(2e3, 200 * 2 ** attempt);
 }
@@ -854,14 +850,14 @@ async function apiError(resp) {
     message = data.error?.message ?? message;
   } catch {
   }
-  return new WebhookdApiError(resp.status, code, message);
+  return new WebhooksApiError(resp.status, code, message);
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.5.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEAD_NEXT_ATTEMPT_MS,
@@ -872,9 +868,9 @@ var VERSION = "0.3.0";
   RedisStore,
   SqliteStore,
   VERSION,
-  WebhookdApiError,
-  WebhookdClient,
-  WebhookdError,
+  WebhooksApiError,
+  WebhooksClient,
+  WebhooksError,
   isDead,
   sign,
   verify