msgraphkit 0.1.0__py3-none-any.whl

graphkit/__init__.py

@@ -0,0 +1,17 @@
+"""
+graphkit -- a small, dependency-light toolkit for authenticating to the
+Microsoft Graph API (app-only / client credentials flow) and making
+simple REST calls against it.
+
+    from graphkit import get_token, GraphClient
+
+    token = get_token()
+    graph = GraphClient(token)
+    me = graph.get("/users/someone@example.com")
+"""
+
+from .auth import get_token, GraphAuthError
+from .client import GraphClient
+
+__all__ = ["get_token", "GraphAuthError", "GraphClient"]
+__version__ = "0.1.0"

graphkit/auth.py

@@ -0,0 +1,89 @@
+"""
+graphkit.auth
+=============
+Authenticates to the Microsoft Graph API using the OAuth2 "client
+credentials" flow -- also called app-only auth. This is the flow you
+want when a script needs to act on a mailbox, Planner plan, SharePoint
+site, etc. *without* a human signing in interactively (e.g. a scheduled
+job, a background automation, a shared-mailbox integration).
+
+No secrets live in this file or anywhere else in this package. All
+three required values are read from environment variables at runtime:
+
+    GRAPH_TENANT_ID
+    GRAPH_CLIENT_ID
+    GRAPH_CLIENT_SECRET
+
+See the README for how to create these by registering an app in
+Azure AD (Entra ID), and .env.example for a template you can copy to
+a real .env file (which you should never commit to version control).
+
+Usage
+-----
+    from graphkit import get_token
+
+    token = get_token()
+"""
+
+import os
+from typing import Optional
+
+import msal
+
+GRAPH_SCOPE = ["https://graph.microsoft.com/.default"]
+
+
+class GraphAuthError(RuntimeError):
+    """Raised when a Graph API access token could not be acquired."""
+
+
+def _require_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise GraphAuthError(
+            f"Missing required environment variable: {name}\n"
+            "Set it in your shell, or add it to a .env file in your "
+            "project folder (see .env.example) and load it with "
+            "python-dotenv before calling get_token()."
+        )
+    return value
+
+
+def get_token(
+    tenant_id: Optional[str] = None,
+    client_id: Optional[str] = None,
+    client_secret: Optional[str] = None,
+) -> str:
+    """
+    Acquire an app-only Microsoft Graph access token.
+
+    If tenant_id / client_id / client_secret are not passed in
+    directly, they are read from the GRAPH_TENANT_ID, GRAPH_CLIENT_ID,
+    and GRAPH_CLIENT_SECRET environment variables.
+
+    MSAL keeps its own in-memory token cache for the lifetime of the
+    process and will reuse a still-valid token instead of calling
+    Azure again, so it's fine to call this once per script, or before
+    every API call, without worrying about hammering the token
+    endpoint.
+
+    Raises GraphAuthError if credentials are missing or invalid.
+    """
+    tenant_id = tenant_id or _require_env("GRAPH_TENANT_ID")
+    client_id = client_id or _require_env("GRAPH_CLIENT_ID")
+    client_secret = client_secret or _require_env("GRAPH_CLIENT_SECRET")
+
+    app = msal.ConfidentialClientApplication(
+        client_id,
+        authority=f"https://login.microsoftonline.com/{tenant_id}",
+        client_credential=client_secret,
+    )
+
+    result = app.acquire_token_for_client(scopes=GRAPH_SCOPE)
+
+    if "access_token" not in result:
+        raise GraphAuthError(
+            result.get("error_description", str(result))
+        )
+
+    return result["access_token"]

graphkit/client.py

