freshjots 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9a2097c87005bc6e9b43c35881949e54bce2871962789f463ed347b4e2e415
-  data.tar.gz: 18f981d7b062f4e683b0c4bb4331f6be9442e94cad3f4067dea8847ed9d3893e
+  metadata.gz: 3916dec8cefe696476c18a0a28aba36a1657721082098eef1929129c05355b84
+  data.tar.gz: 94b852d213f92017d897fe309efd21f9ecf60c6d398e0cbfe6c37af0f11219b0
 SHA512:
-  metadata.gz: 00b9d55134d2826c0aa1515277907e31bcd1cb9b0df62918e194ca4b7f7e2542008fb3236b5503cb815ebde47702e4bac1e094a6ba3d2a5ac025ebb5ebf89171
-  data.tar.gz: f5f7dbcc724409cdb3b969972e0c5ff455abc715f3fc0da6650eaf1b6c654693ebd3a69c93c8f2f67aff021b529c41b37f90b506f3ead3d1e059737bfc4c4b85
+  metadata.gz: 8c650cb3dfdb4ff2c3d4680652e9fa8ec82cfd2fa5f6605fe9e33a3f67b3b6149d46ac5b3f6aada3cb2b3a7c4c8e77d2e4ebf98c122a5957439ce2205001aa9b
+  data.tar.gz: 1ee7ec3cace2bf20ce328f27d9ffb1ed91348eabb5fc3bf1354a9c21f09cd06707d22ca8f9beeb8dfc42b23a39bf8c873d19c0d7bc48af8089f149d659ede7e9

data/README.md

@@ -44,13 +44,25 @@ end
 created = client.create(title: "Research 2026 Q2", body: "Initial outline.")
 puts created[:filename] # server-derived stream name
 
-# Organize: move into a folder (by id or name), delete (by id or filename), list folders.
+# Update a note's fields (only the keys you pass change). By id or by filename:
+client.update(42, title: "Q2 research", body: "Revised outline.")
+client.set("cron-jobs-prod", folder: "Ops", deadline: 26)   # metadata only, no body needed
+
+# Create many notes in one atomic batch (up to 50 — all land or none do).
+client.bulk([{ title: "a", plain_body: "1" }, { title: "b", plain_body: "2" }])
+
+# Organize: move into a folder (by id or name), delete (by id or filename).
 client.move("cron-jobs-prod", folder: "Ops")
 client.delete("old-note")
+
+# Folders: list, read one, create, rename, delete (its notes survive, un-foldered).
 client.folders.each { |f| puts "#{f[:id]}\t#{f[:name]}" }
