reclaim 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2542e7a0ad06c9e9fef776da44dade129f247eefd519a32705168ef6d678b8bb
+  data.tar.gz: b51a8d23c1ce024d30ef4f0390ffdf8603ebb39061b1a6d61b97143300ea1360
+SHA512:
+  metadata.gz: 408a148e25073ed4e6735d6517df1dc2a79c164080489f4d951e43169afa2d5f581d5292b9acbfa624eaeedad5fe7a6517fd5e0dc04a06aba58944303adf7e8b
+  data.tar.gz: d52a5412e0830c622d1c5b53a38f7d289e286f51b78230458f88ff1574983bcb62fa5b1d090d3540a3d193799855a9ec5a0072e91e310f9b5d5ebd868ffe2bd4

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# 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).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-11-14
+
+### Added
+- Dotenv support for environment variable management
+- Automatic loading of `.env` files for API token configuration
+- Development dependency on `dotenv` gem (~> 2.8)
+
+### Changed
+- Renamed environment variable from `RECLAIM_TOKEN` to `RECLAIM_API_KEY` for clarity
+
+## [0.1.0] - 2025-10-29
+
+### Added
+- Initial release of Reclaim Ruby client
+- Complete task management API (CRUD operations)
+- Task filtering by status (active, completed, overdue)
+- Time scheme support with fuzzy name matching
+- Task splitting control (prevent splitting or configure chunk sizes)
+- Priority levels (P1-P4)
+- Date management (due dates, defer dates, start times)
+- Comprehensive error handling with custom exception types
+- Command-line interface (`reclaim` executable)
+- CLI commands: list, create, get, update, complete, delete, list-schemes
+- Full test suite (unit tests + integration tests)
+- Zero runtime dependencies (stdlib only)
+- Ruby 3.0+ support
+
+### Features
+- **Client**: HTTP client with authentication and caching
+- **Task Model**: Task representation with status helpers
+- **Utils**: Formatting and parsing utilities
+- **CLI**: Full-featured command-line interface
+- **Errors**: Custom exception hierarchy for better error handling
+
+[Unreleased]: https://github.com/benjaminjackson/reclaim-ruby/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/benjaminjackson/reclaim-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/benjaminjackson/reclaim-ruby/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benjamin Jackson
+
+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,367 @@
+# Reclaim Ruby Client
+
+[![Gem Version](https://badge.fury.io/rb/reclaim.svg)](https://badge.fury.io/rb/reclaim)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-ruby.svg)](https://www.ruby-lang.org/)
+
+A comprehensive Ruby library for interacting with the [Reclaim.ai](https://reclaim.ai) API. Manage your tasks programmatically with proper error handling, time scheme resolution, caching, and a powerful command-line interface.
+
+## Features
+
+- **Complete Task Management**: Create, read, update, delete, and complete tasks
+- **Time Scheme Support**: Resolve time schemes by name with fuzzy matching
+- **Task Filtering**: Filter tasks by status (active, completed, overdue)
+- **Flexible Scheduling**: Control task splitting, chunk sizes, and defer dates
+- **CLI Tool**: Full-featured command-line interface for task management
+- **Error Handling**: Comprehensive exception handling with custom error types
+- **Zero Dependencies**: Uses only Ruby stdlib (no runtime dependencies)
+- **Well Tested**: Extensive test coverage with unit and integration tests
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install reclaim
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'reclaim'
+```
+
+## Configuration
+
+Set your Reclaim.ai API token as an environment variable:
+
+```bash
+export RECLAIM_API_KEY='your_api_token_here'
+```
+
+Get your API token from your [Reclaim.ai settings](https://app.reclaim.ai/settings/developer).
+
+### Using .env Files (Optional)
+
+If you have the `dotenv` gem installed, the library will automatically load environment variables from `.env` and `.env.local` files from your current working directory. This is helpful for local development:
+
+```bash
+# .env
+RECLAIM_API_KEY='your_api_token_here'
+```
+
+**For users of this gem**: If you're using reclaim-ruby as a library in your own project and want .env file support, add dotenv to your project's Gemfile:
+
+```ruby
+gem 'dotenv', '~> 2.8'
+```
+
+**For contributors**: dotenv is already included as a development dependency for working on this gem.
+
+**File precedence**: `.env.local` takes precedence over `.env` and is typically gitignored for local-only overrides. Environment variables already set in your shell take precedence over .env files.
+
+## Usage
+
+### Ruby Library
+
+```ruby
+require 'reclaim'
+
+# Initialize client (uses ENV['RECLAIM_API_KEY'] by default)
+client = Reclaim::Client.new
+
+# Or pass token explicitly
+client = Reclaim::Client.new('your_api_token')
+
+# Create a task
+task = client.create_task(
+  title: 'Important Work',
+  due_date: '2025-12-31T17:00:00Z',
+  priority: :p1,
+  duration: 2.0,  # hours
+  notes: 'This is important!',
+  time_scheme: 'work'
+)
+
+puts "Created task: #{task.title} (#{task.id})"
+
+# List tasks
+active_tasks = client.list_tasks(filter: :active)
+completed_tasks = client.list_tasks(filter: :completed)
+overdue_tasks = client.list_tasks(filter: :overdue)
+all_tasks = client.list_tasks  # No filter
+
+active_tasks.each do |task|
+  puts "#{task.title} - #{task.status} (Priority: #{task.priority})"
+end
+
+# Get a specific task
+task = client.get_task('task_id_here')
+
+# Update a task
+updated_task = client.update_task(
+  task.id,
+  title: 'Updated Title',
+  priority: :p2,
+  duration: 3.0
+)
+
+# Mark task as complete (archives it)
+completed_task = client.complete_task(task.id)
+
+# Delete a task
+client.delete_task(task.id)
+
+# List available time schemes
+schemes = client.list_time_schemes
+schemes.each do |scheme|
+  puts "#{scheme['title']} (#{scheme['id']})"
+end
+
+# Get formatted time schemes
+puts client.format_time_schemes
+```
+
+### Task Priorities
+
+Tasks support four priority levels:
+
+- `:p1` - Highest priority (P1)
+- `:p2` - High priority (P2)
+- `:p3` - Normal priority (P3, default)
+- `:p4` - Low priority (P4)
+
+### Task Splitting
+
+Control whether tasks can be split into smaller chunks:
+
+```ruby
+# Prevent splitting (default)
+task = client.create_task(
+  title: 'Deep Work Session',
+  duration: 4.0  # Must be scheduled as a single 4-hour block
+)
+
+# Allow splitting with default chunk sizes
+task = client.create_task(
+  title: 'Flexible Task',
+  duration: 3.0,
+  allow_splitting: true  # Can be split into 15min-3hr chunks
+)
+
+# Allow splitting with custom minimum chunk size
+task = client.create_task(
+  title: 'Research',
+  duration: 4.0,
+  allow_splitting: true,
+  split_chunk_size: 0.5  # Minimum 30-minute chunks
+)
+
+# Full control over chunk sizes
+task = client.create_task(
+  title: 'Writing',
+  duration: 6.0,
+  allow_splitting: true,
+  min_chunk_size: 1.0,   # Minimum 1 hour
+  max_chunk_size: 2.0    # Maximum 2 hours
+)
+```
+
+### Time Schemes
+
+Time schemes control when tasks can be scheduled. You can reference them by name:
+
+```ruby
+# Use exact name
+task = client.create_task(
+  title: 'Work Task',
+  time_scheme: 'Work Hours'
+)
+
+# Use alias (fuzzy matching)
+task = client.create_task(
+  title: 'Work Task',
+  time_scheme: 'work'  # Finds "Work Hours"
+)
+
+# Supported aliases:
+# - 'work', 'working hours', 'business hours' → finds schemes with 'work'
+# - 'personal', 'off hours', 'private' → finds schemes with 'personal'
+```
+
+### Error Handling
+
+The library provides specific exception types:
+
+```ruby
+begin
+  client = Reclaim::Client.new('invalid_token')
+rescue Reclaim::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+end
+
+begin
+  task = client.get_task('nonexistent_id')
+rescue Reclaim::NotFoundError => e
+  puts "Task not found: #{e.message}"
+end
+
+begin
+  task = client.create_task(title: '', time_scheme: 'invalid')
+rescue Reclaim::InvalidRecordError => e
+  puts "Validation error: #{e.message}"
+end
+
+begin
+  # Network or API errors
+  tasks = client.list_tasks
+rescue Reclaim::ApiError => e
+  puts "API error: #{e.message}"
+  puts "Status: #{e.status_code}" if e.status_code
+end
+```
+
+### Command-Line Interface
+
+The gem includes a full-featured CLI:
+
+```bash
+# List active tasks (default)
+reclaim
+reclaim list active
+
+# List completed or overdue tasks
+reclaim list completed
+reclaim list overdue
+
+# Create a task
+reclaim create --title "Important Meeting Prep" \
+  --due 2025-12-31 \
+  --priority P1 \
+  --duration 2
+
+# Create a task that allows splitting
+reclaim create --title "Research Project" \
+  --duration 4 \
+  --split 0.5  # 30-minute minimum chunks
+
+# Get task details
+reclaim get TASK_ID
+
+# Update a task
+reclaim update TASK_ID \
+  --title "Updated Title" \
+  --priority P2
+
+# Clear a date field
+reclaim update TASK_ID --due none
+reclaim update TASK_ID --defer clear
+
+# Mark task as complete
+reclaim complete TASK_ID
+
+# Delete a task
+reclaim delete TASK_ID
+
+# List available time schemes
+reclaim list-schemes
+
+# Get help
+reclaim help
+reclaim --help
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/benjaminjackson/reclaim-ruby.git
+cd reclaim-ruby
+bundle install
+```
+
+### Running Tests
+
+```bash
+# Run unit tests only (no API calls)
+SKIP_INTEGRATION_TESTS=true bundle exec rake test
+
+# Run all tests (requires RECLAIM_API_KEY)
+bundle exec rake test
+
+# Run only integration tests
+bundle exec rake test TESTOPTS='-n /Integration/'
+```
+
+### Building the Gem
+
+```bash
+gem build reclaim.gemspec
+gem install ./reclaim-0.1.0.gem
+```
+
+## API Reference
+
+### Reclaim::Client
+
+Main client for API interactions.
+
+**Methods:**
+
+- `initialize(token = nil)` - Create client (uses ENV['RECLAIM_API_KEY'] if token not provided)
+- `create_task(**options)` - Create a new task
+- `list_tasks(filter: nil)` - List all tasks (filter: :active, :completed, :overdue, or nil)
+- `get_task(task_id)` - Get a specific task by ID
+- `update_task(task_id, **options)` - Update an existing task
+- `complete_task(task_id)` - Mark task as complete (ARCHIVED status)
+- `delete_task(task_id)` - Permanently delete a task
+- `list_time_schemes` - Get available time schemes
+- `format_time_schemes` - Get formatted time schemes for display
+
+### Reclaim::Task
+
+Task model with properties and helper methods.
+
+**Properties:**
+
+- `id`, `title`, `notes`, `due_date`, `priority`, `duration`
+- `status`, `time_scheme_id`, `always_private`, `event_category`, `event_color`
+- `min_chunk_size`, `max_chunk_size`, `snooze_until`, `start`
+
+**Methods:**
+
+- `active?` - Check if task is active (not deleted/archived/cancelled)
+- `completed?` - Check if task is completed (COMPLETE or ARCHIVED status)
+- `overdue?` - Check if task is past its due date
+- `due_date_formatted` - Get formatted due date string
+- `priority_symbol` - Get priority as symbol (:p1, :p2, :p3, :p4)
+
+### Exception Classes
+
+- `Reclaim::Error` - Base exception class
+- `Reclaim::AuthenticationError` - Authentication/token errors
+- `Reclaim::ApiError` - API/network errors (includes status_code and response_body)
+- `Reclaim::NotFoundError` - Resource not found (404)
+- `Reclaim::InvalidRecordError` - Validation errors (422)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/benjaminjackson/reclaim-ruby.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Links
+
+- **RubyGems**: https://rubygems.org/gems/reclaim
+- **Source Code**: https://github.com/benjaminjackson/reclaim-ruby
+- **Bug Reports**: https://github.com/benjaminjackson/reclaim-ruby/issues
+- **Reclaim.ai**: https://reclaim.ai
+- **API Documentation**: https://reclaim.ai/api

data/bin/reclaim

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'reclaim'
+
+Reclaim::CLI.run