# ReqToggl

A Req plugin for the Toggl Track API v9. Provides a simple, composable interface for time tracking operations including authentication, project management, and time entry creation.

## Installation

Add `req_toggl` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:req_toggl, "~> 0.1.0"}
  ]
end
```

## Quick Start

```elixir
# Create a client with your API token
client = ReqToggl.new(api_token: System.fetch_env!("TOGGL_API_TOKEN"))

# Get your workspace ID
{:ok, %{body: user}} = ReqToggl.get_me(client)
workspace_id = user["default_workspace_id"]

# List all projects
{:ok, %{body: projects}} = ReqToggl.list_projects(client, workspace_id)

# Create a time entry
{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  date: "2024-01-15",
  start_time: "09:00",
  end_time: "17:00",
  description: "Working on features"
)
```

## Authentication

Get your API token from [https://track.toggl.com/profile](https://track.toggl.com/profile).

You can pass it directly or use environment variables:

```elixir
# From environment
client = ReqToggl.new(api_token: System.fetch_env!("TOGGL_API_TOKEN"))

# Or attach to an existing Req request
req = Req.new(base_url: "https://api.track.toggl.com/api/v9")
|> ReqToggl.attach(api_token: "your-api-token")
```

## API Functions

### Get User Info

```elixir
{:ok, %{body: user}} = ReqToggl.get_me(client)
workspace_id = user["default_workspace_id"]
```

### List Projects

```elixir
# List all projects
{:ok, %{body: projects}} = ReqToggl.list_projects(client, workspace_id)

# Filter by name
{:ok, %{body: projects}} = ReqToggl.list_projects(client, workspace_id, name: "Marketing")
```

### Create Time Entries

ReqToggl supports multiple time formats for flexibility:

#### Using date and time strings (simplest)

```elixir
{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  date: "2024-01-15",
  start_time: "09:00",
  end_time: "17:00",
  description: "Working on features"
)
```

#### Using DateTime structs

```elixir
{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  start: ~U[2024-01-15 09:00:00Z],
  stop: ~U[2024-01-15 17:00:00Z],
  description: "Working on features"
)
```

#### Using duration (in seconds)

```elixir
{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  start: ~U[2024-01-15 09:00:00Z],
  duration: 28800,  # 8 hours
  description: "Working on features"
)
```

### Optional Fields

Time entries support additional optional fields:

```elixir
{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  date: "2024-01-15",
  start_time: "09:00",
  end_time: "17:00",
  description: "Working on features",
  billable: true,
  tags: ["development", "feature"]
)
```

## Development

### Setup

```bash
# Install dependencies
mix deps.get

# Compile
mix compile

# Run tests
mix test
```

### Live Development with Tidewave

Start an interactive session with live reloading:

```bash
./tidewave.sh
```

This starts IEx with Tidewave on port 10002 for live code evaluation.

## Toggl API Details

- **API Version**: v9
- **Base URL**: https://api.track.toggl.com/api/v9
- **Format**: JSON only
- **Rate Limits**: 1 request/second, varying hourly limits by plan
- **Time Format**: ISO 8601 (RFC 3339) in UTC

Documentation: [https://engineering.toggl.com/docs/](https://engineering.toggl.com/docs/)

## License

Copyright 2025

Licensed under the Apache License, Version 2.0.