# n8n-nodes-shabbat-time

An advanced n8n community node to check if a given date/time falls on Shabbat or Jewish holiday using the Hebcal API with precise time checking capabilities.

![n8n.io - Workflow Automation](https://raw.githubusercontent.com/n8n-io/n8n/master/assets/n8n-logo.png)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

```bash
npm install n8n-nodes-shabbat-time
```

## Features

- ✅ Check if a specific date falls on Shabbat
- ✅ Check if a specific date falls on Jewish holidays (major and minor)
- ✅ **NEW** Precise time checking for Shabbat entry/exit times
- ✅ **NEW** Support for Chol Hamoed (intermediate festival days)
- ✅ Support for multiple location formats (GeoNames ID, coordinates, ZIP code)
- ✅ Default location: Tel Aviv, Israel
- ✅ Configurable candle lighting time
- ✅ Israel holiday schedule (not Diaspora)
- ✅ Detailed information about Jewish events and times
- ✅ Usable as AI Tool in n8n agents

## Operations

### Check Date

Checks if a given date/time falls on Shabbat or Jewish holiday.

**Input Parameters:**
- **Date**: The date/time to check (date/time picker)
- **Location Type**: Choose between GeoNames ID, coordinates, or ZIP code
- **GeoNames ID**: Numeric ID from GeoNames.org (default: 293397 for Tel Aviv)
- **Latitude/Longitude**: Geographic coordinates (default: Tel Aviv)
- **ZIP Code**: US ZIP code for location
- **Include Minor Holidays**: Whether to include minor holidays like Rosh Chodesh
- **Include Chol Hamoed**: Whether to include intermediate festival days
- **Check Exact Time**: Enable precise time checking for Shabbat entry/exit
- **Candle Lighting Minutes**: Minutes before sunset for candle lighting (default: 18)

## Time Checking Logic

### Date-Only Mode (Check Exact Time = false)
Returns `true` if the given date falls on Shabbat or a holiday, regardless of time.

### Precise Time Mode (Check Exact Time = true)
Returns `true` only if the exact date/time falls within Shabbat or holiday period:

**Example for Friday-Saturday Shabbat:**
- Friday 19:59 (before candle lighting at 20:00) → `false`
- Friday 20:00 (candle lighting) → `true`  
- Saturday morning → `true`
- Saturday 21:30 (after Havdalah at 21:15) → `false`

**Output:**
- `isShabbatOrHoliday`: Boolean indicating if the date/time is Shabbat or holiday
- `inputDate`: The original input date
- `formattedDate`: Date in YYYY-MM-DD format
- `dayOfWeek`: Day of the week in English
- `checkExactTime`: Whether exact time checking was enabled
- `categories`: Array of event categories found for this date
- `details`: Detailed information about events on this date
- `location`: Location information from Hebcal
- `sabbatTimes`: Object with candle lighting and Havdalah times
- `settings`: Configuration used for this check

## Usage Examples

### Basic Date Check
```javascript
// Input: Friday, December 13, 2024 (any time)
// Check Exact Time: false
// Output: true (because it's Erev Shabbat)
```

### Precise Time Check
```javascript
// Input: Friday, December 13, 2024 19:45
// Check Exact Time: true
// Candle lighting: 20:00
// Output: false (before Shabbat starts)

// Input: Friday, December 13, 2024 20:15
// Check Exact Time: true  
// Output: true (Shabbat has started)
```

### Example Output

```json
{
  "isShabbatOrHoliday": true,
  "inputDate": "2024-12-13T20:15:00.000Z",
  "formattedDate": "2024-12-13",
  "dayOfWeek": "Friday",
  "checkExactTime": true,
  "categories": ["candles", "parashat"],
  "sabbatTimes": {
    "candleLighting": "2024-12-13T18:00:00+02:00",
    "havdalah": "2024-12-14T19:15:00+02:00",
    "isInShabbatTimeRange": true
  },
  "details": [
    {
      "title": "Candle lighting: 6:00pm",
      "category": "candles",
      "hebrew": "הדלקת נרות",
      "date": "2024-12-13T18:00:00+02:00"
    }
  ],
  "location": {
    "title": "Tel Aviv, Tel Aviv, Israel",
    "city": "Tel Aviv",
    "tzid": "Asia/Jerusalem"
  },
  "settings": {
    "includeMinorHolidays": true,
    "includeCholHamoed": false,
    "checkExactTime": true,
    "candleLightingMinutes": 18,
    "location": "geonameid"
  }
}
```

### Categories Detected

The node detects the following categories:
- `candles` - Candle lighting (Friday evening or holiday eve)
- `havdalah` - Havdalah (end of Shabbat)
- `parashat` - Weekly Torah portion (Shabbat)
- `holiday` - Jewish holidays (major)
- `roshchodesh` - Rosh Chodesh (if minor holidays enabled)
- `fast` - Fast days (if minor holidays enabled)
- `modern` - Modern holidays including Chol Hamoed (if enabled)

## Location Options

### GeoNames ID (Recommended)
Use the numeric ID from GeoNames.org for precise location data.

Common GeoNames IDs:
- Tel Aviv: 293397 (default)
- Jerusalem: 281184
- Haifa: 294801
- New York: 5128581
- London: 2643743
- Los Angeles: 5368361

### Coordinates
Provide latitude and longitude for any location worldwide.

### ZIP Code
Use US ZIP codes for locations within the United States.

## Version 2.0.0 Changes

### 🚀 Major New Features:
- **Precise Time Checking**: Check exact time for Shabbat entry/exit
- **Chol Hamoed Support**: Optional inclusion of intermediate festival days
- **Enhanced API**: Now uses full Hebcal calendar API
- **Israel Schedule**: Uses Israel holiday schedule by default
- **Improved Output**: Detailed sabbath times and configuration info

### 🔧 Improvements:
- Default location changed to Tel Aviv
- Better error handling and validation
- More detailed event information
- Optimized API calls with date ranges

## API Reference

This node uses the [Hebcal Jewish Calendar REST API](https://www.hebcal.com/home/developer-apis).

## Compatibility

- n8n version: 1.0.0 or later
- Node.js version: 20.15 or later

## License

[MIT](LICENSE.md)

## Credits

- Powered by [Hebcal.com](https://www.hebcal.com/) API
- Jewish calendar calculations by Hebcal

## Support

For issues and feature requests, please visit the [GitHub repository](https://github.com/idobe977/n8n-nodes-shabbat-time).

## Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests.