HF-307: warn once when a typed key enters its notice window (5/8)

[marcin-kordas-hoc]

Consumes the license key's notice field: a VALID typed key whose usage_until lies within notice days of the current UTC instant prints a single console warning naming the expiry date (with a (UTC) marker). Stacks on #1731; rebased onto its current head on 19.08 (the base moved during PR3/PR4's review passes, which had left this PR conflicting).

Why now

Per Kuba's D5-A (ClickUp, 12.08): hard blocking at/after expiry stays in 3.5.0 and the full rev 5 §4.1 window model is a follow-up — but trials made the notice warning concrete for this release: a trial is technically just a key with grace=0 and notice>0 whose warnings must surface in the console (packages meeting 12.08), and the trial mechanism lands in August.

What changed

• licenseResolution.ts: expiryWithinNoticeWindow() — usage-axis only (rev 5: notice/grace have no effect on the release_until axis), window ends exactly where the soft-stop phase would begin, blind to graceDays by design.
• licenseKeyValidator.ts: notifyLicenseKeyNotice() with per-key warn-once accounting (_noticedKeys keyed by the raw key string) — deliberately not the process-lifetime boolean the state messages use: two engines built with two different keys each get their own warning.
• Blocking behaviour at/after expiry is byte-identical to before; the key's silent flags suppress the warning; CHANGELOG entry included.

Verification

Paired tests: hyperformula-tests@spike/hf307-notice-window (authored RED-first, 8 assertions: inside/outside window, release_until never warns, expired still hard-blocks, silent suppresses, per-key warn-once across two engines). Full license suite 212/212 under Jest (12 suites, unit/license + unit/helpers/licenseKeyValidator), re-measured after the 19.08 rebase onto the current #1731 (e9863f27) — the earlier 165/165 predated PR3's and PR4's review fixes, tsc --noEmit clean, eslint --quiet clean on changed files.

🤖 Generated with Claude Code

---

Note

Low Risk
Console-only notice on the typed-key path; expiry blocking and entitlement logic are unchanged aside from the new warning hook.

Overview
Adds a one-time console warning when a still-valid typed license key’s usage-based expiry (usage_until) falls inside its configured notice period. The message names the expiry date with a (UTC) marker.

expiryWithinNoticeWindow in licenseResolution.ts applies only to the usage axis (not release_until), ends the window at the usage-until day boundary (ignores grace), and is wired from resolveLicense when the key is valid and not silent.

notifyLicenseKeyNotice in licenseKeyValidator.ts tracks warn-once per raw key string (_noticedKeys), separate from the existing once-per-page invalid/expired messaging. Test reset clears both flags.

Blocking at/after expiry is unchanged; silent flags suppress the new warning. CHANGELOG updated.

^{Reviewed by Cursor Bugbot for commit 7b5398d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: HF-307 Implement feature packages and add-ons in HF

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	aa835bf	Commit Preview URL Branch Preview URL	Aug 20 2026, 12:57 PM

[github-actions]

Performance comparison of head (aa835bf) vs base (e9863f2)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |   481.5 |  485.42 | +0.81%
                                      Sheet B |  150.34 |  150.55 | +0.14%
                                      Sheet T |  135.42 |  137.48 | +1.52%
                                Column ranges |  462.69 |  461.58 | -0.24%
                                Sorted lookup | 13836.8 | 14592.7 | +5.46%
Sheet A:  change value, add/remove row/column |   14.47 |   14.15 | -2.21%
 Sheet B: change value, add/remove row/column |  126.34 |  125.34 | -0.79%
                   Column ranges - add column |   144.9 |  142.11 | -1.93%
                Column ranges - without batch |  446.06 |  448.38 | +0.52%
                        Column ranges - batch |  113.82 |  112.79 | -0.90%

[marcin-kordas-hoc]

Paired tests PR: handsontable/hyperformula-tests#37 — merge it BEFORE this one (fetch-tests pairs by branch name).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.38%. Comparing base (e9863f2) to head (aa835bf).

Additional details and impacted files

@@                      Coverage Diff                       @@
##           hf-307-entitlement-gating-pr4    #1736   +/-   ##
==============================================================
  Coverage                          97.38%   97.38%           
==============================================================
  Files                                204      204           
  Lines                              16214    16236   +22     
  Branches                            3487     3493    +6     
==============================================================
+ Hits                               15790    15812   +22     
  Misses                               424      424           

Files with missing lines	Coverage Δ
src/Config.ts	94.69% <100.00%> (ø)
src/HyperFormula.ts	99.76% <100.00%> (ø)
src/helpers/licenseKeyValidator.ts	95.74% <100.00%> (+1.15%)	⬆️
src/license/licenseResolution.ts	97.43% <100.00%> (+0.29%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.