highspot-cli 0.1.1 → 0.2.0

package/README.md

@@ -72,8 +72,7 @@ Example `.highspot-cli.json`:
 
 ```bash
 highspot search <query>
-highspot item <item-id>
-highspot content <item-id>
+highspot get <item-id>
 highspot me
 ```
 
@@ -94,6 +93,15 @@ Global flags:
 - `--no-input`
 - `--no-color`
 
+`get` command flags:
+
+- `--format <value>`
+- `--start <value>`
+- `--meta-only` (skip content download)
+- `-o, --output <path>` (explicit file path)
+- `--output-dir <path>` (directory for auto-saved binary files)
+- `-f, --force` (overwrite existing output file)
+
 Exit codes:
 
 - `0` success
@@ -105,8 +113,11 @@ Exit codes:
 ```bash
 highspot search "GoGuardian Teacher" --limit 10
 highspot search "Beacon" --sort-by date_added --plain
-highspot item it_abc123
-highspot content it_abc123 --format text/plain --plain
+highspot get it_abc123 --meta-only
+highspot get it_abc123 --format text/plain --plain
+highspot get it_abc123
+highspot get it_abc123 --output ./custom-filename.pdf
+highspot get it_abc123 --output-dir ./downloads
 highspot me --json
 highspot search "Fleet" --dry-run
 ```
@@ -115,6 +126,9 @@ Behavior notes:
 
 - Prompts are not used; `--no-input` is accepted for automation consistency.
 - Primary data goes to stdout, errors go to stderr.
+- `get` always fetches `/items/{id}` metadata first, then fetches `/items/{id}/content` unless `--meta-only` is set.
+- Binary content is automatically saved to disk using Highspot `content_name` (canonical filename) when available.
+- Use `--output` to force a specific filename/path, or `--output-dir` to control where auto-saved binaries are written.
 
 ## Development
 

