n8n-nodes-hebrew-calendar/README.md

n8n community node for Hebrew Calendar operations - check if dates are Shabbat, holidays, or Chol Hamoed

# n8n-nodes-hebrew-calendar

[![npm version](https://badge.fury.io/js/n8n-nodes-hebrew-calendar.svg)](https://badge.fury.io/js/n8n-nodes-hebrew-calendar)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An n8n community node for Hebrew/Jewish calendar operations. This node allows you to check if dates are Shabbat, Jewish holidays, or Chol Hamoed (intermediate festival days), and provides accurate candle lighting and Havdalah times.

## Features

- **Check Date Status**: Determine if a specific date and time is Shabbat, a Jewish holiday, or Chol Hamoed
- **Time-Aware Checking**: Validate exact times against Shabbat entry/exit times
- **Shabbat Times**: Get precise candle lighting and Havdalah times for any location
- **Holiday Information**: Retrieve comprehensive Jewish holiday data for date ranges
- **Multiple Locations**: Support for major Israeli cities with accurate sunset/sunrise calculations
- **Customizable Options**: Configure Chol Hamoed inclusion, candle lighting minutes, and more

## Installation

To install this node in your n8n instance:

```bash
npm install n8n-nodes-hebrew-calendar
```

## Usage

### Operations

#### 1. Check Date Status
Checks if a specific date (and optionally time) is a special day in the Jewish calendar.

**Parameters:**
- **Target Date**: Date to check (YYYY-MM-DD format)
- **Check Specific Time**: Enable to check exact time against Shabbat hours
- **Target Time**: Time to check (HH:MM format) - only if "Check Specific Time" is enabled
- **Include Chol Hamoed**: Whether to consider intermediate festival days as special days
- **Location**: Location for sunset/sunrise calculations (defaults to Tel Aviv)

**Example Output:**
```json
{
  "date": "2024-01-20",
  "time": "19:30",
  "location": "Tel Aviv",
  "isShabbat": true,
  "isHoliday": false,
  "isCholHamoed": false,
  "isSpecialDay": true,
  "eventType": "shabbat",
  "timeBasedResult": true,
  "candleLighting": "2024-01-19T16:45:00+02:00",
  "havdalah": "2024-01-20T17:55:00+02:00"
}
```

#### 2. Get Shabbat Times
Retrieves candle lighting and Havdalah times for a specific date.

**Parameters:**
- **Target Date**: Date to get times for
- **Location**: Location for calculations

**Example Output:**
```json
{
  "date": "2024-01-20",
  "location": "Tel Aviv",
  "candleLighting": {
    "time": "2024-01-19T16:45:00+02:00",
    "title": "Candle lighting: 4:45pm"
  },
  "havdalah": {
    "time": "2024-01-20T17:55:00+02:00",
    "title": "Havdalah: 5:55pm"
  }
}
```

#### 3. Get Holiday Info
Retrieves comprehensive Jewish holiday information for a date range.

**Parameters:**
- **Start Date**: Beginning of date range
- **End Date**: End of date range
- **Include Chol Hamoed**: Whether to include intermediate festival days

### Supported Locations

- Tel Aviv (default)
- Jerusalem
- Haifa
- Netanya
- Ashdod
- Rishon LeZion
- Petah Tikva
- Beersheba
- Holon
- Bnei Brak

## Use Cases

- **Scheduling Systems**: Avoid scheduling meetings during Shabbat or holidays
- **E-commerce**: Adjust delivery schedules for observant customers
- **Event Planning**: Coordinate events around Jewish calendar dates
- **Automation**: Create workflows that respect Jewish time observances
- **Notifications**: Send reminders for candle lighting times
- **Business Logic**: Implement Jewish calendar-aware business rules

## API Integration

This node uses the [Hebcal.com API](https://www.hebcal.com/home/developer-apis) for accurate Hebrew calendar data, including:
- Israeli holiday schedule
- Precise sunset/sunrise calculations
- Shabbat and holiday times
- Multiple location support

## Configuration

The node supports various configuration options:
- **Candle Lighting Minutes**: Customize minutes before sunset (default: 18, Jerusalem: 40)
- **Havdalah Calculation**: Choose between tzeit hakochavim (nightfall) or fixed minutes
- **Holiday Types**: Include/exclude minor holidays, fast days, modern holidays
- **Special Shabbatot**: Include special Shabbat readings

## Development

To contribute to this node:

1. Clone the repository
2. Install dependencies: `npm install`
3. Build the project: `npm run build`
4. Test locally: `npm run dev`

## License

[MIT](LICENSE.md)

## Support

For issues and feature requests, please visit our [GitHub repository](https://github.com/your-username/n8n-nodes-hebrew-calendar).

## Acknowledgments

- [Hebcal.com](https://www.hebcal.com) for providing the Jewish calendar API
- [n8n](https://n8n.io) for the excellent workflow automation platform