timeclock

README

Timeclock

Time tracking for payroll: clock in and out, time by customer and project, vacation and sick time per pay cycle, timesheets, approvals, exceptions, and reports a payroll system can import.

It is one Go module with its web app embedded. It runs two ways:

• Inside a host application, mounted under a path. The host says who is calling and answers questions about its people; Timeclock keeps the time.
• On its own, as timeclock-server, with its own sign-in.

What it does

• The clock. One running clock per person: say what you are working on, pick its project, and start. Choosing another project while it runs moves the clock to it without stopping: the time so far stays where it was. Time can also be added and corrected by hand.
• Projects. Every entry can be tagged with a project: a customer's, or internal work with no customer. An organization can require one.
• The week. A calendar of the workweek, a day to a column: drag to add time, drag a block or its edge to change it. Entries may overlap, as a meeting inside a longer stretch does; worked hours count the overlap once, so they are never more than the time that passed.
• Overview. Hours per day by project, each project's share of the week, and who is on the clock now.
• Pay periods. Weekly, biweekly, twice a month or monthly, set by an admin.
• Time zones. The organization has one, and a person can have their own: their times show in it, and their days and workweeks start at its midnight. Pay periods are the same calendar dates for everyone.
• Overtime. Time beyond a weekly threshold is overtime, counted per workweek on the day it was worked, so a week that straddles two pay periods puts its overtime in the right one. People can be marked exempt.
• Time off. Vacation and sick hours are recorded per day and reported per pay period. Balances stay in the payroll system.
• Timesheets. Each period a person submits their timesheet, which locks that period's time. A manager or admin can send it back.
• Approvals. Timesheets and time off can each need approval, from the person's manager or an admin, or not. Nobody approves their own.
• Exceptions. What payroll should look at before paying: a clock left running, a very long entry, a timesheet not submitted or not approved, pending time off, overtime, a period with nothing recorded.
• Reports. Hours per person per pay period, exported as a CSV for Gusto's hours import, and hours by customer, project and person.
• Audit log. Every change to payroll data, with who made it.
• Workspaces. A workspace is one organization's Timeclock: its people, time, settings and look. Every table carries its workspace and every query names it, so one deployment can hold many. A host with several organizations says which one a request is in; without that there is one.
• Themes. A look is a few values: for light and for dark, an accent, a background and a contrast, and optionally the same for the sidebar; every other color follows from them. A workspace admin sets the workspace's in Settings, with the page wearing the draft as it changes; a host application can hand Timeclock its own; and each person chooses light, dark or the system's.
• Reminders. With a host notifier, people are told once about a clock left running and a timesheet that is due.

Embedding

tc, err := timeclock.New(ctx, timeclock.Options{
	DatabaseURL: dsn,          // the host's own PostgreSQL database
	BasePath:    "/timeclock", // where the host mounts it
	Caller: func(r *http.Request) (string, bool) {
		return userIDFromSession(r) // the host's signed-in user
	},
	Directory:       directory,     // a host.Directory over the host's people
	Notifier:        notifier,      // optional: a host.Notifier for reminders
	HomeURL:         "/",           // optional: a link back to the host
	HomeLabel:       "Portal",
	SignInURL:       "/login?next=",
	SignOutURL:      "/api/auth/logout",
	ThemeStorageKey: "portal-theme", // optional: follow the host's light/dark choice
	Theme:           theme,          // optional: a host.Theme, so Timeclock matches the host's colors
	Workspace:       workspaceOf,    // optional: func(*http.Request) (key string, ok bool), for a host with several organizations
})
if err != nil {
	return err
}
defer tc.Close()
go tc.Run(ctx)                  // reminders and integrations, until ctx ends
mux.Handle("/timeclock/", tc)   // requests arrive with the base path still on them

examples/host is a complete host in one file: its own people, several organizations, and its own colors.

host.Directory is two methods: Person(ctx, id) and People(ctx). A host.Person has an id, a name, an email, whether they are an admin (run payroll), and optionally their manager's id; an admin can set managers in Timeclock too, which takes precedence.

Timeclock keeps its tables, and hopper's job tables, in its own schema (timeclock by default) and migrates it at startup under an advisory lock, so replicas can start together and it can share the host's database. Options.SkipMigrations leaves migrating to the host.

It is built on foundation: errors are RFC 9457 problems with stable codes (/problems/timeclock/<code>), the handler sets security headers and a strict CSP, and refuses cross-site writes.

The clock in the host's own pages

@giraffesyo/timeclock is the clock bar as an npm package, for the host's own header: a ready-made ClockBar, a headless useClock() hook, and a store with no React. Timeclock's own bar is that package.

import { ClockBar } from '@giraffesyo/timeclock/react';
import '@giraffesyo/timeclock/styles.css';

