freeagent-cli 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6aa92b15fccb2ce8b889419652ee23e76455f9dea0f84afef73dbb2d33af023
+  data.tar.gz: 3329b71e37fcea5d277b3e05ba61972dd85f204c49bbe264568d555b15184d44
+SHA512:
+  metadata.gz: cdfb521afa51bb920e46965da8e965b9bb5d32b1a659a91746fda0801b790f9cac07e563dd8f5caefca026e3df35bc2345974d47d4a85ff694a33fe5518c8818
+  data.tar.gz: 3c3a1be9095e29c94289320b3c471444166047fb5a766bb1daf88fa5ae83e35d22aed735363c5e07b17a81bb11ec28bd92f394cc47ab362fa2c3b3846346cfb6

data/LICENSE

@@ -0,0 +1,9 @@
+ The MIT License (MIT)
+
+Copyright © 2025 Register Dynamics Limited.
+
+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.txt

@@ -0,0 +1,10 @@
+freeagent-cli: Access and control Freeagent data from the command line.
+
+This gem supplies a `fa` executable which can create, read, update and delete
+data using the Freeagent API.
+
+You need to specify valid Freeagent app credentials. Generate a Freeagent app at
+https://dev.freeagent.com/apps. Ensure you set 'http://localhost:*/' as a valid
+OAuth redirect URI. Then export your ID and secret as environment variables
+FREEAGENT_APP_ID and FREEAGENT_APP_SECRET. On first run, `fa` will authenticate
+you via OAuth so watch out for an authentication URI printed to the console.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/exe/fa

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+
+require 'thor'
+require_relative '../lib/freeagent'
+
+def match type, collection, needle, *values
+  found = collection.select do |item|
+    values.map(&:to_proc).any? {|v| v.call(item) == needle }
+  end
+  if found.none?
+    possibles = collection.product(values).map {|item, value| value.to_proc.call(item).to_s }
+    raise ArgumentError, "No #{type} matching '#{needle}' found, expecting one from #{possibles}"
+  end
+  unless found.one?
+    raise ArgumentError, "Ambiguous #{type}: could be #{found.map(&:url).join(', ')}"
+  end
+  found.first
+end
+
+module Freeagent
+  class Timeslips < Thor
+    no_commands do
+      def api
+        @api ||= API.new
+      end
+    end
+
+    desc 'list USER PROJECT TASK FROM TO', "List timeslips"
+    def list user, project, task, from, to
+      from = Date::parse from
+      to = Date::parse to
+      user = match :user, api.users, user, :first_name, :last_name, :email
+      project = match :project, api.projects, project, :name
+      task = match :task, api.tasks(project), task, :name
+
+      api.timeslips(user, project, task, from, to).each do |timeslip|
+        puts [Date::parse(timeslip.dated_on).strftime('%a %d %b %Y'), user.email, project.name, task.name, timeslip.hours].join("\t")
+      end
+    end
+
+    desc 'create USER PROJECT TASK FROM TO', "Create timeslips"
+    method_option :hours, aliases: '-h', type: :numeric, default: 8, desc: "Number of hours per day"
+    method_option :weekends, aliases: '-w', type: :boolean, default: false, desc: "Create timeslips on Saturdays and Sundays"
+    def create user, project, task, from, to
+      from = Date::parse from
+      to = Date::parse to
+      user = match :user, api.users, user, :first_name, :last_name, :email
+      project = match :project, api.projects, project, :name
+      task = match :task, api.tasks(project), task, :name
+
+      puts "Creating timeslips for #{user.first_name} #{user.last_name} for task '#{task.name}' in project '#{project.name}' between #{from} and #{to} inclusive"
+      timeslips = from.step(to).map do |date|
+        next if (date.saturday? || date.sunday?) && !options[:weekends]
+        {'task' => task.url, 'project' => project.url, 'user' => user.url, 'dated_on' => date.to_s, 'hours' => options[:hours]}
+      end.reject(&:nil?)
+      api.batch_create_timeslips timeslips
+    end
+
+    desc 'delete USER PROJECT TASK FROM TO', 'Delete timeslips'
+    def delete user, project, task, from, to
+      from = Date::parse from
+      to = Date::parse to
+      user = match :user, api.users, user, :first_name, :last_name, :email
+      project = match :project, api.projects, project, :name
+      task = match :task, api.tasks(project), task, :name
+
+      puts "Deleting timeslips for #{user.first_name} #{user.last_name} for task '#{task.name}' in project '#{project.name}' between #{from} and #{to} inclusive"
+      api.timeslips(user, project, task, from, to).each do |timeslip|
+        api.delete_timeslip(timeslip)
+      end
+    end
+  end
+
+  class Command < Thor
+    desc "timeslips", "Create, read, update and delete timeslips"
+    subcommand "timeslips", Timeslips
+  end
+end
+
+Freeagent::Command.start

data/lib/freeagent.rb

