freshjots 0.2.1 → 0.4.0

package/README.md

@@ -1,4 +1,4 @@
-# freshjots — JavaScript
+# freshjots — JS, TS, Windows CLI 
 
 Tiny JavaScript client for the [Fresh Jots](https://freshjots.com) API.
 One file, zero dependencies (uses Node 18's global `fetch`).
@@ -26,9 +26,9 @@ await client.append("cron-jobs-prod", "backup ok");
 const note = await client.note("cron-jobs-prod");
 console.log(note.plain_body);
 
-// List your notes.
-const notes = await client.notes();
-for (const n of notes) console.log(`${n.filename}\t${n.title}`);
+// List your notes (most recent activity first). Pass options to sort/filter:
+const notes = await client.notes({ sort: "created", folderId: 3, limit: 20 });
+for (const n of notes) console.log(`${n.id}\t${n.filename}\t${n.title}`);
 
 // Create a note. The API derives the filename from the title — for a
 // note addressable by an exact filename, use append() instead.
@@ -36,10 +36,61 @@ const created = await client.create({ title: "Research 2026 Q2", body: "Initial
 console.log(created.filename); // server-derived stream name
 ```
 
-The whole API is four methods: `notes()`, `note(filename)`,
-`create({ title, body })`, `append(filename, text)`. `note()` and
-`create()` return the note object directly (no `{ note: … }` wrapper);
-`notes()` returns the array.
+Client methods: `notes({ sort, folderId, limit, offset })`,
+`note(filename)`, `noteById(id)`, `create({ title, body })`,
+`append(filename, text)`, `remove(id)`, `move(id, folderId)`, and
+`folders()`. `note()`/`noteById()`/`create()` return the note object
+directly (no `{ note: … }` wrapper); `notes()` and `folders()` return
+arrays. For `notes()`, `sort` is `created|updated|appended` and
+`folderId` may be a folder id or `"none"` (un-foldered only).
+
+## 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 covers reading, writing, and organizing notes:
+
+```sh
+freshjots ls                              # prints "<id>\t<filename>\t<title>" per row
+freshjots ls -n 10 --sort created         # last 10 by creation (--sort created|updated|appended)
+freshjots ls --folder Work                # filter by folder id or name; --root for un-foldered
+freshjots ls --all -l                     # every page, long format (id, updated, lock, folder, …)
+freshjots get 42                          # full note as JSON
+freshjots cat cron-jobs-prod              # note body, by id or filename
+freshjots create "Research 2026 Q2"       # body from stdin or --body
+freshjots append cron-jobs-prod "ok"      # text may also be piped on stdin
+freshjots rm cron-jobs-prod               # delete by id or filename
+freshjots mv cron-jobs-prod Work          # move into a folder (id or name); --root to un-folder
+freshjots folders                         # prints "<id>\t<name>" per row
+```
+
+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
 
@@ -92,8 +143,8 @@ Stable error codes: `unauthenticated`, `forbidden`, `not_found`,
 
 ## Auth
 
-Mint a token at <https://freshjots.com/settings/api_tokens> (Dev or
-Dev-pro tier required). Set it once:
+Mint a token at <https://freshjots.com/settings/api_tokens> (Pro or
+Team tier required). Set it once:
 
 ```sh
 export FRESHJOTS_TOKEN=<your-token>

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,271 @@
+// 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 ls [flags]                 List notes as id<TAB>filename<TAB>title.
+                                         -n N | --limit N
+                                         --sort created|updated|appended
+                                         --folder <id|name> | --root
+                                         --all      fetch every page (past the 200 cap)
+                                         -l|--long  id, updated_at, lock, folder, name, title
+  freshjots get <id>                   Print a note as JSON (full metadata).
+  freshjots cat <id|filename>          Print a note's body.
+  freshjots create <title> [--body <text>]
+  freshjots append <filename> [<text>]
+  freshjots rm <id|filename>           Delete a note.
+  freshjots mv <id|filename> <folder-id|name|--root>
+  freshjots folders                    List folders as id<TAB>name.
+  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.
+`;
+
+const isNumeric = (s) => /^\d+$/.test(s);
+const errResult = (message) => ({ command: "error", message });
+
+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" || first === "ls") {
+    const opts = { command: "list", limit: null, sort: null, folder: null, all: false, long: false };
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === "-n" || a === "--limit") {
+        if (i + 1 >= rest.length) return errResult("--limit requires a value");
+        opts.limit = rest[++i];
+      } else if (a === "--sort") {
+        if (i + 1 >= rest.length) return errResult("--sort requires a value");
+        opts.sort = rest[++i];
+      } else if (a === "--folder") {
+        if (i + 1 >= rest.length) return errResult("--folder requires a value");
+        opts.folder = rest[++i];
+      } else if (a === "--root") {
+        opts.folder = "none";
+      } else if (a === "--all") {
+        opts.all = true;
+      } else if (a === "-l" || a === "--long") {
+        opts.long = true;
+      } else {
+        return errResult(`unknown flag for list: ${a}`);
+      }
+    }
+    return opts;
+  }
+  if (first === "get") {
+    if (rest.length !== 1) return errResult("get requires exactly one <id>");
+    return { command: "get", id: rest[0] };
+  }
+  if (first === "show" || first === "cat") {
+    if (rest.length !== 1) return errResult(`${first} requires exactly one <id|filename>`);
+    return { command: "show", target: 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 errResult("--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 errResult("create requires exactly one <title>");
+    return { command: "create", title: positional[0], body };
+  }
+  if (first === "append") {
+    if (rest.length < 1 || rest.length > 2) {
+      return errResult("append requires <filename> and optional <text>");
+    }
+    return { command: "append", filename: rest[0], text: rest[1] };
+  }
+  if (first === "rm" || first === "delete") {
+    if (rest.length !== 1) return errResult(`${first} requires exactly one <id|filename>`);
+    return { command: "rm", target: rest[0] };
+  }
+  if (first === "mv" || first === "move") {
+    if (rest.length !== 2) return errResult(`${first} requires <id|filename> <folder-id|name|--root>`);
+    return { command: "mv", target: rest[0], dest: rest[1] };
+  }
+  if (first === "folders") {
+    if (rest.length) return errResult("folders takes no arguments");
+    return { command: "folders" };
+  }
+  return errResult(`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;
+}
+
+// A note argument may be a numeric id (used as-is) or a filename/title,
+// resolved to an id via the by-filename lookup (which carries .id).
+async function resolveNoteId(client, target) {
+  if (isNumeric(target)) return target;
+  return (await client.note(target)).id;
+}
+
+// A folder NAME resolves to its id via GET /folders; ambiguous or unknown
+// names are an error (disambiguate with the numeric id).
+async function resolveFolderName(client, name) {
+  const matches = (await client.folders()).filter((f) => f.name === name);
+  if (matches.length === 0) throw new Error(`no folder named '${name}' (see: freshjots folders)`);
+  if (matches.length > 1) throw new Error(`ambiguous folder name '${name}' — use its numeric id`);
+  return matches[0].id;
+}
+
+function printNotes(notes, long, stdout) {
+  for (const n of notes) {
+    const title = n.title ?? "(untitled)";
+    if (long) {
+      const lock = n.append_only ? "L" : "-";
+      stdout(`${n.id}\t${n.updated_at}\t${lock}\t${n.folder_id ?? "-"}\t${n.filename}\t${title}\n`);
+    } else {
+      stdout(`${n.id}\t${n.filename}\t${title}\n`);
+    }
+  }
+}
+
+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") {
+      let folderId;
+      if (parsed.folder) {
+        if (parsed.folder === "none") folderId = "none";
+        else if (isNumeric(parsed.folder)) folderId = parsed.folder;
+        else folderId = await resolveFolderName(client, parsed.folder);
+      }
+      let notes;
+      if (parsed.all) {
+        notes = [];
+        let offset = 0;
+        for (;;) {
+          const page = await client.notes({ sort: parsed.sort, folderId, limit: 200, offset });
+          notes.push(...page);
+          if (page.length < 200) break;
+          offset += 200;
+          if (offset >= 100000) {
+            stderr("stopping at 100000 notes (safety cap) — narrow with --folder or --sort\n");
+            break;
+          }
+        }
+      } else {
+        notes = await client.notes({ sort: parsed.sort, folderId, limit: parsed.limit ?? undefined });
+      }
+      printNotes(notes, parsed.long, stdout);
+      return 0;
+    }
+    if (parsed.command === "get") {
+      stdout(`${JSON.stringify(await client.noteById(parsed.id), null, 2)}\n`);
+      return 0;
+    }
+    if (parsed.command === "show") {
+      const note = isNumeric(parsed.target)
+        ? await client.noteById(parsed.target)
+        : await client.note(parsed.target);
+      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;
+    }
+    if (parsed.command === "rm") {
+      await client.remove(await resolveNoteId(client, parsed.target));
+      return 0;
+    }
+    if (parsed.command === "mv") {
+      const id = await resolveNoteId(client, parsed.target);
+      let folderId;
+      if (["--root", "root", "none", "null"].includes(parsed.dest)) folderId = null;
+      else if (isNumeric(parsed.dest)) folderId = parsed.dest;
+      else folderId = await resolveFolderName(client, parsed.dest);
+      await client.move(id, folderId);
+      return 0;
+    }
+    if (parsed.command === "folders") {
+      for (const f of await client.folders()) stdout(`${f.id}\t${f.name}\n`);
+      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

@@ -56,6 +56,23 @@ declare module "freshjots" {
     constructor(opts: { status: number; code: ApiErrorCode; message: string; details?: unknown });
   }
 
+  /** A folder, as returned by `folders()`. */
+  export interface Folder {
+    id: number;
+    name: string;
+    created_at: string;
+    updated_at: string;
+  }
+
+  /** Options for `notes()` — mirror the API's list query params. */
+  export interface ListOptions {
+    sort?: "created" | "updated" | "appended";
+    /** A folder id, or "none" for un-foldered notes only. */
+    folderId?: number | string;
+    limit?: number;
+    offset?: number;
+  }
+
   export interface ClientOptions {
     token?: string;
     baseUrl?: string;
@@ -75,9 +92,13 @@ declare module "freshjots" {
     token: string;
     baseUrl: string;
     constructor(options?: ClientOptions);
-    notes(): Promise<NoteSummary[]>;
+    notes(options?: ListOptions): Promise<NoteSummary[]>;
     note(filename: string): Promise<Note>;
+    noteById(id: number | string): Promise<Note>;
     create(input: CreateInput): Promise<Note>;
     append(filename: string, text: string): Promise<true>;
+    remove(id: number | string): Promise<true>;
+    move(id: number | string, folderId: number | string | null): Promise<Note>;
+    folders(): Promise<Folder[]>;
   }
 }

package/index.js

@@ -18,7 +18,7 @@
 // payload ({ "notes": [...] }). show / show-by-filename / create return
 // the note object at the TOP LEVEL — there is no { "note": ... } wrapper.
 
-export const VERSION = "0.2.1";
+export const VERSION = "0.4.0";
 const DEFAULT_BASE_URL = "https://freshjots.com/api/v1";
 
 export class ApiError extends Error {
@@ -40,8 +40,20 @@ export class Client {
     this.baseUrl = baseUrl;
   }
 
-  async notes() {
-    return (await this._request("GET", "/notes")).notes;
+  // List notes (summary projection). Options mirror the API query params:
+  //   sort:    "created" | "updated" | "appended"  (default updated)
+  //   folderId: a folder id, or "none" for un-foldered notes only
+  //   limit/offset: pagination (server caps a page at 200)
+  async notes({ sort, folderId, limit, offset } = {}) {
+    const qs = new URLSearchParams();
+    if (sort) qs.set("sort", sort);
+    if (folderId !== undefined && folderId !== null && folderId !== "") {
+      qs.set("folder_id", String(folderId));
+    }
+    if (limit !== undefined && limit !== null && limit !== "") qs.set("limit", String(limit));
+    if (offset !== undefined && offset !== null && offset !== "") qs.set("offset", String(offset));
+    const q = qs.toString();
+    return (await this._request("GET", q ? `/notes?${q}` : "/notes")).notes;
   }
 
   async note(filename) {
@@ -51,6 +63,32 @@ export class Client {
     return await this._request("GET", path);
   }
 
+  // Full note by numeric id (GET /notes/:id) — top-level serializer.
+  async noteById(id) {
+    return await this._request("GET", `/notes/${encodeURIComponent(id)}`);
+  }
+
+  // Delete a note by id. Locked (append-only) notes are refused by the
+  // API with note_locked. Returns true on success (204).
+  async remove(id) {
+    await this._request("DELETE", `/notes/${encodeURIComponent(id)}`);
+    return true;
+  }
+
+  // Move a note into a folder (or to the root with folderId null/"none").
+  async move(id, folderId) {
+    const folder_id =
+      folderId === null || folderId === undefined || folderId === "" || folderId === "none"
+        ? null
+        : folderId;
+    return await this._request("POST", `/notes/${encodeURIComponent(id)}/move`, { folder_id });
+  }
+
+  // List folders ({ folders: [...] } envelope).
+  async folders() {
+    return (await this._request("GET", "/folders")).folders;
+  }
+
   // 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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freshjots",
-  "version": "0.2.1",
+  "version": "0.4.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"
   ],