voipano 1.0.1__py3-none-any.whl
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/__init__.py +28 -0
- voipano/_http.py +279 -0
- voipano/client.py +102 -0
- voipano/exceptions.py +61 -0
- voipano/py.typed +0 -0
- voipano/resources.py +165 -0
- voipano/webhooks.py +42 -0
- voipano-1.0.1.dist-info/METADATA +205 -0
- voipano-1.0.1.dist-info/RECORD +12 -0
- voipano-1.0.1.dist-info/WHEEL +5 -0
- voipano-1.0.1.dist-info/licenses/LICENSE +21 -0
- voipano-1.0.1.dist-info/top_level.txt +1 -0
voipano/__init__.py
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Official Voipano Public API v1 Python SDK."""
|
|
2
|
+
|
|
3
|
+
from .client import VoipanoClient
|
|
4
|
+
from .exceptions import (
|
|
5
|
+
ApiError,
|
|
6
|
+
AuthenticationError,
|
|
7
|
+
NotFoundError,
|
|
8
|
+
PermissionError,
|
|
9
|
+
RateLimitError,
|
|
10
|
+
ServerError,
|
|
11
|
+
TransportError,
|
|
12
|
+
UnexpectedResponseError,
|
|
13
|
+
ValidationError,
|
|
14
|
+
VoipanoError,
|
|
15
|
+
WebhookVerificationError,
|
|
16
|
+
)
|
|
17
|
+
from .webhooks import RejectAllVerifier, WebhookReceiver, WebhookVerifier
|
|
18
|
+
|
|
19
|
+
__version__ = "1.0.1"
|
|
20
|
+
Voipano = VoipanoClient
|
|
21
|
+
|
|
22
|
+
__all__ = [
|
|
23
|
+
"Voipano", "VoipanoClient", "VoipanoError", "ApiError",
|
|
24
|
+
"AuthenticationError", "PermissionError", "NotFoundError",
|
|
25
|
+
"ValidationError", "RateLimitError", "ServerError", "TransportError",
|
|
26
|
+
"UnexpectedResponseError", "WebhookVerificationError", "WebhookVerifier",
|
|
27
|
+
"RejectAllVerifier", "WebhookReceiver",
|
|
28
|
+
]
|
voipano/_http.py
ADDED
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
"""Synchronous HTTP transport for Voipano Public API v1.
|
|
2
|
+
|
|
3
|
+
Requests are never retried and redirects are never followed: write operations
|
|
4
|
+
may start real telephone calls and the API does not document idempotency.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import json
|
|
10
|
+
import math
|
|
11
|
+
import os
|
|
12
|
+
import tempfile
|
|
13
|
+
import uuid
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any, Mapping
|
|
16
|
+
from urllib.parse import quote, urlsplit
|
|
17
|
+
|
|
18
|
+
import requests
|
|
19
|
+
|
|
20
|
+
from .exceptions import (
|
|
21
|
+
ApiError,
|
|
22
|
+
AuthenticationError,
|
|
23
|
+
NotFoundError,
|
|
24
|
+
PermissionError,
|
|
25
|
+
RateLimitError,
|
|
26
|
+
ServerError,
|
|
27
|
+
TransportError,
|
|
28
|
+
UnexpectedResponseError,
|
|
29
|
+
ValidationError,
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
DEFAULT_BASE_URL = "https://voipano.com/api/v1/webservice"
|
|
33
|
+
STATUS_ERRORS: dict[int, type[ApiError]] = {
|
|
34
|
+
401: AuthenticationError,
|
|
35
|
+
403: PermissionError,
|
|
36
|
+
404: NotFoundError,
|
|
37
|
+
422: ValidationError,
|
|
38
|
+
429: RateLimitError,
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _clean_header(value: str, label: str, *, allow_empty: bool = False) -> str:
|
|
43
|
+
if not isinstance(value, str) or (not allow_empty and not value.strip()):
|
|
44
|
+
raise ValueError(f"{label} must be a nonempty string")
|
|
45
|
+
if any(ord(char) < 32 or ord(char) == 127 for char in value):
|
|
46
|
+
raise ValueError(f"{label} contains invalid control characters")
|
|
47
|
+
return value
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _valid_timeout(value: float, label: str) -> float:
|
|
51
|
+
if isinstance(value, bool) or not isinstance(value, (float, int)) or not math.isfinite(value) or value <= 0:
|
|
52
|
+
raise ValueError(f"{label} must be a positive finite number")
|
|
53
|
+
return float(value)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _validate_url(base_url: str) -> str:
|
|
57
|
+
if not isinstance(base_url, str) or any(ord(c) <= 32 or ord(c) == 127 for c in base_url):
|
|
58
|
+
raise ValueError("base_url must be a valid absolute HTTP(S) URL")
|
|
59
|
+
try:
|
|
60
|
+
parts = urlsplit(base_url)
|
|
61
|
+
valid = (
|
|
62
|
+
parts.scheme.lower() in ("http", "https")
|
|
63
|
+
and bool(parts.hostname)
|
|
64
|
+
and not parts.username
|
|
65
|
+
and not parts.password
|
|
66
|
+
and not parts.query
|
|
67
|
+
and not parts.fragment
|
|
68
|
+
)
|
|
69
|
+
_ = parts.port # Reject invalid port numbers
|
|
70
|
+
except ValueError as exc:
|
|
71
|
+
raise ValueError("base_url must be a valid absolute HTTP(S) URL") from exc
|
|
72
|
+
if not valid:
|
|
73
|
+
raise ValueError("base_url must be a valid absolute HTTP(S) URL without query, fragment or credentials")
|
|
74
|
+
return base_url.rstrip("/")
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _path_segment(value: str | int) -> str:
|
|
78
|
+
if isinstance(value, bool) or not isinstance(value, (str, int)):
|
|
79
|
+
raise ValueError("Resource ID must be a string or integer")
|
|
80
|
+
part = str(value)
|
|
81
|
+
if not part.strip() or part in (".", "..") or any(ord(c) < 32 or ord(c) == 127 for c in part):
|
|
82
|
+
raise ValueError("Invalid resource ID")
|
|
83
|
+
return quote(part, safe="")
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _query(params: Mapping[str, Any] | None) -> dict[str, Any]:
|
|
87
|
+
return {key: value for key, value in (params or {}).items() if value is not None and value != ""}
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _error(response: requests.Response, body: bytes | None = None) -> ApiError:
|
|
91
|
+
payload: Any = {}
|
|
92
|
+
try:
|
|
93
|
+
payload = json.loads(body if body is not None else response.content)
|
|
94
|
+
except (ValueError, UnicodeError):
|
|
95
|
+
pass
|
|
96
|
+
if not isinstance(payload, dict):
|
|
97
|
+
payload = {}
|
|
98
|
+
message = payload.get("message") or payload.get("error")
|
|
99
|
+
if not isinstance(message, str):
|
|
100
|
+
message = f"Voipano API returned HTTP {response.status_code}."
|
|
101
|
+
errors = payload.get("errors", {})
|
|
102
|
+
error_type = STATUS_ERRORS.get(response.status_code)
|
|
103
|
+
if error_type is None:
|
|
104
|
+
error_type = ServerError if response.status_code >= 500 else ApiError
|
|
105
|
+
return error_type(message, response.status_code, response.headers.get("X-Request-Id"), errors)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _ensure_binary(response: requests.Response) -> None:
|
|
109
|
+
content_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
|
|
110
|
+
if content_type in ("application/json", "text/html") or content_type.endswith("+json"):
|
|
111
|
+
raise UnexpectedResponseError(f"Expected audio/binary response, got {content_type}")
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
class Transport:
|
|
115
|
+
"""Low-level client. Scoped copies have isolated configuration and sessions."""
|
|
116
|
+
|
|
117
|
+
def __init__(
|
|
118
|
+
self,
|
|
119
|
+
token: str | None = None,
|
|
120
|
+
*,
|
|
121
|
+
base_url: str | None = None,
|
|
122
|
+
service_id: str | None = None,
|
|
123
|
+
timeout: float = 30,
|
|
124
|
+
connect_timeout: float = 10,
|
|
125
|
+
request_id: str | None = None,
|
|
126
|
+
session: requests.Session | None = None,
|
|
127
|
+
) -> None:
|
|
128
|
+
self.token = _clean_header(
|
|
129
|
+
token if token is not None else os.getenv("VOIPANO_API_TOKEN", ""),
|
|
130
|
+
"token",
|
|
131
|
+
)
|
|
132
|
+
self.base_url = _validate_url(base_url if base_url is not None else os.getenv("VOIPANO_BASE_URL", DEFAULT_BASE_URL))
|
|
133
|
+
self.service_id = _clean_header(
|
|
134
|
+
service_id if service_id is not None else os.getenv("VOIPANO_SERVICE_ID", ""),
|
|
135
|
+
"service_id", allow_empty=True,
|
|
136
|
+
)
|
|
137
|
+
self.timeout = _valid_timeout(timeout, "timeout")
|
|
138
|
+
self.connect_timeout = _valid_timeout(connect_timeout, "connect_timeout")
|
|
139
|
+
self.request_id = _clean_header(request_id, "request_id") if request_id is not None else None
|
|
140
|
+
self._own_session = session is None
|
|
141
|
+
self._session = session if session is not None else requests.Session()
|
|
142
|
+
|
|
143
|
+
def copy(self, **changes: Any) -> Transport:
|
|
144
|
+
data: dict[str, Any] = {
|
|
145
|
+
"token": self.token,
|
|
146
|
+
"base_url": self.base_url,
|
|
147
|
+
"service_id": self.service_id,
|
|
148
|
+
"timeout": self.timeout,
|
|
149
|
+
"connect_timeout": self.connect_timeout,
|
|
150
|
+
"request_id": self.request_id,
|
|
151
|
+
}
|
|
152
|
+
data.update(changes)
|
|
153
|
+
# For injected test/custom sessions, retain the injection; default clients
|
|
154
|
+
# get new sessions to prevent accidental cross-tenant session mutation.
|
|
155
|
+
if not self._own_session:
|
|
156
|
+
data["session"] = self._session
|
|
157
|
+
return Transport(**data)
|
|
158
|
+
|
|
159
|
+
def close(self) -> None:
|
|
160
|
+
if self._own_session:
|
|
161
|
+
self._session.close()
|
|
162
|
+
|
|
163
|
+
def _send(
|
|
164
|
+
self,
|
|
165
|
+
method: str,
|
|
166
|
+
path: str,
|
|
167
|
+
params: Mapping[str, Any] | None = None,
|
|
168
|
+
*,
|
|
169
|
+
binary: bool = False,
|
|
170
|
+
) -> requests.Response:
|
|
171
|
+
method = method.upper()
|
|
172
|
+
if method not in {"GET", "POST", "PUT", "PATCH", "DELETE"}:
|
|
173
|
+
raise ValueError("Unsupported HTTP method")
|
|
174
|
+
if not path.startswith("/") or path.startswith("//") or "?" in path or "#" in path:
|
|
175
|
+
raise ValueError("path must begin with one slash and must not contain a query or fragment")
|
|
176
|
+
headers = {
|
|
177
|
+
"Authorization": f"Bearer {self.token}",
|
|
178
|
+
"Accept": "*/*" if binary else "application/json",
|
|
179
|
+
"X-Request-Id": self.request_id or str(uuid.uuid4()),
|
|
180
|
+
"User-Agent": "voipano-python/1.0.1",
|
|
181
|
+
}
|
|
182
|
+
if self.service_id.strip():
|
|
183
|
+
headers["X-Webservice-Service-Id"] = self.service_id
|
|
184
|
+
kwargs: dict[str, Any] = {
|
|
185
|
+
"headers": headers,
|
|
186
|
+
"timeout": (self.connect_timeout, self.timeout),
|
|
187
|
+
"allow_redirects": False,
|
|
188
|
+
"stream": binary,
|
|
189
|
+
}
|
|
190
|
+
if method == "GET":
|
|
191
|
+
kwargs["params"] = _query(params)
|
|
192
|
+
elif method != "DELETE":
|
|
193
|
+
headers["Content-Type"] = "application/json"
|
|
194
|
+
kwargs["json"] = dict(params or {})
|
|
195
|
+
try:
|
|
196
|
+
return self._session.request(method, self.base_url + path, **kwargs)
|
|
197
|
+
except requests.RequestException as exc:
|
|
198
|
+
raise TransportError("Could not connect to Voipano API. The outcome of a write may be unknown.") from exc
|
|
199
|
+
|
|
200
|
+
@staticmethod
|
|
201
|
+
def _raise_status(response: requests.Response, *, streamed: bool = False) -> None:
|
|
202
|
+
if response.status_code >= 300:
|
|
203
|
+
if streamed:
|
|
204
|
+
# Streamed errors: only inspect the first 8192 bytes.
|
|
205
|
+
chunks = []
|
|
206
|
+
size = 0
|
|
207
|
+
for chunk in response.iter_content(chunk_size=2048):
|
|
208
|
+
chunks.append(chunk[: max(0, 8192 - size)])
|
|
209
|
+
size += len(chunk)
|
|
210
|
+
if size >= 8192:
|
|
211
|
+
break
|
|
212
|
+
raise _error(response, b"".join(chunks))
|
|
213
|
+
raise _error(response)
|
|
214
|
+
|
|
215
|
+
def request(self, method: str, path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any] | list[Any]:
|
|
216
|
+
response = self._send(method, path, params)
|
|
217
|
+
try:
|
|
218
|
+
self._raise_status(response)
|
|
219
|
+
if response.status_code == 204 or not response.content.strip():
|
|
220
|
+
return {}
|
|
221
|
+
try:
|
|
222
|
+
data = response.json()
|
|
223
|
+
except ValueError as exc:
|
|
224
|
+
raise UnexpectedResponseError("Expected JSON response") from exc
|
|
225
|
+
if not isinstance(data, (dict, list)):
|
|
226
|
+
raise UnexpectedResponseError("Expected JSON object or array")
|
|
227
|
+
return data
|
|
228
|
+
finally:
|
|
229
|
+
response.close()
|
|
230
|
+
|
|
231
|
+
def binary(self, path: str, query: Mapping[str, Any] | None = None) -> bytes:
|
|
232
|
+
response = self._send("GET", path, query, binary=True)
|
|
233
|
+
try:
|
|
234
|
+
self._raise_status(response, streamed=True)
|
|
235
|
+
_ensure_binary(response)
|
|
236
|
+
return response.content
|
|
237
|
+
except requests.RequestException as exc:
|
|
238
|
+
raise TransportError("Recording response could not be read") from exc
|
|
239
|
+
finally:
|
|
240
|
+
response.close()
|
|
241
|
+
|
|
242
|
+
def download_to(self, path: str, destination: str | os.PathLike[str], query: Mapping[str, Any] | None = None) -> Path:
|
|
243
|
+
target = Path(destination)
|
|
244
|
+
if target.exists() or target.is_symlink():
|
|
245
|
+
raise FileExistsError(f"Refusing to overwrite existing file: {target}")
|
|
246
|
+
if not target.parent.is_dir():
|
|
247
|
+
raise ValueError("Destination parent directory must exist")
|
|
248
|
+
response = self._send("GET", path, query, binary=True)
|
|
249
|
+
temp_path: Path | None = None
|
|
250
|
+
try:
|
|
251
|
+
self._raise_status(response, streamed=True)
|
|
252
|
+
_ensure_binary(response)
|
|
253
|
+
fd, name = tempfile.mkstemp(prefix=".voipano-", dir=target.parent)
|
|
254
|
+
temp_path = Path(name)
|
|
255
|
+
with os.fdopen(fd, "wb") as tmp:
|
|
256
|
+
for chunk in response.iter_content(chunk_size=65536):
|
|
257
|
+
if chunk:
|
|
258
|
+
tmp.write(chunk)
|
|
259
|
+
target_created = False
|
|
260
|
+
try:
|
|
261
|
+
with target.open("xb") as dst:
|
|
262
|
+
target_created = True
|
|
263
|
+
with temp_path.open("rb") as src:
|
|
264
|
+
while True:
|
|
265
|
+
chunk = src.read(65536)
|
|
266
|
+
if not chunk:
|
|
267
|
+
break
|
|
268
|
+
dst.write(chunk)
|
|
269
|
+
except Exception:
|
|
270
|
+
if target_created:
|
|
271
|
+
target.unlink(missing_ok=True)
|
|
272
|
+
raise
|
|
273
|
+
return target
|
|
274
|
+
except requests.RequestException as exc:
|
|
275
|
+
raise TransportError("Recording download failed") from exc
|
|
276
|
+
finally:
|
|
277
|
+
response.close()
|
|
278
|
+
if temp_path is not None:
|
|
279
|
+
temp_path.unlink(missing_ok=True)
|
voipano/client.py
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Public, typed, synchronous client for the Voipano API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any, Mapping
|
|
6
|
+
|
|
7
|
+
import requests
|
|
8
|
+
|
|
9
|
+
from ._http import Transport
|
|
10
|
+
from .resources import (
|
|
11
|
+
CallReports, Calls, ContactGroups, Contacts, MusicOnHolds,
|
|
12
|
+
Recordings, Services, VoicemailInboxes, Webhooks,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class VoipanoClient:
|
|
17
|
+
"""Official Voipano Public API v1 client.
|
|
18
|
+
|
|
19
|
+
``VoipanoClient()`` reads VOIPANO_API_TOKEN and optionally VOIPANO_SERVICE_ID
|
|
20
|
+
and VOIPANO_BASE_URL from the process environment.
|
|
21
|
+
|
|
22
|
+
Scoped copies from ``with_token``, ``for_service`` or ``with_request_id``
|
|
23
|
+
do not modify the original client.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
def __init__(
|
|
27
|
+
self,
|
|
28
|
+
token: str | None = None,
|
|
29
|
+
*,
|
|
30
|
+
base_url: str | None = None,
|
|
31
|
+
service_id: str | None = None,
|
|
32
|
+
timeout: float = 30,
|
|
33
|
+
connect_timeout: float = 10,
|
|
34
|
+
session: requests.Session | None = None,
|
|
35
|
+
_transport: Transport | None = None,
|
|
36
|
+
) -> None:
|
|
37
|
+
self._transport = _transport or Transport(
|
|
38
|
+
token,
|
|
39
|
+
base_url=base_url,
|
|
40
|
+
service_id=service_id,
|
|
41
|
+
timeout=timeout,
|
|
42
|
+
connect_timeout=connect_timeout,
|
|
43
|
+
session=session,
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
@property
|
|
47
|
+
def services(self) -> Services:
|
|
48
|
+
return Services(self._transport)
|
|
49
|
+
|
|
50
|
+
@property
|
|
51
|
+
def contacts(self) -> Contacts:
|
|
52
|
+
return Contacts(self._transport)
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def contact_groups(self) -> ContactGroups:
|
|
56
|
+
return ContactGroups(self._transport)
|
|
57
|
+
|
|
58
|
+
@property
|
|
59
|
+
def music_on_holds(self) -> MusicOnHolds:
|
|
60
|
+
return MusicOnHolds(self._transport)
|
|
61
|
+
|
|
62
|
+
@property
|
|
63
|
+
def call_reports(self) -> CallReports:
|
|
64
|
+
return CallReports(self._transport)
|
|
65
|
+
|
|
66
|
+
@property
|
|
67
|
+
def voicemail_inboxes(self) -> VoicemailInboxes:
|
|
68
|
+
return VoicemailInboxes(self._transport)
|
|
69
|
+
|
|
70
|
+
@property
|
|
71
|
+
def recordings(self) -> Recordings:
|
|
72
|
+
return Recordings(self._transport)
|
|
73
|
+
|
|
74
|
+
@property
|
|
75
|
+
def webhooks(self) -> Webhooks:
|
|
76
|
+
return Webhooks(self._transport)
|
|
77
|
+
|
|
78
|
+
@property
|
|
79
|
+
def calls(self) -> Calls:
|
|
80
|
+
return Calls(self._transport)
|
|
81
|
+
|
|
82
|
+
def with_token(self, token: str) -> VoipanoClient:
|
|
83
|
+
return VoipanoClient(_transport=self._transport.copy(token=token))
|
|
84
|
+
|
|
85
|
+
def for_service(self, service_id: str) -> VoipanoClient:
|
|
86
|
+
return VoipanoClient(_transport=self._transport.copy(service_id=service_id))
|
|
87
|
+
|
|
88
|
+
def with_request_id(self, request_id: str) -> VoipanoClient:
|
|
89
|
+
return VoipanoClient(_transport=self._transport.copy(request_id=request_id))
|
|
90
|
+
|
|
91
|
+
def request(self, method: str, path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any] | list[Any]:
|
|
92
|
+
"""Advanced access to a documented JSON endpoint."""
|
|
93
|
+
return self._transport.request(method, path, params)
|
|
94
|
+
|
|
95
|
+
def close(self) -> None:
|
|
96
|
+
self._transport.close()
|
|
97
|
+
|
|
98
|
+
def __enter__(self) -> VoipanoClient:
|
|
99
|
+
return self
|
|
100
|
+
|
|
101
|
+
def __exit__(self, *_args: Any) -> None:
|
|
102
|
+
self.close()
|
voipano/exceptions.py
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""Public exceptions raised by the Voipano client."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class VoipanoError(Exception):
|
|
9
|
+
"""Base class for SDK errors."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class ApiError(VoipanoError):
|
|
13
|
+
"""An HTTP error response from Voipano (including unexpected redirects)."""
|
|
14
|
+
|
|
15
|
+
def __init__(
|
|
16
|
+
self,
|
|
17
|
+
message: str,
|
|
18
|
+
status_code: int,
|
|
19
|
+
request_id: str | None = None,
|
|
20
|
+
errors: Any = None,
|
|
21
|
+
) -> None:
|
|
22
|
+
super().__init__(message)
|
|
23
|
+
self.status_code = status_code
|
|
24
|
+
self.request_id = request_id
|
|
25
|
+
self.errors = errors if errors is not None else {}
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class AuthenticationError(ApiError):
|
|
29
|
+
"""HTTP 401."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class PermissionError(ApiError):
|
|
33
|
+
"""HTTP 403; unrelated to built-in PermissionError."""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class NotFoundError(ApiError):
|
|
37
|
+
"""HTTP 404."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class ValidationError(ApiError):
|
|
41
|
+
"""HTTP 422."""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class RateLimitError(ApiError):
|
|
45
|
+
"""HTTP 429."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class ServerError(ApiError):
|
|
49
|
+
"""HTTP 5xx."""
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class TransportError(VoipanoError):
|
|
53
|
+
"""Network, TLS or timeout failure (request outcome may be unknown)."""
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class UnexpectedResponseError(VoipanoError):
|
|
57
|
+
"""The server did not return the expected JSON or binary response."""
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class WebhookVerificationError(VoipanoError):
|
|
61
|
+
"""Incoming webhook rejected; signature scheme is not yet documented."""
|
voipano/py.typed
ADDED
|
File without changes
|
voipano/resources.py
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""Explicit resource wrappers for every endpoint in the 2026-11-21 collection."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from os import PathLike
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any, Mapping, Sequence
|
|
8
|
+
|
|
9
|
+
from ._http import Transport, _path_segment
|
|
10
|
+
|
|
11
|
+
Json = dict[str, Any] | list[Any]
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _required(value: str | int, label: str) -> str:
|
|
15
|
+
if isinstance(value, bool) or not isinstance(value, (str, int)) or not str(value).strip():
|
|
16
|
+
raise ValueError(f"{label} must not be empty")
|
|
17
|
+
return str(value)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Resource:
|
|
21
|
+
def __init__(self, transport: Transport) -> None:
|
|
22
|
+
self._transport = transport
|
|
23
|
+
|
|
24
|
+
def _get(self, path: str, filters: Mapping[str, Any] | None = None) -> Json:
|
|
25
|
+
return self._transport.request("GET", path, filters)
|
|
26
|
+
|
|
27
|
+
def _write(self, method: str, path: str, data: Mapping[str, Any]) -> Json:
|
|
28
|
+
return self._transport.request(method, path, data)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class Services(Resource):
|
|
32
|
+
def all(self) -> Json:
|
|
33
|
+
return self._get("/services")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class Contacts(Resource):
|
|
37
|
+
def all(self, filters: Mapping[str, Any] | None = None) -> Json:
|
|
38
|
+
return self._get("/contacts", filters)
|
|
39
|
+
|
|
40
|
+
def find(self, contact_id: str | int) -> Json:
|
|
41
|
+
return self._get(f"/contacts/{_path_segment(contact_id)}")
|
|
42
|
+
|
|
43
|
+
def create(self, data: Mapping[str, Any]) -> Json:
|
|
44
|
+
return self._write("POST", "/contacts", data)
|
|
45
|
+
|
|
46
|
+
def update(self, contact_id: str | int, data: Mapping[str, Any]) -> Json:
|
|
47
|
+
"""PATCH, modifying only provided fields (empty arrays may clear values)."""
|
|
48
|
+
return self._write("PATCH", f"/contacts/{_path_segment(contact_id)}", data)
|
|
49
|
+
|
|
50
|
+
def update_put(self, contact_id: str | int, data: Mapping[str, Any]) -> Json:
|
|
51
|
+
"""PUT, documented as a partial update alias, not full replacement."""
|
|
52
|
+
return self._write("PUT", f"/contacts/{_path_segment(contact_id)}", data)
|
|
53
|
+
|
|
54
|
+
def delete(self, contact_id: str | int) -> Json:
|
|
55
|
+
return self._transport.request("DELETE", f"/contacts/{_path_segment(contact_id)}")
|
|
56
|
+
|
|
57
|
+
def bulk_import(self, contacts: Sequence[Mapping[str, Any]], options: Mapping[str, Any] | None = None) -> Json:
|
|
58
|
+
"""Import 1..3000 contacts; performed as one request without retries."""
|
|
59
|
+
if isinstance(contacts, (str, bytes)) or not isinstance(contacts, (list, tuple)) or not 1 <= len(contacts) <= 3000:
|
|
60
|
+
raise ValueError("contacts must be a list/tuple of 1 to 3000 objects")
|
|
61
|
+
if any(not isinstance(entry, Mapping) for entry in contacts):
|
|
62
|
+
raise ValueError("each contact must be a mapping")
|
|
63
|
+
data = dict(options or {})
|
|
64
|
+
data["contacts"] = list(contacts)
|
|
65
|
+
return self._write("POST", "/contacts/bulk-import", data)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class ContactGroups(Resource):
|
|
69
|
+
def all(self, filters: Mapping[str, Any] | None = None) -> Json:
|
|
70
|
+
return self._get("/contact-groups", filters)
|
|
71
|
+
|
|
72
|
+
def create(self, data: Mapping[str, Any]) -> Json:
|
|
73
|
+
return self._write("POST", "/contact-groups", data)
|
|
74
|
+
|
|
75
|
+
def delete(self, group_id: str | int) -> Json:
|
|
76
|
+
return self._transport.request("DELETE", f"/contact-groups/{_path_segment(group_id)}")
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class MusicOnHolds(Resource):
|
|
80
|
+
def all(self, filters: Mapping[str, Any] | None = None) -> Json:
|
|
81
|
+
return self._get("/music-on-holds", filters)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class CallReports(Resource):
|
|
85
|
+
def all(self, filters: Mapping[str, Any] | None = None) -> Json:
|
|
86
|
+
return self._get("/call-reports", filters)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class VoicemailInboxes(Resource):
|
|
90
|
+
def all(self, filters: Mapping[str, Any] | None = None) -> Json:
|
|
91
|
+
return self._get("/voicemail-inboxes", filters)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class Recordings(Resource):
|
|
95
|
+
"""Binary read/download. Always supply both call-recording identifiers."""
|
|
96
|
+
|
|
97
|
+
def call(self, cdr_id: str | int, call_details_record_id: str | int, query: Mapping[str, Any] | None = None) -> bytes:
|
|
98
|
+
return self._transport.binary(
|
|
99
|
+
f"/call-recordings/{_path_segment(cdr_id)}",
|
|
100
|
+
{**dict(query or {}), "call_details_record_id": _required(call_details_record_id, "call_details_record_id")},
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
def download_call(
|
|
104
|
+
self, cdr_id: str | int, call_details_record_id: str | int,
|
|
105
|
+
destination: str | PathLike[str], query: Mapping[str, Any] | None = None,
|
|
106
|
+
) -> Path:
|
|
107
|
+
return self._transport.download_to(
|
|
108
|
+
f"/call-recordings/{_path_segment(cdr_id)}", destination,
|
|
109
|
+
{**dict(query or {}), "call_details_record_id": _required(call_details_record_id, "call_details_record_id")},
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
def voicemail(self, unique_id: str | int, context: str, mailbox: str, query: Mapping[str, Any] | None = None) -> bytes:
|
|
113
|
+
return self._transport.binary(
|
|
114
|
+
f"/voicemail-recordings/{_path_segment(unique_id)}",
|
|
115
|
+
{**dict(query or {}), "context": _required(context, "context"), "mailbox": _required(mailbox, "mailbox")},
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
def download_voicemail(
|
|
119
|
+
self, unique_id: str | int, context: str, mailbox: str,
|
|
120
|
+
destination: str | PathLike[str], query: Mapping[str, Any] | None = None,
|
|
121
|
+
) -> Path:
|
|
122
|
+
return self._transport.download_to(
|
|
123
|
+
f"/voicemail-recordings/{_path_segment(unique_id)}", destination,
|
|
124
|
+
{**dict(query or {}), "context": _required(context, "context"), "mailbox": _required(mailbox, "mailbox")},
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
class Webhooks(Resource):
|
|
129
|
+
EVENTS = frozenset({"ringing", "hangup", "missed_call", "call_details_record"})
|
|
130
|
+
|
|
131
|
+
def get(self) -> Json:
|
|
132
|
+
return self._get("/call-events-webhook")
|
|
133
|
+
|
|
134
|
+
def configure(self, settings: Mapping[str, Any]) -> Json:
|
|
135
|
+
return self._write("PUT", "/call-events-webhook", settings)
|
|
136
|
+
|
|
137
|
+
def route(self, event: str, settings: Mapping[str, Any]) -> Json:
|
|
138
|
+
if event not in self.EVENTS:
|
|
139
|
+
raise ValueError("Unsupported call event")
|
|
140
|
+
return self._write("PUT", "/call-events-webhook", {**settings, "event": event})
|
|
141
|
+
|
|
142
|
+
def configure_legacy(self, settings: Mapping[str, Any]) -> Json:
|
|
143
|
+
"""Legacy POST alias for PUT configure()."""
|
|
144
|
+
return self._write("POST", "/call-events-webhook", settings)
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
class Calls(Resource):
|
|
148
|
+
"""These methods initiate REAL calls; the SDK never retries them."""
|
|
149
|
+
|
|
150
|
+
def otp(self, phone_number: str, options: Mapping[str, Any] | None = None, **kwargs: Any) -> Json:
|
|
151
|
+
return self._write("POST", "/call-otp", {**dict(options or {}), **kwargs, "phone_number": _required(phone_number, "phone_number")})
|
|
152
|
+
|
|
153
|
+
def click_to_call(
|
|
154
|
+
self, source: str, destination: str, options: Mapping[str, Any] | None = None, **kwargs: Any,
|
|
155
|
+
) -> Json:
|
|
156
|
+
return self._write("POST", "/click-to-call", {
|
|
157
|
+
**dict(options or {}), **kwargs, "call_source": _required(source, "call_source"), "call_destination": _required(destination, "call_destination"),
|
|
158
|
+
})
|
|
159
|
+
|
|
160
|
+
def secure_call(
|
|
161
|
+
self, source: str, destination: str, options: Mapping[str, Any] | None = None, **kwargs: Any,
|
|
162
|
+
) -> Json:
|
|
163
|
+
return self._write("POST", "/secure-call", {
|
|
164
|
+
**dict(options or {}), **kwargs, "call_source": _required(source, "call_source"), "call_destination": _required(destination, "call_destination"),
|
|
165
|
+
})
|
voipano/webhooks.py
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Framework-independent incoming webhook interface (fail closed by default).
|
|
2
|
+
|
|
3
|
+
The Postman collection does not document signing headers, canonical payload,
|
|
4
|
+
secret derivation, timestamp tolerance or replay protection. This module must
|
|
5
|
+
not invent a signature scheme; users should supply a verifier once confirmed.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
from typing import Any, Mapping, Protocol
|
|
12
|
+
|
|
13
|
+
from .exceptions import WebhookVerificationError
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class WebhookVerifier(Protocol):
|
|
17
|
+
def verify(self, body: bytes, headers: Mapping[str, str]) -> bool:
|
|
18
|
+
"""Validate signature AND replay controls against Voipano's real protocol."""
|
|
19
|
+
...
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class RejectAllVerifier:
|
|
23
|
+
def verify(self, body: bytes, headers: Mapping[str, str]) -> bool:
|
|
24
|
+
return False
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class WebhookReceiver:
|
|
28
|
+
def __init__(self, verifier: WebhookVerifier | None = None) -> None:
|
|
29
|
+
self.verifier = verifier if verifier is not None else RejectAllVerifier()
|
|
30
|
+
|
|
31
|
+
def receive(self, body: bytes, headers: Mapping[str, str]) -> dict[str, Any]:
|
|
32
|
+
if not isinstance(body, bytes):
|
|
33
|
+
raise TypeError("Webhook body must be raw bytes")
|
|
34
|
+
if not self.verifier.verify(body, headers):
|
|
35
|
+
raise WebhookVerificationError("Webhook verification failed")
|
|
36
|
+
try:
|
|
37
|
+
payload = json.loads(body)
|
|
38
|
+
except (ValueError, UnicodeError) as exc:
|
|
39
|
+
raise WebhookVerificationError("Invalid webhook JSON") from exc
|
|
40
|
+
if not isinstance(payload, dict):
|
|
41
|
+
raise WebhookVerificationError("Webhook JSON must be an object")
|
|
42
|
+
return payload
|
|
@@ -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,12 @@
|
|
|
1
|
+
voipano/__init__.py,sha256=gGMRNgDnPjJTHE6--IPE13cnnleWvkuwCW9VSt3UmJ0,801
|
|
2
|
+
voipano/_http.py,sha256=jNJCdMo9KGsZtw2_7_3HJPaspiugcgQoyMDVOFj4QlY,11123
|
|
3
|
+
voipano/client.py,sha256=gMMOuRvXqCW7MsVb2-y8gtrey8qRGOX4jEtihycbVHc,2984
|
|
4
|
+
voipano/exceptions.py,sha256=PBY5mq0dUMkPrcW4fnNa20InEyN754V8SkBZ0QqE05U,1354
|
|
5
|
+
voipano/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
+
voipano/resources.py,sha256=ZsfPdEoNodXJD60wTNoSa-T7GnNzpvDScB3SBWur7yU,7100
|
|
7
|
+
voipano/webhooks.py,sha256=IZ4CJs-mFdSrZUXvZWdgKLF7uPWlyODzl-X08YMhZzI,1591
|
|
8
|
+
voipano-1.0.1.dist-info/licenses/LICENSE,sha256=975g8uF6ixEpHIqFBJsNcDkwlW9c9piZBHe5EyYPTZU,1077
|
|
9
|
+
voipano-1.0.1.dist-info/METADATA,sha256=nNzUUyiCFkRGO33TzeKdcYvRza1PFiLMV-FUPn7RkPM,10400
|
|
10
|
+
voipano-1.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
11
|
+
voipano-1.0.1.dist-info/top_level.txt,sha256=IiJhLxVW0njWkBgW8HsH1l5ULzf0QgvNIloy1miKT-A,8
|
|
12
|
+
voipano-1.0.1.dist-info/RECORD,,
|
|
@@ -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 @@
|
|
|
1
|
+
voipano
|