freshbooks-cli 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84f4c3c33549e8e6f23749a6597fe394d6d94b248c54453810c4bd198b3e4294
-  data.tar.gz: 76d88cb16bf1d4b9298869c4b0a9db068157cbd6e068c851e27a834516b5baa8
+  metadata.gz: 72c774411761de2ede345e21a6961b2dace9debd2adf089b948c6cdd2447ac9b
+  data.tar.gz: a289b2ae8edb32a9759fc35b96165dc261254594a8711291e412a3ad1c69ece5
 SHA512:
-  metadata.gz: 0cba9865b5c7b5e1e2e2b11590be7044803ca4afbb0a8eeba1d3136a84fc5ebaadfd542bf531d3d37073274936f30794dad006348a09bc4fc424a79ef993fc73
-  data.tar.gz: 8d11babdd9b8f3406a664d13f89cca6c5fd915b8154044bfe9dddb3fea2b620ac99d8c0b774a8ffa81c5d32c6e9dfb4521ffaa728dc1f3b68d122e645c21de3d
+  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,26 +249,44 @@ 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
 
-        client = select_client(defaults)
-        project = select_project(client["id"], defaults)
+        context = resolve_log_context(defaults)
+        client = context[:client]
+        project = context[:project]
         service = select_service(defaults, project)
         date = pick_date
         duration_hours = pick_duration
         note = pick_note
 
-        client_name = display_name(client)
+        client_name = client ? display_name(client) : "Internal"
 
         unless options[:format] == "json"
           puts "\n--- Time Entry Summary ---"
@@ -252,9 +309,9 @@ module FreshBooks
           "is_logged" => true,
           "duration" => (duration_hours * 3600).to_i,
           "note" => note,
-          "started_at" => normalize_datetime(date),
-          "client_id" => client["id"]
+          "started_at" => normalize_datetime(date)
         }
+        entry["client_id"] = client["id"] if client
         entry["project_id"] = project["id"] if project
         entry["service_id"] = service["id"] if service
 
@@ -266,7 +323,8 @@ module FreshBooks
           puts "Time entry created!"
         end
 
-        new_defaults = { "client_id" => client["id"] }
+        new_defaults = {}
+        new_defaults["client_id"] = client["id"] if client
         new_defaults["project_id"] = project["id"] if project
         new_defaults["service_id"] = service["id"] if service
         Auth.save_defaults(new_defaults)
@@ -328,7 +386,7 @@ module FreshBooks
 
         rows = entries.map do |e|
           date = (e["local_started_at"] || e["started_at"] || "?").slice(0, 10)
-          client = maps[:clients][e["client_id"].to_s] || e["client_id"].to_s
+          client = display_client_name(e["client_id"], maps)
           project = maps[:projects][e["project_id"].to_s] || "-"
           service = maps[:services][e["service_id"].to_s] || "-"
           note = e["note"] || ""
@@ -341,7 +399,7 @@ module FreshBooks
         total = entries.sum { |e| e["duration"].to_i } / 3600.0
 
         # Per-client breakdown
-        by_client = entries.group_by { |e| maps[:clients][e["client_id"].to_s] || e["client_id"].to_s }
+        by_client = entries.group_by { |e| display_client_name(e["client_id"], maps) }
         if by_client.length > 1
           puts "\nBy client:"
           by_client.sort_by { |_, es| -es.sum { |e| e["duration"].to_i } }.each do |name, es|
@@ -416,7 +474,7 @@ module FreshBooks
         end
 
         rows = projects.map do |p|
-          client_name = maps[:clients][p["client_id"].to_s] || "-"
+          client_name = display_project_client_name(p, maps)
           [p["title"], client_name, p["active"] ? "active" : "inactive"]
         end
 
@@ -514,12 +572,13 @@ 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"
       method_option :service, type: :string, desc: "New service name"
+      method_option :internal, type: :boolean, default: false, desc: "Move entry to an internal project with no client"
       method_option :yes, type: :boolean, default: false, desc: "Skip confirmation"
       def edit
         Auth.valid_access_token
