@curviate/sdk 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -7,6 +7,30 @@ Versioning: semantic — minor for additive changes, patch for bug fixes; no sta
 
 ---
 
+## [0.14.1] — 2026-07-07
+
+### Fixed
+
+- **`constructEvent` examples referenced a wrong header name (`X-Curviate-Signature` → `Curviate-Signature`); corrected a stale default-count description.** The JSDoc and both code examples (Express/Node, Hono) for `constructEvent` named the header `X-Curviate-Signature`; the dispatcher actually sends `Curviate-Signature` (Node lowercases it to `curviate-signature` on `req.headers`), so integrators copying the examples verbatim got `undefined` for the signature header. Also corrected the generated `events` field description on the webhook-create schema from a stale "default: all 7" to "default: all 11 lifecycle events", matching the account_status catalogue.
+
+---
+
+## [0.14.0] — 2026-07-07
+
+Webhooks surface re-based onto the v2 catalogue. Additive minor: one new method,
+one type-only breaking note for `CurviateEvent` (see below).
+
+### Added
+
+- **`webhooks.get(id)`.** Return a single webhook owned by the calling tenant (`GET /v1/webhooks/{id}`). The plaintext secret is never present on a read — only `secret_prefix`. Type `WebhookGetResult`. The `webhooks` namespace is now 7 methods (was 6).
+- **Webhook event catalogue expanded 21 → 27** (`webhooks.listEvents()`), grouped messaging (8) / user (2) / account_status (14), plus 3 tier-gated. New subscribable-but-not-default events: `chat.updated`, `chat.deleted` (messaging), `connection.new` (user), `account.initial_sync.running` / `account.initial_sync.completed` / `account.initial_sync.failed` (account_status). Catalogue entries may now carry an `availability: "realtime" | "no_longer_realtime" | "not_realtime"` field.
+
+### Changed (type-only breaking note)
+
+- **`CurviateEvent` union re-keyed 19 → 24 deliverable events** to match the create-subscribable catalogue. Renamed/removed: `account.stopped`, `account.sync_started`, `account.sync_complete`, `account.creation_success`, `account.sync_success`, `account.reconnect_required`, `account.checkpoint` are gone; the account-lifecycle names now split across `account.synced`, `account.reconnected`, `account.reconnect_needed`, `account.paused`, `account.connecting`, `account.permission_revoked`. Net-new members: `chat.updated`, `chat.deleted`, `connection.new`, `account.initial_sync.running`, `account.initial_sync.completed`, `account.initial_sync.failed`. A `switch`/exhaustiveness check on `event.type` for any of the 7 removed names will now fail to compile — update the case list. Runtime HMAC verification (`constructEvent`) is unaffected; this is a types-only change.
+
+---
+
 ## [0.13.0] — 2026-07-05
 
 Accounts/Auth surface migration. This is a **breaking** minor (pre-1.0): the account

package/README.md

@@ -154,7 +154,7 @@ import { constructEvent, WebhookSignatureError } from "@curviate/sdk";
 
 // Express (Node 18+)
 app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
-  const sig = req.headers["x-curviate-signature"] as string;
+  const sig = req.headers["curviate-signature"] as string;
   const secret = process.env.CURVIATE_WEBHOOK_SECRET!;
 
   let event;
@@ -176,7 +176,7 @@ app.post("/webhook", express.raw({ type: "application/json" }), async (req, res)
     case "account.connected":
       handleAccountConnected(event.data);
       break;
-    // 17 more event types — all in the CurviateEvent union
+    // 22 more event types — all in the CurviateEvent union
   }
 
   res.sendStatus(200);