@@ -0,0 +1,88 @@
+"""
+graphkit.client
+================
+A deliberately thin wrapper around the Microsoft Graph REST API
+(v1.0). It knows nothing about Outlook, Planner, SharePoint, or any
+other specific Graph resource -- it just handles the repetitive parts
+(base URL, auth header, JSON) so you can call any Graph endpoint with
+one line and build your own helper functions on top.
+
+Usage
+-----
+    from graphkit import get_token, GraphClient
+
+    token = get_token()
+    graph = GraphClient(token)
+
+    me = graph.get("/users/someone@example.com")
+
+    graph.post("/users/someone@example.com/messages", {
+        "subject": "Hello",
+        "body": {"contentType": "Text", "content": "Hi there"},
+        "toRecipients": [{"emailAddress": {"address": "other@example.com"}}],
+    })
+"""
+
+from typing import Optional
+
+import requests
+
+GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0"
+
+
+class GraphClient:
+    """
+    Thin HTTP client for the Microsoft Graph API.
+
+    Pass in a bearer token from graphkit.auth.get_token(). One
+    GraphClient per token -- if a token expires mid-run, create a new
+    client with a freshly acquired token.
+    """
+
+    def __init__(self, token: str, base_url: str = GRAPH_BASE_URL):
+        self.token = token
+        self.base_url = base_url
+
+    def _headers(self, extra: Optional[dict] = None) -> dict:
+        headers = {"Authorization": f"Bearer {self.token}"}
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def get(self, path: str) -> dict:
+        """GET a Graph path (e.g. '/me' or '/users/x@y.com/messages') and
+        return the parsed JSON body. Raises on non-2xx responses."""
+        r = requests.get(f"{self.base_url}{path}", headers=self._headers())
+        r.raise_for_status()
+        return r.json()
+
+    def post(self, path: str, body: dict) -> requests.Response:
+        """POST a JSON body to a Graph path. Returns the raw response --
+        check response.status_code (Graph typically returns 201 for a
+        successful create) rather than assuming success."""
+        return requests.post(
+            f"{self.base_url}{path}",
+            headers=self._headers({"Content-Type": "application/json"}),
+            json=body,
+        )
+
+    def patch(self, path: str, body: dict) -> requests.Response:
+        """PATCH (partial update) a JSON body to a Graph path."""
+        return requests.patch(
+            f"{self.base_url}{path}",
+            headers=self._headers({"Content-Type": "application/json"}),
+            json=body,
+        )
+
+    def delete(self, path: str) -> requests.Response:
+        """DELETE a Graph resource."""
+        return requests.delete(f"{self.base_url}{path}", headers=self._headers())
+
+    @staticmethod
+    def error_message(response: requests.Response) -> str:
+        """Best-effort extraction of a human-readable error message from
+        a failed Graph response, for logging/printing."""
+        try:
+            return response.json().get("error", {}).get("message", response.text[:300])
+        except ValueError:
+            return response.text[:300]

msgraphkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: msgraphkit
+Version: 0.1.0
+Summary: A small, dependency-light toolkit for authenticating to the Microsoft Graph API (app-only / client credentials flow) and making simple REST calls against it.
+Author: Duckboard
+License: MIT
+Project-URL: Homepage, https://github.com/Duckboard/graphkit
+Project-URL: Buy me a coffee, https://ko-fi.com/duckboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msal>=1.24
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# graphkit
+
+A small, dependency-light Python toolkit for authenticating to the
+Microsoft Graph API using the **client credentials flow** (app-only
+auth -- no user sign-in required), plus a thin HTTP client for making
+calls against it.
+
+This is useful for background scripts, scheduled jobs, or shared-mailbox
+automations that need to act on Outlook mail, Planner tasks, SharePoint,
+or any other Graph resource without a human logging in each time.
+
+If this saves you time, consider [buying me a coffee](https://ko-fi.com/duckboard).
+
+## Features
+
+- OAuth2 client credentials flow via [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-python)
+- No secrets in code -- credentials are read from environment variables
+- A minimal `GraphClient` for GET/POST/PATCH/DELETE against any Graph endpoint
+- Two worked examples: drafting an email, creating a Planner task
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+or, to install as an editable package:
+
+```bash
+pip install -e .
+```
+
+## Azure app registration
+
+You need an Azure AD (Entra ID) app registration before this will work.
+If you don't already have one:
+
+1. Go to [portal.azure.com](https://portal.azure.com) -> **Azure Active
+   Directory** (or **Entra ID**) -> **App registrations** -> **New
+   registration**.
+2. Give it a name, leave the default options, and click **Register**.
+3. Note down the **Application (client) ID** and **Directory (tenant)
+   ID** from the app's Overview page.
+4. Go to **Certificates & secrets** -> **New client secret**. Copy the
+   secret **value** immediately -- it's only shown once.
+5. Go to **API permissions** -> **Add a permission** -> **Microsoft
+   Graph** -> **Application permissions**, and add whichever
+   permissions your use case needs, for example:
+   - `Mail.ReadWrite` (draft/read/send mail as any mailbox)
+   - `Tasks.ReadWrite` (Planner tasks)
+   - `Group.Read.All` (look up Microsoft 365 Groups by name)
+   - `User.Read.All` (look up users by name/UPN)
+6. Click **Grant admin consent** for your organisation (this step
+   requires a Global Administrator or Application Administrator role).
+
+Application permissions act on the whole tenant, scoped only by
+whichever specific mailbox/site/group you address in your API calls --
+there's no per-user consent screen for this flow. Only grant the
+permissions you actually need.
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+```
+GRAPH_TENANT_ID=your-tenant-id
+GRAPH_CLIENT_ID=your-client-id
+GRAPH_CLIENT_SECRET=your-client-secret
+```
+
+`.env` is already in `.gitignore` -- never commit real credentials.
+
+To load `.env` automatically in your own scripts, install
+`python-dotenv` and add this before importing graphkit:
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+Alternatively, just set the three variables directly in your shell or
+process environment -- graphkit doesn't require python-dotenv, it only
+reads `os.environ`.
+
+## Usage
+
+```python
+from graphkit import get_token, GraphClient
+
+token = get_token()          # reads GRAPH_TENANT_ID / GRAPH_CLIENT_ID / GRAPH_CLIENT_SECRET
+graph = GraphClient(token)
+
+me = graph.get("/users/someone@yourdomain.com")
+print(me["displayName"])
+```
+
+`GraphClient` is intentionally minimal -- `.get()`, `.post()`,
+`.patch()`, `.delete()` -- so it works with any Graph endpoint, not
+just the ones this package happens to have examples for.
+
+### Examples
+
+- `examples/send_email_draft.py` -- create a draft email in a mailbox's
+  Drafts folder
+- `examples/create_planner_task.py` -- look up a Microsoft 365 Group,
+  Planner plan, and bucket by name, then create a task in it
+
+Run either directly once you've set up your `.env`:
+
+```bash
+python examples/send_email_draft.py
+python examples/create_planner_task.py
+```
+
+## Testing
+
+```bash
+pip install pytest
+pytest
+```
+
+Tests mock MSAL, so they run offline without real Azure credentials.
+
+## Why client credentials and not device code / interactive login?
+
+Client credentials (app-only) auth is the right choice when a script
+runs unattended -- no browser, no one available to click "allow" on a
+sign-in prompt. If you need a script to act *as a specific signed-in
+user* instead of a shared app identity, you'd want MSAL's device code
+or interactive flows instead, which this package doesn't cover.
+
+## License
+
+MIT -- see [LICENSE](LICENSE). Do whatever you like with this; a
+credit or a [Ko-fi tip](https://ko-fi.com/duckboard) is
+appreciated but never required.

msgraphkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+graphkit/__init__.py,sha256=tQs-JF0ey5Hm5umro1EoDRLEE8xupr8l85xDK1zD-wE,489
+graphkit/auth.py,sha256=SFEBs0mLMwLHvslzbREywntRWDMs-i0fGDdwAsyYcAU,2827
+graphkit/client.py,sha256=B5Q7tcUlUxdROb96nGZk721LN2iDUut-3AY5kKaeVMg,3068
+msgraphkit-0.1.0.dist-info/licenses/LICENSE,sha256=ChymOtwCDSjsL0VwJuqUn7dw8gqHr0Rt4jHcFsJa8Ec,1066
+msgraphkit-0.1.0.dist-info/METADATA,sha256=OGDxzIqD_PSNxr_3vMi4m21Iqx99gUPgUow3ji2Ek_w,5475
+msgraphkit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+msgraphkit-0.1.0.dist-info/top_level.txt,sha256=xSiy0YBLQPHfTXAI0ihN8QO69oBv2zR-zqkQf9z2kvY,9
+msgraphkit-0.1.0.dist-info/RECORD,,

msgraphkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

msgraphkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duckboard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

msgraphkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graphkit