@shuffl/sdk 0.3.0 → 0.5.0

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';
@@ -33,7 +33,7 @@ const preview = await shuffl.programs.preview({
 
 `users` means people in the team directory, including people who have no web login. IDs are Shuffl person IDs, not Slack IDs or authentication account IDs.
 
-The client includes people and their profiles, teams and departments, access, identity links, programs and runs, Knowledge, invitations, People sync, onboarding and first 90 days check-ins, celebrations, Pulse, Praise, badges, communities, reminders, Home, the HR digest, HR requests, support, reports, exports, credentials and assistant conversations. Company settings and billing are not in the API: a team key never gains company scope. See the [permission reference](https://shuffl-rebuild.vercel.app/docs/api-permissions) for every method. Input and output types come directly from the portable public oRPC contract.
+The client includes people and their profiles, teams and departments, access, identity links, programs and runs, Knowledge, invitations, People sync, onboarding and first 90 days check-ins, celebrations, Pulse, Praise, badges, communities, reminders, Home, the HR digest, HR requests, support, reports, exports, credentials and assistant conversations. A team key never gains company scope; company settings have their own client and key, below. See the [permission reference](https://shuffl-rebuild.vercel.app/docs/api-permissions) for every method. Input and output types come directly from the portable public oRPC contract.
 
 Program creation requires a stable `requestKey`. Repeating the same creation request returns the existing program; using that key with different settings returns `CONFLICT`. Programs start paused unless `draft: false` is explicitly supplied. Updates require `expectedRevision`. Run requests require a preview and request key and return a durable run ID; poll `runs.get` for status. The application scheduler owns execution and delivery.
 
@@ -45,19 +45,65 @@ 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.
 
 Credentials with `credentials:write` can delegate only their own scopes, with bounded expiry and inherited revocation. Account sign-in, switching to another team, provider consent and payment confirmation remain explicit browser/account flows.
 
+## Company settings
+
+A company key (`shuffl_company_`), created by a company owner or administrator in **Company settings → API keys**, manages one company's settings and never reaches a workspace. `createShufflCompany` takes it and calls the REST operations under `/api/v1/company`:
+
+```ts
+import { createShufflCompany } from '@shuffl/sdk';
+
+const company = createShufflCompany({
+  baseUrl: process.env.SHUFFL_BASE_URL!,
+  token: process.env.SHUFFL_COMPANY_KEY!,
+});
+
+const { permissions } = await company.current(); // Any company key.
+const page = await company.members.list({ limit: 100 });
+await company.members.remove({ userId: page.items[0]!.userId });
+```
+
+`company.current()` returns the key's company and grants. Every other method needs its grant: `company.details`, `company.workspaces.list`, `company.members.list`, `company.emailDomains.list`, `company.slack.list`, `company.rename`, `company.workspaces.setDefault` and `company.members.remove`. `members.list` pages with `limit` and `cursor` like `users.list`. Company writes run once when called and take no `requestKey`. A company key can't call `createShuffl` methods, and a workspace key can't call these. See [company keys](https://shuffl-rebuild.vercel.app/docs/api-permissions#company-keys).
+
 Full guide: [Use the SDK and HTTP API](https://shuffl-rebuild.vercel.app/docs/sdk).

package/dist/index.d.ts

@@ -1,12 +1,24 @@
-import type { ContractRouterClient } from '@orpc/contract';
+import { type ContractRouterClient } from '@orpc/contract';
 import type { ShufflContract } from '@shuffl/api-contracts';
+import { type ShufflCompanyContract } from '@shuffl/api-contracts/company';
 export { ORPCError } from '@orpc/client';
-export type { Permission, PermissionDefinition, Scope, } from '@shuffl/api-contracts';
+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>;
 export interface ShufflOptions {
     token: string | (() => string | Promise<string>);
     /** Shuffl application origin, without /api/v1/rpc. */
     baseUrl: string;
     fetch?: typeof globalThis.fetch;
 }
+/** A client for workspace operations, with a workspace key (shuffl_api_). */
 export declare function createShuffl(options: ShufflOptions): ShufflClient;
+/**
+ * A client for the company API, with a company key (shuffl_company_) from
+ * Company settings → API keys. It calls the REST operations under
+ * /api/v1/company: `company.members.list({ limit: 100 })`. A company key
+ * never reaches workspace operations, and a workspace key never reaches these.
+ */
+export declare function createShufflCompany(options: ShufflOptions): ShufflCompanyClient;

package/dist/index.js

@@ -1,23 +1,97 @@
-import { createORPCClient } from '@orpc/client';
+import { createORPCClient, ORPCError } from '@orpc/client';
 import { RPCLink } from '@orpc/client/fetch';
+import { isContractProcedure } from '@orpc/contract';
+import { companyContract, } from '@shuffl/api-contracts/company';
 export { ORPCError } from '@orpc/client';
-export function createShuffl(options) {
-    const base = new URL(options.baseUrl);
+// #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 ||
         base.password ||
         (base.protocol !== 'https:' &&
             !(base.protocol === 'http:' &&
                 ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname))))
         throw new Error('Use HTTPS, or HTTP on localhost for development.');
+    return base;
+}
+const bearer = async (token) => `Bearer ${typeof token === 'function' ? await token() : token}`;
+/** A client for workspace operations, with a workspace key (shuffl_api_). */
+export function createShuffl(options) {
+    const base = origin(options.baseUrl);
     return createORPCClient(new RPCLink({
         // Writes are not automatically retried. Callers own stable request keys.
         fetch: async (request, init) => (options.fetch ?? globalThis.fetch)(request, {
             ...init,
             redirect: 'error',
         }),
-        headers: async () => ({
-            authorization: `Bearer ${typeof options.token === 'function' ? await options.token() : options.token}`,
-        }),
+        headers: async () => ({ authorization: await bearer(options.token) }),
         url: new URL('/api/v1/rpc', base).toString(),
     }));
 }
+const statusCodes = {
+    400: 'BAD_REQUEST',
+    401: 'UNAUTHORIZED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    405: 'METHOD_NOT_SUPPORTED',
+    409: 'CONFLICT',
+    429: 'TOO_MANY_REQUESTS',
+};
+/**
+ * A client for the company API, with a company key (shuffl_company_) from
+ * Company settings → API keys. It calls the REST operations under
+ * /api/v1/company: `company.members.list({ limit: 100 })`. A company key
+ * never reaches workspace operations, and a workspace key never reaches these.
+ */
+export function createShufflCompany(options) {
+    const base = origin(options.baseUrl);
+    const procedure = ({ method, path }) => async (input, call) => {
+        const url = new URL(`/api/v1${path}`, base);
+        const read = method === 'GET';
+        if (read)
+            for (const [key, value] of Object.entries(input ?? {}))
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+        const response = await (options.fetch ?? globalThis.fetch)(url, {
+            body: read ? undefined : JSON.stringify(input ?? {}),
+            headers: {
+                accept: 'application/json',
+                authorization: await bearer(options.token),
+                ...(read ? {} : { 'content-type': 'application/json' }),
+            },
+            method,
+            redirect: 'error',
+            signal: call?.signal,
+        });
+        const text = await response.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = undefined;
+        }
+        if (!response.ok) {
+            const error = (body ?? {});
+            throw new ORPCError(typeof error.code === 'string'
+                ? error.code
+                : (statusCodes[response.status] ?? 'INTERNAL_SERVER_ERROR'), {
+                message: typeof error.message === 'string'
+                    ? error.message
+                    : `Shuffl answered ${response.status}.`,
+                status: response.status,
+            });
+        }
+        if (body === undefined)
+            throw new ORPCError('INTERNAL_SERVER_ERROR', {
+                message: 'Shuffl returned a response that is not JSON.',
+                status: response.status,
+            });
+        return body;
+    };
+    const build = (node) => isContractProcedure(node)
+        ? procedure(node['~orpc'].route)
+        : Object.fromEntries(Object.entries(node).map(([key, value]) => [key, build(value)]));
+    return build(companyContract);
+}

package/package.json

@@ -2,7 +2,7 @@
   "dependencies": {
     "@orpc/client": "1.15.3",
     "@orpc/contract": "1.15.3",
-    "@shuffl/api-contracts": "0.3.0"
+    "@shuffl/api-contracts": "0.5.0"
   },
   "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.3.0"
+  "version": "0.5.0"
 }