freshjots 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9a2097c87005bc6e9b43c35881949e54bce2871962789f463ed347b4e2e415
-  data.tar.gz: 18f981d7b062f4e683b0c4bb4331f6be9442e94cad3f4067dea8847ed9d3893e
+  metadata.gz: '0881261ca2139927877d9e54e9960a92c4318af920804a0324a7e9a728d9a0cd'
+  data.tar.gz: 320b4c81fa62361731c3a02e50570841519d8bcf9458d97bf8ce4478195e270b
 SHA512:
-  metadata.gz: 00b9d55134d2826c0aa1515277907e31bcd1cb9b0df62918e194ca4b7f7e2542008fb3236b5503cb815ebde47702e4bac1e094a6ba3d2a5ac025ebb5ebf89171
-  data.tar.gz: f5f7dbcc724409cdb3b969972e0c5ff455abc715f3fc0da6650eaf1b6c654693ebd3a69c93c8f2f67aff021b529c41b37f90b506f3ead3d1e059737bfc4c4b85
+  metadata.gz: 48f118b9637d9e5beb2c418cfb8c7e91b42f2ee684e8061eadea70c4e11b5ba54f7a1179a80c3ac60fa60f11bb19d416e8edb7d5e58ea118df8c4b8c6ddcb0de
+  data.tar.gz: 3ca213be4f8684c5f1f8ef8a92b84e2b550dd9ff5228888fe7e72c326429ec024b64906285e14e8666a3854dbd0531e15e53d45c7339e65ac13d3315c2dbf5c1

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/exe/freshjots

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "freshjots/cli"
+
+exit Freshjots::CLI.run(ARGV)

data/lib/freshjots/cli.rb