@@ -535,7 +594,7 @@ module FreshBooks
         abort("Time entry not found.") unless entry
 
         maps = Spinner.spin("Resolving names") { Api.build_name_maps }
-        has_edit_flags = options[:duration] || options[:note] || options[:date] || options[:client] || options[:project] || options[:service]
+        has_edit_flags = options[:duration] || options[:note] || options[:date] || options[:client] || options[:project] || options[:service] || options[:internal]
         scripted = has_edit_flags || !interactive?
 
         fields = build_edit_fields(entry, maps, scripted)
@@ -544,11 +603,18 @@ module FreshBooks
         current_project = maps[:projects][entry["project_id"].to_s] || "-"
         current_hours = (entry["duration"].to_i / 3600.0).round(2)
         new_hours = fields["duration"] ? (fields["duration"].to_i / 3600.0).round(2) : current_hours
+        summary_client = if fields.key?("client_id")
+          fields["client_id"] ? maps[:clients][fields["client_id"].to_s] : "Internal"
+        elsif fields["project_id"] != entry["project_id"]
+          "Internal"
+        else
+          current_client
+        end
 
         unless options[:format] == "json"
           puts "\n--- Edit Summary ---"
           puts "  Date:     #{fields["started_at"] || entry["started_at"]}"
-          puts "  Client:   #{fields["client_id"] ? maps[:clients][fields["client_id"].to_s] : current_client}"
+          puts "  Client:   #{summary_client}"
           puts "  Project:  #{fields["project_id"] ? maps[:projects][fields["project_id"].to_s] : current_project}"
           puts "  Duration: #{new_hours}h"
           puts "  Note:     #{fields["note"] || entry["note"]}"
@@ -646,6 +712,63 @@ module FreshBooks
         $stdin.tty?
       end
 
+      def resolve_log_context(defaults)
+        validate_internal_log_options!
+
+        if options[:project] && (!options[:client] || options[:internal])
+          project = resolve_project_by_name(options[:project], force: true)
+          ensure_project_matches_internal_option!(project)
+          client = project_internal?(project) ? nil : resolve_client_for_project(project)
+          return { client: client, project: project }
+        end
+
+        client = select_client(defaults)
+        project = select_project(client["id"], defaults)
+        { client: client, project: project }
+      end
+
+      def validate_internal_log_options!
+        abort("Cannot combine --client with --internal.") if options[:client] && options[:internal]
+        abort("--internal requires --project.") if options[:internal] && !options[:project]
+      end
+
+      def validate_internal_edit_options!
+        abort("Cannot combine --client with --internal.") if options[:client] && options[:internal]
+        abort("--internal requires --project.") if options[:internal] && !options[:project]
+      end
+
+      def resolve_project_by_name(name, force: false)
+        projects = Spinner.spin("Fetching projects") { Api.fetch_projects(force: force) }
+        match = projects.find { |project| project["title"].downcase == name.downcase }
+        abort("Project not found: #{name}") unless match
+        match
+      end
+
+      def project_internal?(project)
+        project["internal"] || project["client_id"].nil?
+      end
+
+      def display_client_name(client_id, maps)
+        return "Internal" if client_id.nil?
+        maps[:clients][client_id.to_s] || client_id.to_s
+      end
+
+      def display_project_client_name(project, maps)
+        return "Internal" if project_internal?(project)
+        maps[:clients][project["client_id"].to_s] || "-"
+      end
+
+      def ensure_project_matches_internal_option!(project)
+        abort("Project #{project["title"]} is not internal.") if options[:internal] && !project_internal?(project)
+      end
+
+      def resolve_client_for_project(project)
+        clients = Spinner.spin("Fetching clients") { Api.fetch_clients }
+        match = clients.find { |client| client["id"].to_i == project["client_id"].to_i }
+        abort("Client not found for project: #{project["title"]}") unless match
+        match
+      end
+
       def select_client(defaults)
         clients = Spinner.spin("Fetching clients") { Api.fetch_clients }
 
@@ -865,7 +988,7 @@ module FreshBooks
 
         grouped = {}
         entries.each do |e|
