@operatorkit/hs 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# @operatorkit/hs
+
+A command-line interface for the [HelpScout](https://www.helpscout.com/) API. Manage mailboxes, conversations, customers, tags, users, workflows, webhooks, and knowledge base content from the terminal.
+
+Ships with an embedded [MCP](https://modelcontextprotocol.io/) server for AI-assisted workflows.
+
+## Install
+
+```bash
+# Run directly (no install)
+npx -y @operatorkit/hs version
+
+# Global install
+npm i -g @operatorkit/hs
+```
+
+On install, the matching platform binary is downloaded from GitHub Releases. Supported: `linux`, `darwin`, `windows` on `amd64`/`arm64`.
+
+## Quick start
+
+```bash
+# Authenticate (Inbox API — OAuth2 app credentials)
+npx -y @operatorkit/hs inbox auth login
+
+# Authenticate (Docs API — API key)
+npx -y @operatorkit/hs docs auth login
+
+# List mailboxes
+npx -y @operatorkit/hs inbox mailboxes list
+
+# List conversations
+npx -y @operatorkit/hs inbox conversations list --status active
+
+# Search articles
+npx -y @operatorkit/hs docs articles search --query "getting started"
+```
+
+## API coverage
+
+### Inbox API (`hs inbox ...`)
+
+Full CRUD for all Inbox API resources:
+
+- **Conversations** — list, get, create, update, delete, tags, custom fields, snooze
+- **Threads** — list, reply, note, create (chat/customer/phone), update, source, source-rfc822
+- **Customers** — list, get, create, update, overwrite, delete
+- **Mailboxes** — list, get, folders, custom fields, routing
+- **Tags** — list, get
+- **Users** — list, get, me, delete, status
+- **Teams** — list, members
+- **Organizations** — list, get, create, update, delete, conversations, customers, properties
+- **Workflows** — list, run, update-status
+- **Webhooks** — list, get, create, update, delete
+- **Saved Replies** — list, get, create, update, delete
+- **Reports** — chats, company, conversations, customers, docs, email, productivity, ratings, users
+- **Properties** — customer properties, conversation properties
+- **Ratings** — get
+- **Attachments** — upload, list, get, delete
+
+### Docs API (`hs docs ...`)
+
+Full CRUD for all Docs API resources:
+
+- **Articles** — list, search, get, create, update, delete, upload, revisions, drafts, related, view count
+- **Categories** — list, get, create, update, reorder, delete
+- **Collections** — list, get, create, update, delete
+- **Sites** — list, get, create, update, delete, restrictions
+- **Redirects** — list, get, find, create, update, delete
+- **Assets** — article upload, settings upload
+
+## MCP server
+
+Start the embedded MCP server for AI-assisted workflows:
+
+```bash
+npx -y @operatorkit/hs mcp -t stdio
+```
+
+124 MCP tools auto-discovered from the command tree (85 inbox + 39 docs). Management commands (`auth`, `config`, `permissions`) are excluded.
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "helpscout": {
+      "command": "npx",
+      "args": ["-y", "@operatorkit/hs", "mcp", "-t", "stdio"],
+      "env": {
+        "HS_INBOX_APP_ID": "your-app-id",
+        "HS_INBOX_APP_SECRET": "your-app-secret",
+        "HS_DOCS_API_KEY": "your-docs-api-key",
+        "HS_INBOX_PERMISSIONS": "*:read"
+      }
+    }
+  }
+}
+```
+
+## Output formats
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| Table | `--format table` | Human-readable table (default) |
+| JSON | `--format json` | Clean JSON — HAL noise stripped, HTML→markdown, fields normalized |
+| JSON-full | `--format json-full` | Raw API response, pretty-printed |
+| CSV | `--format csv` | RFC 4180 CSV with headers |
+
+## Safety features
+
+- **PII redaction** — deterministic, layered pipeline (structured fields + free-text + source payloads). Modes: `off`, `customers`, `all`.
+- **Permissions** — allowlist-based `resource:operation` pairs restrict which actions are permitted. Set via `HS_INBOX_PERMISSIONS` / `HS_DOCS_PERMISSIONS`.
+- **Rate limiting** — built-in rate limiters respect API quotas (Inbox: 200/min, Docs: 2000/10min).
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `HS_INBOX_APP_ID` | Inbox API App ID |
+| `HS_INBOX_APP_SECRET` | Inbox API App Secret |
+| `HS_DOCS_API_KEY` | Docs API key |
+| `HS_FORMAT` | Default output format |
+| `HS_INBOX_PII_MODE` | PII redaction mode: `off`, `customers`, `all` |
+| `HS_INBOX_PERMISSIONS` | Inbox permission policy |
+| `HS_DOCS_PERMISSIONS` | Docs permission policy |
+
+## Links
+
+- [GitHub](https://github.com/operator-kit/hs-cli)
+- [Issues](https://github.com/operator-kit/hs-cli/issues)
+- [HelpScout API docs](https://developer.helpscout.com/)
+
+## License
+
+[MIT](https://github.com/operator-kit/hs-cli/blob/main/LICENSE)

package/bin/hs.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+function resolveTarget() {
+  const platformMap = {
+    linux: "linux",
+    darwin: "darwin",
+    win32: "windows"
+  };
+  const archMap = {
+    x64: "amd64",
+    arm64: "arm64"
+  };
+
+  const os = platformMap[process.platform];
+  const arch = archMap[process.arch];
+  if (!os || !arch) {
+    throw new Error(
+      `Unsupported platform/arch: ${process.platform}/${process.arch}`
+    );
+  }
+  return { os, arch };
+}
+
+function resolveBinaryPath() {
+  const target = resolveTarget();
+  const exe = process.platform === "win32" ? "hs.exe" : "hs";
+  return path.join(__dirname, "..", "dist", `${target.os}-${target.arch}`, exe);
+}
+
+function main() {
+  const binaryPath = resolveBinaryPath();
+  if (!fs.existsSync(binaryPath)) {
+    console.error(
+      "hs binary is not installed. Reinstall package: npm i -g @operatorkit/hs"
+    );
+    process.exit(1);
+  }
+
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: "inherit"
+  });
+
+  child.on("error", (err) => {
+    console.error(`Failed to start hs: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+main();

