@staqon.one/cli 0.0.0-stage → 0.1.0

package/src/commands/members.ts

@@ -0,0 +1,130 @@
+import { Command } from 'commander';
+import { proxy, MAX_LIST_LIMIT } from '../api/client.js';
+import { fail, printJson, ok } from '../output.js';
+
+function teamOpt(cmd: Command): Command {
+  return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+
+export function registerMemberCommands(program: Command): void {
+  const members = program.command('members').description('Manage external team members');
+
+  teamOpt(
+    members
+      .command('list')
+      .description('List this team\'s external (guest) members')
+      .option('--page <n>', 'page number', '1')
+      .option('--limit <n>', `page size, 1-${MAX_LIST_LIMIT} (default 50)`, '50')
+      .option('--search <text>', 'match against name or email'),
+  ).action(async (opts: { page: string; limit: string; search?: string; team?: string }) => {
+    try {
+      const body = await proxy('external/members', {
+        method: 'GET',
+        team: opts.team,
+        query: { page: opts.page, limit: opts.limit, search: opts.search },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    members
+      .command('get')
+      .description('Get one external member, by email or member_id')
+      .option('--email <email>')
+      .option('--member-id <id>'),
+  ).action(async (opts: { email?: string; memberId?: string; team?: string }) => {
+    try {
+      const body = await proxy('external/member', {
+        method: 'GET',
+        team: opts.team,
+        query: { email: opts.email, member_id: opts.memberId },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    members
+      .command('add')
+      .description('Add (or re-add) a member to this external team')
+      .requiredOption('--name <name>')
+      .requiredOption('--email <email>'),
+    // NOTE: no --phone flag. add-member.php's request schema is {name, email} only (both
+    // required) — verified against openapi.yaml this session. The old CLI sent a --phone
+    // value the server silently ignored; that flag is dropped here rather than kept as a
+    // no-op, so nobody mistakes it for working.
+  ).action(async (opts: { name: string; email: string; team?: string }) => {
+    try {
+      const body = await proxy('external/add-member', {
+        method: 'POST',
+        team: opts.team,
+        json: { name: opts.name, email: opts.email },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    members
+      .command('remove')
+      .description('Remove a member from this external team (archives their thread; history kept)')
+      .requiredOption('--email <email>'),
+  ).action(async (opts: { email: string; team?: string }) => {
+    try {
+      const body = await proxy('external/remove-member', {
+        method: 'POST',
+        team: opts.team,
+        json: { email: opts.email },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    members
+      .command('teams')
+      .description('Which external teams has a linked member joined? (looked up by external_ref)')
+      .requiredOption('--external-ref <ref>', 'the external_ref originally sent to link-invite'),
+  ).action(async (opts: { externalRef: string; team?: string }) => {
+    try {
+      const body = await proxy('external/member-teams', {
+        method: 'GET',
+        team: opts.team,
+        query: { external_ref: opts.externalRef },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  // Internal-surface member listing — same family, different endpoint/scope (no guest filter, reports role not message stats).
+  teamOpt(
+    program
+      .command('internal-members')
+      .description('List this key\'s internal team members (role-based, no external thread stats)')
+      .option('--page <n>', 'page number', '1')
+      .option('--limit <n>', `page size, 1-${MAX_LIST_LIMIT} (default 50)`, '50')
+      .option('--search <text>', 'match against name, email or username'),
+  ).action(async (opts: { page: string; limit: string; search?: string; team?: string }) => {
+    try {
+      const body = await proxy('internal/members', {
+        method: 'GET',
+        team: opts.team,
+        query: { page: opts.page, limit: opts.limit, search: opts.search },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+}

package/src/commands/messaging.ts

@@ -0,0 +1,116 @@
+import { Command } from 'commander';
+import { proxy, MAX_LIST_LIMIT } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+
+function teamOpt(cmd: Command): Command {
+  return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+
+export function registerMessagingCommands(program: Command): void {
+  const messages = program.command('messages').description('Send and read External team member conversations');
+
+  teamOpt(
+    messages
+      .command('send')
+      .description('Send a message into a member\'s thread, as the workspace owner')
+      .requiredOption('--email <email>')
+      .requiredOption('--message <text>', 'max 60000 characters'),
+  ).action(async (opts: { email: string; message: string; team?: string }) => {
+    try {
+      const body = await proxy('external/message', {
+        method: 'POST',
+        team: opts.team,
+        json: { email: opts.email, message: opts.message },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    messages
+      .command('comment')
+      .description(
+        'Post a comment into a member\'s thread, attributed to the workspace (no consent link needed — writing in is the workspace\'s own authority)',
+      )
+      .requiredOption('--username <username>')
+      .requiredOption('--comment <text>', 'max 60000 characters')
+      .option(
+        '--external-ref <ref>',
+        'idempotency key, max 190 chars — scoped to the WHOLE WORKSPACE, not per recipient; reusing it for a different recipient silently does not reach them',
+      ),
+  ).action(async (opts: { username: string; comment: string; externalRef?: string; team?: string }) => {
+    try {
+      const body = await proxy('external/comment', {
+        method: 'POST',
+        team: opts.team,
+        json: { username: opts.username, comment: opts.comment, external_ref: opts.externalRef },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    messages
+      .command('read')
+      .description('Read a member\'s thread history — requires an APPROVED consent link for that member (403 if not present)')
+      .requiredOption('--username <username>')
+      .option('--limit <n>', `1-${MAX_LIST_LIMIT} (default 50)`, '50')
+      .option('--before <id>', 'message id cursor — older messages, newest-first')
+      .option('--after <id>', 'message id cursor — newer messages, oldest-first (mutually exclusive with --before)'),
+  ).action(async (opts: { username: string; limit: string; before?: string; after?: string; team?: string }) => {
+    if (opts.before && opts.after) fail(new Error('Use either --before or --after, not both.'));
+    try {
+      const body = await proxy('external/messages', {
+        method: 'GET',
+        team: opts.team,
+        query: { username: opts.username, limit: opts.limit, before: opts.before, after: opts.after },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  // Internal surface: one-way feed push, NOT a conversation (no replies/reactions/attachments).
+  // Requires an APPROVED link_type='internal' consent row (stricter than External's write path).
+  teamOpt(
+    program
+      .command('internal-message')
+      .description('Push a one-way message into a member\'s API Messages feed (internal surface — requires member consent)')
+      .requiredOption('--username <username>')
+      .requiredOption('--message <text>', 'max 60000 characters')
+      .option('--title <text>', 'max 200 characters')
+      .option('--link-url <url>', 'must be http(s)')
+      .option('--external-ref <ref>', 'idempotency key, max 190 chars — scoped per API key, not per recipient'),
+  ).action(
+    async (opts: {
+      username: string;
+      message: string;
+      title?: string;
+      linkUrl?: string;
+      externalRef?: string;
+      team?: string;
+    }) => {
+      try {
+        const body = await proxy('internal/message', {
+          method: 'POST',
+          team: opts.team,
+          json: {
+            username: opts.username,
+            message: opts.message,
+            title: opts.title,
+            link_url: opts.linkUrl,
+            external_ref: opts.externalRef,
+          },
+        });
+        printJson(body);
+      } catch (e) {
+        fail(e);
+      }
+    },
+  );
+}

package/src/commands/misc.ts

@@ -0,0 +1,109 @@
+import { Command } from 'commander';
+import { proxy, MAX_LIST_LIMIT } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+
+function teamOpt(cmd: Command): Command {
+  return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+
+export function registerMiscCommands(program: Command): void {
+  // ---- Escalation (External surface) ----
+  const escalation = program.command('escalation').description('Raise and read escalation matters against team members');
+
+  teamOpt(
+    escalation
+      .command('raise')
+      .description('Raise an escalation matter against a team member')
+      .requiredOption('--email <email>')
+      .requiredOption('--title <text>', 'min 2 characters')
+      .requiredOption('--description <text>')
+      .requiredOption('--due-date <YYYY-MM-DD>', 'must be strictly after today')
+      .option('--priority <level>', 'low|medium|high|critical', 'medium'),
+  ).action(
+    async (opts: { email: string; title: string; description: string; dueDate: string; priority: string; team?: string }) => {
+      try {
+        const body = await proxy('external/escalation', {
+          method: 'POST',
+          team: opts.team,
+          json: {
+            email: opts.email,
+            title: opts.title,
+            description: opts.description,
+            due_date: opts.dueDate,
+            priority: opts.priority,
+          },
+        });
+        printJson(body);
+      } catch (e) {
+        fail(e);
+      }
+    },
+  );
+
+  teamOpt(
+    escalation
+      .command('list')
+      .description('List escalation matters raised against this team\'s members (scoped to matters your key can see)')
+      .option('--page <n>', 'page number', '1')
+      .option('--limit <n>', `1-${MAX_LIST_LIMIT} (default 50)`, '50')
+      .option('--status <status>', 'open|in_progress|resolved'),
+  ).action(async (opts: { page: string; limit: string; status?: string; team?: string }) => {
+    try {
+      const body = await proxy('external/escalations', {
+        method: 'GET',
+        team: opts.team,
+        query: { page: opts.page, limit: opts.limit, status: opts.status },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    escalation
+      .command('get')
+      .description('Fetch a single escalation matter by id')
+      .requiredOption('--matter-id <id>'),
+  ).action(async (opts: { matterId: string; team?: string }) => {
+    try {
+      const body = await proxy('external/escalations', { method: 'GET', team: opts.team, query: { matter_id: opts.matterId } });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  // ---- Status (key context + usage — External and Internal surfaces) ----
+  teamOpt(
+    program
+      .command('status')
+      .description('Key context + usage for this team (External surface) — real-only member counts and rate-limit usage')
+      .option('--internal', 'use the Internal surface instead (no guest-role filter)'),
+  ).action(async (opts: { internal?: boolean; team?: string }) => {
+    try {
+      const body = await proxy(opts.internal ? 'internal/status' : 'external/status', { method: 'GET', team: opts.team });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  // ---- Webhook health (External and Internal surfaces) ----
+  teamOpt(
+    program
+      .command('webhooks')
+      .description('Health of this team\'s webhooks (a webhook auto-disables after 10 consecutive non-2xx deliveries)')
+      .option('--internal', 'use the Internal surface instead'),
+  ).action(async (opts: { internal?: boolean; team?: string }) => {
+    try {
+      const body = await proxy(opts.internal ? 'internal/webhook-status' : 'external/webhook-status', {
+        method: 'GET',
+        team: opts.team,
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+}

package/src/commands/verify.ts

@@ -0,0 +1,75 @@
+import { Command } from 'commander';
+import { proxy } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+
+function teamOpt(cmd: Command): Command {
+  return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+
+export function registerVerifyCommands(program: Command): void {
+  const verify = program.command('verify').description('e-StaqOn Verify — ask a member to push-approve a sensitive action');
+
+  teamOpt(
+    verify
+      .command('start')
+      .description('Ask a member to confirm a sensitive action (push approval) — requires an approved, unexpired consent link')
+      .requiredOption('--username <username>')
+      .requiredOption('--action <text>', 'short label, max 100 chars')
+      .requiredOption('--context <text>', 'what the member is approving — shown to them verbatim, max 500 chars')
+      .option('--ttl <seconds>', 'how long the request stays open, 30-180 (default 30; out-of-range is clamped, not rejected)'),
+  ).action(
+    async (opts: { username: string; action: string; context: string; ttl?: string; team?: string }) => {
+      try {
+        const body = await proxy('external/staqon-verify-start', {
+          method: 'POST',
+          team: opts.team,
+          json: {
+            username: opts.username,
+            action: opts.action,
+            context: opts.context,
+            ttl_seconds: opts.ttl ? Number(opts.ttl) : undefined,
+          },
+        });
+        printJson(body);
+      } catch (e) {
+        fail(e);
+      }
+    },
+  );
+
+  teamOpt(
+    verify
+      .command('check')
+      .description('Poll the outcome of a verification request — only verified:true means the member approved in time')
+      .requiredOption('--id <verification_id>'),
+  ).action(async (opts: { id: string; team?: string }) => {
+    try {
+      const body = await proxy('external/staqon-verify-check', {
+        method: 'POST',
+        team: opts.team,
+        json: { verification_id: opts.id },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    verify
+      .command('cancel')
+      .description('Withdraw a pending verification request — a 409 means the member already answered; that answer stands')
+      .requiredOption('--id <verification_id>'),
+  ).action(async (opts: { id: string; team?: string }) => {
+    try {
+      const body = await proxy('external/staqon-verify-cancel', {
+        method: 'POST',
+        team: opts.team,
+        json: { verification_id: opts.id },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
+
+export const BASE_URL = process.env.STAQON_BASE_URL ?? 'https://staqon.one';
+const CONFIG_DIR = join(homedir(), '.staqon');
+const CREDS_PATH = join(CONFIG_DIR, 'credentials.json');
+
+export interface StoredSession {
+  token: string;                // stq_cli_<64 hex> — the CLI's own session token, never a tenant API key
+  workspace: { id: number; slug: string; name: string };
+  expires_at: string;           // informational only; the server is the real authority on expiry
+  paired_at: string;
+}
+
+async function ensureDir(): Promise<void> {
+  await mkdir(CONFIG_DIR, { recursive: true });
+}
+
+export async function loadSession(): Promise<StoredSession | null> {
+  try {
+    const raw = await readFile(CREDS_PATH, 'utf8');
+    return JSON.parse(raw) as StoredSession;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveSession(session: StoredSession): Promise<void> {
+  await ensureDir();
+  await writeFile(CREDS_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+  // writeFile's mode option is only honored on file *creation* on some platforms — enforce it explicitly.
+  await chmod(CREDS_PATH, 0o600);
+}
+
+export async function clearSession(): Promise<void> {
+  await ensureDir();
+  try {
+    await writeFile(CREDS_PATH, '', { mode: 0o600 });
+    await import('node:fs/promises').then((fs) => fs.unlink(CREDS_PATH));
+  } catch {
+    // already gone — fine
+  }
+}
+
+export function credentialsPath(): string {
+  return CREDS_PATH;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerMemberCommands } from './commands/members.js';
+import { registerMessagingCommands } from './commands/messaging.js';
+import { registerVerifyCommands } from './commands/verify.js';
+import { registerAdCommands } from './commands/ad.js';
+import { registerMiscCommands } from './commands/misc.js';
+
+const program = new Command();
+
+program
+  .name('staqon')
+  .description(
+    'Command-line tool for a StaqOn workspace owner. Sign in with `staqon login` — a device-pairing ' +
+      'flow approved from your StaqOn dashboard. The CLI never holds or sees a raw API key.',
+  )
+  .version('0.1.0');
+
+registerAuthCommands(program);
+registerMemberCommands(program);
+registerMessagingCommands(program);
+registerVerifyCommands(program);
+registerAdCommands(program);
+registerMiscCommands(program);
+
+program.parseAsync(process.argv).catch((e) => {
+  console.error('Error:', e instanceof Error ? e.message : e);
+  process.exit(1);
+});

package/src/output.ts

@@ -0,0 +1,24 @@
+import { StaqOnApiError } from './api/client.js';
+
+export function ok(message: string): void {
+  console.log(message);
+}
+
+export function fail(e: unknown): never {
+  if (e instanceof StaqOnApiError) {
+    console.error(`Error: ${e.message}`);
+    if (Object.keys(e.body).length) {
+      const extra = Object.fromEntries(Object.entries(e.body).filter(([k]) => k !== 'error' && k !== 'ok'));
+      if (Object.keys(extra).length) console.error(JSON.stringify(extra, null, 2));
+    }
+  } else if (e instanceof Error) {
+    console.error(`Error: ${e.message}`);
+  } else {
+    console.error('Error:', e);
+  }
+  process.exit(1);
+}
+
+export function printJson(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": false,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}