@shuffl/sdk 0.5.12 → 0.6.1

package/README.md

@@ -13,12 +13,9 @@ Create an API key in **Settings → API keys**. The key is bound to one team and
 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';
+import { Shuffl } from '@shuffl/sdk';
 
-const shuffl = createShuffl({
-  baseUrl: process.env.SHUFFL_BASE_URL!, // Application origin, without /api/v1/rpc
-  token: process.env.SHUFFL_TOKEN!,
-});
+const shuffl = new Shuffl({ apiKey: process.env.SHUFFL_TOKEN! });
 
 const page = await shuffl.users.list({ limit: 25 });
 const next = page.nextCursor
@@ -31,18 +28,22 @@ const preview = await shuffl.programs.preview({
 });
 ```
 
+`new Shuffl` takes a workspace key or a company key and reads its prefix to tell them apart. Pass `baseUrl` (the application origin, without `/api/v1`) only to reach a server other than production, such as `http://localhost:3000` in development.
+
 `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 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.
+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.
 
 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.
 
 Dates in the public API are ISO strings. Directory lists use an opaque cursor and a limit of 1–100; other methods retain their documented pagination shapes. The SDK does not automatically retry writes. Supply a token getter if credentials rotate:
 
 ```ts
-createShuffl({ baseUrl, token: async () => credentialStore.read() });
+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
@@ -89,21 +90,18 @@ Credentials with `credentials:write` can delegate only their own scopes, with bo
 
 ## 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`:
+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. Pass it to the same client and call `shuffl.company`, which runs the REST operations under `/api/v1/company`:
 
 ```ts
-import { createShufflCompany } from '@shuffl/sdk';
+import { Shuffl } from '@shuffl/sdk';
 
-const company = createShufflCompany({
-  baseUrl: process.env.SHUFFL_BASE_URL!,
-  token: process.env.SHUFFL_COMPANY_KEY!,
-});
+const shuffl = new Shuffl({ apiKey: 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 });
+const { permissions } = await shuffl.company.current(); // Any company key.
+const page = await shuffl.company.members.list({ limit: 100 });
+await shuffl.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).
+`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).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { type ContractRouterClient } from '@orpc/contract';
-import type { ShufflContract } from '@shuffl/api-contracts';
+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';
@@ -8,17 +8,30 @@ 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;
+    /**
+     * A workspace key (shuffl_api_) or a company key (shuffl_company_), or a
+     * function that returns the current one when keys rotate.
+     */
+    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;
 }
-/** A client for workspace operations, with a workspace key (shuffl_api_). */
-export declare function createShuffl(options: ShufflOptions): ShufflClient;
+export interface Shuffl extends 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.
+ * The Shuffl API client. A workspace key (shuffl_api_) calls the workspace
+ * operations at the top level: `shuffl.users.list({ limit: 25 })`. A company
+ * key (shuffl_company_) from Company settings → API keys calls the company
+ * operations under `shuffl.company`: `shuffl.company.members.list()`. Calling
+ * the other kind's methods fails before any request is sent.
  */
-export declare function createShufflCompany(options: ShufflOptions): ShufflCompanyClient;
+export declare class Shuffl {
+    readonly company: ShufflCompanyClient;
+    constructor(options: ShufflOptions);
+}

package/dist/index.js

@@ -1,10 +1,25 @@
 import { createORPCClient, ORPCError } from '@orpc/client';
 import { RPCLink } from '@orpc/client/fetch';
 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.
 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) {
     const base = new URL(baseUrl);
     if (base.username ||
@@ -15,17 +30,30 @@ function origin(baseUrl) {
         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);
+// The key's prefix picks the API it can call, so the wrong kind fails here
+// with a clear message instead of an UNAUTHORIZED from the server.
+const bearer = async (apiKey, kind) => {
+    const key = typeof apiKey === 'function' ? await apiKey() : apiKey;
+    if (key.startsWith(companyKeyPrefix) !== (kind === 'company'))
+        throw new ORPCError('UNAUTHORIZED', {
+            message: kind === 'company'
+                ? 'shuffl.company methods need a company key (shuffl_company_) from Company settings → API keys.'
+                : 'A company key (shuffl_company_) only reaches shuffl.company methods. Use a workspace key (shuffl_api_) from Settings → API keys.',
+            status: 401,
+        });
+    return `Bearer ${key}`;
+};
+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, {
             ...init,
             redirect: 'error',
         }),
-        headers: async () => ({ authorization: await bearer(options.token) }),
+        headers: async () => ({
+            authorization: await bearer(options.apiKey, 'workspace'),
+            'x-shuffl-client': client,
+        }),
         url: new URL('/api/v1/rpc', base).toString(),
     }));
 }
@@ -38,14 +66,9 @@ const statusCodes = {
     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);
+// The company API (#1692) 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, client) {
     const procedure = ({ method, path }) => async (input, call) => {
         const url = new URL(`/api/v1${path}`, base);
         const read = method === 'GET';
@@ -57,7 +80,8 @@ export function createShufflCompany(options) {
             body: read ? undefined : JSON.stringify(input ?? {}),
             headers: {
                 accept: 'application/json',
-                authorization: await bearer(options.token),
+                authorization: await bearer(options.apiKey, 'company'),
+                'x-shuffl-client': client,
                 ...(read ? {} : { 'content-type': 'application/json' }),
             },
             method,
@@ -95,3 +119,25 @@ export function createShufflCompany(options) {
         : Object.fromEntries(Object.entries(node).map(([key, value]) => [key, build(value)]));
     return build(companyContract);
 }
+/**
+ * The Shuffl API client. A workspace key (shuffl_api_) calls the workspace
+ * operations at the top level: `shuffl.users.list({ limit: 25 })`. A company
+ * key (shuffl_company_) from Company settings → API keys calls the company
+ * operations under `shuffl.company`: `shuffl.company.members.list()`. Calling
+ * the other kind's methods fails before any request is sent.
+ */
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the workspace operations are assigned in the constructor.
+export class Shuffl {
+    company;
+    constructor(options) {
+        const base = origin(options.baseUrl ?? defaultBaseUrl);
+        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, client);
+    }
+}

package/dist/version.d.ts

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

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.1';

package/package.json

@@ -2,7 +2,7 @@
   "dependencies": {
     "@orpc/client": "1.15.3",
     "@orpc/contract": "1.15.3",
-    "@shuffl/api-contracts": "0.5.12"
+    "@shuffl/api-contracts": "0.6.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.5.12"
+  "version": "0.6.1"
 }