asoradar 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. asoradar-1.0.0/.github/workflows/ci.yml +30 -0
  2. asoradar-1.0.0/.gitignore +6 -0
  3. asoradar-1.0.0/CHANGELOG.md +24 -0
  4. asoradar-1.0.0/LICENSE +21 -0
  5. asoradar-1.0.0/PKG-INFO +197 -0
  6. asoradar-1.0.0/README.md +172 -0
  7. asoradar-1.0.0/openapi.json +1 -0
  8. asoradar-1.0.0/pyproject.toml +44 -0
  9. asoradar-1.0.0/scripts/generate.py +196 -0
  10. asoradar-1.0.0/src/asoradar/__init__.py +108 -0
  11. asoradar-1.0.0/src/asoradar/_api_async.py +247 -0
  12. asoradar-1.0.0/src/asoradar/_api_sync.py +247 -0
  13. asoradar-1.0.0/src/asoradar/_errors.py +56 -0
  14. asoradar-1.0.0/src/asoradar/_http.py +156 -0
  15. asoradar-1.0.0/src/asoradar/_version.py +2 -0
  16. asoradar-1.0.0/src/asoradar/py.typed +0 -0
  17. asoradar-1.0.0/tests/test_e2e.py +31 -0
  18. asoradar-1.0.0/tests/test_smoke.py +179 -0
  19. asoradar-1.0.0/tests/test_unit.py +58 -0
