clockify_detailed_reports_api_docs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 414310f636ee7f1c54de4fa35715b685ffd04dfb3d0c088ba6c7b70009801d23
+  data.tar.gz: cd2cb66ec833601964dbb78b091c30c07520c1f457cee2040bb681c4bd432843
+SHA512:
+  metadata.gz: ffc83ab72d73afeffdd6f418bb3eb027d3964126d457465f048d1a9fe3898ee5fbc5bad881121b6cb244e4a562d5c8cdf719a5a8f1437c7dd1503713b6b23384
+  data.tar.gz: 62b478659fe6e7be9c7f54b4ea916a34e7f625924805466528a1921b3699a764c1a72d843bf78610c9c2f6f74746d2238e1d745d053a2eacb96329df7282346a

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-08-23
+
+### Added
+- Initial release of comprehensive Clockify Detailed Reports API documentation
+- Complete parameter reference with 60+ documented parameters
+- 43+ documented error conditions with solutions
+- Three documentation formats: User Guide, Complete Reference, and Internal Documentation
+- Search functionality across all documentation
+- Error listing and categorization
+- Real-world implementation examples
+
+### Discovered
+- 3 new validation errors not in official Clockify documentation:
+  - summaryFilter Groups Limit: Groups array must have 1-3 valid group types (Code 501)
+  - Invalid Group Names: Must use enum values like PROJECT, CLIENT, USER (Code 501)
+  - AttendanceFilter Page Limit: Different limit (201) than main filter (1000) (Code 501)
+
+### Corrected
+- AttendanceFilter maximum pageSize is 201, not 1000 as documented
+- AttendanceFilter sortColumn "NAME" fails, must use "USER" instead
+- summaryFilter requires specific enum values, not custom IDs
+- Empty strings in sortColumn, amountShown, exportType cause server crashes
+
+### Features
+- `ClockifyApiDocs.documentation` - Main documentation access
+- `ClockifyApiDocs.user_guide` - Beginner-friendly guide
+- `ClockifyApiDocs.complete_reference` - Complete technical reference  
+- `ClockifyApiDocs.internal_documentation` - Internal/team documentation
+- `Documentation#search(query)` - Search across all documentation
+- `Documentation#list_errors` - List all documented errors
+- `Documentation#save_all_to_directory(path)` - Export documentation
+- `Documentation#endpoint_info` - API endpoint information
+- `Documentation#quick_start_example` - Basic usage example
+
+### Documentation Coverage
+- Complete API endpoint documentation
+- Authentication and setup instructions
+- All request parameters with examples
+- Response structure documentation
+- Error handling with 40+ error conditions
+- Production considerations and best practices
+- Real-world implementation examples
+- Troubleshooting guides
+
+### Based On
+- Systematic API testing with automated error discovery
+- Real-world validation of all parameters and edge cases
+- Corrections to official Clockify API documentation
+- Battle-tested in production environments

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Clockify API Docs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,222 @@
+# ClockifyApiDocs
+
+🚀 **Battle-tested Clockify Detailed Reports API documentation** - More accurate than official documentation!
+
+📊 **IMPORTANT**: This gem is **ONLY** for the Clockify **Detailed Reports API endpoint** (`POST /reports/detailed`). It's **NOT** general Clockify API documentation.
+
+Based on comprehensive API testing, this gem provides complete documentation specifically for the Clockify Detailed Reports API endpoint with 43+ documented error conditions and corrections to the official Clockify specification.
+
+## 🔍 What Makes This Special
+
+- **43+ documented API errors** discovered through systematic testing
+- **Corrections to official Clockify documentation** - our testing found errors in the official spec
+- **3 newly discovered validation errors** not documented anywhere else
+- **Complete parameter reference** with real-world examples
+- **AttendanceFilter corrections** - different limits than documented (201 vs 1000)
+- **summaryFilter enum requirements** - must use specific enum values
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clockify_detailed_reports_api_docs'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install clockify_detailed_reports_api_docs
+
+## 🚀 Usage
+
+```ruby
+require 'clockify_api_docs'
+
+# Quick access to documentation
+puts ClockifyApiDocs.user_guide        # Beginner-friendly guide
+puts ClockifyApiDocs.complete_reference # Complete technical reference
+puts ClockifyApiDocs.internal_documentation # Internal team documentation
+
+# Access documentation object
+docs = ClockifyApiDocs.documentation
+
+# Save all documentation to a folder
+docs.save_all_to_directory('/path/to/save/docs')
+
+# Search documentation
+results = docs.search('attendanceFilter')
+results.each do |result|
+  puts "Found in #{result[:document]}: #{result[:content]}"
+end
+
+# List all documented errors
+errors = docs.list_errors
+puts "Total errors documented: #{errors.length}"
+
+# Get endpoint information
+endpoint = docs.endpoint_info
+puts "API Endpoint: #{endpoint[:url]}"
+
+# Get quick start example
+example = docs.quick_start_example
+puts example[:minimal].to_json
+```
+
+### Available Documentation
+
+- **User Guide** (`user_guide`) - Beginner-friendly guide with copy-paste examples
+- **Complete Reference** (`complete_reference`) - Technical reference with all 60+ parameters
+- **Internal Documentation** (`internal_documentation`) - Team/enterprise documentation
+
+## 📚 What's Included
+
+### Complete API Coverage
+- **Endpoint**: POST `/reports/detailed`
+- **Authentication**: X-Api-Key header setup
+- **All Parameters**: 60+ parameters documented with examples
+- **Response Structure**: Complete response format
+- **Error Handling**: 43+ error conditions with solutions
+
+### Key Discoveries
+- **AttendanceFilter** has max pageSize of 201 (not 1000 as documented)
+- **summaryFilter.groups** requires 1-3 specific enum values
+- **Empty strings** in certain parameters cause server crashes
+- **Official sortColumn values** for AttendanceFilter are incorrect
+
+### Documentation Types
+
+#### 1. User Guide
+Perfect for beginners:
+```ruby
+ClockifyApiDocs.user_guide
+```
+- Simple explanations
+- Copy-paste ready examples
+- Common use cases
+- Troubleshooting guide
+
+#### 2. Complete Technical Reference
+For developers:
+```ruby
+ClockifyApiDocs.complete_reference
+```
+- All 60+ parameters explained
+- Complete examples
+- All error conditions
+- Advanced filtering options
+
+#### 3. Internal Documentation
+For teams and enterprises:
+```ruby
+ClockifyApiDocs.internal_documentation
+```
+- Production considerations
+- Security best practices
+- Implementation examples
+- Monitoring guidelines
+
+## 🔧 API Quick Start
+
+⚠️ **This gem covers ONLY this specific endpoint:**
+```
+POST https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed
+```
+
+🚫 **NOT covered**: Other Clockify API endpoints like time entries, projects, users, etc.
+
+Minimal required request:
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z",
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 100
+  }
+}
+```
+
+## 🚨 Critical Warnings
+
+Based on our testing, avoid these common issues:
+
+- **Never use empty strings** in `sortColumn`, `amountShown`, or `exportType` - causes server crashes
+- **AttendanceFilter pageSize** max is 201, not 1000
+- **summaryFilter.groups** cannot be empty - needs 1-3 enum values
+- **Date format must be exact**: `YYYY-MM-DDTHH:MM:SS.sssZ`
+
+## 🎯 Real-World Examples
+
+### Monthly Invoice Generation
+```ruby
+# Get the example from the gem
+docs = ClockifyApiDocs.documentation
+invoice_example = docs.complete_reference.match(/Invoice Generation[\s\S]*?```json([\s\S]*?)```/)[1]
+```
+
+### Team Productivity Report
+```ruby
+# Search for team examples
+results = docs.search('team productivity')
+```
+
+## 🔍 Search Documentation
+
+```ruby
+# Search across all documentation
+results = ClockifyApiDocs.documentation.search('attendanceFilter')
+
+# Search for specific error codes
+error_results = ClockifyApiDocs.documentation.search('400/501')
+
+# Find parameter examples
+param_results = ClockifyApiDocs.documentation.search('pageSize')
+```
+
+## 🐛 Error Reference
+
+List all documented errors:
+```ruby
+errors = ClockifyApiDocs.documentation.list_errors
+puts "We've documented #{errors.length} error conditions"
+
+errors.each do |error|
+  puts "#{error[:code]}: #{error[:description]}"
+end
+```
+
+## 💡 Why This Gem Exists
+
+We built this after discovering that the official Clockify API documentation contained errors and missing information. Through systematic testing, we:
+
+- Found 43+ error conditions not properly documented
+- Discovered 3 validation errors not mentioned officially
+- Corrected incorrect parameter limits and enum values
+- Created more accurate and complete documentation
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/clockify_detailed_reports_api_docs.
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🔗 Links
+
+- **GitHub**: https://github.com/yourusername/clockify_detailed_reports_api_docs
+- **RubyGems**: https://rubygems.org/gems/clockify_detailed_reports_api_docs
+- **Issues**: https://github.com/yourusername/clockify_detailed_reports_api_docs/issues
+
+---
+
+**📊 Documentation Stats**:
+- 43+ documented errors
+- 60+ API parameters covered
+- 3 documentation formats
+- Based on real API testing
+- More accurate than official docs