@@ -0,0 +1,539 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../freshjots"
+
+# Command-line front-end for the Fresh Jots API — a thin wrapper over
+# Freshjots::Client, mirroring the npm and bash CLIs command-for-command
+# (ls, get, cat, create, append, update, set, rm, mv, bulk, folders, folder
+# subcommands, encrypt, decrypt) and their output. run() takes its I/O and a
+# client factory as keyword args so it is fully testable without a network or a
+# real token; exe/freshjots is a one-line wrapper around it.
+module Freshjots
+  module CLI
+    USAGE = <<~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> [--decrypt]   Print a note's body.
+        freshjots create <title> [<body>] [--body <text>] [--encrypt]
+        freshjots append <filename> [<text>] [--encrypt]
+        freshjots update <id> [flags]        Update a note by id (see Update flags).
+        freshjots set <filename> [flags]     Update a note by filename (see Update flags).
+        freshjots rm <id|filename>           Delete a note.
+        freshjots mv <id|filename> <folder-id|name|--root>
+        freshjots bulk [file.json]           Bulk-create notes (JSON array/{notes:[…]}
+                                               on stdin or from a file; max 50).
+        freshjots folders                    List folders as id<TAB>name.
+        freshjots folder <subcommand>        Manage folders:
+                                               folder [ls]                list (same as 'folders')
+                                               folder create <name>       create a folder
+                                               folder rename <id> <name>  rename a folder
+                                               folder rm <id>             delete a folder (notes survive)
+                                               folder <id>                show one folder as JSON
+        freshjots encrypt                    Encrypt stdin, print an fj1: token.
+        freshjots decrypt                    Decrypt fj1: lines from stdin to plaintext.
+        freshjots --help | --version
+
+      Global flags:
+        -q, --quiet          Suppress the success confirmation on write commands.
+
+      Update flags (update / set) — only the fields you pass are changed:
+        --title <s>              new title (a title change rewrites the body,
+                                   so pass --body too)
+        --body <text> | -        new body (- reads the body from stdin)
+        --folder <id> | --root   move into a folder (numeric id) or un-folder
+        --deadline <hours>       dead-man's-switch deadline
+        --alert-email <s>        dead-man alert address
+        --webhook-url <s>        outbound webhook URL
+        --webhook-secret <s>     outbound webhook signing secret
+
+      Notes:
+        - <text> for append and the body for create may also be piped on stdin.
+        - --encrypt / --decrypt and the encrypt/decrypt commands encrypt client-side
+          with the passphrase in FRESHJOTS_PASSPHRASE; the server only ever stores the
+          ciphertext and cannot read it. Lose the passphrase and the note is lost.
+        - Auth: set FRESHJOTS_TOKEN. Mint one at
+          https://freshjots.com/settings/api_tokens.
+    USAGE
+
+    module_function
+
+    # Entry point. Returns a process exit code. I/O and the client are injected
+    # for testability; production callers (exe/freshjots) use the defaults.
+    def run(argv, out: $stdout, err: $stderr, stdin: $stdin, env: ENV,
+            client_factory: ->(token) { Freshjots::Client.new(token: token) })
+      # Global -q/--quiet, stripped before parsing: suppresses the success
+      # confirmation on write commands. Data commands print regardless.
+      quiet = argv.include?("-q") || argv.include?("--quiet")
+      args = argv.reject { |a| a == "-q" || a == "--quiet" }
+      say = quiet ? ->(_s) {} : ->(s) { out.print(s) }
+
+      parsed = parse_args(args)
+
+      case parsed[:command]
+      when :help
+        (parsed[:exit_code].to_i.positive? ? err : out).print(USAGE)
+        return parsed[:exit_code] || 0
+      when :version
+        out.print("freshjots #{Freshjots::VERSION}\n")
+        return 0
+      when :error
+        err.print("Error: #{parsed[:message]}\n\n#{USAGE}")
+        return 2
+      when :encrypt, :decrypt
+        return run_crypto(parsed[:command], stdin, out, err, env)
+      end
+
+      token = env["FRESHJOTS_TOKEN"]
+      if token.nil? || token.empty?
+        err.print("Error: FRESHJOTS_TOKEN is not set. Mint one at https://freshjots.com/settings/api_tokens\n")
+        return 1
+      end
+
+      begin
+        client = client_factory.call(token)
+      rescue StandardError => e
+        err.print("Error: #{e.message}\n")
+        return 1
+      end
+
+      begin
+        dispatch(parsed, client, out, err, stdin, env, say)
+      rescue Freshjots::ApiError => e
+        err.print("Error: HTTP #{e.status} #{e.code}: #{e.message}\n")
+        1
+      rescue StandardError => e
+        err.print("Error: #{e.message}\n")
+        1
+      end
+    end
+
+    # ---- command dispatch (assumes token + client are ready) ----
+
+    def dispatch(parsed, client, out, err, stdin, env, say)
+      case parsed[:command]
+      when :list
+        folder_id = list_folder_filter(parsed[:folder], client)
+        notes =
+          if parsed[:all]
+            fetch_all_notes(client, parsed[:sort], folder_id)
+          else
+            client.notes(sort: parsed[:sort], folder_id: folder_id, limit: parsed[:limit])
+          end
+        print_notes(notes, parsed[:long], out)
+        0
+      when :get
+        out.print("#{JSON.pretty_generate(client.note_by_id(parsed[:id]))}\n")
+        0
+      when :show
+        note = numeric?(parsed[:target]) ? client.note_by_id(parsed[:target]) : client.note(parsed[:target])
+        body = note[:plain_body] || ""
+        body = decrypt_body(body, passphrase!(env)) if parsed[:decrypt]
+        out.print(body)
+        0
+      when :create
+        body = parsed[:body]
+        body = read_stdin(stdin) if body.nil?
+        body ||= ""
+        encrypted = parsed[:encrypt]
+        body = Freshjots.encrypt(body, passphrase!(env)) if encrypted
+        created = client.create(title: parsed[:title], body: body, client_encrypted: encrypted)
+        say.call("created ##{created[:id]} #{created[:filename]}\n")
+        0
+      when :append
+        text = parsed[:text]
+        text = read_stdin(stdin) if text.nil?
+        if text.nil? || text.empty?
+          err.print("Error: append requires text (as an argument or on stdin)\n")
+          return 2
+        end
+        text = Freshjots.encrypt(text, passphrase!(env)) if parsed[:encrypt]
+        res = client.append(parsed[:filename], text, client_encrypted: parsed[:encrypt])
+        say.call("#{res[:created] ? 'created' : 'appended to'} ##{res[:id]} #{res[:filename]} — #{group_thousands(res[:bytes_remaining])} bytes remaining\n")
+        0
+      when :rm
+        res = client.delete(parsed[:target])
+        say.call("deleted ##{res[:id]}\n")
+        0
+      when :mv
+        dest = parsed[:dest]
+        folder = %w[--root root none null].include?(dest) ? nil : dest
+        res = client.move(parsed[:target], folder: folder)
+        say.call("moved ##{res[:id]} -> folder #{res[:folder_id] || 'root'}\n")
+        0
+      when :folders
+        client.folders.each { |f| out.print("#{f[:id]}\t#{f[:name]}\n") }
+        0
+      when :folder_create
+        f = client.create_folder(parsed[:name])
+        say.call("created folder ##{f[:id]} #{f[:name]}\n")
+        0
+      when :folder_rename
+        f = client.rename_folder(parsed[:id], parsed[:name])
+        say.call("renamed folder ##{f[:id]} -> #{f[:name]}\n")
+        0
+      when :folder_rm
+        res = client.delete_folder(parsed[:id])
+        say.call("deleted folder ##{res[:id]}\n")
+        0
+      when :folder_show
+        out.print("#{JSON.pretty_generate(client.folder(parsed[:id]))}\n")
+        0
+      when :update, :set
+        attrs = parsed[:attrs].dup
+        attrs[:body] = read_stdin(stdin) if parsed[:body_from_stdin]
+        note = parsed[:command] == :update ? client.update(parsed[:id], **attrs) : client.set(parsed[:filename], **attrs)
+        say.call(parsed[:command] == :update ? "updated ##{note[:id]} #{note[:filename]}\n" : "updated #{note[:filename]}\n")
+        0
+      when :bulk
+        run_bulk(parsed, client, err, stdin, say)
+      else
+        0
+      end
+    end
+
+    def run_bulk(parsed, client, err, stdin, say)
+      raw =
+        if parsed[:file]
+          File.read(parsed[:file])
+        else
+          piped = read_stdin(stdin)
+          if piped.nil? || piped.empty?
+            err.print("Error: bulk reads a JSON array of notes from a file arg or stdin\n")
+            return 2
+          end
+          piped
+        end
+      begin
+        json = JSON.parse(raw, symbolize_names: true)
+      rescue JSON::ParserError => e
+        err.print("Error: bulk input is not valid JSON: #{e.message}\n")
+        return 2
+      end
+      notes =
+        if json.is_a?(Array)
+          json
+        elsif json.is_a?(Hash) && json[:notes].is_a?(Array)
+          json[:notes]
+        end
+      if notes.nil?
+        err.print("Error: bulk expects a JSON array of notes, or {\"notes\":[...]}\n")
+        return 2
+      end
+      if notes.size > 50
+        err.print("Error: max 50 notes per batch (got #{notes.size}). Split the input.\n")
+        return 2
+      end
+      res = client.bulk(notes)
+      say.call("created #{res[:created].size} notes\n")
+      0
+    end
+
+    # ---- offline crypto (no API call, no token) ----
+
+    def run_crypto(command, stdin, out, err, env)
+      begin
+        pass = passphrase!(env)
+      rescue StandardError => e
+        err.print("Error: #{e.message}\n")
+        return 1
+      end
+      input = read_stdin(stdin)
+      if input.nil? || input.empty?
+        err.print("Error: #{command} reads #{command == :encrypt ? 'plaintext' : 'ciphertext'} on stdin\n")
+        return 2
+      end
+      begin
+        out.print(command == :encrypt ? Freshjots.encrypt(input, pass) : decrypt_body(input, pass))
+        0
+      rescue StandardError => e
+        err.print("Error: #{e.message}\n")
+        1
+      end
+    end
+
+    # ---- argument parsing (pure) ----
+
+    def parse_args(argv)
+      return { command: :help, exit_code: 2 } if argv.empty?
+
+      first, *rest = argv
+      return { command: :help, exit_code: 0 } if %w[-h --help help].include?(first)
+      return { command: :version } if %w[-v --version version].include?(first)
+
+      case first
+      when "list", "ls"      then parse_list(rest)
+      when "get"
+        return err_result("get requires exactly one <id>") if rest.length != 1
+        { command: :get, id: rest[0] }
+      when "show", "cat"
+        decrypt = false
+        positional = []
+        rest.each { |a| a == "--decrypt" ? (decrypt = true) : (positional << a) }
+        return err_result("#{first} requires exactly one <id|filename>") if positional.length != 1
+        { command: :show, target: positional[0], decrypt: decrypt }
+      when "create"          then parse_create(rest)
+      when "append"          then parse_append(rest)
+      when "rm", "delete"
+        return err_result("#{first} requires exactly one <id|filename>") if rest.length != 1
+        { command: :rm, target: rest[0] }
+      when "mv", "move"
+        return err_result("#{first} requires <id|filename> <folder-id|name|--root>") if rest.length != 2
+        { command: :mv, target: rest[0], dest: rest[1] }
+      when "folders"
+        return err_result("folders takes no arguments") unless rest.empty?
+        { command: :folders }
+      when "folder"          then parse_folder(rest)
+      when "update"
+        return err_result("update requires <note-id> and at least one field flag") if rest.empty?
+        attrs = parse_note_attrs(rest[1..])
+        return err_result(attrs[:error]) if attrs[:error]
+        { command: :update, id: rest[0], attrs: attrs[:attrs], body_from_stdin: attrs[:body_from_stdin] }
+      when "set"
+        return err_result("set requires <filename> and at least one field flag") if rest.empty?
+        attrs = parse_note_attrs(rest[1..])
+        return err_result(attrs[:error]) if attrs[:error]
+        { command: :set, filename: rest[0], attrs: attrs[:attrs], body_from_stdin: attrs[:body_from_stdin] }
+      when "bulk"
+        files = rest.reject { |a| a == "-" }
+        return err_result("usage: freshjots bulk [file.json] (or pipe JSON on stdin)") if files.length > 1
+        { command: :bulk, file: files[0] }
+      when "encrypt", "decrypt"
+        return err_result("#{first} takes no arguments (reads stdin)") unless rest.empty?
+        { command: first.to_sym }
+      else
+        err_result("unknown command: #{first}")
+      end
+    end
+
+    def parse_list(rest)
+      opts = { command: :list, limit: nil, sort: nil, folder: nil, all: false, long: false }
+      i = 0
+      while i < rest.length
+        a = rest[i]
+        case a
+        when "-n", "--limit"
+          return err_result("--limit requires a value") if i + 1 >= rest.length
+          opts[:limit] = rest[i += 1]
+        when "--sort"
+          return err_result("--sort requires a value") if i + 1 >= rest.length
+          opts[:sort] = rest[i += 1]
+        when "--folder"
+          return err_result("--folder requires a value") if i + 1 >= rest.length
+          opts[:folder] = rest[i += 1]
+        when "--root" then opts[:folder] = "none"
+        when "--all"  then opts[:all] = true
+        when "-l", "--long" then opts[:long] = true
+        else return err_result("unknown flag for list: #{a}")
+        end
+        i += 1
+      end
+      opts
+    end
+
+    def parse_create(rest)
+      body = nil
+      encrypt = false
+      positional = []
+      i = 0
+      while i < rest.length
+        a = rest[i]
+        if a == "--body" || a == "-b"
+          return err_result("--body requires a value") if i + 1 >= rest.length
+          body = rest[i += 1]
+        elsif a.start_with?("--body=")
+          body = a.delete_prefix("--body=")
+        elsif a == "--encrypt"
+          encrypt = true
+        else
+          positional << a
+        end
+        i += 1
+      end
+      return err_result("create requires <title> and an optional <body>") if positional.empty? || positional.length > 2
+      if positional.length == 2
+        return err_result("create: pass the body positionally or with --body, not both") unless body.nil?
+        body = positional[1]
+      end
+      { command: :create, title: positional[0], body: body, encrypt: encrypt }
+    end
+
+    def parse_append(rest)
+      encrypt = false
+      positional = []
+      rest.each { |a| a == "--encrypt" ? (encrypt = true) : (positional << a) }
+      return err_result("append requires <filename> and optional <text>") if positional.empty? || positional.length > 2
+      { command: :append, filename: positional[0], text: positional[1], encrypt: encrypt }
+    end
+
+    def parse_folder(rest)
+      sub = rest[0]
+      if sub.nil? || sub == "ls" || sub == "list"
+        return err_result("usage: freshjots folder ls") if rest.length > 1
+        return { command: :folders }
+      end
+      if sub == "create" || sub == "new"
+        return err_result("usage: freshjots folder create <name>") if rest.length != 2 || rest[1].to_s.empty?
+        return { command: :folder_create, name: rest[1] }
+      end
+      if sub == "rename"
+        return err_result("usage: freshjots folder rename <id> <new-name>") if rest.length != 3 || rest[1].to_s.empty? || rest[2].to_s.empty?
+        return { command: :folder_rename, id: rest[1], name: rest[2] }
+      end
+      if sub == "rm" || sub == "delete"
+        return err_result("usage: freshjots folder rm <id>") if rest.length != 2 || rest[1].to_s.empty?
+        return { command: :folder_rm, id: rest[1] }
+      end
+      return err_result("usage: freshjots folder <id>") if rest.length != 1
+      { command: :folder_show, id: sub }
+    end
+
+    # Parse the shared update/set flags into friendly kwargs for Client#update /
+    # #set (only the keys passed are sent). `-` marks the body as coming from
+    # stdin (resolved by dispatch). Returns { attrs:, body_from_stdin: } or
+    # { error: }.
+    def parse_note_attrs(args)
+      attrs = {}
+      body_from_stdin = false
+      has_title = false
+      has_body = false
+      i = 0
+      while i < args.length
+        a = args[i]
+        case a
+        when "--title"
+          v = args[i + 1]
+          return { error: "--title requires a value" } if v.nil?
+          attrs[:title] = v; has_title = true; i += 1
+        when "--body", "-b"
+          v = args[i + 1]
+          return { error: "--body requires a value" } if v.nil?
+          attrs[:body] = v; has_body = true; i += 1
+        when "-"
+          body_from_stdin = true; has_body = true
+        when "--folder"
+          v = args[i + 1]
+          return { error: "--folder requires a value" } if v.nil?
+          return { error: "--folder requires a numeric folder id (or use --root)" } unless v.match?(/\A\d+\z/)
+          attrs[:folder] = v; i += 1
+        when "--root"
+          attrs[:root] = true
+        when "--deadline"
+          v = args[i + 1]
+          return { error: "--deadline requires a value" } if v.nil?
+          return { error: "--deadline requires a number of hours" } unless v.match?(/\A\d+\z/)
+          attrs[:deadline] = v.to_i; i += 1
+        when "--alert-email"
+          v = args[i + 1]
+          return { error: "--alert-email requires a value" } if v.nil?
+          attrs[:alert_email] = v; i += 1
+        when "--webhook-url"
+          v = args[i + 1]
+          return { error: "--webhook-url requires a value" } if v.nil?
+          attrs[:webhook_url] = v; i += 1
+        when "--webhook-secret"
+          v = args[i + 1]
+          return { error: "--webhook-secret requires a value" } if v.nil?
+          attrs[:webhook_secret] = v; i += 1
+        else
+          return { error: "unknown flag: #{a} (append_only/format are not API-updatable)" }
+        end
+        i += 1
+      end
+      return { error: "no fields to update. See 'freshjots --help'." } if attrs.empty? && !body_from_stdin
+      if has_title && !has_body
+        return { error: "can't change the title alone: a content update rewrites the body too, so pass " \
+                        "--body (or '-'). For metadata-only changes use --folder/--root/--deadline/" \
+                        "--alert-email/--webhook-url/--webhook-secret (no body needed)." }
+      end
+      { attrs: attrs, body_from_stdin: body_from_stdin }
+    end
+
+    # ---- helpers ----
+
+    def err_result(message)
+      { command: :error, message: message }
+    end
+
+    def numeric?(value)
+      value.to_s.match?(/\A\d+\z/)
+    end
+
+    def read_stdin(stdin)
+      return "" if stdin.nil?
+      return "" if stdin.respond_to?(:tty?) && stdin.tty?
+
+      stdin.read || ""
+    end
+
+    def passphrase!(env)
+      pass = env["FRESHJOTS_PASSPHRASE"]
+      raise "FRESHJOTS_PASSPHRASE is not set — required for --encrypt/--decrypt" if pass.nil? || pass.empty?
+
+      pass
+    end
+
+    # Decrypt a note body line by line: fj1: lines are decrypted, any other line
+    # passes through unchanged (handles both a whole-body ciphertext and an
+    # append stream of one ciphertext line per entry).
+    def decrypt_body(body, passphrase)
+      body.split("\n", -1).map { |line| Freshjots.encrypted?(line) ? Freshjots.decrypt(line, passphrase) : line }.join("\n")
+    end
+
+    def resolve_folder_name(client, name)
+      matches = client.folders.select { |f| f[:name] == name }
+      raise "no folder named '#{name}' (see: freshjots folders)" if matches.empty?
+      raise "ambiguous folder name '#{name}' — use its numeric id" if matches.size > 1
+
+      matches.first[:id]
+    end
+
+    def list_folder_filter(folder, client)
+      return nil if folder.nil?
+      return "none" if folder == "none"
+      return folder if numeric?(folder)
+
+      resolve_folder_name(client, folder)
+    end
+
+    def fetch_all_notes(client, sort, folder_id)
+      notes = []
+      offset = 0
+      loop do
+        page = client.notes(sort: sort, folder_id: folder_id, limit: 200, offset: offset)
+        notes.concat(page)
+        break if page.size < 200
+
+        offset += 200
+        break if offset >= 100_000
+      end
+      notes
+    end
+
+    # Group an integer with thousands separators ("3145719" -> "3,145,719"),
+    # matching the byte-count formatting the other clients produce.
+    def group_thousands(number)
+      number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse
+    end
+
+    def print_notes(notes, long, out)
+      notes.each do |n|
+        title = n[:title] || "(untitled)"
+        if long
+          lock = n[:append_only] ? "L" : "-"
+          out.print("#{n[:id]}\t#{n[:updated_at]}\t#{lock}\t#{n[:folder_id] || '-'}\t#{n[:filename]}\t#{title}\n")
+        else
+          out.print("#{n[:id]}\t#{n[:filename]}\t#{title}\n")
+        end
+      end
+    end
+  end
+end