asoradar-1.0.0/.github/workflows/ci.yml ADDED
@@ -0,0 +1,30 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python: ["3.10", "3.11", "3.12", "3.13"]
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: astral-sh/setup-uv@v5
17
+ - run: uv python install ${{ matrix.python }}
18
+ - run: uv sync --python ${{ matrix.python }}
19
+ - run: uv run pytest tests/test_unit.py tests/test_smoke.py -q
20
+
21
+ e2e:
22
+ runs-on: ubuntu-latest
23
+ if: ${{ github.event_name == 'push' }}
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+ - uses: astral-sh/setup-uv@v5
27
+ - run: uv sync
28
+ - run: uv run pytest tests/test_e2e.py -q
29
+ env:
30
+ ASORADAR_KEY: ${{ secrets.ASORADAR_KEY }}
asoradar-1.0.0/.gitignore ADDED
@@ -0,0 +1,6 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ .venv/
5
+ .pytest_cache/
6
+ uv.lock
asoradar-1.0.0/CHANGELOG.md ADDED
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ All notable changes to the `asoradar` Python SDK are documented here.
4
+
5
+ ## 1.0.0 — 2026-07-02
6
+
7
+ First public release — the official Python SDK for the
8
+ [ASORadar](https://asoradar.com) API.
9
+
10
+ ### Added
11
+ - **`ASORadar` (sync) and `AsyncASORadar` (async)** clients with three
12
+ namespaces mirroring the API: `app_store` (`/a1/*`), `google_play`
13
+ (`/g1/*`), `webhooks` (`/webhooks`) — 44 methods covering reviews,
14
+ metadata, search, suggest, top charts, similar apps, developer portfolios,
15
+ categories, version history, privacy / Data Safety / permissions (+ diffs),
16
+ ratings, clone-brief, niche-scan, review sentiment, and webhook
17
+ subscription CRUD + secret rotation.
18
+ - **Generated surface** — method signatures come from the live OpenAPI spec
19
+ (`python scripts/generate.py`); typed (PEP 561).
20
+ - **`ASORadarError`** with a machine-usable `kind`
21
+ (`auth`, `budget_exceeded`, `rate_limited` incl. `retry_after_seconds`,
22
+ `validation`, `not_found`, `server`, `timeout`, `network`).
23
+ - `client.request()` escape hatch for endpoints newer than the SDK build.
24
+ - Single dependency (`httpx`); Python ≥ 3.10; context-manager support.
asoradar-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ASORadar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
asoradar-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,197 @@
1
+ Metadata-Version: 2.4
2
+ Name: asoradar
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for the ASORadar API — App Store & Google Play reviews, app metadata, rankings, and ASO intelligence.
5
+ Project-URL: Homepage, https://asoradar.com
6
+ Project-URL: Documentation, https://api.asoradar.com/docs
7
+ Project-URL: Repository, https://github.com/asoradar/asoradar-python
8
+ Project-URL: Changelog, https://github.com/asoradar/asoradar-python/blob/main/CHANGELOG.md
9
+ Author-email: ASORadar <support@asoradar.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: api,app-intelligence,app-reviews,app-store,aso,asoradar,client,google-play,reviews,sdk
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: httpx>=0.27
24
+ Description-Content-Type: text/markdown
25
+
26
+ # asoradar
27
+
28
+ [![PyPI version](https://img.shields.io/pypi/v/asoradar.svg)](https://pypi.org/project/asoradar/)
29
+ [![Python versions](https://img.shields.io/pypi/pyversions/asoradar.svg)](https://pypi.org/project/asoradar/)
30
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
31
+
32
+ Official Python SDK for the [ASORadar](https://asoradar.com) API — App Store & Google Play reviews, app metadata, version history, rankings, and ASO intelligence for developers and AI agents.
33
+
34
+ - **Sync and async** — `ASORadar` and `AsyncASORadar`, same surface.
35
+ - **Generated from the live OpenAPI spec** — 44 methods across App Store, Google Play, and Webhooks.
36
+ - **Typed** (PEP 561) with machine-usable errors — branch on `err.kind`, not status tables.
37
+ - One dependency: [`httpx`](https://www.python-httpx.org/). Python ≥ 3.10.
38
+
39
+ ## Get 100 Free API Requests
40
+
41
+ [Sign up](https://asoradar.com/registration) and get **100 free ASORadar requests** — no credit card required.
42
+
43
+ ## Install
44
+
45
+ ```bash
46
+ pip install asoradar
47
+ # or: uv add asoradar / poetry add asoradar
48
+ ```
49
+
50
+ ## Quickstart
51
+
52
+ ```python
53
+ from asoradar import ASORadar
54
+
55
+ client = ASORadar(access_key="YOUR_KEY") # https://asoradar.com/tokens
56
+
57
+ # Recent App Store reviews for Instagram
58
+ reviews = client.app_store.reviews(app_id="389801252", country="us")
59
+
60
+ # Google Play app metadata
61
+ app = client.google_play.app("com.whatsapp", country="de")
62
+
63
+ # What changed in the last releases?
64
+ versions = client.app_store.version_history("389801252")
65
+
66
+ # One-call competitor brief: metadata + ratings + top complaints
67
+ brief = client.app_store.clone_brief("6446901002")
68
+ ```
69
+
70
+ Async:
71
+
72
+ ```python
73
+ from asoradar import AsyncASORadar
74
+
75
+ async with AsyncASORadar(access_key="YOUR_KEY") as client:
76
+ reviews = await client.app_store.reviews(app_id="389801252")
77
+ ```
78
+
79
+ ## Usage
80
+
81
+ The client mirrors the API's three surfaces:
82
+
83
+ ### `client.app_store` — App Store (`/a1/*`)
84
+
85
+ ```python
86
+ client.app_store.reviews(app_id="389801252", rating=1, search="crash")
87
+ client.app_store.reviews_by_version(app_id="389801252", version="435.0.0")
88
+ client.app_store.reviews_sentiment("389801252")
89
+ client.app_store.app_by_name(name="Instagram")
90
+ client.app_store.app("389801252")
91
+ client.app_store.search(term="photo editor", country="us")
92
+ client.app_store.suggest(term="insta")
93
+ client.app_store.list(collection="topfreeapplications", num=50)
94
+ client.app_store.similar("389801252")
95
+ client.app_store.developer("389801255")
96
+ client.app_store.developer_portfolio_stats("389801255")
97
+ client.app_store.categories()
98
+ client.app_store.version_history("389801252")
99
+ client.app_store.version_history_diff("389801252")
100
+ client.app_store.metadata_diff("389801252")
101
+ client.app_store.privacy("389801252")
102
+ client.app_store.privacy_diff("389801252")
103
+ client.app_store.ratings("389801252")
104
+ client.app_store.clone_brief("389801252")
105
+ client.app_store.niche_scan(category="6008", country="us")
106
+ ```
107
+
108
+ ### `client.google_play` — Google Play (`/g1/*`)
109
+
110
+ Same shape with Google-specific extras:
111
+
112
+ ```python
113
+ client.google_play.reviews(app_id="com.whatsapp", country="de")
114
+ client.google_play.permissions("com.whatsapp")
115
+ client.google_play.permissions_diff("com.whatsapp")
116
+ client.google_play.datasafety("com.whatsapp")
117
+ client.google_play.datasafety_diff("com.whatsapp")
118
+ # ...plus reviews/search/suggest/list/similar/developer/categories/
119
+ # metadata_diff/clone_brief/niche_scan/reviews_sentiment, as on app_store
120
+ ```
121
+
122
+ ### `client.webhooks` — subscriptions (`/webhooks`)
123
+
124
+ Get notified on app changes, chart movement, or review keyword matches:
125
+
126
+ ```python
127
+ sub = client.webhooks.create(
128
+ kind="app_changes",
129
+ target_url="https://example.com/hooks/asoradar",
130
+ criteria={"store": "apple", "app_id": "389801252"},
131
+ )
132
+ # sub["secret"] is returned ONCE — store it to verify HMAC signatures.
133
+
134
+ client.webhooks.list()
135
+ client.webhooks.get(sub["id"])
136
+ client.webhooks.rotate_secret(sub["id"])
137
+ client.webhooks.delete(sub["id"])
138
+ ```
139
+
140
+ ### Freshness
141
+
142
+ Read endpoints are cache-first. Pass `fresh=True` to force a live refresh:
143
+
144
+ ```python
145
+ client.app_store.reviews(app_id="389801252", fresh=True)
146
+ ```
147
+
148
+ ## Error handling
149
+
150
+ Every failure raises `ASORadarError` with a machine-usable `kind`:
151
+
152
+ ```python
153
+ from asoradar import ASORadar, ASORadarError
154
+
155
+ try:
156
+ client.app_store.reviews(app_id="389801252")
157
+ except ASORadarError as err:
158
+ match err.kind:
159
+ case "budget_exceeded": # 402 — top up, do not retry
160
+ ...
161
+ case "rate_limited": # 429 — wait err.retry_after_seconds
162
+ ...
163
+ case "auth": # 401/403 — check your access key
164
+ ...
165
+ case "validation" | "not_found" | "server" | "timeout" | "network" | "api":
166
+ ...
167
+ print(err.status, err.kind, err.body)
168
+ ```
169
+
170
+ ## Options
171
+
172
+ ```python
173
+ ASORadar(
174
+ access_key="...", # required — https://asoradar.com/tokens
175
+ base_url="https://api.asoradar.com", # optional
176
+ timeout=30.0, # optional, per request (seconds)
177
+ transport=custom_httpx_transport, # optional — tests, proxies
178
+ )
179
+ ```
180
+
181
+ ## Escape hatch
182
+
183
+ Endpoints newer than this SDK build are still reachable with full auth / error handling:
184
+
185
+ ```python
186
+ client.request("GET", "/a1/brand-new-endpoint", query={"app_id": "..."})
187
+ ```
188
+
189
+ ## Related
190
+
191
+ - [`asoradar`](https://www.npmjs.com/package/asoradar) on npm — the JavaScript / TypeScript SDK.
192
+ - [`asoradar-mcp`](https://www.npmjs.com/package/asoradar-mcp) — MCP server that exposes this API as tools for AI agents (Claude, Cursor, Codex, …).
193
+ - [API docs](https://api.asoradar.com/docs)
194
+
195
+ ## License
196
+
197
+ MIT — see [LICENSE](LICENSE).
asoradar-1.0.0/README.md ADDED
@@ -0,0 +1,172 @@
1
+ # asoradar
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/asoradar.svg)](https://pypi.org/project/asoradar/)
4
+ [![Python versions](https://img.shields.io/pypi/pyversions/asoradar.svg)](https://pypi.org/project/asoradar/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ Official Python SDK for the [ASORadar](https://asoradar.com) API — App Store & Google Play reviews, app metadata, version history, rankings, and ASO intelligence for developers and AI agents.
8
+
9
+ - **Sync and async** — `ASORadar` and `AsyncASORadar`, same surface.
10
+ - **Generated from the live OpenAPI spec** — 44 methods across App Store, Google Play, and Webhooks.
11
+ - **Typed** (PEP 561) with machine-usable errors — branch on `err.kind`, not status tables.
12
+ - One dependency: [`httpx`](https://www.python-httpx.org/). Python ≥ 3.10.
13
+
14
+ ## Get 100 Free API Requests
15
+
16
+ [Sign up](https://asoradar.com/registration) and get **100 free ASORadar requests** — no credit card required.
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ pip install asoradar
22
+ # or: uv add asoradar / poetry add asoradar
23
+ ```
24
+
25
+ ## Quickstart
26
+
27
+ ```python
28
+ from asoradar import ASORadar
29
+
30
+ client = ASORadar(access_key="YOUR_KEY") # https://asoradar.com/tokens
31
+
32
+ # Recent App Store reviews for Instagram
33
+ reviews = client.app_store.reviews(app_id="389801252", country="us")
34
+
35
+ # Google Play app metadata
36
+ app = client.google_play.app("com.whatsapp", country="de")
37
+
38
+ # What changed in the last releases?
39
+ versions = client.app_store.version_history("389801252")
40
+
41
+ # One-call competitor brief: metadata + ratings + top complaints
42
+ brief = client.app_store.clone_brief("6446901002")
43
+ ```
44
+
45
+ Async:
46
+
47
+ ```python
48
+ from asoradar import AsyncASORadar
49
+
50
+ async with AsyncASORadar(access_key="YOUR_KEY") as client:
51
+ reviews = await client.app_store.reviews(app_id="389801252")
52
+ ```
53
+
54
+ ## Usage
55
+
56
+ The client mirrors the API's three surfaces:
57
+
58
+ ### `client.app_store` — App Store (`/a1/*`)
59
+
60
+ ```python
61
+ client.app_store.reviews(app_id="389801252", rating=1, search="crash")
62
+ client.app_store.reviews_by_version(app_id="389801252", version="435.0.0")
63
+ client.app_store.reviews_sentiment("389801252")
64
+ client.app_store.app_by_name(name="Instagram")
65
+ client.app_store.app("389801252")
66
+ client.app_store.search(term="photo editor", country="us")
67
+ client.app_store.suggest(term="insta")
68
+ client.app_store.list(collection="topfreeapplications", num=50)
69
+ client.app_store.similar("389801252")
70
+ client.app_store.developer("389801255")
71
+ client.app_store.developer_portfolio_stats("389801255")
72
+ client.app_store.categories()
73
+ client.app_store.version_history("389801252")
74
+ client.app_store.version_history_diff("389801252")
75
+ client.app_store.metadata_diff("389801252")
76
+ client.app_store.privacy("389801252")
77
+ client.app_store.privacy_diff("389801252")
78
+ client.app_store.ratings("389801252")
79
+ client.app_store.clone_brief("389801252")
80
+ client.app_store.niche_scan(category="6008", country="us")
81
+ ```
82
+
83
+ ### `client.google_play` — Google Play (`/g1/*`)
84
+
85
+ Same shape with Google-specific extras:
86
+
87
+ ```python
88
+ client.google_play.reviews(app_id="com.whatsapp", country="de")
89
+ client.google_play.permissions("com.whatsapp")
90
+ client.google_play.permissions_diff("com.whatsapp")
91
+ client.google_play.datasafety("com.whatsapp")
92
+ client.google_play.datasafety_diff("com.whatsapp")
93
+ # ...plus reviews/search/suggest/list/similar/developer/categories/
94
+ # metadata_diff/clone_brief/niche_scan/reviews_sentiment, as on app_store
95
+ ```
96
+
97
+ ### `client.webhooks` — subscriptions (`/webhooks`)
98
+
99
+ Get notified on app changes, chart movement, or review keyword matches:
100
+
101
+ ```python
102
+ sub = client.webhooks.create(
103
+ kind="app_changes",
104
+ target_url="https://example.com/hooks/asoradar",
105
+ criteria={"store": "apple", "app_id": "389801252"},
106
+ )
107
+ # sub["secret"] is returned ONCE — store it to verify HMAC signatures.
108
+
109
+ client.webhooks.list()
110
+ client.webhooks.get(sub["id"])
111
+ client.webhooks.rotate_secret(sub["id"])
112
+ client.webhooks.delete(sub["id"])
113
+ ```
114
+
115
+ ### Freshness
116
+
117
+ Read endpoints are cache-first. Pass `fresh=True` to force a live refresh:
118
+
119
+ ```python
120
+ client.app_store.reviews(app_id="389801252", fresh=True)
121
+ ```
122
+
123
+ ## Error handling
124
+
125
+ Every failure raises `ASORadarError` with a machine-usable `kind`:
126
+
127
+ ```python
128
+ from asoradar import ASORadar, ASORadarError
129
+
130
+ try:
131
+ client.app_store.reviews(app_id="389801252")
132
+ except ASORadarError as err:
133
+ match err.kind:
134
+ case "budget_exceeded": # 402 — top up, do not retry
135
+ ...
136
+ case "rate_limited": # 429 — wait err.retry_after_seconds
137
+ ...
138
+ case "auth": # 401/403 — check your access key
139
+ ...
140
+ case "validation" | "not_found" | "server" | "timeout" | "network" | "api":
141
+ ...
142
+ print(err.status, err.kind, err.body)
143
+ ```
144
+
145
+ ## Options
146
+
147
+ ```python
148
+ ASORadar(
149
+ access_key="...", # required — https://asoradar.com/tokens
150
+ base_url="https://api.asoradar.com", # optional
151
+ timeout=30.0, # optional, per request (seconds)
152
+ transport=custom_httpx_transport, # optional — tests, proxies
153
+ )
154
+ ```
155
+
156
+ ## Escape hatch
157
+
158
+ Endpoints newer than this SDK build are still reachable with full auth / error handling:
159
+
160
+ ```python
161
+ client.request("GET", "/a1/brand-new-endpoint", query={"app_id": "..."})
162
+ ```
163
+
164
+ ## Related
165
+
166
+ - [`asoradar`](https://www.npmjs.com/package/asoradar) on npm — the JavaScript / TypeScript SDK.
167
+ - [`asoradar-mcp`](https://www.npmjs.com/package/asoradar-mcp) — MCP server that exposes this API as tools for AI agents (Claude, Cursor, Codex, …).
168
+ - [API docs](https://api.asoradar.com/docs)
169
+
170
+ ## License
171
+
172
+ MIT — see [LICENSE](LICENSE).