hubot-scripts

# Description: # Allows Hubot to interact with Harvest's (http://harvestapp.com) time-tracking # service. # # Dependencies: # None # Configuration: # HUBOT_HARVEST_SUBDOMAIN # # Commands: # # hubot remember my harvest account <email> with password <password> - Make hubot remember your Harvest credentials # hubot forget my harvest account - Make hubot forget your Harvest credentials again # hubot start harvest - Restart the last timer. # hubot start harvest at <project>/<task>: <notes> - Start a Harvest timer at a given project-task combination # hubot stop harvest [at project/task] - Stop the most recent Harvest timer or the one for the given project-task combination. # hubot daily harvest [of <user>] [at yyyy-mm-dd] - Show a user's Harvest timers for today (or yours, if noone is specified) or a specific day # hubot list harvest tasks [of <user>] - Show the Harvest project-task combinations available to a user (or you, if noone is specified) # hubot is harvest down/up - Check if the Harvest API is reachable. # # Notes: # All commands and command arguments are case-insenitive. If you work # on a project "FooBar", hubot will unterstand "foobar" as well. This # is also true for abbreviations, so if you don't have similary named # projects, "foob" will do as expected. # # Some examples: # > hubot remember my harvest account joe@example.org with password doe # > hubot list harvest tasks # > hubot start harvest at myproject/important-task: Some notes go here. # > hubot start harvest at myp/imp: Some notes go here. # > hubot daily harvest of nickofotheruser # # Full command descriptions: # # hubot remember my harvest account <email> with password <password> # Saves your Harvest credentials to allow Hubot to track # time for you. # # hubot forget my harvest account # Deletes your account credentials from Hubt's memory. # # hubot start harvest # Examines the list of timers for today and creates a new timer with # the same properties as the most recent one. # # hubot start harvest at <project>/<task>: <notes> # Starts a timer for a task at a project (both of which may # be abbreviated, Hubot will ask you if your input is # ambigious). An existing timer (if any) will be stopped. # # hubot stop harvest [at <project>/<task>] # Stops the timer for a task, if any. If no project is given, # stops the first active timer it can find. The project and # task arguments may be abbreviated as with start. # # hubot daily harvest [of <user>] [on yyyy-mm-dd] # Hubot responds with your/a specific user's entries # for the given date; if no date is given, assumes today. # If user is ommitted, you are assumed; if both the user and # the date are ommited, your entries for today will be displayed. # # hubot list harvest tasks [of <user>] # Gives you a list of all project/task combinations available # to you or a specific user. You can use these for the start command. # # Note on HUBOT_HARVEST_SUBDOMAIN: # This is the subdomain you access the Harvest service with, e.g. # if you have the Harvest URL http://yourcompany.harvestapp.com # you should set this to "yourcompany" (without the quotes). # # Author: # Quintus @ Asquera # http = require("http") unless process.env.HUBOT_HARVEST_SUBDOMAIN console.log "Please set HUBOT_HARVEST_SUBDOMAIN in the environment to use the harvest plugin script." # Checks if we have the information necessary for making requests # for a user. If we don't, reply accordingly and return null. Otherwise, # return the user object. # If `test_user` is supplied, checks the credentials for the user # with that name, otherwise the sender of `msg` is checked. check_user = (robot, msg, test_user = null) -> # Detect the user; if none is passed, assume the sender. user = null if test_user user = robot.brain.userForName(test_user) unless user msg.reply "#{msg.match[2]}? Whoʼs that?" return null else user = msg.message.user # Check if we know the detected user's credentials. unless user.harvest_account if user == msg.message.user msg.reply "You have to tell me your Harvest credentials first." else msg.reply "I didnʼt crack #{user.name}ʼs Harvest credentials yet, but Iʼm working on it… Sorry for the inconvenience." return null return user # Issues an empty GET request to harvest to test whether the service is # available at the moment. The callback gets passed an exception object # describing the connection error; if everything is fine it gets passed # null. check_harvest_down = (callback) -> opts = headers: "Content-Type": "application/json" "Accept": "application/json" method: "GET" host: "#{process.env.HUBOT_HARVEST_SUBDOMAIN}.harvestapp.com" port: 80 path: "/account/who_am_i" req = http.request opts, (response) -> callback null req.on "error", (error) -> callback error req.setTimeout 5000, -> req.destroy() # Cancel the request callback "Connection timeout" req.end() ### Definitions for hubot ### module.exports = (robot) -> # Periodically check the Harvest service for availability cb = -> check_harvest_down (error) -> if (error) robot.send "broadcast", "Harvest appears to be down; exact error is: #{error}" setInterval(cb, 600000) # 10 Minutes in milliseconds # Check if Harvest is available. robot.respond /is harvest (down|up)/i, (msg) -> check_harvest_down (error) -> if error msg.reply("Harvest is down; exact error: #{error}") else msg.reply("Harvest is up.") # Provide facility for saving the account credentials. robot.respond /remember my harvest account (.+) with password (.+)/i, (msg) -> account = new HarvestAccount msg.match[1], msg.match[2] harvest = new HarvestService(account) # If the credentials are valid, remember them, otherwise # tell the user they are wrong. try harvest.test msg, (valid) -> if valid msg.message.user.harvest_account = account msg.reply "Thanks, Iʼll remember your credentials. Have fun with Harvest." else msg.reply "Uh-oh – I just tested your credentials, but they appear to be wrong. Please specify the correct ones." catch error msg.reply "Unable to test credentials: fatal error: #{error}" # Allows a user to delete his credentials. robot.respond /forget my harvest account/i, (msg) -> msg.message.user.harvest_account = null msg.reply "Okay, I erased your credentials from my memory." # Retrieve your or a specific user's timesheet for today. robot.respond /daily harvest( of (\w+))?( on (\d{4})-(\d{2})-(\d{2}))?/i, (msg) -> unless user = check_user(robot, msg, msg.match[2]) return harvest = new HarvestService(user.harvest_account) if msg.match[3] target_date = new Date(parseInt(msg.match[4]), parseInt(msg.match[5] - 1), parseInt(msg.match[6])) # Month starts at 0 try if target_date harvest.daily_at msg, target_date, (status, body) -> if 200 <= status <= 299 if body.day_entries.length == 0 msg.reply "#{user.name} has no entries on #{target_date}." else msg.reply "#{user.name}'s entries on #{target_date}:" for entry in body.day_entries if entry.ended_at == "" msg.reply "• #{entry.project} (#{entry.client}) → #{entry.task} <#{entry.notes}> [running since #{entry.started_at} (#{entry.hours}h)]" else msg.reply "• #{entry.project} (#{entry.client}) → #{entry.task} <#{entry.notes}> [#{entry.started_at} – #{entry.ended_at} (#{entry.hours}h)]" else msg.reply "Failed to retrieve entry information: request failed with status #{status}." else harvest.daily msg, (status, body) -> if 200 <= status <= 299 msg.reply "Your entries for today, #{user.name}:" for entry in body.day_entries if entry.ended_at == "" msg.reply "• #{entry.project} (#{entry.client}) → #{entry.task} <#{entry.notes}> [running since #{entry.started_at} (#{entry.hours}h)]" else msg.reply "• #{entry.project} (#{entry.client}) → #{entry.task} <#{entry.notes}> [#{entry.started_at} – #{entry.ended_at} (#{entry.hours}h)]" else msg.reply "Failed to retrieve entry information: request failed with status #{status}." catch error msg.reply("Failed to retrieve entry information: fatal error: #{error}") # List all project/task combinations that are available to a user. robot.respond /list harvest tasks( of (.+))?/i, (msg) -> unless user = check_user(robot, msg, msg.match[2]) return harvest = new HarvestService(user.harvest_account) try harvest.daily msg, (status, body) -> if 200 <= status <= 299 msg.reply "The following project/task combinations are available for you, #{user.name}:" for project in body.projects msg.reply "• Project #{project.name}" for task in project.tasks msg.reply " ‣ #{task.name} (#{if task.billable then 'billable' else 'non-billable'})" else msg.reply "Failed to retrieve project/task list: request failed with status #{status}." catch error msg.reply "Failed to retrieve project/task list: fatal error: #{error}" # Kick off a new timer, stopping the previously running one, if any. robot.respond /start harvest at (.+)\/(.+): (.*)/i, (msg) -> unless user = check_user(robot, msg) return harvest = new HarvestService(user.harvest_account) project = msg.match[1] task = msg.match[2] notes = msg.match[3] try harvest.start msg, project, task, notes, (status, body) -> if 200 <= status <= 299 if body.hours_for_previously_running_timer? msg.reply "Previously running timer stopped at #{body.hours_for_previously_running_timer}h." msg.reply "OK, I started tracking you on #{body.project}/#{body.task}." else msg.reply "Failed to start timer: request failed with status #{status}." catch error msg.reply "Failed to start timer: fatal error: #{error}" robot.respond /start harvest/i, (msg) -> unless user = check_user(robot, msg) return harvest = new HarvestService(user.harvest_account) try harvest.restart msg, (status, body) -> if 200 <= status <= 299 if body.hours_for_previously_running_timer? msg.reply "Previously running timer stopped at #{body.hours_for_previously_running_timer}h." msg.reply "OK, I started tracking you on #{body.project}/#{body.task}." else msg.reply "Failed to start timer: request failed with status #{status}." catch error msg.reply "Failed to start timer: fatal error: #{error}" # Stops the timer running for a project/task combination, # if any. If no combination is given, stops the first # active timer available. robot.respond /stop harvest( at (.+)\/(.+))?/i, (msg) -> unless user = check_user(robot, msg) return harvest = new HarvestService(user.harvest_account) if msg.match[1] project = msg.match[2] task = msg.match[3] try harvest.stop msg, project, task, (status, body) -> if 200 <= status <= 299 msg.reply "Timer stopped (#{body.hours}h)." else msg.reply "Failed to stop timer: request failed with status #{status}." msg.reply body catch error msg.reply("Failed to stop timer: fatal error: #{error}") else try harvest.stop_first msg, (status, body) -> if 200 <= status <= 299 msg.reply "Timer stopped (#{body.hours}h)." else msg.reply "Failed to stop timer: request failed with status #{status}." catch error msg.reply("Failed to stop timer: fatal error: #{error}") # Class encapsulating a user's Harvest credentials; safe to store # in Hubot's Redis brain (no methods, this is a data-only construct). class HarvestAccount # Create a new harvest account. Pass in the account's email and the # password used to access harvest. These credentials are the same you # use for logging into Harvest's web service. constructor: (email, password) -> @email = email @password = password # This class represents a user's connection to the Harvest API; # it is bound to a specific account and cannot be stored permanently # in Hubot's (Redis) brain. # # The API calls are asynchronous, i.e. the methods executing # the request immediately return. To process the response, # you have to attach a callback to the method call, which # unless documtened otherwise will receive two arguments, # the first being the response's status code, the second # one is the response's body as a JavaScript object created # via `JSON.parse`. class HarvestService # Creates a new connection to the Harvest API for the given # account. constructor: (account) -> @base_url = "https://#{process.env.HUBOT_HARVEST_SUBDOMAIN}.harvestapp.com" @account = account # Tests whether the account credentials are valid. # If so, the callback gets passed `true`, otherwise # it gets passed `false`. test: (msg, callback) -> this.request(msg).path("account/who_am_i").get() (err, res, body) -> if 200 <= res.statusCode <= 299 callback true else callback false # Issues /daily to the Harvest API. daily: (msg, callback) -> this.request(msg).path("/daily").get() (err, res, body) -> if 200 <= res.statusCode <= 299 callback res.statusCode, JSON.parse(body) else callback res.statusCode, null # Issues /daily/<dayofyear>/<year> to the Harvest API. daily_at: (msg, date, callback) -> this.request(msg).path("/daily/#{this.day_of_year(date)}/#{date.getFullYear()}").get() (err, res, body) -> if 200 <= res.statusCode <= 299 callback res.statusCode, JSON.parse(body) else callback res.statusCode, null restart: (msg, callback) -> this.daily msg, (status, body) => if 200 <= status <= 299 if body.day_entries.length == 0 msg.reply "No last entry to restart, sorry." else last_entry = body.day_entries.pop() data = notes: last_entry.notes project_id: last_entry.project_id task_id: last_entry.task_id this.request(msg).path("/daily/add").post(JSON.stringify(data)) (err, res, body) -> if 200 <= res.statusCode <= 299 callback res.statusCode, JSON.parse(body) else callback res.statusCode, null else callback status, null # Issues /daily/add to the Harvest API to add a new timer # starting from now. start: (msg, target_project, target_task, notes, callback) -> this.find_project_and_task msg, target_project, target_task, (project, task) => # OK, task and project found. Start the tracker. data = notes: notes project_id: project.id task_id: task.id this.request(msg).path("/daily/add").post(JSON.stringify(data)) (err, res, body) -> if 200 <= res.statusCode <= 299 callback res.statusCode, JSON.parse(body) else callback res.statusCode, null # Issues /daily/timer/<id> to the Harvest API to stop # the timer running at `entry.id`. If that timer isn't # running, replys accordingly, otherwise calls the callback # when the operation has finished. stop_entry: (msg, entry, callback) -> if entry.timer_started_at? this.request(msg).path("/daily/timer/#{entry.id}").get() (err, res, body) -> if 200 <= res.statusCode <= 299 callback res.statusCode, JSON.parse(body) else callback res.statusCode, null else msg.reply "This timer is not running." # Issues /daily/timer/<id> to the Harvest API to stop # the timer running at <id>, which is determined by # looking up the current day_entry for the given # project/task combination. If no entry is found (i.e. # no timer has been started for this combination today), # replies with an error message and doesn't executes the # callback. stop: (msg, target_project, target_task, callback) -> this.find_day_entry msg, target_project, target_task, (entry) => this.stop_entry msg, entry, (status, body) -> callback status, body # Issues /daily/timer/<id> to the Harvest API to stop # the timer running at <id>, which is the first active # timer it can find in today's timesheet, then calls the # callback. If no active timer is found, replies accordingly # and doesn't execute the callback. stop_first: (msg, callback) -> this.daily msg, (status, body) => found_entry = null for entry in body.day_entries if entry.timer_started_at? found_entry = entry break if found_entry? this.stop_entry msg, found_entry, (status, body) -> callback status, body else msg.reply "Currently there is no timer running." # (internal method) # Assembles the basic parts of a request to the Harvest # API, i.e. the Content-Type/Accept and authorization # headers. The returned HTTPClient object can (and should) # be customized further by calling path() and other methods # on it. request: (msg) -> req = msg.http(@base_url).headers "Content-Type": "application/json" "Accept": "application/json" .auth(@account.email, @account.password) return req # (internal method) # Searches through all projects available to the sender of # `msg` for a project whose name inclues `target_project`. # If exactly one is found, query all tasks available for the # sender in this projects, and if exactly one is found, # execute the callback with the project object as the first # and the task object as the second argument. If more or # less than one project or task are found to match the query, # reply accordingly to the user (the callback never gets # executed in this case). find_project_and_task: (msg, target_project, target_task, callback) -> this.daily msg, (status, body) -> # Search through all possible projects for the matching ones projects = [] for project in body.projects if project.name.toLowerCase().indexOf(target_project.toLowerCase()) != -1 projects.push(project) # Ask the user if the project name is ambivalent if projects.length == 0 msg.reply "Sorry, no matching projects found." return else if projects.length > 1 msg.reply "I found the following #{projects.length} projects for your query, please be more precise:" for project in projects msg.reply "• #{project.name}" return # Repeat the same process for the tasks tasks = [] for task in projects[0].tasks if task.name.toLowerCase().indexOf(target_task.toLowerCase()) != -1 tasks.push(task) if tasks.length == 0 msg.reply "Sorry, no matching tasks found." else if tasks.length > 1 msg.reply "I found the following #{tasks.length} tasks for your query, please be more pricese:" for task in tasks msg.reply "• #{task.name}" return # Execute the callback with the results callback projects[0], tasks[0] # (internal method) # Searches through all entries made for today and tries # to find a running timer for the given project/task # combination. # If it is found, the respective entry object is passed to # the callback, otherwise an error message is replied and # the callback doesn't get executed. find_day_entry: (msg, target_project, target_task, callback) -> this.find_project_and_task msg, target_project, target_task, (project, task) => this.daily msg, (status, body) -> # For some unknown reason, the daily entry IDs are strings # instead of numbers, causing the comparison below to fail. # So, convert our target stuff to strings as well. project_id = "#{project.id}" task_id = "#{task.id}" # Iterate through all available entries for today # and try to find the requested ID. found_entry = null for entry in body.day_entries if entry.project_id == project_id and entry.task_id == task_id and entry.timer_started_at? found_entry = entry break # None found unless found_entry? msg.reply "I couldnʼt find a running timer in todayʼs timesheet for the combination #{target_project}/#{target_task}." return # Execute the callback with the result callback found_entry # Takes a Date object and figures out which day in its # year it represents and returns that one. Leap years # are honoured. day_of_year: (date) -> start = new Date(date.getFullYear(), 0, 0) return Math.ceil((date - start) / 86400000)