### Install node-calendarific Package via npm

Source: https://github.com/calendarific/node-calendarific/blob/master/README.md

This snippet shows how to install the node-calendarific library using npm. It is a prerequisite for using the library in a Node.js project. No specific inputs or outputs are associated with this command, other than the successful installation of the package.

```shell
npm install --save node-calendarific
```

```shell
npm install node-calendarific
```

--------------------------------

### Initialize Calendarific API Client (Node.js)

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Initializes a new Calendarific API client instance using your provided API key. This is the first step to authenticate and interact with the Calendarific service.

```javascript
const Calendarific = require('node-calendarific');

// Initialize with your API key
const clapi = new Calendarific('your_api_key_here');
```

--------------------------------

### Initialize and Fetch Holidays with node-calendarific

Source: https://github.com/calendarific/node-calendarific/blob/master/README.md

This JavaScript snippet demonstrates how to use the node-calendarific library. It shows how to load the package, initialize it with an API key, define parameters for holiday retrieval (country and year), and then make a call to fetch holiday data, logging the result to the console. It requires a valid API key and optionally takes country and year parameters.

```javascript
// Load the package
const Calendarific = require('node-calendarific');

// Initlize with an API key
const clapi = new Calendarific('_YOUR_API_KEY_');

const parameters = {
  country: 'US',
  year:    2019,
};

clapi.holidays(parameters, function (data) {
  console.log(data)
  // Insert awesome code here...
});
```

--------------------------------

### Calendarific Constructor

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Initialize a new Calendarific API client with your API key to authenticate requests to the Calendarific service.

```APIDOC
## Calendarific Constructor

### Description
Initialize a new Calendarific API client with your API key to authenticate requests to the Calendarific service.

### Method
`new Calendarific(apiKey)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const Calendarific = require('node-calendarific');

// Initialize with your API key
const clapi = new Calendarific('your_api_key_here');
```

### Response
#### Success Response (N/A)
This is a constructor, it does not return a response in the traditional sense.

#### Response Example
N/A
```

--------------------------------

### Integrate Node.js Calendarific with Promises and Async/Await

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Shows how to wrap the callback-based node-calendarific API into a Promise for use with async/await syntax. This facilitates cleaner asynchronous code flow and error handling using try/catch blocks.

```javascript
const Calendarific = require('node-calendarific');
const clapi = new Calendarific('your_api_key_here');

// Create a promise wrapper
function getHolidays(parameters) {
  return new Promise((resolve, reject) => {
    clapi.holidays(parameters, function(data) {
      if (typeof data === 'string') {
        reject(new Error(data));
      } else if (data.meta && data.meta.code !== 200) {
        reject(new Error(data.meta.error_detail || 'API Error'));
      } else {
        resolve(data.response.holidays);
      }
    });
  });
}

// Use with async/await
async function fetchHolidays() {
  try {
    const holidays = await getHolidays({
      country: 'US',
      year: 2023,
      month: 12
    });

    console.log('December holidays:', holidays.length);
    holidays.forEach(holiday => {
      console.log(`${holiday.name} - ${holiday.date.iso}`);
    });
  } catch (error) {
    console.error('Failed to fetch holidays:', error.message);
  }
}

fetchHolidays();

// Use with Promise chains
getHolidays({ country: 'FR', year: 2023 })
  .then(holidays => {
    return holidays.filter(h => h.type.includes('National holiday'));
  })
  .then(nationalHolidays => {
    console.log('National holidays in France:', nationalHolidays.length);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });
```

--------------------------------

### Configure Calendarific API Query Parameters (Node.js)

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Demonstrates how to configure comprehensive query parameters for the Calendarific API to filter holiday data. Includes options for country, year, month, day, type, location, and language.

```javascript
const Calendarific = require('node-calendarific');
const clapi = new Calendarific('your_api_key_here');

// Available parameters
const fullParameters = {
  country: 'US',      // ISO 3166 country code (required)
  year: 2023,         // Year (required)
  month: 7,           // Month (1-12, optional)
  day: 4,             // Day (1-31, optional)
  type: 'national',   // Holiday type: national, local, religious, observance (optional)
  location: 'us-ny',  // Specific location/state code (optional)
  language: 'en'      // Response language code (optional)
};

clapi.holidays(fullParameters, function(data) {
  console.log(JSON.stringify(data, null, 2));
});

// Multiple types can be specified
const multiTypeParameters = {
  country: 'CA',
  year: 2023,
  type: 'national,local'
};

clapi.holidays(multiTypeParameters, function(data) {
  if (data.response) {
    console.log('Found holidays:', data.response.holidays.length);
  }
});
```

