clockify_detailed_reports_api_docs 1.0.0

data/docs/Clockify_API_User_Guide.md

@@ -0,0 +1,353 @@
+# 🚀 Clockify API User Guide - Simple & Easy!
+
+> **New to APIs?** No problem! This guide will get you making successful Clockify API calls in minutes.
+
+---
+
+## 🎯 What Does This API Do?
+
+The Clockify Detailed Reports API lets you:
+- 📊 Get time tracking data from your workspace
+- 💰 See billable hours and earnings
+- 👥 Filter by specific people, projects, or clients
+- 📅 Generate reports for any date range
+- 📤 Export data to Excel, PDF, or CSV
+
+Think of it like asking Clockify: *"Show me all the time entries between January and March for Client ABC, but only the billable hours."*
+
+---
+
+## 🔗 How to Connect
+
+**What You Need:**
+1. Your **Workspace ID** (looks like: `60f91b3ffdaf031696ecxxxx`)
+2. Your **API Key** (looks like: `YTVlNzE2YzAtN2Y4Yy00YjQ5LWIzNTUtZGI5MTQ4ZjQyNGFl`)
+
+**Where to Send Requests:**
+```
+POST https://reports.api.clockify.me/v1/workspaces/{YOUR_WORKSPACE_ID}/reports/detailed
+```
+
+**Headers to Include:**
+```
+X-Api-Key: YOUR_API_KEY
+Content-Type: application/json
+```
+
+---
+
+## ⚡ Super Simple Start (Copy & Paste Ready!)
+
+Here's the absolute minimum request to get time data:
+
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 50
+  }
+}
+```
+
+**What this does:** Gets the first 50 time entries from January 2024.
+
+---
+
+## 🎨 Customize Your Request (Pick What You Want!)
+
+### 📅 **Change the Date Range**
+```json
+{
+  "dateRangeStart": "2024-06-01T00:00:00.000Z",  // June 1st
+  "dateRangeEnd": "2024-06-30T23:59:59.999Z",   // June 30th
+  "detailedFilter": {"page": 1, "pageSize": 50}
+}
+```
+
+### 👤 **Get Data for Specific People**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "users": {
+    "contains": "CONTAINS",
+    "ids": ["user_id_here"],
+    "status": "ACTIVE"
+  },
+  "detailedFilter": {"page": 1, "pageSize": 50}
+}
+```
+
+### 🏢 **Get Data for Specific Clients**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "clients": {
+    "contains": "CONTAINS",
+    "ids": ["client_id_here"],
+    "status": "ACTIVE"
+  },
+  "detailedFilter": {"page": 1, "pageSize": 50}
+}
+```
+
+### 💰 **Include Financial Data**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "amountShown": "EARNED",  // Shows how much money was earned
+  "billable": true,         // Only billable time
+  "detailedFilter": {"page": 1, "pageSize": 50}
+}
+```
+
+### 📤 **Get Data as Excel File**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "exportType": "XLSX",  // Excel format
+  "detailedFilter": {"page": 1, "pageSize": 50}
+}
+```
+
+---
+
+## 🔧 Useful Options You Can Add
+
+### **Money Options** (`amountShown`)
+- `"EARNED"` - Revenue from billable time
+- `"COST"` - How much you paid employees  
+- `"PROFIT"` - Earned minus cost
+
+### **File Format Options** (`exportType`)
+- `"JSON"` - For programming (default)
+- `"CSV"` - For Excel/Google Sheets
+- `"XLSX"` - Excel file
+- `"PDF"` - Formatted report
+
+### **Filter Options**
+- `"billable": true` - Only billable time
+- `"billable": false` - Only non-billable time
+- `"description": "meeting"` - Find entries containing "meeting"
+- `"archived": true` - Include archived projects/clients
+
+### **Sort Options**
+- `"sortColumn": "DATE"` - Sort by date (goes in detailedFilter)
+- `"sortColumn": "USER"` - Sort by person
+- `"sortColumn": "DURATION"` - Sort by time length
+- `"sortOrder": "DESCENDING"` - Newest first (separate parameter)
+
+---
+
+## 📋 What You Get Back
+
+The API returns data like this:
+
+```json
+{
+  "timeEntries": [
+    {
+      "id": "entry_123",
+      "userName": "John Smith",
+      "userEmail": "john@company.com",
+      "projectName": "Website Design",
+      "clientName": "ABC Company",
+      "timeInterval": {
+        "start": "2024-01-15T09:00:00Z",
+        "end": "2024-01-15T17:00:00Z", 
+        "duration": 28800  // Seconds (28800 = 8 hours)
+      },
+      "description": "Design homepage mockups",
+      "billable": true
+    }
+  ],
+  "totals": [
+    {
+      "totalTime": 86400,        // Total seconds for ALL data
+      "totalBillableTime": 28800, // Billable seconds  
+      "entriesCount": 10         // Total number of entries
+    }
+  ]
+}
+```
+
+**Important:** `duration` is in seconds. Divide by 3600 to get hours.
+- 3600 seconds = 1 hour
+- 28800 seconds = 8 hours
+
+---
+
+## 🚨 Common Problems & Solutions
+
+### **❌ "Field dateRangeStart is required"**
+**Problem:** Missing required dates  
+**Solution:** Always include both dates:
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "detailedFilter": {"page": 1, "pageSize": 50}
+}
+```
+
+### **❌ "Invalid date format"**
+**Problem:** Wrong date format  
+**Solution:** Use exact format `YYYY-MM-DDTHH:MM:SS.sssZ`:
+```json
+"dateRangeStart": "2024-01-01T00:00:00.000Z"  // ✅ Correct
+"dateRangeStart": "2024-01-01"                // ❌ Wrong
+```
+
+### **❌ "Unauthorized"**
+**Problem:** Wrong API key or workspace ID  
+**Solution:** Double-check your credentials in Clockify settings
+
+### **❌ "Maximum page size is 1,000"**
+**Problem:** `pageSize` too large  
+**Solution:** Use `pageSize` between 1 and 1000:
+```json
+"detailedFilter": {"page": 1, "pageSize": 100}  // ✅ Good
+"detailedFilter": {"page": 1, "pageSize": 2000} // ❌ Too big
+```
+
+### **❌ Getting No Results**
+**Problem:** Filters are too restrictive  
+**Solution:** Start simple, then add filters:
+1. Try without any filters first
+2. Add one filter at a time
+3. Check if data exists in your date range
+
+---
+
+## 💡 Pro Tips
+
+### **🔄 Get More Results (Pagination)**
+If you have lots of data, get it in chunks:
+```json
+// Get first 100 entries
+{"detailedFilter": {"page": 1, "pageSize": 100}}
+
+// Get next 100 entries  
+{"detailedFilter": {"page": 2, "pageSize": 100}}
+```
+
+### **⚡ Speed Up Requests**
+- Use smaller `pageSize` (50-200) for faster responses
+- Use specific date ranges instead of very large ones
+- Filter early (add `billable`, `clients`, etc. to reduce data)
+
+### **💰 Invoice Workflow**
+To generate invoices:
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "clients": {"contains": "CONTAINS", "ids": ["client_id"], "status": "ACTIVE"},
+  "billable": true,
+  "invoicingState": "UNINVOICED",  // Only un-invoiced time
+  "amountShown": "EARNED",
+  "detailedFilter": {"page": 1, "pageSize": 1000}
+}
+```
+
+### **📊 Team Reports**
+To see team productivity:
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "userGroups": {"contains": "CONTAINS", "ids": ["team_id"], "status": "ACTIVE"},
+  "sortOrder": "ASCENDING",
+  "detailedFilter": {"page": 1, "pageSize": 200, "sortColumn": "USER"}
+}
+```
+
+### **📈 Summary Reports (Advanced)**
+To get grouped summary data:
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "summaryFilter": {
+    "groups": ["PROJECT", "CLIENT"],  // Group by projects and clients
+    "sortColumn": "DURATION"
+  },
+  "detailedFilter": {"page": 1, "pageSize": 100}
+}
+```
+
+**Summary Group Options**: `PROJECT`, `CLIENT`, `USER`, `TASK`, `TAG`, `DATE`, `WEEK`, `MONTH`, `USER_GROUP`, `TIMEENTRY`  
+**⚠️ Important**: Must include 1-3 group types, can't be empty!
+
+---
+
+## 🎯 Real-World Examples
+
+### **Example 1: Monthly Client Report**
+*"Show me all billable work for Client ABC in March 2024"*
+```json
+{
+  "dateRangeStart": "2024-03-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-03-31T23:59:59.999Z",
+  "clients": {"contains": "CONTAINS", "ids": ["abc_client_id"], "status": "ACTIVE"},
+  "billable": true,
+  "amountShown": "EARNED",
+  "sortOrder": "ASCENDING",
+  "detailedFilter": {"page": 1, "pageSize": 500, "sortColumn": "DATE"}
+}
+```
+
+### **Example 2: Find Missing Descriptions**
+*"Show me time entries that are missing descriptions for quality check"*
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "withoutDescription": true,
+  "detailedFilter": {"page": 1, "pageSize": 200}
+}
+```
+
+### **Example 3: Export to Excel**
+*"Get all January data as Excel file for accounting"*
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "exportType": "XLSX",
+  "amountShown": "EARNED",
+  "detailedFilter": {"page": 1, "pageSize": 1000}
+}
+```
+
+---
+
+## 🆘 Still Need Help?
+
+### **Test Your Request**
+1. Start with the simple example at the top
+2. Add one parameter at a time
+3. Check the response after each change
+4. If you get errors, remove the last thing you added
+
+### **Common Beginner Mistakes**
+- ❌ Forgetting the `detailedFilter` object
+- ❌ Using wrong date format (must end with `.000Z`)
+- ❌ Setting `pageSize` too high (max is 1000)
+- ❌ Using empty strings (`""`) in parameters
+
+### **Quick Debugging**
+If something's not working:
+1. Check your API key and workspace ID
+2. Verify date format is exactly `YYYY-MM-DDTHH:MM:SS.000Z`
+3. Try the basic example first
+4. Add parameters one by one
+
+---
+
+**🎉 You're Ready!** Start with the simple example and build up from there. The API is powerful but friendly once you get the basics down!

data/lib/clockify_api_docs/documentation.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module ClockifyApiDocs
+  class Documentation
+    def initialize
+      @docs_path = File.join(__dir__, '..', '..', 'docs')
+    end
+
+    # Get user-friendly guide content
+    def user_guide
+      read_doc_file('Clockify_API_User_Guide.md')
+    end
+
+    # Get complete technical reference
+    def complete_reference
+      read_doc_file('Clockify_API_Complete.md')
+    end
+
+    # Get internal documentation
+    def internal_documentation
+      read_doc_file('Clockify_API_Google_Doc_Internal.md')
+    end
+
+    # Save all documentation to a directory
+    def save_all_to_directory(output_path)
+      FileUtils.mkdir_p(output_path)
+      
+      files = {
+        'Clockify_API_User_Guide.md' => user_guide,
+        'Clockify_API_Complete.md' => complete_reference,
+        'Clockify_API_Google_Doc_Internal.md' => internal_documentation
+      }
+
+      files.each do |filename, content|
+        File.write(File.join(output_path, filename), content)
+      end
+
+      puts "📚 All documentation saved to: #{output_path}"
+      files.keys
+    end
+
+    # Search documentation for specific terms
+    def search(query)
+      results = []
+      
+      [
+        { name: 'User Guide', content: user_guide },
+        { name: 'Complete Reference', content: complete_reference },
+        { name: 'Internal Documentation', content: internal_documentation }
+      ].each do |doc|
+        lines = doc[:content].split("\n")
+        lines.each_with_index do |line, index|
+          if line.downcase.include?(query.downcase)
+            results << {
+              document: doc[:name],
+              line_number: index + 1,
+              content: line.strip,
+              context: get_context(lines, index, 2)
+            }
+          end
+        end
+      end
+
+      results
+    end
+
+    # List all documented errors
+    def list_errors
+      content = complete_reference
+      errors = []
+      
+      # Extract errors from the complete reference
+      in_error_section = false
+      content.split("\n").each do |line|
+        if line.include?("Complete Error Reference")
+          in_error_section = true
+          next
+        end
+        
+        if in_error_section && line.match(/^\s*-\s+`(\d+\/\d+)`:\s+(.+)/)
+          code = $1
+          description = $2
+          errors << { code: code, description: description }
+        end
+        
+        break if in_error_section && line.include?("## 🎯")
+      end
+      
+      errors
+    end
+
+    # Get API endpoint information
+    def endpoint_info
+      {
+        url: "https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed",
+        method: "POST",
+        authentication: "X-Api-Key header required",
+        content_type: "application/json"
+      }
+    end
+
+    # Get quick start example
+    def quick_start_example
+      {
+        minimal: {
+          "dateRangeStart" => "2024-01-01T00:00:00.000Z",
+          "dateRangeEnd" => "2024-12-31T23:59:59.999Z",
+          "detailedFilter" => {
+            "page" => 1,
+            "pageSize" => 100
+          }
+        }
+      }
+    end
+
+    private
+
+    def read_doc_file(filename)
+      file_path = File.join(@docs_path, filename)
+      if File.exist?(file_path)
+        File.read(file_path)
+      else
+        # Return embedded content if file not found
+        case filename
+        when 'Clockify_API_User_Guide.md'
+          USER_GUIDE_CONTENT
+        when 'Clockify_API_Complete.md'
+          COMPLETE_REFERENCE_CONTENT
+        when 'Clockify_API_Google_Doc_Internal.md'
+          INTERNAL_DOCUMENTATION_CONTENT
+        else
+          "Documentation file not found: #{filename}"
+        end
+      end
+    end
+
+    def get_context(lines, index, context_size)
+      start_idx = [0, index - context_size].max
+      end_idx = [lines.length - 1, index + context_size].min
+      
+      lines[start_idx..end_idx].map.with_index(start_idx + 1) do |line, line_num|
+        prefix = line_num == index + 1 ? ">>> " : "    "
+        "#{prefix}#{line_num}: #{line}"
+      end.join("\n")
+    end
+
+    # Embedded documentation content (fallback if files not found)
+    USER_GUIDE_CONTENT = <<~USER_GUIDE
+# 🚀 Clockify API User Guide - Simple & Easy!
+
+> **New to APIs?** No problem! This guide will get you making successful Clockify API calls in minutes.
+
+---
+
+## 🎯 What Does This API Do?
+
+The Clockify Detailed Reports API lets you:
+- 📊 Get time tracking data from your workspace
+- 💰 See billable hours and earnings
+- 👥 Filter by specific people, projects, or clients
+- 📅 Generate reports for any date range
+- 📤 Export data to Excel, PDF, or CSV
+
+Think of it like asking Clockify: *"Show me all the time entries between January and March for Client ABC, but only the billable hours."*
+
+---
+
+## ⚡ Super Simple Start (Copy & Paste Ready!)
+
+Here's the absolute minimum request to get time data:
+
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 50
+  }
+}
+```
+
+**🎉 You're Ready!** Start with the simple example and build up from there!
+    USER_GUIDE
+
+    COMPLETE_REFERENCE_CONTENT = <<~COMPLETE_REF
+# 📚 Clockify Detailed Reports API - Complete Reference
+
+## 🔗 **Endpoint**
+
+```
+POST https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed
+```
+
+**Authentication**: `X-Api-Key: YOUR_API_KEY`
+
+## ⚡ **Quick Start (Minimal Required Call)**
+
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z",
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 100
+  }
+}
+```
+
+**📊 Total Documented Errors**: 40+  
+**🔬 Based on**: Comprehensive API testing  
+**⚠️ More Accurate Than**: Official Clockify API documentation
+    COMPLETE_REF
+
+    INTERNAL_DOCUMENTATION_CONTENT = <<~INTERNAL_DOC
+# Clockify Detailed Reports API - Internal Documentation
+
+## Executive Summary
+
+This documentation provides comprehensive coverage of the Clockify Detailed Reports API based on extensive testing and validation.
+
+## Key Findings
+
+- 40+ documented API errors
+- AttendanceFilter has different pagination limits (201 vs 1000)
+- Official Clockify documentation contains errors
+- Server crashes from empty strings in certain fields
+
+## Implementation Guide
+
+### Authentication
+- API Key: Required in X-Api-Key header
+- Workspace ID: Required in URL path
+
+### Production Considerations
+- Implement proper error handling for 40+ documented errors
+- Use pagination for large datasets
+- Monitor rate limits and implement retries
+    INTERNAL_DOC
+  end
+end

data/lib/clockify_api_docs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClockifyApiDocs
+  VERSION = "1.0.0"
+end

data/lib/clockify_api_docs.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "clockify_api_docs/version"
+require_relative "clockify_api_docs/documentation"
+
+module ClockifyApiDocs
+  class Error < StandardError; end
+
+  # Main entry point for accessing Clockify Detailed Reports API documentation
+  def self.documentation
+    Documentation.new
+  end
+
+  # Quick access to user guide
+  def self.user_guide
+    documentation.user_guide
+  end
+
+  # Quick access to complete reference
+  def self.complete_reference
+    documentation.complete_reference
+  end
+
+  # Quick access to internal documentation
+  def self.internal_documentation
+    documentation.internal_documentation
+  end
+
+  # Print available documentation
+  def self.help
+    puts <<~HELP
+      🚀 Clockify Detailed Reports API Documentation Gem
+      
+      📊 SPECIFIC TO: POST /reports/detailed endpoint ONLY
+      ⚠️  NOT general Clockify API docs - just the detailed reports endpoint
+      
+      Available documentation:
+      
+      • ClockifyApiDocs.user_guide - Beginner-friendly guide
+      • ClockifyApiDocs.complete_reference - Complete technical reference
+      • ClockifyApiDocs.internal_documentation - Internal/team documentation
+      
+      Methods:
+      
+      • ClockifyApiDocs.documentation.save_all_to_directory(path) - Save all docs to folder
+      • ClockifyApiDocs.documentation.list_errors - Show all documented API errors
+      • ClockifyApiDocs.documentation.search(query) - Search documentation
+      
+      📚 More accurate than official Clockify documentation - based on real API testing!
+    HELP
+  end
+end