Qirvo Weather Widget Plugin

A comprehensive weather plugin for Qirvo that displays current weather conditions and forecasts in your daily planner dashboard and provides CLI weather commands.

Features

• 🌤️ Current Weather Display: Real-time weather conditions with temperature, humidity, and wind speed
• 📅 3-Day Forecast: Extended weather forecast in your dashboard widget
• 🖥️ CLI Commands: Get weather information directly from the command line
• 📍 Location Support: Automatic location detection or manual location setting
• ⚙️ Configurable: Customizable units, update intervals, and display options
• 🔄 Auto-Updates: Automatic weather data refresh at configurable intervals
• 💾 Offline Support: Cached weather data when API is unavailable
• 🔧 Plugin Lifecycle: Full lifecycle management with install, enable, disable, and update hooks
• 🛡️ Admin Approval: Integrated with Qirvo's admin approval workflow
• 🧹 Clean Scripts: Built-in cleaning capabilities for development and maintenance
• 📊 Health Monitoring: Health check endpoint for admin monitoring
• 🔄 Configuration Migration: Automatic config migration during plugin updates

Installation

Prerequisites

1. Qirvo Dashboard: Ensure you have Qirvo installed and running
2. Weather API Key: Get a free API key from OpenWeatherMap

Method 1: Install from Qirvo Plugin Marketplace

1. Open your Qirvo dashboard
2. Navigate to Plugins in the sidebar
3. Search for "Weather Widget"
4. Click Install on the Weather Widget plugin
5. Configure your API key in the plugin settings

Method 2: Manual Installation

1. Download the Plugin:

   git clone https://github.com/Qirvo/qirvo-weather-plugin.git
   cd plugin-weather-widget

2. Install Dependencies:

   npm install

3. Build the Plugin:

   npm run build

4. Package for Distribution:

   npm pack

5. Install in Qirvo:

   • Copy the generated .tgz file to your Qirvo plugins directory
   • Or use the Qirvo CLI: qirvo plugin install ./qirvo-plugin-weather-widget-1.0.0.tgz

Configuration

After installation, configure the plugin in your Qirvo dashboard:

1. Go to Plugins → Weather Widget → Settings
2. Add your OpenWeatherMap API key
3. Set your default location (optional)
4. Configure preferences:
   • Temperature Units: Celsius or Fahrenheit
   • Update Interval: How often to refresh weather data (5-60 minutes)
   • Show Forecast: Enable/disable 3-day forecast display

Configuration Options

Setting	Description	Default	Required
apiKey	OpenWeatherMap API key	-	✅
defaultLocation	Default location for weather	-	❌
units	Temperature units (celsius/fahrenheit)	celsius	❌
updateInterval	Update frequency in minutes (5-60)	15	❌
showForecast	Show 3-day forecast in widget	true	❌

Usage

Dashboard Widget

Once installed and configured, the weather widget will automatically appear in your Qirvo dashboard sidebar. The widget displays:

• Current temperature and weather conditions
• Location name
• Humidity and wind speed
• 3-day forecast (if enabled)
• Last update time

CLI Commands

Use the weather plugin from the Qirvo command line:

Basic Weather Command

# Get weather for your default location
qirvo weather

# Get weather for a specific location
qirvo weather "New York, NY"
qirvo weather "London, UK"
qirvo weather "Tokyo, Japan"

Advanced Options

# Specify temperature units
qirvo weather "Paris, France" --units fahrenheit
qirvo weather "Berlin, Germany" --units celsius

# Get extended forecast
qirvo weather "Sydney, Australia" --days 5

# Combine options
qirvo weather "Los Angeles, CA" --units fahrenheit --days 7

Command Aliases

# Short aliases for quick access
qirvo w "Miami, FL"
qirvo forecast "Seattle, WA" --days 3

Integration with Qirvo Tasks

The weather plugin can integrate with your Qirvo tasks:

# Add current weather to a task (via plugin API)
qirvo weather add-to-task <task-id>

Architecture

Modern TSX Component Architecture

The Weather Plugin has been modernized with a clean TypeScript React architecture:

Component Structure

src/
├── components/
│   └── WeatherWidget.tsx          # Main widget component
├── pages/
│   ├── WeatherSettingsPage.tsx    # Settings configuration page
│   └── WeatherDashboardPage.tsx   # Weather overview dashboard
└── index.ts                       # Plugin entry point

Key Features

• TypeScript TSX Components: Modern React components with full TypeScript support
• Page-Based Routing: Structured routing for /plugins/weather/settings and /plugins/weather/dashboard
• CommonJS Compatibility: Full browser-compatible module system with require() support
• Mantine UI Integration: Consistent design system with Qirvo dashboard
• Plugin Runtime Integration: Seamless integration with Qirvo's plugin system

Module System

The plugin uses CommonJS modules for browser compatibility:

// Plugin components can use require() for external dependencies
const React = require('react');
const { Card, Text, Button } = require('@mantine/core');

Plugin Lifecycle

The Weather Plugin follows Qirvo's plugin lifecycle:

1. Installation: Plugin files are uploaded and stored in Firebase Storage
2. Registration: Plugin is registered in the Qirvo plugin registry
3. Loading: Plugin runtime loads components using CommonJS require() system
4. Execution: Components render in the dashboard with full React support
5. Configuration: Settings are managed through dedicated configuration pages

Development

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/Qirvo/qirvo-weather-plugin.git
   cd plugin-weather-widget

2. Install dependencies:

   npm install

3. Start development mode:

   npm run dev

4. Run tests:

   npm test

5. Lint code:

   npm run lint

Project Structure

qirvo-weather-plugin/
├── src/
│   ├── index.ts          # Main plugin logic
│   └── widget.tsx        # React dashboard widget
├── dist/                 # Compiled output
├── manifest.json         # Plugin manifest
├── package.json          # NPM package configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Building for Production

# Build the plugin
npm run build

# Create distribution package
npm pack

Troubleshooting

Common Issues

1. "Weather API key not configured"

   • Solution: Add your OpenWeatherMap API key in plugin settings

2. "No location specified"

   • Solution: Set a default location in settings or specify location in CLI command

3. "Failed to fetch weather data"

   • Check your internet connection
   • Verify your API key is valid
   • Ensure the location name is correct

4. Widget not updating

   • Check the update interval setting
   • Verify the plugin is enabled
   • Check browser console for errors

Debug Mode

Enable debug logging by setting the log level in your Qirvo configuration:

{
  "plugins": {
    "weather-widget": {
      "logLevel": "debug"
    }
  }
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Reporting Issues

Please report issues on our GitHub Issues page.

Feature Requests

Have an idea for a new feature? Open a Feature Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: plugins@qirvo.ai
• 📖 Documentation: Qirvo Plugin Docs
• 🐛 Bug Reports: GitHub Issues

Changelog

---

Made with ❤️ by the Qirvo Community