mailkube 1.0.0__tar.gz

mailkube-1.0.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+max_line_length = 120
+
+[*.{yml,yaml,json,toml,md,js}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

mailkube-1.0.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Default owners for everything in this repo.
+# Update the team/handle below to your actual maintainers before publishing.
+* @mailkube/maintainers

mailkube-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: 🐞 Bug report
+description: Report something that isn't working as expected.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug! For **security vulnerabilities**, do not use
+        this form — follow our [Security Policy](https://github.com/mailkube/mailkube/security/policy).
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps (and the code you ran) to reproduce the behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Console output / logs
+      description: Paste relevant output. This is automatically formatted as code.
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: "mailkube version"
+      placeholder: "1.2.3 (or git commit)"
+    validations:
+      required: true
+  - type: input
+    id: runtime
+    attributes:
+      label: Runtime version & OS
+      placeholder: "e.g. Python 3.12 on macOS 14"
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: This is not a security vulnerability (those go through the Security Policy).
+          required: true

mailkube-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔐 Report a security vulnerability
+    url: https://github.com/mailkube/mailkube/security/advisories/new
+    about: Please report vulnerabilities privately — do not open a public issue.
+  - name: 💬 mailkube product support
+    url: https://support.mailkube.com
+    about: Questions about the mailkube product/API (not this library) belong here.

mailkube-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: 💡 Feature request
+description: Suggest an improvement or new capability.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the use case or pain point, not just the proposed solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like mailkube to do?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches or workarounds you've tried or thought about.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: This fits the scope of this library (not the mailkube product itself).
+          required: true

mailkube-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+<!--
+PR titles MUST follow Conventional Commits (e.g. `fix(client): ...`) — it is CI-enforced and
+becomes the squash-merge commit message. Only feat/fix/perf trigger a release.
+-->
+
+## What
+
+<!-- Describe the change in 1–2 sentences. -->
+
+## Why
+
+<!-- The user-visible problem this solves, or the motivation. -->
+
+## Quality checklist
+
+- [ ] `uv run ruff check .` and `uv run ruff format --check .` pass
+- [ ] `uv run mypy src` passes
+- [ ] `uv run pytest` passes (coverage ≥ 90% line + branch)
+- [ ] `npx jscpd --config .jscpd.json .` clean (no new duplication)
+- [ ] Docs updated (`README.md`) if user-visible
+
+## Engineering standards (SOLID / DRY / KISS)
+
+- [ ] Single-responsibility: new/changed units do one thing; no god-functions
+- [ ] No duplication introduced; shared logic extracted (DRY)
+- [ ] Public APIs documented (docstrings — doc-lint passes)
+- [ ] Complexity within limit (no lint-complexity waivers added)
+- [ ] Depends on abstractions/interfaces where a boundary is crossed (DIP)
+
+## Notes
+
+<!-- Optional: screenshots, follow-ups, breaking-change details. -->

mailkube-1.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    target-branch: "develop"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "develop"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"

mailkube-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # so release.yml can gate on the full CI
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy src
+
+      - name: Tests + coverage gate (pytest, 90% line+branch)
+        run: uv run pytest
+
+  dry:
+    # Language-agnostic duplication (DRY) gate — identical across every mailkube repo.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "20"
+      - name: Copy-paste detection (jscpd)
+        run: npx --yes jscpd@4 --config .jscpd.json .
+
+  docs:
+    # Governance gate: every .rules/*.md must be indexed in CLAUDE.md.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Rule-index sync check
+        run: ./scripts/check-rule-index.sh

mailkube-1.0.0/.github/workflows/pr-title.yml

@@ -0,0 +1,20 @@
+name: PR Title
+
+# Enforce Conventional Commits on the PR title, since PRs are squash-merged using it.
+# Only `feat:`, `fix:`, and `perf:` trigger a release on `main`.
+# NOTE: rendered verbatim (see `_copy_without_render` in cookiecutter.json) so GitHub Actions
+# `${{ ... }}` expressions are not mangled by Cookiecutter's Jinja pass.
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mailkube-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+# Conventional-Commits-driven release: version bump + changelog + GitHub Release + tag,
+# then publish to PyPI via OIDC Trusted Publishing (no long-lived tokens).
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  ci-gate:
+    # Release only proceeds if the full gated CI (test + dry + docs) is green.
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: ci-gate
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write # push version bump, tag, create GitHub Release
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute release (python-semantic-release)
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC for PyPI Trusted Publishing — no password/token stored
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: v${{ needs.release.outputs.version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI (OIDC Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No `password:` — relies purely on OIDC. Register the Trusted Publisher on PyPI first:
+        # org=<github-org>, repo=<repo-slug>, workflow=release.yml, environment=pypi.

mailkube-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+
+# Build artifacts
+build/
+dist/
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.jscpd/
+.coverage
+htmlcov/
+coverage.xml
+
+# Secrets / local config
+.env

mailkube-1.0.0/.jscpd.json

@@ -0,0 +1,19 @@
+{
+  "threshold": 1,
+  "minTokens": 50,
+  "reporters": ["console"],
+  "absolute": true,
+  "gitignore": true,
+  "failOnDuplication": true,
+  "ignore": [
+    "**/tests/**",
+    "**/test/**",
+    "**/examples/**",
+    "**/*.lock",
+    "**/*.lock.json",
+    "**/CHANGELOG.md",
+    "**/.github/**",
+    "**/dist/**",
+    "**/build/**"
+  ]
+}

mailkube-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+# Run `uv run pre-commit install && uv run pre-commit install --hook-type commit-msg` after cloning.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Language-agnostic DRY gate — identical config in every mailkube repo.
+  - repo: local
+    hooks:
+      - id: jscpd
+        name: jscpd (copy-paste detector)
+        entry: npx --yes jscpd@4 --config .jscpd.json .
+        language: system
+        pass_filenames: false
+
+  # Enforce Conventional Commits on the commit message (matches the org house style).
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.22.0
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies:
+          - "@commitlint/config-conventional"

mailkube-1.0.0/.rules/RELEASE.md

@@ -0,0 +1,26 @@
+# Release & Publishing
+
+Load this when touching `release.yml`, `[tool.semantic_release]`, versioning, or PyPI publishing.
+
+## The contract
+
+1. **Conventional Commits drive the version.** On push to `main`, `python-semantic-release` reads the
+   commit history since the last tag: `fix:` → patch, `feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major.
+   `perf:` also releases. Anything else (`chore`, `docs`, `ci`, `refactor`, `test`) does **not** release.
+2. **It bumps `project.version` in `pyproject.toml`**, regenerates `CHANGELOG.md`, commits, tags `vX.Y.Z`,
+   and creates a GitHub Release. `major_on_zero = false`, so `0.x` stays in `0.x` on `feat:`.
+3. **Publishing is OIDC-only.** The `publish` job builds with `uv build` and uploads via
+   `pypa/gh-action-pypi-publish` using GitHub's OIDC token — **no PyPI token is stored anywhere**.
+
+## Required GitHub / PyPI setup (one-time, per repo)
+
+- GitHub **environments** `release` and `pypi` must exist (Settings → Environments), with protection rules.
+- A **PyPI Trusted Publisher** must be registered for this project pointing at:
+  org = this GitHub org, repo = this repo, workflow = `release.yml`, environment = `pypi`.
+  For a brand-new package name, use PyPI's **pending publisher** flow (the project need not exist yet).
+
+## Do not
+
+- Do not hand-edit `project.version` or `CHANGELOG.md` — semantic-release owns them.
+- Do not add a `password:`/token to the publish step — that defeats OIDC and reintroduces a secret.
+- Do not gate `release.yml` on anything weaker than the full `ci.yml` (`test` + `dry` + `docs`).

mailkube-1.0.0/.rules/SOLID_DRY_KISS.md

@@ -0,0 +1,43 @@
+# Engineering Standards: SOLID · DRY · KISS · Coverage · Docs
+
+These are **enforced by CI** — a PR that violates them cannot merge. This file tells you the exact
+thresholds and how to satisfy each gate locally *before* pushing.
+
+## The five pillars
+
+| Pillar | Rule | Enforced by |
+|---|---|---|
+| **Coverage** | ≥ 90% **line and branch** | `pytest --cov-branch --cov-fail-under=90` (the `test` CI job) |
+| **DRY** | ≤ 1% duplicated code | `jscpd` (the `dry` CI job) |
+| **KISS** | cyclomatic complexity ≤ 10 per unit | ruff `C901` (the `test` CI job) |
+| **Documentation** | every public module/class/function has a docstring | ruff `D` / google convention |
+| **SOLID** | see below — approximated by lint + review | ruff `PL`/`SIM`/`ARG`/`B` + PR checklist |
+
+## Run the gates locally
+
+```bash
+uv run ruff check .            # lint incl. C901 (complexity), D (docstrings), PL/SIM/ARG (SOLID smells)
+uv run ruff format --check .   # formatting
+uv run mypy src                # strict types
+uv run pytest                  # tests + 90% line+branch coverage gate
+npx --yes jscpd@4 --config .jscpd.json .   # duplication (DRY) gate
+./scripts/check-rule-index.sh  # every .rules/*.md indexed in CLAUDE.md
+```
+
+`uv run pre-commit run --all-files` runs the ruff + jscpd + commitlint hooks in one shot.
+
+## SOLID, concretely (paradigm-neutral guidance)
+
+SOLID is not a single lint rule; keep these in mind and confirm them in the PR checklist:
+
+- **S**ingle responsibility — a function/class does one thing; if you need "and" to describe it, split it.
+- **O**pen/closed — extend via new functions/subclasses/strategies, not by editing stable call sites.
+- **L**iskov — subtypes honor their base's contract (types, exceptions, invariants).
+- **I**nterface segregation — small, focused protocols; unused parameters (ruff `ARG`) are a smell.
+- **D**ependency inversion — depend on an abstraction/`Protocol` at I/O and network boundaries, inject it.
+
+## Requesting a waiver
+
+If a threshold is genuinely wrong for a specific line, add a **scoped, commented** ignore
+(e.g. `# noqa: C901  # parser dispatch, intentionally flat`) and call it out in the PR. Blanket
+config relaxations (lowering `fail_under`, disabling a rule globally) require maintainer sign-off.

mailkube-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-07-14)
+
+- Initial Release

mailkube-1.0.0/CLAUDE.md

@@ -0,0 +1,30 @@
+# Project Rules
+
+`mailkube` is a public (Apache-2.0) mailkube SDK published to PyPI.
+Load the relevant rule file from `.rules/` based on the task.
+
+## Rule Index
+
+> **Index every rule (required).** Every file in `.rules/` MUST have a row in the table below. When you
+> add or rename a `.rules/` file, add or update its row in the **same change** — an unindexed rule is
+> invisible, because this index is what drives progressive disclosure. The `docs` CI job (`scripts/check-rule-index.sh`)
+> fails the build if `.rules/` and this index drift. This convention holds for every mailkube repo.
+
+| Rule File | Load When |
+|---|---|
+| `.rules/SOLID_DRY_KISS.md` | Writing or changing any code — the enforced engineering standards (SOLID, DRY, KISS, coverage, docs) and how to run each gate locally. |
+| `.rules/RELEASE.md` | Touching `release.yml`, `[tool.semantic_release]`, versioning, or the PyPI OIDC publish flow. |
+
+## Key Conventions (always apply)
+
+- **Tooling is `uv`**: `uv sync`, `uv run …`; deps in PEP 621 `[project]` + `[dependency-groups]`; `uv.lock` committed.
+- **`src/` layout** — code lives in `src/mailkube/`; tests in `tests/`.
+- **Ruff** for lint **and** format; **line length ≤ 120**; **mypy strict** on `src`.
+- **Type-annotate** every function; `from __future__ import annotations` at the top of modules.
+- **≥ 90% coverage, line + branch** — enforced by `--cov-fail-under=90`; never lower the gate to make a change pass.
+- **Max cyclomatic complexity 10** (ruff `C901`) — split, don't waive.
+- **Every public module/class/function has a docstring** (ruff `D`, google convention).
+- **No duplication** — the `jscpd` gate blocks at > 1% duplicated code; extract shared logic.
+- **Conventional Commits** for PR titles (squash-merged); only `feat:`/`fix:`/`perf:` cut a release.
+- **No secrets in the repo** — local config lives in a git-ignored `.env`, excluded from the built package.
+- **Keep `README` / `CHANGELOG` current** with user-visible changes (the changelog is generated on release).

mailkube-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**conduct@opensource.mailkube.com**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations