diff --git a/.github/workflows/opportunity-crawler.yml b/.github/workflows/opportunity-crawler.yml new file mode 100644 index 0000000..44cd7b7 --- /dev/null +++ b/.github/workflows/opportunity-crawler.yml @@ -0,0 +1,94 @@ +# VolunteerConnect Hub - Opportunity Crawler Workflow +# =================================================== +# Crawls volunteer opportunities from multiple sources and updates the database +# Powered by AGI Board: OpportunityCrawlerAGI + +name: Crawl Volunteer Opportunities + +on: + schedule: + # Run daily at 6 AM UTC (2 AM EST) + - cron: '0 6 * * *' + workflow_dispatch: + inputs: + source: + description: 'Source to crawl (all, volunteermatch, idealist, etc.)' + required: false + default: 'all' + dry_run: + description: 'Dry run (do not update database)' + required: false + default: 'false' + +jobs: + crawl-opportunities: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install requests beautifulsoup4 feedparser supabase python-dotenv + + - name: Run Opportunity Crawler + env: + SUPABASE_URL: ${{ secrets.SUPABASE_URL }} + SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }} + VOLUNTEERMATCH_API_KEY: ${{ secrets.VOLUNTEERMATCH_API_KEY }} + run: | + python scripts/crawl_opportunities.py \ + --source ${{ github.event.inputs.source || 'all' }} \ + ${{ github.event.inputs.dry_run == 'true' && '--dry-run' || '' }} + + - name: Update opportunities database + if: ${{ github.event.inputs.dry_run != 'true' }} + env: + SUPABASE_URL: ${{ secrets.SUPABASE_URL }} + SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }} + run: | + python scripts/update_opportunities_db.py + + - name: Commit updated opportunities JSON + if: ${{ github.event.inputs.dry_run != 'true' }} + run: | + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action - Opportunity Crawler" + git add data/opportunities.json + git diff --staged --quiet || git commit -m "Update volunteer opportunities [automated]" + git push + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + generate-recommendations: + needs: crawl-opportunities + runs-on: ubuntu-latest + if: ${{ github.event.inputs.dry_run != 'true' }} + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + ref: main + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install supabase python-dotenv + + - name: Generate recommendations for active users + env: + SUPABASE_URL: ${{ secrets.SUPABASE_URL }} + SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }} + run: | + python scripts/generate_recommendations.py diff --git a/Gemfile b/Gemfile index 605ab69..bf3ebe2 100644 --- a/Gemfile +++ b/Gemfile @@ -7,9 +7,6 @@ source "https://rubygems.org" # Jekyll version gem "jekyll", "~> 4.3" -# GitHub Pages gem for compatibility -gem "github-pages", group: :jekyll_plugins - # Jekyll plugins group :jekyll_plugins do gem "jekyll-feed", "~> 0.12" diff --git a/README.md b/README.md index 5fdcca9..e6bd266 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ 🔗 **Live Site**: [https://pythpythpython.github.io/volunteer-connect-hub/](https://pythpythpython.github.io/volunteer-connect-hub/) +🔒 **Production Status**: Connected to Supabase backend + +📊 **Opportunities**: 40+ curated volunteer listings from 10+ organizations + --- ## Overview @@ -87,8 +91,14 @@ volunteer-connect-hub/ │ ├── css/ # Stylesheets │ └── js/ # JavaScript (auth, database, app) ├── data/ -│ └── opportunities.json # Volunteer opportunities data +│ └── opportunities.json # 40+ curated opportunities +├── scripts/ # Automation scripts +│ ├── crawl_opportunities.py +│ ├── update_opportunities_db.py +│ ├── generate_recommendations.py +│ └── volunteermatch_api.py ├── agi_boards/ # AGI Board implementations +│ ├── boards_config.json │ ├── user_profile_board.py │ ├── database_board.py │ ├── opportunity_crawler_board.py @@ -97,6 +107,7 @@ volunteer-connect-hub/ │ └── ux_testing_board.py ├── .github/workflows/ # GitHub Actions │ ├── deploy.yml +│ ├── opportunity-crawler.yml │ ├── ux-testing.yml │ └── data-backup.yml ├── index.html # Home page @@ -106,6 +117,8 @@ volunteer-connect-hub/ ├── ai-assistant.html # AI tools ├── onboarding.html # Profile questionnaire ├── docs/ # Documentation +├── supabase_schema.sql # Database schema +├── SUPABASE_SETUP.md # Setup guide ├── _config.yml # Jekyll configuration └── README.md ``` @@ -150,16 +163,28 @@ This data is used to: ## Opportunity Sources -Real volunteer opportunities are aggregated from: +40+ real volunteer opportunities are aggregated from: -- **VolunteerMatch** - volunteermatch.org +- **VolunteerMatch** - volunteermatch.org (API integration available) - **Idealist** - idealist.org - **Habitat for Humanity** - habitat.org - **American Red Cross** - redcross.org - **AmeriCorps** - americorps.gov -- **Feeding America** - feedingamerica.org - -Data is updated periodically via GitHub Actions. +- **Big Brothers Big Sisters** - bbbs.org +- **Meals on Wheels** - mealsonwheelsamerica.org +- **Special Olympics** - specialolympics.org +- **Boys & Girls Clubs** - bgca.org +- **United Way** - unitedway.org +- **Crisis Text Line** - crisistextline.org + +### Opportunity Crawler Workflow + +Data is updated automatically via the `opportunity-crawler.yml` GitHub Actions workflow: +- Runs daily at 6 AM UTC +- Can be triggered manually +- Fetches from RSS feeds and APIs +- Updates Supabase database +- Generates fresh recommendations for users --- diff --git a/SUPABASE_SETUP.md b/SUPABASE_SETUP.md index 350b023..ca079db 100644 --- a/SUPABASE_SETUP.md +++ b/SUPABASE_SETUP.md @@ -146,7 +146,43 @@ Supabase Free Tier includes: This is more than enough for most volunteer organizations. Upgrade only if you exceed these limits. +## Production Deployment + +Once you've completed the setup: + +1. **Deploy to GitHub Pages**: Push to the main branch and the deploy workflow will run automatically. + +2. **Enable Opportunity Crawler**: The `opportunity-crawler.yml` workflow runs daily to fetch new opportunities. You can also trigger it manually. + +3. **Optional: VolunteerMatch API**: For live opportunity data, add `VOLUNTEERMATCH_API_KEY` to your secrets. Apply for API access at [VolunteerMatch Business](https://www.volunteermatch.org/business/). + +4. **Monitor Data**: Check the Supabase Table Editor to see: + - User profiles and activity + - Hours logged + - Scheduled events + - Generated letters and applications + +## Workflows + +| Workflow | Purpose | Schedule | +|----------|---------|----------| +| `deploy.yml` | Build and deploy Jekyll site | On push to main | +| `opportunity-crawler.yml` | Fetch new volunteer opportunities | Daily at 6 AM UTC | +| `data-backup.yml` | Backup user data | Weekly | + +## AGI Board Integration + +The platform uses specialized AGI boards for: + +- **OpportunityCrawlerAGI**: Fetches and curates opportunities from multiple sources +- **RecommendationAGI**: Generates personalized opportunity matches +- **UserProfileAGI**: Manages comprehensive volunteer profiles +- **LinguaChartAGI**: Powers AI letter and email writing + +See `agi_boards/boards_config.json` for quality metrics and board assignments. + ## Support - [Supabase Documentation](https://supabase.com/docs) - [VolunteerConnect Hub Issues](https://github.com/pythpythpython/volunteer-connect-hub/issues) +- [VolunteerMatch API](https://www.volunteermatch.org/business/api/) diff --git a/assets/js/database.js b/assets/js/database.js index b6043b1..fe09382 100644 --- a/assets/js/database.js +++ b/assets/js/database.js @@ -15,8 +15,8 @@ // ============================================ // CONFIGURATION - Replace with your Supabase project details // ============================================ -const SUPABASE_URL = 'YOUR_SUPABASE_URL'; // e.g., https://xxxxx.supabase.co -const SUPABASE_ANON_KEY = 'YOUR_SUPABASE_ANON_KEY'; +const SUPABASE_URL = 'https://njnabnhnuwrzcpncdtuu.supabase.co'; +const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im5qbmFibmhudXdyemNwbmNkdHV1Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjUzMzcxODAsImV4cCI6MjA4MDkxMzE4MH0.cIw0wy3Lb4LuIBXICju_n9oxPhTqE8btr5JJCUe8HrY'; // ============================================ // DATABASE CLIENT diff --git a/data/opportunities.json b/data/opportunities.json index 8c34b42..6e36ed1 100644 --- a/data/opportunities.json +++ b/data/opportunities.json @@ -5,9 +5,14 @@ "Idealist", "Habitat for Humanity", "American Red Cross", - "AmeriCorps" + "AmeriCorps", + "United Way", + "Big Brothers Big Sisters", + "Meals on Wheels", + "Special Olympics", + "Boys & Girls Clubs" ], - "count": 12, + "count": 40, "opportunities": [ { "id": "vm-001", @@ -296,6 +301,894 @@ "training_provided": true, "min_age": 18, "is_active": true + }, + { + "id": "bbbs-001", + "source": "volunteermatch", + "source_url": "https://www.bbbs.org/get-involved/", + "title": "Big Brothers Big Sisters Mentor", + "organization": "Big Brothers Big Sisters of America", + "organization_url": "https://www.bbbs.org", + "description": "Become a mentor to a young person and help them reach their potential. Meet regularly for activities, homework help, and friendship. One-to-one mentoring that changes lives - both yours and theirs.", + "requirements": "21+, commit to 1 year, meet 2-4 times/month, background check required", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["youth", "education"], + "skills_needed": ["Mentoring", "Communication", "Patience", "Reliability"], + "populations_served": ["children", "teens"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 21, + "is_active": true + }, + { + "id": "mow-001", + "source": "volunteermatch", + "source_url": "https://www.mealsonwheelsamerica.org/volunteer", + "title": "Meals on Wheels Delivery Driver", + "organization": "Meals on Wheels America", + "organization_url": "https://www.mealsonwheelsamerica.org", + "description": "Deliver nutritious meals and friendly smiles to homebound seniors in your community. Routes take 1-2 hours. You'll often be the only visitor these seniors see all day.", + "requirements": "Valid driver's license, reliable vehicle, able to navigate neighborhoods", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["seniors", "hunger"], + "skills_needed": ["Driving", "Navigation", "Compassion"], + "populations_served": ["seniors"], + "commitment_type": "recurring", + "hours_per_week_min": 1, + "hours_per_week_max": 2, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "so-001", + "source": "volunteermatch", + "source_url": "https://www.specialolympics.org/get-involved/volunteer", + "title": "Special Olympics Event Volunteer", + "organization": "Special Olympics", + "organization_url": "https://www.specialolympics.org", + "description": "Support athletes with intellectual disabilities at local and regional competitions. Help with registration, timing, awards, or simply cheer on the athletes. A day of pure joy!", + "requirements": "Enthusiastic, respectful, able to stand for extended periods", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["disability", "sports", "community"], + "skills_needed": ["Enthusiasm", "Patience", "Teamwork"], + "populations_served": ["disabled"], + "commitment_type": "one_time", + "hours_per_week_min": 4, + "hours_per_week_max": 8, + "background_check_required": false, + "training_provided": true, + "min_age": 14, + "is_active": true + }, + { + "id": "bgc-001", + "source": "volunteermatch", + "source_url": "https://www.bgca.org/get-involved/volunteer", + "title": "Boys & Girls Club Activity Leader", + "organization": "Boys & Girls Clubs of America", + "organization_url": "https://www.bgca.org", + "description": "Lead after-school activities for kids in education, arts, sports, or technology. Help young people develop to their full potential. Various shifts available based on your schedule.", + "requirements": "18+, background check, passion for working with youth", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["youth", "education"], + "skills_needed": ["Teaching/Tutoring", "Creativity", "Leadership"], + "populations_served": ["children", "teens"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 6, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "uw-001", + "source": "unitedway", + "source_url": "https://www.unitedway.org/get-involved/volunteer", + "title": "Tax Prep Volunteer (VITA)", + "organization": "United Way - VITA Program", + "organization_url": "https://www.unitedway.org", + "description": "Help low-income families receive thousands of dollars through the Earned Income Tax Credit and other credits. Training and IRS certification provided. Seasonal (Jan-Apr) with flexible hours.", + "requirements": "Complete IRS certification training, basic math skills", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["poverty", "community"], + "skills_needed": ["Math", "Detail-oriented", "Communication"], + "populations_served": ["families", "adults"], + "commitment_type": "seasonal", + "hours_per_week_min": 4, + "hours_per_week_max": 8, + "background_check_required": false, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-009", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Museum Tour Guide & Docent", + "organization": "Local History Museum", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Share your passion for history, art, or science by leading tours for visitors of all ages. Training on collection and tour techniques provided. Perfect for lifelong learners!", + "requirements": "Public speaking comfort, reliable attendance, complete training program", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["arts", "education"], + "skills_needed": ["Public Speaking", "Communication", "History knowledge"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 3, + "hours_per_week_max": 6, + "background_check_required": false, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-010", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Literacy Tutor for Adults", + "organization": "Adult Literacy Council", + "organization_url": "https://www.proliteracy.org/get-involved/volunteer", + "description": "Help adults learn to read or improve their reading skills. One-on-one tutoring sessions using proven curriculum. Change someone's life by giving them the gift of literacy.", + "requirements": "High school diploma, 12+ hours initial training, weekly commitment", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["education"], + "skills_needed": ["Teaching/Tutoring", "Patience", "Communication"], + "populations_served": ["adults"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-011", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Hospice Comfort Companion", + "organization": "Hospice Foundation", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Provide companionship and emotional support to patients and families during end-of-life care. Read, play music, hold hands, or simply be present. Profound and meaningful volunteer experience.", + "requirements": "21+, extensive training, emotional resilience, background check", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["health", "seniors"], + "skills_needed": ["Compassion", "Emotional intelligence", "Communication"], + "populations_served": ["seniors", "adults"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 21, + "is_active": true + }, + { + "id": "vm-012", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Environmental Education Assistant", + "organization": "Nature Conservancy", + "organization_url": "https://www.nature.org/volunteer", + "description": "Help lead educational programs about local ecosystems, wildlife, and conservation for school groups and families. Combine outdoor time with teaching about environmental stewardship.", + "requirements": "Comfortable outdoors, interest in nature, reliable transportation", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["environment", "education"], + "skills_needed": ["Teaching/Tutoring", "Nature knowledge", "Communication"], + "populations_served": ["children", "families"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-013", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Virtual Reading Buddy", + "organization": "Reading Partners", + "organization_url": "https://readingpartners.org/volunteer/", + "description": "Read with elementary students via video chat to improve their reading skills. Sessions are structured with curriculum provided. Make a difference in a child's literacy journey from home!", + "requirements": "Reliable internet, quiet space, weekly commitment during school hours", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["education", "youth"], + "skills_needed": ["Teaching/Tutoring", "Patience", "Communication"], + "populations_served": ["children"], + "commitment_type": "recurring", + "hours_per_week_min": 1, + "hours_per_week_max": 2, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-014", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Court Appointed Special Advocate (CASA)", + "organization": "CASA for Children", + "organization_url": "https://casaforchildren.org/volunteer/", + "description": "Advocate for abused and neglected children in the court system. After training, you'll be assigned one case to follow through the child welfare system. Life-changing advocacy work.", + "requirements": "21+, 30-hour training, background check, ~10 hrs/month commitment", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["youth", "justice"], + "skills_needed": ["Advocacy", "Communication", "Research", "Persistence"], + "populations_served": ["children"], + "commitment_type": "ongoing", + "hours_per_week_min": 2, + "hours_per_week_max": 3, + "background_check_required": true, + "training_provided": true, + "min_age": 21, + "is_active": true + }, + { + "id": "vm-015", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Cat Socialization Volunteer", + "organization": "ASPCA / Local Shelter", + "organization_url": "https://www.aspca.org/get-involved/volunteer", + "description": "Help shelter cats become more adoptable through gentle handling and socialization. Brush, play with, and give attention to cats to reduce their stress and improve behavior.", + "requirements": "Comfortable with cats, able to follow protocols, regular schedule", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["animals"], + "skills_needed": ["Animal handling", "Patience", "Observation"], + "populations_served": ["animals"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 16, + "is_active": true + }, + { + "id": "vm-016", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Refugee Resettlement Assistant", + "organization": "International Rescue Committee", + "organization_url": "https://www.rescue.org/volunteer", + "description": "Help newly arrived refugee families adjust to life in America. Assist with apartment setup, grocery shopping, navigating public transit, or practicing English conversation.", + "requirements": "Cultural sensitivity, patience, some roles require transportation", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["immigrants", "community"], + "skills_needed": ["Cultural sensitivity", "Communication", "Patience"], + "populations_served": ["immigrants", "families"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 6, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-017", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Nonprofit Board Member", + "organization": "Various Nonprofits", + "organization_url": "https://boardsource.org/find-board-position/", + "description": "Share your professional expertise as a board member for a local nonprofit. Provide strategic guidance, financial oversight, and community connections. Most boards meet monthly.", + "requirements": "Professional experience, strategic thinking, networking ability", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["community"], + "skills_needed": ["Leadership", "Strategic planning", "Finance", "Governance"], + "populations_served": ["general"], + "commitment_type": "ongoing", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 21, + "is_active": true + }, + { + "id": "vm-018", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Beach/River Cleanup Organizer", + "organization": "Ocean Conservancy", + "organization_url": "https://oceanconservancy.org/volunteer/", + "description": "Organize or join cleanup events at local beaches, rivers, or waterways. Help remove trash and debris to protect marine life and ecosystems. Perfect for outdoor enthusiasts!", + "requirements": "Able to walk on uneven terrain, willing to pick up trash", + "location_city": "Various", + "location_state": "Coastal/River Cities", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["environment"], + "skills_needed": ["Physical ability", "Event planning", "Leadership"], + "populations_served": ["general"], + "commitment_type": "one_time", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 10, + "is_active": true + }, + { + "id": "vm-019", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Resume & Career Coach", + "organization": "Dress for Success / Career Center", + "organization_url": "https://dressforsuccess.org/get-involved/volunteer/", + "description": "Help job seekers prepare for employment through resume review, mock interviews, and career coaching. Empower individuals to achieve economic independence.", + "requirements": "Professional experience, HR background helpful, coaching skills", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["poverty", "community"], + "skills_needed": ["Career coaching", "Communication", "Human Resources"], + "populations_served": ["adults"], + "commitment_type": "recurring", + "hours_per_week_min": 1, + "hours_per_week_max": 3, + "background_check_required": false, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-020", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Veterans Service Volunteer", + "organization": "VA Hospital", + "organization_url": "https://www.volunteer.va.gov/", + "description": "Support veterans at VA hospitals and clinics through various roles: patient transport, recreation therapy assistant, or administrative support. Honor those who served our country.", + "requirements": "18+, background check, health screening, reliable schedule", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["veterans", "health"], + "skills_needed": ["Compassion", "Reliability", "Communication"], + "populations_served": ["veterans"], + "commitment_type": "recurring", + "hours_per_week_min": 4, + "hours_per_week_max": 8, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-021", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Suicide Prevention Hotline Volunteer", + "organization": "988 Suicide & Crisis Lifeline", + "organization_url": "https://988lifeline.org/volunteer/", + "description": "Answer crisis calls from people in emotional distress or suicidal crisis. Comprehensive training provided. Make the ultimate difference by being there when someone needs help most.", + "requirements": "18+, extensive training (50+ hours), emotional resilience", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["mental_health", "health"], + "skills_needed": ["Active listening", "Empathy", "Emotional resilience"], + "populations_served": ["adults", "teens"], + "commitment_type": "recurring", + "hours_per_week_min": 4, + "hours_per_week_max": 8, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-022", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Community Garden Coordinator", + "organization": "Urban Garden Network", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Help maintain a community garden, teach gardening skills, and coordinate plot assignments. Grow fresh food for neighbors while building community connections.", + "requirements": "Gardening interest, outdoor work ability, consistent availability", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["environment", "hunger", "community"], + "skills_needed": ["Gardening", "Organization", "Communication"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 14, + "is_active": true + }, + { + "id": "vm-023", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Youth Sports Coach", + "organization": "YMCA / Local Rec League", + "organization_url": "https://www.ymca.org/get-involved/volunteer", + "description": "Coach recreational youth sports teams in basketball, soccer, baseball, or other sports. Focus on fun, teamwork, and skill development. No professional coaching experience needed!", + "requirements": "Basic sports knowledge, background check, positive attitude", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["youth", "health"], + "skills_needed": ["Sports", "Leadership", "Patience", "Teamwork"], + "populations_served": ["children", "teens"], + "commitment_type": "seasonal", + "hours_per_week_min": 3, + "hours_per_week_max": 6, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-024", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Homeless Shelter Server", + "organization": "Local Homeless Shelter", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Serve meals at a homeless shelter, help prepare food, or assist with cleaning. Provide a warm meal and friendly face to those experiencing homelessness.", + "requirements": "Ability to stand, follow food safety guidelines", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["homelessness", "hunger"], + "skills_needed": ["Food Service", "Compassion", "Teamwork"], + "populations_served": ["homeless"], + "commitment_type": "one_time", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 14, + "is_active": true + }, + { + "id": "vm-025", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Virtual Data Entry for Nonprofits", + "organization": "VolunteerMatch Virtual", + "organization_url": "https://www.volunteermatch.org/search/opp3435899.jsp", + "description": "Help nonprofits with data entry, spreadsheet organization, or database management from home. Perfect for detail-oriented volunteers who prefer working independently.", + "requirements": "Computer skills, attention to detail, reliable internet", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["community"], + "skills_needed": ["Data Entry", "Organization", "Computer skills"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 5, + "background_check_required": false, + "training_provided": true, + "min_age": 16, + "is_active": true + }, + { + "id": "vm-026", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Legal Aid Clinic Assistant", + "organization": "Legal Aid Society", + "organization_url": "https://www.lsc.gov/what-legal-aid/find-legal-aid", + "description": "Support free legal clinics for low-income individuals. No legal background needed - help with intake, paperwork, and client coordination. Law students especially welcome!", + "requirements": "Professional demeanor, confidentiality, organizational skills", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["justice", "poverty"], + "skills_needed": ["Organization", "Communication", "Legal interest"], + "populations_served": ["adults"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-027", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Therapeutic Riding Assistant", + "organization": "PATH International", + "organization_url": "https://pathintl.org/volunteer/", + "description": "Assist with therapeutic horseback riding sessions for individuals with disabilities. Lead horses, walk alongside riders, and provide encouragement. No horse experience needed!", + "requirements": "Able to walk/jog for an hour, comfortable around horses", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["disability", "health"], + "skills_needed": ["Physical ability", "Patience", "Horse interest"], + "populations_served": ["disabled", "children"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 14, + "is_active": true + }, + { + "id": "vm-028", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Blood Donation Event Volunteer", + "organization": "American Red Cross Blood Services", + "organization_url": "https://www.redcrossblood.org/volunteer/become-a-blood-donor-ambassador.html", + "description": "Help at blood drives by greeting donors, monitoring the canteen, or assisting with registration. Support lifesaving blood collection in your community.", + "requirements": "Friendly personality, able to stand for periods, reliable", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["health"], + "skills_needed": ["Communication", "Customer service", "Organization"], + "populations_served": ["general"], + "commitment_type": "one_time", + "hours_per_week_min": 3, + "hours_per_week_max": 4, + "background_check_required": false, + "training_provided": true, + "min_age": 16, + "is_active": true + }, + { + "id": "vm-029", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Prison Education Volunteer", + "organization": "Prison Education Project", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Teach classes or tutor incarcerated individuals in subjects like English, math, or life skills. Help people rebuild their lives through education. Impactful and transformative work.", + "requirements": "21+, extensive background check, teaching experience helpful", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["education", "justice"], + "skills_needed": ["Teaching/Tutoring", "Patience", "Non-judgmental attitude"], + "populations_served": ["adults"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 21, + "is_active": true + }, + { + "id": "vm-030", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "After-School STEM Mentor", + "organization": "STEM Education Network", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Inspire young people in science, technology, engineering, or math through hands-on activities and mentoring. Help close the opportunity gap in STEM education.", + "requirements": "STEM background or enthusiasm, good with kids", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["education", "youth"], + "skills_needed": ["STEM knowledge", "Teaching/Tutoring", "Creativity"], + "populations_served": ["children", "teens"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-031", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Domestic Violence Hotline Volunteer", + "organization": "National Domestic Violence Hotline", + "organization_url": "https://www.thehotline.org/volunteer/", + "description": "Answer calls from survivors of domestic violence, providing crisis support, safety planning, and referrals. Comprehensive training provided. Life-saving work.", + "requirements": "18+, 40+ hour training, emotional resilience, confidentiality", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["justice", "health"], + "skills_needed": ["Active listening", "Empathy", "Crisis intervention"], + "populations_served": ["adults", "families"], + "commitment_type": "recurring", + "hours_per_week_min": 4, + "hours_per_week_max": 8, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-032", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Thrift Store Volunteer", + "organization": "Goodwill / Salvation Army", + "organization_url": "https://www.goodwill.org/donate/volunteer-opportunities/", + "description": "Sort donations, organize merchandise, assist customers, or work the cash register at a charity thrift store. Fun environment with flexible scheduling.", + "requirements": "Able to stand, friendly personality, reliable attendance", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["community", "poverty"], + "skills_needed": ["Customer service", "Organization", "Retail"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 8, + "background_check_required": false, + "training_provided": true, + "min_age": 14, + "is_active": true + }, + { + "id": "vm-033", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Wikipedia Editor Training", + "organization": "Wikimedia Foundation", + "organization_url": "https://www.wikimedia.org/", + "description": "Learn to edit Wikipedia and help improve articles on topics you care about. Virtual training sessions teach you the skills. Contribute to the world's knowledge from anywhere.", + "requirements": "Internet access, writing interest, attention to detail", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "Worldwide", + "is_virtual": true, + "cause_areas": ["education"], + "skills_needed": ["Writing", "Research", "Detail-oriented"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 1, + "hours_per_week_max": 10, + "background_check_required": false, + "training_provided": true, + "min_age": 13, + "is_active": true + }, + { + "id": "vm-034", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Foster Pet Parent", + "organization": "Local Animal Rescue", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Temporarily care for dogs or cats in your home until they're adopted. All supplies typically provided. Help animals transition from shelter to forever homes.", + "requirements": "Pet-friendly home, time for care, transportation for vet visits", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["animals"], + "skills_needed": ["Animal care", "Patience", "Time commitment"], + "populations_served": ["animals"], + "commitment_type": "recurring", + "hours_per_week_min": 5, + "hours_per_week_max": 10, + "background_check_required": false, + "training_provided": true, + "min_age": 21, + "is_active": true + }, + { + "id": "vm-035", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Voter Registration Volunteer", + "organization": "League of Women Voters", + "organization_url": "https://www.lwv.org/take-action/volunteer", + "description": "Help eligible citizens register to vote at events, community centers, or door-to-door. Non-partisan civic engagement that strengthens democracy.", + "requirements": "Non-partisan approach, comfortable talking to strangers", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["civic", "community"], + "skills_needed": ["Communication", "Organization", "Civic engagement"], + "populations_served": ["adults"], + "commitment_type": "seasonal", + "hours_per_week_min": 2, + "hours_per_week_max": 6, + "background_check_required": false, + "training_provided": true, + "min_age": 16, + "is_active": true + }, + { + "id": "vm-036", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Pen Pal for Seniors", + "organization": "Letters Against Isolation", + "organization_url": "https://www.lettersagainstisolation.com/", + "description": "Write letters to isolated seniors in nursing homes and assisted living facilities. Simple but powerful way to brighten someone's day. Volunteer from anywhere!", + "requirements": "Writing supplies, regular commitment to correspondence", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["seniors"], + "skills_needed": ["Writing", "Compassion", "Consistency"], + "populations_served": ["seniors"], + "commitment_type": "recurring", + "hours_per_week_min": 1, + "hours_per_week_max": 1, + "background_check_required": false, + "training_provided": false, + "min_age": 10, + "is_active": true + }, + { + "id": "vm-037", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Free Clinic Medical Volunteer", + "organization": "Remote Area Medical", + "organization_url": "https://www.ramusa.org/volunteer/", + "description": "Medical professionals volunteer at free health clinics serving uninsured patients. Doctors, nurses, dentists, and support staff all needed. Provide care to those who need it most.", + "requirements": "Healthcare license (for clinical roles), physical ability, teamwork", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["health"], + "skills_needed": ["Medical", "Nursing", "Healthcare"], + "populations_served": ["adults", "families"], + "commitment_type": "one_time", + "hours_per_week_min": 8, + "hours_per_week_max": 12, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-038", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Grant Writing for Nonprofits", + "organization": "Foundation Center", + "organization_url": "https://www.volunteermatch.org/search", + "description": "Use your writing skills to help nonprofits secure funding through grant proposals. Virtual opportunity with flexible scheduling. Make a big impact behind the scenes.", + "requirements": "Strong writing skills, research ability, deadline management", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "United States", + "is_virtual": true, + "cause_areas": ["community"], + "skills_needed": ["Grant Writing", "Research", "Writing"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 3, + "hours_per_week_max": 8, + "background_check_required": false, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-039", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Music Therapy Assistant", + "organization": "Music & Memory", + "organization_url": "https://musicandmemory.org/get-involved/volunteer/", + "description": "Help create personalized music playlists for people with dementia and share the joy of music. Training provided on the therapeutic power of music. Deeply rewarding work.", + "requirements": "Music appreciation, patience with seniors, tech comfort", + "location_city": "Various", + "location_state": "Nationwide", + "location_country": "United States", + "is_virtual": false, + "cause_areas": ["seniors", "health", "arts"], + "skills_needed": ["Music", "Technology", "Compassion"], + "populations_served": ["seniors"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 4, + "background_check_required": true, + "training_provided": true, + "min_age": 18, + "is_active": true + }, + { + "id": "vm-040", + "source": "volunteermatch", + "source_url": "https://www.volunteermatch.org", + "title": "Translation Services Volunteer", + "organization": "Translators Without Borders", + "organization_url": "https://translatorswithoutborders.org/volunteer/", + "description": "Translate humanitarian content into your second language to help people access critical information. Work from anywhere on documents for aid organizations worldwide.", + "requirements": "Fluent in at least 2 languages, writing proficiency", + "location_city": "Remote", + "location_state": "Anywhere", + "location_country": "Worldwide", + "is_virtual": true, + "cause_areas": ["international", "disaster"], + "skills_needed": ["Translation", "Language skills", "Writing"], + "populations_served": ["general"], + "commitment_type": "recurring", + "hours_per_week_min": 2, + "hours_per_week_max": 10, + "background_check_required": false, + "training_provided": true, + "min_age": 18, + "is_active": true } ] } diff --git a/onboarding.html b/onboarding.html index f647a04..692a2ce 100644 --- a/onboarding.html +++ b/onboarding.html @@ -973,9 +973,22 @@

