Metadata-Version: 2.4
Name: cpmf-lo365om-corpus
Version: 0.1.1
Summary: Test corpus setup for LatchedLO365om — creates M365 fixture messages via Graph API
Project-URL: Homepage, https://github.com/rpapub/LatchedLO365om.Corpus
Project-URL: Repository, https://github.com/rpapub/LatchedLO365om.Corpus
Project-URL: Issues, https://github.com/rpapub/LatchedLO365om.Corpus/issues
Author-email: Christian Prior-Mamulyan <cprior@gmail.com>
License: # Dual License
        
        Copyright (c) 2026 Christian Prior-Mamulyan
        
        This project uses a dual-license model:
        
        ## Code — Apache License 2.0
        
        All source code files (`.py`, `.toml`, `.yaml`, `.json`, and similar) are licensed under the Apache License, Version 2.0.
        
        You may obtain a copy of the license at: <https://www.apache.org/licenses/LICENSE-2.0>
        
        ## Documentation — Creative Commons Attribution 4.0 International (CC BY 4.0)
        
        All documentation files (`.md`, `.txt`, `.html`, and similar) are licensed under CC BY 4.0.
        
        You may obtain a copy of the license at: <https://creativecommons.org/licenses/by/4.0/legalcode>
License-File: LICENSE.md
Keywords: graph-api,m365,rpa,test-corpus,uipath
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: faker
Requires-Dist: fpdf2
Requires-Dist: httpx
Requires-Dist: jsonschema
Requires-Dist: msal
Requires-Dist: msal-extensions
Requires-Dist: openpyxl
Requires-Dist: pygobject; sys_platform == 'linux'
Requires-Dist: pyyaml
Description-Content-Type: text/markdown

# cpmf-lo365om-corpus