-          client = maps[:clients][e["client_id"].to_s] || e["client_id"].to_s
+          client = display_client_name(e["client_id"], maps)
           project = maps[:projects][e["project_id"].to_s] || "-"
           key = "#{client} / #{project}"
           grouped[key] ||= 0.0
@@ -884,7 +1007,7 @@ module FreshBooks
         entry_data = entries.map do |e|
           {
             "id" => e["id"],
-            "client" => maps[:clients][e["client_id"].to_s] || e["client_id"].to_s,
+            "client" => display_client_name(e["client_id"], maps),
             "project" => maps[:projects][e["project_id"].to_s] || "-",
             "duration" => e["duration"],
             "hours" => (e["duration"].to_i / 3600.0).round(2),
@@ -907,7 +1030,7 @@ module FreshBooks
 
         puts "\nToday's entries:\n\n"
         entries.each_with_index do |e, i|
-          client = maps[:clients][e["client_id"].to_s] || e["client_id"].to_s
+          client = display_client_name(e["client_id"], maps)
           hours = (e["duration"].to_i / 3600.0).round(2)
           note = (e["note"] || "").slice(0, 40)
           puts "  #{i + 1}. [#{e["id"]}] #{client} — #{hours}h — #{note}"
@@ -935,22 +1058,26 @@ module FreshBooks
         }
 
         if scripted
+          validate_internal_edit_options!
           fields["duration"] = (options[:duration] * 3600).to_i if options[:duration]
           fields["note"] = options[:note] if options[:note]
           fields["started_at"] = normalize_datetime(options[:date]) if options[:date]
 
-          if options[:client]
+          if options[:project]
+            project = resolve_project_by_name(options[:project], force: true)
+            ensure_project_matches_internal_option!(project)
+            fields["project_id"] = project["id"]
+            if project_internal?(project)
+              fields.delete("client_id")
+            else
+              fields["client_id"] = project["client_id"].to_i
+            end
+          elsif options[:client]
             client_id = maps[:clients].find { |_id, name| name.downcase == options[:client].downcase }&.first
             abort("Client not found: #{options[:client]}") unless client_id
             fields["client_id"] = client_id.to_i
           end
 
-          if options[:project]
-            project_id = maps[:projects].find { |_id, name| name.downcase == options[:project].downcase }&.first
-            abort("Project not found: #{options[:project]}") unless project_id
-            fields["project_id"] = project_id.to_i
-          end
-
           if options[:service]
             service_id = maps[:services].find { |_id, name| name.downcase == options[:service].downcase }&.first
             abort("Service not found: #{options[:service]}") unless service_id
@@ -994,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: {
@@ -1023,12 +1150,13 @@ module FreshBooks
               usage: "fb log",
               interactive: "Prompts for missing fields when interactive; requires --duration and --note when non-interactive",
               flags: {
-                "--client" => "Client name (required non-interactive if multiple clients, auto-selected if single)",
-                "--project" => "Project name (optional, auto-selected if single)",
-                "--service" => "Service name (optional)",
+                "--client" => "Client name (required only for client-backed resolution when multiple clients exist)",
+                "--project" => "Project name (can be internal; internal projects may be used without --client)",
+                "--service" => "Service name (project-scoped; optional if single/default)",
                 "--duration" => "Duration in hours, e.g. 2.5 (required non-interactive)",
                 "--note" => "Work description (required non-interactive)",
                 "--date" => "Date YYYY-MM-DD (defaults to today)",
+                "--internal" => "Force internal-project resolution; requires --project and conflicts with --client",
                 "--yes" => "Skip confirmation prompt"
               }
             },
@@ -1080,8 +1208,9 @@ module FreshBooks
                 "--note" => "New note",
                 "--date" => "New date (YYYY-MM-DD)",
                 "--client" => "New client name",
-                "--project" => "New project name",
+                "--project" => "New project name (internal projects omit client_id)",
                 "--service" => "New service name",
+                "--internal" => "Force internal-project resolution; requires --project and conflicts with --client",
                 "--yes" => "Skip confirmation prompt"
               }
             },

data/lib/freshbooks/version.rb

@@ -2,6 +2,6 @@
 
 module FreshBooks
   module CLI
-    VERSION = "0.4.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.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - parasquid
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor