freshjots 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 878a80b88154f8d8421f1e2aea48643ecdf00dda54ebdd2d3c758ae35d66a99f
-  data.tar.gz: e4e4fe520d5007bc38d93fc29ed96ad1c36eadabfbe09aec36a91dda22cd14dc
+  metadata.gz: 7674ef20013fb9165dcc54d15c0f7b1b99c4ec1967a11e3646d5b72ed605ff3b
+  data.tar.gz: d4663a22426bfcf413a48d0d0e5b00c12d08d291ed388c9cbc5dcac33f4b98d1
 SHA512:
-  metadata.gz: 4a34ff09969147fda0da083a3559ed4c4b4751f8f9a48ebd67c750f72079900dd1f0a17cf7b82236354c7b139209fb60fa8069fb7caddbf566b084b667ffe18a
-  data.tar.gz: a2619e3b7a4d32837374585fb8a1265ab98f3e28482463bca33d5dce7075a3e491d29fcc1a328b6a1ac4e0f4bbc5744f4fca29588447fd51a80ad2903d434931
+  metadata.gz: bb91c405637119e815517dec72db163c65d3a3b58b317cd51fd156eb3fccf08a3967547a8b661fbb3c7c4477756844b4ad08d7e07463df4435ec21a8f0c297b4
+  data.tar.gz: 8f240df1b1b9bb8d69aa0d294e74efa2ae47bfcafa980488fd898bbb368e02016acf96cb97aec9d187848f0f4ec8a815682e73043dfa7448c52a066926f2643c

data/README.md

@@ -34,16 +34,23 @@ client.append("cron-jobs-prod", "backup ok #{Time.now.utc.iso8601}")
 # Read a note's body.
 puts client.note("cron-jobs-prod")[:plain_body]
 
-# List your notes.
-client.notes.each { |note| puts "#{note[:filename]}\t#{note[:title]}" }
+# List your notes (most recent activity first). Sort and filter with options:
+client.notes(sort: "created", folder_id: 3, limit: 20).each do |note|
+  puts "#{note[:id]}\t#{note[:filename]}\t#{note[:title]}"
+end
 
 # Create a note. The API derives the filename from the title — for a
 # note addressable by an exact filename, use append instead.
 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.
+client.move("cron-jobs-prod", folder: "Ops")
+client.delete("old-note")
+client.folders.each { |f| puts "#{f[:id]}\t#{f[:name]}" }
 ```
 
-The whole API is four methods: `notes`, `note(filename)`, `create(title:, body:)`, `append(filename, text)`. `note` and `create` return the note hash directly (no `{ note: … }` wrapper); `notes` returns the array.
+Client methods: `notes(sort:, folder_id:, limit:, offset:)`, `note(filename)`, `note_by_id(id)`, `create(title:, body:)`, `append(filename, text)`, `delete(id_or_filename)`, `move(id_or_filename, folder:)`, and `folders`. `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).
 
 ## Errors
 
@@ -67,8 +74,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>

data/lib/freshjots/version.rb

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

data/lib/freshjots.rb

@@ -40,8 +40,18 @@ module Freshjots
       @token, @base_url = token, base_url
     end
 
-    def notes
-      request(:get, "/notes")[:notes]
+    # List notes (summary projection). Keyword options mirror the API
+    # query params: sort (created|updated|appended, default updated),
+    # folder_id (a folder id, or "none" for un-foldered notes only), and
+    # limit/offset for pagination (the server caps a page at 200).
+    def notes(sort: nil, folder_id: nil, limit: nil, offset: nil)
+      query = {}
+      query[:sort]      = sort      if sort
+      query[:folder_id] = folder_id unless folder_id.nil? || folder_id.to_s.empty?
+      query[:limit]     = limit     unless limit.nil?
+      query[:offset]    = offset    unless offset.nil?
+      path = query.empty? ? "/notes" : "/notes?#{URI.encode_www_form(query)}"
+      request(:get, path)[:notes]
     end
 
     # show-by-filename renders the serializer at the top level (no
@@ -50,6 +60,11 @@ module Freshjots
       request(:get, "/notes/by-filename/#{escape(filename)}")
     end
 
+    # Full note by numeric id (GET /notes/:id) — top-level serializer.
+    def note_by_id(id)
+      request(:get, "/notes/#{escape(id)}")
+    end
+
     # 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
@@ -71,8 +86,50 @@ module Freshjots
       true
     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.
+    def delete(id_or_filename)
+      request(:delete, "/notes/#{resolve_note_id(id_or_filename)}")
+      true
+    end
+
+    # Move a note into a folder. `folder` may be a folder id, a folder
+    # name (resolved via /folders), or nil / "none" / "root" to send the
+    # note back to the root.
+    def move(id_or_filename, folder: nil)
+      id = resolve_note_id(id_or_filename)
+      request(:post, "/notes/#{id}/move", { folder_id: resolve_folder_id(folder) })
+    end
+
+    # List folders ({ folders: [...] } envelope).
+    def folders
+      request(:get, "/folders")[:folders]
+    end
+
     private
 
+    # A note reference is either a numeric id (used as-is) or a
+    # filename/title resolved to an id via the by-filename lookup.
+    def resolve_note_id(value)
+      return value if value.is_a?(Integer) || value.to_s.match?(/\A\d+\z/)
+
+      note(value.to_s)[:id]
+    end
+
+    # A folder reference resolves to an id (or nil for the root). Names go
+    # through /folders; an unknown or ambiguous name is an ArgumentError.
+    def resolve_folder_id(value)
+      return nil if value.nil? || %w[none root null].include?(value.to_s.downcase)
+      return value if value.is_a?(Integer) || value.to_s.match?(/\A\d+\z/)
+
+      matches = folders.select { |f| f[:name] == value.to_s }
+      raise ArgumentError, "no folder named '#{value}'" if matches.empty?
+      raise ArgumentError, "ambiguous folder name '#{value}' — use its id" if matches.size > 1
+
+      matches.first[:id]
+    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: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Goran Arsov
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Append-only notebooks for cron jobs, deploy scripts, and bots. Wraps
-  the four-endpoint plain-text REST API at freshjots.com/api/v1.
+  the plain-text REST API at freshjots.com/api/v1.
 email:
 - arsphy@yahoo.com
 executables: []