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

clockify_unofficial_cli/__init__.py

@@ -0,0 +1,3 @@
+from clockify_unofficial_cli._version import __version__
+
+__all__ = ["__version__"]

clockify_unofficial_cli/__main__.py

@@ -0,0 +1,3 @@
+from clockify_unofficial_cli.main import run
+
+run()

clockify_unofficial_cli/_version.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("clockify-unofficial-cli")

clockify_unofficial_cli/auth/credentials.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+from typing import Literal
+from typing import Protocol
+
+_VISIBLE_SUFFIX: Final = 4
+
+
+class CredentialSource(StrEnum):
+    ENVIRONMENT = "environment"
+    KEYRING = "keyring"
+    FILE = "file"
+
+
+# Clockify only offers API keys (no OAuth2). The tagged encoding leaves room for another
+# credential kind without migrating what is already stored.
+@dataclass(frozen=True, slots=True)
+class ApiKeyCredential:
+    api_key: str
+    kind: Literal["api_key"] = "api_key"
+
+    def masked(self) -> str:
+        if len(self.api_key) <= _VISIBLE_SUFFIX:
+            return "*" * len(self.api_key)
+        return "*" * 8 + self.api_key[-_VISIBLE_SUFFIX:]
+
+
+type Credential = ApiKeyCredential  # pylint: disable=gajaguar-module-const-naming
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCredential:
+    credential: Credential
+    source: CredentialSource
+
+
+def encode(credential: Credential) -> str:
+    return json.dumps({"kind": credential.kind, "api_key": credential.api_key})
+
+
+def decode(raw: str) -> Credential | None:
+    try:
+        payload: object = json.loads(raw)
+    except ValueError:
+        return None
+    if not isinstance(payload, dict) or payload.get("kind") != "api_key":
+        return None
+    api_key = payload.get("api_key")
+    if not isinstance(api_key, str) or not api_key:
+        return None
+    return ApiKeyCredential(api_key=api_key)
+
+
+class CredentialStore(Protocol):
+    @property
+    def source(self) -> CredentialSource: ...
+
+    def get(self, profile: str) -> Credential | None: ...
+
+
+class WritableCredentialStore(CredentialStore, Protocol):
+    def available(self) -> bool: ...
+
+    def set(self, profile: str, credential: Credential) -> None: ...
+
+    def delete(self, profile: str) -> bool: ...

clockify_unofficial_cli/auth/env_store.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clockify.config import API_KEY_ENV_VAR
+
+from clockify_unofficial_cli.auth.credentials import ApiKeyCredential
+from clockify_unofficial_cli.auth.credentials import CredentialSource
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+# The environment key is profile-agnostic: it overrides whatever profile is selected, for CI.
+class EnvCredentialStore:
+    def __init__(self, environ: Mapping[str, str]) -> None:
+        self._environ = environ
+
+    @property
+    def source(self) -> CredentialSource:
+        return CredentialSource.ENVIRONMENT
+
+    def get(self, profile: str) -> ApiKeyCredential | None:
+        del profile
+        api_key = self._environ.get(API_KEY_ENV_VAR)
+        return ApiKeyCredential(api_key=api_key) if api_key else None

clockify_unofficial_cli/auth/file_store.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clockify_unofficial_cli.auth.credentials import CredentialSource
+from clockify_unofficial_cli.auth.credentials import decode
+from clockify_unofficial_cli.auth.credentials import encode
+from clockify_unofficial_cli.config.store import read_toml
+from clockify_unofficial_cli.config.store import write_private_toml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from clockify_unofficial_cli.auth.credentials import Credential
+
+
+# Plaintext fallback for hosts without a keyring backend; only written on explicit opt-in.
+class FileCredentialStore:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    @property
+    def source(self) -> CredentialSource:
+        return CredentialSource.FILE
+
+    @staticmethod
+    def available() -> bool:
+        return True
+
+    def get(self, profile: str) -> Credential | None:
+        raw = self._entries().get(profile)
+        return decode(raw) if isinstance(raw, str) else None
+
+    def set(self, profile: str, credential: Credential) -> None:
+        entries = self._entries()
+        entries[profile] = encode(credential)
+        write_private_toml(self.path, {"profiles": entries})
+
+    def delete(self, profile: str) -> bool:
+        entries = self._entries()
+        if profile not in entries:
+            return False
+        del entries[profile]
+        write_private_toml(self.path, {"profiles": entries})
+        return True
+
+    def _entries(self) -> dict[str, object]:
+        profiles = read_toml(self.path).get("profiles")
+        return dict(profiles) if isinstance(profiles, dict) else {}

clockify_unofficial_cli/auth/keyring_store.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Final
+
+import keyring
+from keyring.backends.fail import Keyring as FailKeyring
+from keyring.errors import KeyringError
+from keyring.errors import PasswordDeleteError
+
+from clockify_unofficial_cli.auth.credentials import CredentialSource
+from clockify_unofficial_cli.auth.credentials import decode
+from clockify_unofficial_cli.auth.credentials import encode
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+if TYPE_CHECKING:
+    from clockify_unofficial_cli.auth.credentials import Credential
+
+SERVICE_NAME: Final = "clockify-cli"
+
+
+class KeyringCredentialStore:
+    def __init__(self, service: str = SERVICE_NAME) -> None:
+        self._service = service
+
+    @property
+    def source(self) -> CredentialSource:
+        return CredentialSource.KEYRING
+
+    @staticmethod
+    def available() -> bool:
+        return not isinstance(keyring.get_keyring(), FailKeyring)
+
+    def get(self, profile: str) -> Credential | None:
+        if not self.available():
+            return None
+        try:
+            raw = keyring.get_password(self._service, profile)
+        except KeyringError:
+            return None
+        return decode(raw) if raw else None
+
+    def set(self, profile: str, credential: Credential) -> None:
+        try:
+            keyring.set_password(self._service, profile, encode(credential))
+        except KeyringError as error:
+            message = f"Could not write to the system keyring: {error}"
+            raise CliError(
+                message,
+                exit_code=ExitCode.CONFIGURATION,
+                hint="Retry with --insecure-storage to use a 0600 file instead.",
+            ) from error
+
+    def delete(self, profile: str) -> bool:
+        if not self.available():
+            return False
+        try:
+            keyring.delete_password(self._service, profile)
+        except PasswordDeleteError:
+            return False
+        return True

clockify_unofficial_cli/auth/resolver.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from clockify_unofficial_cli.auth.credentials import ResolvedCredential
+
+if TYPE_CHECKING:
+    from clockify_unofficial_cli.auth.credentials import CredentialStore
+    from clockify_unofficial_cli.auth.credentials import WritableCredentialStore
+    from clockify_unofficial_cli.auth.env_store import EnvCredentialStore
+    from clockify_unofficial_cli.auth.file_store import FileCredentialStore
+    from clockify_unofficial_cli.auth.keyring_store import KeyringCredentialStore
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialStores:
+    environment: EnvCredentialStore
+    keyring: KeyringCredentialStore
+    file: FileCredentialStore
+
+    # Precedence order: the first store holding a credential for the profile wins.
+    def chain(self) -> tuple[CredentialStore, ...]:
+        return (self.environment, self.keyring, self.file)
+
+    def writable(self) -> tuple[WritableCredentialStore, ...]:
+        return (self.keyring, self.file)
+
+    def resolve(self, profile: str) -> ResolvedCredential | None:
+        for store in self.chain():
+            credential = store.get(profile)
+            if credential is not None:
+                return ResolvedCredential(credential=credential, source=store.source)
+        return None

clockify_unofficial_cli/commands/auth.py

@@ -0,0 +1,153 @@
+import sys
+from typing import TYPE_CHECKING
+from typing import Annotated
+from typing import Final
+
+import typer
+from clockify import Region
+
+from clockify_unofficial_cli.auth.credentials import ApiKeyCredential
+from clockify_unofficial_cli.config.settings import Profile
+from clockify_unofficial_cli.output.columns import AUTH_STATUS
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.runtime.client_factory import ClientRequest
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+if TYPE_CHECKING:
+    from clockify import User
+
+    from clockify_unofficial_cli.auth.credentials import WritableCredentialStore
+    from clockify_unofficial_cli.auth.resolver import CredentialStores
+    from clockify_unofficial_cli.runtime.context import AppContext
+
+APP: Final = typer.Typer(help="Log in, inspect, and remove Clockify credentials.", no_args_is_help=True)
+
+
+def _read_api_key(*, with_token: bool) -> str:
+    # No --api-key flag on purpose: a key passed as an argument ends up in shell history.
+    raw = sys.stdin.read() if with_token else typer.prompt("Clockify API key", hide_input=True, err=True)
+    api_key = str(raw).strip()
+    if not api_key:
+        message = "The API key is empty."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    return api_key
+
+
+def _select_store(stores: CredentialStores, *, insecure_storage: bool) -> WritableCredentialStore:
+    if insecure_storage:
+        return stores.file
+    if stores.keyring.available():
+        return stores.keyring
+    message = "No system keyring backend is available."
+    raise CliError(
+        message,
+        exit_code=ExitCode.CONFIGURATION,
+        hint="Retry with --insecure-storage, or set CLOCKIFY_API_KEY in the environment.",
+    )
+
+
+def _save_profile(app_context: AppContext, user: User, region: Region) -> Profile:
+    options = app_context.options
+    store = app_context.services.settings
+    workspace_id = options.workspace_id or user.active_workspace or user.default_workspace
+    profile = Profile(region=region, workspace_id=workspace_id, user_id=user.id, email=user.email)
+    settings = store.load()
+    if not settings.profiles:
+        settings = settings.model_copy(update={"default_profile": options.profile_name})
+    store.save(settings.with_profile(options.profile_name, profile))
+    return profile
+
+
+@APP.command(help="Validate an API key and store it for the selected profile.")
+@handle_errors
+def login(
+    ctx: typer.Context,
+    *,
+    region: Annotated[
+        Region | None,
+        typer.Option("--region", help="Clockify data region; defaults to the profile's, else GLOBAL."),
+    ] = None,
+    with_token: Annotated[bool, typer.Option("--with-token", help="Read the API key from standard input.")] = False,
+    insecure_storage: Annotated[
+        bool,
+        typer.Option("--insecure-storage", help="Store the key in a 0600 plaintext file instead of the keyring."),
+    ] = False,
+) -> None:
+    app_context = get_app_context(ctx)
+    stores = app_context.services.credentials
+    profile_name = app_context.options.profile_name
+    credential = ApiKeyCredential(api_key=_read_api_key(with_token=with_token))
+    resolved_region = region or app_context.options.profile.region
+
+    with app_context.services.clients(
+        ClientRequest(credential=credential, region=resolved_region, verbose=app_context.options.verbose)
+    ) as client:
+        user = client.user.me()
+
+    store = _select_store(stores, insecure_storage=insecure_storage)
+    store.set(profile_name, credential)
+    for other in stores.writable():
+        if other is not store:
+            other.delete(profile_name)
+    profile = _save_profile(app_context, user, resolved_region)
+
+    app_context.notify(f"Logged in to profile '{profile_name}' as {user.email} ({store.source}).")
+    record = {
+        "profile": profile_name,
+        "name": user.name,
+        "email": user.email,
+        "workspaceId": profile.workspace_id,
+        "region": profile.region,
+        "source": store.source,
+        "apiKey": credential.masked(),
+    }
+    app_context.render(single(record, AUTH_STATUS))
+
+
+@APP.command(help="Show the active credential and the user it belongs to.")
+@handle_errors
+def status(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    resolved = app_context.credential()
+    user = app_context.client().user.me()
+    record = {
+        "profile": app_context.options.profile_name,
+        "name": user.name,
+        "email": user.email,
+        "workspaceId": app_context.options.workspace_id or user.active_workspace,
+        "region": app_context.options.profile.region,
+        "source": resolved.source,
+        "apiKey": resolved.credential.masked(),
+    }
+    app_context.render(single(record, AUTH_STATUS))
+
+
+@APP.command(help="Remove the stored credential and profile.")
+@handle_errors
+def logout(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    services = app_context.services
+    profile_name = app_context.options.profile_name
+
+    removed = [store.source for store in services.credentials.writable() if store.delete(profile_name)]
+    settings = services.settings.load()
+    had_profile = profile_name in settings.profiles
+    if had_profile:
+        services.settings.save(settings.without_profile(profile_name))
+    if not removed and not had_profile:
+        message = f"No stored credentials for profile '{profile_name}'."
+        raise CliError(message, exit_code=ExitCode.CONFIGURATION)
+
+    app_context.notify(f"Logged out of profile '{profile_name}'.")
+    if services.credentials.environment.get(profile_name) is not None:
+        app_context.notify("CLOCKIFY_API_KEY is still set in the environment and will keep being used.")
+
+
+@APP.command(help="Print the raw API key of the active credential.")
+@handle_errors
+def token(ctx: typer.Context) -> None:
+    resolved = get_app_context(ctx).credential()
+    typer.echo(resolved.credential.api_key)

clockify_unofficial_cli/commands/client.py

@@ -0,0 +1,116 @@
+import dataclasses
+from dataclasses import dataclass
+from typing import Annotated
+from typing import Final
+
+import typer
+from clockify import ClientCreate
+from clockify import ClientUpdate
+
+from clockify_unofficial_cli.output.columns import CLIENTS
+from clockify_unofficial_cli.output.renderer import many
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.params import options_from
+from clockify_unofficial_cli.runtime.prompts import confirm
+from clockify_unofficial_cli.services.listing import list_from_options
+from clockify_unofficial_cli.services.resolve import resolve_client
+
+APP: Final = typer.Typer(help="Manage workspace clients.", no_args_is_help=True)
+
+
+@APP.command(name="list", help="List every client in the active workspace.")
+@handle_errors
+def list_clients(
+    ctx: typer.Context,
+    *,
+    limit: Annotated[
+        int | None,
+        typer.Option("--limit", help="Stop after N clients; incompatible with --page/--page-size."),
+    ] = None,
+    page: Annotated[
+        int | None,
+        typer.Option("--page", help="1-based page number when paging through results."),
+    ] = None,
+    page_size: Annotated[
+        int | None,
+        typer.Option("--page-size", help="Page size when paging through results."),
+    ] = None,
+) -> None:
+    app_context = get_app_context(ctx)
+    workspace = app_context.workspace()
+    clients = list_from_options(workspace.clients.list, workspace.clients.list_page, limit, page, page_size)
+    app_context.render(many(clients, CLIENTS))
+
+
+@APP.command(help="Show a client by ID or exact name.")
+@handle_errors
+def get(ctx: typer.Context, term: Annotated[str, typer.Argument(help="Client ID or exact name.")]) -> None:
+    app_context = get_app_context(ctx)
+    client_id = resolve_client(app_context, term)
+    client = app_context.workspace().clients.get(client_id)
+    app_context.render(single(client, CLIENTS))
+
+
+@dataclass(frozen=True, slots=True)
+class _CreateArgs:
+    name: Annotated[str, typer.Option("--name", help="Client display name.")]
+    email: Annotated[str | None, typer.Option("--email", help="Contact email.")] = None
+    address: Annotated[str | None, typer.Option("--address", help="Postal address.")] = None
+    note: Annotated[str | None, typer.Option("--note", help="Free-form note.")] = None
+
+
+@APP.command(help="Create a new client.")
+@handle_errors
+@options_from(_CreateArgs)
+def create(ctx: typer.Context, args: _CreateArgs) -> None:
+    app_context = get_app_context(ctx)
+    payload = ClientCreate(**{k: v for k, v in dataclasses.asdict(args).items() if v is not None})
+    client = app_context.workspace().clients.create(payload)
+    app_context.render(single(client, CLIENTS))
+
+
+@dataclass(frozen=True, slots=True)
+class _UpdateArgs:
+    term: Annotated[str, typer.Argument(help="Client ID or exact name.")]
+    name: Annotated[str | None, typer.Option("--name", help="New client display name.")] = None
+    email: Annotated[str | None, typer.Option("--email", help="New contact email.")] = None
+    address: Annotated[str | None, typer.Option("--address", help="New postal address.")] = None
+    note: Annotated[str | None, typer.Option("--note", help="New free-form note.")] = None
+    archived: Annotated[
+        bool | None,
+        typer.Option(
+            "--archived/--no-archived",
+            help="Archive or restore the client; omit the flag to leave the field untouched.",
+        ),
+    ] = None
+
+
+@APP.command(help="Update an existing client.")
+@handle_errors
+@options_from(_UpdateArgs)
+def update(ctx: typer.Context, args: _UpdateArgs) -> None:
+    app_context = get_app_context(ctx)
+    client_id = resolve_client(app_context, args.term)
+    changes = {k: v for k, v in dataclasses.asdict(args).items() if v is not None and k != "term"}
+    client = app_context.workspace().clients.update(client_id, ClientUpdate(**changes))
+    app_context.render(single(client, CLIENTS))
+
+
+@APP.command(help="Delete a client.")
+@handle_errors
+def delete(
+    ctx: typer.Context,
+    term: Annotated[str, typer.Argument(help="Client ID or exact name.")],
+    *,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the interactive confirmation prompt."),
+    ] = False,
+) -> None:
+    app_context = get_app_context(ctx)
+    confirm(f"Delete client '{term}'", assume_yes=yes)
+    client_id = resolve_client(app_context, term)
+    app_context.workspace().clients.delete(client_id)
+    app_context.notify(f"Deleted client '{client_id}'.")

clockify_unofficial_cli/commands/config.py

@@ -0,0 +1,50 @@
+from typing import Annotated
+from typing import Final
+
+import typer
+
+from clockify_unofficial_cli.output.columns import PROFILES
+from clockify_unofficial_cli.output.renderer import Dataset
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+
+APP: Final = typer.Typer(help="Inspect and edit local CLI configuration.", no_args_is_help=True)
+
+
+@APP.command(help="Print the settings file location.")
+@handle_errors
+def path(ctx: typer.Context) -> None:
+    typer.echo(str(get_app_context(ctx).services.settings.path))
+
+
+@APP.command(name="list", help="List configured profiles.")
+@handle_errors
+def list_profiles(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    settings = app_context.services.settings.load()
+    records = [
+        {
+            "name": name,
+            "default": name == settings.default_profile,
+            "region": profile.region,
+            "workspaceId": profile.workspace_id,
+            "email": profile.email,
+        }
+        for name, profile in sorted(settings.profiles.items())
+    ]
+    app_context.render(Dataset(records=records, columns=PROFILES))
+
+
+@APP.command(help="Set the default profile.")
+@handle_errors
+def use(ctx: typer.Context, name: Annotated[str, typer.Argument(help="Name of an existing profile.")]) -> None:
+    app_context = get_app_context(ctx)
+    store = app_context.services.settings
+    settings = store.load()
+    if name not in settings.profiles:
+        message = f"Unknown profile '{name}'."
+        raise CliError(message, exit_code=ExitCode.CONFIGURATION, hint="Run `clockify config list`.")
+    store.save(settings.model_copy(update={"default_profile": name}))
+    app_context.notify(f"Default profile set to '{name}'.")