freshbooks-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d293f888f52e04f38fd9c325292b83ab1373d3587ca615e48e3c428c9eb4c27d
+  data.tar.gz: 0b7b59a6bcde4b4511019cb72b3f3518b92b96d3b2db4f53176f31f0ad20d888
+SHA512:
+  metadata.gz: b7668df61766607e2d14eafc157772e673d86c8353a7161bdc0452fd3f33c00cbb57b2975d60c62d0ad317fbf22fc934cd060299b4292d010cd192f13aa64746
+  data.tar.gz: 8329f4f4d3d76efd1d9d808cce0fff2d018be1791f93725d9df14ed1ca1c106aa80e3ce6f45c2e4d9853fcc1836484d28c3c6a2e25409cb93266e9b717e81f8c

data/bin/fb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fb"
+
+FB::Cli.start(ARGV)

data/lib/fb/api.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module FB
+  class Api
+    BASE = "https://api.freshbooks.com"
+
+    class << self
+      def headers
+        token = Auth.valid_access_token
+        {
+          "Authorization" => "Bearer #{token}",
+          "Content-Type" => "application/json"
+        }
+      end
+
+      def config
+        @config = nil
+        @config = Auth.require_config
+      end
+
+      def business_id
+        c = config
+        unless c["business_id"]
+          c = Auth.require_business(c)
+        end
+        c["business_id"]
+      end
+
+      def account_id
+        c = config
+        unless c["account_id"]
+          c = Auth.require_business(c)
+        end
+        c["account_id"]
+      end
+
+      # --- Paginated fetch ---
+
+      def fetch_all_pages(url, result_key, params: {})
+        page = 1
+        all_items = []
+
+        loop do
+          response = HTTParty.get(url, {
+            headers: headers,
+            query: params.merge(page: page, per_page: 100)
+          })
+
+          unless response.success?
+            body = response.parsed_response
+            msg = extract_error(body) || response.body
+            abort("API error: #{msg}")
+          end
+
+          data = response.parsed_response
+          items = dig_results(data, result_key)
+          break if items.nil? || items.empty?
+
+          all_items.concat(items)
+
+          meta = dig_meta(data)
+          break if meta.nil?
+          break if page >= meta["pages"].to_i
+
+          page += 1
+        end
+
+        all_items
+      end
+
+      # --- Clients ---
+
+      def fetch_clients
+        url = "#{BASE}/accounting/account/#{account_id}/users/clients"
+        fetch_all_pages(url, "clients")
+      end
+
+      # --- Projects ---
+
+      def fetch_projects
+        url = "#{BASE}/projects/business/#{business_id}/projects"
+        fetch_all_pages(url, "projects")
+      end
+
+      def fetch_projects_for_client(client_id)
+        all = fetch_projects
+        all.select { |p| p["client_id"].to_i == client_id.to_i }
+      end
+
+      # --- Services ---
+
+      def fetch_services
+        url = "#{BASE}/comments/business/#{business_id}/services"
+        response = HTTParty.get(url, { headers: headers })
+
+        unless response.success?
+          body = response.parsed_response
+          msg = extract_error(body) || response.body
+          abort("API error: #{msg}")
+        end
+
+        data = response.parsed_response
+        services_hash = data.dig("result", "services") || {}
+        services_hash.values
+      end
+
+      # --- Time Entries ---
+
+      def fetch_time_entries(started_from: nil, started_to: nil)
+        url = "#{BASE}/timetracking/business/#{business_id}/time_entries"
+        params = {}
+        params["started_from"] = "#{started_from}T00:00:00Z" if started_from
+        params["started_to"] = "#{started_to}T23:59:59Z" if started_to
+        fetch_all_pages(url, "time_entries", params: params)
+      end
+
+      def create_time_entry(entry)
+        url = "#{BASE}/timetracking/business/#{business_id}/time_entries"
+        body = { time_entry: entry }
+
+        response = HTTParty.post(url, {
+          headers: headers,
+          body: body.to_json
+        })
+
+        unless response.success?
+          body = response.parsed_response
+          msg = extract_error(body) || response.body
+          abort("API error: #{msg}")
+        end
+
+        response.parsed_response
+      end
+
+      # --- Name Resolution (for entries display) ---
+
+      def build_name_maps
+        cache = Auth.load_cache
+        now = Time.now.to_i
+
+        if cache["updated_at"] && (now - cache["updated_at"]) < 600
+          return {
+            clients: (cache["clients"] || {}),
+            projects: (cache["projects"] || {})
+          }
+        end
+
+        clients = fetch_clients
+        projects = fetch_projects
+
+        client_map = {}
+        clients.each do |c|
+          name = c["organization"]
+          name = "#{c["fname"]} #{c["lname"]}" if name.nil? || name.empty?
+          client_map[c["id"].to_s] = name
+        end
+
+        project_map = {}
+        projects.each do |p|
+          project_map[p["id"].to_s] = p["title"]
+        end
+
+        cache_data = {
+          "updated_at" => now,
+          "clients" => client_map,
+          "projects" => project_map
+        }
+        Auth.save_cache(cache_data)
+
+        { clients: client_map, projects: project_map }
+      end
+
+      private
+
+      def extract_error(body)
+        return nil unless body.is_a?(Hash)
+        body["error_description"] ||
+          body.dig("response", "errors", 0, "message") ||
+          body.dig("error") ||
+          body.dig("message")
+      end
+
+      def dig_results(data, key)
+        data.dig("result", key) ||
+          data.dig("response", "result", key) ||
+          data.dig(key)
+      end
+
+      def dig_meta(data)
+        data.dig("result", "meta") ||
+          data.dig("response", "result", "meta") ||
+          data.dig("meta")
+      end
+    end
+  end
+end

