@hunt-labs/bytekit-cli 0.2.0 → 0.3.0

package/dist/output.js

@@ -1,4 +1,5 @@
 import { writeFileSync } from 'node:fs';
+import { isFetchBodyResult } from './lib/fetch-body.js';
 /** Text formats whose bodies are strings and can therefore be emitted raw. */
 const TEXT_FORMATS = 'markdown, html, raw_html';
 /**
@@ -71,18 +72,56 @@ export function extractRawBody(response, requestedFormat) {
     }
     return value;
 }
+/**
+ * Exit code for `--raw`/`-o` against a 202 queued (async) scrape.
+ *
+ * Deliberately NOT 0 (a full raw-body success) and NOT 1 (a usage/API error): the job WAS accepted
+ * and billed, there is simply no content body to emit yet. A distinct code lets a caller branch on
+ * "queued" without parsing stderr.
+ */
+export const QUEUED_RAW_EXIT_CODE = 2;
+/** Is `result` a 202 queued scrape envelope carrying a job id? */
+function isQueuedEnvelope(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const obj = result;
+    return obj.status === 'queued' && typeof obj.id === 'string' && obj.id.length > 0;
+}
+/**
+ * Handle `--raw`/`-o` on a 202 queued envelope.
+ *
+ * The user asked for a content body that does not exist yet — but the job was accepted, so losing
+ * the handle (the old behaviour: throw `--raw: response contains no formats`, exit 1) is the real
+ * defect. Instead: emit the `sc_` id to STDOUT so `$(bytekit scrape create … --raw)` still captures
+ * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and exit
+ * with {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ */
+export function emitQueuedRaw(env) {
+    console.error(`Note: scrape ${env.id} was queued (async) — no content body is available yet. ` +
+        `Poll it with: bytekit scrape get ${env.id}`);
+    process.stdout.write(`${env.id}\n`);
+    process.exit(QUEUED_RAW_EXIT_CODE);
+}
 /**
  * Emit a raw body to the target.
  *
- * Uses `process.stdout.write`, never `console.log`: `console.log` appends a newline, which would
- * make the stdout bytes and the `--output` file bytes differ.
+ * Uses `process.stdout.write`, never `console.log`: `console.log` unconditionally appends a newline,
+ * which would make the stdout bytes and the `--output` file bytes differ.
+ *
+ * Trailing-newline rule (#2452 item 6): a body has no guaranteed trailing newline (a scraped markdown
+ * page rarely ends in one), so a naked `--raw` glued the shell prompt onto the last line. When stdout
+ * is an interactive TTY we append a single newline (idempotent — never doubling an existing one) so the
+ * prompt starts cleanly. Off a TTY (a pipe or `>`/`>>` redirect) we write the body verbatim, preserving
+ * the byte-exact invariant that `--raw > file` matches `--output file`. A FILE destination is never
+ * touched by this rule at all.
  */
 export function emitRaw(body, target) {
     if (target.file !== undefined) {
         writeFileSync(target.file, body);
         return;
     }
-    process.stdout.write(body);
+    const appendNewline = process.stdout.isTTY === true && !body.endsWith('\n');
+    process.stdout.write(appendNewline ? `${body}\n` : body);
 }
 /**
  * The single output dispatch a command calls — so no command needs `node:fs` and every rendering
@@ -93,6 +132,14 @@ export function emitRaw(body, target) {
  */
 export function emitResult(result, mode, target, requestedFormat) {
     if (mode.kind === 'raw') {
+        // A 202 queued scrape has no format body to print — surface its `sc_` handle instead of
+        // throwing away the accepted (and billed) job. Scoped to raw mode only: json/human rendering
+        // of a queued envelope stays unchanged (falls through to printResult below). A `-o <file>`
+        // target is deliberately ignored here (id always on STDOUT, never written to the file): there
+        // is no content body yet, and a file holding a bare `sc_` id would masquerade as content.
+        if (isQueuedEnvelope(result)) {
+            emitQueuedRaw(result);
+        }
         emitRaw(extractRawBody(result, requestedFormat), target);
         return;
     }
@@ -107,6 +154,28 @@ export function emitResult(result, mode, target, requestedFormat) {
     // human — unreachable with a file destination (resolveOutputMode never yields it alongside one).
     printResult(result, false);
 }
+/**
+ * Render a `/v1/fetch` content result.
+ *
+ * The transport hands back a {@link FetchBodyResult} whose body IS the fetched content and whose
+ * metadata are the `X-Fetch-*` headers. Default: write the raw body bytes to stdout verbatim
+ * (`process.stdout.write`, never `console.log` — no coercion, no appended newline, binary-safe).
+ * With `--json`: print the `X-Fetch-*` metadata as JSON instead of the body.
+ *
+ * Falls back to {@link printResult} for any result that is not a fetch body (defensive — e.g. a
+ * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
+ */
+export function emitFetchResult(result, jsonMode) {
+    if (isFetchBodyResult(result)) {
+        if (jsonMode) {
+            console.log(JSON.stringify(result.metadata, null, 2));
+            return;
+        }
+        process.stdout.write(result.body);
+        return;
+    }
+    printResult(result, jsonMode);
+}
 /**
  * Print a result to stdout.
  *
@@ -131,19 +200,52 @@ export function printResult(data, jsonMode) {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/** The SDK error classes whose `code` is a ByteKit diagnostic worth surfacing as a suffix. */
+const BYTEKIT_ERROR_NAMES = new Set(['ByteKitError', 'ByteKitConnectionError']);
+/**
+ * A non-empty API/connection error `code`, or undefined when absent.
+ *
+ * Scoped by `err.name` to the ByteKit taxonomy: plenty of OTHER errors also carry a string
+ * `.code` — Node fs/system errors (ENOENT from `parseUrlLines`'s readFileSync, EACCES on a `-o`
+ * write) — whose message already embeds the code, so suffixing them would render the redundant
+ * `Error: ENOENT: … (ENOENT)`. Only `ByteKitError` / `ByteKitConnectionError` codes qualify.
+ */
+function errorCode(err) {
+    if (!BYTEKIT_ERROR_NAMES.has(err.name))
+        return undefined;
+    const raw = err.code;
+    return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+}
 /**
  * Handle a CLI command error: print to stderr and exit 1.
+ *
+ * The message always begins `Error: ` (a prefix scripts grep on) followed by the error message and
+ * an optional parenthesised suffix built from the two diagnostic axes the ByteKit errors carry:
+ *
+ * - a `ByteKitError` from the transport carries both a numeric `status` and an API `code`
+ *   (`rate_limited`, `invalid_url`, …) → `Error: <message> (<code>, status: <n>)`;
+ * - a `ByteKitConnectionError` (client-side timeout / abort / socket failure) carries a `code`
+ *   (`timeout` | `aborted` | `connection`) but NO status → `Error: <message> (<code>)`;
+ * - a plain error with neither → `Error: <message>`.
+ *
+ * The `code` axis is read only off the two ByteKit error classes (see {@link errorCode}) — a plain
+ * error carrying an unrelated string `.code` (a Node errno error) gets NO code suffix. When a
+ * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
+ * placeholder — never `(, status: <n>)`.
  */
 export function handleError(err) {
     if (err instanceof Error) {
-        const hasStatus = 'status' in err && typeof err.status === 'number';
+        const status = err.status;
+        const hasStatus = typeof status === 'number';
+        const code = errorCode(err);
+        let suffix = '';
         if (hasStatus) {
-            const apiErr = err;
-            console.error(`Error: ${apiErr.message} (status: ${apiErr.status})`);
+            suffix = code !== undefined ? ` (${code}, status: ${status})` : ` (status: ${status})`;
         }
-        else {
-            console.error(`Error: ${err.message}`);
+        else if (code !== undefined) {
+            suffix = ` (${code})`;
         }
+        console.error(`Error: ${err.message}${suffix}`);
     }
     else {
         console.error(`Error: ${String(err)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -32,19 +32,16 @@
   ],
   "homepage": "https://bytekit.com/docs",
   "bugs": {
-    "email": "support@bytekit.com"
+    "email": "support@bytekit.com",
+    "url": "https://bytekit.com/contact"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.2.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "@hunt-labs/bytekit-sdk": "^0.3.0"
   },
   "scripts": {
     "build": "tsc",

package/dist/commands/recordings.d.ts

@@ -1,5 +0,0 @@
-import { Command } from 'commander';
-import { type GlobalOptions } from '../client.js';
-export declare function makeRecordingsCommand(getGlobal: () => GlobalOptions & {
-    json: boolean;
-}): Command;

package/dist/commands/recordings.js

@@ -1,36 +0,0 @@
-import { Command } from 'commander';
-import { buildClient } from '../client.js';
-import { printResult, handleError } from '../output.js';
-export function makeRecordingsCommand(getGlobal) {
-    const cmd = new Command('recordings').description('Recording operations');
-    cmd
-        .command('create')
-        .description('Start a page recording')
-        .requiredOption('--url <url>', 'URL to record')
-        .action(async (opts) => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            const result = await client.recordings.create({ url: opts.url });
-            printResult(result, g.json);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    });
-    cmd
-        .command('get <id>')
-        .description('Get a recording by ID')
-        .action(async (id) => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            const result = await client.recordings.get(id);
-            printResult(result, g.json);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    });
-    return cmd;
-}