Creates test fixture messages in a Microsoft 365 mailbox so that
[LatchedLO365om](https://github.com/rpapub/LatchedLO365om) consumers can run
[LatentLithium](https://github.com/rpapub/LatentLithium) test cases against real
Graph API data.

---

## Quick start — first run

Complete sequence from a fresh machine to a populated mailbox ready for testing.
Copy and adapt the commands; replace the values in `< >` with your own.

**Step 1 — Install uv** (skip if already installed)

```powershell
winget install astral-sh.uv
```

**Step 2 — Get the demo scenario yaml**

Download the bundled example into the folder that holds your LatentLithium test data.
Run this from your UiPath project root:

```powershell
mkdir Tests\Corpus
Invoke-WebRequest `
    -Uri "https://raw.githubusercontent.com/rpapub/LatchedLO365om.Corpus/main/scenarios/mail-demo.yaml" `
    -OutFile Tests\Corpus\mail-demo.yaml
```

Or copy the file manually from the
[scenarios/mail-demo.yaml](https://github.com/rpapub/LatchedLO365om.Corpus/blob/main/scenarios/mail-demo.yaml)
page on GitHub.

**Step 3 — Set environment variables**

```powershell
$env:CORPUS_CLIENT_ID = "<application-client-id>"   # from your Entra app registration
$env:CORPUS_TENANT_ID = "consumers"                 # use your tenant ID for work accounts
$env:CORPUS_MAILBOX   = "<you@outlook.com>"         # dedicated test mailbox
```

> First time? See [Entra ID app registration](#entra-id-app-registration-one-time) below.

**Step 4 — Authenticate** (browser opens once; token is cached)

```powershell
uvx cpmf-lo365om-corpus auth
```

**Step 5 — Create the corpus** (type your mailbox address when prompted)

```powershell
uvx cpmf-lo365om-corpus setup `
    --corpus Tests\Corpus\mail-demo.yaml `
    --output Tests\Corpus\corpus.json
```

`corpus.json` is now next to your scenario yaml. Point LatentLithium at it.

**Step 6 — Use corpus.json in your tests**

`corpus.json` contains the immutable IDs, subjects, folder paths, and expected values
for every fixture message. Pass its path to whatever test tooling or automation you are
running against the mailbox.

**Step 7 — Tear down when done** (type your mailbox address when prompted)

```powershell
uvx cpmf-lo365om-corpus teardown --manifest Tests\Corpus\corpus.json
```

Re-run from Step 5 any time you need a fresh corpus.

---

## Install uv

`uvx` is part of [uv](https://docs.astral.sh/uv/) — a fast Python package runner.
No Python installation is required separately; uv manages everything.

**Windows (recommended):**
```powershell
winget install astral-sh.uv
```

**Or via the uv installer script:**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

After installation, restart your terminal and verify:
```powershell
uvx --version
```

### Linux only — system libraries required

The token cache uses libsecret for encryption on Linux. Without a keyring daemon
(e.g. plain WSL), the token is not cached and the OAuth flow runs on every command.
See [Linux prerequisites](#linux-prerequisites) at the end of this document for the
required system packages.

> On macOS and Windows no extra system libraries are needed.

---

## Prerequisites

### Microsoft 365 account

A personal (Outlook.com / Hotmail) or work/school (Entra ID) account with
access to a mailbox you can use for testing.
Use a **dedicated test mailbox** — the `setup` command clears the target folder on every run.

### Entra ID app registration (one-time)

1. Go to [portal.azure.com](https://portal.azure.com) → **Entra ID** → **App registrations** → **New registration**
2. Name it anything (e.g. `corpus-cli`)
3. Under **Redirect URIs** → add `http://localhost` (platform: **Public client / native**)
4. Under **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated** → `Mail.Read` and `Mail.ReadWrite`
5. If your tenant requires it: **Grant admin consent**
6. Copy the **Application (client) ID** — you will need it below

For **personal Outlook.com / Hotmail accounts**, use `consumers` as the tenant ID.

---

## Environment variables

Set these in your shell before running any command, or pass them as flags.

```powershell
$env:CORPUS_CLIENT_ID = "<application-client-id>"
$env:CORPUS_TENANT_ID = "consumers"          # or your Entra tenant ID / domain
$env:CORPUS_MAILBOX   = "you@outlook.com"    # mailbox where fixtures are created
```

| Variable | Description |
|---|---|
| `CORPUS_CLIENT_ID` | App registration client ID |
| `CORPUS_TENANT_ID` | Tenant ID, domain, or `consumers` for personal accounts |
| `CORPUS_MAILBOX` | Target mailbox email address |

---

## Workflow

### 1 — Authenticate

Opens a browser window for interactive sign-in and caches the token locally.
Acquires `Mail.Read` scope — read-only, safe to run at any time.

```powershell
uvx cpmf-lo365om-corpus auth
```

### 2 — Create corpus messages

Reads a scenario yaml, creates fixture messages in the mailbox, and writes
`corpus.json` — the manifest consumed by LatentLithium test cases.

`setup` requires `Mail.ReadWrite` and will prompt you to confirm by typing
the mailbox address before proceeding:

```
This operation will modify the mailbox: you@outlook.com
Type the mailbox address to confirm: _
```

```powershell
uvx cpmf-lo365om-corpus setup `
    --corpus scenarios\mail-demo.yaml `
    --output corpus.json
```

Re-run `setup` any time you need a fresh corpus — the target folder is cleared and
re-populated on every run.

### 3 — Run tests

Open LatentLithium in UiPath Studio and point it at your `corpus.json`.

### 4 — Tear down

Deletes all messages created during `setup` using the IDs recorded in `corpus.json`.
Also requires `Mail.ReadWrite` and the same mailbox confirmation.

```powershell
uvx cpmf-lo365om-corpus teardown --manifest corpus.json
```

---

## Command reference

```
uvx cpmf-lo365om-corpus auth     [--client-id …] [--tenant-id …]
uvx cpmf-lo365om-corpus setup    [--corpus PATH] [--output PATH] [--mailbox …]
uvx cpmf-lo365om-corpus teardown [--manifest PATH]
```

All flags can be replaced by the corresponding environment variable (see table above).

---

## Scenario yaml

Corpus messages are defined in a scenario yaml file.
See [`corpus.schema.yaml`](corpus.schema.yaml) for the full schema and
[`scenarios/mail-demo.yaml`](scenarios/mail-demo.yaml) for a working example.

---

## Linux prerequisites

The token cache is encrypted using [libsecret](https://wiki.gnome.org/Projects/Libsecret)
via PyGObject. The following system libraries must be installed before running any command.

Tested on Ubuntu 24.04 (including WSL2):

```bash
sudo apt update
sudo apt install libgirepository1.0-dev gir1.2-secret-1 python3-cairo-dev
sudo apt install libcairo2-dev
sudo apt install libgirepository-2.0-dev
```

These are one-time system-level installs. After installing, `uvx` will compile and
cache PyGObject automatically on first run.