--------------------------------

### Handle API Errors with Node.js Calendarific

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Demonstrates how to handle potential network issues, invalid responses, and API-specific errors when using the node-calendarific library. It checks for string responses indicating network errors and meta.code for API error codes.

```javascript
const Calendarific = require('node-calendarific');
const clapi = new Calendarific('your_api_key_here');

const parameters = {
  country: 'US',
  year: 2023
};

clapi.holidays(parameters, function(data) {
  // Check for network/request errors (string response)
  if (typeof data === 'string') {
    console.error('Request Error:', data);
    return;
  }

  // Check for API errors
  if (data.meta && data.meta.code !== 200) {
    console.error('API Error:', {
      code: data.meta.code,
      error_type: data.meta.error_type,
      error_detail: data.meta.error_detail
    });
    return;
  }

  // Success - process holidays
  if (data.response && data.response.holidays) {
    console.log('Successfully retrieved holidays');
    data.response.holidays.forEach(holiday => {
      console.log(`- ${holiday.name} (${holiday.date.iso})`);
    });
  }
});

// Handle invalid API key
const invalidClient = new Calendarific('invalid_key');

invalidClient.holidays({ country: 'US', year: 2023 }, function(data) {
  if (data.meta && data.meta.code === 401) {
    console.error('Authentication failed. Please check your API key.');
  }
});
```

--------------------------------

### Retrieve Holiday Data with Calendarific API (Node.js)

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Fetches holiday information from the Calendarific API. Supports basic and advanced filtering by country, year, month, day, and holiday type. Handles API responses and errors.

```javascript
const Calendarific = require('node-calendarific');
const clapi = new Calendarific('your_api_key_here');

// Basic usage - get all holidays for a country and year
const parameters = {
  country: 'US',
  year: 2019
};

clapi.holidays(parameters, function(data) {
  if (data.meta && data.meta.code === 200) {
    console.log('Total holidays:', data.response.holidays.length);
    data.response.holidays.forEach(holiday => {
      console.log(`${holiday.name} - ${holiday.date.iso}`);
    });
  } else {
    console.error('Error:', data);
  }
});

// Advanced usage - filter by month and holiday type
const advancedParameters = {
  country: 'GB',
  year: 2020,
  month: 12,
  type: 'national'
};

clapi.holidays(advancedParameters, function(data) {
  if (data.meta && data.meta.code === 200) {
    data.response.holidays.forEach(holiday => {
      console.log({
        name: holiday.name,
        date: holiday.date.iso,
        description: holiday.description,
        type: holiday.type,
        locations: holiday.locations
      });
    });
  } else {
    console.error('API Error:', data);
  }
});

// Filter by specific day
const specificDayParameters = {
  country: 'IN',
  year: 2021,
  month: 1,
  day: 26
};

clapi.holidays(specificDayParameters, function(data) {
  if (data.response && data.response.holidays) {
    console.log('Holidays on January 26:', data.response.holidays);
  }
});
```

--------------------------------

### holidays() - Retrieve Holiday Data

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Query the Calendarific API to fetch holiday information based on specified parameters including country, year, month, day, type, and language.

```APIDOC
## holidays() - Retrieve Holiday Data

### Description
Query the Calendarific API to fetch holiday information based on specified parameters including country, year, month, day, type, and language.

### Method
`clapi.holidays(parameters, callback)`

### Endpoint
N/A (This is a client-side method that constructs API requests)

### Parameters
#### Path Parameters
None

#### Query Parameters
*   **country** (string) - Required - ISO 3166 country code.
*   **year** (integer) - Required - The year for which to retrieve holidays.
*   **month** (integer) - Optional - The month (1-12) to filter holidays by.
*   **day** (integer) - Optional - The day (1-31) to filter holidays by.
*   **type** (string) - Optional - Comma-separated string of holiday types to filter by (e.g., 'national', 'local', 'religious', 'observance').
*   **location** (string) - Optional - Specific location/state code for more granular filtering.
*   **language** (string) - Optional - Language code for the response.

#### Request Body
None

### Request Example
```javascript
const Calendarific = require('node-calendarific');
const clapi = new Calendarific('your_api_key_here');

