timedoctor

Integrates with TimeDoctor API to pull employee time tracking data, worklogs, statistics, and productivity metrics using simple Python scripts

# TimeDoctor Skill

Interact with TimeDoctor API for employee time tracking, activity logs, productivity statistics, and workforce analytics using simple Python CLI commands.

## What This Skill Does

Provides direct access to TimeDoctor's time tracking API through a Python CLI tool. Execute commands, get JSON data, present formatted results to users.

## Setup Instructions

### For Users: Getting TimeDoctor Credentials

**Option 1: Easy Setup (Recommended)**

Just provide your TimeDoctor email and password:

```bash
python3 timedoctor.py login --email "your-email@company.com" --password "your-password"
```

This returns a JWT token valid for 6 months. Copy the token and set it:

```bash
export TIMEDOCTOR_TOKEN="your-jwt-token-from-login-response"
```

**Option 2: Manual Token Setup**

If you already have a token or prefer manual setup:

```bash
# Required
export TIMEDOCTOR_TOKEN="your-jwt-token"

# Optional (can be discovered via get_authorization)
export TIMEDOCTOR_COMPANY_ID="your-company-id"
```

**For Multiple Accounts**: Users can switch accounts by changing the token:

```bash
# Account 1
export TIMEDOCTOR_TOKEN="token-for-account-1"
export TIMEDOCTOR_COMPANY_ID="company-id-1"

# Account 2  
export TIMEDOCTOR_TOKEN="token-for-account-2"
export TIMEDOCTOR_COMPANY_ID="company-id-2"
```

**Quick Setup Workflow**:
```bash
# 1. Login to get token
python3 timedoctor.py login --email "user@company.com" --password "password"

# 2. Copy token from response and set it
export TIMEDOCTOR_TOKEN="1jxExVs9WGsWccrq2ysMKMZVZlTVyTZc15tlgcWF_Qns"

# 3. Discover available companies
python3 timedoctor.py get_authorization

# 4. Set company ID (optional)
export TIMEDOCTOR_COMPANY_ID="aFtR8crWxHTeLzIm"

# 5. Start using commands
python3 timedoctor.py get_today_worklog --company-id $TIMEDOCTOR_COMPANY_ID
```

## How to Use This Skill

### Core Command Pattern

All commands follow this pattern:
```bash
python3 timedoctor.py COMMAND [--company-id ID] [OPTIONS]
```

The script is located in the skill directory and returns JSON output.

### Key Commands

**Login** (Get JWT Token):
```bash
python3 timedoctor.py login --email "user@company.com" --password "password"
```
Returns: JWT token valid for 6 months

**Discover Available Companies**:
```bash
python3 timedoctor.py get_authorization
```
Returns: User info and list of accessible companies with IDs

**Today's Activity**:
```bash
python3 timedoctor.py get_today_worklog --company-id COMPANY_ID
```

**This Week's Stats**:
```bash
python3 timedoctor.py get_this_week_stats --company-id COMPANY_ID
```

**This Month's Stats**:
```bash
python3 timedoctor.py get_this_month_stats --company-id COMPANY_ID
```

**Custom Date Range**:
```bash
python3 timedoctor.py get_worklog \
  --company-id COMPANY_ID \
  --from-date "2024-03-01T00:00:00Z" \
  --to-date "2024-03-31T00:00:00Z"
```

**List Users**:
```bash
python3 timedoctor.py get_users --company-id COMPANY_ID
```

**List Projects**:
```bash
python3 timedoctor.py get_projects --company-id COMPANY_ID
```

**Filter by Users**:
```bash
python3 timedoctor.py get_today_worklog --company-id COMPANY_ID --user-ids "123,456,789"
```

## Understanding TimeDoctor Account Structure

### Account Hierarchy

```
TimeDoctor User Account (requires TIMEDOCTOR_TOKEN)
  └── Company A (ID: 12345)
      ├── User 1
      ├── User 2
      └── Projects...
  └── Company B (ID: 67890)
      ├── User 3
      ├── User 4
      └── Projects...
  └── Company C (ID: 11111)
      └── Users...
```

### Key Concepts

1. **One Token = One User Account**
   - Each TIMEDOCTOR_TOKEN represents one TimeDoctor user login
   - Example: john@acme.com has one token

