freshjots 0.2.0 → 0.2.1

package/README.md

@@ -30,12 +30,16 @@ 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.
 
 ## TypeScript
 

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.2.1";
 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.2.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",