@shuffl/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shuffl LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Shuffl TypeScript SDK
+
+Use the Shuffl workspace API from Node.js 22+, Bun, or an agent runtime.
+
+```sh
+npm install @shuffl/sdk
+```
+
+The package is ESM-only and ships its own types. It installs `@shuffl/api-contracts`, which carries the input and output types for every method. The SDK, [CLI](https://www.npmjs.com/package/@shuffl/cli) and contracts are released together under one version.
+
+Create an API key in **Settings → API keys**. The key is bound to one workspace 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).
+
+```ts
+import { createShuffl } from '@shuffl/sdk';
+
+const shuffl = createShuffl({
+  baseUrl: process.env.SHUFFL_BASE_URL!, // Application origin, without /api/v1/rpc
+  token: process.env.SHUFFL_TOKEN!,
+});
+
+const page = await shuffl.users.list({ limit: 25 });
+const next = page.nextCursor
+  ? await shuffl.users.list({ cursor: page.nextCursor, limit: 25 })
+  : null;
+
+const preview = await shuffl.programs.preview({
+  id: 'program-id',
+  seed: 'mentoring-preview-2026-09',
+});
+```
+
+`users` means people in the workspace directory, including people who have no web login. IDs are Shuffl person IDs, not Slack IDs or authentication account IDs.
+
+The client includes people, teams, access, identity links, programs, runs, knowledge, invitations, provisioning, HR, support, billing, reports, exports, credentials and assistant conversations. 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() });
+```
+
+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.
+
+## Management commands
+
+```ts
+const saved = await shuffl.units.save({
+  id: crypto.randomUUID(), kind: 'team', name: 'Mentors',
+  expectedRevision: 0, 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.
+```
+
+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 workspace, provider consent and payment confirmation remain explicit browser/account flows.
+
+Full guide: [Use the SDK and HTTP API](https://shuffl-rebuild.vercel.app/docs/sdk).

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { ContractRouterClient } from '@orpc/contract';
+import type { ShufflContract } from '@shuffl/api-contracts';
+export { ORPCError } from '@orpc/client';
+export type { Permission, PermissionDefinition, Scope, } from '@shuffl/api-contracts';
+export type ShufflClient = ContractRouterClient<ShufflContract>;
+export interface ShufflOptions {
+    token: string | (() => string | Promise<string>);
+    /** Shuffl application origin, without /api/v1/rpc. */
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function createShuffl(options: ShufflOptions): ShufflClient;

package/dist/index.js

@@ -0,0 +1,23 @@
+import { createORPCClient } from '@orpc/client';
+import { RPCLink } from '@orpc/client/fetch';
+export { ORPCError } from '@orpc/client';
+export function createShuffl(options) {
+    const base = new URL(options.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 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}`,
+        }),
+        url: new URL('/api/v1/rpc', base).toString(),
+    }));
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "dependencies": {
+    "@orpc/client": "1.15.3",
+    "@orpc/contract": "1.15.3",
+    "@shuffl/api-contracts": "0.1.0"
+  },
+  "description": "TypeScript client for the Shuffl API: people, teams, knowledge, programs and management commands.",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://shuffl-rebuild.vercel.app/docs/sdk",
+  "keywords": [
+    "shuffl",
+    "sdk",
+    "hr",
+    "api-client"
+  ],
+  "license": "MIT",
+  "name": "@shuffl/sdk",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.1.0"
+}