@shuffl/sdk 0.3.0 → 0.4.0

package/README.md

@@ -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.
 
@@ -60,4 +60,23 @@ Management writes return `{receipt, result}`. A duplicate request returns the sa
 
 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,23 @@
-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 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,95 @@
-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);
+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.4.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.4.0"
 }