package/dist/commands/get.js

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, extname, join, resolve } from "node:path";
+import { Args } from "@oclif/core";
+import { BaseCommand } from "../lib/command.js";
+import { contentFlags, globalFlags } from "../lib/flags.js";
+export default class Get extends BaseCommand {
+    static description = "Fetch item metadata and content in one command";
+    static examples = [
+        "highspot get it_abc123",
+        "highspot get it_abc123 --meta-only",
+        "highspot get it_abc123 --output ./discover-guide.pdf",
+        "highspot get it_abc123 --output-dir ./downloads",
+        "highspot get it_abc123 --format text/plain --plain",
+    ];
+    static args = {
+        itemId: Args.string({
+            description: "Highspot item id",
+            required: false,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        ...contentFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(Get);
+        this.ensureOutputFlags(flags);
+        this.ensureVerbosityFlags(flags);
+        if (!args.itemId) {
+            this.fail("itemId is required", 2, flags);
+        }
+        const payload = {
+            operations: [
+                { endpoint: `/items/${encodeURIComponent(args.itemId)}` },
+                ...(flags["meta-only"]
+                    ? []
+                    : [
+                        {
+                            endpoint: `/items/${encodeURIComponent(args.itemId)}/content`,
+                            query: {
+                                ...(flags.format ? { format: flags.format } : {}),
+                                ...(flags.start ? { start: flags.start } : {}),
+                            },
+                        },
+                    ]),
+            ],
+            output: {
+                ...(flags.output ? { output: flags.output } : {}),
+                ...(flags["output-dir"] ? { outputDir: flags["output-dir"] } : {}),
+                force: flags.force,
+            },
+            headers: {
+                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
+            },
+        };
+        if (flags["dry-run"]) {
+            this.printJson(payload);
+            return;
+        }
+        try {
+            const client = this.clientFromFlags(flags);
+            const itemData = await client.getItem({
+                itemId: args.itemId,
+                hsUser: this.effectiveHsUser(flags),
+            });
+            const item = asItemRecord(itemData.item);
+            if (flags["meta-only"]) {
+                if (this.outputMode(flags) === "plain") {
+                    writeItemPlain(item);
+                    return;
+                }
+                this.printJson({ item });
+                return;
+            }
+            const contentData = await client.getItemContent({
+                itemId: args.itemId,
+                format: flags.format,
+                start: flags.start,
+                hsUser: this.effectiveHsUser(flags),
+            });
+            const explicitOutputPath = flags.output
+                ? resolve(process.cwd(), flags.output)
+                : undefined;
+            if (contentData.kind === "binary") {
+                const binaryOutputPath = explicitOutputPath ??
+                    resolveBinaryOutputPath({
+                        outputDir: flags["output-dir"],
+                        item,
+                        itemId: args.itemId,
+                        contentType: contentData.contentType,
+                    });
+                const fileResult = await writeBytesToFile({
+                    bytes: contentData.bytes,
+                    contentType: contentData.contentType,
+                    force: flags.force,
+                    item,
+                    itemId: args.itemId,
+                    outputPath: binaryOutputPath,
+                });
+                if (this.outputMode(flags) === "plain") {
+                    writeFileResultPlain(fileResult);
+                    return;
+                }
+                this.printJson(fileResult);
+                return;
+            }
+            if (explicitOutputPath) {
+                const fileResult = await writeInlineContentToFile({
+                    content: contentData,
+                    force: flags.force,
+                    item,
+                    itemId: args.itemId,
+                    outputPath: explicitOutputPath,
+                });
+                if (this.outputMode(flags) === "plain") {
+                    writeFileResultPlain(fileResult);
+                    return;
+                }
+                this.printJson(fileResult);
+                return;
+            }
+            if (this.outputMode(flags) === "plain") {
+                writeInlineContentPlain(contentData);
+                return;
+            }
+            this.printJson({
+                item,
+                mode: "inline",
+                isBinary: false,
+                contentType: contentData.contentType,
+                content: contentData.content,
+            });
+        }
+        catch (error) {
+            this.handleError(error, flags);
+        }
+    }
+}
+function asItemRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function writeItemPlain(item) {
+    const id = asString(item.id);
+    const url = asString(item.url);
+    const title = asString(item.title);
+    const contentType = asString(item.content_type);
+    const contentName = asString(item.content_name);
+    process.stdout.write(`${id}\t${url}\t${title}\t${contentType}\t${contentName}\n`);
+}
+function writeInlineContentPlain(content) {
+    if (content.kind === "text") {
+        process.stdout.write(content.content);
+        if (!content.content.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+        return;
+    }
+    if (content.kind === "json") {
+        process.stdout.write(`${JSON.stringify(content.content, null, 2)}\n`);
+        return;
+    }
+    throw new Error("Binary content must be written to a file.");
+}
+function writeFileResultPlain(result) {
+    process.stdout.write(`${result.itemId}\t${result.outputPath}\t${result.contentType}\t${result.sizeBytes}\t${result.sha256}\n`);
+}
+function resolveBinaryOutputPath(args) {
+    const outputDir = args.outputDir
+        ? resolve(process.cwd(), args.outputDir)
+        : process.cwd();
+    const fileName = preferredBinaryFileName(args.item, args.itemId, args.contentType);
+    return join(outputDir, fileName);
+}
+function preferredBinaryFileName(item, itemId, contentType) {
+    const candidates = [
+        item.content_name,
+        item.filename,
+        item.file_name,
+        item.name,
+        item.title,
+    ]
+        .map((value) => asString(value).trim())
+        .filter((value) => value.length > 0);
+    const baseCandidate = candidates[0] ?? itemId;
+    const safeBase = sanitizeFileName(baseCandidate) || itemId;
+    if (extname(safeBase)) {
+        return safeBase;
+    }
+    const extension = extensionFromContentType(contentType) ?? "bin";
+    return `${safeBase}.${extension}`;
+}
+function sanitizeFileName(input) {
+    const invalidChars = new Set(["\\", "/", ":", "*", "?", '"', "<", ">", "|"]);
+    let output = "";
+    for (const char of input) {
+        const code = char.charCodeAt(0);
+        if (code >= 0 && code < 32) {
+            output += "_";
+            continue;
+        }
+        output += invalidChars.has(char) ? "_" : char;
+    }
+    return output.replace(/\s+/g, " ").trim();
+}
+function extensionFromContentType(contentType) {
+    const normalized = contentType.toLowerCase();
+    if (normalized.includes("pdf")) {
+        return "pdf";
+    }
+    if (normalized.includes("json")) {
+        return "json";
+    }
+    if (normalized.includes("csv")) {
+        return "csv";
+    }
+    if (normalized.startsWith("text/")) {
+        return "txt";
+    }
+    return undefined;
+}
+async function writeBytesToFile(args) {
+    await ensureWriteablePath(args.outputPath, args.force);
+    await writeFile(args.outputPath, args.bytes);
+    return {
+        contentType: args.contentType,
+        item: args.item,
+        itemId: args.itemId,
+        mode: "file",
+        outputPath: args.outputPath,
+        sha256: createHash("sha256").update(args.bytes).digest("hex"),
+        sizeBytes: args.bytes.byteLength,
+    };
+}
+async function writeInlineContentToFile(args) {
+    await ensureWriteablePath(args.outputPath, args.force);
+    const text = args.content.kind === "text"
+        ? args.content.content
+        : `${JSON.stringify(args.content.content, null, 2)}\n`;
+    await writeFile(args.outputPath, text, "utf8");
+    return {
+        contentType: args.content.contentType,
+        item: args.item,
+        itemId: args.itemId,
+        mode: "file",
+        outputPath: args.outputPath,
+        sha256: createHash("sha256").update(text, "utf8").digest("hex"),
+        sizeBytes: Buffer.byteLength(text, "utf8"),
+    };
+}
+async function ensureWriteablePath(path, force) {
+    await mkdir(dirname(path), { recursive: true });
+    if (existsSync(path) && !force) {
+        throw new Error(`Output file already exists: ${path}. Use --force to overwrite.`);
+    }
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}

package/dist/lib/api.js

@@ -160,8 +160,8 @@ export class HighspotClient {
         if (contentType.includes("json")) {
             const payload = (await response.json());
             return {
+                kind: "json",
                 content: payload,
-                contentEncoding: "json",
                 contentType,
                 isBinary: false,
                 isJson: true,
@@ -171,8 +171,8 @@ export class HighspotClient {
         if (!looksTextual(contentType)) {
             const binary = await response.arrayBuffer();
             return {
-                content: Buffer.from(binary).toString("base64"),
-                contentEncoding: "base64",
+                kind: "binary",
+                bytes: new Uint8Array(binary),
                 contentLength: binary.byteLength,
                 contentType,
                 isBinary: true,
@@ -182,8 +182,8 @@ export class HighspotClient {
         }
         const textContent = await response.text();
         return {
+            kind: "text",
             content: textContent,
-            contentEncoding: "utf8",
             contentLength: textContent.length,
             contentType,
             isBinary: false,

package/dist/lib/command.js

@@ -43,6 +43,9 @@ export class BaseCommand extends Command {
         this.exit(exitCode);
     }
     handleError(error, flags) {
+        if (error instanceof Error && /^EEXIT:\s*\d+/.test(error.message)) {
+            throw error;
+        }
         const mode = this.outputMode(flags);
         if (error instanceof ApiError) {
             writeError(mode, formatApiError(error));

package/dist/lib/flags.js

@@ -72,4 +72,20 @@ export const contentFlags = {
     start: Flags.string({
         description: "Optional cursor/start token for paginated content",
     }),
+    output: Flags.string({
+        char: "o",
+        description: "Write content body to a specific file path",
+    }),
+    "output-dir": Flags.string({
+        description: "Directory for auto-saved binary content (default: current working directory)",
+    }),
+    "meta-only": Flags.boolean({
+        description: "Return item metadata only (skip content download)",
+        default: false,
+    }),
+    force: Flags.boolean({
+        char: "f",
+        description: "Allow overwriting an existing output file",
+        default: false,
+    }),
 };

package/dist/lib/help.js

@@ -9,8 +9,8 @@ export default class Help extends OclifHelp {
         const examples = this.section("EXAMPLES", this.renderList([
             ["highspot --help"],
             ['highspot search "GoGuardian Teacher" --limit 5'],
-            ["highspot item it_abc123 --plain"],
-            ["highspot content it_abc123 --format text/plain --plain"],
+            ["highspot get it_abc123 --meta-only"],
+            ["highspot get it_abc123 --output ./discover-guide.pdf"],
             ["highspot me --json"],
         ], { indentation: 2, spacer: "\n", stripAnsi: this.opts.stripAnsi }));
         return `${base}\n\n${auth}\n\n${config}\n\n${examples}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "highspot-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Agent-first CLI for the Highspot API",
   "license": "MIT",
   "author": "Advait Shinde",
@@ -18,7 +18,7 @@
     "highspot-cli": "dist/bin/highspot.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
     "dev": "npm run build && node dist/bin/highspot.js",
     "lint": "biome check .",
     "format": "biome format --write .",

package/dist/commands/content.js

@@ -1,70 +0,0 @@
-import { Args } from "@oclif/core";
-import { BaseCommand } from "../lib/command.js";
-import { contentFlags, globalFlags } from "../lib/flags.js";
-export default class Content extends BaseCommand {
-    static description = "Fetch Highspot item content";
-    static examples = [
-        "highspot content it_abc123",
-        "highspot content it_abc123 --format text/plain --plain",
-        "highspot content it_abc123 --start cursor-2",
-    ];
-    static args = {
-        itemId: Args.string({
-            description: "Highspot item id",
-            required: false,
-        }),
-    };
-    static flags = {
-        ...globalFlags,
-        ...contentFlags,
-    };
-    async run() {
-        const { args, flags } = await this.parse(Content);
-        this.ensureOutputFlags(flags);
-        this.ensureVerbosityFlags(flags);
-        if (!args.itemId) {
-            this.fail("itemId is required", 2, flags);
-        }
-        const payload = {
-            endpoint: `/items/${encodeURIComponent(args.itemId)}/content`,
-            query: {
-                ...(flags.format ? { format: flags.format } : {}),
-                ...(flags.start ? { start: flags.start } : {}),
-            },
-            headers: {
-                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
-            },
-        };
-        if (flags["dry-run"]) {
-            this.printJson(payload);
-            return;
-        }
-        try {
-            const client = this.clientFromFlags(flags);
-            const data = await client.getItemContent({
-                itemId: args.itemId,
-                format: flags.format,
-                start: flags.start,
-                hsUser: this.effectiveHsUser(flags),
-            });
-            if (this.outputMode(flags) === "plain") {
-                writeContentPlain(data.content);
-                return;
-            }
-            this.printJson(data);
-        }
-        catch (error) {
-            this.handleError(error, flags);
-        }
-    }
-}
-function writeContentPlain(content) {
-    if (typeof content === "string") {
-        process.stdout.write(content);
-        if (!content.endsWith("\n")) {
-            process.stdout.write("\n");
-        }
-        return;
-    }
-    process.stdout.write(`${JSON.stringify(content, null, 2)}\n`);
-}

package/dist/commands/item.js

@@ -1,66 +0,0 @@
-import { Args } from "@oclif/core";
-import { BaseCommand } from "../lib/command.js";
-import { globalFlags } from "../lib/flags.js";
-export default class Item extends BaseCommand {
-    static description = "Fetch metadata for a Highspot item";
-    static examples = [
-        "highspot item it_abc123",
-        "highspot item it_abc123 --hs-user user@example.com",
-        "highspot item it_abc123 --plain",
-    ];
-    static args = {
-        itemId: Args.string({
-            description: "Highspot item id",
-            required: false,
-        }),
-    };
-    static flags = {
-        ...globalFlags,
-    };
-    async run() {
-        const { args, flags } = await this.parse(Item);
-        this.ensureOutputFlags(flags);
-        this.ensureVerbosityFlags(flags);
-        if (!args.itemId) {
-            this.fail("itemId is required", 2, flags);
-        }
-        const payload = {
-            endpoint: `/items/${encodeURIComponent(args.itemId)}`,
-            headers: {
-                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
-            },
-        };
-        if (flags["dry-run"]) {
-            this.printJson(payload);
-            return;
-        }
-        try {
-            const client = this.clientFromFlags(flags);
-            const data = await client.getItem({
-                itemId: args.itemId,
-                hsUser: this.effectiveHsUser(flags),
-            });
-            if (this.outputMode(flags) === "plain") {
-                writeItemPlain(data.item);
-                return;
-            }
-            this.printJson(data);
-        }
-        catch (error) {
-            this.handleError(error, flags);
-        }
-    }
-}
-function writeItemPlain(item) {
-    if (typeof item !== "object" || item === null || Array.isArray(item)) {
-        process.stdout.write(`${JSON.stringify(item)}\n`);
-        return;
-    }
-    const record = item;
-    const id = typeof record.id === "string" ? record.id : "";
-    const title = typeof record.title === "string" ? record.title : "";
-    const url = typeof record.url === "string" ? record.url : "";
-    const contentType = typeof record.content_type === "string" ? record.content_type : "";
-    const description = typeof record.description === "string" ? record.description : "";
-    process.stdout.write(`${id}\t${url}\t${title}\t${contentType}\t${description}\n`);
-}