shabbat-gate 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to this package are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/).
+
+## [0.2.0] - Unreleased
+
+### Added
+
+- `ShabbatGateConfig.enforceVisitorLocation` - when `true`, the gate blocks a visitor during
+  Shabbat/Yom Tov in *their own* location (from Cloudflare's `request.cf` geolocation), not
+  only Israel's. The site is closed to them if it's Shabbat in Israel **or** where they are,
+  so an overseas visitor stays blocked from Israel's candle-lighting right through their own
+  local havdalah. Holidays for a visitor outside Israel use diaspora two-day Yom Tov reckoning
+  (`i=off`); Chanukah/Purim/Yom HaAtzma'ut/Chol HaMoed stay open either way. Falls back to the
+  Israel-only decision when a request has no geolocation (local `wrangler dev`, unplaceable IP).
+  Defaults to `false` (original Israel-only behavior).
+- **Localized secondary holding-page message.** For a visitor physically outside Israel, the
+  default holding page now shows the Hebrew message, then (below a blank-line gap) a message in
+  the visitor's own browser language (from `Accept-Language`). Built-in languages: English
+  (default/fallback), French, Russian, Spanish, German, and Arabic (right-to-left).
+  Hebrew-speaking visitors and visitors
+  in Israel get no second message. Reopen time is shown in the visitor's own timezone. Works
+  independently of `enforceVisitorLocation` (whenever the site is closed and the visitor is
+  known to be abroad).
+- New exports supporting the above: `fetchWindows` now takes an optional third `options`
+  argument (`{ israelMode?, tzid? }`) for computing a non-Israel calendar; `mergeWindows`
+  (coalesces overlapping window lists into continuous ones); `SUPPORTED_LANGUAGES`,
+  `resolveVisitorLanguage`, and the `SecondaryMessage` / `SupportedLanguage` /
+  `FetchWindowsOptions` types.
+
+### Changed
+
+- `HoldingPageContext` gained an optional `secondary?: SecondaryMessage` field (the localized
+  block). Existing custom `renderHoldingPage` functions are unaffected - the field is optional
+  and simply ignored if unused.
+- The default holding page now HTML-escapes `siteName` and all label fields before
+  interpolation.
+
+## [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,190 @@
-# 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;
+    /** הודעה מקומית אופציונלית שמוצגת מתחת להודעה בעברית (עם רווח), עבור גולש מחוץ
+     *  לישראל, בשפת הדפדפן שלו. חסרה עבור גולשים בישראל / דוברי עברית / כשמיקום
+     *  הגולש לא ידוע. */
+    secondary?: { dir: 'ltr' | 'rtl'; lines: string[] };
+  }) => string;
+
+  /** דקות לסגור את האתר *לפני* הדלקת נרות ולפתוח אותו *אחרי* הבדלה, מעל החלון הגולמי
+   *  מ-Hebcal. ברירת מחדל: 0. שימושי כרפידת בטחון מול סחיפת שעון / גלישה של הרגע
+   *  האחרון בדיוק בגבול החלון. */
+  bufferMinutes?: number;
+
+  /** כשמוגדר `true`, חוסם גולש גם בזמן שבת/יום-טוב *במיקום שלו עצמו* (לפי הגאו-לוקיישן
+   *  של Cloudflare ב-`request.cf`), לא רק בזמן של ישראל. האתר סגור לגולש אם זו שבת
+   *  בישראל *או* במקום שבו הוא נמצא - כך שגולש בחו"ל נשאר חסום מהדלקת הנרות בישראל ועד
+   *  צאת השבת המקומית שלו. חגים לגולש מחוץ לישראל מחושבים לפי יום-טוב שני של גלויות
+   *  (יומיים). ברירת מחדל: `false` (שער לפי ישראל בלבד, ההתנהגות המקורית). אם אין נתוני
+   *  מיקום לבקשה (למשל `wrangler dev` מקומי, או IP ש-Cloudflare לא ממקם) - אותה בקשה
+   *  נופלת חזרה להחלטה לפי ישראל בלבד. */
+  enforceVisitorLocation?: boolean;
+}
+```
+
+### חסימה גם לפי אזור הזמן של הגולש (`enforceVisitorLocation`)
+
+ברירת המחדל: השער מחושב לפי לוח הזמנים של **ישראל** בלבד, לכל גולש בעולם. ברגע שיוצאת
+שבת בישראל, האתר נפתח לכולם - גם לגולש בארה"ב שאצלו עדיין שבת.
+
+עם `enforceVisitorLocation: true` השער הופך ל**איחוד של שתי שבתות**: האתר סגור לגולש אם
+זו שבת/יום-טוב בישראל **או** במיקום שממנו הוא גולש. דוגמה לגולש בניו יורק: הוא נחסם כבר
+מהדלקת הנרות בישראל (גם אם אצלו עדיין יום שישי בצהריים), ונשאר חסום ברצף עד צאת השבת
+המקומית שלו. חגים מחושבים לו לפי חשבון גלותי (יום-טוב שני של גלויות). חנוכה, פורים, יום
+העצמאות וחול המועד לא חוסמים - לא בישראל ולא בחו"ל.
+
+### הודעה בשפה מקומית לגולש מחו"ל
+
+כשגולש נמצא מחוץ לישראל, דף ה"סגור" הדיפולטי מציג קודם את ההודעה בעברית, ומתחתיה (עם
+רווח של שתי שורות) הודעה בשפת הדפדפן שלו (לפי כותרת `Accept-Language`). שפות מובנות:
+אנגלית (ברירת מחדל), צרפתית, רוסית, ספרדית, גרמנית, וערבית (מוצגת מימין לשמאל). גולש דובר
+עברית או גולש בישראל לא מקבל שורה שנייה. שעת הפתיחה מוצגת לגולש מחו"ל באזור הזמן שלו. זה עובד גם ללא
+`enforceVisitorLocation` (בכל פעם שהאתר סגור וידוע שהגולש בחו"ל).
+
+דוגמה מלאה:
+
+```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. אם הוגדר `enforceVisitorLocation`, נשלף לוח זמנים שני לפי מיקום הגולש (מ-`request.cf`,
+   בחשבון גלותי לגולש מחוץ לישראל) ומאוחד עם חלונות ישראל - חוסמים אם הזמן נופל באחד
+   מהם. חלונות חופפים ממוזגים לחלון רציף אחד כדי ששעת הפתיחה המוצגת תהיה מדויקת.
+6. אם הזמן הנוכחי נופל בתוך חלון, מוצג דף ה"סגור" (HTTP 200). אחרת, האתר האמיתי עובר.
+7. כל שגיאה בדרך גורמת למעבר לאתר האמיתי.
+
+## מפתח קאש פנימי
+
+רשימת החלונות המאוחדת נשמרת בקאש תחת מפתח פנימי קבוע
+(`https://internal.cache/shabbat-gate-windows-v1`, מיוצא בשם `INTERNAL_CACHE_KEY_URL`) לכ-24
+שעות דרך Workers Cache API. אם הקוד שלכם עושה caching משלו לנתונים נגזרים (למשל חלונות עם
+buffer משלכם), כדאי להשתמש במפתח אחר - שימוש חוזר במפתח הזה יגרום בשקט להחזרת נתונים ישנים
+ולא-מעובדים למשך עד 24 שעות.
+
+## היסטוריית שינויים
+
+ב-[CHANGELOG.md](CHANGELOG.md) (באנגלית) מתועד מה השתנה בכל גרסה, כולל הסבר לשורש כל
+באג שתוקן.
+
+## רישיון
+
+MIT