ya-dialogs-api 1.0.0__tar.gz

ya_dialogs_api-1.0.0/.gitignore

@@ -0,0 +1,55 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+share/python-wheels/
+.eggs/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.nox/
+.cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+
+# Secrets scan
+.secrets.baseline
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Generated
+_version.py
+sbom.json
+*.sigstore
+*.intoto.jsonl
+
+# Local test artifacts
+manual_qr_output.txt

ya_dialogs_api-1.0.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] — 2026-05-06
+
+### Added
+
+Initial public release. Async Yandex Dialogs Developer API client extracted
+from `ma-provider-yandex-smarthome/provider/auto_skill.py` and made
+framework-agnostic.
+
+**Public API:**
+
+- `auto_create_skill(...)` — full skill-creation pipeline (CSRF/cookie session
+  → POST `/apps` → upload logo → PATCH draft → POST OAuth app → attach OAuth
+  → request deploy). Handles both `skill_type="smart_home"` and
+  `skill_type="dialog"` channels. Resumable via `SkillCreationArtifacts`.
+- `auto_rename_dialog_skill(...)` — patches a dialog skill draft name and
+  re-deploys.
+- `DialogsSkillCreator` — low-level dev-console client (one method per
+  pipeline step).
+- `SkillCreationArtifacts` / `SkillCreationState` — incremental state
+  machine; callers persist between calls so transient failures resume from
+  the last completed step.
+- Payload builders: `build_smart_home_draft_payload`,
+  `build_dialog_draft_payload`, `build_oauth_app_payload`.
+- `load_default_logo_bytes()` — bundled fallback skill logo.
+- `SecretStr` re-exported from `ya-passport-auth` for token redaction.
+- Typed errors: `DialogsApiError`, `DialogsCsrfError`,
+  `DialogsDuplicateSkillError`.
+
+**Architecture:**
+
+The library is **framework-agnostic**. Authentication is the caller's
+responsibility — pass a no-arg async-context-manager factory (`AuthenticatorCM`)
+that yields an authenticated `aiohttp.ClientSession`. Typically the caller
+wraps `ya_passport_auth.PassportClient.login_device_code` and any UX surface
+they want around the Device Flow user-code prompt (CLI, web page, Telegram,
+Music Assistant config-flow, etc.).
+
+All URLs are pre-computed by the caller (`backend_uri`, `oauth_authorize_url`,
+`oauth_token_url`, `oauth_client_id`, `oauth_client_secret`) — the lib has
+no opinion on connection-type or hosting.
+
+Failures are values, not exceptions: pipeline errors land as
+`artifacts.state=FAILED` with `last_error` set. Truly unexpected exceptions
+still propagate.
+
+**Testing:**
+
+- 47 tests across `DialogsSkillCreator` methods, payload builders,
+  state-machine serialisation, orchestrator happy paths, resume from each
+  state, and failure recovery.
+- `mypy --strict` clean.
+- 86% coverage (state.py 100%, api_client.py 83%).
+
+**Runtime dependencies:**
+
+- `aiohttp >= 3.10, < 4`
+- `ya-passport-auth >= 1.3.0`

ya_dialogs_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Nevskiy
+
+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.

ya_dialogs_api-1.0.0/NOTICE