<ClockBar basePath="/timeclock" />;

Standalone

timeclock-server is Timeclock with its own accounts. Nobody is signed in until they accept an invitation and set a password.

TIMECLOCK_DATABASE_URL=postgres://... \
TIMECLOCK_PUBLIC_URL=https://time.example.com \
TIMECLOCK_ADMIN_EMAILS=payroll@example.com \
TIMECLOCK_SECRET_KEY=<32+ random characters, kept out of the database's backups> \
TIMECLOCK_SMTP_HOST=smtp.example.com TIMECLOCK_SMTP_FROM='Timeclock <time@example.com>' \
TIMECLOCK_SMTP_USERNAME=... TIMECLOCK_SMTP_PASSWORD=... \
timeclock-server

• Getting in. Each address in TIMECLOCK_ADMIN_EMAILS is invited when the server first starts. After that, a workspace's admins invite people from Settings → People, and whoever runs the server can too: timeclock-server invite KEY EMAIL [--admin]. There is no open sign-up.
• Workspaces. timeclock-server workspace KEY "Name" --admin EMAIL makes another organization on the same server and invites its first admin. Someone in more than one switches between them from the top of the sidebar.
• Passwords. At least 10 characters, with no rules about what they contain; ones known from a data breach are refused (the check sends five characters of a hash, never the password; TIMECLOCK_BREACH_CHECK=off turns it off). They are stored as Argon2id hashes. Repeated wrong guesses pause sign-in for the account and for the address they come from; behind a reverse proxy, set TIMECLOCK_TRUST_PROXY=1 so that address is the client's (from X-Forwarded-For) and not the proxy's.
• Sessions. A random token in an HttpOnly, SameSite=Lax cookie, kept only as a hash. Signing out, resetting or changing a password ends sessions at the server.
• A second step. Anyone can add an authenticator app to their account (with recovery codes for when the phone is gone); sign-in then asks for its code after the password, and a reset link doesn't get around it. A passkey signs in on its own, with a fingerprint, face or device PIN. Both are set up under Account.
• Email. Invitations and password resets go by SMTP. Without a mail server, they are written to the log, and an invitation's link is shown to the admin who made it.
• Single sign-on. A workspace's admins can give it its own OpenID Connect provider in Settings → Sign-in, require it, and let anyone it signs in join; Settings shows a sign-in link that goes straight to the provider. What a workspace's provider says counts in that workspace only: a session that came in through it sees that workspace and can't change how the account signs in. TIMECLOCK_OIDC_ISSUER, _CLIENT_ID and _CLIENT_SECRET add a provider for the whole server instead. Either way the redirect URL is <public URL>/auth/callback.
• The secret key. TIMECLOCK_SECRET_KEY seals authenticator secrets, providers' client secrets, and integration tokens in the database (AES-256-GCM). Losing it means setting those up again; it isn't needed to read time or sign in with a password.

See cmd/timeclock-server/main.go for every variable. The Dockerfile builds the image.

Toggl Track trial sync

An admin opens Integrations → Toggl Track, enters a Toggl workspace admin's API token, selects the workspace, and confirms the suggested email matches between Toggl users and Timeclock people. Employees do not connect their accounts. The Toggl account must have permission to read and edit the matched people's time; plan restrictions and API quotas still apply.

All history is selected by default, including completed entries on archived projects. Historical time with missing required fields or payroll locks is surfaced under Needs attention. You can instead choose a starting date (midnight UTC, 1970 or later). Hopper picks up the connection within a minute. Recent time syncs while older time imports in bounded batches; progress and report-page cursors survive restarts and API limits. Large histories can take multiple runs. After the first historical scan, jobs run about every ten minutes and continue sweeping older dates for changes. History is limited to the matched people and data the Toggl account can access. Run tc.Run(ctx) when embedding, and set Options.IntegrationSecretKey to at least 32 characters. Standalone uses TIMECLOCK_SECRET_KEY. Tokens are encrypted with AES-GCM and are never returned by the API or included in audit records.

• Completed time entries sync in both directions, including descriptions, dates and project assignments. Running timers transfer after stopping. Customers and projects are imported from Toggl and paired with existing names within the same customer; use these projects when tracking in either app. Catalog renames, new Timeclock projects, tags, tasks, billable flags/rates, time off and payroll approvals are outside this bridge's scope.
• Only explicitly matched, active Timeclock people sync. Existing matches cannot be reassigned while connected. An admin can add people through Manage connection.
• Submitted and approved timesheets remain locked. Conflicting edits appear under Needs attention, with both versions and an explicit choice. Toggl does not provide conditional updates for these writes: the bridge re-reads before pushing, but a simultaneous edit after that read remains a limitation of polling.
• Local deletions propagate to Toggl. Missing or inaccessible Toggl entries require an admin decision before deleting local time. A report omission alone never deletes anything.
• Partial reports and API limits stop that attempt. Backoff is saved in the database, including Retry-After; Sync now cannot bypass it. Sync resumes from durable entry mappings. If an external create may have succeeded before a network or database failure, the bridge asks the admin to link the created entry or confirm that it is absent before retrying.
• Disconnect waits for the active workspace sync, then deletes credentials, person/project/entry mappings, staged report pages and sync state. Imported time, customers, projects and the audit history stay in Timeclock; no data is deleted in Toggl. Reconnecting requires a token and person matching again. The retained audit history restores entry identity and the last shared version for the same Toggl workspace and people, avoiding duplicates and detecting offline conflicts or deletions. Previously imported users must be matched to their original Timeclock people.

The integration uses Toggl's Track API, detailed Reports API, and workspace membership API. Google Calendar and Gusto have reserved rows on the Integrations page but are not connected services yet.

The regular browser suite uses a local fake Toggl service, synthetic tokens, the real API/database, and the Hopper worker. make e2e ARGS="e2e/integrations.spec.ts --project=chromium" covers history pagination, edits, disconnect, reconnect and conflict resolution without any Toggl account. The e2e build tag redirects Toggl requests to localhost and refuses real Toggl traffic; production builds have no override.

Live integration tests are opt-in. Set TIMECLOCK_TOGGL_TEST_TOKEN_FILE to a local file containing a Toggl Track API token and TIMECLOCK_TOGGL_TEST_WORKSPACE_ID to the sandbox workspace ID. Run go test ./internal/toggl -run '^TestLiveWorkspaceContract$' -count=1 -v for read-only checks. With the test database configured, TIMECLOCK_TOGGL_TEST_WRITES=1 go test ./internal/clock -run '^TestLiveTogglRoundTrip$' -count=1 -v creates one disposable entry, verifies edits in both directions and disconnect cleanup, then deletes that remote entry. The write test requires a single-user sandbox and uses an isolated local schema; it does not verify editing another team member's time. Toggl 2.0 tokens use a separate API and are not supported by this Track integration.

Development

Needs Go 1.27, Node 26 with pnpm 11, and Docker.

make install
make dev        # http://localhost:8090, signed in as DEV_USER (an admin)
make test-db    # Go tests, with the database tests on
make check      # every linter and test
make vuln       # known vulnerabilities in the Go code
make e2e        # the end-to-end tests: the built server, driven by real browsers
make api        # after changing an API operation: regenerate the web app's types

In development the Go server proxies the web app from Vite, so open the Go server's address. Vite's own address (:5174) passes the API on to the Go server and works too, but only the Go server applies the CSP.

Where	What
timeclock.go	New, Options: the handler a host mounts
host/	Directory and Notifier: what a host implements
internal/clock/	The payroll rules and their storage. Every statement names its workspace as $W; one that doesn't is refused (workspace.go)
internal/api/	The HTTP API (huma); timeclock-server openapi prints its document
internal/standalone/	A standalone server's accounts: passwords, sessions, invitations, workspaces to switch between, email, and OIDC
migrations/	goose migrations, NNNNN_name.sql
web/	The Vite app, embedded in the binary
web/packages/timeclock/	@giraffesyo/timeclock, the clock for a host application; the app is built on its source
examples/host/	A small application with Timeclock mounted in it
web/e2e/	End-to-end tests (Playwright): each test is its own people, against a schema made for the run. They drive four servers: one signed in as whoever a test says, one with its own accounts, one set up like a real deployment (mail by SMTP, identity providers, a breach list, a proxy; the pretend ones are services.mjs), and examples/host

The payroll export

GET /api/v1/reports/payroll.csv?day=<any day in the period> has one row per person whose time is settled (their timesheet is approved, or submitted when timesheets need no approval), with the columns last_name, first_name, gusto_employee_id, regular_hours, overtime_hours, double_overtime_hours, pto_hours, sick_hours. ?all=true includes everyone. Check the columns against the template Gusto gives your company before the first import; the column names are in internal/api/reports.go.

Releasing

Commits on canary follow Conventional Commits, and release-please keeps a release PR open from them. Merging that PR:

• publishes a timeclock-vX.Y.Z GitHub release with the notes;
• tags the Go module vX.Y.Z on a commit that adds the built web/dist, so a tagged version carries the app while canary stays free of build output. A host depends on that tag, never on canary, which embeds no app;
• publishes @giraffesyo/timeclock at the same version to npm, signed in through npm's trusted publishing.

make release VERSION=vX.Y.Z tags the module by hand, as a fallback.

License

Apache License 2.0.

Documentation

Overview

Package timeclock tracks time for payroll: clocking in and out, time by project and customer, vacation and sick time per pay cycle, timesheets, approvals, exceptions and reports a payroll system can import.

