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.
@@ -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.
@@ -0,0 +1,7 @@
1
+ include LICENSE
2
+ include README.md README.fa.md CHANGELOG.md SECURITY.md
3
+ recursive-include docs *.json
4
+ recursive-include tests *.py
5
+ recursive-include src/voipano py.typed
6
+ prune .github
7
+ exclude .gitignore
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.
@@ -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.