API of this project - Hala-f-Habash/Support-Orphans GitHub Wiki

1. Sign-Up

In the users table in the project database, there are several roles, each of which has specific permissions. By signing up, the user can specify his role to add it to the users table.

1.1 Invalid Sign-up

API: http://localhost:3000/api/auth/register Method: POST

Request Body:

{
  "name": "",
  "email": "[email protected]",
  "password": "Noora",
  "role": ""
}

Response:

{
    "errors": [
        {
            "type": "field",
            "value": "",
            "msg": "Name is required",
            "path": "name",
            "location": "body"
        },
        {
            "type": "field",
            "value": "[email protected]",
            "msg": "Valid email is required",
            "path": "email",
            "location": "body"
        },
        {
            "type": "field",
            "value": "Noora",
            "msg": "Min 6 characters password",
            "path": "password",
            "location": "body"
        },
        {
            "type": "field",
            "value": "",
            "msg": "Invalid role",
            "path": "role",
            "location": "body"
        }
    ]
}

1.2 Sign-up-admin

API: http://localhost:3000/api/auth/register Method: POST
Request Body:

{
  "name": " waleed",
  "email": "[email protected]",
  "password": "WaleedWaleed",
  "role": "admin"
}

Response:

{
    "message": "User registered successfully",
    "user": {
        "id": 8,
        "name": " waleed",
        "email": "[email protected]",
        "role": "admin"
    }
}

1.3 Sign-up-donor

Request Body:

{
  "name": "Raghad",
  "email": "[email protected]",
  "password": "RaghadRaghad",
  "role": "donor"
}

Response:

{
    "message": "User registered successfully",
    "user": {
        "id": 15,
        "name": "Raghad",
        "email": "[email protected]",
        "role": "donor"
    }
}

1.4 Sign-up-volunteer

Request Body:

{
  "name": "noora",
  "email": "[email protected]",
  "password": "NooraNoora",
  "role": "volunteer"
}

Response:

{
    "message": "User registered successfully",
    "user": {
        "id": 14,
        "name": "noora",
        "email": "[email protected]",
        "role": "volunteer"
    }
}

1.5 Sign-up-sponsor

Request Body:

{
  "name": "rana",
  "email": "[email protected]",
  "password": "RanaRana",
  "role": "sponsor"
}

Response:

{
    "message": "User registered successfully",
    "user": {
        "id": 17,
        "name": "rana",
        "email": "[email protected]",
        "role": "sponsor"
    }
}

1.6 Sign-up-orphanageManager

Request Body:

{
  "name": "omar",
  "email": "[email protected]",
  "password": "OmarOmar",
  "role": "orphanageManager"
}

Response:

{
    "message": "User registered successfully",
    "user": {
        "id": 16,
        "name": "omar",
        "email": "[email protected]",
        "role": "orphanageManager"
    }
}

1.7 Sign-up-driver

Request Body:

{
  "name": "hasan",
  "email": "[email protected]",
  "password": "HasanHasan",
  "role": "driver"
}

Response:

{
    "message": "User registered successfully",
    "user": {
        "id": 18,
        "name": "hasan",
        "email": "[email protected]",
        "role": "driver"
    }
}

2. Log-In

To implement authentication for users in Node.js using JWT, and bcrypt for passwords, we use JWT to identify who the user is and to grant permissions , The response of the log-in contains the JWT of the user, to use it in the request header later.

2.1 Log-In-admin

API: http://localhost:3000/api/auth/login Method: POST

Request Body:

{
  "email": "[email protected]",
  "password": "WaleedWaleed"
}

Response:

{
    "message": "Login successful",
    "user": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjgsIm5hbWUiOiIgd2FsZWVkIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzQ3MTY1NTUyLCJleHAiOjE3NDcxNjkxNTJ9.xLB5vDB1TnOOBqyga9u-iM80RVII1JGzXYqihcjGcZQ",
        "user": {
            "id": 8,
            "name": " waleed",
            "email": "[email protected]",
            "role": "admin"
        }
    }
}

2.2 Log-In-sponsor

API: http://localhost:3000/api/auth/login Method: POST

Request Body:

{
  "email": "[email protected]",
  "password": "HalaHala"
}

Response:

{
    "message": "Login successful",
    "user": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjUsIm5hbWUiOiIgSGFsYSIsInJvbGUiOiJzcG9uc29yIiwiaWF0IjoxNzQ2OTY2OTE2LCJleHAiOjE3NDY5NzA1MTZ9.CrltDPW1khxxU5BjcFPEVjA88uXIJI3GQ1yysl6TfDw",
        "user": {
            "id": 5,
            "name": " Hala",
            "email": "[email protected]",
            "role": "sponsor"
        }
    }
}

2.3 Log-In-donor

Request Body:

{
  "email": "[email protected]",
  "password": "RemaRema"
}

Response:

{
    "message": "Login successful",
    "user": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyLCJuYW1lIjoiIHJlbWEiLCJyb2xlIjoiZG9ub3IiLCJpYXQiOjE3NDc0MDE2MjMsImV4cCI6MTc0NzQwNTIyM30.XVnJdYVDt3Jx2zt0eowCOwgeKr2s2EmsyXDTia0qG1k",
        "user": {
            "id": 12,
            "name": " rema",
            "email": "[email protected]",
            "role": "donor"
        }
    }
}

2.4Log-In-orphanageManager

Request Body:

{
  "email": "[email protected]",
  "password": "ReemReem"
}

Response:

{
    "message": "Login successful",
    "user": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEwLCJuYW1lIjoiIHJlZW0iLCJyb2xlIjoib3JwaGFuYWdlTWFuYWdlciIsImlhdCI6MTc0NzQwODk5NywiZXhwIjoxNzQ3NDEyNTk3fQ.fH8nS7RzV5-X3KIUSCqlh4rpZNfkdvPpWtDqcDCj9yU",
        "user": {
            "id": 10,
            "name": " reem",
            "email": "[email protected]",
            "role": "orphanageManager"
        }
    }
}