It runs inside a host application, which mounts Timeclock under a path, tells it who is calling and answers its questions about people through a host.Directory:

tc, err := timeclock.New(ctx, timeclock.Options{
	DatabaseURL: dsn,
	BasePath:    "/timeclock",
	Caller:      func(r *http.Request) (string, bool) { return userIDFromSession(r) },
	Directory:   directory,
})
go tc.Run(ctx)
mux.Handle("/timeclock/", tc)

cmd/timeclock-server runs it on its own, with its own sign-in.

Index

• func OpenAPI() *huma.OpenAPI
• type Options
• type Timeclock
  • func New(ctx context.Context, opts Options) (*Timeclock, error)
  • func (t *Timeclock) Close()
  • func (t *Timeclock) Run(ctx context.Context)
  • func (t *Timeclock) ServeHTTP(w http.ResponseWriter, r *http.Request)

Functions

func OpenAPI

func OpenAPI() *huma.OpenAPI

OpenAPI returns the API's OpenAPI document without connecting to anything. The web app's client types are generated from it.

Types

type Options

type Options struct {
	// DatabaseURL is the PostgreSQL database holding Timeclock's schema,
	// normally the host's own.
	DatabaseURL string
	// Schema is Timeclock's schema in that database. Defaults to "timeclock".
	Schema string
	// SkipMigrations leaves migrating to the host. By default New applies
	// Timeclock's migrations under an advisory lock, so replicas can start
	// together.
	SkipMigrations bool
	// BasePath is where the host mounts Timeclock, such as "/timeclock".
	// Requests reach Timeclock with it still on the path. Empty serves at
	// the root.
	BasePath string
	// Caller returns the host user making a request, from the host's
	// session or API key.
	Caller func(r *http.Request) (userID string, ok bool)
	// Directory answers questions about the host's people.
	Directory host.Directory
	// Notifier delivers reminders (a clock left running, a timesheet that is
	// due) through the host's notifications. Without one, none are sent.
	Notifier host.Notifier
	// HomeURL and HomeLabel link from Timeclock back to the host, such as
	// "/" and the host's name.
	HomeURL   string
	HomeLabel string
	// SignInURL is where the host signs a person in, ending with the query
	// parameter that takes the path to return to, such as "/login?next=".
	// Timeclock's web app sends a signed-out browser there.
	SignInURL string
	// SignOutURL is the host's same-origin endpoint that ends its session.
	// Timeclock's web app POSTs to it and then loads HomeURL. Without it,
	// Timeclock offers no sign-out.
	SignOutURL string
	// AccountsURL is where a standalone server manages its own accounts
	// (workspaces to switch between, invitations, passwords). A host that
	// has its own users leaves it empty.
	AccountsURL string
	// ThemeStorageKey is the localStorage key where the host keeps the
	// person's light, dark or system choice, so Timeclock matches it.
	// Without it, Timeclock follows the system.
	ThemeStorageKey string
	// Workspace names the workspace a request is in, for a host with more
	// than one organization: each key is its own people, time and settings,
	// made the first time it is seen. Without it, everyone is in one.
	Workspace func(r *http.Request) (key string, ok bool)
	// Theme is the host's look, so Timeclock mounted in it matches: for
	// light and for dark, an accent and a background. A workspace admin can
	// still set the workspace's own in Timeclock's settings.
	Theme host.Theme
	// Routes registers extra handlers beside Timeclock's own, such as a
	// standalone server's sign-in.
	Routes func(mux *http.ServeMux)
	// DevServer is the Vite dev server, such as "http://localhost:5174",
	// proxied while the module embeds no web build.
	DevServer string
	// HSTS sends Strict-Transport-Security. A host that sets its own
	// security headers leaves it off.
	HSTS bool
	// IntegrationSecretKey encrypts integration credentials. At least 32 characters.
	// Empty disables new connections. Keep this key outside database backups.
	IntegrationSecretKey string
	// Logger defaults to slog.Default().
	Logger *slog.Logger
}

Options configures a Timeclock.

type Timeclock

type Timeclock struct {
	// contains filtered or unexported fields
}

Timeclock is an http.Handler for everything under its base path, and background work started by Run.

func New

func New(ctx context.Context, opts Options) (*Timeclock, error)

New connects to the database, applies migrations and builds the handler.

func (*Timeclock) Close

func (t *Timeclock) Close()

Close releases the database pool.

func (*Timeclock) Run

func (t *Timeclock) Run(ctx context.Context)

Run does Timeclock's background work until ctx ends: reminding people, through the host's Notifier, about a clock left running or a timesheet that is due, and syncing connected integrations. With neither configured, it returns when ctx ends.

func (*Timeclock) ServeHTTP

func (t *Timeclock) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves Timeclock's API and web app.