@shuffl/sdk 0.6.0 → 0.6.2

package/README.md

@@ -32,7 +32,17 @@ 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. A team key never gains company scope; company settings have their own key and live under `shuffl.company`, 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.
+A team key never gains company scope; company settings have their own key and live under `shuffl.company`, 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.
+
+## What the client covers
+
+- People: `users`, `profiles`, `identities`, `invitations`, `access`, `manager`, `timeOff` and `sync` (People Sync).
+- Groups: `groups` (lists, departments, synced groups, automations and their runs), `units` and `communities`.
+- Programs: `programs` and `runs` (Connections), `mentorship`, `network` (the org chart and introductions) and `playbooks` (onboarding, buddies, 30/60/90 plans and leaving).
+- Culture: `celebrations`, `pulse`, `praise`, `badges`, `reminders`, `home`, `getStarted` and `digest`.
+- Knowledge and HR: `knowledge` (pages, sources, templates, read-and-confirm and the handbook), `hr` (HR requests), `support` and `assistant`.
+- Workspace: `teams`, `team`, `channels`, `integrations`, `notifications`, `reports`, `exports` and `webhooks`.
+- Keys and receipts: `credentials`, `permissions`, `commands` and `operations`.
 
 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.
 
@@ -42,11 +52,13 @@ Dates in the public API are ISO strings. Directory lists use an opaque cursor an
 new Shuffl({ apiKey: async () => credentialStore.read() });
 ```
 
+Every request carries an `x-shuffl-client` header naming the SDK release (`shuffl-sdk/0.6.1`; the CLI adds `shuffl-cli/0.6.1`), so Shuffl can count requests by release. Pass `client: 'billing-sync/1.2.0'` to put your app's name in front; Shuffl never stores that part.
+
 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:
+Shuffl can call your HTTPS endpoint when something happens in a workspace. 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';
@@ -103,3 +115,7 @@ await shuffl.company.members.remove({ userId: page.items[0]!.userId });
 `shuffl.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 the workspace methods, and a workspace key can't call `shuffl.company`; the SDK refuses the wrong kind with `UNAUTHORIZED` before sending a request. 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).
+
+## License
+
+MIT © Shuffl LLC. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -5,7 +5,7 @@ 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_). */
+/** The company API, for a company key (shuffl_company_). */
 export type ShufflCompanyClient = ContractRouterClient<ShufflCompanyContract>;
 export interface ShufflOptions {
     /**
@@ -15,6 +15,11 @@ export interface ShufflOptions {
     apiKey: string | (() => string | Promise<string>);
     /** Shuffl application origin, without /api/v1. Defaults to production. */
     baseUrl?: string;
+    /**
+     * Your app's name and version, such as "hris-sync/2.1". Sent ahead of the
+     * SDK's own in the x-shuffl-client header; Shuffl doesn't store it.
+     */
+    client?: string;
     fetch?: typeof globalThis.fetch;
 }
 export interface Shuffl extends ShufflClient {

package/dist/index.js

@@ -4,8 +4,20 @@ import { isContractProcedure } from '@orpc/contract';
 import { contract } from '@shuffl/api-contracts';
 import { companyContract, } from '@shuffl/api-contracts/company';
 export { ORPCError } from '@orpc/client';
-// #643: check and type the webhooks Shuffl sends.
+// Check and type the webhooks Shuffl sends.
 export { isWebhookEventType, signWebhook, verifyWebhook, WebhookVerificationError, webhookApiVersion, webhookEventCatalog, webhookEventGroups, webhookEventTypes, } from '@shuffl/api-contracts/webhooks';
+import { sdkVersion } from './version.js';
+// Which SDK release (and, for the CLI, which CLI release) made a request,
+// for Shuffl's own usage counts. One header line, no spaces inside a part.
+function clientHeader(client) {
+    const own = `shuffl-sdk/${sdkVersion}`;
+    const name = client?.trim();
+    if (!name)
+        return own;
+    if (!/^[\x21-\x7e]+(?: [\x21-\x7e]+)*$/.test(name) || name.length > 128)
+        throw new Error('client is a short name/version, such as billing-sync/1.2.0.');
+    return `${name} ${own}`;
+}
 const defaultBaseUrl = 'https://shuffl-rebuild.vercel.app';
 const companyKeyPrefix = 'shuffl_company_';
 function origin(baseUrl) {
@@ -31,7 +43,7 @@ const bearer = async (apiKey, kind) => {
         });
     return `Bearer ${key}`;
 };
-function workspaceClient(base, options) {
+function workspaceClient(base, options, client) {
     return createORPCClient(new RPCLink({
         // Writes are not automatically retried. Callers own stable request keys.
         fetch: async (request, init) => (options.fetch ?? globalThis.fetch)(request, {
@@ -40,6 +52,7 @@ function workspaceClient(base, options) {
         }),
         headers: async () => ({
             authorization: await bearer(options.apiKey, 'workspace'),
+            'x-shuffl-client': client,
         }),
         url: new URL('/api/v1/rpc', base).toString(),
     }));
@@ -53,9 +66,9 @@ const statusCodes = {
     409: 'CONFLICT',
     429: 'TOO_MANY_REQUESTS',
 };
-// The company API (#1692) is REST under /api/v1/company, so its client is
+// The company API is REST under /api/v1/company, so its client is
 // built from the contract's routes rather than the RPC link.
-function companyClient(base, options) {
+function companyClient(base, options, client) {
     const procedure = ({ method, path }) => async (input, call) => {
         const url = new URL(`/api/v1${path}`, base);
         const read = method === 'GET';
@@ -68,6 +81,7 @@ function companyClient(base, options) {
             headers: {
                 accept: 'application/json',
                 authorization: await bearer(options.apiKey, 'company'),
+                'x-shuffl-client': client,
                 ...(read ? {} : { 'content-type': 'application/json' }),
             },
             method,
@@ -117,12 +131,13 @@ export class Shuffl {
     company;
     constructor(options) {
         const base = origin(options.baseUrl ?? defaultBaseUrl);
-        const workspace = workspaceClient(base, options);
+        const client = clientHeader(options.client);
+        const workspace = workspaceClient(base, options, client);
         for (const key of Object.keys(contract))
             Object.defineProperty(this, key, {
                 enumerable: true,
                 value: workspace[key],
             });
-        this.company = companyClient(base, options);
+        this.company = companyClient(base, options, client);
     }
 }

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const sdkVersion = "0.6.2";

package/dist/version.js

@@ -0,0 +1,3 @@
+// The published version, sent in the x-shuffl-client header so Shuffl can
+// tell which SDK release calls it. `bun sdk:version X.Y.Z` writes it.
+export const sdkVersion = '0.6.2';

package/package.json

@@ -2,9 +2,9 @@
   "dependencies": {
     "@orpc/client": "1.15.3",
     "@orpc/contract": "1.15.3",
-    "@shuffl/api-contracts": "0.6.0"
+    "@shuffl/api-contracts": "0.6.2"
   },
-  "description": "TypeScript client for the Shuffl API: people, teams, knowledge, programs and management commands.",
+  "description": "TypeScript client for the Shuffl API: people, groups, knowledge, playbooks, programs and management commands.",
   "engines": {
     "node": ">=22"
   },
@@ -34,5 +34,5 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.6.0"
+  "version": "0.6.2"
 }