@shuffl/cli 0.3.0 → 0.4.0

package/README.md

@@ -56,4 +56,18 @@ shuffl knowledge sources import-pdf --input-file pdf-command.json --json
 
 Management writes require `requestKey` and return `{receipt, result}`. Sensitive writes also require `confirm` equal to the SDK operation name. Keep the same input/key on retry: the duplicate returns only the receipt and `result: null`, without repeating the write or disclosing an old result. Read current resources to reconcile an unknown outcome.
 
+## Company settings
+
+Commands under `shuffl company` take a company key (`shuffl_company_`) from **Company settings → API keys** instead of a workspace key:
+
+```sh
+credential-command | shuffl login --company --base-url https://YOUR-SHUFFL-HOST --token-stdin
+shuffl company current --json
+shuffl company members list --limit 100 --json
+shuffl company members remove --user-id USER_ID --json
+shuffl logout --company
+```
+
+Or set `SHUFFL_COMPANY_KEY` and `SHUFFL_BASE_URL`. The company key is saved in `company.json` next to `config.json`, and only `shuffl company` commands send it; `shuffl logout --company` removes it. Each command's `--help` names its company permission. See [company keys](https://shuffl-rebuild.vercel.app/docs/api-permissions#company-keys).
+
 Full guide: [Use the Shuffl CLI](https://shuffl-rebuild.vercel.app/docs/cli).

package/dist/commands.generated.js

@@ -2595,6 +2595,10 @@ export const commands = [
                                 const: 'onboarding.candidates',
                                 type: 'string',
                             },
+                            {
+                                const: 'onboarding.completeTodo',
+                                type: 'string',
+                            },
                             {
                                 const: 'onboarding.enroll',
                                 type: 'string',
@@ -6436,6 +6440,37 @@ export const commands = [
         scope: 'onboarding:read',
         summary: 'List people who could be enrolled in onboarding',
     },
+    {
+        access: 'write',
+        command: ['onboarding', 'complete-todo'],
+        input: {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            additionalProperties: false,
+            properties: {
+                confirm: {
+                    const: 'onboarding.completeTodo',
+                    type: 'string',
+                },
+                done: {
+                    type: 'boolean',
+                },
+                requestKey: {
+                    maxLength: 128,
+                    minLength: 1,
+                    type: 'string',
+                },
+                todoId: {
+                    type: 'string',
+                },
+            },
+            required: ['done', 'todoId', 'confirm', 'requestKey'],
+            type: 'object',
+        },
+        path: ['onboarding', 'completeTodo'],
+        permission: 'onboarding.completeTodo',
+        scope: 'self:write',
+        summary: 'Check off (or reopen) one of your own onboarding to-dos',
+    },
     {
         access: 'write',
         command: ['onboarding', 'enroll'],
@@ -6553,7 +6588,7 @@ export const commands = [
         path: ['onboarding', 'journey'],
         permission: 'onboarding.journey',
         scope: 'self:read',
-        summary: 'Your onboarding timeline: start date, buddy, manager and upcoming check-ins',
+        summary: 'Your onboarding timeline: start date, buddy, manager, upcoming check-ins, your to-dos and resources',
     },
     {
         access: 'read',
@@ -6807,6 +6842,171 @@ export const commands = [
                                 sendTime: {
                                     type: 'string',
                                 },
+                                steps: {
+                                    items: {
+                                        additionalProperties: false,
+                                        properties: {
+                                            body: {
+                                                type: 'string',
+                                            },
+                                            checkpoint: {
+                                                anyOf: [
+                                                    {
+                                                        const: 'day_30',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'day_365',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'day_60',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'day_90',
+                                                        type: 'string',
+                                                    },
+                                                ],
+                                            },
+                                            id: {
+                                                type: 'string',
+                                            },
+                                            kind: {
+                                                anyOf: [
+                                                    {
+                                                        const: 'checkpoint',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'message',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'task',
+                                                        type: 'string',
+                                                    },
+                                                ],
+                                            },
+                                            offsetDays: {
+                                                type: 'number',
+                                            },
+                                            personId: {
+                                                type: ['null', 'string'],
+                                            },
+                                            recipient: {
+                                                anyOf: [
+                                                    {
+                                                        const: 'buddy',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'hire',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'hr',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'manager',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        const: 'person',
+                                                        type: 'string',
+                                                    },
+                                                ],
+                                            },
+                                            resources: {
+                                                items: {
+                                                    anyOf: [
+                                                        {
+                                                            additionalProperties: false,
+                                                            properties: {
+                                                                sourceId: {
+                                                                    type: 'string',
+                                                                },
+                                                                title: {
+                                                                    type: 'string',
+                                                                },
+                                                                type: {
+                                                                    const: 'knowledge',
+                                                                    type: 'string',
+                                                                },
+                                                            },
+                                                            required: ['sourceId', 'title', 'type'],
+                                                            type: 'object',
+                                                        },
+                                                        {
+                                                            additionalProperties: false,
+                                                            properties: {
+                                                                label: {
+                                                                    type: 'string',
+                                                                },
+                                                                type: {
+                                                                    const: 'link',
+                                                                    type: 'string',
+                                                                },
+                                                                url: {
+                                                                    type: 'string',
+                                                                },
+                                                            },
+                                                            required: ['label', 'type', 'url'],
+                                                            type: 'object',
+                                                        },
+                                                        {
+                                                            additionalProperties: false,
+                                                            properties: {
+                                                                communityId: {
+                                                                    type: 'string',
+                                                                },
+                                                                name: {
+                                                                    type: 'string',
+                                                                },
+                                                                type: {
+                                                                    const: 'community',
+                                                                    type: 'string',
+                                                                },
+                                                            },
+                                                            required: ['communityId', 'name', 'type'],
+                                                            type: 'object',
+                                                        },
+                                                    ],
+                                                },
+                                                type: 'array',
+                                            },
+                                            title: {
+                                                type: 'string',
+                                            },
+                                            todos: {
+                                                items: {
+                                                    additionalProperties: false,
+                                                    properties: {
+                                                        id: {
+                                                            type: 'string',
+                                                        },
+                                                        label: {
+                                                            type: 'string',
+                                                        },
+                                                    },
+                                                    required: ['id', 'label'],
+                                                    type: 'object',
+                                                },
+                                                type: 'array',
+                                            },
+                                        },
+                                        required: [
+                                            'id',
+                                            'kind',
+                                            'offsetDays',
+                                            'recipient',
+                                            'title',
+                                        ],
+                                        type: 'object',
+                                    },
+                                    type: 'array',
+                                },
                                 timezone: {
                                     type: 'string',
                                 },
@@ -10422,14 +10622,6 @@ export const commands = [
                 },
                 kind: {
                     anyOf: [
-                        {
-                            const: 'manager_check_in',
-                            type: 'string',
-                        },
-                        {
-                            const: 'new_hire_check_in',
-                            type: 'string',
-                        },
                         {
                             const: 'praise',
                             type: 'string',
@@ -10476,14 +10668,6 @@ export const commands = [
                 },
                 kind: {
                     anyOf: [
-                        {
-                            const: 'manager_check_in',
-                            type: 'string',
-                        },
-                        {
-                            const: 'new_hire_check_in',
-                            type: 'string',
-                        },
                         {
                             const: 'praise',
                             type: 'string',
@@ -12832,4 +13016,144 @@ export const commands = [
         scope: null,
         summary: 'Discover endpoint permissions available to this token',
     },
+    {
+        access: 'read',
+        command: ['company', 'current'],
+        credential: 'company',
+        input: null,
+        path: ['current'],
+        permission: 'company.current',
+        scope: null,
+        summary: 'Read the company this key belongs to and the permissions it was granted',
+    },
+    {
+        access: 'read',
+        command: ['company', 'details'],
+        credential: 'company',
+        input: null,
+        path: ['details'],
+        permission: 'company.details',
+        scope: null,
+        summary: 'Read the company name, logo and default workspace',
+    },
+    {
+        access: 'read',
+        command: ['company', 'email-domains', 'list'],
+        credential: 'company',
+        input: null,
+        path: ['emailDomains', 'list'],
+        permission: 'company.emailDomains.list',
+        scope: null,
+        summary: "List the company's email domains and their verification",
+    },
+    {
+        access: 'read',
+        command: ['company', 'members', 'list'],
+        credential: 'company',
+        input: {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            properties: {
+                cursor: {
+                    description: 'nextCursor from the previous page.',
+                    maxLength: 1024,
+                    minLength: 1,
+                    type: 'string',
+                },
+                limit: {
+                    default: 25,
+                    maximum: 100,
+                    minimum: 1,
+                    type: 'integer',
+                },
+            },
+            type: 'object',
+        },
+        path: ['members', 'list'],
+        permission: 'company.members.list',
+        scope: null,
+        summary: 'List company members and their company roles',
+    },
+    {
+        access: 'write',
+        command: ['company', 'members', 'remove'],
+        credential: 'company',
+        input: {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            properties: {
+                userId: {
+                    maxLength: 128,
+                    minLength: 1,
+                    type: 'string',
+                },
+            },
+            required: ['userId'],
+            type: 'object',
+        },
+        path: ['members', 'remove'],
+        permission: 'company.members.remove',
+        scope: null,
+        summary: 'Remove someone from the company (administrators only with an owner’s key)',
+    },
+    {
+        access: 'write',
+        command: ['company', 'rename'],
+        credential: 'company',
+        input: {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            properties: {
+                name: {
+                    maxLength: 100,
+                    minLength: 1,
+                    type: 'string',
+                },
+            },
+            required: ['name'],
+            type: 'object',
+        },
+        path: ['rename'],
+        permission: 'company.rename',
+        scope: null,
+        summary: 'Rename the company',
+    },
+    {
+        access: 'read',
+        command: ['company', 'slack', 'list'],
+        credential: 'company',
+        input: null,
+        path: ['slack', 'list'],
+        permission: 'company.slack.list',
+        scope: null,
+        summary: 'List the Slack workspaces connected to the company',
+    },
+    {
+        access: 'read',
+        command: ['company', 'workspaces', 'list'],
+        credential: 'company',
+        input: null,
+        path: ['workspaces', 'list'],
+        permission: 'company.workspaces.list',
+        scope: null,
+        summary: "List the company's workspaces",
+    },
+    {
+        access: 'write',
+        command: ['company', 'workspaces', 'set-default'],
+        credential: 'company',
+        input: {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            properties: {
+                teamId: {
+                    maxLength: 128,
+                    minLength: 1,
+                    type: 'string',
+                },
+            },
+            required: ['teamId'],
+            type: 'object',
+        },
+        path: ['workspaces', 'setDefault'],
+        permission: 'company.workspaces.setDefault',
+        scope: null,
+        summary: 'Choose the workspace new email domain and single sign-on members join',
+    },
 ];

package/dist/index.js

@@ -3,7 +3,7 @@ import { chmod, mkdir, readFile, rename, rm, writeFile, } from 'node:fs/promises
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { createShuffl, ORPCError } from '@shuffl/sdk';
+import { createShuffl, createShufflCompany, ORPCError } from '@shuffl/sdk';
 import { commands } from './commands.generated.js';
 // package.json sits one level above both src/ and dist/.
 const { version } = createRequire(import.meta.url)('../package.json');
@@ -43,7 +43,7 @@ function parse(args) {
         const [name, ...value] = arg.slice(2).split('=');
         if (!name || name in flags)
             throw new Error(`Duplicate or invalid flag: ${arg}`);
-        if (['help', 'json', 'token-stdin', 'version'].includes(name)) {
+        if (['company', 'help', 'json', 'token-stdin', 'version'].includes(name)) {
             if (value.length)
                 throw new Error(`--${name} takes no value`);
             flags[name] = true;
@@ -72,6 +72,31 @@ function scalar(raw, schema) {
         return JSON.parse(raw);
     return raw;
 }
+async function save(file, credentials) {
+    await mkdir(dirname(file), { mode: 0o700, recursive: true });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(credentials) + '\n', {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        await rename(temporary, file);
+        await chmod(file, 0o600);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function load(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new Error('Cannot read CLI configuration. Run shuffl login again.');
+        return undefined;
+    }
+}
 export async function runCli(args, io = {
     env: process.env,
     stderr: (s) => process.stderr.write(s),
@@ -81,8 +106,12 @@ export async function runCli(args, io = {
     const json = args.includes('--json');
     try {
         const { positional, flags } = parse(args);
-        const configFile = join(io.env.SHUFFL_CONFIG_DIR ??
-            join(io.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'shuffl'), 'config.json');
+        const configDirectory = io.env.SHUFFL_CONFIG_DIR ??
+            join(io.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'shuffl');
+        const configFile = join(configDirectory, 'config.json');
+        // #1692: a company key is saved apart from the workspace key, and only
+        // `shuffl company` commands send it.
+        const companyFile = join(configDirectory, 'company.json');
         if (flags.version && !positional.length) {
             io.stdout(json ? `${JSON.stringify({ version })}\n` : `${version}\n`);
             return 0;
@@ -90,27 +119,38 @@ export async function runCli(args, io = {
         if (flags.help || !positional.length) {
             const definition = commands.find((c) => c.command.join(' ') === positional.join(' '));
             io.stdout(definition
-                ? `${definition.summary}\nPermission: ${definition.permission} (${definition.access})\n\nshuffl ${definition.command.join(' ')} [--input JSON | --input-file FILE] [--json]\n${Object.entries(definition.input?.properties ?? {})
+                ? `${definition.summary}\nPermission: ${definition.permission} (${definition.access})${definition.credential === 'company' ? '\nCredential: a company key (SHUFFL_COMPANY_KEY or shuffl login --company)' : ''}\n\nshuffl ${definition.command.join(' ')} [--input JSON | --input-file FILE] [--json]\n${Object.entries(definition.input?.properties ?? {})
                     .map(([key, value]) => `  --${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)} <${value.type ?? 'json'}>`)
                     .join('\n')}\n`
-                : `Shuffl CLI ${version}\n\n  shuffl login --base-url URL --token-stdin\n  shuffl logout\n  shuffl --version\n${commands.map((c) => `  shuffl ${c.command.join(' ')} — ${c.summary}`).join('\n')}\n\nUse --help on a command for inputs. Use --json for machine-readable output.\nCreate a key in Settings → API keys and choose the endpoint permissions this CLI needs.\n`);
+                : `Shuffl CLI ${version}\n\n  shuffl login --base-url URL --token-stdin\n  shuffl login --company --base-url URL --token-stdin\n  shuffl logout [--company]\n  shuffl --version\n${commands.map((c) => `  shuffl ${c.command.join(' ')} — ${c.summary}`).join('\n')}\n\nUse --help on a command for inputs. Use --json for machine-readable output.\nCreate a key in Settings → API keys and choose the endpoint permissions this CLI needs.\nshuffl company commands use a company key from Company settings → API keys instead.\n`);
             return 0;
         }
         if (positional.length === 1 && positional[0] === 'logout') {
-            if (Object.keys(flags).some((k) => k !== 'json'))
+            if (Object.keys(flags).some((k) => !['company', 'json'].includes(k)))
                 throw new Error('Unknown logout flag.');
-            await rm(configFile, { force: true });
+            await rm(flags.company ? companyFile : configFile, { force: true });
             io.stdout(json
                 ? '{}\n'
-                : 'Signed out locally. Revoke the token in Settings to disable other copies.\n');
+                : `Signed out locally. Revoke the ${flags.company ? 'key in Company settings' : 'token in Settings'} to disable other copies.\n`);
             return 0;
         }
         if (positional.length === 1 && positional[0] === 'login') {
-            if (Object.keys(flags).some((k) => !['base-url', 'token-stdin', 'json'].includes(k)))
+            if (Object.keys(flags).some((k) => !['base-url', 'company', 'token-stdin', 'json'].includes(k)))
                 throw new Error('Unknown login flag.');
             if (!flags['token-stdin'] || typeof flags['base-url'] !== 'string')
                 throw new Error('Use login --base-url URL --token-stdin. The token is read from standard input.');
             const token = (await io.stdin()).trim();
+            if (flags.company) {
+                if (!/^shuffl_company_[A-Za-z0-9_-]{43}$/.test(token))
+                    throw new Error('Expected a Shuffl company key.');
+                const baseUrl = new URL(flags['base-url']).origin;
+                const company = await request(() => createShufflCompany({ baseUrl, token }).current());
+                await save(companyFile, { baseUrl, token });
+                io.stdout(json
+                    ? JSON.stringify({ company }) + '\n'
+                    : `Signed in to company ${company.organizationId} with ${company.permissions.length} permission${company.permissions.length === 1 ? '' : 's'}.\n`);
+                return 0;
+            }
             if (!/^shuffl_api_[A-Za-z0-9_-]{43}$/.test(token))
                 throw new Error('Expected a Shuffl API token.');
             const baseUrl = new URL(flags['base-url']).origin;
@@ -119,19 +159,7 @@ export async function runCli(args, io = {
                 token,
             });
             const team = await request(() => client.teams.current());
-            await mkdir(dirname(configFile), { mode: 0o700, recursive: true });
-            const temporary = `${configFile}.${randomUUID()}.tmp`;
-            try {
-                await writeFile(temporary, JSON.stringify({ baseUrl, token }) + '\n', {
-                    flag: 'wx',
-                    mode: 0o600,
-                });
-                await rename(temporary, configFile);
-                await chmod(configFile, 0o600);
-            }
-            finally {
-                await rm(temporary, { force: true });
-            }
+            await save(configFile, { baseUrl, token });
             io.stdout(json ? JSON.stringify({ team }) + '\n' : `Signed in to ${team.name}.\n`);
             return 0;
         }
@@ -165,25 +193,26 @@ export async function runCli(args, io = {
                     throw new Error(`Input ${key} was provided more than once.`);
                 input[key] = scalar(flags[flag], fields[key]);
             }
-        let saved;
-        try {
-            saved = JSON.parse(await readFile(configFile, 'utf8'));
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT')
-                throw new Error('Cannot read CLI configuration. Run shuffl login again.');
-        }
-        const token = io.env.SHUFFL_TOKEN ?? saved?.token;
+        const company = command.credential === 'company';
+        const environmentToken = company
+            ? io.env.SHUFFL_COMPANY_KEY
+            : io.env.SHUFFL_TOKEN;
+        const saved = await load(company ? companyFile : configFile);
+        const token = environmentToken ?? saved?.token;
         const baseUrl = typeof flags['base-url'] === 'string'
             ? flags['base-url']
             : (io.env.SHUFFL_BASE_URL ?? saved?.baseUrl);
         if (!token || !baseUrl)
-            throw new Error('Run shuffl login, or set SHUFFL_TOKEN and SHUFFL_BASE_URL.');
-        if (!io.env.SHUFFL_TOKEN &&
+            throw new Error(company
+                ? 'Run shuffl login --company, or set SHUFFL_COMPANY_KEY and SHUFFL_BASE_URL.'
+                : 'Run shuffl login, or set SHUFFL_TOKEN and SHUFFL_BASE_URL.');
+        if (!environmentToken &&
             saved &&
             new URL(baseUrl).origin !== new URL(saved.baseUrl).origin)
             throw new Error('Saved credentials belong to a different server. Sign in to the target server first.');
-        let method = createShuffl({ baseUrl, token });
+        let method = company
+            ? createShufflCompany({ baseUrl, token })
+            : createShuffl({ baseUrl, token });
         for (const name of command.path)
             method = method[name];
         const output = await request(() => method(input));

package/dist/types.d.ts

@@ -13,4 +13,6 @@ export interface CommandDefinition {
     summary: string;
     scope: string | null;
     input: JsonSchema | null;
+    /** company: a company key command, under `shuffl company` (#1692). */
+    credential?: 'company';
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
     "@orpc/client": "1.15.3",
-    "@shuffl/api-contracts": "0.3.0",
-    "@shuffl/sdk": "0.3.0"
+    "@shuffl/api-contracts": "0.4.0",
+    "@shuffl/sdk": "0.4.0"
   },
   "description": "Shuffl command line: every public API operation as a scriptable command with JSON output.",
   "engines": {
@@ -33,7 +33,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "bin": {
     "shuffl": "./dist/bin.js"
   }