crowdtime-cli 0.13.0__tar.gz → 0.15.0__tar.gz

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/.gitignore

@@ -70,3 +70,4 @@ pypi_deployment.md
 sentry-workflow.md
 linear-workflow.md
 seeds-mentores.md
+_samples/

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.13.0
+Version: 0.15.0
 Summary: AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest
 Project-URL: Homepage, https://crowdtime.lat
 Project-URL: Documentation, https://crowdtime.lat/docs
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Office/Business
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: click>=8.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: humanize>=4.0
 Requires-Dist: keyring>=25.0
@@ -29,7 +30,7 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dateutil>=2.9
 Requires-Dist: rich>=13.0
 Requires-Dist: tomlkit>=0.12.0
-Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: typer>=0.12.0
 Description-Content-Type: text/markdown
 
 # CrowdTime CLI

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.13.0"
+version = "0.15.0"
 description = "AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest"
 readme = "README.md"
 license = {text = "Proprietary"}
@@ -21,7 +21,14 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "typer[all]>=0.12.0",
+    # Not typer[all]: that extra no longer exists (typer warns on every
+    # install), and what it used to pull in — rich, shellingham — typer
+    # requires outright now.
+    "typer>=0.12.0",
+    # Imported directly by commands/org_cmd.py. It used to arrive through
+    # typer and stopped when typer 0.27 dropped it, which broke `ct` on
+    # every fresh install: importing a package means declaring it.
+    "click>=8.0",
     "rich>=13.0",
     "httpx>=0.27.0",
     "pydantic>=2.0",
@@ -42,7 +49,10 @@ crowdtime = "crowdtime_cli.main:_original_main"
 ct = "crowdtime_cli.main:_original_main"
 
 [build-system]