2. **One Account Can Access Multiple Companies**
   - A user can be part of multiple companies
   - Same token works for all companies they have access to
   - Switch companies using different `--company-id`

3. **Different User Accounts Need Different Tokens**
   - john@acme.com has token A
   - jane@beta.com has token B
   - To switch from John to Jane, change TIMEDOCTOR_TOKEN

### Example Scenarios

**Scenario 1: User with Multiple Companies**
```
User: "Show my companies"
Agent: Runs get_authorization
Response shows:
  - Acme Corp (12345)
  - Beta Startup (67890)
  - Gamma LLC (11111)

Agent: "You have access to 3 companies. Which one?"
User: "Acme Corp"
Agent: Uses --company-id 12345 for all subsequent requests
```

**Scenario 2: Switching Companies**
```
User: "Now show me Beta Startup's data"
Agent: Remembers Beta Startup = 67890 from earlier
Agent: Uses --company-id 67890
No token change needed!
```

**Scenario 3: Switching User Accounts**
```
User: "I want to use my other TimeDoctor account"
Agent: "You need to update your token. Run:
        export TIMEDOCTOR_TOKEN='your-other-token'"
User: Updates token
Agent: Runs get_authorization with new token
Agent: Shows new list of companies for that account
```

## Agent Instructions

### When User Asks About TimeDoctor Data

Follow this workflow:

1. **Check if User Has Token**
   - If `TIMEDOCTOR_TOKEN` is not set, help them login:
     ```
     "To get started, I need your TimeDoctor credentials.
     
     I'll run: python3 timedoctor.py login --email YOUR_EMAIL --password YOUR_PASSWORD
     
     What's your TimeDoctor email and password?"
     ```
   - After getting credentials, run login command
   - Extract token from response
   - Tell user to set: `export TIMEDOCTOR_TOKEN="extracted-token"`
   - Explain token is valid for 6 months

2. **Discover and Present Available Companies**
   - ALWAYS run `get_authorization` first if company_id is not known
   - Parse the response to extract all accessible companies
   - Present to user in a clear format:
     ```
     You have access to these TimeDoctor companies:
     1. Company A (ID: 12345)
     2. Company B (ID: 67890)
     3. Company C (ID: 11111)
     
     Which company would you like to use?
     ```
   - Wait for user to select
   - Remember the selected company_id for subsequent requests in this session

3. **Execute Appropriate Command**
   - Match user's request to the right command
   - Use convenience commands when possible (get_today_worklog, get_this_week_stats, etc.)
   - Always include `--company-id` parameter with the selected company

4. **Handle Multiple Accounts**
   - One TIMEDOCTOR_TOKEN = One user account
   - One user account can have access to multiple companies
   - To switch to a completely different TimeDoctor user account, user must update TIMEDOCTOR_TOKEN
   - To switch between companies under same account, just use different --company-id

5. **Parse and Format Output**
   - Check for `{"error": "..."}` first
   - Convert JSON to readable format (tables, lists, summaries)
   - Highlight key metrics (total hours, productive time, etc.)
   - Format durations as "X hours Y minutes"

6. **Error Recovery**
   - `"TIMEDOCTOR_TOKEN environment variable not set"` → Help user login with email/password
   - `"company_id required"` → Run get_authorization to discover companies
   - `"401 Unauthorized"` → Token expired, user needs to login again (6-month validity)

### Date Format Rules

ALWAYS use ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`

**Examples**:
- Start of day: `2024-03-22T00:00:00Z`
- End of day: `2024-03-23T00:00:00Z`
- For single day: from `2024-03-22T00:00:00Z` to `2024-03-23T00:00:00Z`

**Calculating Dates**:
- Today: Use `get_today_worklog` (automatic)
- This week: Use `get_this_week_stats` (automatic, Monday to today)
- This month: Use `get_this_month_stats` (automatic, 1st to today)
- Custom: Calculate dates and use `get_worklog` or `get_stats_total`

### Response Formatting Guidelines

**For Worklogs**:
- Show as table: User | Start Time | End Time | Duration | Activity
- Group by user or by date depending on context
- Summarize total hours at bottom

**For Statistics**:
- Show key metrics: Total Time, Productive Time, Unproductive Time, Idle Time
- Calculate percentages (e.g., "75% productive")
- Highlight outliers or unusu