@usethrottle/webhook-types 1.0.0 → 1.0.1

package/README.md

@@ -10,39 +10,46 @@ npm install @usethrottle/webhook-types
 
 ```ts
 import {
-  type WebhookEnvelope,
+  type ThrottleEvent,
+  type ThrottleEventEnvelope,
   verifyWebhookSignature,
 } from '@usethrottle/webhook-types';
 
 export async function POST(req: Request) {
   const rawBody = await req.text();
   const ok = verifyWebhookSignature({
-    header: req.headers.get('throttle-signature')!,
+    header: req.headers.get('X-Throttle-Signature')!,
     rawBody,
     secret: process.env.THROTTLE_WEBHOOK_SECRET!,
   });
   if (!ok) return new Response('bad signature', { status: 400 });
 
-  const envelope = JSON.parse(rawBody) as WebhookEnvelope;
-  const { event } = envelope;
+  const envelope = JSON.parse(rawBody) as ThrottleEvent;
+  const wireEnvelope: ThrottleEventEnvelope = envelope;
+  await audit.record({
+    eventId: wireEnvelope.id,
+    eventType: wireEnvelope.type,
+    eventVersion: wireEnvelope.version,
+    environmentId: wireEnvelope.environmentId,
+  });
 
-  // event.data is narrowed by event.type — no casts.
-  switch (event.type) {
+  // envelope.data is narrowed by envelope.type — no casts.
+  switch (envelope.type) {
     case 'cart.item_added':
-      // event.data: { cartId, sequence, itemId, name, quantity, unitPrice }
-      analytics.track('item_added', event.data);
+      // envelope.data: { cartId, sequence, itemId, name, quantity, unitPrice }
+      analytics.track('item_added', envelope.data);
       break;
     case 'order.created':
-      // event.data: { order, fromCart?, sessionId? }
-      await fulfill(event.data.order as { id: string });
+      // envelope.data: { order, fromCart?, sessionId? }
+      await fulfill(envelope.data.order as { id: string });
       break;
     case 'payment.disputed':
-      // event.data: { paymentId, reason, openedAt }
-      await ops.alert(event.data.paymentId, event.data.reason);
+      // envelope.data: { paymentId, reason, openedAt }
+      await ops.alert(envelope.data.paymentId, envelope.data.reason);
       break;
     case 'workspace.payment_method.backup_used':
-      // event.data: { workspace, primaryPaymentMethod, backupPaymentMethod, charge }
-      await notifyOps('backup PM used', event.data);
+      // envelope.data: { workspace, primaryPaymentMethod, backupPaymentMethod, charge }
+      await notifyOps('backup PM used', envelope.data);
       break;
   }
 
@@ -52,7 +59,9 @@ export async function POST(req: Request) {
 
 ## Coverage
 
-- **WebhookEvent** — discriminated union covering all 65 outbound event types currently emitted by the Throttle outbound bus (cart, order, payment, fulfillment, subscription, discount, customer, invoice, shipping/tax, workspace lifecycle).
+- **ThrottleEventEnvelope** — top-level wire envelope with `id`, `type`, `version`, `workspaceId`, `environmentId`, `createdAt`, and typed `data`.
+- **ThrottleEvent** — discriminated union of all `ThrottleEventEnvelope` variants currently emitted by the Throttle outbound bus (cart, order, payment, fulfillment, subscription, discount, customer, invoice, shipping/tax, workspace lifecycle).
+- **WebhookEvent** — legacy nested event union retained for internal/back-compat consumers.
 - **WebhookEventType** — `WebhookEvent['type']`; use it to constrain switch statements or event-name handlers.
 - **Typed payloads** — primitive fields (ids, amounts, codes, timestamps) are fully typed. Embedded domain objects (`order`, `payment`, `subscription`, `workspace`, etc.) are typed as `Record<string, unknown>` because the canonical schemas live in the API server and shouldn't be duplicated here. Cast through the OpenAPI client (`@usethrottle/api-client`) for the embedded shapes.
 - **verifyWebhookSignature** — Stripe-compatible `t=…,v1=…` header parsing with timing-safe HMAC-SHA256 comparison + 5-minute replay window by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/webhook-types",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "TypeScript discriminated unions for every Throttle outbound webhook event.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,21 +10,21 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "tsc --noEmit && vitest run --passWithNoTests"
-  },
   "devDependencies": {
-    "@core/scopes": "workspace:*",
     "@types/node": "^20.0.0",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "@core/scopes": "0.0.1"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsc --noEmit && vitest run --passWithNoTests"
   }
-}
+}