@shuffl/sdk 0.6.0 → 0.6.1

package/README.md

@@ -42,6 +42,8 @@ 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

package/dist/index.d.ts

@@ -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

@@ -6,6 +6,18 @@ 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) {
@@ -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(),
     }));
@@ -55,7 +68,7 @@ const statusCodes = {
 };
 // 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) {
+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.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.6.0"
+    "@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.6.0"
+  "version": "0.6.1"
 }