shabbat-gate 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this package are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.3] - 2026-07-12
+
+### Fixed
+
+- **Windows were computed for the wrong location past the nearest Shabbat.** `fetchWindows`
+  used to call two separate Hebcal endpoints: `/shabbat` (accurate for the given
+  `latitude`/`longitude`, but - confirmed by testing live against the API - it silently
+  ignores the requested `start`/`end` range and always returns only the single nearest
+  Shabbat) and `/hebcal` for holidays (which took a hardcoded `geonameid` for Jerusalem,
+  never the coordinates passed in). Net effect: only the very next Shabbat was ever
+  correctly localized; every window after that was computed for Jerusalem regardless of
+  the site's configured location.
+- **Duplicate/inconsistent windows around the nearest Shabbat**, a direct consequence of
+  the bug above - the two endpoints could both emit a window for the same week, a few
+  minutes apart, with nothing merging or de-duplicating them.
+- **A holiday's Hebrew label could leak into the following, unrelated Shabbat window.**
+  `pairWindows` tracked "the most recently seen holiday item" as a running pointer. Some
+  `holiday`-category items - fast days such as Tish'a B'Av, which are `maj=on` but have no
+  candle-lighting/havdalah of their own - never got consumed into a window, so their label
+  stayed "current" and was wrongly attached to the next real window (e.g. an ordinary
+  Shabbat mislabeled with the fast day's name). Fixed by matching each window's opening
+  `candles` event to a holiday via Hebcal's own `memo` field instead of positional
+  tracking.
+
+**Root fix for both window bugs**: `fetchWindows` now makes a single call to the
+`/hebcal` endpoint with `ss=on` (weekly Shabbat) added alongside `maj=on` (major
+holidays), passing `latitude`/`longitude` directly instead of a `geonameid`. This
+returns every window in the requested range, correctly localized, already merged and
+chronologically ordered - eliminating the two-source reconciliation that caused both bugs.
+
+### Added
+
+- `ShabbatGateConfig.bufferMinutes` - closes the site a configurable number of minutes
+  *before* candle-lighting and reopens it the same number of minutes *after* havdalah, on
+  top of the raw Hebcal window. Applied at decision time (not baked into the 24h cache), so
+  changing it takes effect immediately.
+- `createShabbatGateForWorker(config)` - an adapter for plain Cloudflare Workers with a
+  static `assets` binding (as opposed to Pages Functions). Returns
+  `(request: Request) => Promise<Response | null>`: `null` means "let the real site
+  through", a `Response` means "serve the holding page". Shares all fail-open/caching/
+  bypass logic with `createShabbatGate` internally, so the two can't drift apart.
+- `INTERNAL_CACHE_KEY_URL` export - the fixed internal Workers-Cache-API key this package
+  uses to cache the merged window list for ~24h. Exported so consumers doing their own
+  caching of derived data (e.g. windows with a hand-rolled buffer) can pick a different key
+  and avoid silently serving stale data for up to a day.
+
+## [0.1.2] - 2026-07-10
+
+### Fixed
+
+- Holding page showed the generic literal "הדלקת נרות"/"הבדלה" as the closure reason for
+  every window, Shabbat or holiday alike (Hebcal's `candles`/`havdalah` items always carry
+  that generic text in their `hebrew` field, never the actual occasion name). Plain Shabbat
+  weeks now default to "שבת קודש" (opening) / "השבת" (closing); holiday windows pick up the
+  holiday's own Hebrew name (e.g. "ערב ראש השנה").
+
+### Documentation
+
+- Documented the Cloudflare Worker + `assets` binding `run_worker_first: true` gotcha:
+  without it, requests matching a static asset are served directly and the gate's `fetch`
+  handler never runs, so the site never actually closes despite looking correctly wired up.
+  Found live in production on the package's first real-world Worker (non-Pages) deployment.
+
+## [0.1.1] - 2026-07-10
+
+### Added
+
+- Hebrew README (`README.he.md`), for the package's primary intended audience.
+
+## [0.1.0] - 2026-07-10
+
+### Added
+
+- Initial release: bot/crawler allowlist, Hebcal Shabbat + major-holiday window fetching
+  (Israel single-day Yom Tov mode), `createShabbatGate` Pages Functions middleware,
+  bypass query param, ~24h caching via the Workers Cache API, and fail-open error handling.

package/README.he.md

@@ -1,90 +1,155 @@
-# shabbat-gate
-
-Middleware ל-Cloudflare Pages / Workers שסוגר אתר לגולשים אנושיים בזמן שבת וחגי ישראל
-המרכזיים (לפי כללי שמירת שבת בישראל) - תוך מתן גישה תמידית למנועי חיפוש ולסורקי AI, כך
-שה-SEO לא נפגע.
-
-[English README](README.md)
-
-## למה זה עובד ככה
-
-- **יום טוב חד-יומי לפי ישראל, לא ספירת חו"ל.** לוח החגים נשלף מה-API החינמי של Hebcal
-  עם הפרמטר `i=on`, שקריטי - בלעדיו מתקבלת ספירת חו"ל (יום חסימה מיותר) במקום יום טוב
-  חד-יומי, כפי שנהוג בישראל.
-- **בוטים תמיד עוברים.** רשימת אלוול רחבה, לא תלוית רישיות, של user-agent (Googlebot,
-  Bingbot, GPTBot, ClaudeBot ורבים נוספים) נבדקת ראשונה, לפני כל שאר הלוגיקה. השער משפיע
-  רק על גולשים אנושיים - סורקים ומנועי אינדוקס רואים את האתר האמיתי 24/7, כך שדירוג
-  וניראות ב-AI-search לא נפגעים מכך שהאתר "סגור".
-- **נכשל פתוח (Fail open).** כל שגיאה (תקלת רשת, תשובת API לא תקינה, מה שלא יהיה) גורמת
-  למעבר לאתר האמיתי במקום הצגת דף שגיאה. חסימה בטעות ביום שלישי רגיל היא באג אמיתי וגלוי;
-  אי-חסימה נדירה בזמן שגיאה היא תקלה קטנה ובלתי נראית.
-
-## התקנה
-
-```sh
-npm install shabbat-gate
-```
-
-## שימוש
-
-בפרויקט Cloudflare Pages, מוסיפים קובץ `functions/_middleware.ts`:
-
-```ts
-import { createShabbatGate } from 'shabbat-gate';
-
-const gate = createShabbatGate({ siteName: 'שם האתר שלי' });
-
-export const onRequest: PagesFunction = (context) => gate(context);
-```
-
-## קונפיגורציה
-
-```ts
-export interface ShabbatGateConfig {
-  siteName: string;
-
-  /** קווי אורך/רוחב עשרוניים לחישוב זמנים. ברירת מחדל לשניהם היא ירושלים (31.7683,
-   *  35.2137) אם לא סופקו - נקודת ייחוס טובה לכל ישראל ברזולוציה הזו. */
-  latitude?: number;
-  longitude?: number;
-
-  /** שם פרמטר + ערך נדרש ב-query string שעוקפים את השער לגמרי, כדי שבעל האתר יוכל
-   *  לבדוק/לתצוגה מקדימה בכל יום. חשוב לבחור ערך שלא ניתן לניחוש - זו נוחות לבדיקות,
-   *  לא הרשאה אמיתית. */
-  bypassParam?: string;
-  bypassValue?: string;
-
-  /** פונקציית רינדור מותאמת אישית לדף ה"סגור", אופציונלית. ברירת המחדל היא דף בעברית,
-   *  רספונסיבי למובייל, שמציג את שם האתר ומתי הוא ייפתח מחדש. */
-  renderHoldingPage?: (ctx: { siteName: string; reasonLabel: string; untilLabel: string }) => string;
-}
-```
-
-דוגמה מלאה:
-
-```ts
-import { createShabbatGate } from 'shabbat-gate';
-
-const gate = createShabbatGate({
-  siteName: 'tehila·games',
-  latitude: 31.7683,
-  longitude: 35.2137,
-  bypassParam: 'preview',
-  bypassValue: 'letmein-9f3a7c',
-});
-
-export const onRequest: PagesFunction = (context) => gate(context);
-```
-
-## איך זה עובד
-
-1. בדיקת בוט (regex אלוול על header ה-`user-agent`) - התאמה עוברת ישירות.
-2. בדיקת bypass - אם פרמטר ה-query וערכו תואמים, עוברים ישירות.
-3. שליפה (עם caching לכ-24 שעות דרך Workers Cache API) של רשימת חלונות שבת וחגים
-   מאוחדת מ-Hebcal, כ-45 יום קדימה.
-4. אם הזמן הנוכחי נופל בתוך חלון, מוצג דף ה"סגור" (HTTP 200). אחרת, האתר האמיתי עובר.
-5. כל שגיאה בדרך גורמת למעבר לאתר האמיתי.
-
-## רישיון
-
-MIT
+# shabbat-gate
+
+Middleware ל-Cloudflare Pages / Workers שסוגר אתר לגולשים אנושיים בזמן שבת וחגי ישראל
+המרכזיים (לפי כללי שמירת שבת בישראל) - תוך מתן גישה תמידית למנועי חיפוש ולסורקי AI, כך
+שה-SEO לא נפגע.
+
+[English README](README.md)
+
+## למה זה עובד ככה
+
+- **יום טוב חד-יומי לפי ישראל, לא ספירת חו"ל.** לוח החגים נשלף מה-API החינמי של Hebcal
+  עם הפרמטר `i=on`, שקריטי - בלעדיו מתקבלת ספירת חו"ל (יום חסימה מיותר) במקום יום טוב
+  חד-יומי, כפי שנהוג בישראל.
+- **בוטים תמיד עוברים.** רשימת אלוול רחבה, לא תלוית רישיות, של user-agent (Googlebot,
+  Bingbot, GPTBot, ClaudeBot ורבים נוספים) נבדקת ראשונה, לפני כל שאר הלוגיקה. השער משפיע
+  רק על גולשים אנושיים - סורקים ומנועי אינדוקס רואים את האתר האמיתי 24/7, כך שדירוג
+  וניראות ב-AI-search לא נפגעים מכך שהאתר "סגור".
+- **נכשל פתוח (Fail open).** כל שגיאה (תקלת רשת, תשובת API לא תקינה, מה שלא יהיה) גורמת
+  למעבר לאתר האמיתי במקום הצגת דף שגיאה. חסימה בטעות ביום שלישי רגיל היא באג אמיתי וגלוי;
+  אי-חסימה נדירה בזמן שגיאה היא תקלה קטנה ובלתי נראית.
+
+## התקנה
+
+```sh
+npm install shabbat-gate
+```
+
+## שימוש
+
+בפרויקט Cloudflare Pages, מוסיפים קובץ `functions/_middleware.ts`:
+
+```ts
+import { createShabbatGate } from 'shabbat-gate';
+
+const gate = createShabbatGate({ siteName: 'שם האתר שלי' });
+
+export const onRequest: PagesFunction = (context) => gate(context);
+```
+
+### שימוש עם Worker רגיל + assets binding (לא Pages)
+
+`createShabbatGate` מחזירה handler בצורה של Pages Functions (`(context) => Response`), וזה
+לא מתאים ל-signature של `fetch(request, env)` של Worker רגיל (אין `next()`). במקום זאת יש
+להשתמש ב-`createShabbatGateForWorker` - היא מחזירה `null` כשצריך לתת לאתר האמיתי לעבור, ו-
+`Response` כשצריך להציג את דף ה"סגור":
+
+```ts
+import { createShabbatGateForWorker } from 'shabbat-gate';
+
+const gate = createShabbatGateForWorker({ siteName: 'שם האתר שלי' });
+
+export default {
+  async fetch(request: Request, env: { ASSETS: Fetcher }) {
+    const blocked = await gate(request);
+    return blocked ?? env.ASSETS.fetch(request);
+  },
+};
+```
+
+**מוקש שמבטל את כל השער בשקט:** Cloudflare Worker עם `assets` binding מגיש כל בקשה שתואמת
+קובץ בתיקיית ה-assets **ישירות**, בלי להריץ בכלל את ה-`fetch` handler של ה-Worker - אלא אם
+מגדירים `run_worker_first: true`. בלי זה, קוד השער רץ ונראה מחובר נכון, הבדיקות עוברות, אבל
+בקשות אמיתיות לעמודים (שכמעט תמיד תואמות קובץ סטטי) אף פעם לא מגיעות אליו, אז האתר בפועל
+אף פעם לא נסגר. ב-`wrangler.jsonc`:
+
+```jsonc
+{
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "run_worker_first": true
+  }
+}
+```
+
+## קונפיגורציה
+
+```ts
+export interface ShabbatGateConfig {
+  siteName: string;
+
+  /** קווי אורך/רוחב עשרוניים לחישוב זמנים. ברירת מחדל לשניהם היא ירושלים (31.7683,
+   *  35.2137) אם לא סופקו - נקודת ייחוס טובה לכל ישראל ברזולוציה הזו. */
+  latitude?: number;
+  longitude?: number;
+
+  /** שם פרמטר + ערך נדרש ב-query string שעוקפים את השער לגמרי, כדי שבעל האתר יוכל
+   *  לבדוק/לתצוגה מקדימה בכל יום. חשוב לבחור ערך שלא ניתן לניחוש - זו נוחות לבדיקות,
+   *  לא הרשאה אמיתית. */
+  bypassParam?: string;
+  bypassValue?: string;
+
+  /** פונקציית רינדור מותאמת אישית לדף ה"סגור", אופציונלית. ברירת המחדל היא דף בעברית,
+   *  רספונסיבי למובייל, שמציג את שם האתר ומתי הוא ייפתח מחדש. `reasonLabel` ו-`closingLabel`
+   *  שונים דקדוקית עבור שבת רגילה ("שבת קודש" בפתיחה מול "השבת" בסגירה) - יש להשתמש
+   *  ב-`closingLabel` עבור "ניפגש שוב אחרי ___", לא לחזור על `reasonLabel`. */
+  renderHoldingPage?: (ctx: {
+    siteName: string;
+    reasonLabel: string;
+    closingLabel: string;
+    untilLabel: string;
+  }) => string;
+
+  /** דקות לסגור את האתר *לפני* הדלקת נרות ולפתוח אותו *אחרי* הבדלה, מעל החלון הגולמי
+   *  מ-Hebcal. ברירת מחדל: 0. שימושי כרפידת בטחון מול סחיפת שעון / גלישה של הרגע
+   *  האחרון בדיוק בגבול החלון. */
+  bufferMinutes?: number;
+}
+```
+
+דוגמה מלאה:
+
+```ts
+import { createShabbatGate } from 'shabbat-gate';
+
+const gate = createShabbatGate({
+  siteName: 'tehila·games',
+  latitude: 31.7683,
+  longitude: 35.2137,
+  bypassParam: 'preview',
+  bypassValue: 'letmein-9f3a7c',
+  bufferMinutes: 10,
+});
+
+export const onRequest: PagesFunction = (context) => gate(context);
+```
+
+## איך זה עובד
+
+1. בדיקת בוט (regex אלוול על header ה-`user-agent`) - התאמה עוברת ישירות.
+2. בדיקת bypass - אם פרמטר ה-query וערכו תואמים, עוברים ישירות.
+3. שליפה (עם caching לכ-24 שעות דרך Workers Cache API) של רשימת חלונות שבת וחגים
+   מאוחדת מ-Hebcal, כ-45 יום קדימה - קריאה אחת ל-endpoint `/hebcal` (`ss=on` לשבתות
+   שבועיות + `maj=on` לחגים מרכזיים), עם `latitude`/`longitude` מועברים ישירות, כך שכל
+   חלון מחושב נכון למיקום שהוגדר, לא רק החלון הקרוב ביותר.
+4. אם הוגדר `bufferMinutes`, הוא מוחל מעל החלונות שנשלפו לפני בדיקת הזמן.
+5. אם הזמן הנוכחי נופל בתוך חלון, מוצג דף ה"סגור" (HTTP 200). אחרת, האתר האמיתי עובר.
+6. כל שגיאה בדרך גורמת למעבר לאתר האמיתי.
+
+## מפתח קאש פנימי
+
+רשימת החלונות המאוחדת נשמרת בקאש תחת מפתח פנימי קבוע
+(`https://internal.cache/shabbat-gate-windows-v1`, מיוצא בשם `INTERNAL_CACHE_KEY_URL`) לכ-24
+שעות דרך Workers Cache API. אם הקוד שלכם עושה caching משלו לנתונים נגזרים (למשל חלונות עם
+buffer משלכם), כדאי להשתמש במפתח אחר - שימוש חוזר במפתח הזה יגרום בשקט להחזרת נתונים ישנים
+ולא-מעובדים למשך עד 24 שעות.
+
+## היסטוריית שינויים
+
+ב-[CHANGELOG.md](CHANGELOG.md) (באנגלית) מתועד מה השתנה בכל גרסה, כולל הסבר לשורש כל
+באג שתוקן.
+
+## רישיון
+
+MIT

package/README.md

@@ -1,91 +1,156 @@
-# shabbat-gate
-
-[קריאה בעברית](README.he.md)
-
-Cloudflare Pages / Workers middleware that automatically closes a site to human visitors
-during Shabbat and major Jewish holidays (Israel-observance rules) - while always letting
-search engines and AI crawlers through, so SEO stays unaffected.
-
-## Why
-
-- **Israel single-day Yom Tov, not diaspora 2-day.** The holiday calendar is fetched from
-  Hebcal's free public API with `i=on`, which is critical - without it you'd get the diaspora
-  reckoning (an extra blocked day) instead of the correct single-day Yom Tov used in Israel.
-- **Bots always get through.** A broad, case-insensitive user-agent allowlist (Googlebot,
-  Bingbot, GPTBot, ClaudeBot, and many others) is checked first, before any other logic runs.
-  The gate only ever affects human visitors - crawlers and indexers see the real site 24/7, so
-  ranking and AI-search visibility are never impacted by the site being "closed."
-- **Fails open.** Any error (network failure, bad API response, whatever) falls through to the
-  real site rather than showing an error page. An accidental block on a regular Tuesday would be
-  a real, visible bug; an occasional missed block during a rare error is a minor, invisible one.
-
-## Install
-
-```sh
-npm install shabbat-gate
-```
-
-## Usage
-
-In a Cloudflare Pages project, add `functions/_middleware.ts`:
-
-```ts
-import { createShabbatGate } from 'shabbat-gate';
-
-const gate = createShabbatGate({ siteName: 'My Site' });
-
-export const onRequest: PagesFunction = (context) => gate(context);
-```
-
-## Config
-
-```ts
-export interface ShabbatGateConfig {
-  siteName: string;
-
-  /** Decimal lat/long for zmanim. Both default to Jerusalem (31.7683, 35.2137) if
-   *  omitted - a fine single reference point for all of Israel at this granularity. */
-  latitude?: number;
-  longitude?: number;
-
-  /** Query param name + required value that bypasses the gate entirely, so the site
-   *  owner can preview/test on any day. Keep the value non-guessable - this is a
-   *  testing convenience, not real auth. */
-  bypassParam?: string;
-  bypassValue?: string;
-
-  /** Optional custom holding-page renderer. Defaults to a Hebrew, mobile-responsive
-   *  page showing siteName and when the site reopens. */
-  renderHoldingPage?: (ctx: { siteName: string; reasonLabel: string; untilLabel: string }) => string;
-}
-```
-
-Full example:
-
-```ts
-import { createShabbatGate } from 'shabbat-gate';
-
-const gate = createShabbatGate({
-  siteName: 'tehila·games',
-  latitude: 31.7683,
-  longitude: 35.2137,
-  bypassParam: 'preview',
-  bypassValue: 'letmein-9f3a7c',
-});
-
-export const onRequest: PagesFunction = (context) => gate(context);
-```
-
-## How it works
-
-1. Bot check (allowlist regex on the `user-agent` header) - matches pass straight through.
-2. Bypass check - if the bypass query param + value match, pass straight through.
-3. Fetch (with ~24h caching via the Workers Cache API) the merged list of Shabbat and major
-   holiday windows from Hebcal, ~45 days into the future.
-4. If the current time falls inside a window, serve the holding page (HTTP 200). Otherwise let
-   the real site through.
-5. Any error along the way falls through to the real site.
-
-## License
-
-MIT
+# shabbat-gate
+
+[קריאה בעברית](README.he.md)
+
+Cloudflare Pages / Workers middleware that automatically closes a site to human visitors
+during Shabbat and major Jewish holidays (Israel-observance rules) - while always letting
+search engines and AI crawlers through, so SEO stays unaffected.
+
+## Why
+
+- **Israel single-day Yom Tov, not diaspora 2-day.** The holiday calendar is fetched from
+  Hebcal's free public API with `i=on`, which is critical - without it you'd get the diaspora
+  reckoning (an extra blocked day) instead of the correct single-day Yom Tov used in Israel.
+- **Bots always get through.** A broad, case-insensitive user-agent allowlist (Googlebot,
+  Bingbot, GPTBot, ClaudeBot, and many others) is checked first, before any other logic runs.
+  The gate only ever affects human visitors - crawlers and indexers see the real site 24/7, so
+  ranking and AI-search visibility are never impacted by the site being "closed."
+- **Fails open.** Any error (network failure, bad API response, whatever) falls through to the
+  real site rather than showing an error page. An accidental block on a regular Tuesday would be
+  a real, visible bug; an occasional missed block during a rare error is a minor, invisible one.
+
+## Install
+
+```sh
+npm install shabbat-gate
+```
+
+## Usage
+
+In a Cloudflare Pages project, add `functions/_middleware.ts`:
+
+```ts
+import { createShabbatGate } from 'shabbat-gate';
+
+const gate = createShabbatGate({ siteName: 'My Site' });
+
+export const onRequest: PagesFunction = (context) => gate(context);
+```
+
+### Using with a plain Worker + Assets binding (not Pages)
+
+`createShabbatGate` returns a Pages-Functions-shaped handler (`(context) => Response`), which
+doesn't fit a plain Worker's `fetch(request, env)` signature (there's no `next()`). Use
+`createShabbatGateForWorker` instead - it returns `null` for "let the real site through" and a
+`Response` for "serve the holding page":
+
+```ts
+import { createShabbatGateForWorker } from 'shabbat-gate';
+
+const gate = createShabbatGateForWorker({ siteName: 'My Site' });
+
+export default {
+  async fetch(request: Request, env: { ASSETS: Fetcher }) {
+    const blocked = await gate(request);
+    return blocked ?? env.ASSETS.fetch(request);
+  },
+};
+```
+
+**Gotcha that silently defeats the whole gate:** a Cloudflare Worker with an `assets` binding
+serves any request matching a file in the assets directory *directly*, without invoking the
+Worker's `fetch` handler at all - unless `run_worker_first: true` is set. Without it, the gate
+code runs and looks correctly wired up, tests pass, but real page requests (which almost always
+match a static asset) never reach it, so the site never actually closes. In `wrangler.jsonc`:
+
+```jsonc
+{
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "run_worker_first": true
+  }
+}
+```
+
+## Config
+
+```ts
+export interface ShabbatGateConfig {
+  siteName: string;
+
+  /** Decimal lat/long for zmanim. Both default to Jerusalem (31.7683, 35.2137) if
+   *  omitted - a fine single reference point for all of Israel at this granularity. */
+  latitude?: number;
+  longitude?: number;
+
+  /** Query param name + required value that bypasses the gate entirely, so the site
+   *  owner can preview/test on any day. Keep the value non-guessable - this is a
+   *  testing convenience, not real auth. */
+  bypassParam?: string;
+  bypassValue?: string;
+
+  /** Optional custom holding-page renderer. Defaults to a Hebrew, mobile-responsive
+   *  page showing siteName and when the site reopens. `reasonLabel` and `closingLabel`
+   *  differ grammatically for plain Shabbat ("שבת קודש" opening vs. "השבת" closing) -
+   *  use `closingLabel` for "back after ___", not `reasonLabel` again. */
+  renderHoldingPage?: (ctx: {
+    siteName: string;
+    reasonLabel: string;
+    closingLabel: string;
+    untilLabel: string;
+  }) => string;
+
+  /** Minutes to close the site *before* candle-lighting and reopen *after*
+   *  havdalah, on top of the raw Hebcal window. Defaults to 0. Useful padding
+   *  against clock drift / last-minute browsing right at the boundary. */
+  bufferMinutes?: number;
+}
+```
+
+Full example:
+
+```ts
+import { createShabbatGate } from 'shabbat-gate';
+
+const gate = createShabbatGate({
+  siteName: 'tehila·games',
+  latitude: 31.7683,
+  longitude: 35.2137,
+  bypassParam: 'preview',
+  bypassValue: 'letmein-9f3a7c',
+  bufferMinutes: 10,
+});
+
+export const onRequest: PagesFunction = (context) => gate(context);
+```
+
+## How it works
+
+1. Bot check (allowlist regex on the `user-agent` header) - matches pass straight through.
+2. Bypass check - if the bypass query param + value match, pass straight through.
+3. Fetch (with ~24h caching via the Workers Cache API) the merged list of Shabbat and major
+   holiday windows from Hebcal, ~45 days into the future - one call to Hebcal's `/hebcal`
+   endpoint (`ss=on` for weekly Shabbat + `maj=on` for major holidays), passing `latitude`/
+   `longitude` directly so every window is correctly localized, not just the nearest one.
+4. `bufferMinutes` (if set) is applied on top of the fetched windows before the time check.
+5. If the current time falls inside a window, serve the holding page (HTTP 200). Otherwise let
+   the real site through.
+6. Any error along the way falls through to the real site.
+
+## Internal cache key
+
+The merged window list is cached under a fixed internal key
+(`https://internal.cache/shabbat-gate-windows-v1`, exported as `INTERNAL_CACHE_KEY_URL`) for
+~24h via the Workers Cache API. If your own code also caches derived data (e.g. windows with
+your own buffer applied) via `caches.default`, use a different key - reusing this one will
+silently serve stale, unprocessed data for up to 24h.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed in each release, including root-cause
+explanations for fixed bugs.
+
+## License
+
+MIT

package/dist/hebcal.d.ts

@@ -1,13 +1,24 @@
 export interface Window {
     start: number;
     end: number;
+    /** Hebrew label for "the site is closed for ___". */
     label: string;
+    /** Hebrew label for "back after ___ [ends]" - grammatically distinct from
+     *  `label` for Shabbat ("שבת קודש" opening vs. "השבת" closing). */
+    closingLabel: string;
 }
 interface HebcalItem {
     title: string;
     hebrew?: string;
     date: string;
     category: string;
+    /** Present on `candles`/`havdalah` items: the title of the holiday/parasha
+     *  it belongs to (e.g. "Erev Rosh Hashana", or "Parashat Devarim" for a
+     *  plain Shabbat week). Used to cross-reference against `holiday` items'
+     *  own `title` to find the right Hebrew label for *this specific* window,
+     *  instead of trusting whichever `holiday` item happened to appear most
+     *  recently in the feed (which leaks into unrelated windows - see below). */
+    memo?: string;
 }
 /**
  * Pairs candles/havdalah events into continuous windows. Multi-day holidays
@@ -15,11 +26,39 @@ interface HebcalItem {
  * very end, so candles cannot simply be paired 1:1 with the next havdalah.
  * Instead: open a window on the first candles seen while none is open, ignore
  * further candles while one is open, and close on the next havdalah.
+ *
+ * `defaults` overrides the label for windows that have no matching `holiday`
+ * item (i.e. plain Shabbat weeks) - pass it when calling this with a merged
+ * feed that mixes weekly Shabbat and holiday items together.
+ *
+ * Holiday windows pick up the matching `holiday` item's own Hebrew name (e.g.
+ * "ערב ראש השנה") by matching the opening `candles` item's `memo` field
+ * against a `holiday` item's `title` - not just "the most recent holiday item
+ * seen so far". Some `holiday`-category items (e.g. fast days like תשעה באב,
+ * which are `maj=on` but have no candle-lighting of their own) never get
+ * consumed by a window; naively tracking "last holiday label seen" would leak
+ * their label into the next, unrelated Shabbat window instead of falling back
+ * to `defaults`.
  */
-export declare function pairWindows(items: HebcalItem[]): Window[];
+export declare function pairWindows(items: HebcalItem[], defaults?: {
+    label: string;
+    closingLabel: string;
+}): Window[];
 /**
  * Fetches and merges Shabbat + major-holiday (Israel single-day Yom Tov mode)
  * windows for the next ~45 days from Hebcal's free public JSON API.
+ *
+ * Uses a *single* call to the `/hebcal` endpoint (not the separate `/shabbat`
+ * endpoint) with `ss=on` added, passing `latitude`/`longitude` directly
+ * instead of a `geonameid`. Two real bugs motivated this over the previous
+ * two-call approach: (1) `/shabbat?start=...&end=...` silently ignores the
+ * requested range and only ever returns the single nearest Shabbat,
+ * regardless of how far out `end` is; (2) `geonameid` always resolves to a
+ * fixed city (Jerusalem), so every week after the nearest one was computed
+ * for the wrong location instead of the coordinates passed in. Querying
+ * `/hebcal` with `ss=on` + lat/long returns every Shabbat and holiday in the
+ * range, correctly localized, in one chronologically-ordered, already-merged
+ * list - which also means there's nothing left to de-duplicate.
  */
 export declare function fetchWindows(latitude: number, longitude: number): Promise<Window[]>;
 /** Pure function: is `now` inside any of the given windows? */

package/dist/hebcal.js

@@ -1,26 +1,58 @@
-const HEBCAL_JERUSALEM_GEONAME_ID = 281184;
+/** Hebcal's own "candles"/"havdalah" items always carry the generic literal
+ *  "הדלקת נרות"/"הבדלה" in their `hebrew` field, never the occasion name - so
+ *  it's unusable as a display label on its own. For a plain Shabbat week
+ *  (no accompanying `holiday` item), fall back to this fixed pair instead. */
+const SHABBAT_LABEL = 'שבת קודש';
+const SHABBAT_CLOSING_LABEL = 'השבת';
 /**
  * Pairs candles/havdalah events into continuous windows. Multi-day holidays
  * (e.g. Rosh Hashana) emit two "candles" events but only one "havdalah" at the
  * very end, so candles cannot simply be paired 1:1 with the next havdalah.
  * Instead: open a window on the first candles seen while none is open, ignore
  * further candles while one is open, and close on the next havdalah.
+ *
+ * `defaults` overrides the label for windows that have no matching `holiday`
+ * item (i.e. plain Shabbat weeks) - pass it when calling this with a merged
+ * feed that mixes weekly Shabbat and holiday items together.
+ *
+ * Holiday windows pick up the matching `holiday` item's own Hebrew name (e.g.
+ * "ערב ראש השנה") by matching the opening `candles` item's `memo` field
+ * against a `holiday` item's `title` - not just "the most recent holiday item
+ * seen so far". Some `holiday`-category items (e.g. fast days like תשעה באב,
+ * which are `maj=on` but have no candle-lighting of their own) never get
+ * consumed by a window; naively tracking "last holiday label seen" would leak
+ * their label into the next, unrelated Shabbat window instead of falling back
+ * to `defaults`.
  */
-export function pairWindows(items) {
+export function pairWindows(items, defaults) {
     const windows = [];
+    const holidayTitles = new Map();
     let openStart = null;
     let openLabel = '';
+    let openClosingLabel = '';
     for (const item of items) {
+        if (item.category === 'holiday') {
+            holidayTitles.set(item.title, item.hebrew ?? item.title);
+        }
         if (item.category === 'candles') {
             if (openStart === null) {
                 openStart = new Date(item.date).getTime();
-                openLabel = item.hebrew ?? item.title;
+                const matchedHoliday = item.memo ? holidayTitles.get(item.memo) : undefined;
+                const label = matchedHoliday ?? defaults?.label ?? item.hebrew ?? item.title;
+                openLabel = label;
+                openClosingLabel = matchedHoliday ? label : (defaults?.closingLabel ?? label);
             }
         }
         else if (item.category === 'havdalah' && openStart !== null) {
-            windows.push({ start: openStart, end: new Date(item.date).getTime(), label: openLabel });
+            windows.push({
+                start: openStart,
+                end: new Date(item.date).getTime(),
+                label: openLabel,
+                closingLabel: openClosingLabel,
+            });
             openStart = null;
             openLabel = '';
+            openClosingLabel = '';
         }
     }
     return windows;
@@ -31,31 +63,37 @@ function toISODate(date) {
 /**
  * Fetches and merges Shabbat + major-holiday (Israel single-day Yom Tov mode)
  * windows for the next ~45 days from Hebcal's free public JSON API.
+ *
+ * Uses a *single* call to the `/hebcal` endpoint (not the separate `/shabbat`
+ * endpoint) with `ss=on` added, passing `latitude`/`longitude` directly
+ * instead of a `geonameid`. Two real bugs motivated this over the previous
+ * two-call approach: (1) `/shabbat?start=...&end=...` silently ignores the
+ * requested range and only ever returns the single nearest Shabbat,
+ * regardless of how far out `end` is; (2) `geonameid` always resolves to a
+ * fixed city (Jerusalem), so every week after the nearest one was computed
+ * for the wrong location instead of the coordinates passed in. Querying
+ * `/hebcal` with `ss=on` + lat/long returns every Shabbat and holiday in the
+ * range, correctly localized, in one chronologically-ordered, already-merged
+ * list - which also means there's nothing left to de-duplicate.
  */
 export async function fetchWindows(latitude, longitude) {
     const start = new Date();
     const end = new Date(start.getTime() + 45 * 24 * 60 * 60 * 1000);
     const startParam = toISODate(start);
     const endParam = toISODate(end);
-    const shabbatUrl = `https://www.hebcal.com/shabbat?cfg=json&latitude=${latitude}&longitude=${longitude}` +
-        `&tzid=Asia/Jerusalem&M=on&start=${startParam}&end=${endParam}`;
     // i=on = Israel single-day Yom Tov reckoning (not diaspora 2-day).
     // c=on = attach candles/havdalah entries to holidays, not just bare dates.
+    // ss=on = weekly Shabbat candle-lighting/havdalah, localized to lat/long.
     // maj=on + everything else off = only real work-restricted Yom Tov days.
-    const holidayUrl = `https://www.hebcal.com/hebcal?cfg=json&v=1&maj=on&min=off&mod=off&nx=off&mf=off&ss=off` +
-        `&c=on&i=on&geonameid=${HEBCAL_JERUSALEM_GEONAME_ID}&start=${startParam}&end=${endParam}`;
-    const [shabbatRes, holidayRes] = await Promise.all([fetch(shabbatUrl), fetch(holidayUrl)]);
-    if (!shabbatRes.ok || !holidayRes.ok) {
-        throw new Error(`hebcal fetch failed: shabbat=${shabbatRes.status} holiday=${holidayRes.status}`);
+    const url = `https://www.hebcal.com/hebcal?cfg=json&v=1&maj=on&min=off&mod=off&nx=off&mf=off&ss=on` +
+        `&c=on&i=on&latitude=${latitude}&longitude=${longitude}&tzid=Asia/Jerusalem` +
+        `&start=${startParam}&end=${endParam}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`hebcal fetch failed: ${res.status}`);
     }
-    const [shabbatData, holidayData] = (await Promise.all([
-        shabbatRes.json(),
-        holidayRes.json(),
-    ]));
-    const windows = [
-        ...pairWindows(shabbatData.items ?? []),
-        ...pairWindows(holidayData.items ?? []),
-    ];
+    const data = (await res.json());
+    const windows = pairWindows(data.items ?? [], { label: SHABBAT_LABEL, closingLabel: SHABBAT_CLOSING_LABEL });
     return windows.sort((a, b) => a.start - b.start);
 }
 /** Pure function: is `now` inside any of the given windows? */

package/dist/holdingPage.d.ts

@@ -1,6 +1,7 @@
 export interface HoldingPageContext {
     siteName: string;
     reasonLabel: string;
+    closingLabel: string;
     untilLabel: string;
 }
 /** Simple, centered, mobile-responsive holding page. Inline CSS only, no external assets. */

package/dist/holdingPage.js

@@ -30,7 +30,7 @@ export function defaultRenderHoldingPage(ctx) {
 <body>
   <div class="card">
     <h1>${ctx.siteName}</h1>
-    <p>האתר סגור לכבוד ${ctx.reasonLabel}, ניפגש שוב אחרי הצאת ${ctx.reasonLabel}.</p>
+    <p>האתר סגור לכבוד ${ctx.reasonLabel}, ניפגש שוב אחרי צאת ${ctx.closingLabel}.</p>
     <p class="until">שעת פתיחה משוערת: ${ctx.untilLabel}</p>
   </div>
 </body>

package/dist/index.d.ts

@@ -18,7 +18,19 @@ export interface ShabbatGateConfig {
     /** Optional custom holding-page renderer. Defaults to a Hebrew, mobile-
      *  responsive page showing siteName + when the site reopens. */
     renderHoldingPage?: (ctx: HoldingPageContext) => string;
+    /** Minutes to close the site *before* candle-lighting and reopen *after*
+     *  havdalah, on top of the raw Hebcal window. Defaults to 0 (no buffer).
+     *  Useful padding against clock drift / last-minute browsing right at the
+     *  boundary - applied at decision time, not baked into the cached windows,
+     *  so changing it takes effect immediately without waiting on the cache. */
+    bufferMinutes?: number;
 }
+/** Internal cache key for the merged window list (~24h TTL via the Workers
+ *  Cache API). Exported so consumers that do their own caching of
+ *  derived/post-processed window data (e.g. after applying their own buffer)
+ *  can pick a different key and avoid accidentally colliding with this one -
+ *  which would silently serve stale, unprocessed windows for up to 24h. */
+export declare const INTERNAL_CACHE_KEY_URL = "https://internal.cache/shabbat-gate-windows-v1";
 /**
  * Returns a Cloudflare Pages Functions-compatible handler that closes the
  * site to human visitors during Shabbat and major Jewish holidays, while
@@ -27,3 +39,23 @@ export interface ShabbatGateConfig {
  * occasional missed block during an error is a minor, invisible one.
  */
 export declare function createShabbatGate(config: ShabbatGateConfig): PagesFunction;
+/**
+ * Same gate logic as `createShabbatGate`, adapted for a plain Cloudflare
+ * Worker (with a static `assets` binding) instead of Pages Functions - there
+ * is no `next()` to call in that shape, so this returns `null` for "let the
+ * real site through" and a `Response` for "serve the holding page". Wire it
+ * up in the Worker's own `fetch` handler:
+ *
+ *   const gate = createShabbatGateForWorker({ siteName: 'My Site' });
+ *   export default {
+ *     async fetch(request, env, ctx) {
+ *       const blocked = await gate(request);
+ *       return blocked ?? env.ASSETS.fetch(request);
+ *     },
+ *   };
+ *
+ * Note: a Worker with an `assets` binding skips the `fetch` handler entirely
+ * for requests matching a static asset unless `assets.run_worker_first: true`
+ * is set in `wrangler.jsonc` - without it, this gate never runs.
+ */
+export declare function createShabbatGateForWorker(config: ShabbatGateConfig): (request: Request) => Promise<Response | null>;

package/dist/index.js

@@ -6,11 +6,16 @@ export { isBot, BOT_PATTERN } from './botPattern.js';
 export { defaultRenderHoldingPage } from './holdingPage.js';
 const JERUSALEM_LATITUDE = 31.7683;
 const JERUSALEM_LONGITUDE = 35.2137;
-const CACHE_KEY_URL = 'https://internal.cache/shabbat-gate-windows-v1';
+/** Internal cache key for the merged window list (~24h TTL via the Workers
+ *  Cache API). Exported so consumers that do their own caching of
+ *  derived/post-processed window data (e.g. after applying their own buffer)
+ *  can pick a different key and avoid accidentally colliding with this one -
+ *  which would silently serve stale, unprocessed windows for up to 24h. */
+export const INTERNAL_CACHE_KEY_URL = 'https://internal.cache/shabbat-gate-windows-v1';
 const CACHE_TTL_SECONDS = 24 * 60 * 60;
 async function getWindows(latitude, longitude) {
     const cache = caches.default;
-    const cacheRequest = new Request(CACHE_KEY_URL);
+    const cacheRequest = new Request(INTERNAL_CACHE_KEY_URL);
     const cached = await cache.match(cacheRequest);
     if (cached) {
         return (await cached.json());
@@ -34,6 +39,53 @@ function formatJerusalemTime(epochMs) {
         minute: '2-digit',
     }).format(new Date(epochMs));
 }
+function applyBuffer(windows, bufferMinutes) {
+    if (!bufferMinutes) {
+        return windows;
+    }
+    const bufferMs = bufferMinutes * 60_000;
+    return windows.map((w) => ({ ...w, start: w.start - bufferMs, end: w.end + bufferMs }));
+}
+/**
+ * Shared core: bot allowlist, bypass check, window fetch (cached) + buffer,
+ * and the fail-open try/catch. Both `createShabbatGate` (Pages Functions) and
+ * `createShabbatGateForWorker` (plain Workers + Assets) are thin wrappers
+ * around this, so neither can drift out of sync on caching/fail-open/bypass
+ * behavior.
+ */
+async function evaluateGate(config, request) {
+    const userAgent = request.headers.get('user-agent') ?? '';
+    if (isBot(userAgent)) {
+        return { type: 'pass' };
+    }
+    if (config.bypassParam && config.bypassValue) {
+        const url = new URL(request.url);
+        if (url.searchParams.get(config.bypassParam) === config.bypassValue) {
+            return { type: 'pass' };
+        }
+    }
+    try {
+        const latitude = config.latitude ?? JERUSALEM_LATITUDE;
+        const longitude = config.longitude ?? JERUSALEM_LONGITUDE;
+        const windows = applyBuffer(await getWindows(latitude, longitude), config.bufferMinutes ?? 0);
+        const active = findActiveWindow(windows, Date.now());
+        if (!active) {
+            return { type: 'pass' };
+        }
+        const render = config.renderHoldingPage ?? defaultRenderHoldingPage;
+        const html = render({
+            siteName: config.siteName,
+            reasonLabel: active.label,
+            closingLabel: active.closingLabel,
+            untilLabel: formatJerusalemTime(active.end),
+        });
+        return { type: 'block', html };
+    }
+    catch (error) {
+        console.error('shabbat-gate: failing open due to error', error);
+        return { type: 'pass' };
+    }
+}
 /**
  * Returns a Cloudflare Pages Functions-compatible handler that closes the
  * site to human visitors during Shabbat and major Jewish holidays, while
@@ -43,39 +95,44 @@ function formatJerusalemTime(epochMs) {
  */
 export function createShabbatGate(config) {
     return async (context) => {
-        const { request, next } = context;
-        const userAgent = request.headers.get('user-agent') ?? '';
-        if (isBot(userAgent)) {
-            return next();
-        }
-        if (config.bypassParam && config.bypassValue) {
-            const url = new URL(request.url);
-            if (url.searchParams.get(config.bypassParam) === config.bypassValue) {
-                return next();
-            }
-        }
-        try {
-            const latitude = config.latitude ?? JERUSALEM_LATITUDE;
-            const longitude = config.longitude ?? JERUSALEM_LONGITUDE;
-            const windows = await getWindows(latitude, longitude);
-            const active = findActiveWindow(windows, Date.now());
-            if (!active) {
-                return next();
-            }
-            const render = config.renderHoldingPage ?? defaultRenderHoldingPage;
-            const html = render({
-                siteName: config.siteName,
-                reasonLabel: active.label,
-                untilLabel: formatJerusalemTime(active.end),
-            });
-            return new Response(html, {
-                status: 200,
-                headers: { 'content-type': 'text/html; charset=utf-8' },
-            });
+        const decision = await evaluateGate(config, context.request);
+        if (decision.type === 'pass') {
+            return context.next();
         }
-        catch (error) {
-            console.error('shabbat-gate: failing open due to error', error);
-            return next();
+        return new Response(decision.html, {
+            status: 200,
+            headers: { 'content-type': 'text/html; charset=utf-8' },
+        });
+    };
+}
+/**
+ * Same gate logic as `createShabbatGate`, adapted for a plain Cloudflare
+ * Worker (with a static `assets` binding) instead of Pages Functions - there
+ * is no `next()` to call in that shape, so this returns `null` for "let the
+ * real site through" and a `Response` for "serve the holding page". Wire it
+ * up in the Worker's own `fetch` handler:
+ *
+ *   const gate = createShabbatGateForWorker({ siteName: 'My Site' });
+ *   export default {
+ *     async fetch(request, env, ctx) {
+ *       const blocked = await gate(request);
+ *       return blocked ?? env.ASSETS.fetch(request);
+ *     },
+ *   };
+ *
+ * Note: a Worker with an `assets` binding skips the `fetch` handler entirely
+ * for requests matching a static asset unless `assets.run_worker_first: true`
+ * is set in `wrangler.jsonc` - without it, this gate never runs.
+ */
+export function createShabbatGateForWorker(config) {
+    return async (request) => {
+        const decision = await evaluateGate(config, request);
+        if (decision.type === 'pass') {
+            return null;
         }
+        return new Response(decision.html, {
+            status: 200,
+            headers: { 'content-type': 'text/html; charset=utf-8' },
+        });
     };
 }

package/package.json

@@ -1,35 +1,36 @@
-{
-  "name": "shabbat-gate",
-  "version": "0.1.1",
-  "description": "Cloudflare Pages/Workers middleware that closes a site to human visitors during Shabbat and major Jewish holidays (Israel-observance rules), while always letting search engines and AI crawlers through.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "README.he.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run"
-  },
-  "keywords": [
-    "cloudflare-pages",
-    "cloudflare-workers",
-    "shabbat",
-    "jewish-holidays",
-    "hebcal",
-    "israel"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
-  "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250204.0",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
-  }
-}
+{
+  "name": "shabbat-gate",
+  "version": "0.1.3",
+  "description": "Cloudflare Pages/Workers middleware that closes a site to human visitors during Shabbat and major Jewish holidays (Israel-observance rules), while always letting search engines and AI crawlers through.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "README.he.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "cloudflare-pages",
+    "cloudflare-workers",
+    "shabbat",
+    "jewish-holidays",
+    "hebcal",
+    "israel"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250204.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}