+ops = client.create_folder("Ops")
+client.rename_folder(ops[:id], "Operations")
+client.delete_folder(ops[:id])
 ```
 
-Client methods: `notes(sort:, folder_id:, limit:, offset:)`, `note(filename)`, `note_by_id(id)`, `create(title:, body:, client_encrypted:)`, `append(filename, text, client_encrypted:)`, `delete(id_or_filename)`, `move(id_or_filename, folder:)`, and `folders`. Client-side crypto: `Freshjots.encrypt(text, passphrase)` / `Freshjots.decrypt(token, passphrase)` (see [Encryption](#encryption)). `note`/`note_by_id`/`create` return the note hash directly (no `{ note: … }` wrapper); `notes` and `folders` return arrays. For `notes`, `sort` is `created|updated|appended` and `folder_id` may be a folder id or `"none"` (un-foldered only).
+Client methods: `notes(sort:, folder_id:, limit:, offset:)`, `note(filename)`, `note_by_id(id)`, `create(title:, body:, client_encrypted:)`, `append(filename, text, client_encrypted:)`, `update(id, **fields)`, `set(filename, **fields)`, `bulk(notes)`, `delete(id_or_filename)`, `move(id_or_filename, folder:)`, `folders`, `folder(id)`, `create_folder(name)`, `rename_folder(id, name)`, and `delete_folder(id)`. Client-side crypto: `Freshjots.encrypt(text, passphrase)` / `Freshjots.decrypt(token, passphrase)` (see [Encryption](#encryption)). `note`/`note_by_id`/`create`/`update`/`set` and the single-folder methods return the hash directly (no `{ note: … }` / `{ folder: … }` wrapper); `notes` and `folders` return arrays, and `bulk` returns `{ created: [...] }`. For `update`/`set`, the fields are `title:`, `body:`, `folder:` (id or name — `root: true` un-folders), `deadline:`, `alert_email:`, `webhook_url:`, `webhook_secret:`; changing `title:` rewrites the body as a unit, so pass `body:` too. For `notes`, `sort` is `created|updated|appended` and `folder_id` may be a folder id or `"none"` (un-foldered only).
 
 ## Encryption
 

data/lib/freshjots/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Freshjots
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/freshjots.rb

@@ -34,6 +34,11 @@ module Freshjots
 
   class Client
     DEFAULT_BASE_URL = "https://freshjots.com/api/v1"
+    BULK_MAX = 50
+    # Friendly field names accepted by #update / #set, mapped to the API's
+    # note keys in #note_fields. append_only / format are intentionally
+    # absent — the API does not update them.
+    UPDATABLE_FIELDS = %i[title body folder root deadline alert_email webhook_url webhook_secret].freeze
 
     def initialize(token: ENV["FRESHJOTS_TOKEN"], base_url: DEFAULT_BASE_URL)
       raise ArgumentError, "FRESHJOTS_TOKEN missing — pass token: or set the env var" if token.nil? || token.empty?
@@ -96,9 +101,37 @@ module Freshjots
       true
     end
 
+    # Update a note by id. Pass any of: title:, body:, folder:, root: true,
+    # deadline:, alert_email:, webhook_url:, webhook_secret: — only the keys
+    # you pass are changed, so an unmentioned field is never clobbered. A
+    # content change (title/body) rewrites the body as a unit, so a title
+    # change needs body: too (the API requires plain_body). append_only and
+    # format are not updatable. Returns the updated note hash (top level).
+    def update(id, **fields)
+      request(:patch, "/notes/#{escape(id)}", { note: note_fields(fields) })
+    end
+
+    # Update a note addressed by its exact filename / stream name. Same
+    # fields as #update.
+    def set(filename, **fields)
+      request(:patch, "/notes/by-filename/#{escape(filename)}", { note: note_fields(fields) })
+    end
+
+    # Create up to 50 notes in one atomic batch (all land or none do).
+    # `notes` is an array of note hashes ({ title:, plain_body:,
+    # format: "plain" }). Returns the response ({ created: [...] }).
+    def bulk(notes)
+      items = Array(notes)
+      raise ArgumentError, "bulk requires at least one note" if items.empty?
+      raise ArgumentError, "bulk accepts at most #{BULK_MAX} notes (got #{items.size})" if items.size > BULK_MAX
+
+      request(:post, "/notes/bulk", { notes: items })
+    end
+
     # Delete a note. Accepts a numeric id or a filename (resolved to its
-    # id via the by-filename lookup). Locked (append-only) notes are
-    # refused by the API with note_locked. Returns true on success.
+    # id via the by-filename lookup). Works on any note, including locked
+    # (append-only) ones — the lock freezes content, not deletability.
+    # Returns true on success.
     def delete(id_or_filename)
       request(:delete, "/notes/#{resolve_note_id(id_or_filename)}")
       true
@@ -117,6 +150,28 @@ module Freshjots
       request(:get, "/folders")[:folders]
     end
 
+    # Fetch one folder by id (GET /folders/:id) — top-level serializer.
+    def folder(id)
+      request(:get, "/folders/#{escape(id)}")
+    end
+
+    # Create a folder. Returns the created folder hash (top level).
+    def create_folder(name)
+      request(:post, "/folders", { folder: { name: name } })
+    end
+
+    # Rename a folder. Returns the updated folder hash.
+    def rename_folder(id, name)
+      request(:patch, "/folders/#{escape(id)}", { folder: { name: name } })
+    end
+
+    # Delete a folder by id. Its notes survive — they just become
+    # un-foldered. Returns true.
+    def delete_folder(id)
+      request(:delete, "/folders/#{escape(id)}")
+      true
+    end
+
     private
 
     # A note reference is either a numeric id (used as-is) or a
@@ -140,6 +195,42 @@ module Freshjots
       matches.first[:id]
     end
 
+    # Map the friendly #update / #set keyword fields to the API's note keys,
+    # sending only what the caller passed. A title change rewrites the body
+    # as a unit (the API requires plain_body), so a title-only change is
+    # refused here — mirrors the CLI. Unknown fields and an empty change are
+    # errors. `folder:` accepts an id or a name (resolved via /folders);
+    # `root: true` un-folders the note.
+    def note_fields(fields)
+      unknown = fields.keys - UPDATABLE_FIELDS
+      unless unknown.empty?
+        raise ArgumentError,
+              "unknown update field(s): #{unknown.join(', ')}. " \
+              "allowed: #{UPDATABLE_FIELDS.join(', ')} (append_only/format are not updatable)"
+      end
+      if fields.key?(:title) && !fields.key?(:body)
+        raise ArgumentError,
+              "changing the title also rewrites the body — pass body: too. For metadata " \
+              "only, use folder/root/deadline/alert_email/webhook_* without title."
+      end
+
+      note = {}
+      note[:title]      = fields[:title] if fields.key?(:title)
+      note[:plain_body] = fields[:body]  if fields.key?(:body)
+      if fields[:root]
+        note[:folder_id] = nil
+      elsif fields.key?(:folder)
+        note[:folder_id] = resolve_folder_id(fields[:folder])
+      end
+      note[:append_deadline_hours] = fields[:deadline]       if fields.key?(:deadline)
+      note[:alert_email]           = fields[:alert_email]    if fields.key?(:alert_email)
+      note[:webhook_url]           = fields[:webhook_url]    if fields.key?(:webhook_url)
+      note[:webhook_secret]        = fields[:webhook_secret] if fields.key?(:webhook_secret)
+      raise ArgumentError, "no fields to update" if note.empty?
+
+      note
+    end
+
     def request(method, path, body = nil)
       uri = URI("#{@base_url}#{path}")
       req = Net::HTTP.const_get(method.to_s.capitalize).new(uri)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: freshjots
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Goran Arsov