2.5 Log-In-volunteer

Request Body:

{
  "email": "[email protected]",
  "password": "ZainZain"
}

Response:

{
    "message": "Login successful",
    "user": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjksIm5hbWUiOiIgemFpbiIsInJvbGUiOiJ2b2x1bnRlZXIiLCJpYXQiOjE3NDc0MTQwNDIsImV4cCI6MTc0NzQxNzY0Mn0.tstz_OL22tlAPK-3905O8RsE0Vw7vytNda8LXk62b5I",
        "user": {
            "id": 9,
            "name": " zain",
            "email": "[email protected]",
            "role": "volunteer"
        }
    }
}

2.6 Log-In-driver

Request Body:

{
  "email": "[email protected]",
  "password": "HasanHasan"
}

Response:

{
    "message": "Login successful",
    "user": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjE4LCJuYW1lIjoiaGFzYW4iLCJyb2xlIjoiZHJpdmVyIiwiaWF0IjoxNzQ3NjU1OTkwLCJleHAiOjE3NDc2NTk1OTB9.49shSqfKF4qcbYcg6cErsjz6N3xrvH9glZtzOp9_9jU",
        "user": {
            "id": 18,
            "name": "hasan",
            "email": "[email protected]",
            "role": "driver"
        }
    }
}

3. Orphan Profiles & Sponsorships

Sponsors can only sponsor.

This feature allows orphanage managers to create and manage orphan profiles that include personal information (name, age), education status, health conditions, and profile images. Sponsors can view orphans and choose to sponsor a child using either a one-time or monthly model. Each orphan profile also displays:

Real-time updates (education, health, general).
Uploaded media via multer .
Sponsorship history.

3.1 View All Orphans

API: http://localhost:3000/api/orphans Method: GET
Response:

[
    {
        "orphan_id": 1,
        "name": "Emma Williams",
        "age": 7,
        "education": "Kindergarten",
        "health": "Good health, no issues",
        "orphanage_id": 1,
        "profile_img": "emma.jpg"
    },
    {
        "orphan_id": 2,
        "name": "Liam Johnson",
        "age": 12,
        "education": "Primary School",
        "health": "Needs medical checkup",
        "orphanage_id": 2,
        "profile_img": "liam.jpg"
    },
    {
        "orphan_id": 3,
        "name": "Sophia Brown",
        "age": 9,
        "education": "Elementary School",
        "health": "Asthma, needs care",
        "orphanage_id": 3,
        "profile_img": "sophia.jpg"
    },
    {
        "orphan_id": 4,
        "name": "mariam",
        "age": 12,
        "education": "Grad4",
        "health": "Healthy",
        "orphanage_id": 2,
        "profile_img": null
    },
    {
        "orphan_id": 5,
        "name": "noor",
        "age": 8,
        "education": "Not Studieng",
        "health": "Healthy",
        "orphanage_id": 1,
        "profile_img": null
    },
    {
        "orphan_id": 6,
        "name": "Ali",
        "age": 10,
        "education": "Grade4",
        "health": "Healthy",
        "orphanage_id": 3,
        "profile_img": null
    },
    {
        "orphan_id": 7,
        "name": "Alia",
        "age": 10,
        "education": "Grade4",
        "health": "Healthy",
        "orphanage_id": 2,
        "profile_img": "1746966496453-p6.jpg"
    },
    {
        "orphan_id": 8,
        "name": "samia",
        "age": 12,
        "education": "Grade4",
        "health": "Healthy",
        "orphanage_id": 3,
        "profile_img": "1747488744693-p5.jpg"
    }
]

3.2 View Specific Orphan By ID

API: http://localhost:3000/api/orphans/1 Method: GET

Response:

{
    "orphan": {
        "orphan_id": 1,
        "name": "Emma Williams",
        "age": 7,
        "education": "Kindergarten",
        "health": "Good health, no issues",
        "orphanage_id": 1,
        "profile_img": "http://localhost:3000/uploads/emma.jpg"
    },
    "updates": [
        {
            "update_id": 1,
            "orphan_id": 1,
            "type": "education",
            "description": "Child started school again",
            "media_url": "C:\\Users\\97059\\Desktop\\All Semesters\\2'nd semester 2024-2025\\Advanced software\\Project_hopeconnect\\uploads\\p1.jpg",
            "created_at": "2025-05-11T11:32:37.000Z"
        }
    ],
    "sponsors": [
        {
            "sponsorship_id": 1,
            "user_id": 1,
            "orphan_id": 1,
            "type": "monthly",
            "amount": "50.00",
            "start_date": "2024-12-31T22:00:00.000Z",
            "end_date": null
        },
        {
            "sponsorship_id": 8,
            "user_id": 5,
            "orphan_id": 1,
            "type": "one-time",
            "amount": "400.00",
            "start_date": "2025-05-10T21:00:00.000Z",
            "end_date": null
        }
    ]
}

3.3 Add Orphan Profile

Admin Only

API: http://localhost:3000/api/orphans Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjgsIm5hbWUiOiIgd2FsZWVkIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzQ3NjY1MjY2LCJleHAiOjE3NDc2Njg4NjZ9.Ax7T9jrPFhGYYZDhlHuMoz6Kb4pbw-ovMF9_jKQVjCE

Body:

{

    "name":"rami",
    "age":9,
    "education":"Grade3",
    "health":"Helthy",
    " orphanage_id":4,
    "profile_img":"http://localhost:3000/uploads/p1.jpg"
}

Response:

{
    "message": "Orphan created",
    "orphanId": 10
}

3.4 Add Sponsor Ship By Sponsor

SponsorsOnly

