req_toggl

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ReqToggl is an Elixir library that provides a Req plugin for the Toggl Track API (v9). It allows developers to easily interact with Toggl's time tracking features including authentication, project management, and time entry creation.

## Development Commands

### Testing
- Run all tests: `mix test`
- Run a specific test file: `mix test test/req_toggl_test.exs`
- Run tests with coverage: `mix test --cover`

### Code Quality
- Format code: `mix format`
- Check if code is formatted: `mix format --check-formatted`
- Compile the project: `mix compile`

### Interactive Development
- Start IEx with project loaded: `iex -S mix`
- Start with Tidewave dev server: `./tidewave.sh` (runs on port 10002)
- Recompile within IEx: `recompile()`
- When using Tidewave with MCP's `project_eval` tool:
  - After code changes: `recompile()` to reload the code
  - After adding dependencies: `System.halt()` to restart the Tidewave server

### Documentation
- Generate documentation: `mix docs`

## Project Structure

- `lib/req_toggl.ex` - Main module with Req plugin implementation and API methods
- `lib/req_toggl/application.ex` - Application supervisor for Tidewave dev server
- `test/req_toggl_test.exs` - Test suite
- `tidewave.sh` - Shell script to start IEx with Tidewave (port 10002)
- `mix.exs` - Project configuration and dependencies
- `.formatter.exs` - Code formatting configuration

## Architecture Notes

ReqToggl is implemented as a Req plugin following the Req request/response step pattern:

### Authentication
- Uses HTTP Basic Auth with Toggl API tokens
- Token format: `<token>:api_token` (base64 encoded in Authorization header)
- Get tokens from: https://track.toggl.com/profile

### Request Steps
1. `toggl_auth` - Adds Basic Auth header with API token
2. `toggl_headers` - Sets Content-Type to application/json

### API Implementation
The library provides three main functions:
- `get_me/1` - Get current user info and workspace details
- `list_projects/3` - List projects for a workspace (requires workspace_id)
- `create_time_entry/2` - Create time entries with flexible time formats

### Time Entry Creation
Supports multiple time input formats:
1. DateTime structs with `:start` and `:stop`
2. DateTime structs with `:start` and `:duration` (seconds)
3. Date/time strings with `:date`, `:start_time`, `:end_time`
4. Date/time strings with `:date`, `:start_time`, `:duration`

All datetimes are converted to ISO8601 format (UTC) for the API.

## Toggl API Details

- Base URL: https://api.track.toggl.com/api/v9
- Format: JSON only
- Rate limits: 1 request/second, varying hourly limits by plan
- Times must be ISO 8601 (RFC 3339) in UTC
- Workspace ID is required for most operations (get from `/me` endpoint)

## Dependencies

Core dependencies:
- `req` ~> 0.5 - HTTP client library
- `jason` ~> 1.4 - JSON encoding/decoding

Dev dependencies:
- `bandit` ~> 1.8 - HTTP server for Tidewave
- `tidewave` ~> 0.5 - Live code reloading dev server
- `ex_doc` ~> 0.31 - Documentation generation

## Git Commit Guidelines

When creating commits:
- Do NOT include Claude as a co-author
- Do NOT mention Claude or AI assistance in commit messages
- Write commit messages as if written by a human developer
- Focus on what was changed and why, not how it was created

## Elixir Version

Project requires Elixir ~> 1.18