### Complete Application Example

Source: https://context7.com/lesander/fritzbox.js/llms.txt

A comprehensive example demonstrating session management and multiple API calls for a smart home automation scenario.

```APIDOC
## Complete Application Example

### Description
A comprehensive example demonstrating session management and multiple API calls for a smart home automation scenario.

### Method
None (This is a script demonstrating multiple API calls)

### Endpoint
None

### Parameters
None

### Request Example
```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-secure-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function smartHomeAutomation() {
  // Authenticate once and reuse session
  const sid = await fritz.getSessionId(options)
  if (sid.error) {
    console.log('Authentication failed:', sid.error.message)
    return
  }
  options.sid = sid
  console.log('Authenticated successfully')

  // Check Fritz!Box version
  const version = await fritz.getVersion(options)
  console.log('Fritz!OS Version:', version)

  // Get and display smart devices
  const devices = await fritz.getSmartDevices(options)
  if (!devices.error) {
    console.log('\nSmart Home Devices:')
    devices.forEach(device => {
      const state = device.switch ? (device.switch.SwitchOn ? 'ON' : 'OFF') : 'N/A'
      console.log(`  - ${device.Name} (ID: ${device.ID}): ${state}`)
    })
  }

  // Check for new voicemails
  const messages = await fritz.getTamMessages(options)
  if (!messages.error) {
    const newMessages = messages.filter(m => m.isNewMessage)
    console.log(`\nVoicemail: ${newMessages.length} new message(s)`)
  }

  // Get recent missed calls
  const calls = await fritz.getCalls(options)
  if (!calls.error) {
    const missedCalls = calls.filter(c => c.type === 'missed').slice(0, 5)
    console.log('\nRecent Missed Calls:')
    missedCalls.forEach(call => {
      console.log(`  - ${call.name || call.number} at ${call.date}`)
    })
  }
}

smartHomeAutomation()
```

### Response
None (This example demonstrates various API calls and their outputs)
```

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

### Install FritzBox.js

Source: https://github.com/lesander/fritzbox.js/blob/master/README.md

Installs the fritzbox.js package using npm. This is the standard way to add the library to your Node.js project.

```bash
npm install fritzbox.js
```

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

### Fritz!Box Smart Home Automation Example (JavaScript)

Source: https://context7.com/lesander/fritzbox.js/llms.txt

