clockify-export 0.1.1__tar.gz → 0.1.5__tar.gz

{clockify_export-0.1.1 → clockify_export-0.1.5}/.gitignore

@@ -6,3 +6,4 @@ dist/
 *.egg-info/
 
 export/
+.idea/

clockify_export-0.1.5/AGENTS.md

@@ -0,0 +1,66 @@
+# Agent Instructions
+
+When generating documentation and comments, be as concise and brief as possible without loosing relevant information.
+
+## Project Files
+
+| File | Purpose |
+|------|---------|
+| `PLAN.md` | Development roadmap and task tracking |
+| `CHANGELOG.md` | Version history (Keep a Changelog format) |
+| `README.md` | User documentation |
+
+---
+
+## Updating the Plan
+
+When **adding/removing/starting/resolving tasks**:
+
+1. Edit `PLAN.md`
+2. Use status markers:
+   - `[ ]` — Not started
+   - `🔄` — In progress
+3. When a task is implemented, update `CHANGELOG.md` (in "Unreleased" section) and remove from `PLAN.md`
+
+---
+
+## Updating the Changelog
+
+1. Edit `CHANGELOG.md`
+2. Keep `[Unreleased]` section for things done since last release
+3. Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
+
+---
+
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/):
+- **MAJOR** — Breaking changes
+- **MINOR** — New features (backward compatible)
+- **PATCH** — Bug fixes (backward compatible)
+
+Current version defined in: `pyproject.toml` (also read by `src/clockify_export/__init__.py`)
+
+---
+
+## Code Locations
+
+| Feature | File |
+|---------|------|
+| CLI entry point | `src/clockify_export/cli.py` |
+| Export logic | `src/clockify_export/export.py` |
+| API client | `src/clockify_export/api.py` |
+| Config/state | `src/clockify_export/config.py` |
+| Cache | `src/clockify_export/cache.py` |
+
+## Tests
+
+- Test files in `tests/` directory
+- Run with: `uv run pytest tests/ -v`
+- 90 tests covering:
+  - API: duration parsing, errors
+  - Config: date parsing, priority chain (CLI > env > config.toml > defaults), refetch calculations
+  - Cache: read/write, expiry, workspace data
+  - Export: CSV formatting, grouping, filters, current month filenames, cleanup
+  - CLI: flags, mutually exclusive options, workspace filtering
+- Add more test cases when bugs are encountered

clockify_export-0.1.5/CHANGELOG.md

@@ -0,0 +1,38 @@
+# 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]
+
+### Added
+- Auto-refresh cache when unknown project/client/tag ID encountered during entry processing
+- Cache for workspaces, projects, clients, tags with 1-week expiry
+- `--no-cache` flag to bypass cache and force fresh API fetch
+- Current month CSV includes date in filename (e.g., `...-2026-09-17.csv`)
+- Auto-cleanup of old current-month files with different dates
+- Mutually exclusive date range options: `--from`, `--last`, `--refetch`
+
+### Changed
+- Removed `last` option from config file (prevents inconsistent behavior)
+- `last` is now CLI-only flag
+- Cache now stores timestamp and expires after 1 week
+
+### Fixed
+- Cache validation: expired cache entries are ignored
+
+---
+
+## [0.1.0] - 2026-09-10
+
+### Added
+- Initial release
+- Multi-workspace export
+- Incremental export with state tracking
+- Monthly CSV output per workspace/year
+- Config file support (`~/.config/clockify-export/config.toml`)
+- `--full`, `--from`, `--last`, `--refetch`, `--workspace`, `--status` flags
+- Zero dependencies (stdlib only)
+- systemd timer support for scheduled exports

{clockify_export-0.1.1 → clockify_export-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clockify-export
-Version: 0.1.1
+Version: 0.1.5
 Summary: Export Clockify time entries to CSV with incremental support
 Project-URL: Homepage, https://github.com/ptandler/clockify-export
 Project-URL: Repository, https://github.com/ptandler/clockify-export
@@ -19,6 +19,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Office/Business :: Financial :: Accounting
 Classifier: Topic :: Office/Business :: Scheduling
 Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Clockify Export
@@ -191,3 +194,55 @@ always consistent.
 ## License
 
 MIT
+
+## Schedule Daily Export via systemd
+
+Use can use systemd timers to call the export regularily.
+
+### Install with mise
+
+[mise](https://mise.jdx.dev) can install the systemd unit automatically:
+
+```bash
+mise install-systemd
+```
+
+This copies the service/timer files to `~/.config/systemd/user/` and enables the timer.
+
+### Systemd Timer (daily export)
+
+To run the export automatically every day as a systemd user unit:
+
+#### 1. Install the service and timer
+
+```bash
+cp systemd/clockify-export.service "$HOME/.config/systemd/user/"
+cp systemd/clockify-export.timer "$HOME/.config/systemd/user/"
+systemctl --user daemon-reload
+systemctl --user enable --now clockify-export.timer
+```
+
+#### 2. Set your API key
+
+The unit reads the Clockify API key from the config file.
+You can create one via `clockify-export --init-config` and ensure the
+`api_key` is set in `~/.config/clockify-export/config.toml`.
+
+#### 3. Manage the timer
+
+The default timer is for daily export. Feel free to adjust `OnUnitActiveSec` if desired.
+
+```bash
+# View status
+systemctl --user status clockify-export.timer
+systemctl --user status clockify-export.service
+
+# Manual run
+systemctl --user clockify-export
+
+# Disable
+systemctl --user disable --now clockify-export.timer
+```
+
+> Note: The service uses `Type=oneshot` so it completes and exits each day.
+> Logs can be viewed with `journalctl --user -u clockify-export.service`.

clockify_export-0.1.5/PLAN.md

@@ -0,0 +1,48 @@
+# Development Plan
+
+## Current Version: 0.2.0
+
+---
+
+## ✅ Completed (v0.2.0)
+
+- [x] Cache for workspaces, projects, clients, tags (1-week expiry)
+- [x] `--no-cache` flag to bypass cache
+- [x] Current month CSV includes date in filename (e.g., `...-2026-09-17.csv`)
+- [x] Auto-cleanup of old current-month files
+- [x] Mutually exclusive `--from`, `--last`, `--refetch` options
+- [x] Removed `last` from config file (only CLI)
+
+---
+
+## 🔄 In Progress
+
+- [ ] Auto-refresh cache when unknown project/client/tag ID encountered during entry processing
+
+---
+
+## 📋 Backlog
+
+### Cache Improvements
+- [ ] Add cache stats/debug command (`--cache-status`)
+- [ ] Add config option for cache TTL (default 1 week)
+- [ ] Cache workspaces list (currently only workspace data cached)
+
+### Export Features
+- [ ] Add `--dry-run` to show what would be exported without writing
+- [ ] Add `--format json` output option
+- [ ] Support exporting to single combined CSV (optionally)
+
+### Reliability
+- [ ] Add retry logic with exponential backoff for API requests
+- [ ] Handle HTTP 429 rate limits gracefully (wait and retry)
+
+### Developer Experience
+- [ ] Add `--verbose` / `--quiet` flags
+- [ ] Add progress bar for long exports
+
+---
+
+## 🐛 Known Issues
+
+- None currently

{clockify_export-0.1.1 → clockify_export-0.1.5}/README.md

@@ -168,3 +168,55 @@ always consistent.
 ## License
 
 MIT
+
+## Schedule Daily Export via systemd
+
+Use can use systemd timers to call the export regularily.
+
+### Install with mise
+
+[mise](https://mise.jdx.dev) can install the systemd unit automatically:
+
+```bash
+mise install-systemd
+```
+
+This copies the service/timer files to `~/.config/systemd/user/` and enables the timer.
+
+### Systemd Timer (daily export)
+
+To run the export automatically every day as a systemd user unit:
+
+#### 1. Install the service and timer
+
+```bash
+cp systemd/clockify-export.service "$HOME/.config/systemd/user/"
+cp systemd/clockify-export.timer "$HOME/.config/systemd/user/"
+systemctl --user daemon-reload
+systemctl --user enable --now clockify-export.timer
+```
+
+#### 2. Set your API key
+
+The unit reads the Clockify API key from the config file.
+You can create one via `clockify-export --init-config` and ensure the
+`api_key` is set in `~/.config/clockify-export/config.toml`.
+
+#### 3. Manage the timer
+
+The default timer is for daily export. Feel free to adjust `OnUnitActiveSec` if desired.
+
+```bash
+# View status
+systemctl --user status clockify-export.timer
+systemctl --user status clockify-export.service
+
+# Manual run
+systemctl --user clockify-export
+
+# Disable
+systemctl --user disable --now clockify-export.timer
+```
+
+> Note: The service uses `Type=oneshot` so it completes and exits each day.
+> Logs can be viewed with `journalctl --user -u clockify-export.service`.

clockify_export-0.1.5/mise-tasks/bump-version

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -e
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  echo "Error: Uncommitted changes detected. Commit or stash them first."
+  exit 1
+fi
+uv run pytest
+uv version --bump $@
+git add -A
+version="v$(uv version --short)"
+git commit -m "chore: release $version"
+git tag "$version"
+git push && git push --tags

{clockify_export-0.1.1 → clockify_export-0.1.5}/mise.toml

@@ -11,4 +11,5 @@ export = "uv run clockify-export --output-dir ./export"
 export-full = "uv run clockify-export --full --output-dir ./export"
 status = "uv run clockify-export --status"
 init-config = "uv run clockify-export --init-config"
-test = "uv run python -c \"from clockify_export.api import ClockifyAPI; print('import ok')\""
+test = "uv run python -c \"from clockify_export.api import ClockifyAPI; print('import ok')\""
+install-systemd = "cp systemd/clockify-export.service \"$HOME/.config/systemd/user/\" && cp systemd/clockify-export.timer \"$HOME/.config/systemd/user/\" && systemctl --user daemon-reload && systemctl --user enable --now clockify-export.timer"

{clockify_export-0.1.1 → clockify_export-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clockify-export"
-version = "0.1.1"
+version = "0.1.5"
 description = "Export Clockify time entries to CSV with incremental support"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,6 +20,12 @@ classifiers = [
 ]
 dependencies = []
 
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-mock",
+]
+
 [project.urls]
 Homepage = "https://github.com/ptandler/clockify-export"
 Repository = "https://github.com/ptandler/clockify-export"

clockify_export-0.1.5/src/clockify_export/__init__.py

@@ -0,0 +1,8 @@
+"""clockify-export — export Clockify time entries to CSV."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("clockify-export")
+except PackageNotFoundError:  # pragma: no cover - running from source without install
+    __version__ = "0.0.0"

clockify_export-0.1.5/src/clockify_export/cache.py

@@ -0,0 +1,90 @@
+"""Cache management for Clockify data."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+
+CACHE_DIR = ".cache"
+DEFAULT_MAX_AGE_SECONDS = 7 * 24 * 60 * 60  # 1 week
+
+
+def get_cache_dir(export_dir: Path) -> Path:
+    """Get the cache directory path."""
+    return export_dir / CACHE_DIR
+
+
+def _read_json(path: Path) -> dict | None:
+    """Read JSON file, return None if not exists or invalid."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json(path: Path, data: dict) -> None:
+    """Write JSON file, creating parent directories."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def load_cache(export_dir: Path, name: str, max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS) -> dict | None:
+    """Load cached data by name, return None if expired or missing."""
+    cache_dir = get_cache_dir(export_dir)
+    data = _read_json(cache_dir / f"{name}.json")
+    if data is None:
+        return None
+    # Check age
+    cached_time = data.get("_cached_at", 0)
+    if time.time() - cached_time > max_age_seconds:
+        return None
+    return data
+
+
+def save_cache(export_dir: Path, name: str, data: dict) -> bool:
+    """Save data to cache if changed. Returns True if written."""
+    cache_dir = get_cache_dir(export_dir)
+    path = cache_dir / f"{name}.json"
+    existing = _read_json(path)
+    if existing == data:
+        return False
+    # Add timestamp
+    data_with_ts = {"_cached_at": time.time(), **data}
+    _write_json(path, data_with_ts)
+    return True
+
+
+def load_workspaces(export_dir: Path, max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS) -> list[dict] | None:
+    """Load cached workspaces."""
+    data = load_cache(export_dir, "workspaces", max_age_seconds)
+    return data.get("workspaces") if data else None
+
+
+def save_workspaces(export_dir: Path, workspaces: list[dict]) -> bool:
+    """Save workspaces to cache if changed."""
+    return save_cache(export_dir, "workspaces", {"workspaces": workspaces})
+
+
+def load_workspace_data(export_dir: Path, workspace_id: str, max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS) -> dict | None:
+    """Load cached workspace data (projects, clients, tags)."""
+    return load_cache(export_dir, f"workspace_{workspace_id}", max_age_seconds)
+
+
+def save_workspace_data(
+    export_dir: Path,
+    workspace_id: str,
+    projects: list[dict],
+    clients: list[dict],
+    tags: list[dict],
+) -> bool:
+    """Save workspace data to cache if changed."""
+    data = {
+        "projects": projects,
+        "clients": clients,
+        "tags": tags,
+    }
+    return save_cache(export_dir, f"workspace_{workspace_id}", data)

{clockify_export-0.1.1 → clockify_export-0.1.5}/src/clockify_export/cli.py

@@ -7,14 +7,22 @@ import sys
 from datetime import datetime, timedelta, timezone
 
 from .api import ClockifyAPI, ClockifyError
-from .config import CONFIG_FILE, Config, create_config_file, get_last_exported, set_last_exported
+from .config import CONFIG_FILE, Config, CONFIG_HELP, create_config_file, get_last_exported, set_last_exported, parse_from_date, calculate_last_months, calculate_refetch_date
 from .export import export_workspace
+from . import __version__
 
 
 def main() -> None:
     parser = argparse.ArgumentParser(
         prog="clockify-export",
         description="Export Clockify time entries to CSV",
+        epilog=CONFIG_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
     )
     parser.add_argument(
         "--output-dir", "-o",
@@ -33,12 +41,27 @@ def main() -> None:
         action="store_true",
         help="Full export: ignore incremental state, export everything",
     )
-    parser.add_argument(
+
+    # Mutually exclusive date range options
+    date_group = parser.add_mutually_exclusive_group()
+    date_group.add_argument(
         "--from",
         dest="from_date",
         type=str,
         default=None,
-        help="Export entries from this date (YYYY-MM-DD). Overrides incremental state.",
+        help="Export entries from this date (YYYY-MM or YYYY-MM-DD). Always starts at beginning of month. Overrides incremental state.",
+    )
+    date_group.add_argument(
+        "--last",
+        type=int,
+        default=None,
+        help="Export the last N complete months (e.g., --last 3 exports last 3 complete months).",
+    )
+    date_group.add_argument(
+        "--refetch",
+        type=int,
+        default=None,
+        help="Re-fetch N months back from last exported date (can be set in config). Useful if entries were modified.",
     )
     parser.add_argument(
         "--workspace",
@@ -56,6 +79,11 @@ def main() -> None:
         action="store_true",
         help="Create ~/.config/clockify-export/config.toml and exit",
     )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Bypass cache, fetch fresh projects/clients/tags from API",
+    )
     args = parser.parse_args()
 
     if args.init_config:
@@ -131,9 +159,21 @@ def main() -> None:
         # Determine start date
         since = None
         if cfg.from_date:
-            # Explicit --from flag overrides everything
-            since = datetime.strptime(cfg.from_date, "%Y-%m-%d").replace(tzinfo=timezone.utc)
-            print(f"  --from: fetching since {cfg.from_date}")
+            # Explicit --from flag overrides everything, always start at beginning of month
+            since = parse_from_date(cfg.from_date)
+            print(f"  --from: fetching since {since.strftime('%Y-%m-%d')}")
+        elif args.last is not None and args.last > 0:
+            # --last N: export last N complete months
+            since = calculate_last_months(args.last)
+            print(f"  --last {args.last}: fetching since {since.strftime('%Y-%m-%d')} (last {args.last} complete months)")
+        elif cfg.refetch > 0:
+            # --refetch N: re-fetch N months back from last exported date
+            last = get_last_exported(ws_id)
+            since = calculate_refetch_date(cfg.refetch, last)
+            if since:
+                print(f"  --refetch {cfg.refetch}: re-fetching from {since.strftime('%Y-%m-%d')} (last exported: {last})")
+            else:
+                print(f"  --refetch {cfg.refetch}: no prior export found, skipping refetch")
         elif not cfg.full:
             last = get_last_exported(ws_id)
             if last:
@@ -146,16 +186,14 @@ def main() -> None:
             print("  Full export mode")
 
         try:
-            counts = export_workspace(api, ws_id, ws_name, output_dir, since=since)
+            counts, latest_entry_dt = export_workspace(
+                api, ws_id, ws_name, output_dir, since=since,
+                use_cache=not args.no_cache,
+            )
             if counts:
-                # Update state to the latest entry date
-                latest_month = max(counts.keys())
-                latest_ts = datetime.strptime(latest_month, "%Y-%m").replace(tzinfo=timezone.utc)
-                # Set to end of month to mark the whole month as exported
-                from calendar import monthrange
-                _, last_day = monthrange(latest_ts.year, latest_ts.month)
-                latest_ts = latest_ts.replace(day=last_day)
-                set_last_exported(ws_id, latest_ts.isoformat())
+                # Update state to the actual latest entry date (not end of month)
+                if latest_entry_dt:
+                    set_last_exported(ws_id, latest_entry_dt.isoformat())
                 total = sum(counts.values())
                 print(f"  Total: {total} entries across {len(counts)} month(s)")
             else:

{clockify_export-0.1.1 → clockify_export-0.1.5}/src/clockify_export/config.py

@@ -25,8 +25,22 @@ STATE_FILE = CONFIG_DIR / "state.json"
 DEFAULTS = {
     "api_key": None,
     "export_dir": "export",
+    "refetch": 1,
 }
 
+CONFIG_HELP = """
+Supported configuration options (config.toml):
+  api_key       - Clockify API key (required)
+  export_dir    - Output directory for CSV files (default: "export")
+  refetch       - Number of months to re-fetch from last exported date (default: 1)
+
+Example config.toml:
+  # Clockify export configuration
+  api_key = "YOUR_API_KEY"
+  export_dir = "export"
+  refetch = 1
+"""
+
 
 @dataclass
 class Config:
@@ -35,6 +49,7 @@ class Config:
     full: bool = False
     workspaces: list[str] = field(default_factory=list)
     from_date: str | None = None
+    refetch: int = 0
 
     @classmethod
     def load(cls, args=None) -> Config:
@@ -61,6 +76,12 @@ class Config:
         full = getattr(args, "full", False) if args else False
         workspaces = getattr(args, "workspace", []) if args else []
         from_date = getattr(args, "from_date", None) if args else None
+        
+        # For refetch: CLI arg wins, then config file, then default
+        if args and getattr(args, "refetch", None) is not None:
+            refetch = args.refetch
+        else:
+            refetch = file_cfg.get("refetch", DEFAULTS["refetch"])
 
         return cls(
             api_key=api_key or "",
@@ -68,6 +89,7 @@ class Config:
             full=full,
             workspaces=workspaces or [],
             from_date=from_date,
+            refetch=refetch,
         )
 
 
@@ -111,10 +133,48 @@ def create_config_file(api_key: str = "", export_dir: str = "export") -> Path:
         "# Clockify export configuration\n"
         f'api_key = "{api_key}"\n'
         f'export_dir = "{export_dir}"\n'
+        "# Number of months to re-fetch from last exported date (default: 1)\n"
+        "refetch = 1\n"
     )
     return CONFIG_FILE
 
 
+def parse_from_date(date_str: str) -> datetime:
+    """Parse --from date string (YYYY-MM or YYYY-MM-DD) and return first day of that month."""
+    parts = date_str.split("-")
+    if len(parts) < 2:
+        raise ValueError(f"Invalid date format: {date_str}. Use YYYY-MM or YYYY-MM-DD")
+    year = int(parts[0])
+    month = int(parts[1])
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
+def calculate_last_months(last: int) -> datetime:
+    """Calculate the first day of the month that is 'last' complete months ago."""
+    now = datetime.now(timezone.utc)
+    # Go back 'last' months from the current month, then get the first day of that month
+    # If last=1, we want last complete month (not current month)
+    year = now.year
+    month = now.month - last
+    while month <= 0:
+        month += 12
+        year -= 1
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
+def calculate_refetch_date(refetch: int, last_exported: str | None) -> datetime | None:
+    """Calculate the date to start re-fetching from, going back 'refetch' months from last exported."""
+    if not last_exported or refetch <= 0:
+        return None
+    last_dt = datetime.fromisoformat(last_exported)
+    year = last_dt.year
+    month = last_dt.month - refetch
+    while month <= 0:
+        month += 12
+        year -= 1
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
 def get_state() -> dict:
     if STATE_FILE.exists():
         try: