paprika_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be90eff04cdca456a4aa2aa93e1f08b2819aea6aa4922be0242e92b924c4d721
+  data.tar.gz: 20f63a1e26726ac6961f5411f93642ee454f3c1821dc261e1be7db2d4920e547
+SHA512:
+  metadata.gz: 31f2594519e1dae0a6b0f1b5385c9a275f67fc2610499ef5ae171151248e58c9a183da045855a7287c121648e7696f55b3b6ce2b0f298b9a5d5c800bf24a9b9e
+  data.tar.gz: 7eb404887b1de963c2e09bb9c579fd6940bffe782e0d738921a022fdc855c02d62ccbc8e1e24039f544d0330c81c3e8167897880e93f029f0e9f6bdae59aa37d

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2026-07-02
+
+- Initial release.
+- `PaprikaClient::Client`: list recipes, fetch a full recipe, save a recipe
+  (create/update) with automatic sync-hash recomputation, and notify.
+- `PaprikaClient::Recipe`: attribute wrapper with `nutritional_info` accessors
+  and deterministic sync-hash calculation.
+- `PaprikaClient::Hashing`: Python-`json.dumps`-compatible serialization used
+  for the recipe sync hash.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 James Klein
+
+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,80 @@
+# PaprikaClient
+
+[![CI](https://github.com/kleinjm/paprika_client/actions/workflows/ci.yml/badge.svg)](https://github.com/kleinjm/paprika_client/actions/workflows/ci.yml)
+
+A small, dependency-free Ruby client for the (unofficial) [Paprika Recipe
+Manager](https://www.paprikaapp.com/) Cloud Sync API. Read your own recipes
+and write changes — including `nutritional_info` — back to your Paprika account
+so they sync to all your devices.
+
+> This uses Paprika's private sync API, which is not officially documented or
+> supported. It works today because it's the same API the Paprika apps use, but
+> it could change without notice. Use it with your own account and data.
+
+## Installation
+
+```ruby
+gem "paprika_client"
+```
+
+Or install directly:
+
+```bash
+gem install paprika_client
+```
+
+## Usage
+
+```ruby
+require "paprika_client"
+
+client = PaprikaClient::Client.new(
+  email: "you@example.com",
+  password: "your-paprika-password"
+)
+
+# List every recipe (lightweight: uid + change-detection hash)
+client.recipes
+# => [{ "uid" => "00011ACD-...", "hash" => "B84E5D7D..." }, ...]
+
+# Fetch a full recipe
+recipe = client.recipe("00011ACD-...")
+recipe.name              # => "Low Fodmap Ground Pork Noodle Bowls"
+recipe.nutritional_info  # => "Fat: 22.6 g\nCalories: 487 calories\n..."
+
+# Update nutrition and save it back (recomputes the sync hash and notifies apps)
+recipe.nutritional_info = "Calories: 500 calories\nProtein: 30 g"
+client.save_recipe(recipe)
+```
+
+`save_recipe` accepts either a `PaprikaClient::Recipe` or a plain attributes
+hash, always recomputes the sync `hash`, uploads the gzipped payload, and (by
+default) calls `notify` so your devices refresh. Pass `notify: false` to batch
+several writes and notify once at the end.
+
+### Sync hashes
+
+Paprika uses a per-recipe `hash` to detect changes during sync. The server
+stores whatever hash a client sends, so `PaprikaClient` recomputes a
+deterministic SHA-256 (matching the community reference implementation) on every
+write. You never manage it yourself.
+
+## Authentication
+
+Authentication is HTTP Basic (your Paprika email/password) against the v1 sync
+endpoints. Keep credentials out of source control — use environment variables
+or an encrypted credential store.
+
+## Development
+
+```bash
+bin/setup            # install dependencies
+bundle exec rake     # run tests + RuboCop
+```
+
+Tests use WebMock (no live API calls) and enforce 100% line and branch
+coverage via SimpleCov.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create(:test) do |t|
+  # Start SimpleCov before minitest/autorun so its at_exit (coverage check)
+  # runs after the tests, not before them.
+  t.test_prelude = %(require_relative "test/simplecov_env")
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/paprika_client/client.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "zlib"
+require "stringio"
+require "securerandom"
+
+module PaprikaClient
+  # Client for the Paprika Recipe Manager Cloud Sync API.
+  #
+  #   client = PaprikaClient::Client.new(email: "you@example.com", password: "secret")
+  #   client.recipes                       # => [{ "uid" => "...", "hash" => "..." }, ...]
+  #   recipe = client.recipe(uid)          # => PaprikaClient::Recipe
+  #   recipe.nutritional_info = "Calories: 200 calories"
+  #   client.save_recipe(recipe)           # recomputes hash, uploads, notifies
+  #
+  # Authentication is HTTP Basic (email/password) against the v1 sync
+  # endpoints, which is what the desktop/mobile apps use under the hood.
+  class Client
+    DEFAULT_BASE_URL = "https://www.paprikaapp.com/api"
+    USER_AGENT = "paprika_client (rubygems.org/gems/paprika_client)"
+
+    attr_reader :base_url
+
+    def initialize(email:, password:, base_url: DEFAULT_BASE_URL)
+      raise ArgumentError, "email is required" if email.nil? || email.empty?
+      raise ArgumentError, "password is required" if password.nil? || password.empty?
+
+      @email = email
+      @password = password
+      @base_url = base_url
+    end
+
+    # Lightweight list of every recipe as { "uid" => ..., "hash" => ... }.
+    def recipes
+      get("/v1/sync/recipes/")
+    end
+
+    # Fetch a single full recipe by uid.
+    def recipe(uid)
+      Recipe.new(get("/v1/sync/recipe/#{uid}/"))
+    end
+
+    # Create or update a recipe. Accepts a Recipe or a plain attributes hash.
+    # The sync hash is always recomputed before upload so other devices detect
+    # the change. Calls #notify afterwards unless notify: false.
+    def save_recipe(recipe, notify: true)
+      recipe = Recipe.new(recipe) unless recipe.is_a?(Recipe)
+      raise ArgumentError, "recipe must have a uid" if recipe.uid.nil? || recipe.uid.to_s.empty?
+
+      attributes = recipe.with_recomputed_hash
+      post_multipart("/v1/sync/recipe/#{recipe.uid}/", gzip(JSON.generate(attributes)))
+      self.notify if notify
+      Recipe.new(attributes)
+    end
+
+    # Ask the API to notify the recipe apps that changes have occurred.
+    def notify
+      post("/v1/sync/notify/")
+      true
+    end
+
+    private
+
+    def get(path)
+      request(Net::HTTP::Get.new(uri_for(path)))
+    end
+
+    def post(path)
+      request(Net::HTTP::Post.new(uri_for(path)))
+    end
+
+    def post_multipart(path, gzipped_body)
+      boundary = "----paprikaclient#{SecureRandom.hex(12)}"
+      req = Net::HTTP::Post.new(uri_for(path))
+      req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      req.body = multipart_body(boundary, gzipped_body)
+      request(req)
+    end
+
+    def multipart_body(boundary, gzipped_body)
+      body = +""
+      body << "--#{boundary}\r\n"
+      body << "Content-Disposition: form-data; name=\"data\"; filename=\"data\"\r\n"
+      body << "Content-Type: application/octet-stream\r\n\r\n"
+      body << gzipped_body
+      body << "\r\n--#{boundary}--\r\n"
+      body
+    end
+
+    def request(req)
+      req.basic_auth(@email, @password)
+      req["User-Agent"] = USER_AGENT
+      uri = req.uri
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(req)
+      end
+      parse(res)
+    end
+
+    def parse(res)
+      raise HTTPError.new(res.code.to_i, res.body.to_s[0, 500]) unless res.code.to_i == 200
+
+      json = JSON.parse(gunzip(res.body))
+      if json.is_a?(Hash) && json.key?("error")
+        message = json["error"].is_a?(Hash) ? json["error"]["message"] : json["error"]
+        raise APIError, message.to_s
+      end
+
+      json.is_a?(Hash) && json.key?("result") ? json["result"] : json
+    end
+
+    def uri_for(path)
+      URI.parse("#{@base_url}#{path}")
+    end
+
+    def gzip(string)
+      io = StringIO.new
+      gz = Zlib::GzipWriter.new(io)
+      gz.write(string)
+      gz.close
+      io.string
+    end
+
+    # Paprika sometimes gzip-encodes the response body at the app layer.
+    def gunzip(body)
+      Zlib::GzipReader.new(StringIO.new(body)).read
+    rescue Zlib::GzipFile::Error
+      body
+    end
+  end
+end

data/lib/paprika_client/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PaprikaClient
+  # Base class for all errors raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when the API responds with a non-success HTTP status.
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body = body
+      super("Paprika API returned HTTP #{status}: #{body}")
+    end
+  end
+
+  # Raised when the API responds 200 but the payload contains an error object,
+  # e.g. {"error" => {"message" => "Invalid or expired credentials."}}.
+  class APIError < Error; end
+end

data/lib/paprika_client/hashing.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PaprikaClient
+  # Reproduces the recipe `hash` that Paprika clients compute for change
+  # detection during sync.
+  #
+  # The value is SHA-256 of the recipe serialized the way Python's
+  # `json.dumps(obj, sort_keys=True)` does it: keys sorted, ", " between
+  # items, ": " between key and value, and non-ASCII escaped as \uXXXX.
+  #
+  # The Paprika sync server stores whatever hash a client sends (it does not
+  # validate it against a secret algorithm), so any deterministic scheme works
+  # for round-tripping; matching the community reference implementation keeps
+  # us consistent with other tools.
+  module Hashing
+    module_function
+
+    # Compute the sync hash for a recipe attributes hash. The existing "hash"
+    # key (if any) is excluded from the computation.
+    def digest(attributes)
+      without_hash = attributes.reject { |k, _| k.to_s == "hash" }
+      Digest::SHA256.hexdigest(python_json_dumps(without_hash))
+    end
+
+    # Serialize a Ruby object the way Python's json.dumps(sort_keys=True) does.
+    def python_json_dumps(obj)
+      case obj
+      when Hash
+        pairs = obj.keys.sort_by(&:to_s).map do |key|
+          "#{python_json_dumps(key.to_s)}: #{python_json_dumps(obj[key])}"
+        end
+        "{#{pairs.join(", ")}}"
+      when Array
+        "[#{obj.map { |v| python_json_dumps(v) }.join(", ")}]"
+      when String
+        %("#{escape_string(obj)}")
+      when nil
+        "null"
+      when true
+        "true"
+      when false
+        "false"
+      else
+        obj.to_s
+      end
+    end
+
+    ESCAPES = {
+      "\\" => "\\\\",
+      '"' => '\\"',
+      "\n" => "\\n",
+      "\t" => "\\t",
+      "\r" => "\\r",
+      "\b" => "\\b",
+      "\f" => "\\f"
+    }.freeze
+    private_constant :ESCAPES
+
+    def escape_string(str)
+      str.gsub(/[\\"\x00-\x1f]|[^\x00-\x7f]/) do |ch|
+        ESCAPES[ch] || ch.each_char.map { |c| format('\\u%04x', c.ord) }.join
+      end
+    end
+  end
+end

data/lib/paprika_client/recipe.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PaprikaClient
+  # A Paprika recipe. Thin wrapper around the raw attributes hash returned by
+  # (and sent to) the sync API. Keys are stored as strings.
+  class Recipe
+    attr_reader :attributes
+
+    def initialize(attributes = {})
+      @attributes = {}
+      attributes.each { |k, v| @attributes[k.to_s] = v }
+    end
+
+    def [](key)
+      @attributes[key.to_s]
+    end
+
+    def []=(key, value)
+      @attributes[key.to_s] = value
+    end
+
+    def uid
+      self["uid"]
+    end
+
+    def name
+      self["name"]
+    end
+
+    def nutritional_info
+      self["nutritional_info"]
+    end
+
+    def nutritional_info=(value)
+      self["nutritional_info"] = value
+    end
+
+    # The sync hash currently stored on the recipe (named to avoid clobbering
+    # Ruby's Object#hash).
+    def sync_hash
+      self["hash"]
+    end
+
+    # Recompute the sync hash from the current attributes (excluding "hash").
+    def calculate_hash
+      Hashing.digest(@attributes)
+    end
+
+    # Attributes with a freshly-computed "hash", ready for upload.
+    def with_recomputed_hash
+      @attributes.merge("hash" => calculate_hash)
+    end
+
+    def to_h
+      @attributes.dup
+    end
+  end
+end

data/lib/paprika_client/version.rb

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

data/lib/paprika_client.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "paprika_client/version"
+require_relative "paprika_client/errors"
+require_relative "paprika_client/hashing"
+require_relative "paprika_client/recipe"
+require_relative "paprika_client/client"
+
+# Ruby client for the (unofficial) Paprika Recipe Manager Cloud Sync API.
+module PaprikaClient
+end

data/sig/paprika_client.rbs

@@ -0,0 +1,4 @@
+module PaprikaClient
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: paprika_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Klein
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Read and write your own Paprika Recipe Manager data (recipes, nutritional
+  info, and more) via Paprika's cloud sync API. Supports listing recipes, fetching
+  full recipes, and writing changes back with correct sync hashing.
+email:
+- kleinjm007@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/paprika_client.rb
+- lib/paprika_client/client.rb
+- lib/paprika_client/errors.rb
+- lib/paprika_client/hashing.rb
+- lib/paprika_client/recipe.rb
+- lib/paprika_client/version.rb
+- sig/paprika_client.rbs
+homepage: https://github.com/kleinjm/paprika_client
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kleinjm/paprika_client
+  source_code_uri: https://github.com/kleinjm/paprika_client
+  changelog_uri: https://github.com/kleinjm/paprika_client/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Paprika Recipe Manager Cloud Sync API.
+test_files: []