import logging import os import textwrap import urllib.parse from typing import Optional from uuid import UUID import requests from fastapi import Body, Depends, HTTPException, Path, Query from fastapi.background import BackgroundTasks from fastapi.responses import FileResponse from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm from google.auth.transport import requests as google_requests from google.oauth2 import id_token from pydantic import EmailStr from core.base import R2RException from core.base.api.models import ( GenericBooleanResponse, GenericMessageResponse, WrappedAPIKeyResponse, WrappedAPIKeysResponse, WrappedBooleanResponse, WrappedCollectionsResponse, WrappedGenericMessageResponse, WrappedLimitsResponse, WrappedLoginResponse, WrappedTokenResponse, WrappedUserResponse, WrappedUsersResponse, ) from ...abstractions import R2RProviders, R2RServices from ...config import R2RConfig from .base_router import BaseRouterV3 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token") class UsersRouter(BaseRouterV3): def __init__( self, providers: R2RProviders, services: R2RServices, config: R2RConfig ): logging.info("Initializing UsersRouter") super().__init__(providers, services, config) self.google_client_id = os.environ.get("GOOGLE_CLIENT_ID") self.google_client_secret = os.environ.get("GOOGLE_CLIENT_SECRET") self.google_redirect_uri = os.environ.get("GOOGLE_REDIRECT_URI") self.github_client_id = os.environ.get("GITHUB_CLIENT_ID") self.github_client_secret = os.environ.get("GITHUB_CLIENT_SECRET") self.github_redirect_uri = os.environ.get("GITHUB_REDIRECT_URI") def _setup_routes(self): @self.router.post( "/users", # dependencies=[Depends(self.rate_limit_dependency)], response_model=WrappedUserResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() new_user = client.users.create( email="jane.doe@example.com", password="secure_password123" )"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.create({ email: "jane.doe@example.com", password: "secure_password123" }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users" \\ -H "Content-Type: application/json" \\ -d '{ "email": "jane.doe@example.com", "password": "secure_password123" }'"""), }, ] }, ) @self.base_endpoint async def register( email: EmailStr = Body(..., description="User's email address"), password: str = Body(..., description="User's password"), name: str | None = Body( None, description="The name for the new user" ), bio: str | None = Body( None, description="The bio for the new user" ), profile_picture: str | None = Body( None, description="Updated user profile picture" ), is_verified: bool = Body( False, description="Whether to verify the user immediately", ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedUserResponse: """Register a new user with the given email and password.""" if is_verified and not auth_user.is_superuser: raise R2RException( "Non-superuser cannot verify users during registration.", 403, ) registration_response = await self.services.auth.register( email=email, password=password, is_verified=is_verified, name=name, bio=bio, profile_picture=profile_picture, ) return registration_response # type: ignore @self.router.post( "/users/export", summary="Export users to CSV", dependencies=[Depends(self.rate_limit_dependency)], openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient("http://localhost:7272") # when using auth, do client.login(...) response = client.users.export( output_path="export.csv", columns=["id", "name", "created_at"], include_header=True, ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient("http://localhost:7272"); function main() { await client.users.export({ outputPath: "export.csv", columns: ["id", "name", "created_at"], includeHeader: true, }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "http://127.0.0.1:7272/v3/users/export" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: text/csv" \ -d '{ "columns": ["id", "name", "created_at"], "include_header": true }' \ --output export.csv """), }, ] }, ) @self.base_endpoint async def export_users( background_tasks: BackgroundTasks, columns: Optional[list[str]] = Body( None, description="Specific columns to export" ), filters: Optional[dict] = Body( None, description="Filters to apply to the export" ), include_header: Optional[bool] = Body( True, description="Whether to include column headers" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> FileResponse: """Export users as a CSV file.""" if not auth_user.is_superuser: raise R2RException( status_code=403, message="Only a superuser can export data.", ) ( csv_file_path, temp_file, ) = await self.services.management.export_users( columns=columns, filters=filters, include_header=include_header if include_header is not None else True, ) background_tasks.add_task(temp_file.close) return FileResponse( path=csv_file_path, media_type="text/csv", filename="users_export.csv", ) @self.router.post( "/users/verify-email", # dependencies=[Depends(self.rate_limit_dependency)], response_model=WrappedGenericMessageResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() tokens = client.users.verify_email( email="jane.doe@example.com", verification_code="1lklwal!awdclm" )"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.verifyEmail({ email: jane.doe@example.com", verificationCode: "1lklwal!awdclm" }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/login" \\ -H "Content-Type: application/x-www-form-urlencoded" \\ -d "email=jane.doe@example.com&verification_code=1lklwal!awdclm" """), }, ] }, ) @self.base_endpoint async def verify_email( email: EmailStr = Body(..., description="User's email address"), verification_code: str = Body( ..., description="Email verification code" ), ) -> WrappedGenericMessageResponse: """Verify a user's email address.""" user = ( await self.providers.database.users_handler.get_user_by_email( email ) ) if user and user.is_verified: raise R2RException( status_code=400, message="This email is already verified. Please log in.", ) result = await self.services.auth.verify_email( email, verification_code ) return GenericMessageResponse(message=result["message"]) # type: ignore @self.router.post( "/users/send-verification-email", dependencies=[ Depends(self.providers.auth.auth_wrapper(public=True)) ], response_model=WrappedGenericMessageResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() tokens = client.users.send_verification_email( email="jane.doe@example.com", )"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.sendVerificationEmail({ email: jane.doe@example.com", }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/send-verification-email" \\ -H "Content-Type: application/x-www-form-urlencoded" \\ -d "email=jane.doe@example.com" """), }, ] }, ) @self.base_endpoint async def send_verification_email( email: EmailStr = Body(..., description="User's email address"), ) -> WrappedGenericMessageResponse: """Send a user's email a verification code.""" user = ( await self.providers.database.users_handler.get_user_by_email( email ) ) if user and user.is_verified: raise R2RException( status_code=400, message="This email is already verified. Please log in.", ) await self.services.auth.send_verification_email(email=email) return GenericMessageResponse( message="A verification email has been sent." ) # type: ignore @self.router.post( "/users/login", # dependencies=[Depends(self.rate_limit_dependency)], response_model=WrappedTokenResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() tokens = client.users.login( email="jane.doe@example.com", password="secure_password123" ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.login({ email: jane.doe@example.com", password: "secure_password123" }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/login" \\ -H "Content-Type: application/x-www-form-urlencoded" \\ -d "username=jane.doe@example.com&password=secure_password123" """), }, ] }, ) @self.base_endpoint async def login( form_data: OAuth2PasswordRequestForm = Depends(), ) -> WrappedLoginResponse: """Authenticate a user and provide access tokens.""" return await self.services.auth.login( # type: ignore form_data.username, form_data.password ) @self.router.post( "/users/logout", response_model=WrappedGenericMessageResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) result = client.users.logout() """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.logout(); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/logout" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def logout( token: str = Depends(oauth2_scheme), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedGenericMessageResponse: """Log out the current user.""" result = await self.services.auth.logout(token) return GenericMessageResponse(message=result["message"]) # type: ignore @self.router.post( "/users/refresh-token", # dependencies=[Depends(self.rate_limit_dependency)], openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) new_tokens = client.users.refresh_token() # New tokens are automatically stored in the client"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.refreshAccessToken(); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/refresh-token" \\ -H "Content-Type: application/json" \\ -d '{ "refresh_token": "YOUR_REFRESH_TOKEN" }'"""), }, ] }, ) @self.base_endpoint async def refresh_token( refresh_token: str = Body(..., description="Refresh token"), ) -> WrappedTokenResponse: """Refresh the access token using a refresh token.""" result = await self.services.auth.refresh_access_token( refresh_token=refresh_token ) return result # type: ignore @self.router.post( "/users/change-password", dependencies=[Depends(self.rate_limit_dependency)], response_model=WrappedGenericMessageResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) result = client.users.change_password( current_password="old_password123", new_password="new_secure_password456" )"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.changePassword({ currentPassword: "old_password123", newPassword: "new_secure_password456" }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/change-password" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "current_password": "old_password123", "new_password": "new_secure_password456" }'"""), }, ] }, ) @self.base_endpoint async def change_password( current_password: str = Body(..., description="Current password"), new_password: str = Body(..., description="New password"), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedGenericMessageResponse: """Change the authenticated user's password.""" result = await self.services.auth.change_password( auth_user, current_password, new_password ) return GenericMessageResponse(message=result["message"]) # type: ignore @self.router.post( "/users/request-password-reset", dependencies=[ Depends(self.providers.auth.auth_wrapper(public=True)) ], response_model=WrappedGenericMessageResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() result = client.users.request_password_reset( email="jane.doe@example.com" )"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.requestPasswordReset({ email: jane.doe@example.com", }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/request-password-reset" \\ -H "Content-Type: application/json" \\ -d '{ "email": "jane.doe@example.com" }'"""), }, ] }, ) @self.base_endpoint async def request_password_reset( email: EmailStr = Body(..., description="User's email address"), ) -> WrappedGenericMessageResponse: """Request a password reset for a user.""" result = await self.services.auth.request_password_reset(email) return GenericMessageResponse(message=result["message"]) # type: ignore @self.router.post( "/users/reset-password", dependencies=[ Depends(self.providers.auth.auth_wrapper(public=True)) ], response_model=WrappedGenericMessageResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() result = client.users.reset_password( reset_token="reset_token_received_via_email", new_password="new_secure_password789" )"""), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.resetPassword({ resestToken: "reset_token_received_via_email", newPassword: "new_secure_password789" }); } main(); """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/v3/users/reset-password" \\ -H "Content-Type: application/json" \\ -d '{ "reset_token": "reset_token_received_via_email", "new_password": "new_secure_password789" }'"""), }, ] }, ) @self.base_endpoint async def reset_password( reset_token: str = Body(..., description="Password reset token"), new_password: str = Body(..., description="New password"), ) -> WrappedGenericMessageResponse: """Reset a user's password using a reset token.""" result = await self.services.auth.confirm_password_reset( reset_token, new_password ) return GenericMessageResponse(message=result["message"]) # type: ignore @self.router.get( "/users", dependencies=[Depends(self.rate_limit_dependency)], summary="List Users", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # List users with filters users = client.users.list( offset=0, limit=100, ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.list(); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X GET "https://api.example.com/users?offset=0&limit=100&username=john&email=john@example.com&is_active=true&is_superuser=false" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def list_users( ids: list[str] = Query( [], description="List of user IDs to filter by" ), offset: int = Query( 0, ge=0, description="Specifies the number of objects to skip. Defaults to 0.", ), limit: int = Query( 100, ge=1, le=1000, description="Specifies a limit on the number of objects to return, ranging between 1 and 100. Defaults to 100.", ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedUsersResponse: """List all users with pagination and filtering options. Only accessible by superusers. """ if not auth_user.is_superuser: raise R2RException( status_code=403, message="Only a superuser can call the `users_overview` endpoint.", ) user_uuids = [UUID(user_id) for user_id in ids] users_overview_response = ( await self.services.management.users_overview( user_ids=user_uuids, offset=offset, limit=limit ) ) return users_overview_response["results"], { # type: ignore "total_entries": users_overview_response["total_entries"] } @self.router.get( "/users/me", dependencies=[Depends(self.rate_limit_dependency)], summary="Get the Current User", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Get user details users = client.users.me() """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.me(); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X GET "https://api.example.com/users/me" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def get_current_user( auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedUserResponse: """Get detailed information about the currently authenticated user.""" return auth_user @self.router.get( "/users/{id}", dependencies=[Depends(self.rate_limit_dependency)], summary="Get User Details", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Get user details users = client.users.retrieve( id="b4ac4dd6-5f27-596e-a55b-7cf242ca30aa" ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.retrieve({ id: "b4ac4dd6-5f27-596e-a55b-7cf242ca30aa" }); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X GET "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def get_user( id: UUID = Path( ..., example="550e8400-e29b-41d4-a716-446655440000" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedUserResponse: """Get detailed information about a specific user. Users can only access their own information unless they are superusers. """ if not auth_user.is_superuser and auth_user.id != id: raise R2RException( "Only a superuser can call the get `user` endpoint for other users.", 403, ) users_overview_response = ( await self.services.management.users_overview( offset=0, limit=1, user_ids=[id], ) ) return users_overview_response["results"][0] @self.router.delete( "/users/{id}", dependencies=[Depends(self.rate_limit_dependency)], summary="Delete User", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Delete user client.users.delete(id="550e8400-e29b-41d4-a716-446655440000", password="secure_password123") """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.delete({ id: "550e8400-e29b-41d4-a716-446655440000", password: "secure_password123" }); } main(); """), }, ] }, ) @self.base_endpoint async def delete_user( id: UUID = Path( ..., example="550e8400-e29b-41d4-a716-446655440000" ), password: Optional[str] = Body( None, description="User's current password" ), delete_vector_data: Optional[bool] = Body( False, description="Whether to delete the user's vector data", ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedBooleanResponse: """Delete a specific user. Users can only delete their own account unless they are superusers. """ if not auth_user.is_superuser and auth_user.id != id: raise R2RException( "Only a superuser can delete other users.", 403, ) await self.services.auth.delete_user( user_id=id, password=password, delete_vector_data=delete_vector_data or False, is_superuser=auth_user.is_superuser, ) return GenericBooleanResponse(success=True) # type: ignore @self.router.get( "/users/{id}/collections", dependencies=[Depends(self.rate_limit_dependency)], summary="Get User Collections", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Get user collections collections = client.user.list_collections( "550e8400-e29b-41d4-a716-446655440000", offset=0, limit=100 ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.listCollections({ id: "550e8400-e29b-41d4-a716-446655440000", offset: 0, limit: 100 }); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X GET "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000/collections?offset=0&limit=100" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def get_user_collections( id: UUID = Path( ..., example="550e8400-e29b-41d4-a716-446655440000" ), offset: int = Query( 0, ge=0, description="Specifies the number of objects to skip. Defaults to 0.", ), limit: int = Query( 100, ge=1, le=1000, description="Specifies a limit on the number of objects to return, ranging between 1 and 100. Defaults to 100.", ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedCollectionsResponse: """Get all collections associated with a specific user. Users can only access their own collections unless they are superusers. """ if auth_user.id != id and not auth_user.is_superuser: raise R2RException( "The currently authenticated user does not have access to the specified collection.", 403, ) user_collection_response = ( await self.services.management.collections_overview( offset=offset, limit=limit, user_ids=[id], ) ) return user_collection_response["results"], { # type: ignore "total_entries": user_collection_response["total_entries"] } @self.router.post( "/users/{id}/collections/{collection_id}", dependencies=[Depends(self.rate_limit_dependency)], summary="Add User to Collection", response_model=WrappedBooleanResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Add user to collection client.users.add_to_collection( id="550e8400-e29b-41d4-a716-446655440000", collection_id="750e8400-e29b-41d4-a716-446655440000" ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.addToCollection({ id: "550e8400-e29b-41d4-a716-446655440000", collectionId: "750e8400-e29b-41d4-a716-446655440000" }); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000/collections/750e8400-e29b-41d4-a716-446655440000" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def add_user_to_collection( id: UUID = Path( ..., example="550e8400-e29b-41d4-a716-446655440000" ), collection_id: UUID = Path( ..., example="750e8400-e29b-41d4-a716-446655440000" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedBooleanResponse: if auth_user.id != id and not auth_user.is_superuser: raise R2RException( "The currently authenticated user does not have access to the specified collection.", 403, ) # TODO - Do we need a check on user access to the collection? await self.services.management.add_user_to_collection( # type: ignore id, collection_id ) return GenericBooleanResponse(success=True) # type: ignore @self.router.delete( "/users/{id}/collections/{collection_id}", dependencies=[Depends(self.rate_limit_dependency)], summary="Remove User from Collection", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Remove user from collection client.users.remove_from_collection( id="550e8400-e29b-41d4-a716-446655440000", collection_id="750e8400-e29b-41d4-a716-446655440000" ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.removeFromCollection({ id: "550e8400-e29b-41d4-a716-446655440000", collectionId: "750e8400-e29b-41d4-a716-446655440000" }); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X DELETE "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000/collections/750e8400-e29b-41d4-a716-446655440000" \\ -H "Authorization: Bearer YOUR_API_KEY" """), }, ] }, ) @self.base_endpoint async def remove_user_from_collection( id: UUID = Path( ..., example="550e8400-e29b-41d4-a716-446655440000" ), collection_id: UUID = Path( ..., example="750e8400-e29b-41d4-a716-446655440000" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedBooleanResponse: """Remove a user from a collection. Requires either superuser status or access to the collection. """ if auth_user.id != id and not auth_user.is_superuser: raise R2RException( "The currently authenticated user does not have access to the specified collection.", 403, ) # TODO - Do we need a check on user access to the collection? await self.services.management.remove_user_from_collection( # type: ignore id, collection_id ) return GenericBooleanResponse(success=True) # type: ignore @self.router.post( "/users/{id}", dependencies=[Depends(self.rate_limit_dependency)], summary="Update User", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) # Update user updated_user = client.update_user( "550e8400-e29b-41d4-a716-446655440000", name="John Doe" ) """), }, { "lang": "JavaScript", "source": textwrap.dedent(""" const { r2rClient } = require("r2r-js"); const client = new r2rClient(); function main() { const response = await client.users.update({ id: "550e8400-e29b-41d4-a716-446655440000", name: "John Doe" }); } main(); """), }, { "lang": "Shell", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "John Doe", }' """), }, ] }, ) # TODO - Modify update user to have synced params with user object @self.base_endpoint async def update_user( id: UUID = Path(..., description="ID of the user to update"), email: EmailStr | None = Body( None, description="Updated email address" ), is_superuser: bool | None = Body( None, description="Updated superuser status" ), name: str | None = Body(None, description="Updated user name"), bio: str | None = Body(None, description="Updated user bio"), profile_picture: str | None = Body( None, description="Updated profile picture URL" ), limits_overrides: dict = Body( None, description="Updated limits overrides", ), metadata: dict[str, str | None] | None = None, auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedUserResponse: """Update user information. Users can only update their own information unless they are superusers. Superuser status can only be modified by existing superusers. """ if is_superuser is not None and not auth_user.is_superuser: raise R2RException( "Only superusers can update the superuser status of a user", 403, ) if not auth_user.is_superuser and auth_user.id != id: raise R2RException( "Only superusers can update other users' information", 403, ) if not auth_user.is_superuser and limits_overrides is not None: raise R2RException( "Only superusers can update other users' limits overrides", 403, ) # Pass `metadata` to our auth or management service so it can do a # partial (Stripe-like) merge of metadata. return await self.services.auth.update_user( # type: ignore user_id=id, email=email, is_superuser=is_superuser, name=name, bio=bio, profile_picture=profile_picture, limits_overrides=limits_overrides, new_metadata=metadata, ) @self.router.post( "/users/{id}/api-keys", dependencies=[Depends(self.rate_limit_dependency)], summary="Create User API Key", response_model=WrappedAPIKeyResponse, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) result = client.users.create_api_key( id="550e8400-e29b-41d4-a716-446655440000", name="My API Key", description="API key for accessing the app", ) # result["api_key"] contains the newly created API key """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X POST "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000/api-keys" \\ -H "Authorization: Bearer YOUR_API_TOKEN" \\ -d '{"name": "My API Key", "description": "API key for accessing the app"}' """), }, ] }, ) @self.base_endpoint async def create_user_api_key( id: UUID = Path( ..., description="ID of the user for whom to create an API key" ), name: Optional[str] = Body( None, description="Name of the API key" ), description: Optional[str] = Body( None, description="Description of the API key" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedAPIKeyResponse: """Create a new API key for the specified user. Only superusers or the user themselves may create an API key. """ if auth_user.id != id and not auth_user.is_superuser: raise R2RException( "Only the user themselves or a superuser can create API keys for this user.", 403, ) api_key = await self.services.auth.create_user_api_key( id, name=name, description=description ) return api_key # type: ignore @self.router.get( "/users/{id}/api-keys", dependencies=[Depends(self.rate_limit_dependency)], summary="List User API Keys", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient client = R2RClient() # client.login(...) keys = client.users.list_api_keys( id="550e8400-e29b-41d4-a716-446655440000" ) """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X GET "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000/api-keys" \\ -H "Authorization: Bearer YOUR_API_TOKEN" """), }, ] }, ) @self.base_endpoint async def list_user_api_keys( id: UUID = Path( ..., description="ID of the user whose API keys to list" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedAPIKeysResponse: """List all API keys for the specified user. Only superusers or the user themselves may list the API keys. """ if auth_user.id != id and not auth_user.is_superuser: raise R2RException( "Only the user themselves or a superuser can list API keys for this user.", 403, ) keys = ( await self.providers.database.users_handler.get_user_api_keys( id ) ) return keys, {"total_entries": len(keys)} # type: ignore @self.router.delete( "/users/{id}/api-keys/{key_id}", dependencies=[Depends(self.rate_limit_dependency)], summary="Delete User API Key", openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": textwrap.dedent(""" from r2r import R2RClient from uuid import UUID client = R2RClient() # client.login(...) response = client.users.delete_api_key( id="550e8400-e29b-41d4-a716-446655440000", key_id="d9c562d4-3aef-43e8-8f08-0cf7cd5e0a25" ) """), }, { "lang": "cURL", "source": textwrap.dedent(""" curl -X DELETE "https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000/api-keys/d9c562d4-3aef-43e8-8f08-0cf7cd5e0a25" \\ -H "Authorization: Bearer YOUR_API_TOKEN" """), }, ] }, ) @self.base_endpoint async def delete_user_api_key( id: UUID = Path(..., description="ID of the user"), key_id: UUID = Path( ..., description="ID of the API key to delete" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedBooleanResponse: """Delete a specific API key for the specified user. Only superusers or the user themselves may delete the API key. """ if auth_user.id != id and not auth_user.is_superuser: raise R2RException( "Only the user themselves or a superuser can delete this API key.", 403, ) success = ( await self.providers.database.users_handler.delete_api_key( id, key_id ) ) if not success: raise R2RException( "API key not found or could not be deleted", 400 ) return {"success": True} # type: ignore @self.router.get( "/users/{id}/limits", summary="Fetch User Limits", responses={ 200: { "description": "Returns system default limits, user overrides, and final effective settings." }, 403: { "description": "If the requesting user is neither the same user nor a superuser." }, 404: {"description": "If the user ID does not exist."}, }, openapi_extra={ "x-codeSamples": [ { "lang": "Python", "source": """ from r2r import R2RClient client = R2RClient() # client.login(...) user_limits = client.users.get_limits("550e8400-e29b-41d4-a716-446655440000") """, }, { "lang": "JavaScript", "source": """ const { r2rClient } = require("r2r-js"); const client = new r2rClient(); // await client.users.login(...) async function main() { const userLimits = await client.users.getLimits({ id: "550e8400-e29b-41d4-a716-446655440000" }); console.log(userLimits); } main(); """, }, { "lang": "cURL", "source": """ curl -X GET "https://api.example.com/v3/users/550e8400-e29b-41d4-a716-446655440000/limits" \\ -H "Authorization: Bearer YOUR_API_KEY" """, }, ] }, ) @self.base_endpoint async def get_user_limits( id: UUID = Path( ..., description="ID of the user to fetch limits for" ), auth_user=Depends(self.providers.auth.auth_wrapper()), ) -> WrappedLimitsResponse: """Return the system default limits, user-level overrides, and final "effective" limit settings for the specified user. Only superusers or the user themself may fetch these values. """ if (auth_user.id != id) and (not auth_user.is_superuser): raise R2RException( "Only the user themselves or a superuser can view these limits.", status_code=403, ) # This calls the new helper you created in ManagementService limits_info = await self.services.management.get_all_user_limits( id ) return limits_info # type: ignore @self.router.get("/users/oauth/google/authorize") @self.base_endpoint async def google_authorize() -> WrappedGenericMessageResponse: """Redirect user to Google's OAuth 2.0 consent screen.""" state = "some_random_string_or_csrf_token" # Usually you store a random state in session/Redis scope = "openid email profile" # Build the Google OAuth URL params = { "client_id": self.google_client_id, "redirect_uri": self.google_redirect_uri, "response_type": "code", "scope": scope, "state": state, "access_type": "offline", # to get refresh token if needed "prompt": "consent", # Force consent each time if you want } google_auth_url = f"https://accounts.google.com/o/oauth2/v2/auth?{urllib.parse.urlencode(params)}" return GenericMessageResponse(message=google_auth_url) # type: ignore @self.router.get("/users/oauth/google/callback") @self.base_endpoint async def google_callback( code: str = Query(...), state: str = Query(...) ) -> WrappedLoginResponse: """Google's callback that will receive the `code` and `state`. We then exchange code for tokens, verify, and log the user in. """ # 1. Exchange `code` for tokens token_data = requests.post( "https://oauth2.googleapis.com/token", data={ "code": code, "client_id": self.google_client_id, "client_secret": self.google_client_secret, "redirect_uri": self.google_redirect_uri, "grant_type": "authorization_code", }, ).json() if "error" in token_data: raise HTTPException( status_code=400, detail=f"Failed to get token: {token_data}", ) # 2. Verify the ID token id_token_str = token_data["id_token"] try: # google_auth.transport.requests.Request() is a session for verifying id_info = id_token.verify_oauth2_token( id_token_str, google_requests.Request(), self.google_client_id, ) except ValueError as e: raise HTTPException( status_code=400, detail=f"Token verification failed: {str(e)}", ) from e # id_info will contain "sub", "email", etc. google_id = id_info["sub"] email = id_info.get("email") email = email or f"{google_id}@google_oauth.fake" # 3. Now call our R2RAuthProvider method that handles "oauth-based" user creation or login return await self.providers.auth.oauth_callback_handler( # type: ignore provider="google", oauth_id=google_id, email=email, ) @self.router.get("/users/oauth/github/authorize") @self.base_endpoint async def github_authorize() -> WrappedGenericMessageResponse: """Redirect user to GitHub's OAuth consent screen.""" state = "some_random_string_or_csrf_token" scope = "read:user user:email" params = { "client_id": self.github_client_id, "redirect_uri": self.github_redirect_uri, "scope": scope, "state": state, } github_auth_url = f"https://github.com/login/oauth/authorize?{urllib.parse.urlencode(params)}" return GenericMessageResponse(message=github_auth_url) # type: ignore @self.router.get("/users/oauth/github/callback") @self.base_endpoint async def github_callback( code: str = Query(...), state: str = Query(...) ) -> WrappedLoginResponse: """GitHub callback route to exchange code for an access_token, then fetch user info from GitHub's API, then do the same 'oauth-based' login or registration.""" # 1. Exchange code for access_token token_resp = requests.post( "https://github.com/login/oauth/access_token", data={ "client_id": self.github_client_id, "client_secret": self.github_client_secret, "code": code, "redirect_uri": self.github_redirect_uri, "state": state, }, headers={"Accept": "application/json"}, ) token_data = token_resp.json() if "error" in token_data: raise HTTPException( status_code=400, detail=f"Failed to get token: {token_data}", ) access_token = token_data["access_token"] # 2. Use the access_token to fetch user info user_info_resp = requests.get( "https://api.github.com/user", headers={"Authorization": f"Bearer {access_token}"}, ).json() github_id = str( user_info_resp["id"] ) # GitHub user ID is typically an integer # fetch email (sometimes you need to call /user/emails endpoint if user sets email private) email = user_info_resp.get("email") email = email or f"{github_id}@github_oauth.fake" # 3. Pass to your auth provider return await self.providers.auth.oauth_callback_handler( # type: ignore provider="github", oauth_id=github_id, email=email, )