@@ -185,7 +185,7 @@ app.post("/webhook", express.raw({ type: "application/json" }), async (req, res)
 // Hono / Vercel Edge — always await (Web Crypto is async)
 app.post("/webhook", async (c) => {
   const rawBody = await c.req.text();
-  const event = await constructEvent(rawBody, c.req.header("x-curviate-signature")!, secret);
+  const event = await constructEvent(rawBody, c.req.header("curviate-signature")!, secret);
   return c.text("ok");
 });
 ```

package/dist/index.d.ts

@@ -16726,7 +16726,7 @@ interface paths {
                             value: string;
                         }[];
                         /** @description Messaging events to subscribe to (default: [message.received]) */
-                        events?: ("message.received" | "message.delivered" | "message.read" | "message.reaction" | "message.edited" | "message.deleted")[];
+                        events?: ("message.received" | "message.delivered" | "message.read" | "message.reaction" | "message.edited" | "message.deleted" | "chat.updated" | "chat.deleted")[];
                         /**
                          * @description Field-remapping keys for the messaging delivery payload
                          * @default []
@@ -16761,7 +16761,7 @@ interface paths {
                             value: string;
                         }[];
                         /** @description User/relation events to subscribe to (default: [connection.accepted]) */
-                        events?: "connection.accepted"[];
+                        events?: ("connection.accepted" | "connection.new")[];
                         /**
                          * @description Field-remapping keys for the user/relation delivery payload
                          * @default []
@@ -16795,8 +16795,8 @@ interface paths {
                             key: string;
                             value: string;
                         }[];
-                        /** @description Account-status events to subscribe to (default: all 7) */
-                        events?: ("account.created" | "account.connected" | "account.synced" | "account.reconnected" | "account.reconnect_needed" | "account.creation_failed" | "account.disconnected" | "account.error" | "account.paused" | "account.connecting" | "account.permission_revoked")[];
+                        /** @description Account-status events to subscribe to (default: all 11 lifecycle events) */
+                        events?: ("account.created" | "account.connected" | "account.synced" | "account.reconnected" | "account.reconnect_needed" | "account.creation_failed" | "account.disconnected" | "account.error" | "account.paused" | "account.connecting" | "account.permission_revoked" | "account.initial_sync.running" | "account.initial_sync.completed" | "account.initial_sync.failed")[];
                     };
                 };
             };
@@ -16918,7 +16918,7 @@ interface paths {
         };
         /**
          * List webhook event types
-         * @description Returns the complete canonical event catalogue (21 events) grouped by source: messaging (6), user (1), account_status (11), plus 3 tier-gated events. No quota consumed.
+         * @description Returns the complete canonical event catalogue (27 events) grouped by source: messaging (8), user (2), account_status (14), plus 3 tier-gated events. No quota consumed.
          */
         get: {
             parameters: {
@@ -16960,6 +16960,11 @@ interface paths {
                                      * @enum {string}
                                      */
                                     tier?: "recruiter" | "sales_nav";
+                                    /**
+                                     * @description Delivery timing. Omitted (equivalent to 'realtime') on every live-pushed event. 'no_longer_realtime' means no push exists for this event; 'not_realtime' means the event is polled, not pushed, and may lag the underlying LinkedIn event.
+                                     * @enum {string}
+                                     */
+                                    availability?: "realtime" | "no_longer_realtime" | "not_realtime";
                                 }[];
                             }[];
                         };
@@ -17003,7 +17008,113 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Get a webhook
+         * @description Returns a single webhook owned by the calling tenant. The plaintext secret is never present on a read — only the prefix.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Webhook id (wh_-prefixed ULID). */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The webhook, if owned by the calling tenant. The signing secret is never returned on a read — only the prefix. */
+                200: {
+                    headers: {
+                        "RateLimit-Policy": components["headers"]["RateLimit-Policy"];
+                        RateLimit: components["headers"]["RateLimit"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description Response type discriminator.
+                             * @enum {string}
+                             */
+                            object?: "webhook";
+                            /** @description Webhook id (wh_-prefixed ULID). */
+                            id?: string;
+                            /**
+                             * @description The event source this webhook subscribes to (immutable).
+                             * @enum {string}
+                             */
+                            source?: "messaging" | "user" | "account_status";
+                            /** @description The URL that receives delivery POST requests. */
+                            request_url?: string;
+                            /** @description Human-readable label. */
+                            name?: string | null;
+                            /**
+                             * @description Delivery body encoding.
+                             * @enum {string}
+                             */
+                            format?: "json" | "form";
+                            /** @description Accounts targeted by this webhook. Non-empty — each id is owned by the tenant. */
+                            account_ids?: string[];
+                            /** @description A disabled webhook is kept but delivers nothing. */
+                            enabled?: boolean;
+                            /** @description Custom headers added to each delivery POST. */
+                            headers?: {
+                                key?: string;
+                                value?: string;
+                            }[];
+                            /** @description Canonical event names this webhook subscribes to. */
+                            events?: string[];
+                            /** @description Field-remapping keys for the delivery payload (messaging and user sources only). */
+                            data?: string[];
+                            /** @description First 8 characters of the signing secret. The full secret is never returned on edit — it is preserved unchanged. */
+                            secret_prefix?: string;
+                            /** @description ISO-8601 creation timestamp. */
+                            created_at?: string;
+                        };
+                    };
+                };
+                /** @description Malformed or empty webhook id. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Missing or invalid API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Webhook not found or not owned by this tenant. */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Rate limited — slow down and retry after the hinted delay. */
+                429: {
+                    headers: {
+                        "RateLimit-Policy": components["headers"]["RateLimit-Policy"];
+                        RateLimit: components["headers"]["RateLimit"];
+                        "Retry-After": components["headers"]["Retry-After"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
         put?: never;
         post?: never;
         /**
@@ -18335,12 +18446,13 @@ declare class CompaniesResource {
 }
 
 /**
- * Webhooks resource — 6 methods (root-scoped).
+ * Webhooks resource — 7 methods (root-scoped).
  *
  * Root-scoped: webhooks are tenant-wide, not account-scoped. All methods are
  * mounted directly on the root client (like `accounts`).
  * `getStateDiff` is placed here because it is tagged Webhooks in the OpenAPI
  * (`GET /v1/accounts/:id/state-diff` enables event-driven state sync).
+ * `get` is net-new — a single tenant-scoped read by id.
  */
 
 type WebhookCreateBody = paths["/v1/webhooks"]["post"]["requestBody"]["content"]["application/json"];
@@ -18348,6 +18460,7 @@ type WebhookCreateResult = paths["/v1/webhooks"]["post"]["responses"]["201"]["co
 type WebhookListParams = NonNullable<paths["/v1/webhooks"]["get"]["parameters"]["query"]>;
 type WebhookListResult = paths["/v1/webhooks"]["get"]["responses"]["200"]["content"]["application/json"];
 type WebhookListEventsResult = paths["/v1/webhooks/events"]["get"]["responses"]["200"]["content"]["application/json"];
+type WebhookGetResult = paths["/v1/webhooks/{id}"]["get"]["responses"]["200"]["content"]["application/json"];
 type WebhookUpdateBody = paths["/v1/webhooks/{id}"]["patch"]["requestBody"]["content"]["application/json"];
 type WebhookUpdateResult = paths["/v1/webhooks/{id}"]["patch"]["responses"]["200"]["content"]["application/json"];
 type WebhookDeleteResult = paths["/v1/webhooks/{id}"]["delete"]["responses"]["200"]["content"]["application/json"];
@@ -18369,10 +18482,16 @@ declare class WebhooksResource {
      */
     list(params?: WebhookListParams): Promise<WebhookListResult>;
     /**
-     * Return the complete canonical webhook event catalogue (21 events, grouped by source).
+     * Return the complete canonical webhook event catalogue (27 events, grouped by source).
      * `GET /v1/webhooks/events`
      */
     listEvents(): Promise<WebhookListEventsResult>;
+    /**
+     * Return a single webhook owned by the calling tenant.
+     * `GET /v1/webhooks/{id}`
+     * The plaintext secret is never present on a read — only `secret_prefix`.
+     */
+    get(id: string): Promise<WebhookGetResult>;
     /**
      * Update a webhook in place. `source` is immutable.
      * `PATCH /v1/webhooks/{id}`
@@ -18658,8 +18777,19 @@ interface AccountPayload {
     [key: string]: unknown;
 }
 /**
- * The complete discriminated union of all 19 canonical Curviate webhook events.
- * The `type` field is the discriminant.
+ * The complete discriminated union of all 24 canonical, create-subscribable
+ * Curviate webhook events. The `type` field is the discriminant.
+ *
+ * Re-keyed for the v2 catalogue (was 19). Renamed/removed vs. the prior set:
+ * `account.stopped`, `account.sync_started`, `account.sync_complete`,
+ * `account.creation_success`, `account.sync_success`, `account.reconnect_required`,
+ * and `account.checkpoint` are gone — the account-lifecycle names now split
+ * across `account.synced` / `account.reconnected` / `account.reconnect_needed` /
+ * `account.paused` / `account.connecting` / `account.permission_revoked`. Net-new:
+ * `chat.updated`, `chat.deleted`, `connection.new`, and the three
+ * `account.initial_sync.*` events. This union is pinned at compile time against
+ * the generated create-events enum (see `test/webhooks.constructEvent.test.ts`)
+ * — it must never drift from the served catalogue again.
  *
  * @example
  * const event = await constructEvent(rawBody, header, secret);
@@ -18685,9 +18815,18 @@ type CurviateEvent = {
 } | {
     type: "message.reaction";
     data: MessagePayload;
+} | {
+    type: "chat.updated";
+    data: MessagePayload;
+} | {
+    type: "chat.deleted";
+    data: MessagePayload;
 } | {
     type: "connection.accepted";
     data: ConnectionPayload;
+} | {
+    type: "connection.new";
+    data: ConnectionPayload;
 } | {
     type: "account.created";
     data: AccountPayload;
@@ -18695,34 +18834,40 @@ type CurviateEvent = {
     type: "account.connected";
     data: AccountPayload;
 } | {
-    type: "account.disconnected";
+    type: "account.synced";
     data: AccountPayload;
 } | {
-    type: "account.error";
+    type: "account.reconnected";
     data: AccountPayload;
 } | {
-    type: "account.stopped";
+    type: "account.reconnect_needed";
     data: AccountPayload;
 } | {
-    type: "account.sync_started";
+    type: "account.creation_failed";
     data: AccountPayload;
 } | {
-    type: "account.sync_complete";
+    type: "account.disconnected";
     data: AccountPayload;
 } | {
-    type: "account.creation_success";
+    type: "account.error";
     data: AccountPayload;
 } | {
-    type: "account.creation_failed";
+    type: "account.paused";
+    data: AccountPayload;
+} | {
+    type: "account.connecting";
+    data: AccountPayload;
+} | {
+    type: "account.permission_revoked";
     data: AccountPayload;
 } | {
-    type: "account.sync_success";
+    type: "account.initial_sync.running";
     data: AccountPayload;
 } | {
-    type: "account.reconnect_required";
+    type: "account.initial_sync.completed";
     data: AccountPayload;
 } | {
-    type: "account.checkpoint";
+    type: "account.initial_sync.failed";
     data: AccountPayload;
 };
 /**
@@ -18749,7 +18894,7 @@ interface ConstructEventOptions {
  *
  * @param rawBody - The raw (un-parsed) request body as a string or Buffer.
  *   **Must be the exact bytes received** — do not JSON.parse then re-serialize.
- * @param signatureHeader - Full value of the `X-Curviate-Signature` header.
+ * @param signatureHeader - Full value of the `Curviate-Signature` header.
  * @param secret - The webhook signing secret from your webhook registration.
  * @param opts - Optional verification settings.
  * @returns `Promise<CurviateEvent>` — a typed event once verified.
@@ -18759,7 +18904,7 @@ interface ConstructEventOptions {
  * @example
  * // Express handler (Node 18+)
  * app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
- *   const sig = req.headers['x-curviate-signature'] as string;
+ *   const sig = req.headers['curviate-signature'] as string;
  *   let event;
  *   try {
  *     event = await constructEvent(req.body, sig, secret);
@@ -18777,7 +18922,7 @@ interface ConstructEventOptions {
  * // Hono / Vercel Edge
  * app.post('/webhook', async (c) => {
  *   const rawBody = await c.req.text();
- *   const event = await constructEvent(rawBody, c.req.header('x-curviate-signature')!, secret);
+ *   const event = await constructEvent(rawBody, c.req.header('curviate-signature')!, secret);
  *   return c.text('ok');
  * });
  */

package/dist/index.js

@@ -1630,7 +1630,7 @@ var WebhooksResource = class {
     });
   }
   /**
-   * Return the complete canonical webhook event catalogue (21 events, grouped by source).
+   * Return the complete canonical webhook event catalogue (27 events, grouped by source).
    * `GET /v1/webhooks/events`
    */
   listEvents() {
@@ -1639,6 +1639,17 @@ var WebhooksResource = class {
       path: "/v1/webhooks/events"
     });
   }
+  /**
+   * Return a single webhook owned by the calling tenant.
+   * `GET /v1/webhooks/{id}`
+   * The plaintext secret is never present on a read — only `secret_prefix`.
+   */
+  get(id) {
+    return this.ctx.request({
+      method: "GET",
+      path: `/v1/webhooks/${id}`
+    });
+  }
   /**
    * Update a webhook in place. `source` is immutable.
    * `PATCH /v1/webhooks/{id}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curviate/sdk",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "private": false,
   "description": "TypeScript SDK for the Curviate API.",
   "license": "MIT",

package/src/generated/types.ts

@@ -16617,7 +16617,7 @@ export interface paths {
                             value: string;
                         }[];
                         /** @description Messaging events to subscribe to (default: [message.received]) */
-                        events?: ("message.received" | "message.delivered" | "message.read" | "message.reaction" | "message.edited" | "message.deleted")[];
+                        events?: ("message.received" | "message.delivered" | "message.read" | "message.reaction" | "message.edited" | "message.deleted" | "chat.updated" | "chat.deleted")[];
                         /**
                          * @description Field-remapping keys for the messaging delivery payload
                          * @default []
@@ -16652,7 +16652,7 @@ export interface paths {
                             value: string;
                         }[];
                         /** @description User/relation events to subscribe to (default: [connection.accepted]) */
-                        events?: "connection.accepted"[];
+                        events?: ("connection.accepted" | "connection.new")[];
                         /**
                          * @description Field-remapping keys for the user/relation delivery payload
                          * @default []
@@ -16686,8 +16686,8 @@ export interface paths {
                             key: string;
                             value: string;
                         }[];
-                        /** @description Account-status events to subscribe to (default: all 7) */
-                        events?: ("account.created" | "account.connected" | "account.synced" | "account.reconnected" | "account.reconnect_needed" | "account.creation_failed" | "account.disconnected" | "account.error" | "account.paused" | "account.connecting" | "account.permission_revoked")[];
+                        /** @description Account-status events to subscribe to (default: all 11 lifecycle events) */
+                        events?: ("account.created" | "account.connected" | "account.synced" | "account.reconnected" | "account.reconnect_needed" | "account.creation_failed" | "account.disconnected" | "account.error" | "account.paused" | "account.connecting" | "account.permission_revoked" | "account.initial_sync.running" | "account.initial_sync.completed" | "account.initial_sync.failed")[];
                     };
                 };
             };
@@ -16809,7 +16809,7 @@ export interface paths {
         };
         /**
          * List webhook event types
-         * @description Returns the complete canonical event catalogue (21 events) grouped by source: messaging (6), user (1), account_status (11), plus 3 tier-gated events. No quota consumed.
+         * @description Returns the complete canonical event catalogue (27 events) grouped by source: messaging (8), user (2), account_status (14), plus 3 tier-gated events. No quota consumed.
          */
         get: {
             parameters: {
@@ -16851,6 +16851,11 @@ export interface paths {
                                      * @enum {string}
                                      */
                                     tier?: "recruiter" | "sales_nav";
+                                    /**
+                                     * @description Delivery timing. Omitted (equivalent to 'realtime') on every live-pushed event. 'no_longer_realtime' means no push exists for this event; 'not_realtime' means the event is polled, not pushed, and may lag the underlying LinkedIn event.
+                                     * @enum {string}
+                                     */
+                                    availability?: "realtime" | "no_longer_realtime" | "not_realtime";
                                 }[];
                             }[];
                         };
@@ -16894,7 +16899,113 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Get a webhook
+         * @description Returns a single webhook owned by the calling tenant. The plaintext secret is never present on a read — only the prefix.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Webhook id (wh_-prefixed ULID). */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The webhook, if owned by the calling tenant. The signing secret is never returned on a read — only the prefix. */
+                200: {
+                    headers: {
+                        "RateLimit-Policy": components["headers"]["RateLimit-Policy"];
+                        RateLimit: components["headers"]["RateLimit"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description Response type discriminator.
+                             * @enum {string}
+                             */
+                            object?: "webhook";
+                            /** @description Webhook id (wh_-prefixed ULID). */
+                            id?: string;
+                            /**
+                             * @description The event source this webhook subscribes to (immutable).
+                             * @enum {string}
+                             */
+                            source?: "messaging" | "user" | "account_status";
+                            /** @description The URL that receives delivery POST requests. */
+                            request_url?: string;
+                            /** @description Human-readable label. */
+                            name?: string | null;
+                            /**
+                             * @description Delivery body encoding.
+                             * @enum {string}
+                             */
+                            format?: "json" | "form";
+                            /** @description Accounts targeted by this webhook. Non-empty — each id is owned by the tenant. */
+                            account_ids?: string[];
+                            /** @description A disabled webhook is kept but delivers nothing. */
+                            enabled?: boolean;
+                            /** @description Custom headers added to each delivery POST. */
+                            headers?: {
+                                key?: string;
+                                value?: string;
+                            }[];
+                            /** @description Canonical event names this webhook subscribes to. */
+                            events?: string[];
+                            /** @description Field-remapping keys for the delivery payload (messaging and user sources only). */
+                            data?: string[];
+                            /** @description First 8 characters of the signing secret. The full secret is never returned on edit — it is preserved unchanged. */
+                            secret_prefix?: string;
+                            /** @description ISO-8601 creation timestamp. */
+                            created_at?: string;
+                        };
+                    };
+                };
+                /** @description Malformed or empty webhook id. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Missing or invalid API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Webhook not found or not owned by this tenant. */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Rate limited — slow down and retry after the hinted delay. */
+                429: {
+                    headers: {
+                        "RateLimit-Policy": components["headers"]["RateLimit-Policy"];
+                        RateLimit: components["headers"]["RateLimit"];
+                        "Retry-After": components["headers"]["Retry-After"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
         put?: never;
         post?: never;
         /**