data/lib/fb/auth.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+require "uri"
+require "fileutils"
+
+module FB
+  class Auth
+    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"
+    REDIRECT_URI = "https://localhost"
+    REQUIRED_SCOPES = %w[
+      user:profile:read
+      user:clients:read
+      user:projects:read
+      user:billable_items:read
+      user:time_entries:read
+      user:time_entries:write
+    ].freeze
+
+    class << self
+      def data_dir
+        @data_dir ||= File.join(Dir.home, ".fb")
+      end
+
+      def data_dir=(path)
+        @data_dir = path
+      end
+
+      def config_path
+        File.join(data_dir, "config.json")
+      end
+
+      def tokens_path
+        File.join(data_dir, "tokens.json")
+      end
+
+      def defaults_path
+        File.join(data_dir, "defaults.json")
+      end
+
+      def cache_path
+        File.join(data_dir, "cache.json")
+      end
+
+      def ensure_data_dir
+        FileUtils.mkdir_p(data_dir)
+      end
+
+      # --- Config ---
+
+      def load_config
+        return nil unless File.exist?(config_path)
+        contents = File.read(config_path).strip
+        return nil if contents.empty?
+        config = JSON.parse(contents)
+        return nil unless config["client_id"] && config["client_secret"]
+        config
+      rescue JSON::ParserError
+        nil
+      end
+
+      def save_config(config)
+        ensure_data_dir
+        File.write(config_path, JSON.pretty_generate(config) + "\n")
+      end
+
+      def setup_config
+        puts "Welcome to FreshBooks CLI setup!\n\n"
+        puts "You need a FreshBooks Developer App. Create one at:"
+        puts "  https://my.freshbooks.com/#/developer\n\n"
+        puts "Set the redirect URI to: #{REDIRECT_URI}\n\n"
+        puts "Required scopes:"
+        puts "  user:profile:read          (enabled by default)"
+        puts "  user:clients:read"
+        puts "  user:projects:read"
+        puts "  user:billable_items:read"
+        puts "  user:time_entries:read"
+        puts "  user:time_entries:write\n\n"
+
+        print "Client ID: "
+        client_id = $stdin.gets&.strip
+        abort("Aborted.") if client_id.nil? || client_id.empty?
+
+        print "Client Secret: "
+        client_secret = $stdin.gets&.strip
+        abort("Aborted.") if client_secret.nil? || client_secret.empty?
+
+        config = { "client_id" => client_id, "client_secret" => client_secret }
+        save_config(config)
+        puts "\nConfig saved to #{config_path}"
+        config
+      end
+
+      def require_config
+        config = load_config
+        return config if config
+
+        puts "No config found. Let's set up FreshBooks CLI.\n\n"
+        setup_config
+      end
+
+      # --- Tokens ---
+
+      def load_tokens
+        return nil unless File.exist?(tokens_path)
+        JSON.parse(File.read(tokens_path))
+      end
+
+      def save_tokens(tokens)
+        ensure_data_dir
+        File.write(tokens_path, JSON.pretty_generate(tokens) + "\n")
+      end
+
+      def token_expired?(tokens)
+        return true unless tokens
+        created = tokens["created_at"] || 0
+        expires_in = tokens["expires_in"] || 0
+        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
+        })
+
+        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")
+        end
+
+        data = response.parsed_response
+        new_tokens = {
+          "access_token" => data["access_token"],
+          "refresh_token" => data["refresh_token"],
+          "expires_in" => data["expires_in"],
+          "created_at" => Time.now.to_i
+        }
+        save_tokens(new_tokens)
+        new_tokens
+      end
+
+      def valid_access_token
+        config = require_config
+        tokens = load_tokens
+
+        unless tokens
+          puts "Not authenticated yet. Starting auth flow...\n\n"
+          tokens = authorize(config)
+          discover_business(tokens["access_token"], config)
+        end
+
+        if token_expired?(tokens)
+          puts "Token expired, refreshing..."
+          tokens = refresh_token!(config, tokens)
+        end
+
+        tokens["access_token"]
+      end
+
+      def require_business(config)
+        return config if config["business_id"] && config["account_id"]
+
+        tokens = load_tokens
+        unless tokens
+          puts "Not authenticated yet. Starting auth flow...\n\n"
+          tokens = authorize(config)
+        end
+
+        discover_business(tokens["access_token"], config)
+      end
+
+      # --- OAuth Flow ---
+
+      def authorize(config)
+        url = "#{AUTH_URL}?client_id=#{config["client_id"]}&response_type=code&redirect_uri=#{URI.encode_www_form_component(REDIRECT_URI)}"
+
+        puts "Open this URL in your browser:\n\n"
+        puts "  #{url}\n\n"
+        puts "After authorizing, you'll be redirected to a URL that fails to load."
+        puts "Copy the full URL from your browser's address bar and paste it here.\n\n"
+
+        print "Redirect URL: "
+        redirect_url = $stdin.gets&.strip
+        abort("Aborted.") if redirect_url.nil? || redirect_url.empty?
+
+        uri = URI.parse(redirect_url)
+        params = URI.decode_www_form(uri.query || "").to_h
+        code = params["code"]
+
+        abort("Could not find 'code' parameter in the URL.") unless code
+
+        exchange_code(config, code)
+      end
+
+      def exchange_code(config, code)
+        response = HTTParty.post(TOKEN_URL, {
+          headers: { "Content-Type" => "application/json" },
+          body: {
+            grant_type: "authorization_code",
+            client_id: config["client_id"],
+            client_secret: config["client_secret"],
+            redirect_uri: REDIRECT_URI,
+            code: code
+          }.to_json
+        })
+
+        unless response.success?
+          body = response.parsed_response
+          msg = body.is_a?(Hash) ? (body["error_description"] || body["error"] || response.body) : response.body
+          abort("Token exchange failed: #{msg}")
+        end
+
+        data = response.parsed_response
+        check_scopes(data["scope"])
+
+        tokens = {
+          "access_token" => data["access_token"],
+          "refresh_token" => data["refresh_token"],
+          "expires_in" => data["expires_in"],
+          "created_at" => Time.now.to_i
+        }
+        save_tokens(tokens)
+        puts "Authentication successful!"
+        tokens
+      end
+
+      def check_scopes(granted_scope)
+        return if granted_scope.nil? # skip check if API doesn't return scopes
+
+        granted = granted_scope.split(" ")
+        missing = REQUIRED_SCOPES - granted
+
+        return if missing.empty?
+
+        puts "ERROR: Your FreshBooks app is missing required scopes:\n\n"
+        missing.each { |s| puts "  - #{s}" }
+        puts "\nAdd them at https://my.freshbooks.com/#/developer"
+        puts "then re-run: fb auth"
+        abort
+      end
+
+      # --- Business Discovery ---
+
+      def fetch_identity(access_token)
+        response = HTTParty.get(ME_URL, {
+          headers: { "Authorization" => "Bearer #{access_token}" }
+        })
+
+        unless response.success?
+          abort("Failed to fetch user identity: #{response.body}")
+        end
+
+        response.parsed_response["response"]
+      end
+
+      def discover_business(access_token, config)
+        identity = fetch_identity(access_token)
+        memberships = identity.dig("business_memberships") || []
+        businesses = memberships.select { |m| m.dig("business", "account_id") }
+
+        if businesses.empty?
+          abort("No business memberships found on your FreshBooks account.")
+        end
+
+        selected = if businesses.length == 1
+          businesses.first
+        else
+          puts "\nMultiple businesses found:\n\n"
+          businesses.each_with_index do |m, i|
+            biz = m["business"]
+            puts "  #{i + 1}. #{biz["name"]} (ID: #{biz["id"]})"
+          end
+          print "\nSelect a business (1-#{businesses.length}): "
+          choice = $stdin.gets&.strip&.to_i || 1
+          choice = 1 if choice < 1 || choice > businesses.length
+          businesses[choice - 1]
+        end
+
+        biz = selected["business"]
+        config["business_id"] = biz["id"]
+        config["account_id"] = biz["account_id"]
+        save_config(config)
+
+        puts "Business: #{biz["name"]}"
+        puts "  business_id: #{biz["id"]}"
+        puts "  account_id: #{biz["account_id"]}"
+        config
+      end
+
+      # --- Defaults ---
+
+      def load_defaults
+        return {} unless File.exist?(defaults_path)
+        JSON.parse(File.read(defaults_path))
+      rescue JSON::ParserError
+        {}
+      end
+
+      def save_defaults(defaults)
+        ensure_data_dir
+        File.write(defaults_path, JSON.pretty_generate(defaults) + "\n")
+      end
+
+      # --- Cache ---
+
+      def load_cache
+        return {} unless File.exist?(cache_path)
+        JSON.parse(File.read(cache_path))
+      rescue JSON::ParserError
+        {}
+      end
+
+      def save_cache(cache)
+        ensure_data_dir
+        File.write(cache_path, JSON.pretty_generate(cache) + "\n")
+      end
+    end
+  end
+end

