@curviate/sdk 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -9,6 +9,68 @@ Versioning: semantic — minor for additive changes, patch for bug fixes; no sta
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-08-03
+
+### Fixed
+
+- **`constructEvent` now parses real webhook deliveries. It previously rejected
+  every single one.** The Curviate platform sends the event name in `event`;
+  the SDK required a `type` field that no delivery has ever contained, so
+  verification threw `WebhookSignatureError` on 100% of genuine webhooks. The
+  HMAC path was never at fault (a tampered body was correctly rejected as
+  `invalid_signature`); the parse step was. If webhook verification has never
+  worked for you, this is why, and this release fixes it.
+
+- **A body problem no longer reports a header problem.** A payload whose
+  signature verifies but whose body cannot be parsed used to fail with
+  `reason: "malformed_header"`, pointing at the two things that had just been
+  proven correct: the header and the signing secret. Integrators read that and
+  rotated a secret that was never wrong. Those cases now report the new
+  `reason: "malformed_payload"`, and the message no longer mentions the header,
+  the signature, or the secret.
+
+### Changed
+
+- **BREAKING (type-level), and it breaks no working code.** The `CurviateEvent`
+  discriminant is now `event`, not `type`:
+
+  ```diff
+  - if (event.type === "message.received") { ... }
+  + if (event.event === "message.received") { ... }
+  ```
+
+  Read the label carefully before deferring the upgrade: **there is no working
+  consumer of `event.type` to break.** `constructEvent` has never once returned
+  successfully for a real delivery, so no `event.type` branch has ever executed
+  in production. Any handler you have written behind it is unreachable code
+  today. `event.type` is now a compile error precisely so `tsc` points you at
+  every site that needs the one-word edit; nothing changes at runtime for code
+  that was previously working, because there was none.
+
+  `WebhookSignatureError["reason"]` gains the `"malformed_payload"` member. An
+  exhaustive `switch` over `reason` will need the new arm.
+
+### Added
+
+- **`CurviateEventEnvelope`**: the per-delivery metadata now carried on every
+  event. `event.id` is the `wdl_…` delivery id (de-duplicate retries on it),
+  `event.webhook_id` is the registration, `event.delivered_at` is the attempt
+  timestamp. These are typed optional and are **not** required by the parser:
+  requiring an envelope field is what caused this defect, so nothing beyond the
+  discriminant can fail a verification again.
+
+- Forward compatibility: a payload carrying `type` instead of `event` is
+  accepted and normalized onto `event`, so a future platform-side change to the
+  envelope cannot break verification a second time. `type` is never required.
+
+- `test/webhooks.dispatcherEnvelope.test.ts` and
+  `test/fixtures/webhook-delivery.capture.json`: the regression test replays
+  bytes and a signature header **captured off the wire from the real dispatch
+  worker**, rather than constructing its own payload. The pre-existing suite was
+  green throughout this defect because it built its own `{ type: … }` fixtures;
+  a suite that constructs its own input cannot detect an emitter/parser
+  divergence, and that is what let this ship.
+
 ## [0.18.1] — 2026-07-18
 
 ### Changed

package/README.md

@@ -1,9 +1,9 @@
 # @curviate/sdk
 
