@canopy-io/node 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @canopy-io/node
 
+## 0.3.6
+
+### Patch Changes
+
+- 0708712: Typed webhook deliveries.
+
+  - Canopy now publishes a schema per webhook event, and the types are regenerated from it: 37 `Webhook…Event` schemas on the shared envelope, plus `payload_schema` and `resource_types` on `GET /api/v1/webhooks/event-types`. No operation was added or removed.
+  - New `WebhookDelivery`, `WebhookEventName`, `WebhookEvent<Name>` and `WebhookEventData<Name>` types, and an `isWebhookEvent(delivery, name)` guard, so a handler reads one event's `metadata` without a cast.
+  - `metadata` is now always an object on every delivery.
+
 ## 0.3.5
 
 ### Patch Changes

package/README.md

@@ -169,6 +169,32 @@ const { token, base_url } = await canopy.organizations.mintDirectoryToken(
 );
 ```
 
+### Handling webhooks
+
+Every webhook event has a published schema, and the SDK types deliveries from
+it. Narrow by event name and read that event's `metadata` without a cast; a
+field the API adds arrives with the next `npm run generate`.
+
+```ts
+import { isWebhookEvent, type WebhookDelivery } from "@canopy-io/node";
+
+app.post("/webhooks/canopy", (req, res) => {
+  const delivery = req.body as WebhookDelivery;
+
+  if (isWebhookEvent(delivery, "organization.member.added")) {
+    const { identity_id, role_id } = delivery.data.metadata;
+    // ...
+  }
+
+  res.sendStatus(204);
+});
+```
+
+`WebhookEvent<"assignment.updated">` is the delivery of one event, and
+`WebhookEventName` is every event a subscription can receive. The API's
+`GET /api/v1/webhooks/event-types` names each event's schema in
+`payload_schema`.
+
 ### Authorizing without a call per request
 
 Asking "may this identity act _here_" on every request puts Canopy in your

package/dist/index.cjs

@@ -1606,6 +1606,11 @@ var TokenVerifier = class {
   }
 };
 
+// src/webhooks.ts
+function isWebhookEvent(delivery, name) {
+  return delivery.event === name;
+}
+
 exports.Assignments = Assignments;
 exports.Canopy = Canopy;
 exports.CanopyAuthorizerError = CanopyAuthorizerError;
@@ -1625,6 +1630,7 @@ exports.isCanopyConnectionError = isCanopyConnectionError;
 exports.isCanopyError = isCanopyError;
 exports.isCanopyTokenError = isCanopyTokenError;
 exports.isCursorPagination = isCursorPagination;
+exports.isWebhookEvent = isWebhookEvent;
 exports.orgContext = orgContext;
 exports.paginate = paginate;
 exports.withConcurrency = withConcurrency;