first

README.md

@@ -1,3 +1,66 @@
 # Microsoft 365 Service
 
-Generated by AppFactory.
+FastAPI service for server-to-server communication with Microsoft 365 through Microsoft Graph.
+
+## Configuration
+
+Create an app registration in Microsoft Entra ID, grant the required Microsoft Graph application permissions, and expose these environment variables:
+
+```env
+MS365_TENANT_ID=00000000-0000-0000-0000-000000000000
+MS365_CLIENT_ID=00000000-0000-0000-0000-000000000000
+MS365_CLIENT_SECRET=secret-value
+MS365_GRAPH_BASE_URL=https://graph.microsoft.com/v1.0
+MS365_GRAPH_SCOPE=https://graph.microsoft.com/.default
+MS365_REQUEST_TIMEOUT_SECONDS=30
+```
+
+The service uses the OAuth2 client credentials flow, so Microsoft Graph permissions must be application permissions approved by an administrator.
+
+## Implemented Services
+
+- Users: list and read users.
+- Mail: list messages and send email, including file attachments.
+- Calendar: list and create events, including Teams online meetings.
+- OneDrive: list root files and upload small files.
+- Groups and Teams: list groups and list team channels.
+
+## API
+
+```http
+GET  /health
+GET  /version
+GET  /microsoft365/status
+GET  /microsoft365/users?top=25&search=jane
+GET  /microsoft365/users/{user_id}
+GET  /microsoft365/users/{user_id}/mail/messages?folder=Inbox&top=25
+POST /microsoft365/users/{user_id}/mail/send
+GET  /microsoft365/users/{user_id}/calendar/events?top=25
+POST /microsoft365/users/{user_id}/calendar/events
+GET  /microsoft365/users/{user_id}/drive/root/children?top=25
+PUT  /microsoft365/users/{user_id}/drive/root/{path}
+GET  /microsoft365/groups?top=25
+GET  /microsoft365/teams/{team_id}/channels
+```
+
+`user_id` can be a Microsoft Graph user id or user principal name, for example `jane@example.com`.
+
+## Required Graph Permissions
+
+Grant only the permissions your deployment actually uses:
+
+- Users: `User.Read.All`
+- Mail read: `Mail.Read`
+- Mail send: `Mail.Send`
+- Calendar read/write: `Calendars.ReadWrite`
+- OneDrive read/write: `Files.ReadWrite.All`
+- Groups and Teams channel listing: `Group.Read.All`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+Open `http://localhost:8000/docs` for the generated OpenAPI UI.