External API - Hala-f-Habash/Support-Orphans GitHub Wiki

External API

1. Gmail SMTP (Email Service)

1.1 What is it?

Google's email delivery system uses Simple Mail Transfer Protocol

I used it in the project to send an email to the orphanage managers to inform them that there were volunteers offering services that matched the services the orphanage needed to work with. I also used it to notify donors and sponsors of an emergency campaign on a specific topic for donations.

const orphanage = await matchRepo.getOrphanageInfo(request.orphanage_id);
  if (orphanage && matches.length > 0) {
    await sendEmail({
      to: orphanage.contact_email,
      subject: 'New Volunteer Match Found',
      html: `<p>Dear ${orphanage.name},</p>
        <p>${matches.length} volunteer(s) have been matched for your request.</p>
        <p>Service: ${request.service_type}</p>
        <p>Needed on: ${request.needed_date}</p>
        <p>HopeConnect Team</p>`
    });
  }

  return matches;
};


{
    "message": "Matching completed",
    "matches": [
        {
            "volunteer_id": 2,
            "service_type": "medical",
            "availability": "weekdays"
        },
        {
            "volunteer_id": 13,
            "service_type": "medical",
            "availability": "flexible"
        }
    ]
}

Email

2. OpenStreetMap (Mapping Service)

2.1 What is it?

Crowdsourced open geographic data

2.2 Key Features:

  • Free alternative to Google Maps
  • Provides street maps, points of interest
  • No API key required (but requires attribution)
if (location) {
      const validated = await validateLocation(location);
      if (!validated) {
        return res.status(400).json({ error: 'Invalid location. Please try correct one' });
      }

      formattedLocation = validated.formatted_address;
      lat = validated.lat;
      lon = validated.lon;
      map_url = `https://www.openstreetmap.org/?mlat=${lat}&mlon=${lon}`;
    }

    const campaignId = await campaignService.createCampaign({
      title,
      description,
      start_date: new Date(),
      status: true,
      location: formattedLocation
    });

    await campaignService.notifyDonors_Sponsors(title, description, formattedLocation);

exports.notifyDonors_Sponsors = async (title, description, location) => {
  const donors = await campaignRepo.getDonorEmails();

  for (const donor of donors) {
    const locationURL = location
      ? `https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(location)}`
      : 'https://hopeconnect.org/campaigns';

    await sendEmail({
      to: donor.email,
      subject: ` Emergency Campaign: ${title}`,
      html: `
        <p>Dear ${donor.name},</p>
        <p>We need your urgent support for: <strong>${title}</strong>.</p>
        <p>${description}</p>
        ${location ? `<p> Location: <a href="${locationURL}">${location}</a></p>` : ''}
        <p>- HopeConnect Emergency Team</p>
      `
    });
  }
};

map

3. bad-words (Content Filtering)

Node.js profanity filtering library

Key Features:

  • Local processing
  • Customizable word list

Typical Use Cases:

Filtering user comments

const Filter = require('bad-words');

exports.deleteReview = async (user, reviewId) => {

  const review = await reviewRepo.getReviewById(reviewId);

  // Orphanage managers - must check ownership
  if (user.role === 'orphanageManager') {
    const orphanage = await orphanageService.getOrphanageById(review.orphanage_id);
    if (!orphanage || orphanage.manager_id !== user.userId) {
      throw new Error('You are not allowed to delete this review');
    }
    const filter = new Filter();
         if (!filter.isProfane(review.comment)) {
          throw new Error('Cannot delete review: no inappropriate content');
          }
   
    return await reviewRepo.deleteReviewsByID(reviewId);
  }

  throw new Error('You are not authorized to delete reviews');
};
⚠️ **GitHub.com Fallback** ⚠️