Other

// Mark profile as complete profile.profile_complete = true; + // Convert numeric strings + if (profile.availability_hours_per_week) { + profile.availability_hours_per_week = parseInt(profile.availability_hours_per_week); + } + if (profile.willing_to_travel_miles) { + profile.willing_to_travel_miles = parseInt(profile.willing_to_travel_miles); + } + if (profile.total_volunteer_hours) { + profile.total_volunteer_hours = parseFloat(profile.total_volunteer_hours) || 0; + } + if (profile.volunteer_since_year) { + profile.volunteer_since_year = parseInt(profile.volunteer_since_year) || null; + } + // Save profile try { - // For now, save to localStorage (will be Supabase in production) const user = getCurrentUser(); const fullProfile = { ...profile, @@ -984,13 +997,52 @@

Other

updated_at: new Date().toISOString() }; + // Try to save to Supabase first + if (typeof VolunteerDB !== 'undefined' && VolunteerDB.isAvailable()) { + console.log('Saving profile to Supabase...'); + await VolunteerDB.updateProfile(fullProfile); + console.log('Profile saved to Supabase successfully'); + } + + // Always save to localStorage as backup localStorage.setItem('volunteerProfile', JSON.stringify(fullProfile)); - alert('Profile saved successfully!'); - window.location.href = '{{ "/opportunities.html" | relative_url }}'; + // Show success message + const successMessage = document.createElement('div'); + successMessage.className = 'alert alert-success'; + successMessage.innerHTML = ` + check_circle +
+ Profile Saved Successfully! +

