diff --git a/docs/auth-service.md b/docs/auth-service.md index 0b56eb8..77d7d77 100644 --- a/docs/auth-service.md +++ b/docs/auth-service.md @@ -11,8 +11,9 @@ | POST | `/auth/password/reset/request` | Send password-reset email link | | POST | `/auth/password/reset/confirm` | Set new password via reset token | | POST | [`/auth/token/verify`](#4-access-token-verification-auto-login) | Verify access token and auto-login | +| POST | `/auth/token` | OAuth2 compatible token login (for Swagger UI/OpenAPI) | -*Refer to the [Micro-Level API Specification](./micro-plan.md#1-authentication-service) for more details on password reset endpoints.* +*Refer to the [Micro-Level API Specification](./micro-plan.md#1-authentication-service) for more details on password reset endpoints. Basic request/response for password reset are also summarized below.* ## 1. Email/Password Sign-Up & Sign-In @@ -186,7 +187,75 @@ This endpoint helps in providing a seamless login experience if a valid session --- -## 5. Client-Side Persistence & UX +## 5. Password Reset Endpoints + +These endpoints manage the password reset flow. + +### a. Request Password Reset + +* **Endpoint**: `POST /auth/password/reset/request` +* **Description**: Initiates the password reset process by sending a reset link/token to the user's email. +* **Request**: + ```json + { + "email": "user@example.com" + } + ``` +* **Response (Success)**: + ```json + 200 OK + { + "success": true, + "message": "If the email exists, a reset link has been sent" + } + ``` + +### b. Confirm Password Reset + +* **Endpoint**: `POST /auth/password/reset/confirm` +* **Description**: Allows a user to set a new password using a valid reset token. +* **Request**: + ```json + { + "reset_token": "valid_reset_token_string", + "new_password": "newSecurePassword123" + } + ``` +* **Response (Success)**: + ```json + 200 OK + { + "success": true, + "message": "Password has been reset successfully" + } + ``` + +--- + +## 6. OAuth2 Token Endpoint (Primarily for Swagger/OpenAPI) + +This endpoint is standard for OAuth2 password flow and primarily used by tools like Swagger UI for interactive API documentation. It allows users to authenticate within the Swagger interface to test protected endpoints. + +* **Endpoint**: `POST /auth/token` +* **Description**: OAuth2 compatible token login. Expects `username` (as email) and `password` in form-data. +* **Request (form-data)**: + ``` + username=user@example.com + password=userpassword + ``` +* **Response (Success)**: + ```json + 200 OK + { + "access_token": "...jwt...", + "token_type": "bearer" + } + ``` + *(Note: This endpoint, as implemented in `auth/routes.py` for Swagger, returns only an access_token. The main `/auth/login/email` should be used by clients for full auth token pair.)* + +--- + +## 7. Client-Side Persistence & UX * **On App Launch** diff --git a/docs/expense-service.md b/docs/expense-service.md index 12f398a..922a7fa 100644 --- a/docs/expense-service.md +++ b/docs/expense-service.md @@ -119,6 +119,19 @@ Content-Type: application/json "createdAt": "2024-01-15T18:30:00Z", "updatedAt": "2024-01-15T18:30:00Z" }, + "settlements": null, + "groupSummary": null +} +``` + +**Note:** The `settlements` and `groupSummary` fields in the response are placeholders in the current implementation and will return `null`. Populating these fields with relevant data (e.g., initial settlements generated by this expense, updated group balance summary) is a **TODO**. The example below shows the intended structure once implemented. + +```json +// Example of intended future response structure: +{ + "expense": { + // ... expense details ... + }, "settlements": [ { "_id": "65f1a2b3c4d5e6f7a8b9c0d2", @@ -131,25 +144,13 @@ Content-Type: application/json "amount": 125.00, "status": "completed", "createdAt": "2024-01-15T18:30:00Z" - }, - { - "_id": "65f1a2b3c4d5e6f7a8b9c0d3", - "expenseId": "65f1a2b3c4d5e6f7a8b9c0d1", - "groupId": "65f1a2b3c4d5e6f7a8b9c0d0", - "payerId": "user_a_id", - "payeeId": "user_b_id", - "payerName": "Alice", - "payeeName": "Bob", - "amount": 125.00, - "status": "pending", - "createdAt": "2024-01-15T18:30:00Z" } - // ... similar entries for user_c and user_d + // ... other settlements related to this expense ], "groupSummary": { - "totalExpenses": 2750.00, - "totalSettlements": 12, - "optimizedSettlements": [ + "totalExpenses": 2750.00, // Updated total expenses for the group + "totalSettlements": 12, // Updated total number of settlements in the group + "optimizedSettlements": [ // Potentially updated optimized settlements for the group { "fromUserId": "user_b_id", "toUserId": "user_a_id", @@ -157,7 +158,7 @@ Content-Type: application/json "fromUserName": "Bob", "toUserName": "Alice" } - // ... optimized settlement suggestions + // ... other optimized settlement suggestions ] } } @@ -300,6 +301,7 @@ Content-Type: multipart/form-data "url": "https://storage.example.com/attachments/unique_attachment_key_string.jpg" } ``` +**Note:** The current implementation simulates file upload and generates a key and URL. Actual persistent file storage (e.g., to a cloud bucket) is **TODO**. #### Get/Download an Attachment @@ -312,6 +314,8 @@ Authorization: Bearer Returns the file stream. +**Note:** This endpoint is **TODO** and currently returns a `501 Not Implemented` error. The functionality to retrieve the actual file stream is not yet implemented. + ### 2. Settlement Management #### Manually Record Payment diff --git a/docs/group-service.md b/docs/group-service.md index 3bd5eb1..52d91a1 100644 --- a/docs/group-service.md +++ b/docs/group-service.md @@ -174,6 +174,7 @@ App --> User: Show group details ```json { "error": "You have unsettled balances of ₹123.45" } ``` + **Note**: The check for outstanding balances before allowing a user to leave a group is a **TODO** in the current service implementation. The endpoint will currently allow leaving regardless of balance. --- @@ -194,3 +195,41 @@ App --> User: Show group details *All require `Authorization: Bearer ` (managed by [Auth Service](./auth-service.md)).* *Interactions with expenses and settlements are handled by the [Expense Service](./expense-service.md).* + +--- + +## 5. List Group Members + +Retrieves a list of all members within a specified group, including their user details. + +* **Endpoint**: `GET /groups/{group_id}/members` +* **Authorization**: `Bearer ` (User must be a member of the group) + +**Successful Response (200 OK):** +Returns a list of member objects. + +```json +[ + { + "userId": "usr_123abc", + "role": "admin", + "joinedAt": "2024-01-15T10:00:00Z", + "name": "Jane Doe", + "imageUrl": "https://example.com/profile_jane.jpg" + }, + { + "userId": "usr_456def", + "role": "member", + "joinedAt": "2024-01-16T11:30:00Z", + "name": "John Smith", + "imageUrl": "https://example.com/profile_john.jpg" + } +] +``` + +Each object in the list contains: +- `userId`: The unique identifier of the member. +- `role`: The role of the member in the group (e.g., "admin", "member"). +- `joinedAt`: The timestamp when the member joined the group. +- `name`: The name of the user (fetched from user profile). +- `imageUrl`: The profile image URL of the user (fetched from user profile). diff --git a/docs/user-service.md b/docs/user-service.md index f82b495..aebeaa8 100644 --- a/docs/user-service.md +++ b/docs/user-service.md @@ -39,7 +39,7 @@ Retrieves the profile information for the currently authenticated user. "image_url": "https://example.com/profile.jpg", "currency": "USD", "created_at": "2024-01-15T10:00:00Z", - "updatedAt": "2024-01-16T12:30:00Z" + "updated_at": "2024-01-16T12:30:00Z" } ``` @@ -89,13 +89,13 @@ Allows the currently authenticated user to update their profile information and ```json { "user": { - "_id": "507f191e810c19729de860ea", + "id": "507f191e810c19729de860ea", "name": "Johnathan Doe", "email": "john.doe@example.com", - "imageUrl": "https://example.com/profiles/johnathan_doe_new.jpg", + "image_url": "https://example.com/profiles/johnathan_doe_new.jpg", "currency": "EUR", - "createdAt": "2024-01-10T10:00:00Z", - "updatedAt": "2025-06-11T10:15:00Z" + "created_at": "2024-01-10T10:00:00Z", + "updated_at": "2025-06-11T10:15:00Z" } } ```