[N3] firebase auth and update apis

[1jeanpaul1]

Description

• Changes Authorization from cognito to firebase
• Adds missing APIs
• Adds API Docs

API Docs: https://fridgefinder.github.io/CFM_Notification/

API

Base URLs:

• Dev: https://notifications-api-dev.communityfridgefinder.com
• Staging: https://notifications-api-staging.communityfridgefinder.com
• Prod: https://notifications-api-prod.communityfridgefinder.com

Authentication: All endpoints (except health check) require Firebase JWT token in Authorization: Bearer <token> header.

---

Endpoints

Get Notification for Specific Fridge

GET /v1/users/{user_id}/fridge-notifications/{fridge_id}

Retrieve notification preferences for a specific fridge.

Path Parameters:

• user_id (string, required) - Firebase User ID (must match authenticated user)
• fridge_id (string, required) - Unique fridge identifier

Success Response (200):

{
  "userId": "abc123xyz456def789",
  "fridgeId": "fridge_123abc",
  "contactTypePreferences": {
    "email": {
      "good": true,
      ...
    }
  },
  "createdAt": "2025-12-13T10:30:45.123Z",
  "updatedAt": "2025-12-13T15:20:30.456Z"
}

---

Create Notification Preferences

POST /v1/users/{user_id}/fridge-notifications/{fridge_id}

Create new notification preferences for a fridge.

Path Parameters:

• user_id (string, required) - Firebase User ID (must match authenticated user)
• fridge_id (string, required) - Unique fridge identifier

Request Body:

{
  "contactTypePreferences": {
    "email": {
      "good": true,
      ...
    },
    "device": {
      "good": false,
      ...
    }
  }
}

Success Response (201):

{
  "userId": "abc123xyz456def789",
  "fridgeId": "fridge_123abc",
  "contactTypePreferences": {
    "email": {
      "good": true,
      ...
    },
    "device": {
      "good": false,
      ...
    }
  },
  "createdAt": "2025-12-13T10:30:45.123Z",
  "updatedAt": "2025-12-13T10:30:45.123Z"
}

---

Update Notification Preferences

PATCH /v1/users/{user_id}/fridge-notifications/{fridge_id}

Update existing notification preferences for a fridge.

Path Parameters:

• user_id (string, required) - Firebase User ID (must match authenticated user)
• fridge_id (string, required) - Unique fridge identifier

Request Body:

{
  "contactTypePreferences": {
    "email": {
      "good": false,
      ...
    },
    "device": {
      "good": true,
      ...
    }
  }
}

Success Response (200):

{
  "userId": "abc123xyz456def789",
  "fridgeId": "fridge_123abc",
  "contactTypePreferences": {
    "email": {
      "good": false,
      ...
    },
    "device": {
      "good": true,
      ...
    }
  },
  "createdAt": "2025-12-13T10:30:45.123Z",
  "updatedAt": "2025-12-13T16:45:22.789Z"
}

---

Get All User Notifications

GET /v1/users/{user_id}/fridge-notifications

Retrieve all notification preferences for a user.

Path Parameters:

• user_id (string, required) - Firebase User ID (must match authenticated user)

Success Response (200):

{
  "data": [
    {
      "userId": "abc123xyz456def789",
      "fridgeId": "fridge_123abc",
      "contactTypePreferences": {
        "email": {
          "good": true,
          "dirty": true,
          "outOfOrder": true,
          "notAtLocation": false,
          "ghost": false,
          "foodLevel0": true,
          "foodLevel1": false,
          "foodLevel2": false,
          "foodLevel3": false
        },
        "device": {
          "good": false,
          ...
        }
      },
      "createdAt": "2025-12-13T10:30:45.123Z",
      "updatedAt": "2025-12-13T15:20:30.456Z"
    }
  ],
  "count": 1
}

---

Delete Notification Preferences

DELETE /v1/users/{user_id}/fridge-notifications/{fridge_id}

Remove notification preferences for a specific fridge.

Path Parameters:

• user_id (string, required) - Firebase User ID (must match authenticated user)
• fridge_id (string, required) - Unique fridge identifier

Success Response (204):

No content (empty response body)

---

Error Responses

All errors follow a standardized format with an error object containing a code and message.

Error Response Structure

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Error Examples

400 Bad Request - Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Notification preference not found"
  }
}

409 Conflict

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "Notification preference already exists for this user and fridge"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred"
  }
}

401 Unauthorized

{
  "message": "Unauthorized"
}

401 errors are returned from API Gateway if JWT token is not valid

[1jeanpaul1]

I think these fields should map 1to1 with Fridge Status Update Fields

Client can improve the language, for example: "runningLow" in frontend can be mapped to foodLevel1 or "updatedWithFood" can be mapped to foodLevel: 2-4

just a thought, but might be error prone

[1jeanpaul1]

I think notifications could be laid out something like this in the future on web and mobile

on web:
if user clicks on phone -> redirects them to download mobile app
if user clicks on email -> updates user preference

note: The only notification that I can think of that would be email specific: Weekly/Monthly Digest which emails the user monthly stats about the fridge (not included yet)

[1jeanpaul1]

can ignore - was testing to see how streams worked

[1jeanpaul1]

firebase auth

[1jeanpaul1]

Hash/PrimaryKey: userId
Range: fridgeId