voipano 1.0.1__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.
- voipano-1.0.1/CHANGELOG.md +15 -0
- voipano-1.0.1/LICENSE +21 -0
- voipano-1.0.1/MANIFEST.in +7 -0
- voipano-1.0.1/PKG-INFO +205 -0
- voipano-1.0.1/README.fa.md +93 -0
- voipano-1.0.1/README.md +174 -0
- voipano-1.0.1/SECURITY.md +15 -0
- voipano-1.0.1/docs/voipano-webservice.postman_collection.json +1069 -0
- voipano-1.0.1/pyproject.toml +49 -0
- voipano-1.0.1/setup.cfg +4 -0
- voipano-1.0.1/src/voipano/__init__.py +28 -0
- voipano-1.0.1/src/voipano/_http.py +279 -0
- voipano-1.0.1/src/voipano/client.py +102 -0
- voipano-1.0.1/src/voipano/exceptions.py +61 -0
- voipano-1.0.1/src/voipano/py.typed +0 -0
- voipano-1.0.1/src/voipano/resources.py +165 -0
- voipano-1.0.1/src/voipano/webhooks.py +42 -0
- voipano-1.0.1/src/voipano.egg-info/PKG-INFO +205 -0
- voipano-1.0.1/src/voipano.egg-info/SOURCES.txt +25 -0
- voipano-1.0.1/src/voipano.egg-info/dependency_links.txt +1 -0
- voipano-1.0.1/src/voipano.egg-info/requires.txt +6 -0
- voipano-1.0.1/src/voipano.egg-info/top_level.txt +1 -0
- voipano-1.0.1/tests/conftest.py +72 -0
- voipano-1.0.1/tests/test_client.py +181 -0
- voipano-1.0.1/tests/test_recordings.py +61 -0
- voipano-1.0.1/tests/test_resources.py +94 -0
- voipano-1.0.1/tests/test_webhooks.py +26 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [1.0.1] - 2026-11-22
|
|
4
|
+
|
|
5
|
+
- Publish the official PyPI distribution as `voipano`.
|
|
6
|
+
- Preserve compatibility with the existing Python import API.
|
|
7
|
+
|
|
8
|
+
## [1.0.0] - 2026-11-22
|
|
9
|
+
|
|
10
|
+
- Initial Python SDK for the Voipano Public Webservice API v1 (23 documented requests).
|
|
11
|
+
- Typed client with isolated token/service scopes and standard API exceptions.
|
|
12
|
+
- Contacts, contact groups, calls, OTP, reports, recordings, and outgoing webhook resources.
|
|
13
|
+
- Streamed, exclusive audio downloads with cleanup on errors.
|
|
14
|
+
- Fail-closed optional incoming webhook receiver; signing specification pending API verification.
|
|
15
|
+
- Offline endpoint-contract tests, Python 3.11+ support, CI, and PyPI Trusted Publishing workflow.
|
voipano-1.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Voipano contributors
|
|
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.
|
voipano-1.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: voipano
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Official Python SDK for the Voipano Public API v1
|
|
5
|
+
Author: Voipano
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://voipano.com
|
|
8
|
+
Project-URL: Source, https://github.com/voipano/python-voipano
|
|
9
|
+
Project-URL: Issues, https://github.com/voipano/python-voipano/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/voipano/python-voipano#readme
|
|
11
|
+
Keywords: voipano,voip,telephony,call-center,api,otp,webhooks
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
20
|
+
Classifier: Topic :: Communications :: Telephony
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: requests<3,>=2.31.0
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
28
|
+
Requires-Dist: build<2,>=1.2; extra == "dev"
|
|
29
|
+
Requires-Dist: twine<8,>=5; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# Voipano Python SDK
|
|
33
|
+
|
|
34
|
+
[فارسی](README.fa.md) · [Postman collection](docs/voipano-webservice.postman_collection.json) · [Security](SECURITY.md)
|
|
35
|
+
|
|
36
|
+
The official, synchronous Python SDK for the **Voipano Public Webservice API v1**, providing the documented **23 requests** from the Postman collection dated **2026-11-21**. Designed for ordinary Python, Django, Flask, FastAPI, and other Python applications; there is **no framework dependency**.
|
|
37
|
+
|
|
38
|
+
## Requirements
|
|
39
|
+
|
|
40
|
+
- Python **3.11+** (the oldest Python line still receiving official security fixes in November 2026).
|
|
41
|
+
- An active Voipano API token for your account.
|
|
42
|
+
- The [`requests`](https://pypi.org/project/requests/) HTTP library is installed automatically.
|
|
43
|
+
|
|
44
|
+
## Install
|
|
45
|
+
|
|
46
|
+
After the first PyPI release:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
python -m pip install voipano
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Set an environment variable in your application environment (do not commit credentials):
|
|
53
|
+
|
|
54
|
+
```dotenv
|
|
55
|
+
VOIPANO_API_TOKEN=your-private-token
|
|
56
|
+
# Optional when your token does not select a single service:
|
|
57
|
+
VOIPANO_SERVICE_ID=
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
There is **no configuration file, CLI setup, database migration, or framework integration** required for outgoing requests.
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from voipano import VoipanoClient
|
|
66
|
+
|
|
67
|
+
with VoipanoClient() as voipano: # reads VOIPANO_API_TOKEN from the environment
|
|
68
|
+
services = voipano.services.all()
|
|
69
|
+
contacts = voipano.contacts.all({"search": "Ali", "page": 1, "per_page": 20})
|
|
70
|
+
contact = voipano.contacts.find("contact-id")
|
|
71
|
+
voipano.contacts.create({"primary_number": "09120000000", "first_name": "Ali"})
|
|
72
|
+
voipano.contacts.update("contact-id", {"first_name": "Ali"})
|
|
73
|
+
|
|
74
|
+
# These calls trigger REAL telecommunications operations and may incur costs:
|
|
75
|
+
# voipano.calls.otp("09120000000", purpose="login")
|
|
76
|
+
# voipano.calls.click_to_call("09120000000", "09121111111", timeout=30)
|
|
77
|
+
# voipano.calls.secure_call("09120000000", "09121111111", retry_count=0)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
If preferred, pass credentials directly: `VoipanoClient(token="your-private-token")`.
|
|
81
|
+
|
|
82
|
+
## Multi-service and multi-tenant requests
|
|
83
|
+
|
|
84
|
+
Each scoped client has its own token, service ID, and request ID configuration without changing the original client:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
client = VoipanoClient(token="your-private-token")
|
|
88
|
+
customer_client = client.with_token("customer-token").for_service("service-id")
|
|
89
|
+
reports = customer_client.call_reports.all({"page": 1})
|
|
90
|
+
traced = customer_client.with_request_id("my-request-id").services.all()
|
|
91
|
+
customer_client.close()
|
|
92
|
+
client.close()
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Note: independently created clients manage their own HTTP sessions. Injected custom sessions are shared between scoped copies; manage their lifecycle yourself.
|
|
96
|
+
|
|
97
|
+
## API resource methods
|
|
98
|
+
|
|
99
|
+
| Resource | Methods |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| `client.services` | `all()` |
|
|
102
|
+
| `client.contacts` | `all(filters)`, `find(id)`, `create(data)`, `update(id, data)`, `update_put(id, data)`, `delete(id)`, `bulk_import(contacts, options)` |
|
|
103
|
+
| `client.contact_groups` | `all(filters)`, `create(data)`, `delete(id)` |
|
|
104
|
+
| `client.music_on_holds` | `all(filters)` |
|
|
105
|
+
| `client.call_reports` | `all(filters)` |
|
|
106
|
+
| `client.voicemail_inboxes` | `all(filters)` |
|
|
107
|
+
| `client.recordings` | `call(cdr_id, record_id, query)`, `download_call(cdr_id, record_id, path, query)`, `voicemail(id, context, mailbox, query)`, `download_voicemail(id, context, mailbox, path, query)` |
|
|
108
|
+
| `client.webhooks` | `get()`, `configure(settings)`, `route(event, settings)`, `configure_legacy(settings)` |
|
|
109
|
+
| `client.calls` | `otp(phone, options, **kwargs)`, `click_to_call(source, destination, options, **kwargs)`, `secure_call(source, destination, options, **kwargs)` |
|
|
110
|
+
|
|
111
|
+
The client preserves API JSON responses as Python dictionaries or lists, without guessing about response schemas. HTTP 204 and empty responses return `{}`. Optional list filters are passed as documented, including `client_ref`.
|
|
112
|
+
|
|
113
|
+
### Call recordings and voicemail audio
|
|
114
|
+
|
|
115
|
+
Use **streaming** downloads for large files; the destination **must not already exist**, and its parent folder must already exist:
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from pathlib import Path
|
|
119
|
+
from voipano import VoipanoClient
|
|
120
|
+
|
|
121
|
+
client = VoipanoClient()
|
|
122
|
+
recording = client.recordings.download_call(
|
|
123
|
+
"cdr-id", "call-details-record-id", Path("private/audio/call.wav")
|
|
124
|
+
)
|
|
125
|
+
voicemail = client.recordings.download_voicemail(
|
|
126
|
+
"vm-id", "default", "1001", Path("private/audio/message.wav")
|
|
127
|
+
)
|
|
128
|
+
client.close()
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The binary `.call()` and `.voicemail()` methods return `bytes` and read the whole recording into memory; use them only for small files. Downloaded audio may contain personal information: store it outside a public/static directory, apply access controls, and follow applicable retention rules.
|
|
132
|
+
|
|
133
|
+
**Known collection ambiguity:** the example uses different `cdr_id` (path) and `call_details_record_id` (query) identifiers but describes them as the same ID. The SDK requires both parameters until the actual API contract is confirmed.
|
|
134
|
+
|
|
135
|
+
### Outgoing webhook configuration
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
client.webhooks.configure({
|
|
139
|
+
"endpoint_url": "https://your-domain.example/webhooks/voipano",
|
|
140
|
+
"secret": "your-webhook-secret",
|
|
141
|
+
"is_active": True,
|
|
142
|
+
})
|
|
143
|
+
client.webhooks.route("missed_call", {
|
|
144
|
+
"endpoint_url": "https://your-domain.example/webhooks/missed-call",
|
|
145
|
+
"is_active": True,
|
|
146
|
+
})
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Supported event names: `ringing`, `hangup`, `missed_call`, `call_details_record`. POST `configure_legacy` exists for the documented compatibility alias; prefer PUT `configure` for new integrations.
|
|
150
|
+
|
|
151
|
+
### Incoming webhook verification: secure by default
|
|
152
|
+
|
|
153
|
+
**Do not accept incoming events without verification.** The supplied Postman collection does not specify the signature header, signing algorithm, canonical payload, or replay-defense procedure. `WebhookReceiver` rejects all requests by default. Only supply a custom `WebhookVerifier` after validating the true protocol against the server implementation. There is intentionally **no web server route, hardcoded HMAC algorithm, or accept-all mode**.
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from voipano import WebhookReceiver, WebhookVerificationError
|
|
157
|
+
|
|
158
|
+
receiver = WebhookReceiver() # rejects all incoming requests until configured
|
|
159
|
+
# receiver.receive(raw_request_body, request_headers) -> raises WebhookVerificationError
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Errors and reliability
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
from voipano import ValidationError, VoipanoClient
|
|
166
|
+
|
|
167
|
+
try:
|
|
168
|
+
VoipanoClient().contacts.create({"primary_number": "09120000000"})
|
|
169
|
+
except ValidationError as error:
|
|
170
|
+
print(error.status_code, error.request_id, error.errors)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `ValidationError` (422), `RateLimitError` (429), and `ServerError` (5xx) derive from `ApiError`. Transport errors (`TransportError`) and invalid response formats (`UnexpectedResponseError`) are separate.
|
|
174
|
+
|
|
175
|
+
The SDK uses **Bearer authentication**, optional `X-Webservice-Service-Id`, and one UUID `X-Request-Id` per HTTP request. Redirects and automatic retries are disabled. **Never blindly retry OTP or call requests** after timeouts: `client_ref` is described as a tracking value, not a confirmed idempotency key. Do not log secrets or raw audio files.
|
|
176
|
+
|
|
177
|
+
Timeouts can be customized: `VoipanoClient(timeout=30, connect_timeout=10, base_url="https://voipano.com/api/v1/webservice")`. Optional `VOIPANO_BASE_URL` is supported for controlled staging environments. HTTP(S) only; production should use HTTPS.
|
|
178
|
+
|
|
179
|
+
## Testing and release
|
|
180
|
+
|
|
181
|
+
This repository includes offline tests that never start actual calls:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
python -m pip install -e '.[dev]'
|
|
185
|
+
python -m pytest -q
|
|
186
|
+
python -m build
|
|
187
|
+
python -m twine check dist/*
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`.github/workflows/tests.yml` runs tests on Python 3.11–3.15. `.github/workflows/publish.yml` builds, retests, checks metadata, and publishes on `v*` tags using **PyPI Trusted Publishing** (OIDC, no PyPI token stored in GitHub).
|
|
191
|
+
|
|
192
|
+
To enable the initial release:
|
|
193
|
+
|
|
194
|
+
1. Create a GitHub repository (suggested `voipano/python-voipano`) and upload the **contents** of this source repository.
|
|
195
|
+
2. Create a GitHub environment called **`pypi`**, ideally with required reviewers. If the GitHub owner/repository differs from the suggested link, edit the URLs in `pyproject.toml` before releasing.
|
|
196
|
+
3. On [PyPI](https://pypi.org/manage/account/publishing/), configure a **pending Trusted Publisher** for distribution **`voipano`**: GitHub owner `<your-owner>`, repository `<your-repository>`, workflow filename **`publish.yml`**, environment name **`pypi`**. Pending publishers create the PyPI project at first successful publish.
|
|
197
|
+
4. When your GitHub tests pass, create and push tag `v1.0.1` to trigger the release workflow. Do **not** upload `dist/` or API credentials to GitHub.
|
|
198
|
+
|
|
199
|
+
PyPI names are global and can be unavailable or reserved even if search does not find a project; confirm that `voipano` is accepted when registering the Trusted Publisher. A published release's version cannot be overwritten: create a new version/tag for future updates.
|
|
200
|
+
|
|
201
|
+
The Postman collection contains **no example JSON responses** and does not document inbound webhook signatures, rate limits or idempotency guarantees. Automated tests verify request contracts and the SDK's handling of mock responses; they do not establish live API compatibility.
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# SDK رسمی پایتون ویپانو
|
|
2
|
+
|
|
3
|
+
[English README](README.md) · [کالکشن Postman](docs/voipano-webservice.postman_collection.json)
|
|
4
|
+
|
|
5
|
+
کتابخانه پایتون برای اتصال ساده به **Voipano Public Webservice API v1** که هر **۲۳ درخواست** کالکشن مورخ **۲۰۲۶/۱۱/۲۱** را پوشش میدهد. بدون وابستگی به Django، Flask یا FastAPI و قابل استفاده در همه برنامههای معمول پایتون.
|
|
6
|
+
|
|
7
|
+
## پیشنیاز و نصب
|
|
8
|
+
|
|
9
|
+
- حداقل **Python 3.11**؛ قدیمیترین نسخه پایتون تحت پشتیبانی امنیتی در نوامبر ۲۰۲۶.
|
|
10
|
+
- توکن معتبر وبسرویس ویپانو.
|
|
11
|
+
|
|
12
|
+
پس از اولین انتشار در PyPI:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
python -m pip install voipano
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
متغیرهای محیطی برنامه خود را تنظیم کنید؛ توکن را هرگز در Git ثبت نکنید:
|
|
19
|
+
|
|
20
|
+
```dotenv
|
|
21
|
+
VOIPANO_API_TOKEN=your-private-token
|
|
22
|
+
VOIPANO_SERVICE_ID=
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
استفاده:
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from voipano import VoipanoClient
|
|
29
|
+
|
|
30
|
+
with VoipanoClient() as client:
|
|
31
|
+
services = client.services.all()
|
|
32
|
+
contacts = client.contacts.all({"page": 1, "per_page": 20})
|
|
33
|
+
client.contacts.create({"primary_number": "09120000000", "first_name": "Ali"})
|
|
34
|
+
|
|
35
|
+
# این عملیات تماس واقعی برقرار میکند؛ فقط پس از دریافت مجوز اجرا کنید:
|
|
36
|
+
# client.calls.otp("09120000000", purpose="login")
|
|
37
|
+
# client.calls.click_to_call("09120000000", "09121111111", timeout=30)
|
|
38
|
+
# client.calls.secure_call("09120000000", "09121111111", retry_count=0)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## امکانات
|
|
42
|
+
|
|
43
|
+
- مشاهده سرویسهای متصل به توکن؛ مدیریت مخاطبین و گروهها؛ ورود گروهی تا ۳۰۰۰ مخاطب.
|
|
44
|
+
- گزارش تماس، صندوق صوتی، صوت انتظار و دریافت یا دانلود فایلهای ضبطشده.
|
|
45
|
+
- OTP صوتی، تماس سریع و تماس امن؛ مدیریت وبهوک عمومی و اختصاصی ۴ نوع رویداد.
|
|
46
|
+
- پشتیبانی از چند توکن/سرویس بهصورت مستقل با `with_token()` و `for_service()`.
|
|
47
|
+
- خطاهای نوعبندیشده، تایماوت قابل تنظیم، شناسه درخواست و جلوگیری از Retry خودکار.
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
customer = client.with_token("customer-token").for_service("service-id")
|
|
51
|
+
reports = customer.call_reports.all({"page": 1})
|
|
52
|
+
customer.close()
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### دریافت فایل ضبطشده
|
|
56
|
+
|
|
57
|
+
برای فایلهای بزرگ از دانلود استریم استفاده کنید. پوشه مقصد باید از قبل وجود داشته باشد و فایل مقصد موجود نباشد:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from pathlib import Path
|
|
61
|
+
|
|
62
|
+
file_path = client.recordings.download_call(
|
|
63
|
+
"cdr-id", "call-details-record-id", Path("private/audio/call.wav")
|
|
64
|
+
)
|
|
65
|
+
voice_path = client.recordings.download_voicemail(
|
|
66
|
+
"vm-id", "default", "1001", Path("private/audio/message.wav")
|
|
67
|
+
)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
در مستندات Postman، دو شناسه `cdr_id` و `call_details_record_id` نمونه با یکدیگر متفاوتاند، در حالی که متن توضیحی آنها را یکسان میداند. تا مشخصشدن قرارداد واقعی، هر دو ورودی الزامی هستند.
|
|
71
|
+
|
|
72
|
+
### نکته امنیتی وبهوک
|
|
73
|
+
|
|
74
|
+
کالکشن فعلی **شیوه امضای وبهوک ورودی را مستند نکرده است**. به همین دلیل `WebhookReceiver` بهصورت پیشفرض تمام درخواستها را رد میکند و هیچ مسیر ورودی خودکاری فعال نیست. پس از تأیید روش امضا و پیشگیری از replay از سمت سرور، Verifier اختصاصی خودتان را متصل کنید. وبهوک عمومی و اختصاصی خروجی از طریق `client.webhooks` قابل تنظیم است.
|
|
75
|
+
|
|
76
|
+
### پایداری و خطاها
|
|
77
|
+
|
|
78
|
+
خطاهای 401، 403، 404، 422، 429 و 5xx به Exceptionهای مجزا تبدیل میشوند. انتقال ناموفق به `TransportError` و پاسخ نامعتبر به `UnexpectedResponseError` تبدیل میشود. درخواستها بازگردانی خودکار یا پیگیری Redirect ندارند. بعد از تایماوت تماس یا OTP، بدون تأیید وضعیت درخواست قبلی آن را تکرار نکنید.
|
|
79
|
+
|
|
80
|
+
## تست و انتشار
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
python -m pip install -e '.[dev]'
|
|
84
|
+
python -m pytest -q
|
|
85
|
+
python -m build
|
|
86
|
+
python -m twine check dist/*
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
فایلهای GitHub Actions آمادهاند: تست در `tests.yml` و انتشار امن در `publish.yml` با **Trusted Publishing** بدون API Token در مخزن. برای اولین انتشار باید در حساب PyPI یک **Pending Trusted Publisher** برای پروژه `voipano` بسازید و مالک GitHub، نام ریپازیتوری، نام workflow برابر `publish.yml` و environment برابر `pypi` را ثبت کنید. سپس پس از موفقیت تستهای GitHub، تگ `v1.0.1` را Push کنید. در GitHub هم environment با نام `pypi` ایجاد شود. اگر نام Repository با `voipano/python-voipano` متفاوت بود، لینکهای `pyproject.toml` را اصلاح کنید.
|
|
90
|
+
|
|
91
|
+
مستندات Postman پاسخهای نمونه و جزئیات امنیتی وبهوک را ندارد؛ بنابراین تستهای Mock جایگزین بررسی واقعی API نمیشوند.
|
|
92
|
+
|
|
93
|
+
مجوز: MIT.
|
voipano-1.0.1/README.md
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Voipano Python SDK
|
|
2
|
+
|
|
3
|
+
[فارسی](README.fa.md) · [Postman collection](docs/voipano-webservice.postman_collection.json) · [Security](SECURITY.md)
|
|
4
|
+
|
|
5
|
+
The official, synchronous Python SDK for the **Voipano Public Webservice API v1**, providing the documented **23 requests** from the Postman collection dated **2026-11-21**. Designed for ordinary Python, Django, Flask, FastAPI, and other Python applications; there is **no framework dependency**.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Python **3.11+** (the oldest Python line still receiving official security fixes in November 2026).
|
|
10
|
+
- An active Voipano API token for your account.
|
|
11
|
+
- The [`requests`](https://pypi.org/project/requests/) HTTP library is installed automatically.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
After the first PyPI release:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
python -m pip install voipano
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Set an environment variable in your application environment (do not commit credentials):
|
|
22
|
+
|
|
23
|
+
```dotenv
|
|
24
|
+
VOIPANO_API_TOKEN=your-private-token
|
|
25
|
+
# Optional when your token does not select a single service:
|
|
26
|
+
VOIPANO_SERVICE_ID=
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
There is **no configuration file, CLI setup, database migration, or framework integration** required for outgoing requests.
|
|
30
|
+
|
|
31
|
+
## Quick start
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from voipano import VoipanoClient
|
|
35
|
+
|
|
36
|
+
with VoipanoClient() as voipano: # reads VOIPANO_API_TOKEN from the environment
|
|
37
|
+
services = voipano.services.all()
|
|
38
|
+
contacts = voipano.contacts.all({"search": "Ali", "page": 1, "per_page": 20})
|
|
39
|
+
contact = voipano.contacts.find("contact-id")
|
|
40
|
+
voipano.contacts.create({"primary_number": "09120000000", "first_name": "Ali"})
|
|
41
|
+
voipano.contacts.update("contact-id", {"first_name": "Ali"})
|
|
42
|
+
|
|
43
|
+
# These calls trigger REAL telecommunications operations and may incur costs:
|
|
44
|
+
# voipano.calls.otp("09120000000", purpose="login")
|
|
45
|
+
# voipano.calls.click_to_call("09120000000", "09121111111", timeout=30)
|
|
46
|
+
# voipano.calls.secure_call("09120000000", "09121111111", retry_count=0)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
If preferred, pass credentials directly: `VoipanoClient(token="your-private-token")`.
|
|
50
|
+
|
|
51
|
+
## Multi-service and multi-tenant requests
|
|
52
|
+
|
|
53
|
+
Each scoped client has its own token, service ID, and request ID configuration without changing the original client:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
client = VoipanoClient(token="your-private-token")
|
|
57
|
+
customer_client = client.with_token("customer-token").for_service("service-id")
|
|
58
|
+
reports = customer_client.call_reports.all({"page": 1})
|
|
59
|
+
traced = customer_client.with_request_id("my-request-id").services.all()
|
|
60
|
+
customer_client.close()
|
|
61
|
+
client.close()
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Note: independently created clients manage their own HTTP sessions. Injected custom sessions are shared between scoped copies; manage their lifecycle yourself.
|
|
65
|
+
|
|
66
|
+
## API resource methods
|
|
67
|
+
|
|
68
|
+
| Resource | Methods |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| `client.services` | `all()` |
|
|
71
|
+
| `client.contacts` | `all(filters)`, `find(id)`, `create(data)`, `update(id, data)`, `update_put(id, data)`, `delete(id)`, `bulk_import(contacts, options)` |
|
|
72
|
+
| `client.contact_groups` | `all(filters)`, `create(data)`, `delete(id)` |
|
|
73
|
+
| `client.music_on_holds` | `all(filters)` |
|
|
74
|
+
| `client.call_reports` | `all(filters)` |
|
|
75
|
+
| `client.voicemail_inboxes` | `all(filters)` |
|
|
76
|
+
| `client.recordings` | `call(cdr_id, record_id, query)`, `download_call(cdr_id, record_id, path, query)`, `voicemail(id, context, mailbox, query)`, `download_voicemail(id, context, mailbox, path, query)` |
|
|
77
|
+
| `client.webhooks` | `get()`, `configure(settings)`, `route(event, settings)`, `configure_legacy(settings)` |
|
|
78
|
+
| `client.calls` | `otp(phone, options, **kwargs)`, `click_to_call(source, destination, options, **kwargs)`, `secure_call(source, destination, options, **kwargs)` |
|
|
79
|
+
|
|
80
|
+
The client preserves API JSON responses as Python dictionaries or lists, without guessing about response schemas. HTTP 204 and empty responses return `{}`. Optional list filters are passed as documented, including `client_ref`.
|
|
81
|
+
|
|
82
|
+
### Call recordings and voicemail audio
|
|
83
|
+
|
|
84
|
+
Use **streaming** downloads for large files; the destination **must not already exist**, and its parent folder must already exist:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from pathlib import Path
|
|
88
|
+
from voipano import VoipanoClient
|
|
89
|
+
|
|
90
|
+
client = VoipanoClient()
|
|
91
|
+
recording = client.recordings.download_call(
|
|
92
|
+
"cdr-id", "call-details-record-id", Path("private/audio/call.wav")
|
|
93
|
+
)
|
|
94
|
+
voicemail = client.recordings.download_voicemail(
|
|
95
|
+
"vm-id", "default", "1001", Path("private/audio/message.wav")
|
|
96
|
+
)
|
|
97
|
+
client.close()
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The binary `.call()` and `.voicemail()` methods return `bytes` and read the whole recording into memory; use them only for small files. Downloaded audio may contain personal information: store it outside a public/static directory, apply access controls, and follow applicable retention rules.
|
|
101
|
+
|
|
102
|
+
**Known collection ambiguity:** the example uses different `cdr_id` (path) and `call_details_record_id` (query) identifiers but describes them as the same ID. The SDK requires both parameters until the actual API contract is confirmed.
|
|
103
|
+
|
|
104
|
+
### Outgoing webhook configuration
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
client.webhooks.configure({
|
|
108
|
+
"endpoint_url": "https://your-domain.example/webhooks/voipano",
|
|
109
|
+
"secret": "your-webhook-secret",
|
|
110
|
+
"is_active": True,
|
|
111
|
+
})
|
|
112
|
+
client.webhooks.route("missed_call", {
|
|
113
|
+
"endpoint_url": "https://your-domain.example/webhooks/missed-call",
|
|
114
|
+
"is_active": True,
|
|
115
|
+
})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Supported event names: `ringing`, `hangup`, `missed_call`, `call_details_record`. POST `configure_legacy` exists for the documented compatibility alias; prefer PUT `configure` for new integrations.
|
|
119
|
+
|
|
120
|
+
### Incoming webhook verification: secure by default
|
|
121
|
+
|
|
122
|
+
**Do not accept incoming events without verification.** The supplied Postman collection does not specify the signature header, signing algorithm, canonical payload, or replay-defense procedure. `WebhookReceiver` rejects all requests by default. Only supply a custom `WebhookVerifier` after validating the true protocol against the server implementation. There is intentionally **no web server route, hardcoded HMAC algorithm, or accept-all mode**.
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
from voipano import WebhookReceiver, WebhookVerificationError
|
|
126
|
+
|
|
127
|
+
receiver = WebhookReceiver() # rejects all incoming requests until configured
|
|
128
|
+
# receiver.receive(raw_request_body, request_headers) -> raises WebhookVerificationError
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Errors and reliability
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
from voipano import ValidationError, VoipanoClient
|
|
135
|
+
|
|
136
|
+
try:
|
|
137
|
+
VoipanoClient().contacts.create({"primary_number": "09120000000"})
|
|
138
|
+
except ValidationError as error:
|
|
139
|
+
print(error.status_code, error.request_id, error.errors)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `ValidationError` (422), `RateLimitError` (429), and `ServerError` (5xx) derive from `ApiError`. Transport errors (`TransportError`) and invalid response formats (`UnexpectedResponseError`) are separate.
|
|
143
|
+
|
|
144
|
+
The SDK uses **Bearer authentication**, optional `X-Webservice-Service-Id`, and one UUID `X-Request-Id` per HTTP request. Redirects and automatic retries are disabled. **Never blindly retry OTP or call requests** after timeouts: `client_ref` is described as a tracking value, not a confirmed idempotency key. Do not log secrets or raw audio files.
|
|
145
|
+
|
|
146
|
+
Timeouts can be customized: `VoipanoClient(timeout=30, connect_timeout=10, base_url="https://voipano.com/api/v1/webservice")`. Optional `VOIPANO_BASE_URL` is supported for controlled staging environments. HTTP(S) only; production should use HTTPS.
|
|
147
|
+
|
|
148
|
+
## Testing and release
|
|
149
|
+
|
|
150
|
+
This repository includes offline tests that never start actual calls:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
python -m pip install -e '.[dev]'
|
|
154
|
+
python -m pytest -q
|
|
155
|
+
python -m build
|
|
156
|
+
python -m twine check dist/*
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`.github/workflows/tests.yml` runs tests on Python 3.11–3.15. `.github/workflows/publish.yml` builds, retests, checks metadata, and publishes on `v*` tags using **PyPI Trusted Publishing** (OIDC, no PyPI token stored in GitHub).
|
|
160
|
+
|
|
161
|
+
To enable the initial release:
|
|
162
|
+
|
|
163
|
+
1. Create a GitHub repository (suggested `voipano/python-voipano`) and upload the **contents** of this source repository.
|
|
164
|
+
2. Create a GitHub environment called **`pypi`**, ideally with required reviewers. If the GitHub owner/repository differs from the suggested link, edit the URLs in `pyproject.toml` before releasing.
|
|
165
|
+
3. On [PyPI](https://pypi.org/manage/account/publishing/), configure a **pending Trusted Publisher** for distribution **`voipano`**: GitHub owner `<your-owner>`, repository `<your-repository>`, workflow filename **`publish.yml`**, environment name **`pypi`**. Pending publishers create the PyPI project at first successful publish.
|
|
166
|
+
4. When your GitHub tests pass, create and push tag `v1.0.1` to trigger the release workflow. Do **not** upload `dist/` or API credentials to GitHub.
|
|
167
|
+
|
|
168
|
+
PyPI names are global and can be unavailable or reserved even if search does not find a project; confirm that `voipano` is accepted when registering the Trusted Publisher. A published release's version cannot be overwritten: create a new version/tag for future updates.
|
|
169
|
+
|
|
170
|
+
The Postman collection contains **no example JSON responses** and does not document inbound webhook signatures, rate limits or idempotency guarantees. Automated tests verify request contracts and the SDK's handling of mock responses; they do not establish live API compatibility.
|
|
171
|
+
|
|
172
|
+
## License
|
|
173
|
+
|
|
174
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
The Voipano Python SDK is designed to avoid exposing secrets or invoking duplicate operations through automatic retries. Use TLS, protect API tokens, store recordings privately, and do not log raw audio or credentials.
|
|
4
|
+
|
|
5
|
+
## Reporting a vulnerability
|
|
6
|
+
|
|
7
|
+
Please use your repository's private **Security → Report a vulnerability** mechanism (GitHub Security Advisories), or contact Voipano through its official support channel. Do not disclose exploitable vulnerabilities publicly before coordinating remediation.
|
|
8
|
+
|
|
9
|
+
## Webhook verification
|
|
10
|
+
|
|
11
|
+
The 2026-11-21 Postman collection does not document the signature scheme for incoming webhooks. Therefore the optional receiver **rejects all requests by default**. Do not treat incoming events as authenticated until you have confirmed a verifier with signature and replay protections.
|
|
12
|
+
|
|
13
|
+
## Support
|
|
14
|
+
|
|
15
|
+
This SDK targets Python 3.11+ and follows the actively supported Python versions. Security updates and advisories are handled through GitHub releases.
|