@nimbusnexus/webhooks-sdk 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -105,8 +105,12 @@ interface OutboxRecord {
     id: string;
     eventType: string;
     payload: Record<string, unknown>;
-    environment: string;
-    application: string;
+    /**
+     * The id of the project the event is published into (`prj_…`), or `null` for the workspace's default
+     * project. `null` means the `project_id` field is OMITTED from the publish body — the id is opaque
+     * and per-workspace, so only the server can resolve the default.
+     */
+    projectId: string | null;
     source: string | null;
     /** Epoch ms the record was first enqueued; `listPending` orders by this, oldest first. */
     createdAt: number;
@@ -186,12 +190,12 @@ declare class SqliteStore implements Store {
 }
 
 /** The published event, as returned by `POST /v1/events` (webhookd's `EventOut`). */
-interface WebhookdEvent {
+interface WebhooksEvent {
     id: string;
     eventUid: string;
     eventType: string;
-    application: string;
-    environment: string;
+    /** The id of the project the event was published into (always resolved server-side). */
+    projectId: string;
     deliveriesCreated: number;
     source: string | null;
 }
@@ -208,8 +212,8 @@ interface Subscription {
 interface Endpoint {
     id: string;
     url: string;
-    environment: string;
-    application: string;
+    /** The id of the project the endpoint belongs to. */
+    project_id: string;
     status: string;
     subscriptions: Subscription[];
     /** The signing secret — returned ONCE, on create + rotate-secret only. */
@@ -253,20 +257,20 @@ interface Page<T> {
 }
 interface ClientOptions {
     baseUrl: string;
-    /** A per-tenant API key (`whsk_…`) or a service token. */
+    /** A per-workspace API key (`whsk_…`) or a service token. */
     apiKey: string;
     timeoutMs?: number;
     maxRetries?: number;
     /** Inject a `fetch` implementation (defaults to the global `fetch`); used for tests. */
     fetchImpl?: typeof fetch;
     /**
-     * Durable outbox store. When set, {@link WebhookdClient.enqueue} / {@link WebhookdClient.drain}
-     * (and the background drainer) become available. Omit to use only the live {@link WebhookdClient.publish}.
+     * Durable outbox store. When set, {@link WebhooksClient.enqueue} / {@link WebhooksClient.drain}
+     * (and the background drainer) become available. Omit to use only the live {@link WebhooksClient.publish}.
      */
     store?: Store;
     /** Max delivery attempts before a record is parked dead (default 10). */
     maxAttempts?: number;
-    /** How many records a single {@link WebhookdClient.drain} pulls from the store (default 100). */
+    /** How many records a single {@link WebhooksClient.drain} pulls from the store (default 100). */
     drainBatchLimit?: number;
     /** Invoked once when `drain` parks a record dead (retry budget exhausted). */
     onDead?: (record: OutboxRecord) => void;
@@ -274,8 +278,11 @@ interface ClientOptions {
     onDrainError?: (error: unknown) => void;
 }
 interface EnqueueOptions {
-    environment?: string;
-    application?: string;
+    /**
+     * The id of the project to publish into (`prj_…`). Omit (or pass an empty string) to target the
+     * workspace's default project — the server resolves it, there is no client-side sentinel.
+     */
+    projectId?: string;
     source?: string;
     /** The Idempotency-Key / record id. Defaults to a generated UUID v4. Re-enqueuing the same key is a no-op overwrite. */
     idempotencyKey?: string;
@@ -295,16 +302,22 @@ interface DrainResult {
     remaining: number;
 }
 interface PublishOptions {
-    environment?: string;
-    application?: string;
+    /**
+     * The id of the project to publish into (`prj_…`). Omit (or pass an empty string) to target the
+     * workspace's default project — the server resolves it, there is no client-side sentinel.
+     */
+    projectId?: string;
     source?: string;
     /** Makes the publish safe to retry — a replay returns the original event without re-fanning-out. */
     idempotencyKey?: string;
 }
 interface CreateEndpointOptions {
-    environment?: string;
+    /**
+     * The id of the project to create the endpoint in (`prj_…`). Omit (or pass an empty string) for
+     * the workspace's default project.
+     */
+    projectId?: string;
     subscriptions?: Subscription[];
-    application?: string;
     secret?: string;
     maxAttempts?: number;
     retrySchedule?: number[];
@@ -313,7 +326,11 @@ interface CreateEndpointOptions {
     deliveryTimeoutMs?: number;
 }
 interface ListEndpointsOptions {
-    environment?: string;
+    /**
+     * The id of the project to list endpoints for (`prj_…`). Omit (or pass an empty string) for the
+     * workspace's default project.
+     */
+    projectId?: string;
     offset?: number;
     limit?: number;
 }
@@ -345,7 +362,7 @@ interface ListDeliveriesOptions {
     offset?: number;
     limit?: number;
 }
-declare class WebhookdClient {
+declare class WebhooksClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeoutMs;
@@ -359,7 +376,7 @@ declare class WebhookdClient {
     private drainTimer?;
     private draining;
     constructor(opts: ClientOptions);
-    publish(eventType: string, payload: Record<string, unknown>, opts?: PublishOptions): Promise<WebhookdEvent>;
+    publish(eventType: string, payload: Record<string, unknown>, opts?: PublishOptions): Promise<WebhooksEvent>;
     /**
      * Durably buffer an event and return IMMEDIATELY — NO network call. Builds an {@link OutboxRecord}
      * (id = `opts.idempotencyKey` or a fresh UUID v4), saves it to the configured store, and returns the
@@ -388,7 +405,7 @@ declare class WebhookdClient {
     private requireStore;
     /** Create an endpoint. The response includes the signing `secret` exactly once — persist it. */
     createEndpoint(url: string, opts?: CreateEndpointOptions): Promise<Endpoint>;
-    /** List endpoints for an environment (defaults to `prod`). */
+    /** List endpoints for a project. Omit `projectId` for the workspace's default project. */
     listEndpoints(opts?: ListEndpointsOptions): Promise<Page<Endpoint>>;
     /** Fetch a single endpoint by id. */
     getEndpoint(id: string): Promise<Endpoint>;
@@ -416,13 +433,13 @@ declare class WebhookdClient {
     /**
      * 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.
      */
     private request;
 }
 
 /** Base class for all webhookd SDK errors (network failures, etc.). */
-declare class WebhookdError extends Error {
+declare class WebhooksError extends Error {
     constructor(message: string);
 }
 /**
@@ -430,7 +447,7 @@ declare class WebhookdError extends Error {
  * `code` (e.g. `"rate_limited"`, `"not_found"`, `"validation_error"`) and a human `message`,
  * plus the HTTP `statusCode`.
  */
-declare class WebhookdApiError extends WebhookdError {
+declare class WebhooksApiError extends WebhooksError {
     readonly statusCode: number;
     readonly code: string;
     constructor(statusCode: number, code: string, message: string);
@@ -440,9 +457,9 @@ declare class WebhookdApiError extends WebhookdError {
  * @nimbusnexus/webhooks-sdk — the official TypeScript client for NimbusNexus Webhooks.
  *
  * - `verify` — verify an incoming webhook's HMAC signature (for subscribers).
- * - `WebhookdClient` — publish events to webhookd (for producers).
+ * - `WebhooksClient` — publish events to webhookd (for producers).
  */
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.0";
 
-export { type ApiKey, type ClientOptions, type CreateApiKeyOptions, type CreateEndpointOptions, DEAD_NEXT_ATTEMPT_MS, DEFAULT_TOLERANCE_SECONDS, type Delivery, type DrainOptions, type DrainResult, type Endpoint, type EndpointPatch, type EnqueueOptions, FileStore, type ListDeliveriesOptions, type ListEndpointsOptions, MemoryStore, type OutboxRecord, type Page, PostgresStore, type PostgresStoreOptions, type PublishOptions, RedisStore, type RedisStoreOptions, SqliteStore, type Store, type Subscription, VERSION, type VerifyOptions, WebhookdApiError, WebhookdClient, WebhookdError, type WebhookdEvent, isDead, sign, verify };
+export { type ApiKey, type ClientOptions, type CreateApiKeyOptions, type CreateEndpointOptions, DEAD_NEXT_ATTEMPT_MS, DEFAULT_TOLERANCE_SECONDS, type Delivery, type DrainOptions, type DrainResult, type Endpoint, type EndpointPatch, type EnqueueOptions, FileStore, type ListDeliveriesOptions, type ListEndpointsOptions, MemoryStore, type OutboxRecord, type Page, PostgresStore, type PostgresStoreOptions, type PublishOptions, RedisStore, type RedisStoreOptions, SqliteStore, type Store, type Subscription, VERSION, type VerifyOptions, WebhooksApiError, WebhooksClient, WebhooksError, type WebhooksEvent, isDead, sign, verify };

package/dist/index.js

@@ -41,18 +41,18 @@ function verify(secret, rawBody, signature, opts = {}) {
 import { randomUUID } from "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;
   }
@@ -159,8 +159,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,
@@ -197,8 +196,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,
@@ -215,13 +213,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,
@@ -232,8 +229,7 @@ var PostgresStore = class {
         record.id,
         record.eventType,
         JSON.stringify(record.payload),
-        record.environment,
-        record.application,
+        record.projectId,
         record.source,
         record.attempts,
         record.lastError,
@@ -389,8 +385,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,
@@ -417,12 +412,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,
@@ -434,13 +431,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,
@@ -450,8 +446,7 @@ var SqliteStore = class {
       record.id,
       record.eventType,
       JSON.stringify(record.payload),
-      record.environment,
-      record.application,
+      record.projectId,
       record.source,
       record.createdAt,
       record.attempts,
@@ -496,7 +491,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;
@@ -524,10 +519,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;
@@ -537,8 +532,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
     };
@@ -556,8 +550,8 @@ var WebhookdClient = class {
       id: opts.idempotencyKey ?? 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,
@@ -584,10 +578,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", {
@@ -647,18 +640,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;
@@ -668,9 +659,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 });
@@ -744,7 +737,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}`;
@@ -781,7 +774,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));
@@ -790,9 +783,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);
 }
@@ -811,14 +807,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";
 export {
   DEAD_NEXT_ATTEMPT_MS,
   DEFAULT_TOLERANCE_SECONDS,
@@ -828,9 +824,9 @@ export {
   RedisStore,
   SqliteStore,
   VERSION,
-  WebhookdApiError,
-  WebhookdClient,
-  WebhookdError,
+  WebhooksApiError,
+  WebhooksClient,
+  WebhooksError,
   isDead,
   sign,
   verify