shabbat-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eyal Meshulam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# shabbat-gate
+
+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

package/dist/botPattern.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Broad, case-insensitive allowlist for search engine and AI crawlers.
+ * Matches let a request through unconditionally, before any gate logic runs.
+ * Erring toward "let more things through" is the safe direction here, since
+ * the whole point of this list is protecting SEO/crawlability.
+ */
+export declare const BOT_PATTERN: RegExp;
+export declare function isBot(userAgent: string): boolean;

package/dist/botPattern.js

@@ -0,0 +1,10 @@
+/**
+ * Broad, case-insensitive allowlist for search engine and AI crawlers.
+ * Matches let a request through unconditionally, before any gate logic runs.
+ * Erring toward "let more things through" is the safe direction here, since
+ * the whole point of this list is protecting SEO/crawlability.
+ */
+export const BOT_PATTERN = /bot|crawl|spider|slurp|googlebot|google-inspectiontool|adsbot-google|bingbot|duckduckbot|baiduspider|yandex|facebookexternalhit|twitterbot|linkedinbot|whatsapp|telegrambot|discordbot|applebot|gptbot|chatgpt-user|oai-searchbot|ccbot|claudebot|claude-web|anthropic-ai|perplexitybot|google-extended|bytespider|semrushbot|ahrefsbot|mj12bot|petalbot/i;
+export function isBot(userAgent) {
+    return BOT_PATTERN.test(userAgent);
+}

package/dist/hebcal.d.ts

@@ -0,0 +1,29 @@
+export interface Window {
+    start: number;
+    end: number;
+    label: string;
+}
+interface HebcalItem {
+    title: string;
+    hebrew?: string;
+    date: string;
+    category: string;
+}
+/**
+ * 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.
+ */
+export declare function pairWindows(items: HebcalItem[]): 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.
+ */
+export declare function fetchWindows(latitude: number, longitude: number): Promise<Window[]>;
+/** Pure function: is `now` inside any of the given windows? */
+export declare function isBlocked(windows: Window[], now: number): boolean;
+/** Pure function: the window covering `now`, if any. */
+export declare function findActiveWindow(windows: Window[], now: number): Window | undefined;
+export {};

package/dist/hebcal.js

@@ -0,0 +1,68 @@
+const HEBCAL_JERUSALEM_GEONAME_ID = 281184;
+/**
+ * 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.
+ */
+export function pairWindows(items) {
+    const windows = [];
+    let openStart = null;
+    let openLabel = '';
+    for (const item of items) {
+        if (item.category === 'candles') {
+            if (openStart === null) {
+                openStart = new Date(item.date).getTime();
+                openLabel = item.hebrew ?? item.title;
+            }
+        }
+        else if (item.category === 'havdalah' && openStart !== null) {
+            windows.push({ start: openStart, end: new Date(item.date).getTime(), label: openLabel });
+            openStart = null;
+            openLabel = '';
+        }
+    }
+    return windows;
+}
+function toISODate(date) {
+    return date.toISOString().slice(0, 10);
+}
+/**
+ * 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.
+ */
+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.
+    // 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 [shabbatData, holidayData] = (await Promise.all([
+        shabbatRes.json(),
+        holidayRes.json(),
+    ]));
+    const windows = [
+        ...pairWindows(shabbatData.items ?? []),
+        ...pairWindows(holidayData.items ?? []),
+    ];
+    return windows.sort((a, b) => a.start - b.start);
+}
+/** Pure function: is `now` inside any of the given windows? */
+export function isBlocked(windows, now) {
+    return findActiveWindow(windows, now) !== undefined;
+}
+/** Pure function: the window covering `now`, if any. */
+export function findActiveWindow(windows, now) {
+    return windows.find((w) => w.start <= now && now < w.end);
+}

package/dist/holdingPage.d.ts

@@ -0,0 +1,7 @@
+export interface HoldingPageContext {
+    siteName: string;
+    reasonLabel: string;
+    untilLabel: string;
+}
+/** Simple, centered, mobile-responsive holding page. Inline CSS only, no external assets. */
+export declare function defaultRenderHoldingPage(ctx: HoldingPageContext): string;

package/dist/holdingPage.js

@@ -0,0 +1,38 @@
+/** Simple, centered, mobile-responsive holding page. Inline CSS only, no external assets. */
+export function defaultRenderHoldingPage(ctx) {
+    return `<!doctype html>
+<html lang="he" dir="rtl">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${ctx.siteName}</title>
+<style>
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+    background: #0f2138;
+    color: #f3efe4;
+    text-align: center;
+    padding: 24px;
+  }
+  .card { max-width: 480px; }
+  h1 { font-size: 1.5rem; margin: 0 0 12px; }
+  p { font-size: 1rem; line-height: 1.6; color: #c8a951; margin: 0 0 8px; }
+  .until { font-size: 0.9rem; color: #9fb0c4; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1>${ctx.siteName}</h1>
+    <p>האתר סגור לכבוד ${ctx.reasonLabel}, ניפגש שוב אחרי הצאת ${ctx.reasonLabel}.</p>
+    <p class="until">שעת פתיחה משוערת: ${ctx.untilLabel}</p>
+  </div>
+</body>
+</html>`;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type HoldingPageContext } from './holdingPage.js';
+export type { Window } from './hebcal.js';
+export type { HoldingPageContext } from './holdingPage.js';
+export { isBlocked, findActiveWindow, pairWindows, fetchWindows } from './hebcal.js';
+export { isBot, BOT_PATTERN } from './botPattern.js';
+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. */
+    latitude?: number;
+    longitude?: 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. */
+    bypassParam?: string;
+    bypassValue?: string;
+    /** Optional custom holding-page renderer. Defaults to a Hebrew, mobile-
+     *  responsive page showing siteName + when the site reopens. */
+    renderHoldingPage?: (ctx: HoldingPageContext) => string;
+}
+/**
+ * Returns a Cloudflare Pages Functions-compatible handler that closes the
+ * site to human visitors during Shabbat and major Jewish holidays, while
+ * always letting search engines and AI crawlers through. Fails open on any
+ * error - an accidental block on a regular Tuesday is a real, visible bug; an
+ * occasional missed block during an error is a minor, invisible one.
+ */
+export declare function createShabbatGate(config: ShabbatGateConfig): PagesFunction;

package/dist/index.js

@@ -0,0 +1,81 @@
+import { isBot } from './botPattern.js';
+import { fetchWindows, findActiveWindow } from './hebcal.js';
+import { defaultRenderHoldingPage } from './holdingPage.js';
+export { isBlocked, findActiveWindow, pairWindows, fetchWindows } from './hebcal.js';
+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';
+const CACHE_TTL_SECONDS = 24 * 60 * 60;
+async function getWindows(latitude, longitude) {
+    const cache = caches.default;
+    const cacheRequest = new Request(CACHE_KEY_URL);
+    const cached = await cache.match(cacheRequest);
+    if (cached) {
+        return (await cached.json());
+    }
+    const windows = await fetchWindows(latitude, longitude);
+    const cacheResponse = new Response(JSON.stringify(windows), {
+        headers: {
+            'content-type': 'application/json',
+            'cache-control': `max-age=${CACHE_TTL_SECONDS}`,
+        },
+    });
+    await cache.put(cacheRequest, cacheResponse);
+    return windows;
+}
+function formatJerusalemTime(epochMs) {
+    return new Intl.DateTimeFormat('he-IL', {
+        timeZone: 'Asia/Jerusalem',
+        day: '2-digit',
+        month: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    }).format(new Date(epochMs));
+}
+/**
+ * Returns a Cloudflare Pages Functions-compatible handler that closes the
+ * site to human visitors during Shabbat and major Jewish holidays, while
+ * always letting search engines and AI crawlers through. Fails open on any
+ * error - an accidental block on a regular Tuesday is a real, visible bug; an
+ * occasional missed block during an error is a minor, invisible one.
+ */
+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' },
+            });
+        }
+        catch (error) {
+            console.error('shabbat-gate: failing open due to error', error);
+            return next();
+        }
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "shabbat-gate",
+  "version": "0.1.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",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.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"
+  }
+}