freshjots 0.2.0 → 0.3.0

package/README.md

@@ -30,12 +30,57 @@ console.log(note.plain_body);
 const notes = await client.notes();
 for (const n of notes) console.log(`${n.filename}\t${n.title}`);
 
-// Create a new note explicitly (errors if the filename is taken).
-await client.create({ filename: "research-2026-q2", body: "Initial outline." });
+// Create a note. The API derives the filename from the title — for a
+// note addressable by an exact filename, use append() instead.
+const created = await client.create({ title: "Research 2026 Q2", body: "Initial outline." });
+console.log(created.filename); // server-derived stream name
 ```
 
 The whole API is four methods: `notes()`, `note(filename)`,
-`create({ filename, body, title })`, `append(filename, text)`.
+`create({ title, body })`, `append(filename, text)`. `note()` and
+`create()` return the note object directly (no `{ note: … }` wrapper);
+`notes()` returns the array.
+
+## CLI
+
+Installing the package globally puts a `freshjots` command on your
+PATH, so you can read and write notes straight from a terminal without
+writing any JavaScript. This works in bash, zsh, fish, Windows
+PowerShell, and CMD — npm generates a `.cmd` shim on Windows
+automatically.
+
+```sh
+npm install -g freshjots
+export FRESHJOTS_TOKEN=mn_…           # PowerShell: $env:FRESHJOTS_TOKEN = "mn_…"
+```
+
+The CLI mirrors the four API methods one-for-one:
+
+```sh
+freshjots list                            # prints "<filename>\t<title>" per row
+freshjots show cron-jobs-prod             # prints the note's plain_body
+freshjots create "Research 2026 Q2"       # body comes from stdin or --body
+freshjots append cron-jobs-prod "ok"      # text may also be piped on stdin
+```
+
+Both `create` and `append` read from stdin when the body or text isn't
+passed as an argument, so the usual pipe patterns work:
+
+```sh
+backup.sh && echo "backup ok $(date -Iseconds)" | freshjots append cron-jobs-prod
+git log -1 --pretty=format:"%h %s" | freshjots append deploys
+```
+
+The same patterns work in PowerShell:
+
+```powershell
+"backup ok $(Get-Date -Format o)" | freshjots append cron-jobs-prod
+freshjots create "Deploy log" --body "Initial entry."
+```
+
+Exit codes: `0` on success, `1` on runtime errors (missing token,
+network failure, non-2xx API response — printed as `Error: HTTP <status>
+<code>: <message>`), `2` on usage errors.
 
 ## TypeScript
 

package/bin/freshjots.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../cli.js";
+
+run(process.argv.slice(2)).then((code) => process.exit(code));

package/cli.js

@@ -0,0 +1,149 @@
+// CLI dispatcher for the `freshjots` command. The shebang entry
+// (bin/freshjots.js) is a one-line wrapper around run() so this module
+// stays import-safe and testable: parseArgs is pure, run takes its I/O
+// surface as deps so tests can stub stdin/stdout/stderr and the Client.
+
+import { Client, ApiError, VERSION } from "./index.js";
+
+const USAGE = `freshjots — Fresh Jots CLI
+
+Usage:
+  freshjots list
+  freshjots show <filename>
+  freshjots create <title> [--body <text>]
+  freshjots append <filename> [<text>]
+  freshjots --help | --version
+
+Notes:
+  - <text> for append and --body for create may also be piped on stdin.
+  - Auth: set FRESHJOTS_TOKEN. Mint one at
+    https://freshjots.com/settings/api_tokens.
+`;
+
+export function parseArgs(argv) {
+  if (argv.length === 0) return { command: "help", exitCode: 2 };
+  const [first, ...rest] = argv;
+
+  if (first === "-h" || first === "--help" || first === "help") {
+    return { command: "help", exitCode: 0 };
+  }
+  if (first === "-v" || first === "--version" || first === "version") {
+    return { command: "version" };
+  }
+  if (first === "list") {
+    if (rest.length) return { command: "error", message: "list takes no arguments" };
+    return { command: "list" };
+  }
+  if (first === "show") {
+    if (rest.length !== 1) return { command: "error", message: "show requires exactly one <filename>" };
+    return { command: "show", filename: rest[0] };
+  }
+  if (first === "create") {
+    let body;
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === "--body" || a === "-b") {
+        if (i + 1 >= rest.length) return { command: "error", message: "--body requires a value" };
+        body = rest[++i];
+      } else if (a.startsWith("--body=")) {
+        body = a.slice("--body=".length);
+      } else {
+        positional.push(a);
+      }
+    }
+    if (positional.length !== 1) return { command: "error", message: "create requires exactly one <title>" };
+    return { command: "create", title: positional[0], body };
+  }
+  if (first === "append") {
+    if (rest.length < 1 || rest.length > 2) {
+      return { command: "error", message: "append requires <filename> and optional <text>" };
+    }
+    return { command: "append", filename: rest[0], text: rest[1] };
+  }
+  return { command: "error", message: `unknown command: ${first}` };
+}
+
+async function readStdin(stdin) {
+  if (!stdin || stdin.isTTY) return "";
+  let buf = "";
+  for await (const chunk of stdin) {
+    buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+  }
+  return buf;
+}
+
+export async function run(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const stdout = deps.stdout ?? ((s) => process.stdout.write(s));
+  const stderr = deps.stderr ?? ((s) => process.stderr.write(s));
+  const stdin = deps.stdin ?? process.stdin;
+  const clientFactory = deps.clientFactory ?? ((token) => new Client({ token }));
+
+  const parsed = parseArgs(argv);
+
+  if (parsed.command === "help") {
+    (parsed.exitCode ? stderr : stdout)(USAGE);
+    return parsed.exitCode ?? 0;
+  }
+  if (parsed.command === "version") {
+    stdout(`freshjots ${VERSION}\n`);
+    return 0;
+  }
+  if (parsed.command === "error") {
+    stderr(`Error: ${parsed.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const token = env.FRESHJOTS_TOKEN;
+  if (!token) {
+    stderr("Error: FRESHJOTS_TOKEN is not set. Mint one at https://freshjots.com/settings/api_tokens\n");
+    return 1;
+  }
+
+  let client;
+  try {
+    client = clientFactory(token);
+  } catch (e) {
+    stderr(`Error: ${e.message}\n`);
+    return 1;
+  }
+
+  try {
+    if (parsed.command === "list") {
+      const notes = await client.notes();
+      for (const n of notes) stdout(`${n.filename}\t${n.title}\n`);
+      return 0;
+    }
+    if (parsed.command === "show") {
+      const note = await client.note(parsed.filename);
+      stdout(note.plain_body ?? "");
+      return 0;
+    }
+    if (parsed.command === "create") {
+      let body = parsed.body;
+      if (body === undefined) body = await readStdin(stdin);
+      const created = await client.create({ title: parsed.title, body });
+      stdout(`${created.filename}\n`);
+      return 0;
+    }
+    if (parsed.command === "append") {
+      let text = parsed.text;
+      if (text === undefined) text = await readStdin(stdin);
+      if (!text) {
+        stderr("Error: append requires text (as an argument or on stdin)\n");
+        return 2;
+      }
+      await client.append(parsed.filename, text);
+      return 0;
+    }
+  } catch (e) {
+    if (e instanceof ApiError) {
+      stderr(`Error: HTTP ${e.status} ${e.code}: ${e.message}\n`);
+    } else {
+      stderr(`Error: ${e.message}\n`);
+    }
+    return 1;
+  }
+  return 0;
+}

