freshjots 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 878a80b88154f8d8421f1e2aea48643ecdf00dda54ebdd2d3c758ae35d66a99f
+  data.tar.gz: e4e4fe520d5007bc38d93fc29ed96ad1c36eadabfbe09aec36a91dda22cd14dc
+SHA512:
+  metadata.gz: 4a34ff09969147fda0da083a3559ed4c4b4751f8f9a48ebd67c750f72079900dd1f0a17cf7b82236354c7b139209fb60fa8069fb7caddbf566b084b667ffe18a
+  data.tar.gz: a2619e3b7a4d32837374585fb8a1265ab98f3e28482463bca33d5dce7075a3e491d29fcc1a328b6a1ac4e0f4bbc5744f4fca29588447fd51a80ad2903d434931

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goran Arsov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# freshjots — Ruby
+
+Tiny Ruby client for the [Fresh Jots](https://freshjots.com) API. One file,
+no runtime dependencies (uses `net/http` from stdlib).
+
+## Install
+
+```ruby
+# Gemfile
+gem "freshjots"
+```
+
+```sh
+bundle install
+```
+
+Or globally:
+
+```sh
+gem install freshjots
+```
+
+## Use
+
+```ruby
+require "freshjots"
+
+# Reads FRESHJOTS_TOKEN from the environment by default.
+client = Freshjots::Client.new
+
+# Append text to a note (creates it if missing).
+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]}" }
+
+# 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
+```
+
+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.
+
+## Errors
+
+Any non-2xx response raises `Freshjots::ApiError` with `status`, `code`,
+`message`, and (when present) `details` from the API's stable error
+envelope:
+
+```ruby
+begin
+  client.append("huge", "x" * 5_000_000)
+rescue Freshjots::ApiError => e
+  puts "#{e.status} #{e.code}: #{e.message}"
+  # 413 content_too_large: body exceeds the per-note 3 MB cap
+end
+```
+
+Stable error codes: `unauthenticated`, `forbidden`, `not_found`,
+`validation_failed`, `cap_exceeded`, `storage_cap_exceeded`,
+`content_too_large`, `content_type_mismatch`, `rate_limited`. Full list:
+<https://freshjots.com/docs>.
+
+## Auth
+
+Mint a token at <https://freshjots.com/settings/api_tokens> (Dev or
+Dev-pro tier required). Set it once:
+
+```sh
+export FRESHJOTS_TOKEN=<your-token>
+```
+
+Or pass explicitly:
+
+```ruby
+Freshjots::Client.new(token: "fjk_…")
+```
+
+## License
+
+MIT.

data/lib/freshjots/version.rb

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

data/lib/freshjots.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "freshjots/version"
+
+# Tiny client for the Fresh Jots API (https://freshjots.com/docs).
+#
+# Usage:
+#
+#   client = Freshjots::Client.new          # reads FRESHJOTS_TOKEN from ENV
+#   client.append("cron-jobs-prod", "backup ok")
+#   client.note("cron-jobs-prod")[:plain_body]
+#   client.create(title: "Deploy log")[:filename]   # server-derived
+#
+# All methods raise Freshjots::ApiError on non-2xx, with code/status/details
+# from the API's stable error envelope.
+#
+# Response shapes: GET /notes is the only endpoint that wraps its payload
+# ({ notes: [...] }). show / show-by-filename / create return the note
+# hash at the TOP LEVEL — there is no { note: ... } wrapper.
+module Freshjots
+  class ApiError < StandardError
+    attr_reader :status, :code, :details
+
+    def initialize(status:, code:, message:, details: nil)
+      super(message)
+      @status, @code, @details = status, code, details
+    end
+  end
+
+  class Client
+    DEFAULT_BASE_URL = "https://freshjots.com/api/v1"
+
+    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?
+
+      @token, @base_url = token, base_url
+    end
+
+    def notes
+      request(:get, "/notes")[:notes]
+    end
+
+    # show-by-filename renders the serializer at the top level (no
+    # { note: ... } wrapper), so the response *is* the note hash.
+    def note(filename)
+      request(:get, "/notes/by-filename/#{escape(filename)}")
+    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
+    # (the by-filename endpoint creates it with that exact name on first
+    # call). Returns the created note hash (top level); read [:filename]
+    # for the server-derived stream name.
+    def create(title:, body: "")
+      if title.nil? || title.to_s.empty?
+        raise ArgumentError,
+              "create requires a title — the API derives the filename from it. " \
+              "For a note addressable by an exact filename, use append."
+      end
+      payload = { note: { title: title, plain_body: body, format: "plain" } }
+      request(:post, "/notes", payload)
+    end
+
+    def append(filename, text)
+      request(:post, "/notes/by-filename/#{escape(filename)}/append", { text: text })
+      true
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      uri = URI("#{@base_url}#{path}")
+      req = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+      req["Authorization"] = "Bearer #{@token}"
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = body.to_json
+      end
+
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
+      data = res.body.to_s.empty? ? {} : JSON.parse(res.body, symbolize_names: true)
+      raise_for_error!(res, data)
+      data
+    end
+
+    def raise_for_error!(res, data)
+      return if res.is_a?(Net::HTTPSuccess)
+
+      err = data[:error] || {}
+      raise ApiError.new(
+        status:  res.code.to_i,
+        code:    err[:code]    || "unknown",
+        message: err[:message] || "request failed",
+        details: err[:details]
+      )
+    end
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: freshjots
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Goran Arsov
+bindir: bin
+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.
+email:
+- arsphy@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/freshjots.rb
+- lib/freshjots/version.rb
+homepage: https://github.com/Goran-Arsov/freshjots-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Goran-Arsov/freshjots-ruby
+  source_code_uri: https://github.com/Goran-Arsov/freshjots-ruby
+  bug_tracker_uri: https://github.com/Goran-Arsov/freshjots-ruby/issues
+  documentation_uri: https://freshjots.com/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Tiny Ruby client for the Fresh Jots API
+test_files: []