API: http://localhost:3000/api/orphans/1/sponsor Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjUsIm5hbWUiOiIgSGFsYSIsInJvbGUiOiJzcG9uc29yIiwiaWF0IjoxNzQ2OTYxMjcwLCJleHAiOjE3NDY5NjQ4NzB9.Tx5lPKIAz5WwZOazHZcWTm7wp1XkGyz0H9v7rsBdazo

Body:

{
  "type": "one-time",
  "amount": 400
}

Response:

{
    "message": "Sponsorship successful",
    "sponsorshipId": 8
}

3.5 Not Sponsor cant sponsor

API: http://localhost:3000/api/orphans/1/sponsor Method: POST

Body:

{
  "type": "one-time",
  "amount": 400
}

Response:

{
    "error": "Only sponsors can perform this action"
}

3.6 Update Orphans Profile

Admin Only

API: http://localhost:3000/api/orphans/1/updates Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjgsIm5hbWUiOiIgd2FsZWVkIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzQ2OTYyOTk0LCJleHAiOjE3NDY5NjY1OTR9.s0DmjQ3xmea-wqDPQ8_dfgHFea_0H4SIm-5mQ2caCp0

Body:

{
  "type": "education",
  "description": "Child started school again",
  "media_url": "http://localhost:3000/uploads/update1.jpg"
}

Response:

{
    "message": "Update added",
    "updateId": 1
}

4. Volunteer & Service Matching

Volunteers can register their availability and service types (teaching, medical, etc.). Orphanages submit service requests for upcoming needs. The system matches requests to appropriate volunteers based on:

Matching service_type.
Compatible availability (weekends, weekdays, flexible, etc.).
Email is sent to the orphanage manager.

4.1 Register Volunteer

API:http://localhost:3000/api/volunteers/register Method: POST