data/lib/freshjots/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Freshjots
-  VERSION = "1.1.0"
+  VERSION = "2.0.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?
@@ -89,19 +94,51 @@ module Freshjots
     # On first-touch creation, pass client_encrypted: true to open the stream
     # as a client-encrypted note (send one ciphertext line per append).
     # Ignored once the note exists.
+    # Returns the append envelope (top level): { created:, id:, filename:,
+    # bytes_remaining:, ... } — `created` is true on first-touch creation and
+    # false on subsequent appends.
     def append(filename, text, client_encrypted: false)
       body = { text: text }
       body[:client_encrypted] = true if client_encrypted
       request(:post, "/notes/by-filename/#{escape(filename)}/append", body)
-      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 { deleted: true, id: <numeric id> } (the API's 204 carries no
+    # body, so this is synthesized from the resolved id).
     def delete(id_or_filename)
-      request(:delete, "/notes/#{resolve_note_id(id_or_filename)}")
-      true
+      id = resolve_note_id(id_or_filename)
+      request(:delete, "/notes/#{id}")
+      { deleted: true, id: id.to_i }
     end
 
     # Move a note into a folder. `folder` may be a folder id, a folder
@@ -117,6 +154,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 { deleted: true, id: <numeric id> }.
+    def delete_folder(id)
+      request(:delete, "/folders/#{escape(id)}")
+      { deleted: true, id: id.to_i }
+    end
+
     private
 
     # A note reference is either a numeric id (used as-is) or a
@@ -140,6 +199,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,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: freshjots
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Goran Arsov
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
@@ -13,13 +13,16 @@ description: Append-only notebooks for cron jobs, deploy scripts, and bots. Wrap
   the plain-text REST API at freshjots.com/api/v1.
 email:
 - arsphy@yahoo.com
-executables: []
+executables:
+- freshjots
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- exe/freshjots
 - lib/freshjots.rb
+- lib/freshjots/cli.rb
 - lib/freshjots/crypto.rb
 - lib/freshjots/version.rb
 homepage: https://github.com/Goran-Arsov/freshjots-ruby