freshjots 0.3.0 → 1.0.1

package/README.md

@@ -1,46 +1,8 @@
-# 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`).
 
-## Install
-
-```sh
-npm install freshjots
-```
-
-(Or `pnpm add freshjots`, `yarn add freshjots`, `bun add freshjots`.)
-
-## Use
-
-```js
-import { Client } from "freshjots";
-
-// Reads FRESHJOTS_TOKEN from the environment by default.
-const client = new Client();
-
-// Append text to a note (creates it if missing).
-await client.append("cron-jobs-prod", "backup ok");
-
-// Read a note's body.
-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}`);
-
-// 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({ 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
@@ -51,16 +13,27 @@ automatically.
 
 ```sh
 npm install -g freshjots
-export FRESHJOTS_TOKEN=mn_…           # PowerShell: $env:FRESHJOTS_TOKEN = "mn_…"
+
+# Persist the token for every new shell (macOS defaults to zsh; use ~/.bashrc on bash):
+echo 'export FRESHJOTS_TOKEN=mn_…' >> ~/.zshrc && source ~/.zshrc
+# Windows PowerShell: [Environment]::SetEnvironmentVariable("FRESHJOTS_TOKEN", "mn_…", "User")
 ```
 
-The CLI mirrors the four API methods one-for-one:
+The CLI covers reading, writing, and organizing notes:
 
 ```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 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
+freshjots --version                       # print version (--help for full usage)
 ```
 
 Both `create` and `append` read from stdin when the body or text isn't
@@ -82,6 +55,47 @@ 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.
 
+## Install
+
+```sh
+npm install freshjots
+```
+
+(Or `pnpm add freshjots`, `yarn add freshjots`, `bun add freshjots`.)
+
+## Use
+
+```js
+import { Client } from "freshjots";
+
+// Reads FRESHJOTS_TOKEN from the environment by default.
+const client = new Client();
+
+// Append text to a note (creates it if missing).
+await client.append("cron-jobs-prod", "backup ok");
+
+// Read a note's body.
+const note = await client.note("cron-jobs-prod");
+console.log(note.plain_body);
+
+// 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.
+const created = await client.create({ title: "Research 2026 Q2", body: "Initial outline." });
+console.log(created.filename); // server-derived stream name
+```
+
+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).
+
 ## TypeScript
 
 Types ship with the package — no `@types/freshjots` needed, no `.d.ts`
@@ -133,8 +147,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/cli.js

@@ -8,10 +8,19 @@ import { Client, ApiError, VERSION } from "./index.js";
 const USAGE = `freshjots — Fresh Jots CLI
 
 Usage:
-  freshjots list
-  freshjots show <filename>
+  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:
@@ -20,6 +29,9 @@ Notes:
     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;
@@ -30,13 +42,38 @@ export function parseArgs(argv) {
   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 === "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") {
-    if (rest.length !== 1) return { command: "error", message: "show requires exactly one <filename>" };
-    return { command: "show", filename: 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;
@@ -44,7 +81,7 @@ export function parseArgs(argv) {
     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" };
+        if (i + 1 >= rest.length) return errResult("--body requires a value");
         body = rest[++i];
       } else if (a.startsWith("--body=")) {
         body = a.slice("--body=".length);
@@ -52,16 +89,28 @@ export function parseArgs(argv) {
         positional.push(a);
       }
     }
-    if (positional.length !== 1) return { command: "error", message: "create requires exactly one <title>" };
+    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 { command: "error", message: "append requires <filename> and optional <text>" };
+      return errResult("append requires <filename> and optional <text>");
     }
     return { command: "append", filename: rest[0], text: rest[1] };
   }
-  return { command: "error", message: `unknown command: ${first}` };
+  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) {
@@ -73,6 +122,34 @@ async function readStdin(stdin) {
   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));
@@ -111,12 +188,40 @@ export async function run(argv, deps = {}) {
 
   try {
     if (parsed.command === "list") {
-      const notes = await client.notes();
-      for (const n of notes) stdout(`${n.filename}\t${n.title}\n`);
+      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 = await client.note(parsed.filename);
+      const note = isNumeric(parsed.target)
+        ? await client.noteById(parsed.target)
+        : await client.note(parsed.target);
       stdout(note.plain_body ?? "");
       return 0;
     }
@@ -137,6 +242,23 @@ export async function run(argv, deps = {}) {
       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`);

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.3.0";
+export const VERSION = "1.0.1";
 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.3.0",
+  "version": "1.0.1",
   "description": "Tiny JavaScript client for the Fresh Jots API. Append-only notebooks for cron jobs, deploy scripts, and bots.",
   "type": "module",
   "main": "index.js",