crowdtime-cli 0.21.1__tar.gz → 0.22.0__tar.gz

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.21.1
+Version: 0.22.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

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.21.1"
+version = "0.22.0"
 description = "AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest"
 readme = "README.md"
 license = {text = "Proprietary"}

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/__init__.py

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

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/commands/invoice_cmd.py

@@ -589,6 +589,14 @@ def create_invoice(
             "in a client-wide invoice."
         ),
     ),
+    payments: Optional[list[str]] = typer.Option(
+        None, "--payment",
+        help=(
+            "One-off fixed-fee payment ID(s) to bill (see `ct projects show`). "
+            "Repeat for multiple. Without it a selected one-off project bills "
+            "its next unbilled payment; each payment is billed only once."
+        ),
+    ),
     group_by: Optional[str] = typer.Option(
         None, "--group-by", "-g", help="Group line items by: project, task, user, date, none."
     ),
@@ -630,6 +638,7 @@ def create_invoice(
         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>
+        ct invoice create --client <id> --period last-month --project <fixed-project-id> --payment <payment-id>
     """
     # Resolve period dates
     if period:
@@ -690,6 +699,11 @@ def create_invoice(
         payload["due_date"] = due_date_str
     if projects:
         payload["project_ids"] = list(projects)
+    if payments:
+        if not projects:
+            format_error("--payment needs the fixed-fee project selected with --project.")
+            raise typer.Exit(1)
+        payload["milestone_ids"] = list(payments)
     if group_by:
         payload["group_by"] = group_by
     if tax_rate is not None:

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/commands/projects_cmd.py

@@ -42,6 +42,69 @@ def _resolve_billing_type(value: str) -> str | None:
     return BILLING_TYPE_ALIASES.get(value.strip().lower().replace("-", "_"))
 
 
+FEE_SCHEDULES = {"one-off": "one_off", "one_off": "one_off", "oneoff": "one_off",
+                 "recurring": "recurring"}
+FEE_FREQUENCIES = ["weekly", "biweekly", "monthly", "quarterly"]
+
+
+def _parse_payment(value: str) -> dict:
+    """Parse a --payment value: NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD."""
+    if "=" not in value:
+        raise ValueError(f"Invalid --payment '{value}'. Use NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD.")
+    name, rest = value.rsplit("=", 1)
+    amount, _, due = rest.partition("@")
+    try:
+        amount_dec = Decimal(amount.strip())
+    except Exception:
+        raise ValueError(f"Invalid amount in --payment '{value}'.")
+    if not name.strip() or amount_dec <= 0:
+        raise ValueError(f"Invalid --payment '{value}': needs a name and an amount above zero.")
+    return {"name": name.strip(), "amount": str(amount_dec), "due_date": due.strip() or None}
+
+
+def _fee_plan_payload(
+    fee_schedule: Optional[str],
+    fee_frequency: Optional[str],
+    payments: Optional[List[str]],
+    first_invoice: Optional[str],
+    existing: Optional[list[dict]] = None,
+) -> dict:
+    """Build the fixed-fee plan fields of a project payload (CRO-61).
+
+    On update, ``existing`` milestones keep their id when a --payment names
+    them, and payments already invoiced are always kept — the API refuses a
+    plan that drops or changes them.
+    """
+    payload: dict = {}
+    if fee_schedule is not None:
+        resolved = FEE_SCHEDULES.get(fee_schedule.strip().lower())
+        if resolved is None:
+            raise ValueError("Invalid --fee-schedule. Choose from: one-off, recurring.")
+        payload["fixed_fee_schedule"] = resolved
+    if fee_frequency is not None:
+        if fee_frequency not in FEE_FREQUENCIES:
+            raise ValueError(f"Invalid --fee-frequency. Choose from: {', '.join(FEE_FREQUENCIES)}.")
+        payload["fixed_fee_frequency"] = fee_frequency
+        payload.setdefault("fixed_fee_schedule", "recurring")
+    if first_invoice is not None:
+        payload["fixed_fee_first_invoice_date"] = first_invoice
+    if payments:
+        items = [_parse_payment(p) for p in payments]
+        by_name = {m["name"]: m for m in (existing or [])}
+        for item in items:
+            if item["name"] in by_name:
+                item["id"] = by_name[item["name"]]["id"]
+        named = {i["name"] for i in items}
+        billed = [
+            {"id": m["id"], "name": m["name"], "amount": m["amount"], "due_date": m.get("due_date")}
+            for m in (existing or [])
+            if m.get("invoice") and m["name"] not in named
+        ]
+        payload["fixed_fee_milestones"] = billed + items
+        payload.setdefault("fixed_fee_schedule", "one_off")
+    return payload
+
+
 PAYMENT_TERMS_ALIASES = {"receipt": 0, "net7": 7, "net15": 15, "net30": 30}
 
 
@@ -146,7 +209,26 @@ def show(
                     if project.fixed_fee_amount is not None
                     else "[red]not set[/red]"
                 )
-                console.print(f"  Billing:      Fixed Fee — {fee}")
+                if project.fixed_fee_schedule == "recurring":
+                    freq = project.fixed_fee_frequency or "?"
+                    console.print(f"  Billing:      Recurring fixed fee — {fee} {freq}")
+                    tpl = project.fixed_fee_template
+                    if tpl:
+                        state = (f"next invoice {tpl['next_run_date']}" if tpl.get("is_active")
+                                 else "paused")
+                        console.print(f"  Invoiced by:  {tpl['name']} ({tpl['id']}) — {state}")
+                    else:
+                        console.print("  Invoiced by:  [yellow]no active recurring invoice[/yellow]")
+                else:
+                    console.print(f"  Billing:      Fixed Fee (one-off) — {fee}")
+                    for m in project.fixed_fee_milestones or []:
+                        inv = m.get("invoice")
+                        status = f"billed on {inv['invoice_number']}" if inv else "not billed"
+                        due = f" due {m['due_date']}" if m.get("due_date") else ""
+                        console.print(
+                            f"    • {m['name']}: {format_currency(Decimal(m['amount']), currency)}"
+                            f"{due} — {status}  [dim]{m['id']}[/dim]"
+                        )
             else:
                 console.print("  Billing:      Time & Materials")
                 console.print(f"  Billing Mode: {billing_labels.get(project.billing_mode, project.billing_mode)}")
@@ -184,6 +266,22 @@ def create(
         None, "--fixed-fee",
         help="Agreed price billed instead of logged hours. Implies --billing-type fixed_fee.",
     ),
+    fee_schedule: Optional[str] = typer.Option(
+        None, "--fee-schedule",
+        help="one-off (the price is paid in payments, default) or recurring (the price every period).",
+    ),
+    fee_frequency: Optional[str] = typer.Option(
+        None, "--fee-frequency",
+        help="How often a recurring fee is billed: weekly, biweekly, monthly, quarterly.",
+    ),
+    payments: Optional[List[str]] = typer.Option(
+        None, "--payment",
+        help="One-off payment as NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD (due date). Repeat; must add up to --fixed-fee.",
+    ),
+    first_invoice: Optional[str] = typer.Option(
+        None, "--first-invoice",
+        help="Recurring fee: date of the first invoice (YYYY-MM-DD). Default: one period after start.",
+    ),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
         help=(
@@ -202,9 +300,16 @@ def create(
 ) -> None:
     """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.
+    Fixed-fee projects bill an agreed price instead of logged hours, one of two
+    ways. One-off: --fixed-fee is the whole price, paid in --payment
+    milestones (one full payment if none are given), each billed once.
+    Recurring: --fixed-fee is billed every --fee-frequency period by a
+    recurring invoice the project sets up for itself.
+
+    Examples:
+        ct projects create "Website" -c Acme --fixed-fee 5000 \
+            --payment Kickoff=1500@2026-06-01 --payment Midpoint=1500 --payment Delivery=2000
+        ct projects create "Support" -c Acme --fixed-fee 4000 --fee-frequency monthly
     """
     api_client = CrowdTimeClient(require_auth=True, require_org=True)
 
@@ -251,6 +356,17 @@ def create(
         payload["billing_type"] = resolved_billing_type
     if fixed_fee is not None:
         payload["fixed_fee_amount"] = fixed_fee
+    if resolved_billing_type != "fixed_fee" and (fee_schedule or fee_frequency or payments or first_invoice):
+        format_error("--fee-schedule, --fee-frequency, --payment and --first-invoice only apply to fixed-fee projects.")
+        raise typer.Exit(1)
+    try:
+        payload.update(_fee_plan_payload(fee_schedule, fee_frequency, payments, first_invoice))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
+    if payload.get("fixed_fee_schedule") == "recurring" and not payload.get("fixed_fee_frequency"):
+        format_error("A recurring fee needs --fee-frequency.")
+        raise typer.Exit(1)
     if payment_terms is not None:
         resolved_terms = _resolve_payment_terms_opt(payment_terms)
         if resolved_terms is None:
@@ -341,6 +457,22 @@ def update(
         None, "--fixed-fee",
         help="Agreed price billed instead of logged hours.",
     ),
+    fee_schedule: Optional[str] = typer.Option(
+        None, "--fee-schedule",
+        help="one-off (the price is paid in payments, default) or recurring (the price every period).",
+    ),
+    fee_frequency: Optional[str] = typer.Option(
+        None, "--fee-frequency",
+        help="How often a recurring fee is billed: weekly, biweekly, monthly, quarterly.",
+    ),
+    payments: Optional[List[str]] = typer.Option(
+        None, "--payment",
+        help="One-off payment as NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD (due date). Repeat; replaces the plan; invoiced payments are kept.",
+    ),
+    first_invoice: Optional[str] = typer.Option(
+        None, "--first-invoice",
+        help="Recurring fee: date of the first invoice (YYYY-MM-DD). Moves the next invoice.",
+    ),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
         help="Payment terms: receipt, net7, net15, net30, or a number of days.",
@@ -364,6 +496,8 @@ def update(
         ct projects update my-project --name "New Name"
         ct projects update my-project --budget 200 --budget-type hours
         ct projects update my-project --billing-mode per_person --status paused
+        ct projects update my-project --fixed-fee 6000 --payment Kickoff=1500 --payment Rest=4500
+        ct projects update my-project --fee-frequency quarterly
     """
     api_client = CrowdTimeClient(require_auth=True, require_org=True)
 
@@ -411,6 +545,21 @@ def update(
         payload["billing_type"] = resolved_billing_type
     if fixed_fee is not None:
         payload["fixed_fee_amount"] = fixed_fee
+    existing_milestones = None
+    if payments:
+        try:
+            current = api_client.get(f"/projects/{resolve_project(api_client, project_id)}/")
+            existing_milestones = current.get("fixed_fee_milestones") or []
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+    try:
+        payload.update(_fee_plan_payload(
+            fee_schedule, fee_frequency, payments, first_invoice, existing_milestones,
+        ))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if payment_terms is not None:
         resolved_terms = _resolve_payment_terms_opt(payment_terms)
         if resolved_terms is None:

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/models.py

@@ -40,6 +40,11 @@ class Project(BaseModel):
     billing_mode: str = "custom"
     billing_type: str = "time_and_materials"
     fixed_fee_amount: Decimal | None = None
+    # one_off (price paid in milestones) or recurring (amount per period).
+    fixed_fee_schedule: str = "one_off"
+    fixed_fee_frequency: str = ""
+    fixed_fee_milestones: list[dict] | None = None
+    fixed_fee_template: dict | None = None
     payment_terms_days: int | None = None
     status: str = "active"
     is_billable: bool = True

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -161,7 +161,9 @@ ct projects list                    # List all projects
 ct projects show <id>               # Project details
 ct projects create "New Project" --client "Acme" --budget 100 --budget-type hours -b
 ct projects create "New Project" --client "Acme" --billing-mode per_person  # Set billing mode
-ct projects create "Redesign" --client "Acme" --fixed-fee 10000  # Fixed price instead of hours
+ct projects create "Redesign" --client "Acme" --fixed-fee 10000  # One-off price, one payment
+ct projects create "Web" --client "Acme" --fixed-fee 5000 --payment Kickoff=1500@2026-06-01 --payment Delivery=3500
+ct projects create "Support" --client "Acme" --fixed-fee 4000 --fee-frequency monthly  # Recurring fee
 ct projects archive <id>            # Archive a project
 ct projects switch <slug>           # Set default project
 
@@ -202,9 +204,13 @@ ct projects add-tasks <project-id> --task <tid1> --task <tid2>  # Bulk assign ta
 
 **Billing types** (*what* is charged): `time_and_materials` (default) or `fixed_fee` (an agreed price via `--fixed-fee`, billed instead of logged hours).
 
+**Fixed fees come in two schedules** — ask which one when the user doesn't say:
+- **One-off** (default): `--fixed-fee` is the whole project price, split into `--payment NAME=AMOUNT[@DUE]` milestones that must add up to it (one "Full payment" if none are given). Each payment is invoiced exactly once.
+- **Recurring**: `--fixed-fee` is charged every `--fee-frequency` (`weekly`, `biweekly`, `monthly`, `quarterly`). The project sets up its own recurring invoice automatically — don't create a template for it by hand.
+
 **Billing modes** (*how* an hourly rate resolves, T&M only): `custom` (default), `per_task` (rate per task), `per_person` (rate per person).
 
-A fixed fee is never billed automatically — client-wide invoices skip fixed-fee projects. Bill it by naming the project explicitly (`ct invoice create --project <id>`) or via a recurring template.
+A fixed fee is never swept into a client-wide invoice. A one-off price is billed by naming the project (`ct invoice create --project <id>`, which bills its next unbilled payment; add `--payment <payment-id>` to pick one — IDs are in `ct projects show`). A recurring fee is billed by its own recurring invoice.
 
 **Rate waterfall** (order depends on billing mode):
 - `custom`: Entry → ProjectMember → ProjectTask → Project → Task → Membership → User

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/skills/crowdtime/references/commands.md

@@ -958,7 +958,11 @@ ct projects create NAME [options]
 | `--billable`, `-b` | flag | Billable (default: true) |
 | `--no-billable`, `-B` | flag | Non-billable |
 | `--billing-type` | string | What the client is charged: `time_and_materials` (default) or `fixed_fee`. Accepts `tm` / `fixed` as aliases |
-| `--fixed-fee` | float | Agreed price billed instead of logged hours. Implies `--billing-type fixed_fee` |
+| `--fixed-fee` | float | Agreed price billed instead of logged hours. Implies `--billing-type fixed_fee`. The whole price for a one-off fee; the amount per period for a recurring one |
+| `--fee-schedule` | string | `one-off` (default) or `recurring` |
+| `--fee-frequency` | string | Recurring fee cadence: `weekly`, `biweekly`, `monthly`, `quarterly`. Implies `--fee-schedule recurring` |
+| `--payment` | string (repeatable) | One-off payment `NAME=AMOUNT` or `NAME=AMOUNT@YYYY-MM-DD`. Must add up to `--fixed-fee`. Omitted → one "Full payment" |
+| `--first-invoice` | string | Recurring fee: date of the first invoice. Default: one period after the project starts |
 | `--billing-mode` | string | Rate resolution for T&M work: `per_task`, `per_person`, `custom` (default). Ignored for fixed-fee projects |
 | `--payment-terms` | string | Terms for this project: `receipt`, `net7`, `net15`, `net30`, or a number of days. Omit to inherit the client, then org, default |
 | `--color` | string | Hex color code |
@@ -974,9 +978,13 @@ ct projects create NAME [options]
 | `time_and_materials` | Default. Billed from logged hours at the resolved rate |
 | `fixed_fee` | Billed at `--fixed-fee`, an agreed price. Logged hours are tracked but never charged by the hour |
 
-> **How a fixed fee gets invoiced.** It is *never* billed automatically. A client-wide invoice (`ct invoice create` with no project filter) deliberately skips fixed-fee projects entirely, so the fee cannot go out by accident. It is billed only when:
+> **Fixed-fee schedules.**
+> - **One-off** — the price is paid in payments (milestones) that add up to it. Each payment is billed **once**: naming the project on an invoice bills its next unbilled payment (or the ones picked with `--payment <id>`), and a fully billed project bills nothing. Voiding or deleting the invoice frees the payment again. A recurring template that lists the project bills the payments due by the end of the period it covers; payments without a due date are only billed by naming the project on an invoice. Duplicating an invoice leaves out its payment lines. Invoiced payments cannot be changed or removed.
+> - **Recurring** — the amount is billed every period. Creating the project (or switching it to recurring) sets up its own recurring invoice template with that cadence; changing the frequency updates it, and switching away, making it non-billable or archiving pauses it. If a hand-made template already bills the project, no second one is created.
+>
+> **How a fixed fee gets invoiced.** A client-wide invoice (`ct invoice create` with no project filter) deliberately skips fixed-fee projects entirely, so the fee cannot go out by accident. It is billed only when:
 > 1. the project is named explicitly — `ct invoice create --client <id> --project <fixed-project-id>`, or
-> 2. a recurring template lists the project.
+> 2. a recurring template lists the project (including the one a recurring fee creates for itself).
 >
 > When the fee is billed, that project's hours in the period are linked to the fee line and marked invoiced, so they stop showing as outstanding work without ever being charged twice. Until then they stay uninvoiced and available.
 
@@ -992,7 +1000,12 @@ ct projects create NAME [options]
 **Fixed-fee examples:**
 ```bash
 ct projects create "Rediseño Web" --client "Acme" --fixed-fee 10000
+ct projects create "Web" --client "Acme" --fixed-fee 5000 \
+  --payment Kickoff=1500@2026-06-01 --payment Midpoint=1500@2026-07-01 --payment Delivery=2000@2026-08-01
+ct projects create "Soporte" --client "Acme" --fixed-fee 4000 --fee-frequency monthly --first-invoice 2026-12-01
 ct projects update redesign --billing-type fixed --fixed-fee 12000
+ct projects update web --fixed-fee 6000 --payment Kickoff=1500 --payment Rest=4500  # Invoiced payments are kept
+ct projects update soporte --fee-frequency quarterly
 ct projects update redesign --billing-type tm --billing-mode per_person
 ```
 
@@ -2028,6 +2041,7 @@ Creates an invoice from tracked time entries. Requires either `--from`/`--to` or
 | `--to` | string | Period end date |
 | `--period` | string | Preset: `last-week`, `last-2-weeks`, `last-month`, `this-month` |
 | `--project`, `-p` | string (repeatable) | Limit to specific project ID(s). **Required to bill a fixed-fee project** — those are never included in a client-wide invoice |
+| `--payment` | string (repeatable) | One-off fixed-fee payment ID(s) to bill (from `ct projects show`). Without it, each selected one-off project bills its next unbilled payment |
 | `--group-by` | string | Group line items by: `project`, `task`, `user`, `date`, `none` |
 | `--tax-rate` | float | Tax rate percentage (e.g. 21 for 21%) |
 | `--payment-terms` | string | Payment terms: `receipt` (0 days), `net7`, `net15`, `net30`, or number of days. **Omit** to resolve from the waterfall below |
@@ -2051,7 +2065,8 @@ ct invoice create --client <id> --period last-2-weeks --group-by project
 ct invoice create --client <id> --period last-month --group-by user    # One line item per team member
 ct invoice create --client <id> --period last-month                    # Uses the client's own terms
 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>  # Bills the fixed fee
+ct invoice create --client <id> --period last-month --project <fixed-project-id>  # Bills the next payment / one period
+ct invoice create --client <id> --period last-month --project <fixed-project-id> --payment <payment-id>
 ```
 
 Endpoint: `POST /invoices/from-time-entries/`

{crowdtime_cli-0.21.1 → crowdtime_cli-0.22.0}/src/crowdtime_cli/skills/crowdtime/references/workflows.md

@@ -278,6 +278,26 @@ ct projects update-member consulting-engagement senior@co.com --rate 200
 ct projects update-member consulting-engagement junior@co.com --rate 100
 ```
 
+### Set Up a Fixed-Fee Project
+
+First ask which kind of fixed fee it is — the two are billed very differently:
+
+```bash
+# One project price, paid in milestones (each invoiced exactly once)
+ct projects create "Website" --client "Acme" --fixed-fee 5000 \
+  --payment Kickoff=1500@2026-06-01 --payment Midpoint=1500@2026-07-01 --payment Delivery=2000@2026-08-01
+
+# Bill the next payment when it's time (see `ct projects show` for payment IDs)
+ct invoice create --client <client-id> --period this-month --project <project-id>
+
+# The same amount every month — a recurring invoice is created for it automatically
+ct projects create "Support" --client "Acme" --fixed-fee 4000 --fee-frequency monthly
+ct projects show support   # "Invoiced by:" names the template and its next run
+```
+
+Payments must add up to the price. Invoiced payments can't be changed or removed;
+void the invoice first if one was billed by mistake.
+
 ### Apply Task Presets to an Existing Project
 
 ```bash
@@ -1142,8 +1162,9 @@ ct invoice recurring generate-now <template-id> \
 ```
 
 Logged hours cannot be double-billed — they are settled on the invoice that
-pulled them. Fixed lines and fixed-fee projects can: they are billed in full on
-every run whatever the period, which is what the guard exists for.
+pulled them. Fixed lines and recurring fixed fees can: they are billed in full
+on every run whatever the period, which is what the guard exists for. One-off
+fixed-fee payments are safe — each is billed only once.
 
 ---