[emmy-devop]

Requested by @drafty

🔴 Review tier: HIGH — human review required

• Contract: adds typed sync/async publisher-distribution helpers and response models to the public SDK.
• Release: merging publishes a new release to PyPI through the existing release automation.

What / why

Add get_domain_hit_share() and get_top_n_articles_for_domains() to DistributionAPI and AsyncDistributionAPI, replacing the need for raw requests to these existing endpoints:

• GET /v1/distribution/stats/hit_share → HitShareResponse
• GET /v1/distribution/articles/top_n_for_domains → TopNArticlesForDomainResponse

Models live in asknews_sdk.dto.distribution; optional article IDs and pagination fields preserve the schema defaults. Query defaults, repeated domain parameters, all three ranking metrics, date filters and custom headers follow existing client conventions. Numeric limits remain server-validated, as in neighboring helpers.

Contract checked on 2026-10-26 against production OpenAPI 0.32.7 and the committed asknews-sdk/openapi.json (API info version 0.32.3). The two endpoints' parameters and all four relevant response schemas are identical. The dev gateway also reports 0.32.7 with identical targeted contracts: compared to the committed spec, 0 operations added/removed and 0 schemas added/removed. No spec files, versions, changelogs or workflows changed.

How I tested

• Frozen dependency installation from uv.lock, Python 3.11.
• Taskfile-equivalent commands (task is not installed): ruff check asknews_sdk; coverage run -m pytest --junitxml=report.xml; coverage report; coverage xml; coverage html -d coverage-report — 169 tests passed.
• 19 new transport/model cases cover sync/async, defaults/overrides, Boolean false, metric choices, repeated domains, headers, nested models, empty results, nullable/omitted fields and required counts.
• ruff format --check asknews_sdk/api/distribution.py asknews_sdk/dto/distribution.py and git diff --check passed.
• mypy --follow-imports=silent asknews_sdk/api/distribution.py asknews_sdk/dto/distribution.py passed.
• Full mypy asknews_sdk reports 3 existing errors in unchanged dto/chat.py and api/wiki.py; no distribution errors. The repository CI uses lint/tests, not mypy.

Risk / rollback

Additive methods only; existing methods and client serialization are unchanged. No live authenticated calls or production actions. Merging publishes a new release to PyPI. Revert via a follow-up reviewed release if needed. Keep the fix: PR/squash title so release automation selects the change; repository squash-title settings preserve the commit or PR title. No merge, tag, publish or release performed by this change author.