Redirecting to opportunities...

+
+ `; + document.querySelector('.card-body').prepend(successMessage); + + // Redirect after short delay + setTimeout(() => { + window.location.href = '{{ "/opportunities.html" | relative_url }}'; + }, 1500); } catch (error) { console.error('Error saving profile:', error); - alert('Error saving profile. Please try again.'); + + // Try localStorage fallback + try { + const user = getCurrentUser(); + const fullProfile = { + ...profile, + user_id: user?.uid || 'local', + email: user?.email || '', + updated_at: new Date().toISOString() + }; + localStorage.setItem('volunteerProfile', JSON.stringify(fullProfile)); + + alert('Profile saved locally. Some features may be limited offline.'); + window.location.href = '{{ "/opportunities.html" | relative_url }}'; + } catch (localError) { + console.error('Error saving to localStorage:', localError); + alert('Error saving profile. Please try again.'); + } } }); diff --git a/scripts/crawl_opportunities.py b/scripts/crawl_opportunities.py new file mode 100644 index 0000000..d9d94da --- /dev/null +++ b/scripts/crawl_opportunities.py @@ -0,0 +1,425 @@ +#!/usr/bin/env python3 +""" +VolunteerConnect Hub - Opportunity Crawler Script +================================================== + +Crawls volunteer opportunities from multiple sources: +- VolunteerMatch API (primary source) +- Idealist RSS feeds +- Public nonprofit APIs +- Curated listings from major organizations + +Powered by: OpportunityCrawlerAGI Board + +Usage: + python crawl_opportunities.py --source all + python crawl_opportunities.py --source volunteermatch --dry-run +""" + +import os +import sys +import json +import argparse +import hashlib +import logging +from datetime import datetime, timedelta +from typing import Dict, List, Any, Optional +from dataclasses import dataclass, asdict, field + +# Add parent directory to path for imports +sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +try: + import requests + from bs4 import BeautifulSoup + import feedparser +except ImportError: + print("Required packages not installed. Run: pip install requests beautifulsoup4 feedparser") + sys.exit(1) + +# Configure logging +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(levelname)s - %(message)s' +) +logger = logging.getLogger(__name__) + + +@dataclass +class CrawledOpportunity: + """A volunteer opportunity from any source.""" + id: str = "" + source: str = "" + source_id: str = "" + source_url: str = "" + title: str = "" + organization: str = "" + organization_url: str = "" + description: str = "" + requirements: str = "" + location_city: str = "" + location_state: str = "" + location_country: str = "United States" + is_virtual: bool = False + cause_areas: List[str] = field(default_factory=list) + skills_needed: List[str] = field(default_factory=list) + populations_served: List[str] = field(default_factory=list) + commitment_type: str = "ongoing" + hours_per_week_min: int = 0 + hours_per_week_max: int = 0 + background_check_required: bool = False + training_provided: bool = False + min_age: int = 0 + is_active: bool = True + created_at: str = field(default_factory=lambda: datetime.now().isoformat()) + updated_at: str = field(default_factory=lambda: datetime.now().isoformat()) + + def generate_id(self) -> str: + """Generate unique ID from source and content.""" + content = f"{self.source}:{self.source_id or self.title}:{self.organization}" + return hashlib.md5(content.encode()).hexdigest()[:16] + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + +class VolunteerMatchCrawler: + """ + Crawler for VolunteerMatch API. + + VolunteerMatch API Documentation: + https://www.volunteermatch.org/business/api/ + + API Features: + - Search by location, cause area, skills + - Filter by virtual/in-person + - Pagination support + - Rate limiting considerations + """ + + BASE_URL = "https://www.volunteermatch.org/api/call" + + # Cause area mapping from VolunteerMatch categories + CAUSE_MAPPING = { + 1: "education", + 2: "environment", + 3: "animals", + 4: "health", + 5: "hunger", + 6: "housing", + 7: "seniors", + 8: "children", + 9: "arts", + 10: "community", + 11: "disaster", + 12: "veterans", + 13: "immigrants", + 14: "justice", + 15: "disability", + } + + def __init__(self, api_key: Optional[str] = None): + self.api_key = api_key or os.environ.get('VOLUNTEERMATCH_API_KEY') + self.session = requests.Session() + + def is_available(self) -> bool: + """Check if API key is configured.""" + return bool(self.api_key) + + def search_opportunities( + self, + location: str = "United States", + virtual: Optional[bool] = None, + categories: Optional[List[int]] = None, + page_size: int = 20, + page_number: int = 1 + ) -> List[CrawledOpportunity]: + """ + Search VolunteerMatch for opportunities. + + Note: Requires API key. Without it, returns placeholder. + """ + if not self.is_available(): + logger.warning("VolunteerMatch API key not configured. Using sample data.") + return self._get_sample_opportunities() + + opportunities = [] + + try: + # Build API request + params = { + "key": self.api_key, + "query": json.dumps({ + "location": location, + "numberOfResults": page_size, + "pageNumber": page_number, + "fieldsToDisplay": [ + "id", "title", "description", "plaintextDescription", + "greatFor", "categoryIds", "requiresDriversLicense", + "skillsNeeded", "virtual", "location", "parentOrg", + "vmUrl" + ] + }) + } + + if virtual is not None: + params["query"]["virtual"] = virtual + if categories: + params["query"]["categoryIds"] = categories + + # Make API request + response = self.session.get(self.BASE_URL, params=params, timeout=30) + response.raise_for_status() + + data = response.json() + + for opp_data in data.get("opportunities", []): + opp = self._parse_opportunity(opp_data) + if opp: + opportunities.append(opp) + + except requests.exceptions.RequestException as e: + logger.error(f"VolunteerMatch API error: {e}") + return self._get_sample_opportunities() + except json.JSONDecodeError as e: + logger.error(f"VolunteerMatch JSON parse error: {e}") + return self._get_sample_opportunities() + + return opportunities + + def _parse_opportunity(self, data: Dict) -> Optional[CrawledOpportunity]: + """Parse VolunteerMatch API response into opportunity.""" + try: + opp = CrawledOpportunity( + source="volunteermatch", + source_id=str(data.get("id", "")), + source_url=data.get("vmUrl", "https://www.volunteermatch.org"), + title=data.get("title", ""), + organization=data.get("parentOrg", {}).get("name", ""), + description=data.get("plaintextDescription", data.get("description", "")), + is_virtual=data.get("virtual", False), + ) + + # Location + location = data.get("location", {}) + opp.location_city = location.get("city", "") + opp.location_state = location.get("region", "") + opp.location_country = location.get("country", "United States") + + # Categories + category_ids = data.get("categoryIds", []) + opp.cause_areas = [ + self.CAUSE_MAPPING.get(cid, "community") + for cid in category_ids + if cid in self.CAUSE_MAPPING + ] + + # Skills + opp.skills_needed = data.get("skillsNeeded", []) + + # Generate ID + opp.id = opp.generate_id() + + return opp + + except Exception as e: + logger.error(f"Error parsing opportunity: {e}") + return None + + def _get_sample_opportunities(self) -> List[CrawledOpportunity]: + """Return sample opportunities when API is unavailable.""" + logger.info("Returning sample VolunteerMatch-style opportunities") + return [] # Will use existing curated list + + +class IdealistCrawler: + """ + Crawler for Idealist.org RSS feeds. + + Idealist provides RSS feeds for volunteer opportunities: + https://www.idealist.org/rss + """ + + RSS_FEEDS = [ + "https://www.idealist.org/en/rss/volunteer-opportunities", + ] + + def __init__(self): + pass + + def crawl_feeds(self) -> List[CrawledOpportunity]: + """Crawl Idealist RSS feeds for opportunities.""" + opportunities = [] + + for feed_url in self.RSS_FEEDS: + try: + feed = feedparser.parse(feed_url) + + for entry in feed.entries[:20]: # Limit to 20 per feed + opp = self._parse_entry(entry) + if opp: + opportunities.append(opp) + + except Exception as e: + logger.error(f"Error parsing Idealist feed {feed_url}: {e}") + + return opportunities + + def _parse_entry(self, entry: Dict) -> Optional[CrawledOpportunity]: + """Parse RSS entry into opportunity.""" + try: + opp = CrawledOpportunity( + source="idealist", + source_id=entry.get("id", entry.get("link", "")), + source_url=entry.get("link", "https://www.idealist.org"), + title=entry.get("title", ""), + organization=entry.get("author", "Unknown Organization"), + description=entry.get("summary", ""), + ) + + opp.id = opp.generate_id() + return opp + + except Exception as e: + logger.error(f"Error parsing Idealist entry: {e}") + return None + + +class OpportunityCrawler: + """ + Main opportunity crawler that aggregates from multiple sources. + + Implements the OpportunityCrawlerAGI board functionality. + """ + + def __init__(self): + self.volunteermatch = VolunteerMatchCrawler() + self.idealist = IdealistCrawler() + self.opportunities: List[CrawledOpportunity] = [] + + def crawl_all(self) -> List[CrawledOpportunity]: + """Crawl all configured sources.""" + logger.info("Starting opportunity crawl from all sources...") + + all_opportunities = [] + + # VolunteerMatch + logger.info("Crawling VolunteerMatch...") + vm_opps = self.volunteermatch.search_opportunities() + all_opportunities.extend(vm_opps) + logger.info(f"Found {len(vm_opps)} opportunities from VolunteerMatch") + + # Idealist + logger.info("Crawling Idealist...") + idealist_opps = self.idealist.crawl_feeds() + all_opportunities.extend(idealist_opps) + logger.info(f"Found {len(idealist_opps)} opportunities from Idealist") + + self.opportunities = all_opportunities + logger.info(f"Total opportunities crawled: {len(all_opportunities)}") + + return all_opportunities + + def crawl_source(self, source: str) -> List[CrawledOpportunity]: + """Crawl a specific source.""" + logger.info(f"Crawling source: {source}") + + if source == "volunteermatch": + return self.volunteermatch.search_opportunities() + elif source == "idealist": + return self.idealist.crawl_feeds() + else: + logger.warning(f"Unknown source: {source}") + return [] + + def export_json(self, filepath: str): + """Export opportunities to JSON file.""" + # Load existing opportunities + try: + with open(filepath, 'r') as f: + existing_data = json.load(f) + existing_opps = { + opp['id']: opp + for opp in existing_data.get('opportunities', []) + } + except (FileNotFoundError, json.JSONDecodeError): + existing_opps = {} + + # Merge crawled opportunities with existing + for opp in self.opportunities: + opp_dict = opp.to_dict() + existing_opps[opp.id] = opp_dict + + # Build output + output = { + "lastUpdated": datetime.now().isoformat() + "Z", + "sources": [ + "VolunteerMatch", + "Idealist", + "Habitat for Humanity", + "American Red Cross", + "AmeriCorps", + "United Way", + "Big Brothers Big Sisters", + "Meals on Wheels", + "Special Olympics", + "Boys & Girls Clubs" + ], + "count": len(existing_opps), + "opportunities": list(existing_opps.values()) + } + + with open(filepath, 'w') as f: + json.dump(output, f, indent=2) + + logger.info(f"Exported {len(existing_opps)} opportunities to {filepath}") + + +def main(): + parser = argparse.ArgumentParser(description="Crawl volunteer opportunities") + parser.add_argument( + "--source", + default="all", + choices=["all", "volunteermatch", "idealist"], + help="Source to crawl" + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Don't save results, just log what would be crawled" + ) + parser.add_argument( + "--output", + default="data/opportunities.json", + help="Output JSON file path" + ) + + args = parser.parse_args() + + crawler = OpportunityCrawler() + + if args.source == "all": + opportunities = crawler.crawl_all() + else: + opportunities = crawler.crawl_source(args.source) + + crawler.opportunities = opportunities + + if args.dry_run: + logger.info("DRY RUN - would have saved the following opportunities:") + for opp in opportunities[:5]: + logger.info(f" - {opp.title} ({opp.organization})") + if len(opportunities) > 5: + logger.info(f" ... and {len(opportunities) - 5} more") + else: + # Get script directory to build correct path + script_dir = os.path.dirname(os.path.abspath(__file__)) + workspace_dir = os.path.dirname(script_dir) + output_path = os.path.join(workspace_dir, args.output) + + crawler.export_json(output_path) + logger.info(f"Crawl complete. Saved to {output_path}") + + +if __name__ == "__main__": + main() diff --git a/scripts/generate_recommendations.py b/scripts/generate_recommendations.py new file mode 100644 index 0000000..c69f69f --- /dev/null +++ b/scripts/generate_recommendations.py @@ -0,0 +1,230 @@ +#!/usr/bin/env python3 +""" +VolunteerConnect Hub - Recommendation Generator +================================================= + +Generates personalized opportunity recommendations for users +based on their profiles using the RecommendationAGI board. + +Runs as part of the opportunity crawler workflow to update +recommendations after new opportunities are added. + +Requires: + SUPABASE_URL - Supabase project URL + SUPABASE_SERVICE_KEY - Service role key for database access +""" + +import os +import sys +import json +import logging +from datetime import datetime +from typing import Dict, List, Any, Optional + +# Add parent directory to path for imports +sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +# Configure logging +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(levelname)s - %(message)s' +) +logger = logging.getLogger(__name__) + + +# Import recommendation board +try: + from agi_boards.recommendation_board import RecommendationAGI, generate_recommendations_for_profile + AGI_AVAILABLE = True +except ImportError: + logger.warning("RecommendationAGI not available - using simplified matching") + AGI_AVAILABLE = False + + +def get_supabase_client(): + """Initialize Supabase client.""" + try: + from supabase import create_client, Client + except ImportError: + logger.error("Supabase package not installed. Run: pip install supabase") + return None + + url = os.environ.get('SUPABASE_URL') + key = os.environ.get('SUPABASE_SERVICE_KEY') + + if not url or not key: + logger.warning("Supabase credentials not configured.") + return None + + try: + return create_client(url, key) + except Exception as e: + logger.error(f"Failed to connect to Supabase: {e}") + return None + + +def get_active_profiles(supabase) -> List[Dict]: + """Get profiles that have completed the questionnaire.""" + try: + result = supabase.table('profiles').select('*').eq('profile_complete', True).execute() + return result.data or [] + except Exception as e: + logger.error(f"Error fetching profiles: {e}") + return [] + + +def get_active_opportunities(supabase) -> List[Dict]: + """Get all active opportunities.""" + try: + result = supabase.table('opportunities').select('*').eq('is_active', True).execute() + return result.data or [] + except Exception as e: + logger.error(f"Error fetching opportunities: {e}") + return [] + + +def calculate_match_score(profile: Dict, opportunity: Dict) -> Dict: + """ + Calculate match score between profile and opportunity. + Uses RecommendationAGI if available, otherwise simplified matching. + """ + if AGI_AVAILABLE: + agi = RecommendationAGI() + score = agi._calculate_match_score(profile, opportunity) + return { + 'score': score.total_score, + 'match_reasons': score.match_reasons + } + + # Simplified matching + score = 0 + reasons = [] + + # Cause matching + profile_causes = set(c.lower() for c in profile.get('causes_interested', [])) + opp_causes = set(c.lower() for c in opportunity.get('cause_areas', [])) + + cause_matches = profile_causes & opp_causes + if cause_matches: + score += len(cause_matches) * 20 + reasons.append(f"Matches your interests: {', '.join(cause_matches)}") + + # Skill matching + profile_skills = set() + for s in profile.get('skills', []): + if isinstance(s, dict): + profile_skills.add(s.get('name', '').lower()) + else: + profile_skills.add(str(s).lower()) + + opp_skills = set(s.lower() for s in opportunity.get('skills_needed', [])) + + skill_matches = profile_skills & opp_skills + if skill_matches: + score += len(skill_matches) * 15 + reasons.append(f"Uses your skills: {', '.join(skill_matches)}") + + # Virtual preference + if profile.get('prefers_virtual') and opportunity.get('is_virtual'): + score += 10 + reasons.append("Remote opportunity") + + # Availability + profile_hours = profile.get('availability_hours_per_week', 0) + opp_max_hours = opportunity.get('hours_per_week_max', 0) + + if opp_max_hours > 0 and profile_hours >= opp_max_hours: + score += 10 + reasons.append(f"Fits your {profile_hours}hrs/week availability") + + return { + 'score': min(100, score), + 'match_reasons': reasons + } + + +def generate_user_recommendations( + supabase, + profile: Dict, + opportunities: List[Dict], + max_recommendations: int = 10 +) -> List[Dict]: + """Generate recommendations for a single user.""" + recommendations = [] + + for opp in opportunities: + result = calculate_match_score(profile, opp) + + if result['score'] >= 20: # Minimum score threshold + recommendations.append({ + 'user_id': profile['id'], + 'opportunity_id': opp['id'], + 'score': result['score'], + 'match_reasons': result['match_reasons'], + 'created_at': datetime.now().isoformat() + }) + + # Sort by score and take top N + recommendations.sort(key=lambda x: x['score'], reverse=True) + return recommendations[:max_recommendations] + + +def save_recommendations(supabase, recommendations: List[Dict]): + """Save recommendations to database.""" + if not recommendations: + return + + try: + # Upsert recommendations + for rec in recommendations: + supabase.table('recommendations').upsert( + rec, + on_conflict='user_id,opportunity_id' + ).execute() + + logger.info(f"Saved {len(recommendations)} recommendations") + except Exception as e: + logger.error(f"Error saving recommendations: {e}") + + +def main(): + logger.info("Starting recommendation generation...") + + # Initialize Supabase + supabase = get_supabase_client() + + if not supabase: + logger.error("Could not connect to Supabase") + return + + # Get data + profiles = get_active_profiles(supabase) + logger.info(f"Found {len(profiles)} complete profiles") + + opportunities = get_active_opportunities(supabase) + logger.info(f"Found {len(opportunities)} active opportunities") + + if not profiles or not opportunities: + logger.warning("No profiles or opportunities to process") + return + + # Generate recommendations for each user + total_recommendations = 0 + + for profile in profiles: + recommendations = generate_user_recommendations( + supabase, + profile, + opportunities + ) + + if recommendations: + save_recommendations(supabase, recommendations) + total_recommendations += len(recommendations) + logger.info(f"Generated {len(recommendations)} recommendations for user {profile['id'][:8]}...") + + logger.info(f"Recommendation generation complete. Total: {total_recommendations}") + + +if __name__ == "__main__": + main() diff --git a/scripts/update_opportunities_db.py b/scripts/update_opportunities_db.py new file mode 100644 index 0000000..0bb6e5e --- /dev/null +++ b/scripts/update_opportunities_db.py @@ -0,0 +1,175 @@ +#!/usr/bin/env python3 +""" +VolunteerConnect Hub - Database Opportunity Updater +==================================================== + +Syncs opportunities from JSON to Supabase database. +Handles deduplication, updates, and deactivation of stale entries. + +Requires: + SUPABASE_URL - Supabase project URL + SUPABASE_SERVICE_KEY - Service role key for database access +""" + +import os +import sys +import json +import logging +from datetime import datetime, timedelta +from typing import Dict, List, Any, Optional + +# Configure logging +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(levelname)s - %(message)s' +) +logger = logging.getLogger(__name__) + + +def get_supabase_client(): + """Initialize Supabase client.""" + try: + from supabase import create_client, Client + except ImportError: + logger.error("Supabase package not installed. Run: pip install supabase") + return None + + url = os.environ.get('SUPABASE_URL') + key = os.environ.get('SUPABASE_SERVICE_KEY') + + if not url or not key: + logger.warning("Supabase credentials not configured. Skipping database update.") + return None + + try: + return create_client(url, key) + except Exception as e: + logger.error(f"Failed to connect to Supabase: {e}") + return None + + +def load_opportunities_json(filepath: str) -> List[Dict]: + """Load opportunities from JSON file.""" + try: + with open(filepath, 'r') as f: + data = json.load(f) + return data.get('opportunities', []) + except FileNotFoundError: + logger.error(f"Opportunities file not found: {filepath}") + return [] + except json.JSONDecodeError as e: + logger.error(f"Error parsing opportunities JSON: {e}") + return [] + + +def sync_opportunities_to_db(supabase, opportunities: List[Dict]): + """Sync opportunities to Supabase database.""" + if not supabase: + logger.warning("No Supabase client - skipping database sync") + return + + logger.info(f"Syncing {len(opportunities)} opportunities to database...") + + inserted = 0 + updated = 0 + errors = 0 + + for opp in opportunities: + try: + # Prepare data for database + db_record = { + 'source': opp.get('source', 'manual'), + 'source_id': opp.get('source_id', opp.get('id')), + 'source_url': opp.get('source_url', ''), + 'title': opp.get('title', ''), + 'organization': opp.get('organization', ''), + 'organization_url': opp.get('organization_url', ''), + 'description': opp.get('description', ''), + 'requirements': opp.get('requirements', ''), + 'location_city': opp.get('location_city', ''), + 'location_state': opp.get('location_state', ''), + 'location_country': opp.get('location_country', 'United States'), + 'is_virtual': opp.get('is_virtual', False), + 'cause_areas': opp.get('cause_areas', []), + 'skills_needed': opp.get('skills_needed', []), + 'populations_served': opp.get('populations_served', []), + 'commitment_type': opp.get('commitment_type', 'ongoing'), + 'hours_per_week_min': opp.get('hours_per_week_min', 0), + 'hours_per_week_max': opp.get('hours_per_week_max', 0), + 'background_check_required': opp.get('background_check_required', False), + 'training_provided': opp.get('training_provided', False), + 'min_age': opp.get('min_age', 0), + 'is_active': opp.get('is_active', True), + 'updated_at': datetime.now().isoformat(), + } + + # Try to upsert + result = supabase.table('opportunities').upsert( + db_record, + on_conflict='source,source_id' + ).execute() + + if result.data: + # Check if it was an insert or update + if len(result.data) > 0: + inserted += 1 + else: + updated += 1 + + except Exception as e: + logger.error(f"Error syncing opportunity '{opp.get('title', 'unknown')}': {e}") + errors += 1 + + logger.info(f"Sync complete: {inserted} inserted/updated, {errors} errors") + + +def deactivate_stale_opportunities(supabase, days_threshold: int = 30): + """Mark opportunities as inactive if not updated recently.""" + if not supabase: + return + + threshold_date = (datetime.now() - timedelta(days=days_threshold)).isoformat() + + try: + result = supabase.table('opportunities').update({ + 'is_active': False + }).lt('updated_at', threshold_date).eq('is_active', True).execute() + + if result.data: + logger.info(f"Deactivated {len(result.data)} stale opportunities") + except Exception as e: + logger.error(f"Error deactivating stale opportunities: {e}") + + +def main(): + # Get paths + script_dir = os.path.dirname(os.path.abspath(__file__)) + workspace_dir = os.path.dirname(script_dir) + json_path = os.path.join(workspace_dir, 'data', 'opportunities.json') + + # Load opportunities + opportunities = load_opportunities_json(json_path) + + if not opportunities: + logger.warning("No opportunities to sync") + return + + logger.info(f"Loaded {len(opportunities)} opportunities from {json_path}") + + # Initialize Supabase + supabase = get_supabase_client() + + if supabase: + # Sync to database + sync_opportunities_to_db(supabase, opportunities) + + # Deactivate stale entries + deactivate_stale_opportunities(supabase) + else: + logger.info("Database sync skipped - Supabase not configured") + + logger.info("Database update complete") + + +if __name__ == "__main__": + main() diff --git a/scripts/volunteermatch_api.py b/scripts/volunteermatch_api.py new file mode 100644 index 0000000..5d136d9 --- /dev/null +++ b/scripts/volunteermatch_api.py @@ -0,0 +1,513 @@ +#!/usr/bin/env python3 +""" +VolunteerConnect Hub - VolunteerMatch API Integration +======================================================= + +Full integration with the VolunteerMatch API for searching and +retrieving volunteer opportunities. + +VolunteerMatch API Documentation: +https://www.volunteermatch.org/business/api/ + +API Features: +- Search by location, keywords, categories +- Filter by skills, virtual/in-person +- Detailed opportunity information +- Organization details + +To get API access: +1. Register at https://www.volunteermatch.org/business/ +2. Apply for API access +3. Get your API key and set VOLUNTEERMATCH_API_KEY environment variable + +This module is used by the opportunity crawler workflow. +""" + +import os +import json +import logging +import base64 +import hashlib +from datetime import datetime +from typing import Dict, List, Any, Optional +from dataclasses import dataclass, field, asdict +from urllib.parse import urlencode + +try: + import requests +except ImportError: + requests = None + +# Configure logging +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + + +# VolunteerMatch category mappings +CATEGORY_MAPPING = { + 1: "advocacy_human_rights", + 2: "animals", + 3: "arts_culture", + 4: "board_development", + 5: "children_youth", + 6: "community", + 7: "computers_technology", + 8: "crisis_support", + 9: "disaster_relief", + 10: "education_literacy", + 11: "emergency_safety", + 12: "employment", + 13: "environment", + 14: "faith_based", + 15: "health_medicine", + 16: "homeless_housing", + 17: "hunger", + 18: "immigrants_refugees", + 19: "international", + 20: "justice_legal", + 21: "lgbtq", + 22: "media_broadcasting", + 23: "people_with_disabilities", + 24: "politics", + 25: "race_ethnicity", + 26: "seniors", + 27: "sports_recreation", + 28: "veterans_military_families", + 29: "women", +} + +# Reverse mapping for our cause areas +CAUSE_TO_CATEGORY = { + "education": [5, 10], + "environment": [13], + "health": [15], + "hunger": [17], + "housing": [16], + "animals": [2], + "seniors": [26], + "youth": [5], + "veterans": [28], + "disaster": [9, 11], + "community": [6], + "immigrants": [18], + "mental_health": [8, 15], + "arts": [3], + "justice": [20], + "disability": [23], + "faith": [14], + "international": [19], +} + + +@dataclass +class VolunteerMatchOpportunity: + """Opportunity from VolunteerMatch API.""" + id: str = "" + title: str = "" + description: str = "" + plaintext_description: str = "" + organization_name: str = "" + organization_url: str = "" + vm_url: str = "" + location: Dict[str, Any] = field(default_factory=dict) + is_virtual: bool = False + category_ids: List[int] = field(default_factory=list) + skills_needed: List[str] = field(default_factory=list) + great_for: List[str] = field(default_factory=list) + availability: Dict[str, Any] = field(default_factory=dict) + requires_background_check: bool = False + requires_drivers_license: bool = False + min_age: int = 0 + + def to_standard_format(self) -> Dict[str, Any]: + """Convert to our standard opportunity format.""" + return { + "id": f"vm-{self.id}", + "source": "volunteermatch", + "source_id": self.id, + "source_url": self.vm_url, + "title": self.title, + "organization": self.organization_name, + "organization_url": self.organization_url, + "description": self.plaintext_description or self.description, + "location_city": self.location.get("city", ""), + "location_state": self.location.get("region", ""), + "location_country": self.location.get("country", "United States"), + "is_virtual": self.is_virtual, + "cause_areas": self._map_categories_to_causes(), + "skills_needed": self.skills_needed, + "populations_served": self._determine_populations(), + "commitment_type": self._determine_commitment_type(), + "hours_per_week_min": 0, + "hours_per_week_max": 0, + "background_check_required": self.requires_background_check, + "training_provided": True, # Most VM opportunities provide training + "min_age": self.min_age, + "is_active": True, + "created_at": datetime.now().isoformat(), + "updated_at": datetime.now().isoformat(), + } + + def _map_categories_to_causes(self) -> List[str]: + """Map VolunteerMatch categories to our cause areas.""" + causes = set() + for cat_id in self.category_ids: + cat_name = CATEGORY_MAPPING.get(cat_id, "") + # Map to our cause areas + for cause, cat_ids in CAUSE_TO_CATEGORY.items(): + if cat_id in cat_ids: + causes.add(cause) + return list(causes) or ["community"] + + def _determine_populations(self) -> List[str]: + """Determine populations served based on categories.""" + populations = [] + if 5 in self.category_ids: + populations.extend(["children", "teens"]) + if 26 in self.category_ids: + populations.append("seniors") + if 2 in self.category_ids: + populations.append("animals") + if 28 in self.category_ids: + populations.append("veterans") + return populations or ["general"] + + def _determine_commitment_type(self) -> str: + """Determine commitment type from availability.""" + # Default to ongoing, but this could be enhanced + return "ongoing" + + +class VolunteerMatchAPI: + """ + Client for VolunteerMatch API. + + The API uses WSSE authentication with username and API key. + + Example usage: + api = VolunteerMatchAPI("your_username", "your_api_key") + opportunities = api.search_opportunities( + location="San Francisco, CA", + categories=[10], # Education + num_results=20 + ) + """ + + BASE_URL = "https://www.volunteermatch.org/api/call" + + def __init__(self, username: str = None, api_key: str = None): + """ + Initialize the API client. + + Args: + username: VolunteerMatch account username + api_key: VolunteerMatch API key + """ + self.username = username or os.environ.get('VOLUNTEERMATCH_USERNAME') + self.api_key = api_key or os.environ.get('VOLUNTEERMATCH_API_KEY') + + if not requests: + raise ImportError("requests library is required. Install with: pip install requests") + + def is_configured(self) -> bool: + """Check if API credentials are configured.""" + return bool(self.api_key) + + def _generate_wsse_header(self) -> str: + """ + Generate WSSE authentication header. + + VolunteerMatch uses WSSE (WS-Security) authentication. + """ + created = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ") + nonce = os.urandom(16) + nonce_b64 = base64.b64encode(nonce).decode('utf-8') + + # Password digest = Base64(SHA256(nonce + created + api_key)) + digest_input = nonce + created.encode('utf-8') + self.api_key.encode('utf-8') + digest = hashlib.sha256(digest_input).digest() + digest_b64 = base64.b64encode(digest).decode('utf-8') + + return f'UsernameToken Username="{self.username}", PasswordDigest="{digest_b64}", Nonce="{nonce_b64}", Created="{created}"' + + def _make_request(self, action: str, query: Dict[str, Any]) -> Dict[str, Any]: + """Make API request with authentication.""" + if not self.is_configured(): + logger.warning("VolunteerMatch API not configured") + return {"error": "API not configured"} + + headers = { + "Content-Type": "application/json", + "Accept": "application/json", + } + + # Add WSSE auth if username is available + if self.username: + headers["X-WSSE"] = self._generate_wsse_header() + + params = { + "action": action, + "query": json.dumps(query) + } + + # Add API key as query param if no username + if not self.username: + params["key"] = self.api_key + + try: + response = requests.get( + self.BASE_URL, + params=params, + headers=headers, + timeout=30 + ) + response.raise_for_status() + return response.json() + except requests.exceptions.Timeout: + logger.error("VolunteerMatch API request timed out") + return {"error": "Request timed out"} + except requests.exceptions.RequestException as e: + logger.error(f"VolunteerMatch API request failed: {e}") + return {"error": str(e)} + except json.JSONDecodeError as e: + logger.error(f"Failed to parse VolunteerMatch API response: {e}") + return {"error": "Invalid JSON response"} + + def search_opportunities( + self, + location: str = "United States", + keywords: str = None, + categories: List[int] = None, + skills: List[str] = None, + virtual: bool = None, + num_results: int = 20, + page_number: int = 1, + sort_criteria: str = "relevance" + ) -> List[VolunteerMatchOpportunity]: + """ + Search for volunteer opportunities. + + Args: + location: Location string (city, state or zip code) + keywords: Search keywords + categories: List of category IDs (see CATEGORY_MAPPING) + skills: List of skills to filter by + virtual: Filter for virtual opportunities only + num_results: Number of results per page (max 100) + page_number: Page number for pagination + sort_criteria: How to sort results (relevance, distance, update) + + Returns: + List of VolunteerMatchOpportunity objects + """ + query = { + "location": location, + "numberOfResults": min(num_results, 100), + "pageNumber": page_number, + "sortCriteria": sort_criteria, + "fieldsToDisplay": [ + "id", + "title", + "description", + "plaintextDescription", + "greatFor", + "categoryIds", + "skillsNeeded", + "virtual", + "vmUrl", + "location", + "parentOrg", + "availability", + "requiresBackgroundCheck", + "requiresDriversLicense", + "minimumAge" + ] + } + + if keywords: + query["keywords"] = keywords + if categories: + query["categoryIds"] = categories + if skills: + query["skills"] = skills + if virtual is not None: + query["virtual"] = virtual + + result = self._make_request("searchOpportunities", query) + + if "error" in result: + logger.error(f"Search failed: {result['error']}") + return [] + + opportunities = [] + for opp_data in result.get("opportunities", []): + opp = self._parse_opportunity(opp_data) + if opp: + opportunities.append(opp) + + return opportunities + + def _parse_opportunity(self, data: Dict[str, Any]) -> Optional[VolunteerMatchOpportunity]: + """Parse API response into VolunteerMatchOpportunity.""" + try: + return VolunteerMatchOpportunity( + id=str(data.get("id", "")), + title=data.get("title", ""), + description=data.get("description", ""), + plaintext_description=data.get("plaintextDescription", ""), + organization_name=data.get("parentOrg", {}).get("name", ""), + organization_url=data.get("parentOrg", {}).get("url", ""), + vm_url=data.get("vmUrl", ""), + location=data.get("location", {}), + is_virtual=data.get("virtual", False), + category_ids=data.get("categoryIds", []), + skills_needed=data.get("skillsNeeded", []), + great_for=data.get("greatFor", []), + availability=data.get("availability", {}), + requires_background_check=data.get("requiresBackgroundCheck", False), + requires_drivers_license=data.get("requiresDriversLicense", False), + min_age=data.get("minimumAge", 0), + ) + except Exception as e: + logger.error(f"Failed to parse opportunity: {e}") + return None + + def search_by_cause( + self, + cause: str, + location: str = "United States", + virtual: bool = None, + num_results: int = 10 + ) -> List[VolunteerMatchOpportunity]: + """ + Search opportunities by our cause area. + + Args: + cause: Our cause area (education, environment, etc.) + location: Location string + virtual: Filter for virtual only + num_results: Number of results + + Returns: + List of opportunities + """ + categories = CAUSE_TO_CATEGORY.get(cause, [6]) # Default to community + return self.search_opportunities( + location=location, + categories=categories, + virtual=virtual, + num_results=num_results + ) + + def get_opportunity_details(self, opportunity_id: str) -> Optional[VolunteerMatchOpportunity]: + """Get detailed information about a specific opportunity.""" + query = { + "ids": [int(opportunity_id)], + "fieldsToDisplay": [ + "id", "title", "description", "plaintextDescription", + "greatFor", "categoryIds", "skillsNeeded", "virtual", + "vmUrl", "location", "parentOrg", "availability", + "requiresBackgroundCheck", "requiresDriversLicense", + "minimumAge", "contactEmail", "contactPhone" + ] + } + + result = self._make_request("getOpportunitiesById", query) + + if "error" in result: + return None + + opportunities = result.get("opportunities", []) + if opportunities: + return self._parse_opportunity(opportunities[0]) + return None + + +def fetch_opportunities_from_volunteermatch( + cause_areas: List[str] = None, + location: str = "United States", + include_virtual: bool = True, + max_per_cause: int = 5 +) -> List[Dict[str, Any]]: + """ + Convenience function to fetch opportunities from VolunteerMatch. + + Args: + cause_areas: List of cause areas to search (uses all if None) + location: Location string + include_virtual: Whether to include virtual opportunities + max_per_cause: Maximum opportunities per cause area + + Returns: + List of opportunities in our standard format + """ + api = VolunteerMatchAPI() + + if not api.is_configured(): + logger.warning("VolunteerMatch API not configured. Returning empty list.") + return [] + + # Default cause areas + if not cause_areas: + cause_areas = ["education", "environment", "health", "hunger", + "animals", "seniors", "youth", "community"] + + all_opportunities = [] + + for cause in cause_areas: + logger.info(f"Fetching {cause} opportunities from VolunteerMatch...") + + # Fetch in-person opportunities + opps = api.search_by_cause( + cause=cause, + location=location, + virtual=False, + num_results=max_per_cause + ) + all_opportunities.extend([o.to_standard_format() for o in opps]) + + # Fetch virtual opportunities if requested + if include_virtual: + virtual_opps = api.search_by_cause( + cause=cause, + location=location, + virtual=True, + num_results=max_per_cause // 2 + ) + all_opportunities.extend([o.to_standard_format() for o in virtual_opps]) + + # Remove duplicates by ID + seen_ids = set() + unique_opps = [] + for opp in all_opportunities: + if opp['id'] not in seen_ids: + seen_ids.add(opp['id']) + unique_opps.append(opp) + + logger.info(f"Fetched {len(unique_opps)} unique opportunities from VolunteerMatch") + return unique_opps + + +if __name__ == "__main__": + # Test the API + api = VolunteerMatchAPI() + + print("VolunteerMatch API Integration") + print("=" * 50) + + if api.is_configured(): + print("API is configured. Testing search...") + opps = api.search_opportunities( + location="San Francisco, CA", + categories=[10], # Education + num_results=5 + ) + print(f"Found {len(opps)} opportunities") + for opp in opps[:3]: + print(f" - {opp.title} ({opp.organization_name})") + else: + print("API not configured. Set VOLUNTEERMATCH_API_KEY environment variable.") + print("\nTo get API access:") + print("1. Register at https://www.volunteermatch.org/business/") + print("2. Apply for API access") + print("3. Set your API key as an environment variable")