@canopy-io/node 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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
+
+- bd5a478: Set up an organization's directory sync (SCIM) from your backend.
+
+  - `organizations.setDirectoryGrantableRoles` and `listDirectoryGrantableRoles` wrap the two new operations, `PUT`/`GET /api/v1/organizations/{id}/directory/grantable-roles`. Naming the roles an organization's identity provider may grant, and the one people arrive with, is what opens directory sync for it. Only your API key can set the list; an organization admin's token can read it and is refused changing it.
+  - The rest of an organization's directory is wrapped too: `getDirectory`, `createDirectory`, `removeDirectory`, `listDirectoryTokens`, `mintDirectoryToken`, `rotateDirectoryToken`, `revokeDirectoryToken`, `listDirectoryActivity`, `listDirectoryGroups`, `mapDirectoryGroup` and `unmapDirectoryGroup`. They were already typed and reachable through `client.request`.
+  - `base_url` on a directory and on a minted token is now the full URL, including the host, so it can be handed to a customer as it is. If you were putting your API host in front of it, stop.
+
+  The published spec gained 2 operations (132 to 134), both additive, so this is a patch.
+
 ## 0.3.4
 
 ### Patch Changes

package/README.md

@@ -136,8 +136,8 @@ plus `mfa` once a second factor was verified), so a backend can insist on
 `claims.amr?.includes("mfa")` before a sensitive action.
 
 The organizations themselves are wrapped on the client: provision a tenant,
-manage its members and invitations, tighten its sign-in policy, and bind its
-identity provider.
+manage its members and invitations, tighten its sign-in policy, bind its
+identity provider, and set up its directory sync.
 
 ```ts
 const acme = await canopy.organizations.create({ name: "Acme Corp" });
@@ -150,6 +150,51 @@ await canopy.organizations.addMember(acme.id, {
 await canopy.organizations.updatePolicy(acme.id, { mfa_required: true });
 ```
 
+Directory sync (SCIM) opens when you name the roles an organization's identity
+provider may grant; the organization's own admin can read that list but not
+change it. The token is returned once, with the full base URL its connector
+needs.
+
+```ts
+await canopy.organizations.setDirectoryGrantableRoles(acme.id, {
+  role_ids: [memberRoleId, leadRoleId],
+  default_role_id: memberRoleId,
+});
+
+await canopy.organizations.createDirectory(acme.id);
+
+const { token, base_url } = await canopy.organizations.mintDirectoryToken(
+  acme.id,
+  { name: "Okta" },
+);
+```
+
+### 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

@@ -770,6 +770,127 @@ var Organizations = class {
       `/api/v1/organizations/${enc(id)}/sso-connections/${enc(connectionId)}`
     );
   }
+  // ── Directory sync: the organization's own SCIM connection ──
+  /**
+   * The roles this organization's identity provider may grant, and the one
+   * people arrive with. An empty list means directory sync is not open for
+   * the organization.
+   */
+  listDirectoryGrantableRoles(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/directory/grantable-roles`
+    );
+  }
+  /**
+   * Replace the list in one act, which is how directory sync is opened for
+   * an organization. Exactly one role is `default_role_id`, the one people
+   * arrive with. Withdrawing a role unmaps the groups naming it and keeps
+   * their members in the organization; an empty list is refused while a
+   * directory is connected. Your API key only: an organization admin's
+   * token can read the list but is refused changing it.
+   */
+  setDirectoryGrantableRoles(id, input) {
+    return this.client.request(
+      "PUT",
+      `/api/v1/organizations/${enc(id)}/directory/grantable-roles`,
+      { body: input }
+    );
+  }
+  /**
+   * The organization's directory, its full SCIM base URL, and the roles it
+   * may grant. `id` is null until a directory is connected.
+   */
+  getDirectory(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/directory`
+    );
+  }
+  /** Connect a directory. Refused until the organization's roles are set. */
+  createDirectory(id) {
+    return this.client.request(
+      "POST",
+      `/api/v1/organizations/${enc(id)}/directory`
+    );
+  }
+  /**
+   * End the connection. The people it provisioned keep their accounts and
+   * their membership; what ends is the provider's ability to push.
+   */
+  removeDirectory(id) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}/directory`
+    );
+  }
+  listDirectoryTokens(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/directory/tokens`
+    );
+  }
+  /**
+   * The raw token is in this answer and nowhere else, alongside the full
+   * base URL the identity provider's connector needs with it.
+   */
+  mintDirectoryToken(id, input = {}) {
+    return this.client.request(
+      "POST",
+      `/api/v1/organizations/${enc(id)}/directory/tokens`,
+      { body: input }
+    );
+  }
+  /**
+   * A replacement token, shown once. The old one keeps working for a short
+   * overlap, so the provider can be moved across without an outage.
+   */
+  rotateDirectoryToken(id, tokenId, input = {}) {
+    return this.client.request(
+      "POST",
+      `/api/v1/organizations/${enc(id)}/directory/tokens/${enc(tokenId)}/rotate`,
+      { body: input }
+    );
+  }
+  revokeDirectoryToken(id, tokenId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}/directory/tokens/${enc(tokenId)}`
+    );
+  }
+  /** The organization's own provisioning events, newest first. */
+  listDirectoryActivity(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/directory/activity`
+    );
+  }
+  /** The groups the provider has pushed, each with its role mapping. */
+  listDirectoryGroups(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/directory/groups`
+    );
+  }
+  /**
+   * Grant a listed role to every member of a pushed group, at the
+   * organization. A role not on the organization's list is refused with
+   * `scim.role_not_grantable`.
+   */
+  mapDirectoryGroup(id, groupId, input) {
+    return this.client.request(
+      "PUT",
+      `/api/v1/organizations/${enc(id)}/directory/groups/${enc(groupId)}/mapping`,
+      { body: input }
+    );
+  }
+  /** Members fall back to the arrival role and stay in the organization. */
+  unmapDirectoryGroup(id, groupId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}/directory/groups/${enc(groupId)}/mapping`
+    );
+  }
 };
 function enc(segment) {
   return encodeURIComponent(segment);
@@ -1485,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;
@@ -1504,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;