HitKeep 2.13.0 turns email reporting from a small set of frequency switches into a complete reporting workflow. A personal or team report now has an owner, preset, site scope, recipients, local delivery time, next run, and delivery history. Teams can confirm external recipients without creating dashboard accounts, while operators can inspect retries without storing rendered email bodies or tracking opens.
The release also adds Google, GitHub, and Microsoft sign-in, extends traffic exclusions across instance, team, and site scopes, and hardens DuckDB operation with serialized checkpoints and narrow, evidence-preserving recovery paths. Country, city, provider, and ASN lookups move to block-addressable embedded assets so the runtime can decode bounded portions on demand.
There is one intentional breaking REST API change. The old report-subscription routes are removed after an automatic data migration. Integrations that call those endpoints must move to the new report-definition API before upgrading.
Breaking report API change
HitKeep 2.13.0 removes GET /api/user/report-subscriptions, PUT /api/user/report-subscriptions/digest, and PUT /api/user/report-subscriptions/sites/{site_id}. The DigestSubscription, SiteReportSubscription, and ReportSubscriptions OpenAPI schemas are removed with them. Use /api/reports and the related preview, run-history, test-send, retry, confirmation, unsubscribe, and resubscribe operations instead.
What Ships In 2.13.0
- Configurable scheduled reports: create personal or team reports with a named preset, selected or accessible sites, an IANA timezone, a local delivery time, and daily, weekly, or monthly cadence.
- Stakeholder delivery without dashboard access: team owners and admins can add confirmed external recipients. Consent is report-specific, expires, can be withdrawn, and does not create an account or grant site access.
- Durable delivery operations: preview content, send a test to yourself, inspect runs and recipient deliveries, retry failures, and distinguish SMTP acceptance from inbox delivery.
- Google, GitHub, and Microsoft sign-in: enable only completely configured providers, use them for login or signup, link them to an existing account, and preserve invitations and MFA handoff.
- Layered traffic controls: apply CIDR, country, user-agent, or path exclusions at instance, team, or site scope, with inherited rules visible through effective API reads.
- Safer DuckDB lifecycle: serialize periodic, migration, backup, and shutdown checkpoints; retain recovery bundles before narrow repairs; and keep application WAL bypass behind explicit operator approval.
- Lower-overhead IP metadata: decode validated country, city, provider, and ASN blocks on demand under bounded caches instead of inflating every embedded lookup table at startup.
- Security and dependency maintenance: move Spamhaus refreshes to its JSON feeds, refresh the embedded denylist data, update Go and dashboard dependencies, fix high-severity frontend audit findings, and pin current GitHub Actions revisions.
- One contributor workflow: route setup, development sessions, screenshots, builds, smoke tests, and canonical QA through the repository-owned
hkplatform and its developer MCP surface. - Release metadata that follows the artifact: publish a checksummed configuration catalog with stable releases, then synchronize the public configuration reference and current-version facts only after release binaries and the Helm chart succeed.
Reports Become First-Class Definitions
The Reporting hub replaces separate digest and per-site switches with saved report definitions. Each row answers the questions an operator needs before trusting scheduled delivery: who owns the report, what it covers, who receives it, when it runs next, and how the last run ended.
Three presets cover different jobs:
| Preset | Cadence | Main content |
|---|---|---|
| Site Summary | Daily, weekly, or monthly | Visitors, pageviews, bounce rate, session duration, goals, comparison, trend, top pages, and referrers for one site |
| Portfolio Digest | Daily, weekly, or monthly | Pageviews, visitors, goals, deltas, and site links across selected sites or every site accessible to a personal report owner |
| Opportunity Brief | Daily or weekly | Saved, validated Opportunity Recommendations and their cited evidence |
Opportunity Brief does not start a model run. It reads already saved recommendations and suppresses an empty report when none passes the deterministic quality rules.
Schedules use the report’s timezone rather than a server-local assumption. New reports default to 08:00 in the browser-detected timezone, allow 15-minute delivery increments, and recalculate the UTC run after schedule changes and daylight-saving transitions. Weekly reports choose a weekday. Monthly reports choose a day from 1 through 28.
Personal reports belong to one user and send only to that user. Team reports use explicitly selected sites and can include members plus up to 25 external addresses. On HitKeep Cloud, external recipients are available with Pro and Business; self-hosted HitKeep does not apply that plan gate.
An external address receives a seven-day, single-use confirmation that names the team, cadence, and selected domains. HitKeep stores a SHA-256 hash of the confirmation token, not the token itself. Changing the preset, sites, or frequency requires renewed consent. Renaming a report or changing only its delivery time does not. External mail contains the report content but omits dashboard and site links.
The delivery worker records report runs and per-recipient outcomes before mail is attempted. SMTP failures retry after 5 minutes, 30 minutes, and 2 hours with the same Message-ID. A restart catches up at most one missed occurrence inside bounded daily, weekly, or monthly windows. Delivery records retain status, attempt count, timestamps, and safe error codes, but not rendered email bodies, remote tracking images, click tracking, or a snapshot of an external email address.
Migrate Report API Clients Before Upgrade
The database migration converts existing enabled report settings into report definitions at 08:00 UTC so their previous delivery time remains unchanged. Disabled settings remain disabled and are not materialized. After that migration, the old handlers and old subscription storage are gone; requests to the removed routes return 404.
Use this mapping when updating a session-authenticated client:
| HitKeep 2.12 operation | HitKeep 2.13 replacement |
|---|---|
GET /api/user/report-subscriptions |
GET /api/reports |
PUT /api/user/report-subscriptions/digest |
POST /api/reports to create, then PATCH /api/reports/{report_id} to update a personal Portfolio Digest |
PUT /api/user/report-subscriptions/sites/{site_id} |
POST /api/reports to create, then PATCH /api/reports/{report_id} to update a personal Site Summary |
DigestSubscription |
ReportSchedule inside ReportDefinitionInput or ReportDefinitionUpdate |
SiteReportSubscription and ReportSubscriptions |
ReportDefinition, ReportRecipient, ReportRun, and ReportDelivery |
The replacement surface also adds operations for preview, test send, run history, failed-run retry, external-recipient confirmation, unsubscribe, and resubscribe. Generated clients should refresh from the 2.13 OpenAPI document because the removed schemas will no longer be present.
Other API changes in this release are additive. Social-authentication paths, team traffic-exclusion paths, database-status operations, and the report-definition paths are new. Existing instance and site exclusion creation payloads remain valid, including the legacy CIDR form that omits type. Exclusion responses retain their existing value fields and add scope, optional owner IDs, and inherited.
Social Sign-In Without Replacing Existing Login Methods
Self-hosted operators can configure OAuth client pairs for Google, GitHub, Microsoft, or any subset of the three. HitKeep lists only providers with a complete configuration. Open social signup has its own switch, so a provider can remain available for existing accounts and invitations without allowing uninvited account creation.
The browser flow uses short-lived, one-time state, PKCE S256, and an OIDC nonce where the provider supports OIDC. Return URLs stay inside the application. HitKeep resolves an account through the provider’s immutable identity, discards provider tokens after the exchange, and never treats an editable email address as the long-term identity key.
Google and GitHub verified-email flows can complete a normal signup without another email verification step. Microsoft identities do not provide the same verified-email guarantee, so the first unauthenticated Microsoft link or signup sends a HitKeep confirmation unless an authenticated session or matching invitation already proves the account boundary.
An authenticated user can link or unlink a social provider from security settings. Unlinking is refused when it would remove the last usable login method. Password, passkey, team OIDC SSO, MFA, and social sign-in keep their separate responsibilities: a social provider proves identity, while HitKeep still enforces team membership, site permissions, invitations, and any required second factor.
Traffic Controls Follow Ownership
Traffic exclusions now use the same ownership structure as the rest of HitKeep. Instance rules apply everywhere. Team rules follow every site currently owned by that team. Site rules stay attached to one site. Effective reads make inherited rules visible, but a team or site route cannot modify a rule owned by a parent scope.
Rules are additive and forward-only. HitKeep evaluates instance, current-team, and site rules, then drops a record when any rule matches. There are no allow overrides, and changing a rule does not rewrite historical analytics.
The two new match types cover traffic that network and country rules cannot express cleanly:
- User agent: case-insensitive substring matching for monitors, known clients, or other identifiable traffic.
- Path: case-sensitive segment-boundary matching after query strings, fragments, duplicate slashes, trailing slashes, and dot segments are normalized.
/adminmatches/admin/users, but not/administrator.
User-agent and path values are used transiently during filtering and do not add stored visitor fields. Filtering covers browser pageviews and events, Web Vitals, trusted server ingest, AI-fetch records, and dynamic QR opens. Matching ingest keeps its normal accepted response so the API does not reveal which filter matched.
Recovery Preserves Evidence Before Repair
DuckDB is embedded, but it still has a write-ahead log, checkpoint behavior, indexes, and failure modes that need explicit operating rules. Version 2.13.0 serializes periodic checkpoints and requires checkpoints around migrations, before backups, and during clean shutdown. An instance operator can inspect the sanitized database state and request an immediate checkpoint from System Status or the new admin API.
Automatic repair remains intentionally narrow. For the recognized non-unique-index invalidation, HitKeep first creates a permission-restricted, checksummed recovery bundle, then removes only implicated non-unique secondary indexes. Primary-key and unique indexes stay intact. A repair that finds no eligible index fails closed instead of reporting a false success.
The known migration WAL failure has a separate guard. Startup migrations run before the store is published to workers, record a checkpoint identity inside the database and a durable guard, then checkpoint after commit. HitKeep can bypass a migration-only WAL automatically only when those identities match. Bypassing an application WAL remains disabled by default because committed changes may exist only in that WAL; HITKEEP_DB_AUTO_RECOVER_WAL=true is an explicit availability-versus-data-loss decision.
While a shared or open tenant database is recovering, /healthz continues to report process liveness, while /readyz and database-dependent API or ingest routes return 503 with a stable reason and Retry-After: 5. If recovery cannot preserve evidence, verify disk space, or drain open connections, HitKeep stops instead of serving partial data.
Recovery bundles are local incident artifacts, not backup rotation. They can contain the same sensitive data as the live database and are never deleted automatically. Keep backing up the complete data path, including tenant databases, and keep recovery-bundle retention in the operator runbook.
Smaller, Bounded IP Metadata Work
HitKeep still derives country, region, city, provider, ASN, and ASN organization from embedded IP metadata without storing the raw visitor IP. The implementation now stores validated address directories and compressed blocks instead of inflating the full country, city, and network datasets at startup.
Lookup decodes only the block needed for an address, validates length, ordering, metadata references, and checksums, and keeps decoded data under separate bounded country, city, and ASN caches. The result keeps the same analytics dimensions while reducing embedded asset size and putting an upper bound on decoded range-block memory.
The bundled spam filter also moves from legacy Spamhaus feed handling to the provider’s JSON data, with schema validation and a refreshed default snapshot. Production filtering remains embedded and deterministic; a release does not need a runtime download token to start protecting ingest.
Contributor And Release Workflows Become Reproducible
For contributors, the new ./hk launcher is the source of truth for toolchain diagnosis, isolated workspace state, container-only development, screenshots, builds, smokes, and QA. A central developer MCP adapter exposes those operations to supported coding clients without giving them arbitrary shell execution or source-rewrite access.
Development is now one workspace session with status and event cursors. Finite setup, QA, build, and smoke operations use durable run IDs and bounded logs. That distinction lets a slow e2e or image gate continue even if one client disconnects, and lets contributors resume the exact run instead of starting a duplicate.
Release preparation receives the same treatment. Release Please owns the version manifest, changelog, dashboard package versions, MCP registry version, and Helm chart version. After a stable release is created, the release workflow builds and uploads binaries, checksums, the Helm chart, and hitkeep-configuration.json. Only after those artifacts succeed does it synchronize the docs repository’s machine-owned current-version and configuration files, validate the site, deploy that exact revision, and trigger the managed-cloud rollout.
Upgrade Checklist
- Back up the complete HitKeep data path and verify at least one recent restore before changing the running binary.
- Update any client that calls the three removed report-subscription routes, then regenerate typed clients from the 2.13 OpenAPI schema.
- Upgrade HitKeep and let migrations finish before accepting traffic. Existing enabled report subscriptions become reports at 08:00 UTC.
- Open Settings → Reporting, verify converted reports, choose a local timezone and time where needed, and send a test through the configured SMTP transport.
- If you add external recipients, confirm the consent invitation in a separate browser and verify that the delivery omits dashboard links.
- If you enable social sign-in, register the exact callback derived from
HITKEEP_PUBLIC_URL, configure only the providers you intend to expose, and test login, invitation, MFA, linking, and last-login-method protection. - Review instance, team, and site traffic filters with
effective=trueor the dashboard scope labels, especially after site transfers. - Confirm
HITKEEP_DB_RECOVERY_PATHhas suitable free space, keep application WAL bypass disabled unless incident policy explicitly accepts its loss boundary, and monitor readiness during the first restart.
What Does Not Change
HitKeep 2.13.0 keeps the same product boundary:
- one Go binary with the Angular dashboard embedded;
- DuckDB for storage and NSQ running in process;
- no required PostgreSQL, Redis, Kafka, ClickHouse, or separate report worker;
- cookie-free browser tracking by default;
- no raw visitor IP stored in analytics;
- open exports and complete account takeout; and
- the same open-source product foundation for self-hosted and managed cloud.
Scheduled reports add durable outbound mail delivery. Social sign-in adds optional provider connections. Recovery and traffic controls harden operation. None of them add a required external database, queue, cache, or identity service.
Read More
- Scheduled Email Reports
- REST API Reference
- Social sign-in configuration
- Traffic Exclusions and IP Filtering
- Disaster Recovery Runbook
- Backups and Restore
- Architecture and data lifecycle
- Runtime facts and limits
- Contributing to HitKeep
Self-hosted HitKeep includes scheduled reports, social sign-in, layered traffic controls, and guarded recovery in the same binary. If you want managed email delivery, backups, upgrades, and regional hosting, start a managed HitKeep Cloud deployment.