package/bin/install.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const https = require("node:https");
+const { pipeline } = require("node:stream/promises");
+
+const AdmZip = require("adm-zip");
+const tar = require("tar");
+
+const REPO_OWNER = "operator-kit";
+const REPO_NAME = "hs-cli";
+
+function resolveTarget() {
+  const platformMap = {
+    linux: "linux",
+    darwin: "darwin",
+    win32: "windows"
+  };
+  const archMap = {
+    x64: "amd64",
+    arm64: "arm64"
+  };
+
+  const osName = platformMap[process.platform];
+  const archName = archMap[process.arch];
+  if (!osName || !archName) {
+    throw new Error(`Unsupported platform/arch: ${process.platform}/${process.arch}`);
+  }
+
+  return {
+    os: osName,
+    arch: archName,
+    archiveExt: osName === "windows" ? ".zip" : ".tar.gz",
+    binaryName: osName === "windows" ? "hs.exe" : "hs"
+  };
+}
+
+function packageVersion() {
+  const pkgPath = path.join(__dirname, "..", "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  return String(pkg.version || "").trim();
+}
+
+function isDevVersion(version) {
+  return (
+    !version ||
+    version === "0.0.0-development" ||
+    version === "0.0.0" ||
+    version.includes("dev")
+  );
+}
+
+function releaseAssetURL(version, target) {
+  const tag = `v${version}`;
+  const asset = `hs_${tag}_${target.os}_${target.arch}${target.archiveExt}`;
+  return {
+    tag,
+    asset,
+    url: `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${asset}`
+  };
+}
+
+function downloadFile(url, destination, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (response) => {
+      if (
+        response.statusCode &&
+        response.statusCode >= 300 &&
+        response.statusCode < 400 &&
+        response.headers.location
+      ) {
+        if (redirects <= 0) {
+          reject(new Error(`Too many redirects while downloading ${url}`));
+          return;
+        }
+        response.resume();
+        resolve(downloadFile(response.headers.location, destination, redirects - 1));
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        const code = response.statusCode || "unknown";
+        response.resume();
+        reject(new Error(`Download failed (${code}): ${url}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destination);
+      pipeline(response, file)
+        .then(() => resolve())
+        .catch(reject);
+    }).on("error", reject);
+  });
+}
+
+async function extractArchive(archivePath, target, distDir) {
+  if (target.archiveExt === ".zip") {
+    const zip = new AdmZip(archivePath);
+    zip.extractAllTo(distDir, true);
+    return;
+  }
+  await tar.x({
+    file: archivePath,
+    cwd: distDir
+  });
+}
+
+function findFile(rootDir, fileName) {
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isFile() && entry.name === fileName) {
+      return entryPath;
+    }
+    if (entry.isDirectory()) {
+      const nested = findFile(entryPath, fileName);
+      if (nested) {
+        return nested;
+      }
+    }
+  }
+  return "";
+}
+
+async function install() {
+  const version = packageVersion();
+  if (isDevVersion(version)) {
+    console.log("Skipping hs binary download for development package version.");
+    return;
+  }
+
+  const target = resolveTarget();
+  const release = releaseAssetURL(version, target);
+  const distDir = path.join(__dirname, "..", "dist", `${target.os}-${target.arch}`);
+  await fs.promises.mkdir(distDir, { recursive: true });
+
+  const tempArchivePath = path.join(
+    os.tmpdir(),
+    `hs-${target.os}-${target.arch}-${Date.now()}${target.archiveExt}`
+  );
+
+  console.log(`Downloading hs ${release.tag} (${target.os}/${target.arch})...`);
+  await downloadFile(release.url, tempArchivePath);
+  await extractArchive(tempArchivePath, target, distDir);
+  fs.unlinkSync(tempArchivePath);
+
+  const binaryPath = path.join(distDir, target.binaryName);
+  if (!fs.existsSync(binaryPath)) {
+    const discovered = findFile(distDir, target.binaryName);
+    if (!discovered) {
+      throw new Error(`Binary ${target.binaryName} not found in downloaded archive.`);
+    }
+    fs.copyFileSync(discovered, binaryPath);
+  }
+
+  if (target.binaryName === "hs") {
+    await fs.promises.chmod(binaryPath, 0o755);
+  }
+
+  console.log(`Installed hs binary to ${binaryPath}`);
+}
+
+install().catch((err) => {
+  console.error(`Failed to install hs binary: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@operatorkit/hs",
+  "version": "0.1.0",
+  "description": "HelpScout CLI with embedded MCP server",
+  "license": "MIT",
+  "homepage": "https://github.com/operator-kit/hs-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/operator-kit/hs-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/operator-kit/hs-cli/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "hs": "bin/hs.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node ./bin/install.js"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "tar": "^7.4.3"
+  }
+}