@@ -0,0 +1,172 @@
+require 'oauth2'
+require 'webrick'
+
+FREEAGENT_APP_ID = ENV['FREEAGENT_APP_ID']
+FREEAGENT_APP_SECRET = ENV['FREEAGENT_APP_SECRET']
+
+TOKEN_FILE = './.token.yml'
+
+module Freeagent
+  class API
+    def initialize
+      if FREEAGENT_APP_ID.nil? || FREEAGENT_APP_ID.empty?
+        raise ArgumentError, 'FREEAGENT_APP_ID is unset'
+      end
+      if FREEAGENT_APP_SECRET.nil? || FREEAGENT_APP_SECRET.empty?
+        raise ArgumentError, 'FREEAGENT_APP_SECRET is unset'
+      end
+
+      @token = reload || authorize
+      File.write TOKEN_FILE, @token.to_hash.to_hash.to_yaml
+    end
+
+    private
+    def reload
+      if File.exist? TOKEN_FILE
+        OAuth2::AccessToken.from_hash(client, YAML.unsafe_load_file(TOKEN_FILE)).refresh
+      end
+    rescue OAuth2::Error
+      nil
+    end
+
+    def client
+      @client ||= OAuth2::Client.new(FREEAGENT_APP_ID, FREEAGENT_APP_SECRET,
+        site: 'https://api.freeagent.com/v2/',
+        authorize_url: 'approve_app',
+        token_url: 'token_endpoint'
+      )
+    end
+
+    def authorize
+      receiver = WEBrick::HTTPServer.new(Port: 0)
+      receiver_url = "http://localhost:#{receiver.config[:Port]}/"
+      url = client.auth_code.authorize_url(redirect_uri: receiver_url)
+      puts "Go and authorize at #{url}, I'm waiting..."
+
+      access_code = nil
+      receiver.mount_proc '/' do |req, res|
+        # TODO: parse redirect response...
+        access_code = req.query['code']
+        receiver.shutdown
+      end
+
+      Signal.trap('INT') do
+        receiver.shutdown
+      end
+
+      receiver.start
+      raise if access_code.nil?
+
+      client.auth_code.get_token(access_code, redirect_uri: receiver_url)
+    end
+
+    def get *parts, **params
+      relatives = parts.map(&:to_s).join('/')
+      uri = URI.parse(relatives)
+      puts "GET #{uri}"
+      res = @token.get(uri, params: params, headers: {'Accept': 'application/json'})
+      data = res.parsed
+      if res.headers.include? 'Link'
+        data._links = res.headers['Link'].split(", ").map do |link|
+          url, rel = link.split('; rel=')
+          [rel.gsub(/^'|'$/, ''), URI::parse(url.gsub(/^<|>$/, ''))]
+        end.to_h
+      end
+      data
+    rescue => err
+      if err.response.status == 429
+        retry_after = err.response.headers['retry-after'].to_i
+        STDERR.puts "Rate limited; sleeping for #{retry_after}"
+        sleep retry_after
+        retry
+      end
+    end
+
+    def get_pages *path, **params
+      Enumerator.new do |yielder|
+        loop do
+          res = get(*path, **{per_page: 100}.update(params))
+          yielder << res
+          break if res._links.nil? || res._links.next.nil?
+          params = URI::decode_www_form(res._links.next.query).to_h
+        end
+      end
+    end
+
+    def post *parts, **params
+      data = parts.pop
+      relatives = parts.map(&:to_s).join('/')
+      uri = URI.parse(relatives)
+      puts "POST #{uri}"
+      body = data.to_json
+      @token.post(uri, body: body, params: params, headers: {'Content-Type': 'application/json', 'Accept': 'application/json'}).parsed
+    end
+
+    def delete *parts, **params
+      relatives = parts.map(&:to_s).join('/')
+      uri = URI.parse(relatives)
+      puts "DELETE #{uri}"
+      @token.delete(uri, params: params, headers: {'Accept': 'application/json'})
+    end
+
+    public
+    def first_accounting_year_end
+      Date.parse get('company').company.first_accounting_year_end
+    end
+
+    def periods year
+      get('payroll', year).periods
+    end
+
+    def payslips year, period
+      get('payroll', year, period).period.payslips
+    end
+
+    def profiles year
+      get('payroll_profiles', year).profiles
+    end
+
+    def projects
+      get_pages('projects').flat_map(&:projects)
+    end
+
+    def tasks project
+      get_pages('tasks', project: project.url).flat_map(&:tasks)
+    end
+
+    def timeslips user, project, task, from, to
+      get_pages('timeslips', user: user.url, project: project.url, task: task.url, from_date: from.to_s, to_date: to.to_s).flat_map(&:timeslips)
+    end
+
+    def create_timeslip user, project, task, dated, hours
+      post('timeslips', {
+        'task' => task.url,
+        'project' => project.url,
+        'user' => user.url,
+        'dated_on' => dated.to_s,
+        'hours' => hours,
+      })
+    end
+
+    def batch_create_timeslips timeslips
+      post('timeslips', {'timeslips' => timeslips})
+    end
+
+    def delete_timeslip timeslip
+      id = timeslip.url.split('/').last
+      delete('timeslips', id)
+    end
+
+    def users
+      get_pages('users').flat_map(&:users)
+    end
+
+    def user id
+      get('users', id).user
+    end
+
+    def profile year, user
+      get('payroll_profiles', year, user: user)
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: freeagent-cli
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Simon Worthington
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: |-
+  This gem supplies a `fa` executable which can create, read, update and delete
+  data using the Freeagent API.
+
+  You need to specify valid Freeagent app credentials. Generate a Freeagent app at
+  https://dev.freeagent.com/apps. Ensure you set 'http://localhost:*/' as a valid
+  OAuth redirect URI. Then export your ID and secret as environment variables
+  FREEAGENT_APP_ID and FREEAGENT_APP_SECRET. On first run, `fa` will authenticate
+  you via OAuth so watch out for an authentication URI printed to the console.
+email:
+- simon@register-dynamics.co.uk
+executables:
+- fa
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.txt
+- Rakefile
+- exe/fa
+- lib/freeagent.rb
+homepage: https://www.github.com/register-dynamics/freeagent-cli
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.github.com/register-dynamics/freeagent-cli
+  source_code_uri: https://www.github.com/register-dynamics/freeagent-cli
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: 'freeagent-cli: Access and control Freeagent data from the command line.'
+test_files: []