This example showcases a complete application for smart home automation using fritzbox.js. It demonstrates session management, retrieving Fritz!Box version, listing smart devices, checking voicemail, and fetching recent missed calls. It utilizes async/await for cleaner asynchronous operations.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-secure-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function smartHomeAutomation() {
  // Authenticate once and reuse session
  const sid = await fritz.getSessionId(options)
  if (sid.error) {
    console.log('Authentication failed:', sid.error.message)
    return
  }
  options.sid = sid
  console.log('Authenticated successfully')

  // Check Fritz!Box version
  const version = await fritz.getVersion(options)
  console.log('Fritz!OS Version:', version)

  // Get and display smart devices
  const devices = await fritz.getSmartDevices(options)
  if (!devices.error) {
    console.log('
Smart Home Devices:')
    devices.forEach(device => {
      const state = device.switch ? (device.switch.SwitchOn ? 'ON' : 'OFF') : 'N/A'
      console.log(`  - ${device.Name} (ID: ${device.ID}): ${state}`)
    })
  }

  // Check for new voicemails
  const messages = await fritz.getTamMessages(options)
  if (!messages.error) {
    const newMessages = messages.filter(m => m.isNewMessage)
    console.log(`
Voicemail: ${newMessages.length} new message(s)`)
  }

  // Get recent missed calls
  const calls = await fritz.getCalls(options)
  if (!calls.error) {
    const missedCalls = calls.filter(c => c.type === 'missed').slice(0, 5)
    console.log('
Recent Missed Calls:')
    missedCalls.forEach(call => {
      console.log(`  - ${call.name || call.number} at ${call.date}`)
    })
  }
}

smartHomeAutomation()
```

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

### Get Call History with Promises (v1.x.x)

Source: https://github.com/lesander/fritzbox.js/blob/master/README.md

Illustrates how to fetch call history using the older Promise-based .then() and .catch() syntax, as used in versions prior to v2.x.x of fritzbox.js.

```javascript
fritz.getCalls(options)
.then((callHistory) => {
  console.log(callHistory)
})
.catch((error) => {
  console.log(error)
})
```

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

### Get Call History with Async/Await

Source: https://github.com/lesander/fritzbox.js/blob/master/README.md

Demonstrates how to retrieve call history from a Fritz!Box using the fritzbox.js library with async/await syntax. It requires Node.js 7.6.0 or newer and includes basic error handling.

```javascript
const fritz = require('fritzbox.js')
const options = {
  username: 'xxx',
  password: 'xxx',
  server: 'fritz.box',
  protocol: 'https' }

;(async () => {

  const calls = await fritz.getCalls(options)
  if (calls.error) return console.log('Error: ' + calls.error.message)
  console.log('Got ' + calls.length + 'calls.')

})()
```

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

### Get Smart Home Devices

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Retrieves a list of all DECT Smart Home devices and groups registered on the network. The returned objects contain device metadata, state information, and manufacturer details.

```javascript
const devices = await fritz.getSmartDevices();
```

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

### Get Smart Home Devices

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieves all DECT smart home devices and device groups registered on the Fritz!Box. Returns an array of device objects including switches, thermostats, and power meters with their current states.

```APIDOC
## GET /api/smart-devices

### Description
Retrieves all DECT smart home devices and device groups registered on the Fritz!Box. Returns an array of device objects including switches, thermostats, and power meters with their current states.

### Method
GET

### Endpoint
/api/smart-devices

### Parameters
#### Query Parameters
- **options** (object) - Optional - Configuration options for the connection (username, password, server, protocol).

### Request Example
```javascript
const fritz = require('fritzbox.js')
const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}
const devices = await fritz.getSmartDevices(options)
```

### Response
#### Success Response (200)
- **devices** (array) - An array of device objects. Each object contains details about a smart home device, such as:
  - **ID** (number) - Unique identifier for the device.
  - **Name** (string) - The name of the device.
  - **Manufacturer** (string) - The manufacturer of the device.
  - **ProductName** (string) - The product name of the device.
  - **FWVersion** (string) - The firmware version of the device.
  - **switch** (object) - State of the switch (if applicable).
  - **temperature** (number) - Current temperature reading (if applicable).

#### Response Example
```json
[
  {
    "ID": 18,
    "Name": "Christmas Tree",
    "Manufacturer": "AVM",
    "ProductName": "FRITZ!DECT 200",
    "FWVersion": "03.59",
    "switch": {
      "SwitchOn": 0,
      "SwitchLock": 65535
    },
    "temperature": -9999
  }
]
```
```

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

### Get Call History with Promises and Error Check (v2.x.x)

Source: https://github.com/lesander/fritzbox.js/blob/master/README.md

Shows how to retrieve call history using Promises in v2.x.x of fritzbox.js, where errors are handled within the .then() block by checking for an 'error' property in the response.

```javascript
fritz.getCalls(options)
.then((callHistory) => {
  if (callHistory.error) return console.log(callHistory.error.message)
  console.log(callHistory)
})
```

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

### Get Phonebook Contacts

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Downloads all contacts from a specified phonebook on the Fritz!Box. Returns an array of contact objects.

```APIDOC
## GET /api/phonebook

### Description
Downloads all contacts from a specified phonebook on the Fritz!Box. Returns an array of contact objects with names, phone numbers (with type and priority), email addresses, and metadata.

### Method
GET

### Endpoint
/api/phonebook

### Parameters
#### Query Parameters
- **phonebookId** (number) - Optional - The ID of the phonebook to download. Defaults to 0 (main phonebook).
- **options** (object) - Optional - Configuration options for the connection (username, password, server, protocol).

### Request Example
```javascript
const fritz = require('fritzbox.js')
const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}
const phonebook = await fritz.getPhonebook(0, options)
```

### Response
#### Success Response (200)
- **phonebook** (array) - An array of contact objects. Each object contains:
  - **uniqueId** (string) - Unique identifier for the contact.
  - **name** (string) - The name of the contact.
  - **numbers** (array) - An array of phone number objects, each with:
    - **number** (string) - The phone number.
    - **type** (string) - The type of number (e.g., 'mobile', 'home').
    - **priority** (string) - The priority of the number.
  - **category** (string) - The category of the contact.
  - **email** (string) - The email address of the contact.
  - **lastModified** (string) - Timestamp of the last modification.
  - **ringtone** (string) - The assigned ringtone.

#### Response Example
```json
[
  {
    "uniqueId": "13",
    "name": "John Doe",
    "numbers": [
      {
        "number": "0612345678",
        "type": "mobile",
        "priority": "1"
      },
      {
        "number": "0201234567",
        "type": "home",
        "priority": "0"
      }
    ],
    "category": "1",
    "email": "john@example.com",
    "lastModified": "1484585116",
    "ringtone": "19"
  }
]
```
```

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

### GET /active-calls

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieves a list of currently active phone calls on the Fritz!Box network.

```APIDOC
## GET /active-calls

### Description
Retrieves information about any currently active phone calls on the Fritz!Box network. Returns an array of active call objects.

### Method
GET

### Endpoint
fritz.getActiveCalls(options)

### Parameters
#### Request Body
- **options** (object) - Required - Configuration object containing username, password, server, and protocol.

### Response
#### Success Response (200)
- **calls** (array) - List of active call objects.

#### Response Example
[
  {
    "id": "1",
    "number": "0612345678",
    "direction": "incoming"
  }
]
```

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

### GET /tam-messages

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieves all messages from the Telephone Answering Machine (TAM).

```APIDOC
## GET /tam-messages

### Description
Retrieves all messages from the Telephone Answering Machine (TAM) including metadata like caller info and duration.

### Method
GET

### Endpoint
fritz.getTamMessages(options)

### Parameters
#### Request Body
- **options** (object) - Required - Configuration object.

### Response
#### Success Response (200)
- **messages** (array) - List of TAM message objects.

#### Response Example
[
  {
    "tamId": 0,
    "messageId": 14,
    "name": "John Doe",
    "isNewMessage": true
  }
]
```

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

### Get Active Calls with fritzbox.js

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieves information about currently active phone calls on the Fritz!Box network. It requires connection options and returns an array of call objects or an error object if an issue occurs. The output indicates the number of active calls and details of each call.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function checkActiveCalls() {
  const calls = await fritz.getActiveCalls(options)

  if (calls.error) {
    console.log('Error:', calls.error.message)
    process.exit(1)
  }

  console.log('Currently there are/is ' + calls.length + ' active call(s).')
  // Output: "Currently there are/is 2 active call(s)."

  calls.forEach(call => {
    console.log('Active call:', call)
  })
}

checkActiveCalls()
```

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

### Get TAM Messages with fritzbox.js

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieves all messages from the Fritz!Box Telephone Answering Machine (TAM). It requires connection options and returns an array of message objects, including metadata like caller information, duration, and whether the message is new. The function automatically selects the appropriate API based on the Fritz!Box firmware version. New messages are counted and logged.

```javascript
const fritz = require('fritzbox.js')
const fs = require('fs')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function getVoicemails() {
  const messages = await fritz.getTamMessages(options)

  if (messages.error) {
    console.log('Error:', messages.error.message)
    process.exit(1)
  }

  console.log('Got', messages.length, 'TAM messages.')

  // Count and display new messages
  let newCount = 0
  for (const message of messages) {
    if (message.isNewMessage) {
      newCount++
      console.log('New message:', message)
      // Example message object:
      // {
      //   "tamId": 0,
      //   "messageId": 14,
      //   "date": "Wed Feb 15 2017 19:09:00 GMT+0100 (CET)",
      //   "name": "John Doe",
      //   "duration": "0:01",
      //   "number": "0612345678",
      //   "numberSelf": "0201234567",
      //   "path": "/data/tam/rec/rec.0.014",
      //   "inPhonebook": true,
      //   "isNewMessage": true
      // }
    }
  }

  console.log('There are/is', newCount, 'new TAM message(s).')
  fs.writeFileSync('tam.json', JSON.stringify(messages, null, 2))
}

getVoicemails()
```

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

### Configure FritzBox.js Connection Options

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Defines the required configuration object for establishing a connection to the Fritz!Box. Includes server address, protocol, and authentication credentials.

```javascript
{
  username: '',
  password: '',
  server: 'fritz.box',
  protocol: 'https'
}
```

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

### Execute API Calls with Async/Await

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Demonstrates the standard pattern for calling FritzBox.js API methods using async/await syntax and handling potential error responses.

```javascript
async function main() {
  const result = await fritz.functionName(parameter1, parameter2, ...)

  if (result.error) {
    return console.log(result.error.message)
  }

  // deal with the result object.
}
main()
```

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

### fritz.getSmartDevices

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Retrieves a list of all smart home devices registered with the Fritz!Box.

```APIDOC
## fritz.getSmartDevices(options)

### Description
Get a list of all registered smart devices.

### Method
GET (assumed)

### Endpoint
/query.lua (or similar Fritz!Box API endpoint)

### Parameters
#### Request Body
- **options** (object) - Required - An object containing connection options, including a valid session ID.
  - **sid** (string) - Required - The session ID obtained from `fritz.getSessionId()`.
  - **server** (string) - Optional - The hostname or IP address of the Fritz!Box.
  - **protocol** (string) - Optional - The protocol to use (http or https).

### Response
#### Success Response (200)
- **smartDevices** (array) - An array of smart device objects.
  - **id** (string) - Unique identifier for the smart device.
  - **name** (string) - Name of the smart device.
  - **type** (string) - Type of the smart device (e.g., 'switch', 'thermostat').
  - **state** (string/boolean) - Current state of the device (e.g., 'on', 'off', true, false).
  - ... other device-specific properties

#### Response Example
```json
[
  {
    "id": "12345 67890 123",
    "name": "Living Room Lamp",
    "type": "switch",
    "state": "on"
  },
  { ... }
]
```
```

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

### fritzSystem API

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Provides information about the Fritz!Box system and firmware.

```APIDOC
## GET /api/system/getVersionNumber

### Description
Retrieves the firmware version number of the Fritz!Box.

### Method
GET

### Endpoint
/api/system/getVersionNumber

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{ "options": {} }
```

### Response
#### Success Response (200)
- **versionNumber** (string) - The firmware version number.

#### Response Example
```json
{
  "versionNumber": "154.07.29"
}
```
```

```APIDOC
## GET /api/system/getVersion

### Description
Retrieves detailed firmware version information of the Fritz!Box.

### Method
GET

### Endpoint
/api/system/getVersion

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{ "options": {} }
```

### Response
#### Success Response (200)
- **version** (Object) - An object containing detailed version information.

#### Response Example
```json
{
  "version": {
    "major": 154,
    "minor": 7,
    "patch": 29,
    "build": "stable"
  }
}
```
```

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

### Configure FritzBox.js Connection

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Define the connection options object required for API authentication and communication with the router.

```javascript
const options = {
  username: '',
  password: 'your-password',
  server: 'fritz.box',
  protocol: 'https',
  callmonitorport: '1012'
}
```

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

### Retrieve Fritz!OS Version

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Fetches the Fritz!OS version from the device without requiring authentication. Supports returning the version as a string or as an integer.

```javascript
const versionString = await fritzSystem.getVersion(options);
const versionNumber = await fritzSystem.getVersionNumber(options);
```

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

### fritzLogin API

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Handles authentication and session management for the Fritz!Box.

```APIDOC
## GET /api/login/getSessionId

### Description
Obtains a session ID for authenticated access to the Fritz!Box.

### Method
GET

### Endpoint
/api/login/getSessionId

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{
  "username": "admin",
  "password": "password123",
  "options": {}
}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The obtained session ID.

#### Response Example
```json
{
  "sessionId": "abcdef1234567890"
}
```
```

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

### POST /download-tam-message

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Downloads a TAM message audio file to the local filesystem.

```APIDOC
## POST /download-tam-message

### Description
Downloads a Telephone Answering Machine message audio file to the local filesystem in WAV format.

### Method
POST

### Endpoint
fritz.downloadTamMessage(messagePath, localPath, options)

### Parameters
#### Path Parameters
- **messagePath** (string) - Required - Path to the message on the Fritz!Box.
- **localPath** (string) - Required - Destination path on the local filesystem.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

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

### Initiate Call with fritzbox.js

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Initiates a call to a specified phone number using the Fritz!Box's Click to Dial feature. This function requires connection options and the target phone number. It returns a status message indicating success or an error object if the call cannot be initiated. Ensure Click to Dial is enabled in Fritz!Box settings.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function makeCall(phoneNumber) {
  const status = await fritz.dialNumber(phoneNumber, options)

  if (status.error) {
    console.log('Error:', status.error.message)
    // Output: "Error: Invalid phone number given."
    // Or: "Error: An error occurred while ringing the number."
    process.exit(1)
  }

  console.log(status.message)
  // Output: "Ringing. Please pick up your designated handset now."
}

makeCall('0612345678')
```

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

### Retrieve Fritz!Box Smart Home Devices (JavaScript)

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieves all DECT smart home devices and device groups registered on the Fritz!Box. It returns an array of device objects, including switches, thermostats, and power meters with their current states. Requires the 'fritzbox.js' library.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function listSmartDevices() {
  const devices = await fritz.getSmartDevices(options)

  if (devices.error) {
    console.log('Error:', devices.error.message)
    process.exit(1)
  }

  console.log('Got ' + devices.length + ' DECT Smart Home devices.')
  // Output: "Got 5 DECT Smart Home devices."

  // Example device object:
  // {
  //   "ID": 18,
  //   "Name": "Christmas Tree",
  //   "Manufacturer": "AVM",
  //   "ProductName": "FRITZ!DECT 200",
  //   "FWVersion": "03.59",
  //   "switch": {
  //     "SwitchOn": 0,
  //     "SwitchLock": 65535
  //   },
  //   "temperature": -9999,
  //   ...
  // }

  devices.forEach(device => {
    console.log(`Device: ${device.Name} (${device.ProductName}) - ID: ${device.ID}`)
  })
}

listSmartDevices()
```

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

### Authenticate with Fritz!Box

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Initiates a login session with the Fritz!Box device. Returns a sessionId string upon successful authentication.

```javascript
const sessionId = await fritzLogin.getSessionId(options);
```

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

### fritzDect API

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Provides functions to interact with Fritz!Box DECT and Smart Home devices.

```APIDOC
## POST /api/dect/toggleSwitch

### Description
Toggle a Fritz DECT switch on or off.

### Method
POST

### Endpoint
/api/dect/toggleSwitch

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **deviceId** (integer) - Required - The Id of the smart home device.
- **value** (integer) - Required - Turn on (1) or off (0).
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{
  "deviceId": 12345,
  "value": 1,
  "options": {}
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message.
- **deviceId** (integer) - The Id of the device that was toggled.

#### Response Example
```json
{
  "message": "Device toggled successfully",
  "deviceId": 12345
}
```
```

```APIDOC
## GET /api/dect/getSmartDevices

### Description
Get all smart devices and groups managed by the Fritz!Box.

### Method
GET

### Endpoint
/api/dect/getSmartDevices

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{
  "options": {}
}
```

### Response
#### Success Response (200)
- **devices** (Array) - An array of all found smart devices and groups.

#### Response Example
```json
[
  {
    "id": "12345",
    "name": "Living Room Lamp",
    "state": "on",
    "level": 100
  },
  {
    "id": "67890",
    "name": "Smart Plug",
    "state": "off"
  }
]
```
```

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

### Monitor Fritz!Box Calls in Real-Time (JavaScript)

Source: https://context7.com/lesander/fritzbox.js/llms.txt

This snippet demonstrates how to use the CallMonitor to listen for real-time events from a Fritz!Box, including inbound, outbound, connected, and disconnected calls. It requires enabling the call monitor on the Fritz!Box by dialing #96*5*. The monitor emits events with call details.

```javascript
const fritz = require('fritzbox.js')

const options = {
  server: 'fritz.box',
  callmonitorport: '1012'  // Default port
}

// Create call monitor instance
const monitor = new fritz.CallMonitor(options)

// Handle incoming calls
monitor.on('inbound', (call) => {
  console.log('Incoming call:', call)
  // Output: { time: 1487172540, caller: '0612345678', called: '0201234567' }
})

// Handle outgoing calls
monitor.on('outbound', (call) => {
  console.log('Outgoing call:', call)
  // Output: { time: 1487172540, extension: '1', caller: '0201234567', called: '0612345678' }
})

// Handle call connection (pickup)
monitor.on('connected', (call) => {
  console.log('Call connected:', call)
  // Output: { time: 1487172545, extension: '1', caller: '0612345678', called: '0201234567' }
})

// Handle call end
monitor.on('disconnected', (call) => {
  console.log('Call ended:', call)
  // Output: {
  //   type: 'inbound',
  //   start: 1487172540,
  //   caller: '0612345678',
  //   called: '0201234567',
  //   connect: 1487172545,
  //   disconnect: 1487172600,
  //   duration: 55
  // }
})

// Handle errors
monitor.on('error', (error) => {
  console.log('Monitor error:', error)
  // Output: { message: 'Connection refused on 192.168.1.1:1012', code: 'ECONNREFUSED', raw: Error }
  process.exit(1)
})

console.log('Call monitor running... (dial #96*5* to enable on Fritz!Box)')
```

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

### Download TAM Message with fritzbox.js

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Downloads an audio file of a Telephone Answering Machine message to the local filesystem in WAV format. This function requires the message path (obtained from getTamMessages()), a local path for saving the file, and connection options. It returns a status message upon successful download or an error object if the download fails.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function downloadVoicemail() {
  const messagePath = '/data/tam/rec/rec.0.020'  // From getTamMessages()
  const localPath = './voicemail.wav'

  const status = await fritz.downloadTamMessage(messagePath, localPath, options)

  if (status.error) {
    console.log('Error:', status.error.message)
    // Output: "Error: Did not receive wav audio file"
    process.exit(1)
  }

  console.log(status.message)
  // Output: "Saved tam message to ./voicemail.wav"
}

downloadVoicemail()
```

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

### POST /dial-number

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Initiates a call to a specified phone number using the Click to Dial feature.

```APIDOC
## POST /dial-number

### Description
Initiates a call to the specified phone number. Requires Click to Dial to be enabled in Fritz!Box settings.

### Method
POST

### Endpoint
fritz.dialNumber(phoneNumber, options)

### Parameters
#### Path Parameters
- **phoneNumber** (string) - Required - The number to dial.

#### Request Body
- **options** (object) - Required - Configuration object.

### Response
#### Success Response (200)
- **message** (string) - Status message indicating the call has been initiated.

#### Response Example
{
  "message": "Ringing. Please pick up your designated handset now."
}
```

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

### fritz.downloadTamMessage

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Downloads a specific TAM message audio file (in WAV format) to a local file path on the client machine.

```APIDOC
## fritz.downloadTamMessage(path, localPath, options)

### Description
Download a Telephone Answering Machine (TAM) message in `.wav` format to disk. The `path` variable must be obtained using the `fritz.getTamMessages()` function. `localPath` can be something like `./my_tam.wav`.

### Method
GET (assumed, for file download)

### Endpoint
/download.lua (or similar Fritz!Box API endpoint for file access)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the TAM message audio file on the Fritz!Box, obtained from `fritz.getTamMessages()`.
- **localPath** (string) - Required - The local file path where the audio file will be saved.

#### Request Body
- **options** (object) - Required - An object containing connection options, including a valid session ID.
  - **sid** (string) - Required - The session ID obtained from `fritz.getSessionId()`.
  - **server** (string) - Optional - The hostname or IP address of the Fritz!Box.
  - **protocol** (string) - Optional - The protocol to use (http or https).

### Response
#### Success Response (200)
- File download successful. The response body would be the audio file content.

#### Response Example
(Binary audio data - no JSON example)
```

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

### Fetch Call History

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieve the complete call history from the Fritz!Box and save it to a JSON file.

```javascript
const fritz = require('fritzbox.js')
const fs = require('fs')
const options = { username: '', password: 'my-password', server: 'fritz.box', protocol: 'https' }
async function getCallHistory() {
  const calls = await fritz.getCalls(options)
  if (!calls.error) {
    fs.writeFileSync('calls.json', JSON.stringify(calls, null, 2))
  }
}
getCallHistory()
```

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

### Authenticate with Fritz!Box

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Retrieve a session ID (SID) to authorize subsequent API requests. The SID is stored in the options object for reuse.

```javascript
const fritz = require('fritzbox.js')
const options = { username: '', password: 'my-password', server: 'fritz.box', protocol: 'https' }
async function authenticate() {
  const sessionId = await fritz.getSessionId(options)
  if (sessionId.error) {
    console.log('Error:', sessionId.error.message)
    process.exit(1)
  }
  console.log('Session ID:', sessionId)
  options.sid = sessionId
}
authenticate()
```

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

### fritzFon API

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Provides functions for managing phone calls, messages, and the phonebook.

```APIDOC
## POST /api/fon/markTamMessageAsRead

### Description
Marks a specific answering machine message as read.

### Method
POST

### Endpoint
/api/fon/markTamMessageAsRead

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (integer) - Required - The ID of the answering machine message.
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{
  "id": 1,
  "options": {}
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Answering machine message marked as read."
}
```
```

```APIDOC
## GET /api/fon/getActiveCalls

### Description
Retrieves a list of currently active calls.

### Method
GET

### Endpoint
/api/fon/getActiveCalls

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{ "options": {} }
```

### Response
#### Success Response (200)
- **calls** (Array) - An array of active calls.

#### Response Example
```json
[
  {
    "id": "123",
    "number": "+123456789",
    "name": "John Doe",
    "direction": "in",
    "state": "connected"
  }
]
```
```

```APIDOC
## GET /api/fon/getPhonebook

### Description
Retrieves the entire phonebook.

### Method
GET

### Endpoint
/api/fon/getPhonebook

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{ "options": {} }
```

### Response
#### Success Response (200)
- **phonebook** (Array) - An array of phonebook entries.

#### Response Example
```json
[
  {
    "id": "1",
    "name": "John Doe",
    "number": "+123456789"
  }
]
```
```

```APIDOC
## POST /api/fon/dialNumber

### Description
Dials a specified phone number.

### Method
POST

### Endpoint
/api/fon/dialNumber

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **number** (string) - Required - The phone number to dial.
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{
  "number": "+123456789",
  "options": {}
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Dialing number..."
}
```
```

```APIDOC
## GET /api/fon/getCalls

### Description
Retrieves a list of all calls (incoming, outgoing, missed).

### Method
GET

### Endpoint
/api/fon/getCalls

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{ "options": {} }
```

### Response
#### Success Response (200)
- **calls** (Array) - An array of call records.

#### Response Example
```json
[
  {
    "id": "123",
    "number": "+123456789",
    "name": "John Doe",
    "direction": "in",
    "date": "2023-10-27T10:00:00Z",
    "type": "missed"
  }
]
```
```

```APIDOC
## GET /api/fon/getTamMessages

### Description
Retrieves a list of all answering machine messages.

### Method
GET

### Endpoint
/api/fon/getTamMessages

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{ "options": {} }
```

### Response
#### Success Response (200)
- **messages** (Array) - An array of answering machine messages.

#### Response Example
```json
[
  {
    "id": 1,
    "caller": "+123456789",
    "date": "2023-10-27T10:00:00Z",
    "read": false,
    "duration": 30
  }
]
```
```

```APIDOC
## GET /api/fon/downloadTamMessage

### Description
Downloads a specific answering machine message.

### Method
GET

### Endpoint
/api/fon/downloadTamMessage

### Parameters
#### Path Parameters
None

#### Query Parameters
- **id** (integer) - Required - The ID of the answering machine message to download.
- **options** (Object) - Optional - FritzBox.js options object.

### Request Example
```json
{
  "id": 1,
  "options": {}
}
```

### Response
#### Success Response (200)
- **audioData** (string) - The audio data of the answering machine message (e.g., base64 encoded).

#### Response Example
```json
{
  "audioData": "UklGR..."
}
```
```

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

### DECT Smart Home API

Source: https://github.com/lesander/fritzbox.js/wiki/_Sidebar

Endpoints for controlling DECT smart home devices.

```APIDOC
## GET /api/dect/getSmartDevices

### Description
Retrieves a list of connected DECT smart home devices.

### Method
GET

### Endpoint
/api/dect/getSmartDevices

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **devices** (array) - List of smart device objects.

#### Response Example
{
  "devices": [
    {
      "id": "device1",
      "name": "Smart Plug",
      "state": "on"
    }
  ]
}

## POST /api/dect/toggleSwitch

### Description
Toggles the state of a DECT smart switch.

### Method
POST

### Endpoint
/api/dect/toggleSwitch

### Parameters
#### Request Body
- **id** (string) - Required - The ID of the smart switch to toggle.
- **state** (string) - Optional - The desired state ('on' or 'off'). If not provided, the current state is toggled.

### Request Example
{
  "id": "device1",
  "state": "off"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
{
  "success": true
}
```

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

### Toggle Fritz!Box Smart Switch (JavaScript)

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Toggles a DECT smart home switch on or off. The deviceId is obtained from getSmartDevices(), and the value should be 1 (on) or 0 (off). This function automatically uses the appropriate API based on the Fritz!Box firmware version. Requires the 'fritzbox.js' library.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function controlSwitch() {
  const deviceId = 17  // From getSmartDevices()
  const turnOn = 1     // 1 = on, 0 = off

  const result = await fritz.toggleSwitch(deviceId, turnOn, options)

  if (result.error) {
    console.log('Error:', result.error.message)
    // Output: "Error: Switch state not changed."
    process.exit(1)
  }

  console.log('Toggled switch:', result)
  // Output: "Toggled switch: { message: 'Set switch to given state.', deviceId: 17 }"
}

controlSwitch()
```

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

### Monitor and Manage Calls

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Functions to handle active calls, retrieve call history, and initiate new calls. The CallMonitor function returns an EventEmitter to handle real-time call events.

```javascript
const activeCalls = await fritzFon.getActiveCalls(options);
const history = await fritzFon.getCalls(options);
const dialStatus = await fritzFon.dialNumber(123456789, options);

const monitor = fritzFon.CallMonitor(options);
monitor.on('call', (event) => console.log(event));
```

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

### Download Fritz!Box Phonebook Contacts (JavaScript)

Source: https://context7.com/lesander/fritzbox.js/llms.txt

Downloads all contacts from a specified phonebook on the Fritz!Box. It returns an array of contact objects, each containing names, phone numbers, email addresses, and metadata. The default phonebookId is 0. Requires the 'fritzbox.js' library.

```javascript
const fritz = require('fritzbox.js')

const options = {
  username: '',
  password: 'my-password',
  server: 'fritz.box',
  protocol: 'https'
}

async function getContacts() {
  const phonebookId = 0  // Main phonebook
  const phonebook = await fritz.getPhonebook(phonebookId, options)

  if (phonebook.error) {
    console.log('Error:', phonebook.error.message)
    process.exit(1)
  }

  console.log('Got', phonebook.length, 'contacts.')
  // Output: "Got 42 contacts."

  // Example contact object:
  // {
  //   "uniqueId": "13",
  //   "name": "John Doe",
  //   "numbers": [
  //     {
  //       "number": "0612345678",
  //       "type": "mobile",
  //       "priority": "1"
  //     },
  //     {
  //       "number": "0201234567",
  //       "type": "home",
  //       "priority": "0"
  //     }
  //   ],
  //   "category": "1",
  //   "email": "john@example.com",
  //   "lastModified": "1484585116",
  //   "ringtone": "19"
  // }
}

getContacts()
```

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

### fritz.toggleSwitch

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Toggles the state of a DECT smart switch (on/off).

```APIDOC
## fritz.toggleSwitch(deviceId, value, options)

### Description
Toggle a DECT switch on or off.

### Method
POST (assumed, as it modifies state)

### Endpoint
/query.lua (or similar Fritz!Box API endpoint)

### Parameters
#### Path Parameters
- **deviceId** (string) - Required - The unique identifier of the smart switch device.
- **value** (string/boolean) - Required - The desired state ('on' or 'off', or true/false).

#### Request Body
- **options** (object) - Required - An object containing connection options, including a valid session ID.
  - **sid** (string) - Required - The session ID obtained from `fritz.getSessionId()`.
  - **server** (string) - Optional - The hostname or IP address of the Fritz!Box.
  - **protocol** (string) - Optional - The protocol to use (http or https).

### Response
#### Success Response (200)
- A success indicator, likely a JSON object confirming the action.

#### Response Example
```json
{
  "success": true
}
```
```

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

### fritz.dialNumber

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Initiates a phone call to a specified number. Requires 'Click to Dial' to be configured in the Fritz!Box settings.

```APIDOC
## fritz.dialNumber(phoneNumber, options)

### Description
Dial a number. Once the other party picks up the phone, your preconfigured handset will start ringing. Requires you to set up *Click to Dial* in the Fritz!Box (can be found under `Telephony > Calls`).

### Method
POST (assumed, as it initiates an action)

### Endpoint
/query.lua (or similar Fritz!Box API endpoint)

### Parameters
#### Path Parameters
- **phoneNumber** (string) - Required - The phone number to dial.

#### Request Body
- **options** (object) - Required - An object containing connection options, including a valid session ID.
  - **sid** (string) - Required - The session ID obtained from `fritz.getSessionId()`.
  - **server** (string) - Optional - The hostname or IP address of the Fritz!Box.
  - **protocol** (string) - Optional - The protocol to use (http or https).

### Response
#### Success Response (200)
- A success indicator, likely a JSON object confirming the call initiation.

#### Response Example
```json
{
  "success": true
}
```
```

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

### Toggle Smart Switch State

Source: https://github.com/lesander/fritzbox.js/blob/master/DOCS.md

Changes the state of a specific DECT Smart Home switch. Requires the device ID and a binary value (1 for on, 0 for off).

```javascript
await fritz.toggleSwitch(18, 1);
```

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

### Download TAM Message

Source: https://github.com/lesander/fritzbox.js/blob/master/docs/api/index.html

Downloads a specific message from the Telephone Answering Machine to a local path. Requires the remote message path, local destination path, and configuration options.

```javascript
const result = await fritzBox.downloadTamMessage(messagePath, localPath, options);
```