馃尫 the cutsie hackatime helper
dunkirk.sh
1// Package wakatime provides a Go client for interacting with the WakaTime API.
2// WakaTime is a time tracking service for programmers that automatically tracks
3// how much time is spent on coding projects.
4package wakatime
5
6import (
7 "bytes"
8 "encoding/base64"
9 "encoding/json"
10 "fmt"
11 "net/http"
12 "runtime"
13 "time"
14)
15
16// Default API URL for the WakaTime API v1
17const (
18 DefaultAPIURL = "https://api.wakatime.com/api/v1"
19)
20
21// Error types returned by the client
22var (
23 // ErrMarshalingHeartbeat occurs when a heartbeat can't be marshaled to JSON
24 ErrMarshalingHeartbeat = fmt.Errorf("failed to marshal heartbeat to JSON")
25 // ErrCreatingRequest occurs when the HTTP request cannot be created
26 ErrCreatingRequest = fmt.Errorf("failed to create HTTP request")
27 // ErrSendingRequest occurs when the HTTP request fails to send
28 ErrSendingRequest = fmt.Errorf("failed to send HTTP request")
29 // ErrInvalidStatusCode occurs when the API returns a non-success status code
30 ErrInvalidStatusCode = fmt.Errorf("received invalid status code from API")
31 // ErrDecodingResponse occurs when the API response can't be decoded
32 ErrDecodingResponse = fmt.Errorf("failed to decode API response")
33 // ErrUnauthorized occurs when the API rejects the provided credentials
34 ErrUnauthorized = fmt.Errorf("unauthorized: invalid API key or insufficient permissions")
35)
36
37// Client represents a WakaTime API client with authentication and connection settings.
38type Client struct {
39 // APIKey is the user's WakaTime API key used for authentication
40 APIKey string
41 // APIURL is the base URL for the WakaTime API
42 APIURL string
43 // HTTPClient is the HTTP client used to make requests to the WakaTime API
44 HTTPClient *http.Client
45}
46
47// NewClient creates a new WakaTime API client with the provided API key
48// and a default HTTP client with a 10-second timeout.
49func NewClient(apiKey string) *Client {
50 return &Client{
51 APIKey: apiKey,
52 APIURL: DefaultAPIURL,
53 HTTPClient: &http.Client{Timeout: 10 * time.Second},
54 }
55}
56
57// NewClientWithOptions creates a new WakaTime API client with the provided API key,
58// custom API URL and a default HTTP client with a 10-second timeout.
59func NewClientWithOptions(apiKey string, apiURL string) *Client {
60 return &Client{
61 APIKey: apiKey,
62 APIURL: apiURL,
63 HTTPClient: &http.Client{Timeout: 10 * time.Second},
64 }
65}
66
67// Heartbeat represents a coding activity heartbeat sent to the WakaTime API.
68// Heartbeats are the core data structure for tracking time spent coding.
69type Heartbeat struct {
70 // Entity is the file path or resource being worked on
71 Entity string `json:"entity"`
72 // Type specifies the entity type (usually "file")
73 Type string `json:"type"`
74 // Time is the timestamp of the heartbeat in UNIX epoch format
75 Time float64 `json:"time"`
76 // Project is the optional project name associated with the entity
77 Project string `json:"project,omitempty"`
78 // Language is the optional programming language of the entity
79 Language string `json:"language,omitempty"`
80 // IsWrite indicates if the file was being written to (vs. just viewed)
81 IsWrite bool `json:"is_write,omitempty"`
82 // EditorName is the optional name of the editor or IDE being used
83 EditorName string `json:"editor_name,omitempty"`
84 // Branch is the optional git branch name
85 Branch string `json:"branch,omitempty"`
86 // Category is the optional activity category
87 Category string `json:"category,omitempty"`
88 // LineCount is the optional number of lines in the file
89 LineCount int `json:"lines,omitempty"`
90 // UserAgent is the optional user agent string
91 UserAgent string `json:"user_agent,omitempty"`
92 // EntityType is the optional entity type (usually redundant with Type)
93 EntityType string `json:"entity_type,omitempty"`
94 // Dependencies is an optional list of project dependencies
95 Dependencies []string `json:"dependencies,omitempty"`
96 // ProjectRootCount is the optional number of directories in the project root path
97 ProjectRootCount int `json:"project_root_count,omitempty"`
98}
99
100// StatusBarResponse represents the response from the WakaTime Status Bar API endpoint.
101// This contains summary information about a user's coding activity for a specific time period.
102type StatusBarResponse struct {
103 // Data contains coding duration information
104 Data struct {
105 // GrandTotal contains the aggregated coding time information
106 GrandTotal struct {
107 // Text is the human-readable representation of the total coding time
108 // Example: "3 hrs 42 mins"
109 Text string `json:"text"`
110 // TotalSeconds is the total time spent coding in seconds
111 // This can be used for precise calculations or custom formatting
112 TotalSeconds int `json:"total_seconds"`
113 } `json:"grand_total"`
114 } `json:"data"`
115}
116
117// SendHeartbeat sends a coding activity heartbeat to the WakaTime API.
118// It returns an error if the request fails or returns a non-success status code.
119func (c *Client) SendHeartbeat(heartbeat Heartbeat) error {
120 // Set the user agent in the heartbeat data
121 if heartbeat.UserAgent == "" {
122 heartbeat.UserAgent = "wakatime/unset (" + runtime.GOOS + "-" + runtime.GOARCH + ") akami-wakatime/1.0.0"
123 }
124
125 data, err := json.Marshal(heartbeat)
126 if err != nil {
127 return fmt.Errorf("%w: %v", ErrMarshalingHeartbeat, err)
128 }
129
130 req, err := http.NewRequest("POST", c.APIURL+"/users/current/heartbeats", bytes.NewBuffer(data))
131 if err != nil {
132 return fmt.Errorf("%w: %v", ErrCreatingRequest, err)
133 }
134
135 req.Header.Set("Content-Type", "application/json")
136 req.Header.Set("Authorization", "Basic "+base64.StdEncoding.EncodeToString([]byte(c.APIKey)))
137 // Set the user agent in the request header as well
138 req.Header.Set("User-Agent", "wakatime/unset ("+runtime.GOOS+"-"+runtime.GOARCH+") akami-wakatime/1.0.0")
139
140 resp, err := c.HTTPClient.Do(req)
141 if err != nil {
142 return fmt.Errorf("%w: %v", ErrSendingRequest, err)
143 }
144 defer resp.Body.Close()
145
146 // Read and log the response
147 var respBody bytes.Buffer
148 _, err = respBody.ReadFrom(resp.Body)
149 if err != nil {
150 return fmt.Errorf("failed to read response body: %v", err)
151 }
152
153 respContent := respBody.String()
154
155 if resp.StatusCode == http.StatusUnauthorized {
156 return fmt.Errorf("%w: %s", ErrUnauthorized, respContent)
157 } else if resp.StatusCode < 200 || resp.StatusCode >= 300 {
158 return fmt.Errorf("%w: status code %d, response: %s", ErrInvalidStatusCode, resp.StatusCode, respContent)
159 }
160
161 return nil
162}
163
164// GetStatusBar retrieves a user's current day coding activity summary from the WakaTime API.
165// It returns an error if the request fails or returns a non-success status code.
166func (c *Client) GetStatusBar() (StatusBarResponse, error) {
167 req, err := http.NewRequest("GET", fmt.Sprintf("%s/users/current/statusbar/today", c.APIURL), nil)
168 if err != nil {
169 return StatusBarResponse{}, fmt.Errorf("%w: %v", ErrCreatingRequest, err)
170 }
171
172 req.Header.Set("Authorization", "Basic "+base64.StdEncoding.EncodeToString([]byte(c.APIKey)))
173
174 resp, err := c.HTTPClient.Do(req)
175 if err != nil {
176 return StatusBarResponse{}, fmt.Errorf("%w: %v", ErrSendingRequest, err)
177 }
178 defer resp.Body.Close()
179
180 // Read the response body for potential error messages
181 var respBody bytes.Buffer
182 _, err = respBody.ReadFrom(resp.Body)
183 if err != nil {
184 return StatusBarResponse{}, fmt.Errorf("failed to read response body: %v", err)
185 }
186
187 respContent := respBody.String()
188
189 if resp.StatusCode == http.StatusUnauthorized {
190 return StatusBarResponse{}, fmt.Errorf("%w: %s", ErrUnauthorized, respContent)
191 } else if resp.StatusCode < 200 || resp.StatusCode >= 300 {
192 return StatusBarResponse{}, fmt.Errorf("%w: status code %d, response: %s", ErrInvalidStatusCode, resp.StatusCode, respContent)
193 }
194
195 var durationResp StatusBarResponse
196 if err := json.Unmarshal(respBody.Bytes(), &durationResp); err != nil {
197 return StatusBarResponse{}, fmt.Errorf("%w: %v, response: %s", ErrDecodingResponse, err, respContent)
198 }
199
200 return durationResp, nil
201}