@@ -0,0 +1,29 @@
+ya-dialogs-api
+Copyright (c) 2026 Mikhail Nevskiy
+
+This library implements a client for the Yandex Dialogs Developer API
+(`dialogs.yandex.ru/developer-api/v2/`). The API is undocumented and
+private — the request shapes, endpoint paths, CSRF extraction pattern,
+and pipeline ordering were captured from Chrome DevTools HAR files
+during interactive sessions with the Yandex developer console.
+
+This product includes software originally developed as part of the
+ma-provider-yandex-smarthome Music Assistant plugin:
+
+    ma-provider-yandex-smarthome
+    Copyright (c) 2025-2026 Mikhail Nevskiy
+    https://github.com/trudenboy/ma-provider-yandex-smarthome
+    Licensed under the MIT License
+
+The skill auto-creation pipeline (Device Flow OAuth → CSRF/cookie session
+→ POST /apps → POST /skills/{id}/draft → publication polling) was
+extracted from `provider/auto_skill.py` of that project and made
+framework-agnostic for general use.
+
+The default skill logo asset (`src/ya_dialogs_api/assets/default_logo.png`)
+is also drawn from that upstream project.
+
+This library uses ya-passport-auth (https://github.com/trudenboy/ya-passport-auth)
+for the Yandex Passport authentication side of the flow. ya-passport-auth
+in turn re-implements work originally derived from AlexxIT/YandexStation;
+see ya-passport-auth's NOTICE for that upstream attribution.

ya_dialogs_api-1.0.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: ya-dialogs-api
+Version: 1.0.0
+Summary: Yandex Dialogs Developer API client — programmatic skill creation, draft management, OAuth Device Flow
+Project-URL: Homepage, https://github.com/trudenboy/ya-dialogs-api
+Project-URL: Repository, https://github.com/trudenboy/ya-dialogs-api
+Project-URL: Issues, https://github.com/trudenboy/ya-dialogs-api/issues
+Project-URL: Changelog, https://github.com/trudenboy/ya-dialogs-api/blob/main/CHANGELOG.md
+Author: Mikhail Nevskiy
+License: MIT License
+        
+        Copyright (c) 2026 Mikhail Nevskiy
+        
+        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.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: aiohttp,alice,api-client,async,dialogs,oauth,skill,yandex
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp<4,>=3.10
+Requires-Dist: ya-passport-auth>=1.3.0
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7.6; extra == 'dev'
+Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
+Requires-Dist: cyclonedx-bom>=4; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: liccheck>=0.9; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ya-dialogs-api
+
+> Async Yandex Dialogs Developer API client — programmatic skill creation, draft management, OAuth Device Flow.
+
+[![CI](https://github.com/trudenboy/ya-dialogs-api/actions/workflows/ci.yml/badge.svg)](https://github.com/trudenboy/ya-dialogs-api/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ya-dialogs-api)](https://pypi.org/project/ya-dialogs-api/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## What this is
+
+A framework-agnostic Python library that drives the **Yandex Dialogs Developer
+API** — the meta-API at `dialogs.yandex.ru/developer-api/v2/` used to
+programmatically create and manage Alice skills (Smart Home and custom dialog
+skills). Where every other Yandex Alice library on PyPI handles the *runtime*
+side (incoming webhook requests from end users), this one handles the
+*provisioning* side: sign in via Yandex Passport Device Flow, create a skill,
+upload a logo, set the webhook backend URL, publish a draft, poll for
+publication state.
+
+It exists because Yandex doesn't publish a developer-API SDK and the only
+known Python implementation lived inside the Music Assistant
+`ma-provider-yandex-smarthome` plugin. This library is that code, extracted
+and made generic.
+
+## Features
+
+- **Full skill auto-creation pipeline** — Device Flow OAuth → CSRF/cookie
+  session → POST `/apps` → POST `/skills/{id}/draft` → publication polling →
+  callback URL extraction.
+- **Two channel types** — `skill_type="smart_home"` for Yandex Smart Home
+  skills, `skill_type="dialog"` for Alice custom dialog (`aliceSkill`) skills.
+- **Incremental state machine** — `SkillCreationArtifacts` snapshots progress
+  after every step. On transient failure, retry resumes from the last
+  completed step instead of restarting.
+- **Framework-agnostic** — caller provides a `WebserverAdapter` Protocol
+  implementation for hosting the short-lived Device Code activation page.
+  Works with aiohttp, FastAPI, Starlette, or any ASGI/aiohttp-compatible
+  webserver.
+- **Strictly typed** — `mypy --strict` clean, PEP 561 `py.typed` marker.
+- **Security-aware** — `SecretStr` redacts tokens in repr/str/format/tracebacks
+  (re-exported from `ya-passport-auth`).
+
+## Installation
+
+```bash
+pip install ya-dialogs-api
+```
+
+## Quick start
+
+```python
+import asyncio
+from ya_dialogs_api import (
+    SkillCreationArtifacts,
+    SkillCreationState,
+    WebserverAdapter,
+    auto_create_skill,
+    load_default_logo_bytes,
+)
+
+# 1. Implement WebserverAdapter against your HTTP framework.
+#    See docs for an aiohttp reference implementation.
+my_webserver: WebserverAdapter = ...
+
+# 2. Drive the pipeline. Persist artifacts between calls — the next
+#    invocation will resume from the last completed step.
+async def main() -> None:
+    artifacts = SkillCreationArtifacts(state=SkillCreationState.PENDING)
+    result = await auto_create_skill(
+        webserver=my_webserver,
+        connection_type="direct",
+        skill_name="My Smart Home",
+        artifacts=artifacts,
+        cloud_instance_id="...",
+        direct_client_secret="...",
+        logo_bytes=load_default_logo_bytes(),
+        session_id="cfg-flow-1",
+        skill_type="smart_home",
+    )
+    if result.state == SkillCreationState.DONE:
+        print(f"Skill created: skill_id={result.skill_id}")
+    else:
+        print(f"Failed at step {result.state}: {result.last_error}")
+
+asyncio.run(main())
+```
+
+## Status
+
+**Beta.** The API is stable enough to depend on, but the underlying Yandex dev-
+console endpoints are unofficial (reverse-engineered from DevTools traces) and
+may break without notice. The library is actively maintained against the
+current production endpoint behavior.
+
+## See also
+
+- [`ya-passport-auth`](https://github.com/trudenboy/ya-passport-auth) — Yandex
+  Passport authentication library. Required runtime dependency for the OAuth
+  Device Flow used by this library.
+- [`ma-provider-yandex-smarthome`](https://github.com/trudenboy/ma-provider-yandex-smarthome)
+  and [`ma-provider-yandex-alice`](https://github.com/trudenboy/ma-provider-yandex-alice)
+  — Music Assistant providers that consume this library.
+
+## License
+
+[MIT](LICENSE)

ya_dialogs_api-1.0.0/README.md

@@ -0,0 +1,107 @@
+# ya-dialogs-api
+
+> Async Yandex Dialogs Developer API client — programmatic skill creation, draft management, OAuth Device Flow.
+
+[![CI](https://github.com/trudenboy/ya-dialogs-api/actions/workflows/ci.yml/badge.svg)](https://github.com/trudenboy/ya-dialogs-api/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ya-dialogs-api)](https://pypi.org/project/ya-dialogs-api/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## What this is
+
+A framework-agnostic Python library that drives the **Yandex Dialogs Developer
+API** — the meta-API at `dialogs.yandex.ru/developer-api/v2/` used to
+programmatically create and manage Alice skills (Smart Home and custom dialog
+skills). Where every other Yandex Alice library on PyPI handles the *runtime*
+side (incoming webhook requests from end users), this one handles the
+*provisioning* side: sign in via Yandex Passport Device Flow, create a skill,
+upload a logo, set the webhook backend URL, publish a draft, poll for
+publication state.
+
+It exists because Yandex doesn't publish a developer-API SDK and the only
+known Python implementation lived inside the Music Assistant
+`ma-provider-yandex-smarthome` plugin. This library is that code, extracted
+and made generic.
+
+## Features
+
+- **Full skill auto-creation pipeline** — Device Flow OAuth → CSRF/cookie
+  session → POST `/apps` → POST `/skills/{id}/draft` → publication polling →
+  callback URL extraction.
+- **Two channel types** — `skill_type="smart_home"` for Yandex Smart Home
+  skills, `skill_type="dialog"` for Alice custom dialog (`aliceSkill`) skills.
+- **Incremental state machine** — `SkillCreationArtifacts` snapshots progress
+  after every step. On transient failure, retry resumes from the last
+  completed step instead of restarting.
+- **Framework-agnostic** — caller provides a `WebserverAdapter` Protocol
+  implementation for hosting the short-lived Device Code activation page.
+  Works with aiohttp, FastAPI, Starlette, or any ASGI/aiohttp-compatible
+  webserver.
+- **Strictly typed** — `mypy --strict` clean, PEP 561 `py.typed` marker.
+- **Security-aware** — `SecretStr` redacts tokens in repr/str/format/tracebacks
+  (re-exported from `ya-passport-auth`).
+
+## Installation
+
+```bash
+pip install ya-dialogs-api
+```
+
+## Quick start
+
+```python
+import asyncio
+from ya_dialogs_api import (
+    SkillCreationArtifacts,
+    SkillCreationState,
+    WebserverAdapter,
+    auto_create_skill,
+    load_default_logo_bytes,
+)
+
+# 1. Implement WebserverAdapter against your HTTP framework.
+#    See docs for an aiohttp reference implementation.
+my_webserver: WebserverAdapter = ...
+
+# 2. Drive the pipeline. Persist artifacts between calls — the next
+#    invocation will resume from the last completed step.
+async def main() -> None:
+    artifacts = SkillCreationArtifacts(state=SkillCreationState.PENDING)
+    result = await auto_create_skill(
+        webserver=my_webserver,
+        connection_type="direct",
+        skill_name="My Smart Home",
+        artifacts=artifacts,
+        cloud_instance_id="...",
+        direct_client_secret="...",
+        logo_bytes=load_default_logo_bytes(),
+        session_id="cfg-flow-1",
+        skill_type="smart_home",
+    )
+    if result.state == SkillCreationState.DONE:
+        print(f"Skill created: skill_id={result.skill_id}")
+    else:
+        print(f"Failed at step {result.state}: {result.last_error}")
+
+asyncio.run(main())
+```
+
+## Status
+
+**Beta.** The API is stable enough to depend on, but the underlying Yandex dev-
+console endpoints are unofficial (reverse-engineered from DevTools traces) and
+may break without notice. The library is actively maintained against the
+current production endpoint behavior.
+
+## See also
+
+- [`ya-passport-auth`](https://github.com/trudenboy/ya-passport-auth) — Yandex
+  Passport authentication library. Required runtime dependency for the OAuth
+  Device Flow used by this library.
+- [`ma-provider-yandex-smarthome`](https://github.com/trudenboy/ma-provider-yandex-smarthome)
+  and [`ma-provider-yandex-alice`](https://github.com/trudenboy/ma-provider-yandex-alice)
+  — Music Assistant providers that consume this library.
+
+## License
+
+[MIT](LICENSE)

ya_dialogs_api-1.0.0/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you discover a security issue, **please do not open a public issue.**
+
+Instead, email the maintainer directly or use GitHub's private vulnerability
+reporting feature at:
+https://github.com/trudenboy/ya-dialogs-api/security/advisories/new
+
+You will receive an acknowledgement within 72 hours and a resolution timeline
+within 7 days.
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | Yes       |
+
+## Threat model summary
+
+This library is a relatively thin HTTP client over the Yandex Dialogs developer
+API. The hot security perimeter (Yandex Passport credentials, OAuth tokens,
+session cookies) is owned by `ya-passport-auth`, which has its own threat
+model. The threats specific to this library are:
+
+| # | Threat | Mitigation |
+|---|--------|------------|
+| D1 | Skill credentials leak via logs (skill_id is sensitive enough that an attacker who learns it can call dialogs.yandex.net/api/v1/skills/{id}/callback/state if they also have skill_token) | Library-side: never logs full credentials; only logs `step` + status code + first 200 chars of error body, which never contain skill_token |
+| D2 | DoS via unbounded HTML response from dev-console | 2 MiB hard cap on developer page HTML (`_MAX_HTML_RESPONSE_BYTES`) |
+| D3 | ReDoS on CSRF regex | Single explicit character class, non-greedy. The regex matches inside a 2 MiB cap |
+| D4 | Spoofed dev-console responses (e.g. on a malicious proxy) | TLS verification is the caller's responsibility on the supplied `aiohttp.ClientSession` (this library does not own the session) |
+| D5 | CSRF token reuse across attempts | `fetch_csrf` is called once per attempt; orchestrator does not cache the token across `auto_create_skill` calls |
+| D6 | Pickled `SkillCreationArtifacts` carrying secrets | Artifacts dataclass is frozen but does not currently carry secrets — only IDs (skill_id, logo_id, oauth_app_id). The actual `skill_token` is owned by the caller and never enters the artifacts object |
+| D7 | Supply-chain compromise via this library | Hash-pinned `uv.lock`, `pip-audit` in CI, Dependabot enabled, OpenSSF Scorecard published |
+| D8 | Real Yandex tokens in test fixtures | All test data uses synthetic tokens (`csrf-token`, `test-secret`, `skill-id-123`); no production credentials in source tree |
+
+For the security of the Passport authentication flow, OAuth Device Flow,
+SecretStr handling, host allow-list, and TLS verification, see the threat model
+of [`ya-passport-auth`](https://github.com/trudenboy/ya-passport-auth) — this
+library uses it as a runtime dependency.
+
+## Out of scope
+
+- Host compromise / memory scraping
+- Side-channel timing attacks
+- Encrypted at-rest storage of artifacts (caller responsibility)
+- The undocumented Yandex API itself — if Yandex changes endpoint shapes or
+  auth requirements, this library's release cadence is the mitigation
+- CAPTCHA / anti-bot bypass

ya_dialogs_api-1.0.0/VERSION

@@ -0,0 +1 @@
+1.0.0