data/lib/fb/cli.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+require "date"
+
+module FB
+  class Cli < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    # --- auth ---
+
+    desc "auth", "Authenticate with FreshBooks via OAuth2"
+    def auth
+      config = Auth.require_config
+      tokens = Auth.authorize(config)
+      Auth.discover_business(tokens["access_token"], config)
+      puts "\nReady to go! Try: fb entries"
+    end
+
+    # --- log ---
+
+    desc "log", "Log a time entry"
+    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 :date, type: :string, desc: "Date (YYYY-MM-DD, defaults to today)"
+    method_option :yes, type: :boolean, default: false, desc: "Skip confirmation"
+    def log
+      Auth.require_config
+      defaults = Auth.load_defaults
+      interactive = !(options[:client] && options[:duration] && options[:note])
+
+      client = select_client(defaults, interactive)
+      project = select_project(client["id"], defaults, interactive)
+      service = select_service(defaults, interactive)
+      date = pick_date(interactive)
+      duration_hours = pick_duration(interactive)
+      note = pick_note(interactive)
+
+      client_name = display_name(client)
+
+      puts "\n--- Time Entry Summary ---"
+      puts "  Client:   #{client_name}"
+      puts "  Project:  #{project ? project["title"] : "(none)"}"
+      puts "  Service:  #{service ? service["name"] : "(none)"}"
+      puts "  Date:     #{date}"
+      puts "  Duration: #{duration_hours}h"
+      puts "  Note:     #{note}"
+      puts "--------------------------\n\n"
+
+      unless options[:yes]
+        print "Submit? (Y/n): "
+        answer = $stdin.gets&.strip&.downcase
+        abort("Cancelled.") if answer == "n"
+      end
+
+      entry = {
+        "is_logged" => true,
+        "duration" => (duration_hours * 3600).to_i,
+        "note" => note,
+        "started_at" => date,
+        "client_id" => client["id"]
+      }
+      entry["project_id"] = project["id"] if project
+      entry["service_id"] = service["id"] if service
+
+      Api.create_time_entry(entry)
+      puts "Time entry created!"
+
+      new_defaults = { "client_id" => client["id"] }
+      new_defaults["project_id"] = project["id"] if project
+      new_defaults["service_id"] = service["id"] if service
+      Auth.save_defaults(new_defaults)
+    end
+
+    # --- entries ---
+
+    desc "entries", "List time entries (defaults to current month)"
+    method_option :month, type: :numeric, desc: "Month (1-12)"
+    method_option :year, type: :numeric, desc: "Year"
+    method_option :from, type: :string, desc: "Start date (YYYY-MM-DD)"
+    method_option :to, type: :string, desc: "End date (YYYY-MM-DD)"
+    method_option :format, type: :string, default: "table", desc: "Output format: table or json"
+    def entries
+      Auth.require_config
+
+      today = Date.today
+
+      if options[:from] || options[:to]
+        first_day = options[:from] ? Date.parse(options[:from]) : nil
+        last_day = options[:to] ? Date.parse(options[:to]) : nil
+      else
+        month = options[:month] || today.month
+        year = options[:year] || today.year
+        first_day = Date.new(year, month, 1)
+        last_day = Date.new(year, month, -1)
+      end
+
+      label = if first_day && last_day
+        "#{first_day} to #{last_day}"
+      elsif first_day
+        "from #{first_day} onwards"
+      elsif last_day
+        "up to #{last_day}"
+      end
+
+      entries = Spinner.spin("Fetching time entries#{label ? " (#{label})" : ""}") do
+        Api.fetch_time_entries(
+          started_from: first_day&.to_s,
+          started_to: last_day&.to_s
+        )
+      end
+
+      if entries.empty?
+        puts "No time entries#{label ? " #{label}" : ""}."
+        return
+      end
+
+      if options[:format] == "json"
+        puts JSON.pretty_generate(entries)
+        return
+      end
+
+      maps = Spinner.spin("Resolving names") { Api.build_name_maps }
+      entries.sort_by! { |e| e["started_at"] || "" }
+
+      rows = entries.map do |e|
+        date = e["started_at"] || "?"
+        client = maps[:clients][e["client_id"].to_s] || e["client_id"].to_s
+        project = maps[:projects][e["project_id"].to_s] || "-"
+        note = (e["note"] || "").slice(0, 50)
+        hours = (e["duration"].to_i / 3600.0).round(2)
+        [date, client, project, note, "#{hours}h"]
+      end
+
+      headers = ["Date", "Client", "Project", "Note", "Duration"]
+      widths = headers.each_with_index.map do |h, i|
+        [h.length, *rows.map { |r| r[i].to_s.length }].max
+      end
+
+      fmt = widths.map { |w| "%-#{w}s" }.join("  ")
+      puts fmt % headers
+      puts widths.map { |w| "-" * w }.join("  ")
+      rows.each { |r| puts fmt % r }
+
+      total = entries.sum { |e| e["duration"].to_i } / 3600.0
+      puts "\nTotal: #{total.round(2)}h"
+    end
+
+    # --- help ---
+
+    desc "help [COMMAND]", "Describe available commands or one specific command"
+    method_option :format, type: :string, desc: "Output format: text (default) or json"
+    def help(command = nil)
+      if options[:format] == "json"
+        puts JSON.pretty_generate(help_json)
+        return
+      end
+      super
+    end
+
+    private
+
+    def select_client(defaults, interactive)
+      clients = Spinner.spin("Fetching clients") { Api.fetch_clients }
+
+      if options[:client]
+        match = clients.find { |c| display_name(c).downcase == options[:client].downcase }
+        abort("Client not found: #{options[:client]}") unless match
+        return match
+      end
+
+      abort("No clients found.") if clients.empty?
+
+      puts "\nClients:\n\n"
+      clients.each_with_index do |c, i|
+        name = display_name(c)
+        default_marker = c["id"].to_i == defaults["client_id"].to_i ? " [default]" : ""
+        puts "  #{i + 1}. #{name}#{default_marker}"
+      end
+
+      default_idx = clients.index { |c| c["id"].to_i == defaults["client_id"].to_i }
+      prompt = default_idx ? "\nSelect client (1-#{clients.length}) [#{default_idx + 1}]: " : "\nSelect client (1-#{clients.length}): "
+      print prompt
+      input = $stdin.gets&.strip
+
+      idx = if input.nil? || input.empty?
+        default_idx || 0
+      else
+        input.to_i - 1
+      end
+
+      abort("Invalid selection.") if idx < 0 || idx >= clients.length
+      clients[idx]
+    end
+
+    def select_project(client_id, defaults, interactive)
+      projects = Spinner.spin("Fetching projects") { Api.fetch_projects_for_client(client_id) }
+
+      if options[:project]
+        match = projects.find { |p| p["title"].downcase == options[:project].downcase }
+        abort("Project not found: #{options[:project]}") unless match
+        return match
+      end
+
+      return nil if projects.empty?
+
+      puts "\nProjects:\n\n"
+      projects.each_with_index do |p, i|
+        default_marker = p["id"].to_i == defaults["project_id"].to_i ? " [default]" : ""
+        puts "  #{i + 1}. #{p["title"]}#{default_marker}"
+      end
+
+      default_idx = projects.index { |p| p["id"].to_i == defaults["project_id"].to_i }
+      prompt = default_idx ? "\nSelect project (1-#{projects.length}, Enter to skip) [#{default_idx + 1}]: " : "\nSelect project (1-#{projects.length}, Enter to skip): "
+      print prompt
+      input = $stdin.gets&.strip
+
+      if input.nil? || input.empty?
+        return default_idx ? projects[default_idx] : nil
+      end
+
+      idx = input.to_i - 1
+      return nil if idx < 0 || idx >= projects.length
+      projects[idx]
+    end
+
+    def select_service(defaults, interactive)
+      if options[:service]
+        services = Spinner.spin("Fetching services") { Api.fetch_services }
+        match = services.find { |s| s["name"].downcase == options[:service].downcase }
+        abort("Service not found: #{options[:service]}") unless match
+        return match
+      end
+
+      return nil unless interactive
+
+      services = Spinner.spin("Fetching services") { Api.fetch_services }
+      return nil if services.empty?
+
+      puts "\nServices:\n\n"
+      services.each_with_index do |s, i|
+        default_marker = s["id"].to_i == defaults["service_id"].to_i ? " [default]" : ""
+        puts "  #{i + 1}. #{s["name"]}#{default_marker}"
+      end
+
+      default_idx = services.index { |s| s["id"].to_i == defaults["service_id"].to_i }
+      prompt = default_idx ? "\nSelect service (1-#{services.length}, Enter to skip) [#{default_idx + 1}]: " : "\nSelect service (1-#{services.length}, Enter to skip): "
+      print prompt
+      input = $stdin.gets&.strip
+
+      if input.nil? || input.empty?
+        return default_idx ? services[default_idx] : nil
+      end
+
+      idx = input.to_i - 1
+      return nil if idx < 0 || idx >= services.length
+      services[idx]
+    end
+
+    def pick_date(interactive)
+      return options[:date] if options[:date]
+
+      today = Date.today.to_s
+      return today unless interactive
+
+      print "\nDate [#{today}]: "
+      input = $stdin.gets&.strip
+      (input.nil? || input.empty?) ? today : input
+    end
+
+    def pick_duration(interactive)
+      return options[:duration] if options[:duration]
+
+      print "\nDuration (hours): "
+      input = $stdin.gets&.strip
+      abort("Duration is required.") if input.nil? || input.empty?
+      input.to_f
+    end
+
+    def pick_note(interactive)
+      return options[:note] if options[:note]
+
+      print "\nNote: "
+      input = $stdin.gets&.strip
+      abort("Note is required.") if input.nil? || input.empty?
+      input
+    end
+
+    def display_name(client)
+      name = client["organization"]
+      (name.nil? || name.empty?) ? "#{client["fname"]} #{client["lname"]}" : name
+    end
+
+    def help_json
+      {
+        name: "fb",
+        description: "FreshBooks time tracking CLI",
+        required_scopes: Auth::REQUIRED_SCOPES,
+        commands: {
+          auth: {
+            description: "Authenticate with FreshBooks via OAuth2",
+            usage: "fb auth",
+            interactive: true
+          },
+          log: {
+            description: "Log a time entry (interactive prompts with defaults from last use)",
+            usage: "fb log",
+            interactive: true,
+            flags: {
+              "--client" => "Pre-select client by name (skip prompt)",
+              "--project" => "Pre-select project by name (skip prompt)",
+              "--service" => "Pre-select service by name (skip prompt)",
+              "--duration" => "Duration in hours (e.g. 2.5)",
+              "--note" => "Work description",
+              "--date" => "Date (YYYY-MM-DD, defaults to today)",
+              "--yes" => "Skip confirmation prompt"
+            }
+          },
+          entries: {
+            description: "List time entries (defaults to current month)",
+            usage: "fb entries",
+            flags: {
+              "--from" => "Start date (YYYY-MM-DD, open-ended if omitted)",
+              "--to" => "End date (YYYY-MM-DD, open-ended if omitted)",
+              "--month" => "Month (1-12, defaults to current)",
+              "--year" => "Year (defaults to current)",
+              "--format" => "Output format: table (default) or json"
+            }
+          },
+          help: {
+            description: "Show help information",
+            usage: "fb help [COMMAND]",
+            flags: {
+              "--format" => "Output format: text (default) or json"
+            }
+          }
+        }
+      }
+    end
+  end
+end

data/lib/fb/spinner.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FB
+  module Spinner
+    FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+    def self.spin(message)
+      done = false
+      result = nil
+
+      thread = Thread.new do
+        i = 0
+        while !done
+          print "\r#{FRAMES[i % FRAMES.length]} #{message}"
+          $stdout.flush
+          i += 1
+          sleep 0.08
+        end
+      end
+
+      begin
+        result = yield
+      ensure
+        done = true
+        thread.join
+        print "\r✓ #{message}\n"
+      end
+
+      result
+    end
+  end
+end

data/lib/fb/version.rb

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

data/lib/fb.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "fb/version"
+require_relative "fb/spinner"
+require_relative "fb/auth"
+require_relative "fb/api"
+require_relative "fb/cli"

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: freshbooks-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- parasquid
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Manage FreshBooks time entries from the command line. Supports OAuth2
+  auth, interactive time logging with defaults, and monthly entry listings.
+email:
+- git@parasquid.com
+executables:
+- fb
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/fb
+- lib/fb.rb
+- lib/fb/api.rb
+- lib/fb/auth.rb
+- lib/fb/cli.rb
+- lib/fb/spinner.rb
+- lib/fb/version.rb
+homepage: https://github.com/parasquid/freshbooks-cli
+licenses:
+- GPL-3.0-only
+metadata:
+  source_code_uri: https://github.com/parasquid/freshbooks-cli
+  bug_tracker_uri: https://github.com/parasquid/freshbooks-cli/issues
+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: 4.0.3
+specification_version: 4
+summary: FreshBooks time tracking CLI
+test_files: []