-requires = ["hatchling"]
+# Pinned below 1.28: from there hatchling stamps Metadata-Version 2.5,
+# which twine refuses to upload ("not a valid metadata version"). 0.14.0
+# shipped 2.4. Lift once the packaging toolchain accepts 2.5.
+requires = ["hatchling<1.28"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/__init__.py

@@ -1,3 +1,3 @@
 """CrowdTime CLI - AI-powered time tracking from the command line."""
 
-__version__ = "0.13.0"
+__version__ = "0.15.0"

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/commands/billing_cmd.py

@@ -143,6 +143,8 @@ def status(
     table.add_column("Value")
 
     table.add_row("Status", f"[{color}]{label}[/{color}]")
+    if data.get("billing_exempt"):
+        table.add_row("Exempt", "[green]Billing exempt — full access, not billed[/green]")
     table.add_row("Plan", PLAN_LABELS.get(plan, plan.capitalize()))
     table.add_row("Seats", str(seat_count))
     table.add_row("Base", f"{format_currency(base_dollars)}/mo")

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/commands/invoice_cmd.py

@@ -89,6 +89,7 @@ def _resolve_payment_terms(value: str) -> int | None:
     """
     mapping = {
         "receipt": 0,
+        "net7": 7,
         "net15": 15,
         "net30": 30,
     }
@@ -580,6 +581,14 @@ def create_invoice(
         None, "--period", "-P",
         help="Preset period: last-week, last-2-weeks, last-month, this-month.",
     ),
+    projects: Optional[list[str]] = typer.Option(
+        None, "--project", "-p",
+        help=(
+            "Limit the invoice to specific project ID(s). Repeat for multiple. "
+            "Required to bill a fixed-fee project, which is never included "
+            "in a client-wide invoice."
+        ),
+    ),
     group_by: Optional[str] = typer.Option(
         None, "--group-by", "-g", help="Group line items by: project, task, user, date, none."
     ),
@@ -590,7 +599,17 @@ def create_invoice(
     terms: Optional[str] = typer.Option(None, "--terms", help="Payment terms text."),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
-        help="Payment terms: receipt, net15, net30, or number of days.",
+        help=(
+            "Payment terms: receipt, net15, net30, or number of days. "
+            "Omit to use the client's configured terms, then the org default."
+        ),
+    ),
+    issue_date: Optional[str] = typer.Option(
+        None, "--issue-date", help="Invoice date. Default: today."
+    ),
+    due_date: Optional[str] = typer.Option(
+        None, "--due-date",
+        help="Explicit due date. Default: issue date + payment terms.",
     ),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
@@ -600,11 +619,17 @@ def create_invoice(
     the specified date range. Use --period for preset ranges or
     --from/--to for custom dates.
 
+    The due date is derived from the invoice date, never from the end of the
+    billing period — invoicing a period weeks after it closed would otherwise
+    produce an invoice that is already overdue.
+
     Examples:
         ct invoice create --client <id> --from 2026-03-01 --to 2026-03-31
         ct invoice create --client <id> --period last-month --group-by project
         ct invoice create --client <id> --period last-2-weeks --payment-terms net30
         ct invoice create --client <id> --from monday --to friday --payment-terms 15
+        ct invoice create --client <id> --period last-month --due-date 2026-09-15
+        ct invoice create --client <id> --period last-month --project <fixed-project-id>
     """
     # Resolve period dates
     if period:
@@ -638,6 +663,20 @@ def create_invoice(
             )
             raise typer.Exit(1)
 
+    # Resolve explicit invoice dates
+    try:
+        issue_date_str = format_date(parse_date(issue_date)) if issue_date else None
+        due_date_str = format_date(parse_date(due_date)) if due_date else None
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
+
+    if issue_date_str and due_date_str and due_date_str < issue_date_str:
+        format_error(
+            f"--due-date {due_date_str} is before --issue-date {issue_date_str}."
+        )
+        raise typer.Exit(1)
+
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
     payload: dict = {
@@ -645,6 +684,12 @@ def create_invoice(
         "date_from": start,
         "date_to": end,
     }
+    if issue_date_str:
+        payload["issue_date"] = issue_date_str
+    if due_date_str:
+        payload["due_date"] = due_date_str
+    if projects:
+        payload["project_ids"] = list(projects)
     if group_by:
         payload["group_by"] = group_by
     if tax_rate is not None:
@@ -796,7 +841,7 @@ def update_invoice(
     tax_rate: Optional[float] = typer.Option(None, "--tax-rate", help="Tax rate percentage (e.g. 21 for 21%)."),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
-        help="Payment terms: receipt, net15, net30, or number of days.",
+        help="Payment terms: receipt, net7, net15, net30, or number of days.",
     ),
     from_name: Optional[str] = typer.Option(None, "--from-name", help="Issuer/sender name."),
     from_email: Optional[str] = typer.Option(None, "--from-email", help="Issuer/sender email."),
@@ -906,6 +951,10 @@ def send_invoice(
         None, "--cc",
         help="Contact ID(s) to CC. Repeat for multiple.",
     ),
+    keep_dates: bool = typer.Option(
+        False, "--keep-dates",
+        help="Send with the drafted dates as-is instead of re-stamping a stale issue date to today.",
+    ),
     force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
@@ -915,10 +964,15 @@ def send_invoice(
     Use --to to specify contact(s) or it defaults to the client's primary contact.
     This action cannot be undone (use void instead).
 
+    If the draft's issue date has fallen into the past, it is re-stamped to
+    today and the due date shifts by the same number of days, so the invoice
+    doesn't arrive already overdue. Pass --keep-dates to send it as drafted.
+
     Examples:
         ct invoice send <invoice-id>
         ct invoice send <invoice-id> --to <contact-id>
         ct invoice send <invoice-id> --to <contact-id-1> --to <contact-id-2> --cc <contact-id-3>
+        ct invoice send <invoice-id> --keep-dates
         ct invoice send <invoice-id> --force
     """
     if not force:
@@ -933,6 +987,8 @@ def send_invoice(
         payload["contact_ids"] = to
     if cc:
         payload["cc_contact_ids"] = cc
+    if keep_dates:
+        payload["keep_dates"] = True
 
     try:
         data = client.post(f"/invoices/{invoice_id}/send/", data=payload if payload else None)
@@ -1305,6 +1361,10 @@ def show_recurring(
             console.print(f"  Currency:        {data.get('currency', 'USD')}")
             console.print(f"  Payment Terms:   {data.get('payment_terms_days', 30)} days")
             console.print(f"  Next Run:        {data.get('next_run_date', '') or 'Not scheduled'}")
+            next_start = data.get("next_period_start")
+            next_end = data.get("next_period_end")
+            if next_start and next_end:
+                console.print(f"  Next Period:     {next_start} to {next_end}")
             console.print(f"  Last Run:        {data.get('last_run_date', '') or 'Never'}")
             console.print(f"  Total Generated: {data.get('total_generated', 0)}")
             console.print(f"  Auto-send:       {'Yes' if data.get('auto_send') else 'No'}")
@@ -1482,25 +1542,80 @@ def delete_recurring(
 @recurring_app.command("generate-now")
 def generate_now(
     template_id: str = typer.Argument(..., help="Recurring template ID."),
+    period_start: Optional[str] = typer.Option(
+        None, "--period-start", help="Start of the period to bill (YYYY-MM-DD)."
+    ),
+    period_end: Optional[str] = typer.Option(
+        None, "--period-end", help="End of the period to bill (YYYY-MM-DD)."
+    ),
+    issue_date: Optional[str] = typer.Option(
+        None, "--issue-date", help="Invoice date (YYYY-MM-DD). Defaults to today."
+    ),
+    allow_overlap: bool = typer.Option(
+        False, "--allow-overlap", help="Bill a period this template already invoiced."
+    ),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
     """Manually generate an invoice from a recurring template.
 
+    With no dates the template bills its scheduled period, dated today —
+    the same invoice the nightly job would raise, and it advances the
+    schedule. Naming a period bills that one instead as a one-off and
+    leaves the schedule untouched. The invoice date is separate from the
+    period: an invoice raised today can bill a period that closed months
+    ago (`ct invoice recurring show` prints both).
+
     Examples:
         ct invoice recurring generate-now <template-id>
+        ct invoice recurring generate-now <template-id> --period-start 2026-03-01 --period-end 2026-03-31
+        ct invoice recurring generate-now <template-id> --period-start 2026-03-01 --period-end 2026-03-31 --issue-date 2026-08-20
     """
+    if bool(period_start) != bool(period_end):
+        format_error("Give both --period-start and --period-end, or neither.")
+        raise typer.Exit(1)
+
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
+    payload: dict = {}
+    if period_start:
+        payload["period_start"] = period_start
+        payload["period_end"] = period_end
+    if issue_date:
+        payload["issue_date"] = issue_date
+    if allow_overlap:
+        payload["allow_overlap"] = True
+
     try:
-        data = client.post(f"/invoices/recurring-templates/{template_id}/generate-now/")
+        data = client.post(
+            f"/invoices/recurring-templates/{template_id}/generate-now/", data=payload
+        )
 
         if output_json:
             print_json(data)
         else:
+            invoice = data.get("invoice") or {}
             format_success(data.get("detail", "Invoice generated successfully."))
+            if invoice:
+                console.print(f"  Invoice: {invoice.get('invoice_number', '')}")
+                console.print(f"  ID:      {invoice.get('id', '')}")
+                console.print(
+                    f"  Period:  {invoice.get('period_start', '')} to {invoice.get('period_end', '')}"
+                )
+                console.print(f"  Issued:  {invoice.get('issue_date', '')}")
     except APIError as e:
         if e.status_code == 404:
             format_error(f"Recurring template '{template_id}' not found.")
+        elif e.status_code == 409:
+            # The period is already billed, or is about to be by the scheduled
+            # run. Fixed lines go out in full every run, so say what clashes.
+            format_error(e.message)
+            body = e.detail if isinstance(e.detail, dict) else {}
+            for inv in body.get("overlapping_invoices", []):
+                console.print(
+                    f"  {inv.get('invoice_number', '')} ({inv.get('status', '')}) "
+                    f"— {inv.get('period_start', '')} to {inv.get('period_end', '')}"
+                )
+            console.print("[dim]Re-run with --allow-overlap to bill it anyway.[/dim]")
         else:
             format_error(e.message)
         raise typer.Exit(1)

{crowdtime_cli-0.13.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/commands/projects_cmd.py

@@ -21,6 +21,44 @@ console = Console()
 
 BILLING_MODES = ["per_task", "per_person", "custom"]
 
+# WHAT the client is charged. Distinct from BILLING_MODES, which only decides
+# HOW an hourly rate is resolved and is irrelevant for fixed-fee work.
+BILLING_TYPES = ["time_and_materials", "fixed_fee"]
+# Friendly aliases so `--billing-type fixed` and `--billing-type t&m` work.
+BILLING_TYPE_ALIASES = {
+    "tm": "time_and_materials",
+    "t&m": "time_and_materials",
+    "time": "time_and_materials",
+    "hourly": "time_and_materials",
+    "time_and_materials": "time_and_materials",
+    "fixed": "fixed_fee",
+    "fixed_fee": "fixed_fee",
+    "fixedfee": "fixed_fee",
+}
+
+
+def _resolve_billing_type(value: str) -> str | None:
+    """Normalise a --billing-type value, or None if unrecognised."""
+    return BILLING_TYPE_ALIASES.get(value.strip().lower().replace("-", "_"))
+
+
+PAYMENT_TERMS_ALIASES = {"receipt": 0, "net7": 7, "net15": 15, "net30": 30}
+
+
+def _resolve_payment_terms_opt(value: str) -> int | None:
+    """Resolve a --payment-terms value to days, or None if unrecognised.
+
+    Accepts the same presets as the invoice commands plus a raw day count.
+    """
+    lower = value.strip().lower()
+    if lower in PAYMENT_TERMS_ALIASES:
+        return PAYMENT_TERMS_ALIASES[lower]
+    try:
+        days = int(lower)
+    except ValueError:
+        return None
+    return days if days >= 0 else None
+
 
 def _resolve_or_create_client(api_client: CrowdTimeClient, client_name: str) -> str:
     """Look up a client by name; create one if it doesn't exist. Returns the client UUID."""
@@ -101,7 +139,17 @@ def show(
             console.print(f"  Client:       {project.client_name or project.client or '-'}")
             console.print(f"  Status:       {project.status}")
             console.print(f"  Billable:     {'Yes' if project.is_billable else 'No'}")
-            console.print(f"  Billing Mode: {billing_labels.get(project.billing_mode, project.billing_mode)}")
+            if project.billing_type == "fixed_fee":
+                currency = data.get("currency", "USD")
+                fee = (
+                    format_currency(project.fixed_fee_amount, currency)
+                    if project.fixed_fee_amount is not None
+                    else "[red]not set[/red]"
+                )
+                console.print(f"  Billing:      Fixed Fee — {fee}")
+            else:
+                console.print("  Billing:      Time & Materials")
+                console.print(f"  Billing Mode: {billing_labels.get(project.billing_mode, project.billing_mode)}")
             if project.budget_type and project.budget_type != "none" and project.budget_amount:
                 currency = data.get("currency", "USD")
                 budget_label = f"{project.budget_amount}h" if project.budget_type == "hours" else format_currency(project.budget_amount, currency)
@@ -126,7 +174,22 @@ def create(
                                   help="Mark as billable."),
     billing_mode: Optional[str] = typer.Option(
         None, "--billing-mode", "-m",
-        help="Billing mode: per_task, per_person, custom.",
+        help="Rate resolution for time & materials work: per_task, per_person, custom.",
+    ),
+    billing_type: Optional[str] = typer.Option(
+        None, "--billing-type",
+        help="What the client is charged: time_and_materials (default) or fixed_fee.",
+    ),
+    fixed_fee: Optional[float] = typer.Option(
+        None, "--fixed-fee",
+        help="Agreed price billed instead of logged hours. Implies --billing-type fixed_fee.",
+    ),
+    payment_terms: Optional[str] = typer.Option(
+        None, "--payment-terms",
+        help=(
+            "Payment terms for this project: receipt, net7, net15, net30, or a "
+            "number of days. Omit to inherit the client/org default."
+        ),
     ),
     color: Optional[str] = typer.Option(None, "--color", help="Project color hex code (e.g. #FF5733)."),
     budget: Optional[float] = typer.Option(None, "--budget", help="Budget amount (hours or money depending on --budget-type)."),
@@ -137,13 +200,39 @@ def create(
     code: Optional[str] = typer.Option(None, "--code", help="Short project code."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Create a new project."""
+    """Create a new project.
+
+    Fixed-fee projects bill an agreed price instead of logged hours. That fee
+    is never billed automatically — only when the project is selected
+    explicitly on an invoice, or pulled in by a recurring template.
+    """
     api_client = CrowdTimeClient(require_auth=True, require_org=True)
 
     if billing_mode and billing_mode not in BILLING_MODES:
         format_error(f"Invalid billing mode. Choose from: {', '.join(BILLING_MODES)}")
         raise typer.Exit(1)
 
+    # --fixed-fee alone is enough to mean "this is a fixed-fee project".
+    resolved_billing_type = None
+    if billing_type:
+        resolved_billing_type = _resolve_billing_type(billing_type)
+        if resolved_billing_type is None:
+            format_error(f"Invalid billing type. Choose from: {', '.join(BILLING_TYPES)}")
+            raise typer.Exit(1)
+    elif fixed_fee is not None:
+        resolved_billing_type = "fixed_fee"
+
+    if resolved_billing_type == "fixed_fee":
+        if fixed_fee is None:
+            format_error("--fixed-fee is required for fixed-fee projects.")
+            raise typer.Exit(1)
+        if fixed_fee <= 0:
+            format_error("--fixed-fee must be greater than zero.")
+            raise typer.Exit(1)
+    elif fixed_fee is not None:
+        format_error("--fixed-fee only applies to fixed-fee projects.")
+        raise typer.Exit(1)
+
     budget_types = ["hours", "money", "none"]
     if budget_type and budget_type not in budget_types:
         format_error(f"Invalid budget type. Choose from: {', '.join(budget_types)}")
@@ -158,6 +247,19 @@ def create(
     payload: dict = {"name": name, "is_billable": billable}
     if billing_mode:
         payload["billing_mode"] = billing_mode
+    if resolved_billing_type:
+        payload["billing_type"] = resolved_billing_type
+    if fixed_fee is not None:
+        payload["fixed_fee_amount"] = fixed_fee
+    if payment_terms is not None:
+        resolved_terms = _resolve_payment_terms_opt(payment_terms)
+        if resolved_terms is None:
+            format_error(
+                f"Invalid --payment-terms: '{payment_terms}'. "
+                "Use: receipt, net7, net15, net30, or a non-negative number of days."
+            )
+            raise typer.Exit(1)
+        payload["payment_terms_days"] = resolved_terms
     if color:
         payload["color"] = color
     if budget is not None:
@@ -229,7 +331,19 @@ def update(
                                             help="Mark as billable or not."),
     billing_mode: Optional[str] = typer.Option(
         None, "--billing-mode", "-m",
-        help="Billing mode: per_task, per_person, custom.",
+        help="Rate resolution for time & materials work: per_task, per_person, custom.",
+    ),
+    billing_type: Optional[str] = typer.Option(
+        None, "--billing-type",
+        help="What the client is charged: time_and_materials or fixed_fee.",
+    ),
+    fixed_fee: Optional[float] = typer.Option(
+        None, "--fixed-fee",
+        help="Agreed price billed instead of logged hours.",
+    ),
+    payment_terms: Optional[str] = typer.Option(
+        None, "--payment-terms",
+        help="Payment terms: receipt, net7, net15, net30, or a number of days.",
     ),
     color: Optional[str] = typer.Option(None, "--color", help="Project color hex code (e.g. #FF5733)."),
     budget: Optional[float] = typer.Option(None, "--budget", help="Budget amount (hours or money depending on --budget-type)."),
@@ -273,6 +387,19 @@ def update(
         format_error(f"Invalid status. Choose from: {', '.join(valid_statuses)}")
         raise typer.Exit(1)
 
+    resolved_billing_type = None
+    if billing_type:
+        resolved_billing_type = _resolve_billing_type(billing_type)
+        if resolved_billing_type is None:
+            format_error(f"Invalid billing type. Choose from: {', '.join(BILLING_TYPES)}")
+            raise typer.Exit(1)
+    elif fixed_fee is not None:
+        resolved_billing_type = "fixed_fee"
+
+    if fixed_fee is not None and fixed_fee <= 0:
+        format_error("--fixed-fee must be greater than zero.")
+        raise typer.Exit(1)
+
     payload: dict = {}
     if name is not None:
         payload["name"] = name
@@ -280,6 +407,19 @@ def update(
         payload["is_billable"] = billable
     if billing_mode:
         payload["billing_mode"] = billing_mode
+    if resolved_billing_type:
+        payload["billing_type"] = resolved_billing_type
+    if fixed_fee is not None:
+        payload["fixed_fee_amount"] = fixed_fee
+    if payment_terms is not None:
+        resolved_terms = _resolve_payment_terms_opt(payment_terms)
+        if resolved_terms is None:
+            format_error(
+                f"Invalid --payment-terms: '{payment_terms}'. "
+                "Use: receipt, net7, net15, net30, or a non-negative number of days."
+            )
+            raise typer.Exit(1)
+        payload["payment_terms_days"] = resolved_terms
     if color:
         payload["color"] = color
     if budget is not None: