@staqon.one/cli 0.0.0-stage → 0.1.0

package/dist/commands/misc.js

@@ -0,0 +1,94 @@
+import { proxy, MAX_LIST_LIMIT } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+function teamOpt(cmd) {
+    return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+export function registerMiscCommands(program) {
+    // ---- 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) => {
+        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) => {
+        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) => {
+        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) => {
+        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) => {
+        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/dist/commands/verify.js

@@ -0,0 +1,64 @@
+import { proxy } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+function teamOpt(cmd) {
+    return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+export function registerVerifyCommands(program) {
+    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) => {
+        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) => {
+        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) => {
+        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/dist/config.js

@@ -0,0 +1,37 @@
+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');
+async function ensureDir() {
+    await mkdir(CONFIG_DIR, { recursive: true });
+}
+export async function loadSession() {
+    try {
+        const raw = await readFile(CREDS_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveSession(session) {
+    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() {
+    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() {
+    return CREDS_PATH;
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/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/dist/output.js

@@ -0,0 +1,24 @@
+import { StaqOnApiError } from './api/client.js';
+export function ok(message) {
+    console.log(message);
+}
+export function fail(e) {
+    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) {
+    console.log(JSON.stringify(data, null, 2));
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@staqon.one/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Command-line tool for StaqOn workspace owners — send messages, post ads, run e-StaqOn Verify approvals, manage external/internal team members, and raise escalations, all without ever handling a raw API key.",
+  "bin": {
+    "staqon": "./dist/index.js"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aroraashish292-creator/staqon-cli.git"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,84 @@
+import { BASE_URL, loadSession, saveSession, clearSession } from '../config.js';
+
+export class StaqOnApiError extends Error {
+  constructor(
+    public status: number,
+    public body: Record<string, unknown>,
+  ) {
+    super(typeof body.error === 'string' ? body.error : `HTTP ${status}`);
+  }
+}
+
+/**
+ * The real, server-enforced ceiling for every paginated CLI list endpoint
+ * (members.php, internal/members.php, messages.php): Swagger says
+ * `maximum: 200` on all three. The OLD cli had a client-side MAX_LIST_LIMIT
+ * of 100 — that was a self-imposed, unnecessarily tight cap, not a server
+ * fact. Verified against openapi.yaml this session (Nov 11 2026).
+ */
+export const MAX_LIST_LIMIT = 200;
+
+interface CallOptions {
+  method?: 'GET' | 'POST';
+  query?: Record<string, string | number | undefined>;
+  json?: Record<string, unknown>;
+  team?: string; // X-StaqOn-Team — only needed when a workspace has 2+ eligible teams for that command's family
+}
+
+function buildQuery(params: Record<string, string | number | undefined> = {}): string {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined) qs.set(k, String(v));
+  }
+  const s = qs.toString();
+  return s ? `?${s}` : '';
+}
+
+/**
+ * The CLI's ONE front door, matching /api/v1/cli-proxy.php exactly:
+ *   GET|POST /api/v1/cli-proxy.php?_ep=<name>&...their own query
+ *   Authorization: Bearer stq_cli_<64 hex>
+ *   X-StaqOn-Team: <team id or slug>   (only when the workspace has >1 eligible team)
+ * Never sends X-API-Key — the proxy drops it server-side anyway; the CLI
+ * never holds, or needs, a raw tenant key.
+ */
+export async function proxy(ep: string, opts: CallOptions = {}): Promise<Record<string, unknown>> {
+  const session = await loadSession();
+  if (!session) {
+    throw new StaqOnApiError(401, { error: 'Not logged in. Run: staqon login' });
+  }
+
+  const method = opts.method ?? (opts.json ? 'POST' : 'GET');
+  const url = `${BASE_URL}/api/v1/cli-proxy.php${buildQuery({ _ep: ep, ...opts.query })}`;
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${session.token}`,
+  };
+  if (opts.team) headers['X-StaqOn-Team'] = opts.team;
+  if (opts.json) headers['Content-Type'] = 'application/json';
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: opts.json ? JSON.stringify(opts.json) : undefined,
+  });
+
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+
+  if (res.status === 401) {
+    // Session is gone/expired/revoked server-side — don't leave a dead token lying around locally.
+    await clearSession();
+    throw new StaqOnApiError(401, {
+      error: (body.error as string) ?? 'This CLI session is missing, expired or revoked. Run: staqon login',
+    });
+  }
+  if (!res.ok) throw new StaqOnApiError(res.status, body);
+  return body;
+}
+
+/** `_ep=whoami` — no backing file; the proxy answers directly with session/workspace/limits/access. */
+export async function whoami(): Promise<Record<string, unknown>> {
+  return proxy('whoami', { method: 'GET' });
+}
+
+export { BASE_URL, loadSession, saveSession, clearSession };

package/src/auth.ts

@@ -0,0 +1,132 @@
+import { BASE_URL, saveSession, clearSession, loadSession } from './config.js';
+
+const CLI_VERSION = '0.1.0'; // keep in sync with package.json
+
+interface CodeRequestResponse {
+  ok: true;
+  pair_id: string;
+  code: string;              // shown as "XXXX-XXXX"
+  verification_url: string;
+  poll_secret: string;
+  expires_in: number;        // seconds (600 server-side, i.e. 10 min)
+  interval: number;          // seconds between polls (3 server-side)
+}
+
+type PollStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'consumed';
+
+interface PollResponse {
+  ok: boolean;
+  status: PollStatus;
+  token?: string;            // present only on the one successful 'approved' poll — shown once
+  workspace?: { id: number; slug: string; name: string };
+  expires_at?: string;
+  error?: string;
+}
+
+async function postJson<T>(path: string, body: Record<string, unknown>): Promise<T> {
+  const res = await fetch(`${BASE_URL}/api/cli-pair.php?action=${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const data = (await res.json()) as T & { error?: string };
+  if (!res.ok || (data as { ok?: boolean }).ok === false) {
+    throw new Error((data as { error?: string }).error ?? `Login failed (HTTP ${res.status})`);
+  }
+  return data;
+}
+
+function osLabel(): string {
+  const p = process.platform;
+  if (p === 'darwin') return 'macOS';
+  if (p === 'win32') return 'Windows';
+  if (p === 'linux') return 'Linux';
+  return p;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Device-pairing login, matching api/cli-pair.php exactly:
+ *   1. code_request -> {pair_id, code, verification_url, poll_secret, expires_in, interval}
+ *   2. show the code + verification_url to the user
+ *   3. poll {pair_id, poll_secret} every `interval` seconds until approved/denied/expired
+ *   4. on 'approved', the token is minted and returned EXACTLY ONCE on that poll response —
+ *      save it immediately; a repeat poll after that returns 'consumed', not the token again.
+ *
+ * No API key is ever involved. The workspace owner approves the device at
+ * <verification_url> (StaqOn's own /cli page), picking which workspace and,
+ * if their web session is stale, re-entering their MPIN — all server-side.
+ */
+export async function login(deviceLabel?: string): Promise<{ workspace: { id: number; slug: string; name: string } }> {
+  const label = deviceLabel ?? `${osLabel()} computer`;
+
+  const start = await postJson<CodeRequestResponse>('code_request', {
+    device_label: label,
+    os: osLabel(),
+    cli_version: CLI_VERSION,
+  });
+
+  console.log('');
+  console.log(`  To finish signing in, visit: ${start.verification_url}`);
+  console.log(`  And enter this code: ${start.code}`);
+  console.log('');
+  console.log('  Waiting for approval (this code expires in 10 minutes)...');
+
+  const deadline = Date.now() + start.expires_in * 1000;
+  const intervalMs = Math.max(start.interval, 1) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const poll = await postJson<PollResponse>('poll', {
+      pair_id: start.pair_id,
+      poll_secret: start.poll_secret,
+    });
+
+    if (poll.status === 'pending') continue;
+
+    if (poll.status === 'approved' && poll.token && poll.workspace) {
+      await saveSession({
+        token: poll.token,
+        workspace: poll.workspace,
+        expires_at: poll.expires_at ?? '',
+        paired_at: new Date().toISOString(),
+      });
+      return { workspace: poll.workspace };
+    }
+
+    if (poll.status === 'denied') throw new Error('Login request was denied.');
+    if (poll.status === 'expired') throw new Error('Login code expired. Run: staqon login');
+    if (poll.status === 'consumed') throw new Error('This login code was already used. Run: staqon login');
+
+    throw new Error(poll.error ?? `Unexpected login status: ${poll.status}`);
+  }
+
+  throw new Error('Login timed out. Run: staqon login');
+}
+
+/**
+ * Rotates the current session token via ?action=refresh. The OLD token
+ * stays valid for 5 more minutes server-side (CLI_ROTATE_GRACE=300), so a
+ * failed save here doesn't strand the user mid-rotation.
+ */
+export async function refresh(): Promise<void> {
+  const session = await loadSession();
+  if (!session) throw new Error('Not logged in. Run: staqon login');
+
+  const res = await fetch(`${BASE_URL}/api/cli-pair.php?action=refresh`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${session.token}` },
+  });
+  const data = (await res.json()) as { ok: boolean; token?: string; error?: string };
+  if (!res.ok || !data.ok || !data.token) {
+    throw new Error(data.error ?? 'Could not refresh. Run: staqon login');
+  }
+  await saveSession({ ...session, token: data.token });
+}
+
+export async function logout(): Promise<void> {
+  await clearSession();
+}

package/src/commands/ad.ts

@@ -0,0 +1,100 @@
+import { Command } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { proxy, BASE_URL, loadSession } 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 registerAdCommands(program: Command): void {
+  const ad = program.command('ad').description('Advertisement API — send a card to every member thread of a team');
+
+  teamOpt(
+    ad
+      .command('upload-image')
+      .description('Upload one banner image (JPEG/PNG/WebP, max 300KB) and get back an image_url for `ad send --image-url`')
+      .requiredOption('--file <path>', 'local path to the image'),
+  ).action(async (opts: { file: string; team?: string }) => {
+    try {
+      const session = await loadSession();
+      if (!session) throw new Error('Not logged in. Run: staqon login');
+      const data = await readFile(opts.file);
+      const form = new FormData();
+      form.append('image', new Blob([data]), opts.file.split('/').pop() ?? 'image');
+
+      const headers: Record<string, string> = { Authorization: `Bearer ${session.token}` };
+      if (opts.team) headers['X-StaqOn-Team'] = opts.team;
+
+      const res = await fetch(`${BASE_URL}/api/v1/cli-proxy.php?_ep=external/ad-image`, {
+        method: 'POST',
+        headers,
+        body: form,
+      });
+      const body = (await res.json()) as Record<string, unknown>;
+      if (!res.ok) throw new Error(typeof body.error === 'string' ? body.error : `HTTP ${res.status}`);
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+
+  teamOpt(
+    ad
+      .command('send')
+      .description(
+        'Queue an ad card to every active thread of the team — asynchronous: returns 202 immediately, poll `ad status` for progress',
+      )
+      .requiredOption('--body <text>', '50-900 characters')
+      .requiredOption('--button-label <text>', '1-30 characters')
+      .requiredOption('--button-url <url>', 'must start with https://')
+      .option('--image-url <url>', 'from `ad upload-image`, same workspace+team')
+      .option('--external-ref <ref>', 'idempotency key — repeating it returns the original send\'s counts, sends nothing twice'),
+  ).action(
+    async (opts: {
+      body: string;
+      buttonLabel: string;
+      buttonUrl: string;
+      imageUrl?: string;
+      externalRef?: string;
+      team?: string;
+    }) => {
+      try {
+        const body = await proxy('external/ad', {
+          method: 'POST',
+          team: opts.team,
+          json: {
+            body: opts.body,
+            button_label: opts.buttonLabel,
+            button_url: opts.buttonUrl,
+            image_url: opts.imageUrl,
+            external_ref: opts.externalRef,
+          },
+        });
+        printJson(body);
+      } catch (e) {
+        fail(e);
+      }
+    },
+  );
+
+  teamOpt(
+    ad
+      .command('status')
+      .description('Progress or final result of one ad send — look up by external_ref or ad_request_id')
+      .option('--external-ref <ref>')
+      .option('--request-id <id>'),
+  ).action(async (opts: { externalRef?: string; requestId?: string; team?: string }) => {
+    if (!opts.externalRef && !opts.requestId) fail(new Error('Pass --external-ref or --request-id.'));
+    try {
+      const body = await proxy('external/ad-status', {
+        method: 'GET',
+        team: opts.team,
+        query: { external_ref: opts.externalRef, ad_request_id: opts.requestId },
+      });
+      printJson(body);
+    } catch (e) {
+      fail(e);
+    }
+  });
+}

package/src/commands/auth.ts

@@ -0,0 +1,39 @@
+import { Command } from 'commander';
+import { login, logout } from '../auth.js';
+import { whoami as fetchWhoami } from '../api/client.js';
+import { ok, fail } from '../output.js';
+
+export function registerAuthCommands(program: Command): void {
+  program
+    .command('login')
+    .description('Pair this computer with a StaqOn workspace (device-code flow — no API key needed)')
+    .option('--label <name>', 'a name for this computer, shown to the workspace owner when they approve')
+    .action(async (opts: { label?: string }) => {
+      try {
+        const { workspace } = await login(opts.label);
+        ok(`Paired with workspace "${workspace.name}" (${workspace.slug}).`);
+      } catch (e) {
+        fail(e);
+      }
+    });
+
+  program
+    .command('logout')
+    .description('Forget this computer\'s paired session (does not revoke it on the server — use the dashboard for that)')
+    .action(async () => {
+      await logout();
+      ok('Logged out locally. The server-side session, if still live, can be revoked from the workspace\'s CLI access page.');
+    });
+
+  program
+    .command('whoami')
+    .description('Show the paired workspace, session info, rate-limit usage, and which commands are available')
+    .action(async () => {
+      try {
+        const body = await fetchWhoami();
+        console.log(JSON.stringify(body, null, 2));
+      } catch (e) {
+        fail(e);
+      }
+    });
+}