package/index.d.ts

@@ -61,10 +61,14 @@ declare module "freshjots" {
     baseUrl?: string;
   }
 
+  /**
+   * Input for `create()`. The API derives the note's filename from the
+   * title (it does not accept a client-supplied filename). For a note
+   * addressable by an exact, caller-chosen filename, use `append()`.
+   */
   export interface CreateInput {
-    filename: string;
+    title: string;
     body?: string;
-    title?: string;
   }
 
   export class Client {

package/index.js

@@ -7,12 +7,18 @@
 //   await client.append("cron-jobs-prod", "backup ok");
 //   const note = await client.note("cron-jobs-prod");
 //   console.log(note.plain_body);
+//   const created = await client.create({ title: "Deploy log" });
+//   console.log(created.filename);            // server-derived from the title
 //
 // Requires Node 18+ (uses global fetch). All methods throw ApiError on
 // non-2xx responses, with the code/status/details from the API's stable
 // error envelope.
+//
+// Note on response shapes: GET /notes is the only endpoint that wraps its
+// payload ({ "notes": [...] }). show / show-by-filename / create return
+// the note object at the TOP LEVEL — there is no { "note": ... } wrapper.
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.3.0";
 const DEFAULT_BASE_URL = "https://freshjots.com/api/v1";
 
 export class ApiError extends Error {
@@ -39,14 +45,27 @@ export class Client {
   }
 
   async note(filename) {
+    // show-by-filename renders the serializer at the top level (no
+    // { note: ... } wrapper), so return the response as-is.
     const path = `/notes/by-filename/${encodeURIComponent(filename)}`;
-    return (await this._request("GET", path)).note;
+    return await this._request("GET", path);
   }
 
-  async create({ filename, body = "", title }) {
-    const note = { filename, plain_body: body, format: "plain" };
-    if (title) note.title = title;
-    return (await this._request("POST", "/notes", { note })).note;
+  // Create a note. The API permits note[title, plain_body, format, ...]
+  // — NOT filename: the server DERIVES the filename from the title. For
+  // a note addressable by an exact, caller-chosen filename, use append()
+  // (the by-filename endpoint creates it with that exact name on first
+  // call). Returns the created note (top level); read `.filename` for
+  // the server-derived stream name.
+  async create({ title, body = "" }) {
+    if (!title) {
+      throw new Error(
+        "create requires a title — the API derives the filename from it. " +
+          "For a note addressable by an exact filename, use append().",
+      );
+    }
+    const note = { title, plain_body: body, format: "plain" };
+    return await this._request("POST", "/notes", { note });
   }
 
   async append(filename, text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freshjots",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Tiny JavaScript client for the Fresh Jots API. Append-only notebooks for cron jobs, deploy scripts, and bots.",
   "type": "module",
   "main": "index.js",
@@ -11,9 +11,14 @@
       "default": "./index.js"
     }
   },
+  "bin": {
+    "freshjots": "./bin/freshjots.js"
+  },
   "files": [
     "index.js",
     "index.d.ts",
+    "cli.js",
+    "bin/",
     "README.md",
     "LICENSE"
   ],