Add Karakeep export command with comprehensive functionality

[digithree]

Summary

Add a new export command to sync Pocket bookmarks to Karakeep via REST API. This provides a complete solution for exporting Pocket data to external bookmark management systems with robust error handling, retry logic, and user-friendly features.

New Export Command Features

🚀 Core Functionality

• Full CLI Integration - New pocket-to-sqlite export command with comprehensive options
• Karakeep API Client - Production-ready REST API client with Bearer token authentication
• Data Mapping - Intelligent mapping from Pocket fields to Karakeep bookmark format
• Progress Tracking - Real-time progress bars with accurate item counts
• Resume Capability - Offset-based pagination for large exports and recovery

🛡️ Robust Error Handling

• Progressive Retry Logic - Up to 5 retries with exponential backoff for network issues
• Timeout Handling - 30-second request timeouts with retry on failure
• Rate Limiting - Automatic handling of 429 rate limit responses
• Client Error Handling - Proper parsing of 400-level errors without unnecessary retries
• Server Error Recovery - Retry logic for 503/504 server errors

🎯 Advanced Filtering & Options

• Status Filtering - Export by Pocket status (unread/archived/deleted)
• Favorite Filtering - Export only favorited items
• Batching Support - Limit and offset parameters for controlled exports
• Dry-Run Mode - Preview functionality without making API calls
• Debug Mode - Comprehensive logging for troubleshooting
• Silent Mode - Suppress progress output for automated use

🔧 Authentication & Configuration

• Extended auth.json - Adds karakeep_token and karakeep_base_url to existing auth pattern
• Configurable Base URL - Support for custom Karakeep instances
• Validation - Pre-flight checks for required credentials and database tables

Technical Implementation

KarakeepClient API Integration

# Handles actual Karakeep API response formats
{
  "id": "string",
  "createdAt": "string", 
  "title": "string",
  "content": {"type": "link", "url": "string"},
  // ... full Karakeep response structure
}

# Error responses with proper parsing
{
  "code": "VALIDATION_ERROR",
  "message": "Title is required and cannot be empty"
}

Field Mapping

• resolved_title or given_title → title
• excerpt → summary
• resolved_url or given_url → url
• type → "link" (constant)

Error Recovery Features

• Network timeouts and connection errors with retry
• Rate limiting (429) with progressive backoff
• Server errors (503/504) with retry logic
• Client errors (400-499) with immediate failure and clear messages
• Graceful handling of items without URLs (skip with logging)

Usage Examples

Basic Export

# Export all bookmarks
pocket-to-sqlite export pocket.db

# Export with progress and error details
pocket-to-sqlite export pocket.db --debug

Advanced Filtering

# Export only unread items
pocket-to-sqlite export pocket.db --filter-status 0

# Export only favorites
pocket-to-sqlite export pocket.db --filter-favorite

# Combined filters
pocket-to-sqlite export pocket.db --filter-status 1 --filter-favorite

Batching & Resume

# Export first 100 items
pocket-to-sqlite export pocket.db --limit 100

# Resume from item 500  
pocket-to-sqlite export pocket.db --offset 500 --limit 100

Preview & Testing

# Dry-run to preview export
pocket-to-sqlite export pocket.db --dry-run --limit 10

# Silent mode for automation
pocket-to-sqlite export pocket.db --silent

Authentication Setup

Extend existing auth.json file:

{
  "pocket_consumer_key": "...",
  "pocket_access_token": "...",
  "karakeep_token": "your-karakeep-api-token",
  "karakeep_base_url": "https://your-karakeep-instance.com"
}

Testing & Quality

Comprehensive Test Coverage

• 8 new test cases covering all functionality
• KarakeepClient tests - API interaction, retry logic, error handling
• Export function tests - Filtering, batching, error scenarios
• CLI integration tests - Command validation, dry-run functionality
• Mock-based testing - Isolated unit tests with proper API response simulation

Real-World Validation

• ✅ Successfully tested against actual Karakeep API
• ✅ Verified authentication and request formatting
• ✅ Confirmed 201 responses with proper bookmark creation
• ✅ Validated error handling with 400-level responses

Files Changed

• pocket_to_sqlite/cli.py - New export command with full CLI interface
• pocket_to_sqlite/utils.py - KarakeepClient and export functionality
• tests/test_save_pocket.py - Comprehensive test coverage
• README.md - Complete documentation with examples

Breaking Changes

None. This is a purely additive feature that extends existing functionality without modifying current behavior.

Performance & Reliability

• Efficient API usage - 1-second delays between requests to respect rate limits
• Memory efficient - Streaming export with generator-based processing
• Network resilient - Comprehensive retry logic for production reliability
• Progress tracking - Real-time feedback for long-running exports
• Resume capability - Recoverable exports for large datasets

Ready for Production

This implementation provides enterprise-grade reliability with:

• Comprehensive error handling and recovery
• Production-tested retry logic
• Clear logging and debugging capabilities
• User-friendly progress tracking
• Flexible filtering and batching options
• Complete documentation and examples

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com