freshbooks-cli 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a37704cb4e7d203009ad3e85149f128509f11fd1e78198890c27687017e8f43d
-  data.tar.gz: 654e5bfc31deb194428128f8c2eb308c744c8c877426546f6400887b244c209c
+  metadata.gz: 72c774411761de2ede345e21a6961b2dace9debd2adf089b948c6cdd2447ac9b
+  data.tar.gz: a289b2ae8edb32a9759fc35b96165dc261254594a8711291e412a3ad1c69ece5
 SHA512:
-  metadata.gz: 3bb70e134009c39efe0a912ff507d0a6c79f7613dda511f3dc9fa968467ddfc5df69faa78f85667cca66d7d4a019188d0968ac6ba94f2eac046f4923e835c995
-  data.tar.gz: d641d16f38405cad36806eac8b346c9e6aa228cb46a1365cb1dd8f7ddf2f22181a531def080dc8d77fec3a1447db57ac904a2a45c3756d8ec4c4d9e48ed87c6b
+  metadata.gz: 88c4848ab50045afa539f92fee68585b0bcdc61719cb99723b3758eba772ace18f810b1c81d8f024173604c4161ab0b4ada6b247a32d69ba3005c572ed341b79
+  data.tar.gz: 21304aa42d250e86ccf868342158a7d8f1135a7344bdc1407a4395de1bd7cccdf72f55dba9d4a3bb0cab22f73a7223c524788b96b537fd264ad9402c23d7afb4

data/lib/freshbooks/api.rb

@@ -41,8 +41,6 @@ module FreshBooks
         # --- Paginated fetch ---
 
         def fetch_all_pages(url, result_key, params: {})
-          return [] if Thread.current[:fb_dry_run]
-
           page = 1
           all_items = []
 
@@ -132,8 +130,6 @@ module FreshBooks
         # --- Services ---
 
         def fetch_services(force: false)
-          return (Auth.load_cache["services_data"] || []) if Thread.current[:fb_dry_run]
-
           unless force
             cached = cached_data("services_data")
             return cached if cached

data/lib/freshbooks/auth.rb

@@ -9,6 +9,8 @@ require "dotenv"
 module FreshBooks
   module CLI
     class Auth
+      class TokenRefreshError < StandardError; end
+
       TOKEN_URL = "https://api.freshbooks.com/auth/oauth/token"
       AUTH_URL = "https://auth.freshbooks.com/oauth/authorize"
       ME_URL = "https://api.freshbooks.com/auth/api/v1/users/me"
@@ -60,6 +62,10 @@ module FreshBooks
           File.join(data_dir, "tokens.json")
         end
 
+        def tokens_lock_path
+          File.join(data_dir, "tokens.json.lock")
+        end
+
         def defaults_path
           File.join(data_dir, "defaults.json")
         end
@@ -200,14 +206,28 @@ module FreshBooks
         def auth_status
           config = load_config
           tokens = load_tokens
+          refresh_error = nil
+
+          if config && tokens && token_expired?(tokens)
+            begin
+              tokens = refresh_token_with_lock(config, tokens, abort_on_failure: false)
+            rescue TokenRefreshError => e
+              refresh_error = e.message
+            end
+          end
+
+          tokens_expired = tokens ? token_expired?(tokens) : nil
+          requires_reauth = config.nil? || tokens.nil? || tokens_expired == true
           {
             "config_exists" => !config.nil?,
             "config_path" => config_path,
             "tokens_exist" => !tokens.nil?,
-            "tokens_expired" => tokens ? token_expired?(tokens) : nil,
+            "tokens_expired" => tokens_expired,
+            "requires_reauth" => requires_reauth,
+            "refresh_error" => refresh_error,
             "business_id" => config&.dig("business_id"),
             "account_id" => config&.dig("account_id")
-          }
+          }.compact
         end
 
         def fetch_businesses(access_token)
@@ -258,7 +278,15 @@ module FreshBooks
 
         def save_tokens(tokens)
           ensure_data_dir
-          File.write(tokens_path, JSON.pretty_generate(tokens) + "\n")
+          tmp_path = "#{tokens_path}.#{$$}.tmp"
+          File.open(tmp_path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+            file.write(JSON.pretty_generate(tokens) + "\n")
+            file.flush
+            file.fsync
+          end
+          File.rename(tmp_path, tokens_path)
+        ensure
+          File.delete(tmp_path) if tmp_path && File.exist?(tmp_path)
         end
 
         def token_expired?(tokens)
@@ -268,22 +296,30 @@ module FreshBooks
           Time.now.to_i >= (created + expires_in - 60)
         end
 
-        def refresh_token!(config, tokens)
-          response = HTTParty.post(TOKEN_URL, {
-            headers: { "Content-Type" => "application/json" },
-            body: {
-              grant_type: "refresh_token",
-              client_id: config["client_id"],
-              client_secret: config["client_secret"],
-              redirect_uri: REDIRECT_URI,
-              refresh_token: tokens["refresh_token"]
-            }.to_json
-          })
+        def refresh_token!(config, tokens, abort_on_failure: true)
+          begin
+            response = HTTParty.post(TOKEN_URL, {
+              headers: { "Content-Type" => "application/json" },
+              body: {
+                grant_type: "refresh_token",
+                client_id: config["client_id"],
+                client_secret: config["client_secret"],
+                redirect_uri: REDIRECT_URI,
+                refresh_token: tokens["refresh_token"]
+              }.to_json
+            })
+          rescue StandardError => e
+            message = "Token refresh failed: #{e.class}: #{e.message}\nPlease re-run: fb auth"
+            raise if abort_on_failure
+            raise TokenRefreshError, message
+          end
 
           unless response.success?
             body = response.parsed_response
             msg = body.is_a?(Hash) ? (body["error_description"] || body["error"] || response.body) : response.body
-            abort("Token refresh failed: #{msg}\nPlease re-run: fb auth")
+            message = "Token refresh failed: #{msg}\nPlease re-run: fb auth"
+            abort(message) if abort_on_failure
+            raise TokenRefreshError, message
           end
 
           data = response.parsed_response
@@ -297,6 +333,20 @@ module FreshBooks
           new_tokens
         end
 
+        def refresh_token_with_lock(config, tokens, abort_on_failure: true)
+          ensure_data_dir
+          File.open(tokens_lock_path, File::RDWR | File::CREAT, 0o600) do |lock_file|
+            lock_file.flock(File::LOCK_EX)
+
+            latest_tokens = load_tokens || tokens
+            return latest_tokens if latest_tokens && !token_expired?(latest_tokens)
+
+            refresh_token!(config, latest_tokens || tokens, abort_on_failure: abort_on_failure)
+          ensure
+            lock_file.flock(File::LOCK_UN)
+          end
+        end
+
         def valid_access_token
           if Thread.current[:fb_dry_run]
             tokens = load_tokens
@@ -315,7 +365,7 @@ module FreshBooks
 
           if token_expired?(tokens)
             puts "Token expired, refreshing..."
-            tokens = refresh_token!(config, tokens)
+            tokens = refresh_token_with_lock(config, tokens)
           end
 
           tokens["access_token"]

data/lib/freshbooks/cli.rb

@@ -13,10 +13,48 @@ module FreshBooks
         true
       end
 
+      def self.dispatch(command, given_args, given_opts, config)
+        requested_command = command || given_args.first
+
+        super
+      rescue Thor::UnknownArgumentError => e
+        if requested_command.to_s == "log"
+          unknown_option = e.unknown.first
+          raise Thor::InvocationError, log_parse_error_message(unknown_option, e.message)
+        end
+
+        raise
+      end
+
+      def self.handle_argument_error(command, error, args, arity)
+        unknown_option = args.find { |arg| arg.to_s.start_with?("--") }
+        if command.name == "log" && unknown_option
+          raise Thor::InvocationError, log_parse_error_message(unknown_option, error.message)
+        end
+
+        super
+      end
+
+      def self.log_parse_error_message(option, fallback)
+        suggestion = { "--hours" => "--duration", "--notes" => "--note" }[option]
+        lines = ["Unknown option: #{option || fallback}"]
+        lines << "Did you mean: #{suggestion}" if suggestion
+        lines.concat([
+          "",
+          "fb log requires:",
+          "  --duration HOURS",
+          "  --note TEXT",
+          "",
+          "Example:",
+          '  fb log --project "Sample Project" --service "Development" --duration 0.5 --note "Reviewed pull requests" --yes'
+        ])
+        lines.join("\n")
+      end
+
       class_option :no_interactive, type: :boolean, default: false, desc: "Disable interactive prompts (auto-detected when not a TTY)"
       class_option :interactive, type: :boolean, default: false, desc: "Force interactive mode even when not a TTY"
       class_option :format, type: :string, desc: "Output format: table (default) or json"
-      class_option :dry_run, type: :boolean, default: false, desc: "Simulate command without making network calls"
+      class_option :dry_run, type: :boolean, default: false, desc: "Simulate writes while allowing read lookups"
 
       no_commands do
         def invoke_command(command, *args)
@@ -124,6 +162,7 @@ module FreshBooks
             if status_data["tokens_exist"]
               puts "Expired: #{status_data["tokens_expired"] ? "yes" : "no"}"
             end
+            puts "Requires re-auth: #{status_data["requires_reauth"] ? "yes" : "no"}"
             puts "Business ID: #{status_data["business_id"] || "not set"}"
             puts "Account ID: #{status_data["account_id"] || "not set"}"
           end
@@ -210,16 +249,32 @@ module FreshBooks
 
       # --- log ---
 
-      desc "log", "Log a time entry"
+      desc "log [--client NAME] [--project NAME] [--service NAME] --duration HOURS --note TEXT [--date YYYY-MM-DD] [--internal] [--yes]",
+        "Log a time entry"
+      long_desc <<~DESC
+        Log a FreshBooks time entry.
+
+        Non-interactive usage requires --duration and --note. Use --client when multiple clients exist, or --internal with --project for internal work.
+
+        Examples:
+          fb log --project "Sample Project" --service "Development" --duration 0.5 --note "Reviewed pull requests" --yes
+          fb log --internal --project "Admin" --hours 1 --notes "Planning" --yes
+      DESC
       method_option :client, type: :string, desc: "Pre-select client by name"
       method_option :project, type: :string, desc: "Pre-select project by name"
       method_option :service, type: :string, desc: "Pre-select service by name"
-      method_option :duration, type: :numeric, desc: "Duration in hours (e.g. 2.5)"
-      method_option :note, type: :string, desc: "Work description"
+      method_option :duration, type: :numeric, aliases: "--hours", desc: "Duration in hours (e.g. 2.5)"
+      method_option :note, type: :string, aliases: "--notes", desc: "Work description"
       method_option :date, type: :string, desc: "Date (YYYY-MM-DD, defaults to today)"
       method_option :internal, type: :boolean, default: false, desc: "Log to an internal project with no client"
       method_option :yes, type: :boolean, default: false, desc: "Skip confirmation"
+      method_option :help, type: :boolean, desc: "Show command help"
       def log
+        if options[:help]
+          self.class.command_help(shell, "log")
+          return
+        end
+
         Auth.valid_access_token
         defaults = Auth.load_defaults
 
@@ -517,8 +572,8 @@ module FreshBooks
 
       desc "edit", "Edit a time entry"
       method_option :id, type: :numeric, desc: "Time entry ID (skip interactive picker)"
-      method_option :duration, type: :numeric, desc: "New duration in hours"
-      method_option :note, type: :string, desc: "New note"
+      method_option :duration, type: :numeric, aliases: "--hours", desc: "New duration in hours"
+      method_option :note, type: :string, aliases: "--notes", desc: "New note"
       method_option :date, type: :string, desc: "New date (YYYY-MM-DD)"
       method_option :client, type: :string, desc: "New client name"
       method_option :project, type: :string, desc: "New project name"
@@ -1066,7 +1121,7 @@ module FreshBooks
           global_flags: {
             "--no-interactive" => "Disable interactive prompts (auto-detected when not a TTY)",
             "--format json"    => "Output format: json (available on all commands)",
-            "--dry-run"        => "Simulate command without making network calls (writes skipped)"
+            "--dry-run"        => "Simulate writes while allowing read lookups"
           },
           commands: {
             auth: {

data/lib/freshbooks/version.rb

@@ -2,6 +2,6 @@
 
 module FreshBooks
   module CLI
-    VERSION = "0.5.0"
+    VERSION = "0.5.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: freshbooks-cli
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - parasquid
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-23 00:00:00.000000000 Z
+date: 2026-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor