# Punchin

A time billing tool for FOSS teams that want to spend as little time tracking time as possible

# Features
- Invoice Management
    - automatically log hours to draft invoices via invoice system integration
- Conversation discovery
    - Find potentially billable conversations with tracked people, domains, or channels
- Work Discovery
    - Find potentially billable commits, tickets, milestones
- Secret Management
    - Store all credentials in hardware-token-backed PGP encrypted storage

# Integrations
- Slack
- Matrix
- Forgejo
- Firefox
- IMAP
- InvoiceNinja
- git

# Workflow

## Setup

1. Register data sources

    ```
    > punchin login [service]
    ```
    - setup chat, email, git accounts, invoice system, etc
    - Will be asked to add all services if none specified

2. Register a new client

    ```
    > punchin client add
    ```
    - Select client from list of clients defined in invoicing system
    - Setup minimum time increment (e.g. 30m)
    - Setup rate from list of supported rates in invoicing system
    - Setup reduced rate for first x hours for retainers
    - Setup monitored keywords, domains, repos
    - Setup milestones, projects, issues to log time to
    - Setup target invoice template

## Usage

```
> punchin

-> Select Client
--> 1. ACME Co. [Default]
--> 2. John Doe Intustries

[Enter] for default
> 1

-> Time: 14:34 2024-12-06
Last Update: Nov 5
Search time: Nov 3-5

-> Searching Events...

------------------------------------------------------------------
-> Found meeting:
- Description: "Meeting: Discussing Priorities"
- Source: Email Invite
- Context: [Link] 
- Timeframe: Nov 4 - Nov 5
- Words: 345
- Participants: Joe C, Jim G., Bob H.
- Time [Estimated]: 2.5h
--> 1. Bill [Default]
--> 2. Mark non-billable
--> 3. Update time
--> 4. Update description
> 1

------------------------------------------------------------------
-> Found conversation
- Description: "Matrix Chat in 'Team'"
- Keywords: "ACME"
- Channel: #acme-team@matrix.org
- Participants: Joe C, Jim G.
- Words: 195
- Context: [Link] 
- Time [Estimated]: 30m
--> 1. Bill [Default]
--> 2. Mark non-billable
--> 3. Update time
--> 4. Update description
> 3
New Total:
> 1h
> 4
New Description:
> Architecture Discussion 
> 1
--> Invoice Line Submitted

------------------------------------------------------------------
-> Found commit
- Description: "Refactor to be more readable"
- Source: git@codeberg.org/acme/website.git#joe/refactor-stuff
- Channel: "Team"
- Ticket: [None]
- Milestone: [None]
- Participants: Joe C, Jim G.
- Lines: 2534
- Context: [Link] 
- Time [Estimated]: 5h
--> 1. Bill [Default]
--> 2. Mark non-billable
--> 3. Update time
--> 4. Update description
> 1

Error: Client "ACME" requires "Ticket" and "Milestone" to be set

Choose ticket:
--> 1. Cleanup Refactor
--> 2. Spellcheck support
--> N. [New]
> 1

Choose milestone:
--> 1. Usability
--> 2. Doc Improvements
--> N. [New] 
> N

New Milestone Name
> Refactor/Cleanup

-> Updated Hours: "acme/website - Cleanup Refactor"
-> Updated Invoice: "ACME Consulting - 2025/01/12"

------------------------------------------------------------------
-> Found review
- Description: "Review: add spell checking"
- Source: git@codeberg.org/acme/website.git#jim/spellcheck-support
- Issue: "#154"
- Context: [Link] 
- Participants: Joe C, Jim G.
- Lines: 2534
- Time [Estimated]: 1h
--> 1. Bill [Default]
--> 2. Mark non-billable
--> 3. Update time
--> 4. Update description
> 1

------------------------------------------------------------------
-> Log manual hours?
--> [Y/n]
> Y
Start:
> 2024-12-06 15:41 PT
End:
> 2024-12-06 16:00 PT
Description:
> Took a walk trying to do debugging
-> Adjusted time: 30m
-> Updated Invoice: "ACME Consulting - 2025/01/12"

------------------------------------------------------------------
-> Time spent tracking time
-> Total: 1h
-> Updated Invoice: "ACME Consulting - 2025/01/12"
```