Time Tracker and Invoicing

Time Tracker & Invoicing

Track billable time against your notes and projects, aggregate it by client, and generate invoices — built for freelancers and consultants who live in Obsidian. Fully local: no external API, no account, your data stays in your vault.

Open-core / one-time purchase. Time tracking is free forever in the Lite tier. Invoicing & PDF export unlock with a one-time license — ~$29–39 (one-time).

---

Lite vs. Premium

All time tracking is free. Invoicing/PDF export is gated behind the license check (LicenseManager.isPremium()).

---

How it works

Tracking time

• Start tracking active note — begins a timer against the currently open note. The note's client and project frontmatter (configurable) tag the entry; if absent, a default client is used and the note name becomes the project.
• Stop tracking — closes the timer and records a time entry.
• A status bar item shows the running timer (⏺ 0:12:34 · Acme Co); click it to start/stop.
• Entries are stored locally in the plugin's data.json (alongside settings) — fully in your vault.

Aggregation

• Show tracked time totals — summarizes hours by client.
• Aggregation also powers invoicing (totals broken down by project → invoice line items).

Invoicing (premium)

• Generate invoice (Premium) — pick a client; the plugin builds a markdown invoice (one line item per project, configurable rounding) and saves it to your invoice folder, with business details and totals.
• PDF export is stubbed today (exportPdfStub) — it saves the markdown and points you to Obsidian's built-in Export to PDF. A real local PDF generator is left as a clean TODO(pdf).

---

Commands

• Start tracking active note (Lite)
• Stop tracking (Lite)
• Toggle tracking (start/stop) (Lite)
• Show tracked time totals (Lite)
• Generate invoice (Premium)
• Verify license key

Plus a ribbon clock icon to toggle tracking.

Settings

Default hourly rate, currency, hours rounding, client/project frontmatter property names, and default client (all free). Business name/address/email and invoice folder are premium (invoice-only) and locked until licensed. License key lives under License.

Keys are verified offline with Ed25519 signatures (tweetnacl) — no account, server, or network call, keeping the plugin 100% local. A key is base64url(payload).base64url(signature), verified against the public key in src/license/publicKey.ts.

Selling keys (author workflow):

node scripts/keygen.mjs                 # one-time: create keypair
npm run license:generate -- [email protected]   # after a sale: mint a key

Billing/delivery (payment + emailing the key) is handled out-of-band by Lemon Squeezy / Gumroad — see the TODO(billing) in src/license/LicenseManager.ts.

---

Build

npm install
npm run build      # bundles to main.js
npm run dev        # watch mode
npm run typecheck  # tsc --noEmit
npm test           # offline license verification tests

npm run build produces main.js next to manifest.json and styles.css.

Install into a vault for testing

Copy main.js, manifest.json, and styles.css into:

<your-vault>/.obsidian/plugins/time-tracker-invoicing/

Then enable Time Tracker & Invoicing in Settings → Community plugins.

---

Project layout

time-tracker-invoicing/
├── manifest.json
├── versions.json
├── package.json
├── tsconfig.json
├── esbuild.config.mjs
├── styles.css
├── .github/workflows/
│   └── release.yml        # tag-driven GitHub release (build + attach assets)
├── scripts/
│   ├── keygen.mjs         # one-time Ed25519 keypair generator (author)
│   ├── generate-license.mjs   # mint a customer key (author)
│   └── customer-license-template.txt
├── tests/
│   └── license.test.mjs   # offline license sign/verify round-trip
└── src/
    ├── main.ts            # entry, commands, status bar, persistence
    ├── settings.ts        # settings tab
    ├── license/
    │   ├── LicenseManager.ts  # offline Ed25519 verification
    │   └── publicKey.ts       # embedded public key
    ├── types/tweetnacl.d.ts   # minimal tweetnacl type shim
    ├── timeStore.ts       # entries, active timer, aggregation
    ├── invoice.ts         # invoice markdown generation + PDF stub (premium)
    └── types.ts           # shared interfaces & defaults

Reference: the licensing approach, settings-tab patterns, build/test setup, and project layout are adapted from the Vault Spotlight plugin — see "Borrowed from Vault Spotlight" notes in the repo.

License

MIT (plugin source). Premium feature access is governed by a signed license key.