Header: Authorization : `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEzLCJuYW1lIjoibm9vciIsInJvbGUiOiJ2b2x1bnRlZXIiLCJpYXQiOjE3NDc2NjY5MTcsImV4cCI6MTc0NzY3MDUxN30.mU5GYK350SFJFRzQRCLsoQhuJCqHZ2B6vtZQMTavgfQ

Body:

{ "service_type": "medical", "availability": "flexible" }

Response:

{
    "message": "Volunteer profile created successfully"
}

4.2 Orphanage Manager Requests A service

API:http://localhost:3000/api/requests Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEwLCJuYW1lIjoiIHJlZW0iLCJyb2xlIjoib3JwaGFuYWdlTWFuYWdlciIsImlhdCI6MTc0NzY2ODUwNSwiZXhwIjoxNzQ3NjcyMTA1fQ.4Tw2qO0e0VNFxbL5O2sODn7bYtZk691KUryiXxg0Fjo

Body:

{
"orphanage_name":"Sunshine Home",
  "service_type": "medical",
  "description": "We need volunteers to help with medical day.",
  "needed_date": "2025-05-21",
  "number_of_orphanages": 12
}

Response:

{
    "message": "Request created successfully",
    "requestId": 7
}

4.3 Match Requests/Services

API:http://localhost:3000/api/match/7 Method: POST

Response:

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

Email:

New Volunteer Match Found External Inbox HopeConnect [email protected] Dear Sunshine Home,

2 volunteer(s) have been matched for your request.

Service: medical

Needed on: Wed May 21 2025 00:00:00 GMT+0300 (Eastern European Summer Time)

HopeConnect Team

4.4 Delete volunteer service

API: http://localhost:3000/api/volunteers/delete Method: DELETE

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEzLCJuYW1lIjoibm9vciIsInJvbGUiOiJ2b2x1bnRlZXIiLCJpYXQiOjE3NDc0MTUwNzQsImV4cCI6MTc0NzQxODY3NH0.i4IYEN1ZZFacIp9E61y5DNZbrAFdriZzRzTissklydM

Response:

{
    "message": "(( Volunteer profile deleted successfully ))"
}

5. Emergency Support System

Admins can launch emergency campaigns for urgent needs (e.g., food crises, medical aid). Users can view active campaigns and donate.

Location of campaign is included (with openstreetmap link).
Email notifications sent to all donors/sponsors upon creation.
Campaigns are public (no login needed to view them).
Campaigns have a status (active/inactive) and start date.

5.1 Create Emergency Campaign

API:http://localhost:3000/api/campaigns Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjgsIm5hbWUiOiIgd2FsZWVkIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzQ3MTY1NTUyLCJleHAiOjE3NDcxNjkxNTJ9.xLB5vDB1TnOOBqyga9u-iM80RVII1JGzXYqihcjGcZQ

Body:

{
  "title": "Emergency Winter Support",
  "description": "We need warm blankets and jackets in Tulkarm area.",
  "location": "Tulkarm, Palestine"
}

Response:

{
    "message": "Campaign created",
    "campaign": {
        "id": 8,
        "title": "Emergency Winter Support",
        "description": "We need warm blankets and jackets in Nablus area.",
        "location": "Palestine, Zeita - Illar, علار, منطقة أ, الضفة الغربية, 113, Palestinian Territory",
        "lat": "32.3710952",
        "lon": "35.1078677",
        "map_url": "https://www.openstreetmap.org/?mlat=32.3710952&mlon=35.1078677"
    }
}

Email: Dear Alice Smith,

We need your urgent support for: Emergency Winter Support.

We need warm blankets and jackets in Nablus area. Location: منتجع حياة نابلس, Tunis, رفيديا البلد, نابلس, منطقة أ, الضفة الغربية, +970, Palestinian Territory -HopeConnect Emergency Team

5.2 Not Admin try to Create Emergency Campaign

API:http://localhost:3000/api/campaigns Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjUsIm5hbWUiOiIgSGFsYSIsInJvbGUiOiJzcG9uc29yIiwiaWF0IjoxNzQ3MTY1OTgyLCJleHAiOjE3NDcxNjk1ODJ9.heuWzuL6QAJ_wD9HhBRttwEpNKg0wB5lC1J4cuDu1LE

Body:

{
  "title": "teaching Emergency - Gaza",
  "description": "We need immediate supplies for child care units."
}

Response:

{
    "error": "Only admins can create emergency campaigns"
}

5.3 Invalid Campaign Location

Body:

{
  "title": "Emergency Winter Support",
  "description": "We need warm blankets and jackets in palestine area.",
  "location": "nottrue"
}

Response:

{
    "error": "Invalid location. Please try another one."
}

5.4 Show Active Campaigns

API:http://localhost:3000/api/campaigns Method: GET

Response:

[
    {
        "campaign_id": 1,
        "title": "Fundraising for Education",
        "description": "Campaign to raise funds for education in orphanages",
        "start_date": "2025-05-31T21:00:00.000Z",
        "location": "Nablus, West Bank",
        "map_url": "https://www.google.com/maps/search/?api=1&query=Nablus%2C%20West%20Bank"
    },
    {
        "campaign_id": 12,
        "title": "Emergency Winter Support2",
        "description": "We need warm blankets and jackets in Nablus area.",
        "start_date": "2025-05-15T21:00:00.000Z",
        "location": "نابلس, منطقة أ, الضفة الغربية, Palestinian Territory",
        "map_url": "https://www.google.com/maps/search/?api=1&query=%D9%86%D8%A7%D8%A8%D9%84%D8%B3%2C%20%D9%85%D9%86%D8%B7%D9%82%D8%A9%20%D8%A3%2C%20%D8%A7%D9%84%D8%B6%D9%81%D8%A9%20%D8%A7%D9%84%D8%BA%D8%B1%D8%A8%D9%8A%D8%A9%2C%20Palestinian%20Territory"
    },
    {
        "campaign_id": 13,
        "title": "Emergency Winter Support2",
        "description": "We need warm blankets and jackets in jenin area.",
        "start_date": "2025-05-15T21:00:00.000Z",
        "location": "جنين, منطقة أ, الضفة الغربية, 180, Palestinian Territory",
        "map_url": "https://www.google.com/maps/search/?api=1&query=%D8%AC%D9%86%D9%8A%D9%86%2C%20%D9%85%D9%86%D8%B7%D9%82%D8%A9%20%D8%A3%2C%20%D8%A7%D9%84%D8%B6%D9%81%D8%A9%20%D8%A7%D9%84%D8%BA%D8%B1%D8%A8%D9%8A%D8%A9%2C%20180%2C%20Palestinian%20Territory"
    },
    {
        "campaign_id": 2,
        "title": "Medical Aid for Children",
        "description": "Campaign to provide medical supplies for orphanages",
        "start_date": "2025-05-14T21:00:00.000Z",
        "location": "Nablus, West Bank",
        "map_url": "https://www.google.com/maps/search/?api=1&query=Nablus%2C%20West%20Bank"
    },
    {
        "campaign_id": 5,
        "title": "teaching Emergency - Gaza",
        "description": "We need immediate supplies for child care units.",
        "start_date": "2025-05-13T21:00:00.000Z",
        "location": "Tulkarm, West Bank",
        "map_url": "https://www.google.com/maps/search/?api=1&query=Tulkarm%2C%20West%20Bank"
    },
    {
        "campaign_id": 6,
        "title": "Food Crisis in Jenin",
        "description": "We need urgent support for orphanages in Jenin.",
        "start_date": "2025-05-13T21:00:00.000Z",
        "location": "Jenin, Palestine",
        "map_url": "https://www.google.com/maps/search/?api=1&query=Jenin%2C%20Palestine"
    },
    {
        "campaign_id": 7,
        "title": "Emergency Winter Support",
        "description": "We need warm blankets and jackets in Nablus area.",
        "start_date": "2025-05-13T21:00:00.000Z",
        "location": "منتجع حياة نابلس, Tunis, رفيديا البلد, نابلس, منطقة أ, الضفة الغربية, +970, Palestinian Territory",
        "map_url": "https://www.google.com/maps/search/?api=1&query=%D9%85%D9%86%D8%AA%D8%AC%D8%B9%20%D8%AD%D9%8A%D8%A7%D8%A9%20%D9%86%D8%A7%D8%A8%D9%84%D8%B3%2C%20Tunis%2C%20%D8%B1%D9%81%D9%8A%D8%AF%D9%8A%D8%A7%20%D8%A7%D9%84%D8%A8%D9%84%D8%AF%2C%20%D9%86%D8%A7%D8%A8%D9%84%D8%B3%2C%20%D9%85%D9%86%D8%B7%D9%82%D8%A9%20%D8%A3%2C%20%D8%A7%D9%84%D8%B6%D9%81%D8%A9%20%D8%A7%D9%84%D8%BA%D8%B1%D8%A8%D9%8A%D8%A9%2C%20%2B970%2C%20Palestinian%20Territory"
    },
    {
        "campaign_id": 8,
        "title": "Emergency Winter Support",
        "description": "We need warm blankets and jackets in Nablus area.",
        "start_date": "2025-05-13T21:00:00.000Z",
        "location": "Palestine, Zeita - Illar, علار, منطقة أ, الضفة الغربية, 113, Palestinian Territory",
        "map_url": "https://www.google.com/maps/search/?api=1&query=Palestine%2C%20Zeita%20-%20Illar%2C%20%D8%B9%D9%84%D8%A7%D8%B1%2C%20%D9%85%D9%86%D8%B7%D9%82%D8%A9%20%D8%A3%2C%20%D8%A7%D9%84%D8%B6%D9%81%D8%A9%20%D8%A7%D9%84%D8%BA%D8%B1%D8%A8%D9%8A%D8%A9%2C%20113%2C%20Palestinian%20Territory"
    },
    {
        "campaign_id": 10,
        "title": "Emergency Winter Support",
        "description": "We need warm blankets and jackets in palestine area.",
        "start_date": "2025-05-13T21:00:00.000Z",
        "location": null,
        "map_url": null
    },
    {
        "campaign_id": 11,
        "title": "Emergency Winter Support",
        "description": "We need warm blankets and jackets in palestine area.",
        "start_date": "2025-05-13T21:00:00.000Z",
        "location": null,
        "map_url": null
    },
    {
        "campaign_id": 4,
        "title": "Medical Emergency - Gaza",
        "description": "We need immediate supplies for child care units.",
        "start_date": "2025-05-12T21:00:00.000Z",
        "location": "Tulkarm, West Bank",
        "map_url": "https://www.google.com/maps/search/?api=1&query=Tulkarm%2C%20West%20Bank"
    }
]

5.5 Donate to Emergency Campaign

API:http://localhost:3000/api/campaigns/4/donate Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjUsIm5hbWUiOiIgSGFsYSIsInJvbGUiOiJzcG9uc29yIiwiaWF0IjoxNzQ3MTY4NTY4LCJleHAiOjE3NDcxNzIxNjh9.tADYZgqytQkNpyLddKTE9Hk-RwGCK0uVYPmNum2bMnI

Body:

{
  "amount": 500
}

Response:

{
    "message": "Thank you for your donation!",
    "donationId": 10
}

6. Revenue Model & Sustainability

To ensure operational sustainability, a 2% fee is applied to monetary donations. This fee supports:

Server costs.
Maintenance.
NGO partnerships.
Admins can view the total revenue collected from these fees via a dedicated endpoint.

6.1 Fees On Donations

API:http://localhost:3000/api/donations Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyLCJuYW1lIjoiIHJlbWEiLCJyb2xlIjoiZG9ub3IiLCJpYXQiOjE3NDc0MDc3MTksImV4cCI6MTc0NzQxMTMxOX0.a_GsTcW8qt-JclfZ_uV0ZQxdXOGAUnYW5s8TDV-J0U4

Body:

{
  "orphanage_id": 1,
  "type": "money",
  "category": "education",
  "amount": 500,
  "details": "for School supplies and books"
}

Response:

{
    "success": true,
    "donationId": 7,
    "platform_fee": 10,
    "amount_sent_to_cause": 490,
    "message": "Donation created successfully"
}

6.2 Sponsor Donation with fees

API:http://localhost:3000/api/donations Method: POST

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjUsIm5hbWUiOiIgSGFsYSIsInJvbGUiOiJzcG9uc29yIiwiaWF0IjoxNzQ3NDA4ODY2LCJleHAiOjE3NDc0MTI0NjZ9.58nnHmQxoAGUWcu0ODiuFf76Xxi4fp8gIT-HlhW7gJo

Body:

{
  "orphanage_id": 1,
  "type": "money",
  "category": "medical",
  "amount": 1000,
  "details": "for medcine supplies "
}

Response:

{
    "success": true,
    "donationId": 9,
    "platform_fee": 20,
    "amount_sent_to_cause": 980,
    "message": "Donation created successfully"
}

6.3 Not allowed Donation

Response:

{
    "success": false,
    "error": "Only donors, sponsors, or admins can create donations"
}

6.4 Admin view the platform revenues from fees

API:http://localhost:3000/api/finance/revenue Method: GET

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjgsIm5hbWUiOiIgd2FsZWVkIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzQ3NDA5NTgwLCJleHAiOjE3NDc0MTMxODB9.pScWhdGYbw4W2JgFl1qWwnXjwun_2sTpYrg96B9Vzhc

Response:

{
    "success": true,
    "message": "Total platform revenue from donation fees",
    "revenue": 38
}

6.5 Not Admin try to view revenue

API:http://localhost:3000/api/finance/revenue Method: GET

Response:

{
    "error": "Access denied: Admins only"
}

6.6 Get revenue per specific month & year

API:http://localhost:3000/api/finance/revenue?month=5&year=2024 Method: GET

Header: Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjgsIm5hbWUiOiIgd2FsZWVkIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzQ3NDEwNDA2LCJleHAiOjE3NDc0MTQwMDZ9.fUJ3C-4Xnk7SustBVdOWn29-to5RpYd8iTQnvPyDUDY

Response:

{
    "success": true,
    "message": "Total revenue for 5/2024",
    "revenue": 8
}

6.7 Get revenue per specific month

API:http://localhost:3000/api/finance/revenue?month=5 Method: GET

Response:

{
    "success": true,
    "message": "Total revenue",
    "revenue": 38
}

6.8 Get revenue per specific YEAR

API:http://localhost:3000/api/finance/revenue?year=2025 Method: GET

Response:

{
    "success": true,
    "message": "Total revenue",
    "revenue": 30
}

6.9 View metrics about the orphanages for NGO partnerships.

API:http://localhost:3000/api/partners/metrics Method: GET

Response:

{
    "success": true,
    "data": [
        {
            "orphanage_id": 1,
            "orphanage_name": "Hope Orphanage",
            "total_orphans": 2,
            "total_donations": 4,
            "total_donated": "1962.00",
            "total_requests": 2,
            "total_matches": 2,
            "average_rating": "4.0000"
        },
        {
            "orphanage_id": 2,
            "orphanage_name": "Sunshine Home",
            "total_orphans": 3,
            "total_donations": 4,
            "total_donated": "40.00",
            "total_requests": 2,
            "total_matches": 2,
            "average_rating": "5.0000"
        },
        {
            "orphanage_id": 3,
            "orphanage_name": "Future Care Center",
            "total_orphans": 2,
            "total_donations": 1,
            "total_donated": null,
            "total_requests": 1,
            "total_matches": 1,
            "average_rating": "3.5000"
        }
    ]
}

7. Driver (driverRoutes.js)

In this project, we need to get non-financial donations from donors, then deliver them to orphanages or the desired destination. In this table, we can see only drivers added by the admin, not the registered drivers, who need to be reviewed by the admin to add them.

7.1 Get All Drivers

API: http://localhost:3000/api/drivers Method: GET

Response:

{
    "success": true,
    "drivers": [
        {
            "driver_id": 1,
            "name": "Momen",
            "phone": "121",
            "is_available": 0
        },
        {
            "driver_id": 2,
            "name": "Ali",
            "phone": "3",
            "is_available": 0
        },
        {
            "driver_id": 3,
            "name": "Ahmed Driver",
            "phone": "123456789",
            "is_available": 1
        }
    ]
}

7.2 Get Available Drivers

API: http://localhost:3000/api/drivers/available Method: GET

Response:


{
    "success": true,
    "drivers": [
        {
            "driver_id": 2,
            "name": "Ali",
            "phone": "3",
            "is_available": 1
        },
        {
            "driver_id": 3,
            "name": "Ahmed Driver",
            "phone": "123456789",
            "is_available": 1
        }
    ]
}

7.3 Get Driver By ID

API: http://localhost:3000/api/drivers/2 Method: GET

Response:

{
    "success": true,
    "message": "Driver found",
    "driver": {
        "driver_id": 2,
        "name": "Ali",
        "phone": "3",
        "is_available": 0
    }
}

7.4 Delete Driver By ID

API: http://localhost:3000/api/drivers/3 Method: DELETE

Response:


{
    "success": true,
    "message": "Driver deleted"
}

7.5 Update Driver's Availability

API: http://localhost:3000/api/drivers/2/availability Method: PUT

Request Body:


{
  "is_available": false
}

Response:

{
    "success": true,
    "message": "Driver availability updated"
}

7.6 POST Method

API: http://localhost:3000/api/drivers

Method: POST

7.6.1 Add Driver with Valid Information

API: http://localhost:3000/api/drivers Method: POST

Request Body:


{
  "name": "Ahmed Driver",
  "phone": "123456789"
}

Response:


{
    "success": true,
    "message": "Driver created",
    "driverId": 3
}

7.6.2 Add Driver with Invalid Information

API: http://localhost:3000/api/drivers Method: POST

Request Body:


{
  "name": "",
  "phone": "789"
}

Response:


{
    "errors": [
        {
            "type": "field",
            "value": "",
            "msg": "Name is required",
            "path": "name",
            "location": "body"
        },
        {
            "type": "field",
            "value": "789",
            "msg": "Phone must be valid",
            "path": "phone",
            "location": "body"
        }
    ]
}

7.6.3 Add Driver not Authorized

API: http://localhost:3000/api/drivers Method: POST

Request Body:


{
  "name": "Ahmed Driver",
  "phone": "123456789"
}

Response:


{
    "success": false,
    "error": "You are not authorized to add a driver"
}

8. Reviews And Trust

** In this route, anyone can make reviews on the orphanages except for the orphanages' Managers. Deleting a review can only be done by an admin without any conditions. An orphanage manager (user role) can only delete reviews on his/her orphanage if the review's comment contains bad words. These rules were regulated to ensure trust and transparency **

8.1 Get All Reviews

API: http://localhost:3000/api/reviews Method: GET

Response:

[
    {
        "review_id": 1,
        "user_id": 1,
        "orphanage_id": 2,
        "rating": 5,
        "comment": "This orphanage provides excellent care for the children."
    },
    {
        "review_id": 2,
        "user_id": 3,
        "orphanage_id": 1,
        "rating": 4,
        "comment": "Good facilities and caring staff, but more activities are needed."
    },
    {
        "review_id": 3,
        "user_id": 2,
        "orphanage_id": 3,
        "rating": 3,
        "comment": "The orphanage is decent, but the children need more educational support."
    }
]

8.2 Get Reviews By Orphanage's ID

API: http://localhost:3000/api/reviews/orphanage/1 Method: GET

Response:

[
    {
        "review_id": 1,
        "user_id": 5,
        "orphanage_id": 1,
        "rating": 5,
        "comment": "The orphanage is decent, but the children need more educational support."
    },
    {
        "review_id": 2,
        "user_id": 3,
        "orphanage_id": 1,
        "rating": 4,
        "comment": "Good facilities and caring staff, but more activities are needed."
    }

8.3 Get Review By ID

API: http://localhost:3000/api/reviews/1 Method: GET

Response:

{
    "review_id": 1,
    "user_id": 1,
    "orphanage_id": 2,
    "rating": 5,
    "comment": "This orphanage provides excellent care for the children."
}

8.4 POST Method

API: http://localhost:3000/api/reviews

Method: POST

8.4.1 Create Review Successfully

API: http://localhost:3000/api/reviews Method: POST

Authorized Roles: Everyone can create reviews except for the orphanage's manager

Request Body:


{
  "orphanage_id": 2,
  "rating": 5,
  "comment": "The children were happy and well taken care of."
}

Response:


{
    "id": 4,
    "data": {
        "user_id": 4,
        "orphanage_id": 2,
        "rating": 5,
        "comment": "The children were happy and well taken care of."
    },
    "message": "Review created successfully"
}

8.4.2 Create Review but no such orphanage

API: http://localhost:3000/api/reviews Method: POST

Request Body:


{
  "orphanage_id": 6,
  "rating": 5,
  "comment": "The children were happy and well taken care of."
}

Response:


{
    "error": "no such orphanage with this id"
}

8.4.3 POST Method

API: http://localhost:3000/api/reviews Method: POST

Request Body:


{
  "orphanage_id": 6,
  "rating": 5,
  "comment": "The children were happy and well taken care of."
}

Response:


{
    "success": false,
    "error": "you are an orphanage's manager you can not make reviews"
}

8.5 Delete Method

API: http://localhost:3000/api/reviews/1

Method: DELETE

8.5.1 Delete a Review successfully

API: http://localhost:3000/api/reviews/1 Method: DELETE

Note: in this example the manager tries to delete a review with inappropriate content. The same message appears when an admin tries to delete a review.

Response:

{
    "success": true,
    "message": "Review deleted successfully"
}

8.5.2 Manager Delete a Review Denied

API: http://localhost:3000/api/reviews/1 Method: DELETE

Response:

{
    "success": false,
    "error": "Cannot delete review: no inappropriate content"
}

8.5.3 Delete a Review not authorized

API: http://localhost:3000/api/reviews/1 Method: DELETE

Response:

{
    "success": false,
    "error": "You are not authorized to delete reviews"
}

8.6 PUT Method

API: http://localhost:3000/api/orphanage/id/verify Method: PUT

8.6.1 Update verify flag not by Admin

API: http://localhost:3000/api/orphanage/3/verify Method: PUT

Request Body:

{
  "verified": false
}

Response:


{
    "success": false,
    "error": "Only admins can verify orphanages"
}

8.6.2 Update verify flag by Admin

API: http://localhost:3000/api/orphanage/3/verify Method: PUT

Request Body:

{
  "verified": true
}

Response:


{
    "success": true,
    "message": "Verification status updated",
    "data": {
        "orphanageId": "2",
        "verified": true
    }
}

9. Logistics & Resource Distribution

** In this feature, we implemented a delivery and tracking system to match between donations and drivers. These routes with be called implicitly when creating a donation. (see next)**

9.1 GET Deliveries by status type

API: http://localhost:3000/api/delivery/in_transit Method: GET

Response:

{
    "success": true,
    "deliveries": [
        {
            "delivery_id": 2,
            "donation_id": 2,
            "status": "in_transit",
            "assigned_to": "driver 2",
            "location": "456 Oak St, City, Country",
            "lat": null,
            "lng": null,
            "delivery_time": null,
            "driver_id": null
        },
        {
            "delivery_id": 4,
            "donation_id": 3,
            "status": "in_transit",
            "assigned_to": "Momen",
            "location": "15 Main St, Nablus",
            "lat": null,
            "lng": null,
            "delivery_time": null,
            "driver_id": 1
        }
    ]
}

API: http://localhost:3000/api/delivery/done Method: GET

Response:


{
    "success": true,
    "deliveries": [
        {
            "delivery_id": 3,
            "donation_id": 3,
            "status": "done",
            "assigned_to": "driver 3",
            "location": "789 Pine St, City, Country",
            "lat": null,
            "lng": null,
            "delivery_time": null,
            "driver_id": null
        }
    ]
}

9.2 GET Deliveries location by ID

API: http://localhost:3000/api/delivery/5/track Method: GET

Response:


{
    "success": true,
    "location": {
        "lat": "40.73061000",
        "lng": "-73.93524200"
    }
}

9.3 Update delivery Status

API: http://localhost:3000/api/delivery/4/status Method: PUT

Request Body:

{
  "status": "in_transit"
}

Response:


{
    "success": true,
    "message": "Status updated"
}

9.4 Update delivery Location

API: http://localhost:3000/api/delivery/5/location Method: PUT

Request Body:

{
  "lat": 40.730610,
  "lng": -73.935242
}

Response:


{
    "success": true,
    "message": "Location updated"
}

9.5 POST Methos

9.5.1 add delivery and found an available driver

API:http://localhost:3000/api/delivery Method: POST

Request Body:


{
  "donation_id": 3,
  "location": "15 Main St, Nablus"
}

Response:


{
    "success": true,
    "message": "Delivery assigned to driver Ali, process will start within a week",
    "deliveryId": 9,
    "assignedDriver": "Ali"
}

9.5.2 add delivery and found an available driver

API:http://localhost:3000/api/delivery Method: POST

Request Body:


{
  "donation_id": 4,
  "location": "15 Main St, Nablus"
}

Response:


{
    "success": true,
    "message": "Delivery created but no driver was available at the moment.",
    "deliveryId": 10,
    "assignedDriver": null
}

10. Donation Management

This part shows different operations on the donations. Different APIs have different accessibility by various Roles

10.1 Get All Donations

API: http://localhost:3000/api/donations Method: GET

10.1.1 Not Admin (Not Authorized)

Response:


{
    "success": false,
    "error": "Only admins can view all donations"
}

10.1.2 Admin (Authorized)

Response:


{
    "success": true,
    "data": [
        {
            "donation_id": 1,
            "user_id": 1,
            "orphanage_id": 1,
            "type": "money",
            "category": "general",
            "amount": "100.00",
            "details": "Donation for general needs at Hope Orphanage",
            "created_at": "2025-05-09T17:54:13.000Z"
        },
        {
            "donation_id": 2,
            "user_id": 2,
            "orphanage_id": 2,
            "type": "clothes",
            "category": "clothing",
            "amount": null,
            "details": "Clothes donated for children at Sunshine Home",
            "created_at": "2025-05-09T17:54:13.000Z"
        },
        {
            "donation_id": 3,
            "user_id": 4,
            "orphanage_id": 3,
            "type": "books",
            "category": "education",
            "amount": null,
            "details": "Books donated for educational purposes at Future Care Center",
            "created_at": "2025-05-09T17:54:13.000Z"
        }
    ]
}

10.2 Get Donation By ID

API: http://localhost:3000/api/donations/id Method: GET

10.2.1 Not Authorized

API: http://localhost:3000/api/donations/5 Method: GET

Response:


{
    "success": false,
    "error": "Not authorized to view this donation"
}

10.2.2 (Authorized)

** Admin and Orphanage Managers can see any donation, and donation's owner can see their own donations **

API: http://localhost:3000/api/donations/2 Method: GET

Response:

{
    "success": true,
    "data": {
        "donation_id": 6,
        "user_id": 4,
        "orphanage_id": 1,
        "type": "money",
        "category": "education",
        "amount": "50.00",
        "details": "For school supplies",
        "created_at": "2025-05-12T14:40:37.000Z"
    }
}

10.3 Get User's Donation

API: http://localhost:3000/api/donations/user/my-donations Method: GET

Response:



{
    "success": true,
    "data": [
        {
            "donation_id": 3,
            "user_id": 4,
            "orphanage_id": 3,
            "type": "books",
            "category": "education",
            "amount": null,
            "details": "Books donated for educational purposes at Future Care Center",
            "created_at": "2025-05-09T17:54:13.000Z"
        },
        {
            "donation_id": 6,
            "user_id": 4,
            "orphanage_id": 1,
            "type": "money",
            "category": "education",
            "amount": "50.00",
            "details": "For school supplies",
            "created_at": "2025-05-12T14:40:37.000Z"
        }
    ]
}

10.4 Get Donation By orphanage ID

API: http://localhost:3000/api/donations/orphanage/1 Method: GET

Response:


{
    "success": true,
    "data": [
        {
            "donation_id": 1,
            "user_id": 1,
            "orphanage_id": 1,
            "type": "money",
            "category": "general",
            "amount": "100.00",
            "details": "Donation for general needs at Hope Orphanage",
            "created_at": "2025-05-09T17:54:13.000Z"
        },
        {
            "donation_id": 4,
            "user_id": 5,
            "orphanage_id": 1,
            "type": "clothes",
            "category": "clothing",
            "amount": null,
            "details": "Winter jackets for children",
            "created_at": "2025-05-12T14:17:43.000Z"
        },
        {
            "donation_id": 5,
            "user_id": 5,
            "orphanage_id": 1,
            "type": "clothes",
            "category": "clothing",
            "amount": null,
            "details": "Winter jackets for children",
            "created_at": "2025-05-12T14:23:51.000Z"
        },
        {
            "donation_id": 6,
            "user_id": 4,
            "orphanage_id": 1,
            "type": "money",
            "category": "education",
            "amount": "50.00",
            "details": "For school supplies",
            "created_at": "2025-05-12T14:40:37.000Z"
        }
    ]
}

10.5 Get Donation sorted by type

API: http://localhost:3000/api/donations/type_summary Method: GET

Response:


{
    "success": true,
    "data": [
        {
            "type": "money",
            "count": 4
        },
        {
            "type": "clothes",
            "count": 3
        },
        {
            "type": "books",
            "count": 1
        },
        {
            "type": "medical",
            "count": 4
        }
    ],
    "chartData": {
        "labels": [
            "money",
            "clothes",
            "books",
            "medical"
        ],
        "values": [
            4,
            3,
            1,
            4
        ]
    }
}

10.6 POST Method

Roles who registered as donor, sponsor and admin can make a donation. Here when the donation type is Money the operation taken is to add a payment transaction and get a some fee then track the transaction

API: http://localhost:3000/api/donations Method: POST

10.6.1 Donate By Money

Request Body:


{
  "orphanage_id":2 ,
  "type": "money",
  "category": "clothing",
  "amount": 10,
   "details": "Winter jackets for children",
  "location": "Hebron , Palestine"
}

Response:


{
    "success": true,
    "donationId": 13,
    "platform_fee": 0.2,
    "amount_sent_to_cause": 9.8,
    "message": "Donation created successfully"
}

new row will be added to table donation_tracking

10.6.2 Donate By non-monetary donation

notice the information of delivery: no available drivers to get the donations

Request Body:

{
  "orphanage_id":1 ,
  "type": "medical",
  "category": "healthcare",
  "amount": 10,
  "details": "For hospital supplies",
  "location": "Cairo, Egypt"
}

Response:


{
    "success": true,
    "donationId": 17,
    "message": "Donation created successfully",
    "delivery": {
        "deliveryId": 18,
        "message": "Delivery assigned to driver Ali, process will start within a week",
        "driver": "Ali",
        "mapUrl": "https://www.openstreetmap.org/?mlat=30.0443879&mlon=31.2357257#map=16/30.0443879/31.2357257"
    }
}

new row will be added to table donation_tracking

10.6.3 Donate By not authorized role

Request Body:

{
  "orphanage_id":2 ,
  "type": "clothes",
  "category": "clothing",
  "amount": 15,
   "details": "Winter jackets for children",
  "location": "Hebron , Palestine"
}

Response:

{
    "success": false,
    "error": "Only donors, sponsors, or admins can create donations"
}

10.6.4 invalid Inputs

Request Body:

{
  "orphanage_id":2 ,
  "type": "",
  "category": "",
  "amount": 10,
  "details": "",
  "location": ""
}

Response:

{
    "errors": [
        {
            "type": "field",
            "value": "",
            "msg": "Invalid donation type",
            "path": "type",
            "location": "body"
        },
        {
            "type": "field",
            "value": "",
            "msg": "Invalid donation category",
            "path": "category",
            "location": "body"
        }
    ]
}

10.7 Track Donations (Update Status for Donations)

API: http://localhost:3000/api/donations/6/status Method: PATCH

Allowed Roles: Admins and orphanages' managers.

Request Body:


{
  "status": "delivered"
}

Response: (authorized)


{
    "success": true,
    "message": "Donation status updated"
}

Response: (not authorized)


{
    "success": false,
    "error": "Only admins or orphanage managers can update donation status"
}

10.8 Delete Donations

API: http://localhost:3000/api/donations/5 Method: DELETE

Allowed Roles: Admins, orphanages managers and donation's owner.

Response: (authorized)


{
    "message": "Donation deleted successfully"
}

Response: (not authorized)


{
    "success": false,
    "error": "Not authorized to Delete this donation"
}