# bhavinkumar-vegad/playwright-email-utils architecture

> Architecture diagram of the GitHub repository bhavinkumar-vegad/playwright-email-utils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhavinkumar-vegad/playwright-email-utils
- Repository: https://github.com/bhavinkumar-vegad/playwright-email-utils

## Overview

##### Project Type and Purpose
- This is an open-source utility/library package (an SDK) designed to let Playwright tests extract and interact with emails from:
- Gmail (via Gmail API + OAuth2)
- Disposable web-based services like Yopmail (via browser automation)
- It exposes a unified API (`emailUtils`) and a CLI helper (`get-gmail-refresh-token`) for initial Gmail setup.

##### File Structure Analysis
- src/
- bin/get-gmail-refresh-token.ts → CLI entrypoint
- index.ts → main library export (`emailUtils`)
- emailUtils.ts → builds the API surface, maps providers and methods
- providers/
– gmail.ts → Gmail provider implementation
– yopmail.ts → Yopmail provider implementation
- utils/
– emailBodyParser.ts → shared parsing logic for body extraction
– gmailApi.ts → wraps actual calls to Gmail REST API
– gmailAuthUtils.ts → OAuth flow (token exchange, refresh)
- types.ts → shared TypeScript interfaces and types
- dist/ → transpiled JavaScript + type declarations for npm publish
- examples/ → sample integration tests showing usage of Gmail + Yopmail

##### Core Components
a. Client / Test Code
- The user’s Playwright test or script that calls `emailUtils.getEmail.*` or the CLI to obtain a refresh token.
b. Library API Layer (`emailUtils`)
- Unified façade exposing `.fromGmail()`, `.fromYopmail()`, and advanced extraction methods.
c. Providers
- Gmail Provider
- Yopmail Provider
d. Utility Modules
- Parser (emailBodyParser)
- Gmail REST wrapper (gmailApi)
- OAuth helper (gmailAuthUtils)
e. CLI Tool
- `get-gmail-refresh-token`: runs OAuth dance, prompts user, writes `.env` entries.
f. External Systems
- Google OAuth2 & Gmail REST API (secure HTTPS calls)
- Yopmail web UI (HTTP + browser automation via Playwright)

##### Relationships and Data Flow
1. **Setup (CLI)**
- Developer runs `npx get-gmail-token` → CLI loads `dotenv` → uses `gmailAuthUtils` → opens browser for consent → receives code → exchanges for refresh token → writes to .env.
2. **Runtime (Library)**
- Test Code → calls `emailUtils.fromGmail(config, searchOptions)`
↳ `emailUtils` delegates to Gmail Provider
↳ Gmail Provider calls `gmailAuthUtils` to ensure valid access token
↳ Gmail Provider uses `gmailApi` to query messages → returns raw email payload
↳ `emailBodyParser` applies extraction strategies (between-markers, regex, full-text) → returns structured result to test code
- Test Code → calls `emailUtils.fromYopmail(page, inbox, subject, actions)`
↳ `emailUtils` delegates to Yopmail Provider
↳ Yopmail Provider drives Playwright `page` to navigate to Yopmail URL
↳ Performs UI actions (text lookup, click, attribute extraction) → returns result to test code
- Optional: Yopmail auto-delete flag triggers extra navigation/click to clear mailbox

##### Architectural Patterns and Design Principles
- Provider Abstraction/Strategy Pattern: each email-service implements the same interface for `.getEmail` and extraction rules
- Single Responsibility: utils are factored by concern (parsing, API calls, auth)
- CLI vs Library separation: clear boundary between one-off setup tool and reusable API
- Type Safety: interfaces and types defined in `types.ts` used across modules
- Build Pipeline: TypeScript source → `tsc` → `dist/` → npm publish

##### Essential Elements to Capture
- API façade vs provider implementations
- Shared utility modules
- CLI vs library runtime
- External dependencies (Gmail API, web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    TestCode["Client/Test Code"]:::client
    subgraph "Library API Layer"
        Index["src/index.ts"]:::internal
        EmailUtils["src/emailUtils.ts"]:::internal
    end
    subgraph "Providers"
        GmailProv["Gmail Provider"]:::internal
        YopmailProv["Yopmail Provider"]:::internal
    end
    subgraph "Utils"
        Parser["emailBodyParser"]:::internal
        GmailAPI["gmailApi"]:::internal
        AuthUtil["gmailAuthUtils"]:::internal
    end
    CLI["get-gmail-refresh-token CLI"]:::internal
    Env[".env config"]:::config
    GmailExt["Google OAuth2 & Gmail REST API"]:::external
    YopmailExt["Yopmail Web UI"]:::external

    TestCode -->|"calls"| Index
    Index --> EmailUtils
    EmailUtils -->|".fromGmail()"| GmailProv
    EmailUtils -->|".fromYopmail()"| YopmailProv
    GmailProv -->|"ensure token"| AuthUtil
    AuthUtil -->|"OAuth2 flow"| GmailExt
    GmailProv -->|"calls"| GmailAPI
    GmailAPI -->|"REST API calls"| GmailExt
    GmailProv -->|"parses body"| Parser
    Parser --> EmailUtils
    YopmailProv -->|"browser automation"| YopmailExt

    CLI -->|"uses"| AuthUtil
    AuthUtil -->|"oauth2 exchange"| GmailExt
    AuthUtil -->|"writes token"| Env

    click TestCode "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/examples/gmail-parsing.spec.ts"
    click Index "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/index.ts"
    click EmailUtils "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/emailUtils.ts"
    click GmailProv "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/providers/gmail.ts"
    click YopmailProv "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/providers/yopmail.ts"
    click Parser "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/utils/emailBodyParser.ts"
    click GmailAPI "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/utils/gmailApi.ts"
    click AuthUtil "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/utils/gmailAuthUtils.ts"
    click CLI "https://github.com/bhavinkumar-vegad/playwright-email-utils/blob/main/src/bin/get-gmail-refresh-token.ts"

    classDef internal fill:#D6E8FF,stroke:#003399,color:#000;
    classDef client fill:#D6E8FF,stroke:#003399,color:#000;
    classDef external fill:#D5F5E3,stroke:#239B56,color:#000;
    classDef config fill:#FCF3CF,stroke:#B7950B,color:#000;
```