// Basic usage - get all holidays for a country and year
const parameters = {
  country: 'US',
  year: 2019
};

clapi.holidays(parameters, function(data) {
  if (data.meta && data.meta.code === 200) {
    console.log('Total holidays:', data.response.holidays.length);
    data.response.holidays.forEach(holiday => {
      console.log(`${holiday.name} - ${holiday.date.iso}`);
    });
  } else {
    console.error('Error:', data);
  }
});

// Advanced usage - filter by month and holiday type
const advancedParameters = {
  country: 'GB',
  year: 2020,
  month: 12,
  type: 'national'
};

clapi.holidays(advancedParameters, function(data) {
  if (data.meta && data.meta.code === 200) {
    data.response.holidays.forEach(holiday => {
      console.log({
        name: holiday.name,
        date: holiday.date.iso,
        description: holiday.description,
        type: holiday.type,
        locations: holiday.locations
      });
    });
  } else {
    console.error('API Error:', data);
  }
});

// Filter by specific day
const specificDayParameters = {
  country: 'IN',
  year: 2021,
  month: 1,
  day: 26
};

clapi.holidays(specificDayParameters, function(data) {
  if (data.response && data.response.holidays) {
    console.log('Holidays on January 26:', data.response.holidays);
  }
});
```

### Response
#### Success Response (200)
- **meta** (object) - Metadata about the API request.
  - **code** (integer) - HTTP status code of the response.
  - **error** (boolean) - Indicates if an error occurred.
  - **error_message** (string) - Message describing the error, if any.
- **response** (object) - Contains the holiday data.
  - **holidays** (array) - An array of holiday objects.
    - **name** (string) - The name of the holiday.
    - **date** (object) - The date of the holiday.
      - **iso** (string) - ISO 8601 format date.
      - **datetime** (object) - Date and time components.
        - **year** (integer)
        - **month** (integer)
        - **day** (integer)
    - **description** (string) - A description of the holiday.
    - **type** (array) - An array of holiday types (e.g., 'national').
    - **locations** (object) - Location-specific information.

#### Response Example
```json
{
  "meta": {
    "code": 200,
    "error": false,
    "error_message": null
  },
  "response": {
    "holidays": [
      {
        "name": "Independence Day",
        "date": {
          "iso": "2019-07-04T00:00:00.000Z",
          "datetime": {
            "year": 2019,
            "month": 7,
            "day": 4
          }
        },
        "description": "Independence Day",
        "type": [
          "national"
        ],
        "locations": {
          "country": {
            "name": "United States",
            "iso": "US"
          },
          "state": null
        }
      }
    ]
  }
}
```
```

--------------------------------

### Parse Holiday Response Data with Node.js Calendarific

Source: https://context7.com/calendarific/node-calendarific/llms.txt

Illustrates how to parse the structured holiday data returned by the Calendarific API. It accesses nested properties like name, date, and type to extract relevant holiday information.

```javascript
const Calendarific = require('node-calendarific');
const clapi = new Calendarific('your_api_key_here');

clapi.holidays({ country: 'US', year: 2023 }, function(data) {
  // Response structure example
  /*
  {
    "meta": {
      "code": 200
    },
    "response": {
      "holidays": [
        {
          "name": "New Year's Day",
          "description": "New Year's Day is the first day of the year...",
          "country": {
            "id": "us",
            "name": "United States"
          },
          "date": {
            "iso": "2023-01-01",
            "datetime": {
              "year": 2023,
              "month": 1,
              "day": 1
            }
          },
          "type": ["National holiday"],
          "locations": "All",
          "states": "All"
        }
      ]
    }
  }
  */

  if (data.response && data.response.holidays) {
    data.response.holidays.forEach(holiday => {
      const holidayInfo = {
        name: holiday.name,
        description: holiday.description,
        iso_date: holiday.date.iso,
        year: holiday.date.datetime.year,
        month: holiday.date.datetime.month,
        day: holiday.date.datetime.day,
        types: holiday.type,
        country: holiday.country.name,
        country_code: holiday.country.id,
        locations: holiday.locations,
        states: holiday.states
      };

      console.log(holidayInfo);
    });
  }
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.