-The official TypeScript SDK for the [Curviate API](https://docs.curviate.com) — agent-native
+The official TypeScript SDK for the [Curviate API](https://docs.curviate.com). Agent-native
 LinkedIn infrastructure for AI engineers and agent builders.
 
-> **Status:** `0.16.0` — pre-1.0. Full v2 API parity; the surface is public but not yet stability-promised.
+> **Status:** pre-1.0. Full v2 API parity; the surface is public but not yet stability-promised.
 
 ---
 
@@ -17,7 +17,7 @@ Requires Node 18+. Works in Cloudflare Workers and Vercel Edge.
 
 ---
 
-## Auth — construct the client
+## Auth: construct the client
 
 Get your API key from the Curviate dashboard. Store it as an environment variable.
 
@@ -37,7 +37,7 @@ const curviate = new Curviate({
 
 ## Account-scoped accessor
 
-Every LinkedIn operation (messages, member profiles, invites, posts) is tied to a **managed account** — a LinkedIn session you have connected via the connect flow (`curviate.auth.intent()`). The `curviate.account(id)` accessor fixes the `account_id` on every call so you do not have to thread it manually:
+Every LinkedIn operation (messages, member profiles, invites, posts) is tied to a **managed account**, a LinkedIn session you have connected via the connect flow (`curviate.auth.intent()`). The `curviate.account(id)` accessor fixes the `account_id` on every call so you do not have to thread it manually:
 
 ```ts
 // Root-level: tenant-wide operations (accounts, auth, webhooks)
@@ -56,7 +56,7 @@ const profile = await acc.users.get("some-user-id"); // someone else's
 
 ## First end-to-end call
 
-This snippet lists your connected accounts, picks the first one, and sends a message — something an agent might do to automate outreach:
+This snippet lists your connected accounts, picks the first one, and sends a message, something an agent might do to automate outreach:
 
 ```ts
 import { Curviate, isCurviateError } from "@curviate/sdk";
@@ -78,7 +78,7 @@ async function sendFirstMessage() {
   // 3. Send a message to the first chat
   const chat = chats[0]!;
   await acc.messaging.sendMessage(chat.id ?? "", {
-    text: "Hi — following up from our conversation.",
+    text: "Hi, following up from our conversation.",
   });
 
   console.log("Message sent.");
@@ -114,7 +114,7 @@ try {
       break;
     default:
       if (err.retryLikelyToSucceed) {
-        // Safe to retry — server-side transient error
+        // Safe to retry: server-side transient error
         await retry();
       }
   }
@@ -127,7 +127,7 @@ All 34 error codes are documented in the [API reference](https://docs.curviate.c
 
 ## Cursor pagination
 
-Resources that return lists support cursor pagination. `curviate.paginate()` is an async iterator that follows the `cursor` field automatically — pull items one at a time without managing cursors:
+Resources that return lists support cursor pagination. `curviate.paginate()` is an async iterator that follows the `cursor` field automatically, so you pull items one at a time without managing cursors:
 
 ```ts
 // Iterate over every chat across all pages
@@ -163,27 +163,28 @@ app.post("/webhook", express.raw({ type: "application/json" }), async (req, res)
     event = await constructEvent(req.body, sig, secret);
   } catch (err) {
     if (err instanceof WebhookSignatureError) {
-      console.warn("Bad webhook:", err.reason); // 'invalid_signature' | 'replay_detected' | 'malformed_header'
+      // 'invalid_signature' | 'replay_detected' | 'malformed_header' | 'malformed_payload'
+      console.warn("Bad webhook:", err.reason);
       return res.sendStatus(400);
     }
     throw err;
   }
 
-  switch (event.type) {
+  switch (event.event) {
     case "message.received":
-      // event.data is MessagePayload — account_id, message_id, etc.
+      // event.data is MessagePayload: account_id, message_id, and so on.
       handleNewMessage(event.data);
       break;
     case "account.connected":
       handleAccountConnected(event.data);
       break;
-    // 22 more event types — all in the CurviateEvent union
+    // 22 more event types, all in the CurviateEvent union.
   }
 
   res.sendStatus(200);
 });
 
-// Hono / Vercel Edge — always await (Web Crypto is async)
+// 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("curviate-signature")!, secret);
@@ -191,16 +192,28 @@ app.post("/webhook", async (c) => {
 });
 ```
 
-`constructEvent` always returns a `Promise<CurviateEvent>` — always `await` it.
+`constructEvent` always returns a `Promise<CurviateEvent>`. Always `await` it.
 
-`WebhookSignatureError` is NOT a `CurviateError` — narrow with `instanceof WebhookSignatureError`.
+Each event also carries its delivery metadata: `event.id` (a `wdl_` delivery id you
+can de-duplicate retries on), `event.webhook_id`, and `event.delivered_at`.
+
+`WebhookSignatureError` is NOT a `CurviateError`. Narrow with `instanceof WebhookSignatureError`.
+Its `reason` tells you where to look: `malformed_header` means the signature header could not be
+read, `invalid_signature` means the HMAC did not match (check the secret, and check that you passed
+the raw request bytes), `replay_detected` means the event is outside the replay window, and
+`malformed_payload` means the signature was **valid** but the body was not a Curviate event, so
+your secret and header are both fine.
+
+> **Upgrading from 0.18.x or earlier?** The event discriminant is `event.event`, not `event.type`.
+> See the 0.19.0 entry in [CHANGELOG.md](./CHANGELOG.md); the change is a one-word edit and it
+> breaks no working code, because `constructEvent` never returned successfully before 0.19.0.
 
 ---
 
 ## Links
 
 - API reference: https://docs.curviate.com
-- Issues: https://github.com/curviate/sdk/issues
+- Issues: https://github.com/curviate/curviate-sdk/issues
 - Changelog: [CHANGELOG.md](./CHANGELOG.md)
 
 ## License

package/dist/index.d.ts

@@ -29211,6 +29211,20 @@ declare function isCurviateError(err: unknown): err is CurviateError;
  * Extends `Error`, NOT `CurviateError` — callers can narrow with
  * `instanceof WebhookSignatureError` independently of CurviateError.
  *
+ * The `reason` codes split by where the problem actually is, so the code you
+ * read points at the thing you need to look at:
+ *
+ * - `malformed_header` - the `Curviate-Signature` header itself is unusable
+ *   (missing `t=` or `v1=`, non-numeric timestamp). Check how you are reading
+ *   the header.
+ * - `invalid_signature` - the header parsed, but the HMAC does not match.
+ *   Check the signing secret, and check that you passed the raw request bytes
+ *   rather than a re-serialized object.
+ * - `replay_detected` - signature valid, timestamp outside the replay window.
+ * - `malformed_payload` - **signature valid**, but the body is not a Curviate
+ *   event. Nothing is wrong with your secret or your header; look at what is
+ *   POSTing to the endpoint.
+ *
  * @example
  * try {
  *   const event = await constructEvent(rawBody, header, secret);
@@ -29223,7 +29237,7 @@ declare function isCurviateError(err: unknown): err is CurviateError;
 declare class WebhookSignatureError extends Error {
     readonly name = "WebhookSignatureError";
     /** Structured reason code for the verification failure. */
-    readonly reason: "invalid_signature" | "replay_detected" | "malformed_header";
+    readonly reason: "invalid_signature" | "replay_detected" | "malformed_header" | "malformed_payload";
     constructor(reason: WebhookSignatureError["reason"], message: string);
 }
 /**
@@ -29248,9 +29262,34 @@ interface AccountPayload {
     account_id: string;
     [key: string]: unknown;
 }
+/**
+ * Delivery metadata that accompanies every Curviate webhook event.
+ *
+ * These fields are present on every delivery the platform sends, but
+ * `constructEvent` does **not** require them: the parser insists only on the
+ * discriminant. That is deliberate. Requiring an envelope field is exactly how
+ * verification broke before (the parser demanded a field the emitter did not
+ * send, and rejected every genuine delivery), so anything the union does not
+ * strictly need to narrow is optional here and cannot fail a verification.
+ */
+interface CurviateEventEnvelope {
+    /** Unique id for this delivery attempt, e.g. `wdl_01J...`. Use it to de-duplicate retries. */
+    id?: string;
+    /** Id of the webhook registration this delivery belongs to, e.g. `wh_01J...`. */
+    webhook_id?: string;
+    /** ISO-8601 timestamp of the delivery attempt. */
+    delivered_at?: string;
+}
 /**
  * The complete discriminated union of all 24 canonical, create-subscribable
- * Curviate webhook events. The `type` field is the discriminant.
+ * Curviate webhook events. The **`event`** field is the discriminant, matching
+ * the field the platform actually sends on the wire.
+ *
+ * > Migrating from 0.18.x and earlier: the discriminant was `type`, a field no
+ * > Curviate delivery has ever contained, so `constructEvent` threw on every
+ * > real webhook and no `event.type` branch could ever run. Switch your checks
+ * > to `event.event === '...'`. `event.type` is now a compile error, which is
+ * > intentional: it points at every site that needs the one-word change.
  *
  * Re-keyed for the v2 catalogue (was 19). Renamed/removed vs. the prior set:
  * `account.stopped`, `account.sync_started`, `account.sync_complete`,
@@ -29265,83 +29304,83 @@ interface AccountPayload {
  *
  * @example
  * const event = await constructEvent(rawBody, header, secret);
- * if (event.type === 'message.received') {
+ * if (event.event === 'message.received') {
  *   // event.data is MessagePayload
  * }
  */
-type CurviateEvent = {
-    type: "message.received";
+type CurviateEvent = CurviateEventEnvelope & ({
+    event: "message.received";
     data: MessagePayload;
 } | {
-    type: "message.delivered";
+    event: "message.delivered";
     data: MessagePayload;
 } | {
-    type: "message.read";
+    event: "message.read";
     data: MessagePayload;
 } | {
-    type: "message.edited";
+    event: "message.edited";
     data: MessagePayload;
 } | {
-    type: "message.deleted";
+    event: "message.deleted";
     data: MessagePayload;
 } | {
-    type: "message.reaction";
+    event: "message.reaction";
     data: MessagePayload;
 } | {
-    type: "chat.updated";
+    event: "chat.updated";
     data: MessagePayload;
 } | {
-    type: "chat.deleted";
+    event: "chat.deleted";
     data: MessagePayload;
 } | {
-    type: "connection.accepted";
+    event: "connection.accepted";
     data: ConnectionPayload;
 } | {
-    type: "connection.new";
+    event: "connection.new";
     data: ConnectionPayload;
 } | {
-    type: "account.created";
+    event: "account.created";
     data: AccountPayload;
 } | {
-    type: "account.connected";
+    event: "account.connected";
     data: AccountPayload;
 } | {
-    type: "account.synced";
+    event: "account.synced";
     data: AccountPayload;
 } | {
-    type: "account.reconnected";
+    event: "account.reconnected";
     data: AccountPayload;
 } | {
-    type: "account.reconnect_needed";
+    event: "account.reconnect_needed";
     data: AccountPayload;
 } | {
-    type: "account.creation_failed";
+    event: "account.creation_failed";
     data: AccountPayload;
 } | {
-    type: "account.disconnected";
+    event: "account.disconnected";
     data: AccountPayload;
 } | {
-    type: "account.error";
+    event: "account.error";
     data: AccountPayload;
 } | {
-    type: "account.paused";
+    event: "account.paused";
     data: AccountPayload;
 } | {
-    type: "account.connecting";
+    event: "account.connecting";
     data: AccountPayload;
 } | {
-    type: "account.permission_revoked";
+    event: "account.permission_revoked";
     data: AccountPayload;
 } | {
-    type: "account.initial_sync.running";
+    event: "account.initial_sync.running";
     data: AccountPayload;
 } | {
-    type: "account.initial_sync.completed";
+    event: "account.initial_sync.completed";
     data: AccountPayload;
 } | {
-    type: "account.initial_sync.failed";
+    event: "account.initial_sync.failed";
     data: AccountPayload;
-};
+});
 /**
  * Options for {@link constructEvent}.
  */
@@ -29386,7 +29425,7 @@ interface ConstructEventOptions {
  *     }
  *     throw err;
  *   }
- *   if (event.type === 'message.received') { ... }
+ *   if (event.event === 'message.received') { ... }
  *   res.sendStatus(200);
  * });
  *
@@ -29400,4 +29439,4 @@ interface ConstructEventOptions {
  */
 declare function constructEvent(rawBody: string | Buffer, signatureHeader: string, secret: string, opts?: ConstructEventOptions): Promise<CurviateEvent>;
 
-export { type AccountListPage, type AccountListParams, type AccountPayload, type AccountScopedNamespaces, type ConnectionPayload, type ConstructEventOptions, Curviate, type CurviateConfig, CurviateError, type CurviateErrorInit, type CurviateErrorJSON, type CurviateEvent, type ErrorCode, type MessagePayload, type RequiredTier, type ResolvedConfig, type ResourceNamespaces, type RetryHint, WebhookSignatureError, type components, constructEvent, isCurviateError, type operations, type paths };
+export { type AccountListPage, type AccountListParams, type AccountPayload, type AccountScopedNamespaces, type ConnectionPayload, type ConstructEventOptions, Curviate, type CurviateConfig, CurviateError, type CurviateErrorInit, type CurviateErrorJSON, type CurviateEvent, type CurviateEventEnvelope, type ErrorCode, type MessagePayload, type RequiredTier, type ResolvedConfig, type ResourceNamespaces, type RetryHint, WebhookSignatureError, type components, constructEvent, isCurviateError, type operations, type paths };

package/dist/index.js

@@ -2684,12 +2684,27 @@ function verifyAndParse(computedHex, v1, timestamp, bodyStr, replayWindowSecs) {
   try {
     parsed = JSON.parse(bodyStr);
   } catch {
-    throw new WebhookSignatureError("malformed_header", "Webhook body is not valid JSON.");
+    throw new WebhookSignatureError(
+      "malformed_payload",
+      "Webhook body is not valid JSON. Verification already succeeded, so the problem is the request body, not your webhook configuration."
+    );
   }
-  if (typeof parsed !== "object" || parsed === null || typeof parsed["type"] !== "string") {
-    throw new WebhookSignatureError("malformed_header", 'Webhook payload missing "type" field.');
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new WebhookSignatureError(
+      "malformed_payload",
+      "Webhook body is not a JSON object. Verification already succeeded, so the problem is the request body, not your webhook configuration."
+    );
+  }
+  const record = parsed;
+  const discriminant = typeof record["event"] === "string" ? record["event"] : typeof record["type"] === "string" ? record["type"] : void 0;
+  if (discriminant === void 0) {
+    throw new WebhookSignatureError(
+      "malformed_payload",
+      'Webhook body has no "event" field, so it cannot be resolved to a Curviate event. Verification already succeeded, so the problem is the request body, not your webhook configuration.'
+    );
   }
-  return parsed;
+  record["event"] = discriminant;
+  return record;
 }
 async function constructEvent(rawBody, signatureHeader, secret, opts) {
   const replayWindowSecs = opts?.replayWindowSecs ?? 300;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curviate/sdk",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "private": false,
   "description": "TypeScript SDK for the Curviate API.",
   "license": "MIT",
@@ -8,10 +8,10 @@
   "homepage": "https://docs.curviate.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/curviate/sdk.git"
+    "url": "git+https://github.com/curviate/curviate-sdk.git"
   },
   "bugs": {
-    "url": "https://github.com/curviate/sdk/issues"
+    "url": "https://github.com/curviate/curviate-sdk/issues"
   },
   "publishConfig": {
     "access": "public"