shabbat-gate 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -3,7 +3,22 @@
 All notable changes to this package are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
-## [0.2.1] - Unreleased
+## [0.3.0] - Unreleased
+
+### Added
+
+- `ShabbatGateConfig.geonameid` (and `FetchWindowsOptions.geonameid`) - set the site's home city
+  by Hebcal geonameid instead of `latitude`/`longitude`, so the base Shabbat/holiday times come
+  out at Hebcal's *official* times for that city. This matters because a city's official
+  candle-lighting can differ from a raw sunset-minus-default computation at the same coordinates:
+  e.g. Haifa (`294801`) lights ~10 minutes earlier than its bare lat/long - a real gap for a
+  Shabbat-observant site owner. When set, `latitude`/`longitude` are ignored for the base window
+  (and the internal cache key is namespaced by the geonameid so switching location doesn't serve
+  stale coordinate-based windows). Does not affect `enforceVisitorLocation` - visitor windows
+  always come from the visitor's `request.cf` coordinates. Common Israeli IDs: Jerusalem=281184,
+  Haifa=294801, Tel Aviv=293397, Beer Sheva=295530.
+
+## [0.2.1] - 2026-07-19
 
 ### Fixed
 

package/README.he.md

@@ -80,10 +80,19 @@ export interface ShabbatGateConfig {
   siteName: string;
 
   /** קווי אורך/רוחב עשרוניים לחישוב זמנים. ברירת מחדל לשניהם היא ירושלים (31.7683,
-   *  35.2137) אם לא סופקו - נקודת ייחוס טובה לכל ישראל ברזולוציה הזו. */
+   *  35.2137) אם לא סופקו - נקודת ייחוס טובה לכל ישראל ברזולוציה הזו. מתעלמים ממנו
+   *  כאשר מוגדר `geonameid`. */
   latitude?: number;
   longitude?: number;
 
+  /** geonameid של Hebcal לעיר הבית של האתר. כשמוגדר, זמני השבת/חג של האתר נלקחים
+   *  מהזמנים ה*רשמיים* של אותה עיר ב-Hebcal, במקום חישוב שקיעה-פחות-ברירת-מחדל
+   *  בקואורדינטות גולמיות (ההפרש אמיתי - למשל חיפה `294801` מדליקה נרות ~10 דק'
+   *  מוקדם יותר מה-lat/long הגולמי שלה). `latitude`/`longitude` לא בשימוש כשזה מוגדר.
+   *  לא משפיע על `enforceVisitorLocation` (חלונות הגולש תמיד לפי `request.cf`).
+   *  ירושלים=281184, חיפה=294801, תל אביב=293397, באר שבע=295530. */
+  geonameid?: number;
+
   /** שם פרמטר + ערך נדרש ב-query string שעוקפים את השער לגמרי, כדי שבעל האתר יוכל
    *  לבדוק/לתצוגה מקדימה בכל יום. חשוב לבחור ערך שלא ניתן לניחוש - זו נוחות לבדיקות,
    *  לא הרשאה אמיתית. */

package/README.md

@@ -80,10 +80,18 @@ 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. */
+   *  omitted - a fine single reference point for all of Israel at this granularity.
+   *  Ignored when `geonameid` is set. */
   latitude?: number;
   longitude?: number;
 
+  /** Hebcal geonameid of the site's home city. When set, the base Shabbat/holiday times use
+   *  Hebcal's *official* times for that city instead of sunset-minus-default at raw coordinates
+   *  (they can differ - e.g. Haifa `294801` lights ~10 min earlier than its bare lat/long).
+   *  `latitude`/`longitude` are ignored when set. Does not affect `enforceVisitorLocation`.
+   *  Jerusalem=281184, Haifa=294801, Tel Aviv=293397, Beer Sheva=295530. */
+  geonameid?: 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. */

package/dist/hebcal.d.ts

@@ -62,6 +62,15 @@ export interface FetchWindowsOptions {
      *  computing their local windows so day boundaries line up with their sunset,
      *  not Jerusalem's. */
     tzid?: string;
+    /** Hebcal geonameid of a specific city. When set, the query uses this city
+     *  instead of `latitude`/`longitude`, so candle-lighting/havdalah come out at
+     *  Hebcal's *official* times for that city - which can differ from a raw
+     *  sunset-minus-18-minutes computation at the same coordinates (e.g. Haifa,
+     *  geonameid 294801, lights ~10 min earlier than its bare lat/long). Use this
+     *  for the site's own reference location when you want the exact city time;
+     *  `latitude`/`longitude` are ignored when it is present. Jerusalem=281184,
+     *  Haifa=294801, Tel Aviv=293397, Beer Sheva=295530. */
+    geonameid?: number;
 }
 /**
  * Fetches and merges Shabbat + major-holiday windows for the next ~45 days from

package/dist/hebcal.js

@@ -85,13 +85,18 @@ export async function fetchWindows(latitude, longitude, options = {}) {
     const end = new Date(start.getTime() + 45 * 24 * 60 * 60 * 1000);
     const startParam = toISODate(start);
     const endParam = toISODate(end);
+    // A specific city (geonameid) yields Hebcal's official times for that city;
+    // otherwise fall back to raw coordinates (sunset-minus-default at that point).
+    const locationParam = options.geonameid != null
+        ? `geonameid=${options.geonameid}`
+        : `latitude=${latitude}&longitude=${longitude}`;
     // i=on = Israel single-day Yom Tov reckoning; i=off = 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.
+    // ss=on = weekly Shabbat candle-lighting/havdalah, localized to the location.
     // maj=on + everything else off = only real work-restricted Yom Tov days.
     const iParam = israelMode ? 'on' : 'off';
     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=${iParam}&latitude=${latitude}&longitude=${longitude}&tzid=${encodeURIComponent(tzid)}` +
+        `&c=on&i=${iParam}&${locationParam}&tzid=${encodeURIComponent(tzid)}` +
         `&start=${startParam}&end=${endParam}`;
     const res = await fetch(url);
     if (!res.ok) {

package/dist/index.d.ts

@@ -9,9 +9,19 @@ export { defaultRenderHoldingPage } from './holdingPage.js';
 export interface ShabbatGateConfig {
     siteName: string;
     /** Decimal lat/long for zmanim. Both default to Jerusalem if omitted - a fine
-     *  single reference point for all of Israel at this granularity. */
+     *  single reference point for all of Israel at this granularity. Ignored when
+     *  `geonameid` is set. */
     latitude?: number;
     longitude?: number;
+    /** Hebcal geonameid of the site's home city. When set, the site's own
+     *  Shabbat/holiday times come from Hebcal's *official* times for that city
+     *  (rather than sunset-minus-default at raw coordinates), and `latitude`/
+     *  `longitude` are ignored for the base window. Preferred over lat/long when
+     *  you want a specific Israeli city exactly - e.g. Haifa (`294801`) lights
+     *  ~10 min earlier than its bare coordinates. Jerusalem=281184, Haifa=294801,
+     *  Tel Aviv=293397, Beer Sheva=295530. Does not affect `enforceVisitorLocation`
+     *  (visitor windows always come from the visitor's `request.cf` coordinates). */
+    geonameid?: number;
     /** Query param name + required value that bypasses the gate entirely, for
      *  the site owner to preview/test on any day. Keep the value non-guessable -
      *  this is a testing convenience, not real auth. */

package/dist/index.js

@@ -56,9 +56,13 @@ function readVisitorLocation(request) {
     }
     return { latitude, longitude, tzid, israelMode: cf.country === 'IL' };
 }
-/** Israel/Jerusalem windows - the base gate, always computed. */
-function getIsraelWindows(latitude, longitude) {
-    return getCachedWindows(INTERNAL_CACHE_KEY_URL, () => fetchWindows(latitude, longitude));
+/** Israel windows - the base gate, always computed. When `geonameid` is set the
+ *  site's own times come from Hebcal's official city times (and the cache key is
+ *  namespaced by it so switching location doesn't serve stale coordinate-based
+ *  windows for up to 24h). */
+function getIsraelWindows(latitude, longitude, geonameid) {
+    const cacheKey = geonameid != null ? `${INTERNAL_CACHE_KEY_URL}?geonameid=${geonameid}` : INTERNAL_CACHE_KEY_URL;
+    return getCachedWindows(cacheKey, () => fetchWindows(latitude, longitude, geonameid != null ? { geonameid } : {}));
 }
 /** Windows for a specific visitor location, cached per rounded cell. */
 function getVisitorWindows(loc) {
@@ -111,7 +115,7 @@ async function evaluateGate(config, request) {
         // local-time display shown to a visitor outside Israel.
         const visitor = readVisitorLocation(request);
         const isAbroad = visitor !== null && !visitor.israelMode;
-        let windows = applyBuffer(await getIsraelWindows(latitude, longitude), bufferMinutes);
+        let windows = applyBuffer(await getIsraelWindows(latitude, longitude, config.geonameid), bufferMinutes);
         if (config.enforceVisitorLocation && visitor) {
             const visitorWindows = applyBuffer(await getVisitorWindows(visitor), bufferMinutes);
             // Union of both calendars: block if it's Shabbat/Yom Tov in Israel OR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabbat-gate",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",