meetstream-sdk 1.0.0__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.
meetstream/__init__.py ADDED
@@ -0,0 +1,154 @@
1
+ """Official MeetStream SDK for Python.
2
+
3
+ Send AI meeting bots into Zoom, Google Meet and Microsoft Teams. Record,
4
+ transcribe, summarize and stream meetings, and run MIA voice agents.
5
+
6
+ from meetstream import MeetStream
7
+
8
+ meetstream = MeetStream() # reads MEETSTREAM_API_KEY
9
+
10
+ bot = meetstream.bots.create({
11
+ "meeting_link": "https://meet.google.com/abc-defg-hij",
12
+ "bot_name": "Notetaker",
13
+ "recording_config": {
14
+ "transcript": {"provider": {"deepgram": {"model": "nova-3", "language": "en"}}}
15
+ },
16
+ })
17
+
18
+ transcript = meetstream.transcripts.wait_for(bot["transcript_id"])
19
+
20
+ Docs: https://docs.meetstream.ai
21
+ """
22
+ from __future__ import annotations
23
+
24
+ from typing import Any, Dict, Optional
25
+
26
+ import httpx
27
+
28
+ from ._client import (
29
+ DEFAULT_BASE_URL,
30
+ AsyncMeetStreamTransport,
31
+ MeetStreamTransport,
32
+ )
33
+ from ._errors import (
34
+ AuthenticationError,
35
+ BadRequestError,
36
+ ConflictError,
37
+ ConnectionError,
38
+ MeetStreamError,
39
+ NotFoundError,
40
+ NotReadyError,
41
+ PermissionError,
42
+ RateLimitError,
43
+ ServerError,
44
+ TimeoutError,
45
+ )
46
+ from .resources import (
47
+ AsyncBots,
48
+ AsyncCalendar,
49
+ AsyncGoogleLogins,
50
+ AsyncMia,
51
+ AsyncStorage,
52
+ AsyncTranscripts,
53
+ AsyncZoom,
54
+ Bots,
55
+ Calendar,
56
+ GoogleLogins,
57
+ Mia,
58
+ Storage,
59
+ Transcripts,
60
+ Zoom,
61
+ )
62
+ from .webhooks import describe_stop, is_terminal, parse_webhook, verify_webhook_signature
63
+
64
+ __version__ = "1.0.0"
65
+
66
+ __all__ = [
67
+ "MeetStream", "AsyncMeetStream", "__version__", "DEFAULT_BASE_URL",
68
+ "MeetStreamError", "ConnectionError", "TimeoutError", "BadRequestError",
69
+ "AuthenticationError", "PermissionError", "NotFoundError", "ConflictError",
70
+ "RateLimitError", "ServerError", "NotReadyError",
71
+ "verify_webhook_signature", "parse_webhook", "is_terminal", "describe_stop",
72
+ ]
73
+
74
+
75
+ class MeetStream:
76
+ """Synchronous MeetStream client.
77
+
78
+ Usable as a context manager, which closes the underlying HTTP connection
79
+ pool on exit.
80
+ """
81
+
82
+ def __init__(
83
+ self,
84
+ api_key: Optional[str] = None,
85
+ *,
86
+ base_url: Optional[str] = None,
87
+ timeout: float = 60.0,
88
+ max_retries: int = 2,
89
+ default_headers: Optional[Dict[str, str]] = None,
90
+ http_client: Optional[httpx.Client] = None,
91
+ ) -> None:
92
+ self.http = MeetStreamTransport(
93
+ api_key,
94
+ base_url=base_url,
95
+ timeout=timeout,
96
+ max_retries=max_retries,
97
+ default_headers=default_headers,
98
+ http_client=http_client,
99
+ )
100
+ self.bots = Bots(self.http)
101
+ self.transcripts = Transcripts(self.http)
102
+ self.calendar = Calendar(self.http)
103
+ self.mia = Mia(self.http)
104
+ self.google_logins = GoogleLogins(self.http)
105
+ self.zoom = Zoom(self.http)
106
+ self.storage = Storage(self.http)
107
+
108
+ def close(self) -> None:
109
+ self.http.close()
110
+
111
+ def __enter__(self) -> "MeetStream":
112
+ return self
113
+
114
+ def __exit__(self, *exc: Any) -> None:
115
+ self.close()
116
+
117
+
118
+ class AsyncMeetStream:
119
+ """Asynchronous MeetStream client. Same surface, awaited."""
120
+
121
+ def __init__(
122
+ self,
123
+ api_key: Optional[str] = None,
124
+ *,
125
+ base_url: Optional[str] = None,
126
+ timeout: float = 60.0,
127
+ max_retries: int = 2,
128
+ default_headers: Optional[Dict[str, str]] = None,
129
+ http_client: Optional[httpx.AsyncClient] = None,
130
+ ) -> None:
131
+ self.http = AsyncMeetStreamTransport(
132
+ api_key,
133
+ base_url=base_url,
134
+ timeout=timeout,
135
+ max_retries=max_retries,
136
+ default_headers=default_headers,
137
+ http_client=http_client,
138
+ )
139
+ self.bots = AsyncBots(self.http)
140
+ self.transcripts = AsyncTranscripts(self.http)
141
+ self.calendar = AsyncCalendar(self.http)
142
+ self.mia = AsyncMia(self.http)
143
+ self.google_logins = AsyncGoogleLogins(self.http)
144
+ self.zoom = AsyncZoom(self.http)
145
+ self.storage = AsyncStorage(self.http)
146
+
147
+ async def aclose(self) -> None:
148
+ await self.http.aclose()
149
+
150
+ async def __aenter__(self) -> "AsyncMeetStream":
151
+ return self
152
+
153
+ async def __aexit__(self, *exc: Any) -> None:
154
+ await self.aclose()
meetstream/_client.py ADDED
@@ -0,0 +1,284 @@
1
+ """HTTP transport for the MeetStream API.
2
+
3
+ Handles auth, retries, timeouts and the two MeetStream status codes that are
4
+ not failures.
5
+
6
+ Note the auth scheme: the REST API uses ``Authorization: Token <key>``. The MCP
7
+ server at mcp.meetstream.ai uses ``Bearer`` instead. They are not
8
+ interchangeable, and sending the wrong one returns 401.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ import random
14
+ import time
15
+ from typing import Any, Dict, Mapping, Optional
16
+
17
+ import httpx
18
+
19
+ from ._errors import ConnectionError as MSConnectionError
20
+ from ._errors import MeetStreamError
21
+ from ._errors import TimeoutError as MSTimeoutError
22
+ from ._errors import error_for_status
23
+
24
+ DEFAULT_BASE_URL = "https://api.meetstream.ai/api/v1"
25
+ RETRYABLE = frozenset({408, 429, 500, 502, 503, 504})
26
+ _USER_AGENT = "meetstream-python"
27
+
28
+
29
+ def _message_from(body: Any, status: int) -> str:
30
+ """Pull out the API's own ``message``, falling back to something useful."""
31
+ if isinstance(body, Mapping):
32
+ for key in ("message", "detail", "error"):
33
+ value = body.get(key)
34
+ if isinstance(value, str) and value:
35
+ return value
36
+ if isinstance(body, str) and body.strip():
37
+ return body.strip()[:500]
38
+ return f"MeetStream API returned HTTP {status}"
39
+
40
+
41
+ def _resolve_key(api_key: Optional[str]) -> str:
42
+ key = api_key or os.environ.get("MEETSTREAM_API_KEY")
43
+ if not key:
44
+ raise MeetStreamError(
45
+ "Missing MeetStream API key. Pass api_key=... or set MEETSTREAM_API_KEY. "
46
+ "Create a key at https://app.meetstream.ai/api-key"
47
+ )
48
+ return key
49
+
50
+
51
+ def _backoff(attempt: int, retry_after: Optional[float]) -> float:
52
+ if retry_after is not None:
53
+ return retry_after
54
+ return (2 ** attempt) * 0.5 + random.random() * 0.25
55
+
56
+
57
+ class BaseTransport:
58
+ """Shared config and response handling for the sync and async clients."""
59
+
60
+ def __init__(
61
+ self,
62
+ api_key: Optional[str] = None,
63
+ *,
64
+ base_url: Optional[str] = None,
65
+ timeout: float = 60.0,
66
+ max_retries: int = 2,
67
+ default_headers: Optional[Dict[str, str]] = None,
68
+ ) -> None:
69
+ self.api_key = _resolve_key(api_key)
70
+ self.base_url = (base_url or os.environ.get("MEETSTREAM_API_URL") or DEFAULT_BASE_URL).rstrip("/")
71
+ self.timeout = timeout
72
+ self.max_retries = max_retries
73
+ self.default_headers = dict(default_headers or {})
74
+
75
+ def _headers(self, idempotency_key: Optional[str], extra: Optional[Mapping[str, str]]) -> Dict[str, str]:
76
+ headers = {
77
+ "Authorization": f"Token {self.api_key}",
78
+ "Accept": "application/json",
79
+ "User-Agent": _USER_AGENT,
80
+ }
81
+ headers.update(self.default_headers)
82
+ if idempotency_key:
83
+ headers["Idempotency-Key"] = idempotency_key
84
+ if extra:
85
+ headers.update(extra)
86
+ return headers
87
+
88
+ def _url(self, path: str) -> str:
89
+ return self.base_url + (path if path.startswith("/") else "/" + path)
90
+
91
+ @staticmethod
92
+ def _parse(response: httpx.Response) -> Any:
93
+ if not response.content:
94
+ return None
95
+ try:
96
+ return response.json()
97
+ except ValueError:
98
+ return response.text
99
+
100
+ def _handle(self, response: httpx.Response) -> Any:
101
+ """Turn a response into a value or an exception.
102
+
103
+ 202 sits inside the 2xx range, so it must be checked *before* the
104
+ success check or "not ready yet" would silently look like success. 507
105
+ is the mirror case: outside 2xx, but an idempotent replay and therefore
106
+ a success.
107
+ """
108
+ parsed = self._parse(response)
109
+ status = response.status_code
110
+
111
+ if status != 202 and (response.is_success or status == 507):
112
+ return parsed
113
+
114
+ retry_after_raw = response.headers.get("retry-after")
115
+ try:
116
+ retry_after = float(retry_after_raw) if retry_after_raw else None
117
+ except ValueError:
118
+ retry_after = None
119
+
120
+ raise error_for_status(
121
+ status,
122
+ _message_from(parsed, status),
123
+ body=parsed,
124
+ request_id=response.headers.get("x-request-id"),
125
+ retry_after=retry_after,
126
+ )
127
+
128
+
129
+ class MeetStreamTransport(BaseTransport):
130
+ """Synchronous transport."""
131
+
132
+ def __init__(self, *args: Any, http_client: Optional[httpx.Client] = None, **kwargs: Any) -> None:
133
+ super().__init__(*args, **kwargs)
134
+ self._client = http_client or httpx.Client(timeout=self.timeout)
135
+ self._owns_client = http_client is None
136
+
137
+ def request(
138
+ self,
139
+ method: str,
140
+ path: str,
141
+ *,
142
+ params: Optional[Dict[str, Any]] = None,
143
+ json: Any = None,
144
+ idempotency_key: Optional[str] = None,
145
+ headers: Optional[Mapping[str, str]] = None,
146
+ timeout: Optional[float] = None,
147
+ max_retries: Optional[int] = None,
148
+ ) -> Any:
149
+ retries = self.max_retries if max_retries is None else max_retries
150
+ clean_params = {k: v for k, v in (params or {}).items() if v is not None}
151
+ last_exc: Optional[MeetStreamError] = None
152
+
153
+ for attempt in range(retries + 1):
154
+ try:
155
+ response = self._client.request(
156
+ method,
157
+ self._url(path),
158
+ params=clean_params or None,
159
+ json=json,
160
+ headers=self._headers(idempotency_key, headers),
161
+ timeout=timeout if timeout is not None else self.timeout,
162
+ )
163
+ except httpx.TimeoutException as exc:
164
+ last_exc = MSTimeoutError(f"Request timed out: {method} {path} ({exc})")
165
+ if attempt == retries:
166
+ raise last_exc from exc
167
+ time.sleep(_backoff(attempt, None))
168
+ continue
169
+ except httpx.HTTPError as exc:
170
+ last_exc = MSConnectionError(f"Could not reach the MeetStream API: {exc}")
171
+ if attempt == retries:
172
+ raise last_exc from exc
173
+ time.sleep(_backoff(attempt, None))
174
+ continue
175
+
176
+ try:
177
+ return self._handle(response)
178
+ except MeetStreamError as exc:
179
+ # 202 is never retried here: the caller decides the polling
180
+ # cadence through the wait_for_* helpers.
181
+ if response.status_code not in RETRYABLE or attempt == retries:
182
+ raise
183
+ last_exc = exc
184
+ time.sleep(_backoff(attempt, getattr(exc, "retry_after", None)))
185
+
186
+ raise last_exc or MeetStreamError("Request failed")
187
+
188
+ def get(self, path: str, **kw: Any) -> Any:
189
+ return self.request("GET", path, **kw)
190
+
191
+ def post(self, path: str, json: Any = None, **kw: Any) -> Any:
192
+ return self.request("POST", path, json=json, **kw)
193
+
194
+ def put(self, path: str, json: Any = None, **kw: Any) -> Any:
195
+ return self.request("PUT", path, json=json, **kw)
196
+
197
+ def patch(self, path: str, json: Any = None, **kw: Any) -> Any:
198
+ return self.request("PATCH", path, json=json, **kw)
199
+
200
+ def delete(self, path: str, **kw: Any) -> Any:
201
+ return self.request("DELETE", path, **kw)
202
+
203
+ def close(self) -> None:
204
+ if self._owns_client:
205
+ self._client.close()
206
+
207
+
208
+ class AsyncMeetStreamTransport(BaseTransport):
209
+ """Asynchronous transport. Mirrors the sync API exactly."""
210
+
211
+ def __init__(self, *args: Any, http_client: Optional[httpx.AsyncClient] = None, **kwargs: Any) -> None:
212
+ super().__init__(*args, **kwargs)
213
+ self._client = http_client or httpx.AsyncClient(timeout=self.timeout)
214
+ self._owns_client = http_client is None
215
+
216
+ async def request(
217
+ self,
218
+ method: str,
219
+ path: str,
220
+ *,
221
+ params: Optional[Dict[str, Any]] = None,
222
+ json: Any = None,
223
+ idempotency_key: Optional[str] = None,
224
+ headers: Optional[Mapping[str, str]] = None,
225
+ timeout: Optional[float] = None,
226
+ max_retries: Optional[int] = None,
227
+ ) -> Any:
228
+ import asyncio
229
+
230
+ retries = self.max_retries if max_retries is None else max_retries
231
+ clean_params = {k: v for k, v in (params or {}).items() if v is not None}
232
+ last_exc: Optional[MeetStreamError] = None
233
+
234
+ for attempt in range(retries + 1):
235
+ try:
236
+ response = await self._client.request(
237
+ method,
238
+ self._url(path),
239
+ params=clean_params or None,
240
+ json=json,
241
+ headers=self._headers(idempotency_key, headers),
242
+ timeout=timeout if timeout is not None else self.timeout,
243
+ )
244
+ except httpx.TimeoutException as exc:
245
+ last_exc = MSTimeoutError(f"Request timed out: {method} {path} ({exc})")
246
+ if attempt == retries:
247
+ raise last_exc from exc
248
+ await asyncio.sleep(_backoff(attempt, None))
249
+ continue
250
+ except httpx.HTTPError as exc:
251
+ last_exc = MSConnectionError(f"Could not reach the MeetStream API: {exc}")
252
+ if attempt == retries:
253
+ raise last_exc from exc
254
+ await asyncio.sleep(_backoff(attempt, None))
255
+ continue
256
+
257
+ try:
258
+ return self._handle(response)
259
+ except MeetStreamError as exc:
260
+ if response.status_code not in RETRYABLE or attempt == retries:
261
+ raise
262
+ last_exc = exc
263
+ await asyncio.sleep(_backoff(attempt, getattr(exc, "retry_after", None)))
264
+
265
+ raise last_exc or MeetStreamError("Request failed")
266
+
267
+ async def get(self, path: str, **kw: Any) -> Any:
268
+ return await self.request("GET", path, **kw)
269
+
270
+ async def post(self, path: str, json: Any = None, **kw: Any) -> Any:
271
+ return await self.request("POST", path, json=json, **kw)
272
+
273
+ async def put(self, path: str, json: Any = None, **kw: Any) -> Any:
274
+ return await self.request("PUT", path, json=json, **kw)
275
+
276
+ async def patch(self, path: str, json: Any = None, **kw: Any) -> Any:
277
+ return await self.request("PATCH", path, json=json, **kw)
278
+
279
+ async def delete(self, path: str, **kw: Any) -> Any:
280
+ return await self.request("DELETE", path, **kw)
281
+
282
+ async def aclose(self) -> None:
283
+ if self._owns_client:
284
+ await self._client.aclose()
meetstream/_errors.py ADDED
@@ -0,0 +1,118 @@
1
+ """Errors raised by the MeetStream SDK.
2
+
3
+ Every MeetStream error response carries a ``message`` field; it becomes
4
+ ``error.message`` and the raw body is kept on ``error.body``.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ from typing import Any, Optional
9
+
10
+ __all__ = [
11
+ "MeetStreamError", "ConnectionError", "TimeoutError", "BadRequestError",
12
+ "AuthenticationError", "PermissionError", "NotFoundError", "ConflictError",
13
+ "RateLimitError", "ServerError", "NotReadyError", "error_for_status",
14
+ ]
15
+
16
+
17
+ class MeetStreamError(Exception):
18
+ """Base class for everything this SDK raises."""
19
+
20
+ def __init__(
21
+ self,
22
+ message: str,
23
+ *,
24
+ status: Optional[int] = None,
25
+ body: Any = None,
26
+ request_id: Optional[str] = None,
27
+ ) -> None:
28
+ super().__init__(message)
29
+ self.message = message
30
+ self.status = status
31
+ self.body = body
32
+ self.request_id = request_id
33
+
34
+ def __str__(self) -> str: # pragma: no cover - trivial
35
+ if self.status is not None:
36
+ return f"[{self.status}] {self.message}"
37
+ return self.message
38
+
39
+
40
+ class ConnectionError(MeetStreamError):
41
+ """The request never reached the API, or the connection failed mid-flight."""
42
+
43
+
44
+ class TimeoutError(MeetStreamError):
45
+ """The request exceeded the configured timeout."""
46
+
47
+
48
+ class BadRequestError(MeetStreamError):
49
+ """400 - the request was malformed. Read ``message``; do not retry unchanged."""
50
+
51
+
52
+ class AuthenticationError(MeetStreamError):
53
+ """401 - no API key was sent. The header is missing entirely."""
54
+
55
+
56
+ class PermissionError(MeetStreamError): # noqa: A001 - deliberately shadows builtin
57
+ """403 - a key was sent but rejected: wrong, revoked, or truncated."""
58
+
59
+
60
+ class NotFoundError(MeetStreamError):
61
+ """404 - unknown bot id, transcript id, or route."""
62
+
63
+
64
+ class ConflictError(MeetStreamError):
65
+ """409 - deduplication conflict: same ``deduplication_key``, different meeting."""
66
+
67
+
68
+ class RateLimitError(MeetStreamError):
69
+ """429 - rate limited. ``retry_after`` is in seconds when the API supplied it."""
70
+
71
+ def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any) -> None:
72
+ super().__init__(message, **kwargs)
73
+ self.retry_after = retry_after
74
+
75
+
76
+ class ServerError(MeetStreamError):
77
+ """5xx - transient server error. Safe to retry with backoff."""
78
+
79
+
80
+ class NotReadyError(MeetStreamError):
81
+ """The resource exists but is not ready yet (HTTP 202).
82
+
83
+ This is **not** a failure. It is normal for transcripts and per-participant
84
+ streams while a bot is still in the meeting or media is still processing.
85
+
86
+ One trap: a bot that used a streaming-only transcription provider returns
87
+ 202 *forever*, because no post-call transcript will ever exist. Always cap
88
+ your polling. The ``wait_for_*`` helpers do this for you.
89
+ """
90
+
91
+
92
+ def error_for_status(
93
+ status: int,
94
+ message: str,
95
+ *,
96
+ body: Any = None,
97
+ request_id: Optional[str] = None,
98
+ retry_after: Optional[float] = None,
99
+ ) -> MeetStreamError:
100
+ """Map an HTTP status onto the right error class."""
101
+ kwargs = {"status": status, "body": body, "request_id": request_id}
102
+ if status == 202:
103
+ return NotReadyError(message, **kwargs)
104
+ if status == 400:
105
+ return BadRequestError(message, **kwargs)
106
+ if status == 401:
107
+ return AuthenticationError(message, **kwargs)
108
+ if status == 403:
109
+ return PermissionError(message, **kwargs)
110
+ if status == 404:
111
+ return NotFoundError(message, **kwargs)
112
+ if status == 409:
113
+ return ConflictError(message, **kwargs)
114
+ if status == 429:
115
+ return RateLimitError(message, retry_after=retry_after, **kwargs)
116
+ if status >= 500:
117
+ return ServerError(message, **kwargs)
118
+ return MeetStreamError(message, **kwargs)
meetstream/py.typed ADDED
File without changes
@@ -0,0 +1,11 @@
1
+ from .bots import AsyncBots, Bots
2
+ from .calendar import AsyncCalendar, Calendar
3
+ from .integrations import AsyncGoogleLogins, AsyncStorage, AsyncZoom, GoogleLogins, Storage, Zoom
4
+ from .mia import AsyncMia, Mia
5
+ from .transcripts import AsyncTranscripts, Transcripts
6
+
7
+ __all__ = [
8
+ "Bots", "AsyncBots", "Transcripts", "AsyncTranscripts", "Calendar", "AsyncCalendar",
9
+ "Mia", "AsyncMia", "GoogleLogins", "AsyncGoogleLogins", "Zoom", "AsyncZoom",
10
+ "Storage", "AsyncStorage",
11
+ ]