@shuffl/sdk 0.4.0 → 0.5.1

package/README.md

@@ -10,7 +10,7 @@ The package is ESM-only and ships its own types. It installs `@shuffl/api-contra
 
 Create an API key in **Settings → API keys**. The key is bound to one team and the issuing user's current permissions, and expires within 30 days. There is one kind of API key: the same key works for the SDK, CLI, HTTP API and, when it carries the `mcp.knowledge` permission, the MCP server.
 
-Choose exact endpoint permissions such as `users.list` and `units.save`, grouped by resource and Read/Write. Discover them with `shuffl.permissions.list()`. A write grant does not imply reads or sibling operations. See [endpoint permissions and delegation](https://shuffl-rebuild.vercel.app/docs/api-permissions).
+Choose exact endpoint permissions such as `users.list` and `groups.save`, grouped by resource and Read/Write. Discover them with `shuffl.permissions.list()`. A write grant does not imply reads or sibling operations. See [endpoint permissions and delegation](https://shuffl-rebuild.vercel.app/docs/api-permissions).
 
 ```ts
 import { createShuffl } from '@shuffl/sdk';
@@ -45,15 +45,42 @@ createShuffl({ baseUrl, token: async () => credentialStore.read() });
 
 Use `ORPCError.code` for errors (`UNAUTHORIZED`, `FORBIDDEN`, `BAD_REQUEST`, `NOT_FOUND`, `CONFLICT`, and others). Calls accept oRPC's second options argument, including an abort signal. HTTPS is required except on loopback; redirects are refused to avoid forwarding credentials to another origin. The public API currently allows same-origin browser calls and server/CLI clients; cross-origin browser CORS is not enabled.
 
+## Webhooks
+
+Shuffl can call your HTTPS endpoint when something happens in a workspace (#643). Add an endpoint in Settings → Webhooks or with `webhooks.create`, keep the `whsec_…` signing secret it returns, and check every delivery against it before you trust it. Pass the raw body, before any JSON parsing:
+
+```ts
+import { verifyWebhook, WebhookVerificationError } from '@shuffl/sdk';
+
+export async function POST(request: Request) {
+  const body = await request.text();
+  try {
+    const event = await verifyWebhook({
+      body,
+      headers: request.headers,
+      secret: process.env.SHUFFL_WEBHOOK_SECRET!,
+    });
+    if (event.type === 'knowledge.document.published')
+      console.log(event.data.document_id);
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof WebhookVerificationError)
+      return new Response('Bad signature', { status: 400 });
+    throw error;
+  }
+}
+```
+
+Deliveries follow [Standard Webhooks](https://www.standardwebhooks.com/), so their libraries for other languages work too. `event.id` stays the same across retries and resends; use it to drop duplicates. Payloads carry ids, statuses and counts only; read anything more through the API. `webhookEventCatalog` lists every event type with its group and the fields its `data` may carry. While a secret is rolled, pass both secrets as an array.
+
 ## Management commands
 
 ```ts
-const saved = await shuffl.units.save({
-  id: crypto.randomUUID(), kind: 'team', name: 'Mentors',
-  expectedRevision: 0, requestKey: 'create-mentors-2026-09',
+const saved = await shuffl.groups.save({
+  kind: 'list', name: 'Mentors', requestKey: 'create-mentors-2026-09',
 });
 const receipt = await shuffl.commands.get({ id: saved.receipt.id });
-const teams = await shuffl.units.list({}); // Same persisted teams the web app reads.
+const groups = await shuffl.groups.list({}); // Same groups the web app reads.
 ```
 
 Management writes return `{receipt, result}`. A duplicate request returns the same receipt with `result: null`; it never replays an action or a private result. Reusing a key with changed input fails. Read the resource after replay and reconcile an `unknown` receipt before issuing a new command. Sensitive actions require `confirm` equal to the method name (for example `knowledge.sources.publish`). Initial program/run methods retain the shapes described above.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import type { ShufflContract } from '@shuffl/api-contracts';
 import { type ShufflCompanyContract } from '@shuffl/api-contracts/company';
 export { ORPCError } from '@orpc/client';
 export type { CompanyPermission, Permission, PermissionDefinition, Scope, } from '@shuffl/api-contracts';
+export { isWebhookEventType, signWebhook, verifyWebhook, type WebhookActor, type WebhookEvent, type WebhookEventData, type WebhookEventGroup, type WebhookEventType, WebhookVerificationError, webhookApiVersion, webhookEventCatalog, webhookEventGroups, webhookEventTypes, } from '@shuffl/api-contracts/webhooks';
 export type ShufflClient = ContractRouterClient<ShufflContract>;
 /** The company API (#1692), for a company key (shuffl_company_). */
 export type ShufflCompanyClient = ContractRouterClient<ShufflCompanyContract>;

package/dist/index.js

@@ -3,6 +3,8 @@ import { RPCLink } from '@orpc/client/fetch';
 import { isContractProcedure } from '@orpc/contract';
 import { companyContract, } from '@shuffl/api-contracts/company';
 export { ORPCError } from '@orpc/client';
+// #643: check and type the webhooks Shuffl sends.
+export { isWebhookEventType, signWebhook, verifyWebhook, WebhookVerificationError, webhookApiVersion, webhookEventCatalog, webhookEventGroups, webhookEventTypes, } from '@shuffl/api-contracts/webhooks';
 function origin(baseUrl) {
     const base = new URL(baseUrl);
     if (base.username ||

package/package.json

@@ -2,7 +2,7 @@
   "dependencies": {
     "@orpc/client": "1.15.3",
     "@orpc/contract": "1.15.3",
-    "@shuffl/api-contracts": "0.4.0"
+    "@shuffl/api-contracts": "0.5.1"
   },
   "description": "TypeScript client for the Shuffl API: people, teams, knowledge, programs and management commands.",
   "engines": {
@@ -34,5 +34,5 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.4.0"
+  "version": "0.5.1"
 }