clockify-unofficial-cli 0.2.0__py3-none-any.whl

clockify_unofficial_cli/runtime/exit_codes.py

@@ -0,0 +1,15 @@
+from enum import IntEnum
+
+
+# 1 and 2 are reserved by Click for generic failures and usage errors.
+class ExitCode(IntEnum):
+    OK = 0
+    FAILURE = 1
+    USAGE = 2
+    CONFIGURATION = 3
+    AUTHENTICATION = 4
+    FORBIDDEN = 5
+    NOT_FOUND = 6
+    VALIDATION = 7
+    RATE_LIMITED = 8
+    UNAVAILABLE = 9

clockify_unofficial_cli/runtime/params.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import dataclasses
+import functools
+import inspect
+from typing import TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def _parameter(field: dataclasses.Field[object], annotation: object) -> inspect.Parameter:
+    default = inspect.Parameter.empty if field.default is dataclasses.MISSING else field.default
+    return inspect.Parameter(field.name, inspect.Parameter.KEYWORD_ONLY, default=default, annotation=annotation)
+
+
+# Typer builds a command from the callback's signature, so every option must be a parameter. This
+# fabricates that signature from a dataclass and hands the callback one options object instead,
+# which keeps commands within the argument limit without dropping any flag.
+def options_from[T, R](options: type[T]) -> Callable[[Callable[[typer.Context, T], R]], Callable[..., R]]:
+    annotations = inspect.get_annotations(options, eval_str=True)
+    context = inspect.Parameter("ctx", inspect.Parameter.KEYWORD_ONLY, annotation=typer.Context)
+    fields = dataclasses.fields(options)  # type: ignore[arg-type]
+    parameters = [context, *(_parameter(field, annotations[field.name]) for field in fields)]
+    signature = inspect.Signature(parameters)
+
+    def decorate(func: Callable[[typer.Context, T], R]) -> Callable[..., R]:
+        @functools.wraps(func)
+        def wrapper(*, ctx: typer.Context, **values: object) -> R:
+            return func(ctx, options(**values))
+
+        wrapper.__signature__ = signature  # type: ignore[attr-defined]
+        wrapper.__annotations__ = {parameter.name: parameter.annotation for parameter in parameters}
+        del wrapper.__wrapped__
+        return wrapper
+
+    return decorate

clockify_unofficial_cli/runtime/prompts.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+
+# Single "are you sure?" prompt shared by every destructive command.
+# TTYs get an interactive confirm; non-TTY callers must pass --yes. A "no" reply
+# exits OK (the user explicitly cancelled, not a failure).
+def confirm(action: str, *, assume_yes: bool) -> None:
+    if assume_yes:
+        return
+    if not sys.stdin.isatty():
+        message = f"{action} requires --yes when run non-interactively."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    if not typer.confirm(action, err=True):
+        raise typer.Exit(ExitCode.OK)
+
+
+__all__ = ["confirm"]

clockify_unofficial_cli/services/listing.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from collections.abc import Iterable
+    from collections.abc import Iterator
+
+    from clockify._pagination import Page
+
+
+@dataclass(frozen=True, slots=True)
+class ListOptions:
+    limit: int | None = None
+    page: int | None = None
+    page_size: int | None = None
+
+
+def collect[T](
+    fetch_all: Callable[[], Iterator[T]],
+    fetch_page: Callable[..., Page[T]],
+    options: ListOptions,
+) -> Iterable[T]:
+    if options.page is not None or options.page_size is not None:
+        if options.limit is not None:
+            message = "--limit cannot be combined with --page/--page-size."
+            raise CliError(message, exit_code=ExitCode.USAGE)
+        return _paginated(fetch_page, options)
+    if options.limit is None:
+        return fetch_all()
+    return itertools.islice(fetch_all(), options.limit)
+
+
+def _paginated[T](
+    fetch_page: Callable[..., Page[T]],
+    options: ListOptions,
+) -> Iterable[T]:
+    page = options.page if options.page is not None else 1
+    return fetch_page(page=page, page_size=options.page_size).items
+
+
+def list_from_options[T](
+    fetch_all: Callable[[], Iterator[T]],
+    fetch_page: Callable[..., Page[T]],
+    limit: int | None,
+    page: int | None,
+    page_size: int | None,
+) -> Iterable[T]:
+    return collect(fetch_all, fetch_page, ListOptions(limit=limit, page=page, page_size=page_size))
+
+
+__all__ = ["ListOptions", "collect", "list_from_options"]

clockify_unofficial_cli/services/parsing.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import datetime
+import re
+from typing import Final
+
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+_DURATION_PATTERN: Final[str] = r"^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$"
+_DURATION_RE: Final[re.Pattern[str]] = re.compile(_DURATION_PATTERN)
+
+_CLOCK_PATTERN: Final[str] = r"^(\d{1,3}):(\d{2})(?::(\d{2}))?$"
+_CLOCK_RE: Final[re.Pattern[str]] = re.compile(_CLOCK_PATTERN)
+
+_RELATIVE_PATTERN: Final[str] = r"^([+-])(\d+)([hm])$"
+_RELATIVE_RE: Final[re.Pattern[str]] = re.compile(_RELATIVE_PATTERN)
+
+_DAY_KEYWORDS: Final[frozenset[str]] = frozenset({"today", "tomorrow", "yesterday"})
+
+
+def parse_duration(value: str) -> datetime.timedelta:
+    raw = value.strip()
+    if not raw:
+        message = f"Invalid duration '{value}'."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    if ":" in raw:
+        return _parse_clock_duration(raw)
+    if _DURATION_RE.match(raw) and any(raw.endswith(unit) for unit in ("h", "m", "s")):
+        return _parse_compact_duration(raw)
+    message = f"Invalid duration '{value}'."
+    raise CliError(message, exit_code=ExitCode.USAGE)
+
+
+def _parse_compact_duration(value: str) -> datetime.timedelta:
+    match = _DURATION_RE.match(value)
+    if match is None:
+        message = f"Invalid duration '{value}'."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    return datetime.timedelta(
+        hours=int(match.group(1) or 0),
+        minutes=int(match.group(2) or 0),
+        seconds=int(match.group(3) or 0),
+    )
+
+
+def _parse_clock_duration(value: str) -> datetime.timedelta:
+    match = _CLOCK_RE.match(value)
+    if match is None:
+        message = f"Invalid duration '{value}'."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    hours, minutes, seconds = match.groups()
+    return datetime.timedelta(hours=int(hours), minutes=int(minutes), seconds=int(seconds or 0))
+
+
+def parse_instant(value: str) -> datetime.datetime:
+    raw = value.strip()
+    if not raw:
+        message = f"Invalid instant '{value}'."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    if _CLOCK_RE.match(raw):
+        return _today_at(raw)
+    head, _, tail = raw.partition(" ")
+    lowered_head = head.casefold()
+    if lowered_head in _DAY_KEYWORDS:
+        return _day_keyword_at(lowered_head, tail or "00:00")
+    if _RELATIVE_RE.match(raw):
+        return _resolve_relative(raw)
+    return _resolve_absolute(raw)
+
+
+def _today_at(time_str: str) -> datetime.datetime:
+    today = datetime.datetime.now(datetime.UTC).date()
+    hour, minute = _parse_clock(time_str)
+    return datetime.datetime(today.year, today.month, today.day, hour, minute, tzinfo=datetime.UTC)
+
+
+def _day_keyword_at(keyword: str, time_str: str) -> datetime.datetime:
+    today = datetime.datetime.now(datetime.UTC).date()
+    if keyword == "today":
+        target = today
+    elif keyword == "tomorrow":
+        target = today + datetime.timedelta(days=1)
+    else:
+        target = today - datetime.timedelta(days=1)
+    hour, minute = _parse_clock(time_str)
+    return datetime.datetime(target.year, target.month, target.day, hour, minute, tzinfo=datetime.UTC)
+
+
+def _parse_clock(value: str) -> tuple[int, int]:
+    match = _CLOCK_RE.match(value.strip())
+    if match is None:
+        message = f"Invalid clock time '{value}'."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    hours, minutes, _ = match.groups()
+    return int(hours), int(minutes)
+
+
+def _resolve_relative(value: str) -> datetime.datetime:
+    sign, amount, unit = _RELATIVE_RE.match(value).groups()  # type: ignore[union-attr]
+    delta = datetime.timedelta(hours=int(amount)) if unit == "h" else datetime.timedelta(minutes=int(amount))
+    if sign == "-":
+        delta = -delta
+    return datetime.datetime.now(datetime.UTC) + delta
+
+
+def _resolve_absolute(value: str) -> datetime.datetime:
+    try:
+        parsed = datetime.datetime.fromisoformat(value)
+    except ValueError as exc:
+        message = f"Invalid instant '{value}'."
+        raise CliError(message, exit_code=ExitCode.USAGE) from exc
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=datetime.UTC)
+    return parsed.astimezone(datetime.UTC)
+
+
+__all__ = ["parse_duration", "parse_instant"]

clockify_unofficial_cli/services/resolve.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Final
+
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from collections.abc import Iterable
+
+    from clockify import ProjectId
+
+    from clockify_unofficial_cli.runtime.context import AppContext
+
+
+_HEX_CHARS: Final[frozenset[str]] = frozenset("0123456789abcdef")
+_ID_LENGTH: Final = 24
+
+
+def _looks_like_id(term: str) -> bool:
+    return len(term) == _ID_LENGTH and all(character in _HEX_CHARS for character in term.lower())
+
+
+def _render_candidates(candidates: Iterable[str]) -> str:
+    rendered = ", ".join(candidates)
+    return f"candidates: {rendered}"
+
+
+# Pattern shared by every resolve_* helper: pass a term that is already an ID,
+# an exact case-insensitive name match, or surface a clear error.
+@dataclass(frozen=True, slots=True)
+class Candidate:
+    id: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class _Resolver:
+    candidates: list[Candidate]
+    noun: str
+
+    def resolve(self, term: str) -> str:
+        if _looks_like_id(term):
+            return term
+        lowered = term.casefold()
+        matches = [candidate for candidate in self.candidates if candidate.name.casefold() == lowered]
+        if len(matches) == 1:
+            return matches[0].id
+        if not matches:
+            message = f"Unknown {self.noun} '{term}'."
+            raise CliError(message, exit_code=ExitCode.NOT_FOUND)
+        ids = [candidate.id for candidate in matches]
+        message = f"Ambiguous {self.noun} '{term}'; {_render_candidates(ids)}."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+
+
+def _candidate_ids_from(items: Iterable[Any], *, name: Callable[[Any], str]) -> list[Candidate]:
+    return [Candidate(id=str(item.id), name=name(item)) for item in items]
+
+
+def resolve(term: str, candidates: list[Candidate], *, noun: str) -> str:
+    return _Resolver(candidates=candidates, noun=noun).resolve(term)
+
+
+def resolve_client(app_context: AppContext, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(workspace.clients.list(), name=lambda item: item.name)
+    return resolve(term, candidates, noun="client")
+
+
+def resolve_project(app_context: AppContext, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(workspace.projects.list(), name=lambda item: item.name)
+    return resolve(term, candidates, noun="project")
+
+
+def resolve_tag(app_context: AppContext, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(workspace.tags.list(), name=lambda item: item.name)
+    return resolve(term, candidates, noun="tag")
+
+
+def resolve_custom_field(app_context: AppContext, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(workspace.custom_fields.list(), name=lambda item: item.name)
+    return resolve(term, candidates, noun="custom field")
+
+
+def resolve_group(app_context: AppContext, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(workspace.user_groups.list(), name=lambda item: item.name)
+    return resolve(term, candidates, noun="group")
+
+
+def resolve_task(app_context: AppContext, project_id: ProjectId, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(workspace.tasks.list(project_id), name=lambda item: item.name)
+    return resolve(term, candidates, noun="task")
+
+
+def resolve_user(app_context: AppContext, term: str) -> str:
+    workspace = app_context.workspace()
+    candidates = _candidate_ids_from(
+        workspace.users.list(),
+        name=lambda item: item.email or item.name,
+    )
+    by_name = [
+        Candidate(id=str(item.id), name=item.name) for item in workspace.users.list() if item.email != item.name
+    ]
+    candidates.extend(by_name)
+    return resolve(term, candidates, noun="user")
+
+
+__all__ = [
+    "Candidate",
+    "resolve",
+    "resolve_client",
+    "resolve_custom_field",
+    "resolve_group",
+    "resolve_project",
+    "resolve_tag",
+    "resolve_task",
+    "resolve_user",
+]

clockify_unofficial_cli/services/timer.py

@@ -0,0 +1,126 @@
+import datetime
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from clockify import TimeEntryCreate
+from clockify import TimeEntryFilter
+
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+from clockify_unofficial_cli.services.parsing import parse_duration
+from clockify_unofficial_cli.services.parsing import parse_instant
+
+if TYPE_CHECKING:
+    from clockify import ProjectId
+    from clockify import TagId
+    from clockify import TaskId
+
+    from clockify_unofficial_cli.runtime.context import AppContext
+
+
+# Per-invocation bundle so the timer service can build a Clockify payload without
+# growing a long positional argument list every time a new flag appears.
+@dataclass(frozen=True, slots=True)
+class TimerRequest:
+    description: str | None
+    project_id: ProjectId | None
+    task_id: TaskId | None
+    tag_ids: tuple[TagId, ...]
+    billable: bool
+    start: datetime.datetime | None
+    end: datetime.datetime | None
+    duration: datetime.timedelta | None
+
+
+def _now() -> datetime.datetime:
+    return datetime.datetime.now(datetime.UTC)
+
+
+def start_timer(app_context: AppContext, request: TimerRequest) -> object:
+    resolved_start = request.start if request.start is not None else _now()
+    payload = TimeEntryCreate(
+        start=resolved_start,
+        end=request.end,
+        billable=request.billable or None,
+        description=request.description,
+        project_id=request.project_id,
+        task_id=request.task_id,
+        tag_ids=list(request.tag_ids) if request.tag_ids else None,
+    )
+    return app_context.workspace().time_entries.start(app_context.user_id(), payload)
+
+
+def stop_timer(app_context: AppContext, *, end: datetime.datetime | None) -> object:
+    return app_context.workspace().time_entries.stop(app_context.user_id(), end=end)
+
+
+def running_entry(app_context: AppContext) -> object | None:
+    entries = list(
+        app_context.workspace().time_entries.list(
+            app_context.user_id(),
+            entry_filter=TimeEntryFilter(in_progress=True),
+        )
+    )
+    return entries[0] if entries else None
+
+
+@dataclass(frozen=True, slots=True)
+class LogRequest:
+    description: str | None
+    project_id: ProjectId | None
+    task_id: TaskId | None
+    tag_ids: tuple[TagId, ...]
+    billable: bool
+    start: datetime.datetime | None
+    end: datetime.datetime | None
+    duration: datetime.timedelta | None
+
+
+def log_entry(
+    app_context: AppContext,
+    request: LogRequest,
+) -> object:
+    if request.start is not None and request.end is not None and request.duration is None:
+        resolved_start, resolved_end = request.start, request.end
+    elif request.start is not None and request.duration is not None and request.end is None:
+        resolved_start, resolved_end = request.start, request.start + request.duration
+    elif request.end is not None and request.duration is not None and request.start is None:
+        resolved_start, resolved_end = request.end - request.duration, request.end
+    elif request.duration is not None and request.start is None and request.end is None:
+        resolved_start, resolved_end = _now() - request.duration, _now()
+    else:
+        message = "`log` needs --from/--to or --duration (exactly one pairing)."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    payload = TimeEntryCreate(
+        start=resolved_start,
+        end=resolved_end,
+        billable=request.billable or None,
+        description=request.description,
+        project_id=request.project_id,
+        task_id=request.task_id,
+        tag_ids=list(request.tag_ids) if request.tag_ids else None,
+    )
+    return app_context.workspace().time_entries.create(payload)
+
+
+def parse_optional_duration(value: str | None) -> datetime.timedelta | None:
+    if value is None:
+        return None
+    return parse_duration(value)
+
+
+def parse_optional_instant(value: str | None) -> datetime.datetime | None:
+    if value is None:
+        return None
+    return parse_instant(value)
+
+
+__all__ = [
+    "TimerRequest",
+    "log_entry",
+    "parse_optional_duration",
+    "parse_optional_instant",
+    "running_entry",
+    "start_timer",
+    "stop_timer",
+]