vocalstack 1.0.0a0__tar.gz → 1.0.0a1__tar.gz

vocalstack-1.0.0a1/.gitignore

@@ -0,0 +1,8 @@
+# Packaging: hatchling reads the nearest .gitignore when it builds the sdist.
+.venv/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.env
+.env.*

vocalstack-1.0.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VocalStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: vocalstack
-Version: 1.0.0a0
+Version: 1.0.0a1
 Summary: VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming.
 Project-URL: Homepage, https://vocalstack.com
-License: MIT
+License-Expression: MIT
+License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.7
@@ -32,11 +33,13 @@ async def main():
 asyncio.run(main())
 ```
 
-<!-- sdk-docs: generated by `make sdk-docs` from the guides; edit those, not this -->
+<!-- sdk-docs: generated from the VocalStack API guides; edits here are overwritten -->
 
 ## Install
 
-Not on PyPI yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+```sh
+pip install vocalstack
+```
 
 ## Guides
 
@@ -48,6 +51,7 @@ Not on PyPI yet. The API serves its own builds to every account: [https://api.vo
 - [Go live](https://github.com/vocalstack/python-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
 - [Listen](https://github.com/vocalstack/python-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
 - [Live translation and spoken translations](https://github.com/vocalstack/python-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Connect an app with one click](https://github.com/vocalstack/python-sdk/blob/main/docs/connect-an-app.md): Let the people who use your app connect their VocalStack account with one Authenticate click — OAuth 2.0 authorization code with PKCE, where the access token is an API key — instead of pasting a key.
 - [Errors, retries and limits](https://github.com/vocalstack/python-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
 
 <!-- /sdk-docs -->
@@ -113,5 +117,5 @@ async with VocalStack(api_key=key) as vs:
 `status`, `retryable`, `details` (quota numbers, code suggestions), `headers`
 and `retry_after`.
 
-Verified against the language-agnostic conformance suite (`make conformance`)
-and against a running API (`make sdk-e2e`). For agents: `SKILL.md`.
+Verified against a language-agnostic conformance suite shared by every
+VocalStack SDK and against a running API. For agents: `SKILL.md`.

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/README.md

@@ -20,11 +20,13 @@ async def main():
 asyncio.run(main())
 ```
 
-<!-- sdk-docs: generated by `make sdk-docs` from the guides; edit those, not this -->
+<!-- sdk-docs: generated from the VocalStack API guides; edits here are overwritten -->
 
 ## Install
 
-Not on PyPI yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+```sh
+pip install vocalstack
+```
 
 ## Guides
 
@@ -36,6 +38,7 @@ Not on PyPI yet. The API serves its own builds to every account: [https://api.vo
 - [Go live](https://github.com/vocalstack/python-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
 - [Listen](https://github.com/vocalstack/python-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
 - [Live translation and spoken translations](https://github.com/vocalstack/python-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Connect an app with one click](https://github.com/vocalstack/python-sdk/blob/main/docs/connect-an-app.md): Let the people who use your app connect their VocalStack account with one Authenticate click — OAuth 2.0 authorization code with PKCE, where the access token is an API key — instead of pasting a key.
 - [Errors, retries and limits](https://github.com/vocalstack/python-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
 
 <!-- /sdk-docs -->
@@ -101,5 +104,5 @@ async with VocalStack(api_key=key) as vs:
 `status`, `retryable`, `details` (quota numbers, code suggestions), `headers`
 and `retry_after`.
 
-Verified against the language-agnostic conformance suite (`make conformance`)
-and against a running API (`make sdk-e2e`). For agents: `SKILL.md`.
+Verified against a language-agnostic conformance suite shared by every
+VocalStack SDK and against a running API. For agents: `SKILL.md`.

{vocalstack-1.0.0a0/skills/vocalstack → vocalstack-1.0.0a1}/SKILL.md

@@ -31,16 +31,6 @@ python3 -m venv .venv && . .venv/bin/activate   # system Pythons refuse a bare p
 pip install vocalstack                           # Python 3.10 or newer
 ```
 
-Before the package is published, any account installs
-the private build its environment serves: the API reference's Install section
-(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
-give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
-Or install it from a local checkout of the repository:
-
-```sh
-pip install -e /absolute/path/to/transcribe/sdks/python
-```
-
 Live transcription (program 4) also needs `ffmpeg` on PATH.
 
 Speaker numbers start at 0. A speaker of `-1` means speaker labels were off
@@ -57,8 +47,7 @@ for that transcription, so print the text without a speaker.
 - Scopes: `read` (read transcripts, search, export), `write` and
   `recordings:publish` (create transcriptions, stream live audio), or `*`.
 - Base URL: `https://api.vocalstack.com` (the default). Override it with
-  `VOCALSTACK_BASE_URL`: `http://127.0.0.1:8090` for a local server,
-  `https://api.e2e.vocalstack.com` for e2e.
+  `VOCALSTACK_BASE_URL` (for example, a local or staging server).
 
 Every program below opens the client the same way, inside `async def main()`
 run with `asyncio.run(main())` (a `None` base URL means the default):
@@ -203,8 +192,9 @@ its `Retry-After`, twice by default (`max_retries` on the client).
 |---|---|---|
 | 401 | `invalid_token`, `key_expired`, `key_revoked` | Check `VOCALSTACK_API_KEY`. Use the replacement key, or create a new one. |
 | 403 | `forbidden` | Usually a missing scope: the message names it, and `e.headers["www-authenticate"]` lists the scopes the route needs. A suspended key or account gets `suspended`. |
-| 402 | `insufficient_credit` | The account's credit is out. `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
-| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True, waive_withdrawal=True)` opens one; a signed-in person's token, never an API key). |
+| 403 | `terms_acceptance_required` | The account has not accepted the current Terms of Service and Privacy Policy: someone signs in to the Dashboard and accepts them (an organisation's keys work once an owner or admin has). Not retryable until then. |
+| 402 | `insufficient_credit` | The account's credit is out, or does not cover the transcription: every transcription is billed at least the plan's minimum (`rates.minimumSeconds`, 5 minutes). `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
+| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True)` opens one; a signed-in person's token, never an API key). |
 | 402 | `quota_exceeded` | The plan's transcriptions-at-once limit is reached. `details`: `metric` (`concurrent_transcriptions`), `limit`, `used`, `plan`, `topUpUrl`. |
 | 429 | `rate_limited` | Retried automatically; if it still fails, wait `e.retry_after` seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
 | 503 | `unavailable` | The service is waking (its database was asleep). Retried automatically after `Retry-After` (2 s) on calls that are safe to repeat: GET, HEAD, DELETE, or any call with `idempotency_key=`. A create without a key is not retried: retry it yourself, with an `idempotency_key` so it cannot run twice. A realtime socket refused this way raises `unavailable`; a bare 503 there is `capacity_exceeded`. |

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/pyproject.toml

@@ -1,13 +1,14 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling>=1.27"]
 build-backend = "hatchling.build"
 
 [project]
 name = "vocalstack"
-version = "1.0.0a0"
+version = "1.0.0a1"
 description = "VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming."
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.10"
 dependencies = [
     "httpx>=0.27",
@@ -28,4 +29,4 @@ packages = ["src/vocalstack"]
 
 # An explicit list: nothing else from the repository goes into the sdist.
 [tool.hatch.build.targets.sdist]
-only-include = ["src/vocalstack", "README.md", "SKILL.md", "skills", "pyproject.toml"]
+only-include = ["src/vocalstack", "LICENSE", "README.md", "SKILL.md", "skills", "pyproject.toml"]

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1/skills/vocalstack}/SKILL.md

@@ -31,16 +31,6 @@ python3 -m venv .venv && . .venv/bin/activate   # system Pythons refuse a bare p
 pip install vocalstack                           # Python 3.10 or newer
 ```
 
-Before the package is published, any account installs
-the private build its environment serves: the API reference's Install section
-(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
-give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
-Or install it from a local checkout of the repository:
-
-```sh
-pip install -e /absolute/path/to/transcribe/sdks/python
-```
-
 Live transcription (program 4) also needs `ffmpeg` on PATH.
 
 Speaker numbers start at 0. A speaker of `-1` means speaker labels were off
@@ -57,8 +47,7 @@ for that transcription, so print the text without a speaker.
 - Scopes: `read` (read transcripts, search, export), `write` and
   `recordings:publish` (create transcriptions, stream live audio), or `*`.
 - Base URL: `https://api.vocalstack.com` (the default). Override it with
-  `VOCALSTACK_BASE_URL`: `http://127.0.0.1:8090` for a local server,
-  `https://api.e2e.vocalstack.com` for e2e.
+  `VOCALSTACK_BASE_URL` (for example, a local or staging server).
 
 Every program below opens the client the same way, inside `async def main()`
 run with `asyncio.run(main())` (a `None` base URL means the default):
@@ -203,8 +192,9 @@ its `Retry-After`, twice by default (`max_retries` on the client).
 |---|---|---|
 | 401 | `invalid_token`, `key_expired`, `key_revoked` | Check `VOCALSTACK_API_KEY`. Use the replacement key, or create a new one. |
 | 403 | `forbidden` | Usually a missing scope: the message names it, and `e.headers["www-authenticate"]` lists the scopes the route needs. A suspended key or account gets `suspended`. |
-| 402 | `insufficient_credit` | The account's credit is out. `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
-| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True, waive_withdrawal=True)` opens one; a signed-in person's token, never an API key). |
+| 403 | `terms_acceptance_required` | The account has not accepted the current Terms of Service and Privacy Policy: someone signs in to the Dashboard and accepts them (an organisation's keys work once an owner or admin has). Not retryable until then. |
+| 402 | `insufficient_credit` | The account's credit is out, or does not cover the transcription: every transcription is billed at least the plan's minimum (`rates.minimumSeconds`, 5 minutes). `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
+| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True)` opens one; a signed-in person's token, never an API key). |
 | 402 | `quota_exceeded` | The plan's transcriptions-at-once limit is reached. `details`: `metric` (`concurrent_transcriptions`), `limit`, `used`, `plan`, `topUpUrl`. |
 | 429 | `rate_limited` | Retried automatically; if it still fails, wait `e.retry_after` seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
 | 503 | `unavailable` | The service is waking (its database was asleep). Retried automatically after `Retry-After` (2 s) on calls that are safe to repeat: GET, HEAD, DELETE, or any call with `idempotency_key=`. A create without a key is not retried: retry it yourself, with an `idempotency_key` so it cannot run twice. A realtime socket refused this way raises `unavailable`; a bare 503 there is `capacity_exceeded`. |

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/src/vocalstack/__init__.py

@@ -30,7 +30,7 @@ from .errors import VocalStackError
 from .realtime import RealtimeTranscript
 from .realtime import RealtimeSession, pace_realtime
 
-__version__ = "1.0.0a0"
+__version__ = "1.0.0a1"
 
 __all__ = [
     "DEFAULT_BASE_URL",

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/src/vocalstack/_http.py

@@ -8,7 +8,7 @@ from typing import Any, Callable, Dict, Mapping, Optional, Union
 
 import httpx
 
-from .errors import from_envelope
+from .errors import from_envelope, from_oauth
 
 DEFAULT_BASE_URL = "https://api.vocalstack.com"
 
@@ -103,6 +103,8 @@ class Transport:
         headers: Optional[Mapping[str, str]] = None,
         idempotency_key: Optional[str] = None,
         anonymous: bool = False,
+        no_retry: bool = False,
+        oauth_errors: bool = False,
     ) -> httpx.Response:
         h: Dict[str, str] = {"accept": "application/json"}
         if headers:
@@ -135,8 +137,8 @@ class Transport:
                 body = resp.json()
             except (json.JSONDecodeError, ValueError):
                 pass
-            err = from_envelope(body, resp.status_code, resp.headers)
-            if retries(resp.status_code, err.code, method, idempotency_key) and attempt < self.max_retries:
+            err = (from_oauth if oauth_errors else from_envelope)(body, resp.status_code, resp.headers)
+            if not no_retry and retries(resp.status_code, err.code, method, idempotency_key) and attempt < self.max_retries:
                 wait = err.retry_after
                 if wait is None and err.code == "unavailable":
                     wait = UNAVAILABLE_WAIT_S

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/src/vocalstack/_models.py

@@ -14,7 +14,7 @@ class _Base(BaseModel):
 
 Access = Literal["public", "private"]
 
-ErrorCode = Literal["invalid_audio", "invalid_options", "invalid_token", "capacity_exceeded", "slow_consumer", "engine_unavailable", "internal", "session_expired", "forbidden", "broadcast_archived", "not_found", "conflict", "invalid_state", "password_required", "rate_limited", "preview_pending", "language_unavailable", "suspended", "key_expired", "key_revoked", "key_from_browser", "insufficient_credit", "payment_method_required", "payment_method_in_use", "billing_details_required", "promo_code_invalid", "auto_top_up_off", "range_too_long", "quota_exceeded", "idempotency_key_reused", "method_not_allowed", "payload_too_large", "unsupported_media_type", "invalid_body", "timeout", "unavailable"]
+ErrorCode = Literal["invalid_audio", "invalid_options", "invalid_token", "capacity_exceeded", "slow_consumer", "engine_unavailable", "internal", "session_expired", "forbidden", "broadcast_archived", "not_found", "conflict", "invalid_state", "password_required", "rate_limited", "preview_pending", "language_unavailable", "suspended", "key_expired", "key_revoked", "key_from_browser", "insufficient_credit", "usage_cap_reached", "payment_method_required", "terms_acceptance_required", "payment_method_in_use", "billing_details_required", "promo_code_invalid", "auto_top_up_off", "range_too_long", "quota_exceeded", "idempotency_key_reused", "method_not_allowed", "payload_too_large", "unsupported_media_type", "invalid_body", "timeout", "unavailable"]
 
 AudioEncoding = Literal["pcm_f32le"]
 
@@ -46,7 +46,9 @@ IngestState = Literal["connecting", "streaming", "reconnecting", "stopped", "fai
 
 InputKind = Literal["live", "file", "url", "stream"]
 
-JobState = Literal["queued", "fetching", "transcribing", "done", "failed", "cropping"]
+QueueReason = Literal["concurrency"]
+
+JobState = Literal["queued", "fetching", "transcribing", "done", "failed", "cropping", "stopped"]
 
 LinkKind = Literal["live", "file", "unknown"]
 
@@ -63,6 +65,11 @@ SentenceStatus = Literal["open", "closed", "dropped"]
 VoiceStatusState = Literal["preparing", "unavailable"]
 
 
+class AccountClosing(_Base):
+    at: str
+    unspent_paid_credit_refunded: bool = Field(alias="unspentPaidCreditRefunded")
+
+
 class Actor(_Base):
     api_key_id: Optional[str] = Field(default=None, alias="apiKeyId")
     display_name: Optional[str] = Field(default=None, alias="displayName")
@@ -77,7 +84,6 @@ class WordAlt(_Base):
 class Word(_Base):
     alts: Optional[List["WordAlt"]] = None
     end: float
-    llm: Optional[bool] = None
     prob: Optional[float] = None
     recognized: Optional[str] = None
     script: Optional[bool] = None
@@ -166,6 +172,7 @@ class MoneyRange(_Base):
 class AutoTopUpChoices(_Base):
     amount_range: "MoneyRange" = Field(alias="amountRange")
     amounts: List[float]
+    auto_topup_max_per_day: int = Field(alias="autoTopupMaxPerDay")
     threshold_range: "MoneyRange" = Field(alias="thresholdRange")
     thresholds: List[float]
 
@@ -178,8 +185,23 @@ class AutoTopUpSettings(_Base):
     threshold: Optional[float] = None
 
 
+class SettingLowering(_Base):
+    """A lowering of a billing setting that changes the account's terms (the
+days data is kept after a downgrade, the auto top-up daily limit),
+told with at least 30 days' notice (docs/billing-price-changes.md §6)."""
+
+    after_date: Optional[str] = Field(default=None, alias="afterDate")
+    applies_at: str = Field(alias="appliesAt")
+    refund_deadline: str = Field(alias="refundDeadline")
+    refund_window_open: bool = Field(alias="refundWindowOpen")
+    renewal_on: Optional[str] = Field(default=None, alias="renewalOn")
+    to: int
+
+
 class AutoTopUpView(_Base):
     amount: Optional[float] = None
+    auto_topup_max_per_day: int = Field(alias="autoTopupMaxPerDay")
+    auto_topup_max_per_day_lowering: Optional["SettingLowering"] = Field(default=None, alias="autoTopupMaxPerDayLowering")
     available: bool
     enabled: bool
     last: Optional["AutoTopUpAttempt"] = None
@@ -207,6 +229,13 @@ class CardView(_Base):
     last4: str
 
 
+class DowngradeKeepDays(_Base):
+    """The account's days data is kept after a downgrade (Terms §14)."""
+
+    days: int
+    lowering: Optional["SettingLowering"] = None
+
+
 class Limits2(_Base):
     """The limits of a version.  `null` is unlimited."""
 
@@ -244,16 +273,32 @@ class MonthlyCreditView(_Base):
     used: float
 
 
+class PriceChange(_Base):
+    from_: float = Field(alias="from")
+    interval: str
+    to: float
+
+
 class Rates(_Base):
-    """The rates of a version, in dollars per hour."""
+    """The rate card of a version: dollars per hour, and the least a
+transcription is billed."""
 
     file_per_hour: float = Field(alias="filePerHour")
     live_per_hour: float = Field(alias="livePerHour")
+    minimum_seconds: int = Field(alias="minimumSeconds")
 
 
 class PendingChange(_Base):
+    after_date: Optional[str] = Field(default=None, alias="afterDate")
     applies_at: str = Field(alias="appliesAt")
+    below_zero_limit_changes: bool = Field(alias="belowZeroLimitChanges")
+    cancel_before: Optional[str] = Field(default=None, alias="cancelBefore")
+    changes: str
+    price: Optional["PriceChange"] = None
     rates: "Rates"
+    refund_deadline: Optional[str] = Field(default=None, alias="refundDeadline")
+    refund_window_open: bool = Field(alias="refundWindowOpen")
+    renewal_on: Optional[str] = Field(default=None, alias="renewalOn")
 
 
 class PendingPayment(_Base):
@@ -278,37 +323,61 @@ class PlanRef(_Base):
 class NextPayment(_Base):
     amount: float
     at: str
+    cancel_before: str = Field(alias="cancelBefore")
 
 
 class PendingInterval(_Base):
-    applies_at: str = Field(alias="appliesAt")
+    applies_at: Optional[str] = Field(default=None, alias="appliesAt")
+    cancel_before: Optional[str] = Field(default=None, alias="cancelBefore")
     interval: str
 
 
+class ScheduledEnd(_Base):
+    at: str
+    reason: str
+    return_plan: Optional[str] = Field(default=None, alias="returnPlan")
+    unused_period_refunded: bool = Field(alias="unusedPeriodRefunded")
+
+
+class SwitchPrices(_Base):
+    month: Optional[float] = None
+    year: Optional[float] = None
+
+
 class SubscriptionView(_Base):
     cancel_at_period_end: bool = Field(alias="cancelAtPeriodEnd")
+    cancel_reason: Optional[str] = Field(default=None, alias="cancelReason")
     current_period_end: Optional[str] = Field(default=None, alias="currentPeriodEnd")
     current_period_start: Optional[str] = Field(default=None, alias="currentPeriodStart")
     interval: str
     next_payment: Optional["NextPayment"] = Field(default=None, alias="nextPayment")
     past_due_since: Optional[str] = Field(default=None, alias="pastDueSince")
     pending_interval: Optional["PendingInterval"] = Field(default=None, alias="pendingInterval")
+    return_plan: Optional[str] = Field(default=None, alias="returnPlan")
+    scheduled_end: Optional["ScheduledEnd"] = Field(default=None, alias="scheduledEnd")
     status: str
+    switch_prices: "SwitchPrices" = Field(alias="switchPrices")
+    yearly_opt_in: bool = Field(alias="yearlyOptIn")
 
 
 class BillingView(_Base):
     """`GET /v1/billing`: the account as the Dashboard shows it.  The plan's
-debt cap (the grace amount) is never on it: `inGrace` says whether
+below-zero limit (its amount) is never on it: `inBelowZero` says whether
 running transcriptions go on below zero, never how far."""
 
+    account_closing: Optional["AccountClosing"] = Field(default=None, alias="accountClosing")
     account_created: Optional[str] = Field(default=None, alias="accountCreated")
     auto_top_up: "AutoTopUpView" = Field(alias="autoTopUp")
     balance: float
+    below_zero_limit_changes_at: Optional[str] = Field(default=None, alias="belowZeroLimitChangesAt")
+    below_zero_limit_on: bool = Field(alias="belowZeroLimitOn")
     can_start: bool = Field(alias="canStart")
+    can_start_live: bool = Field(alias="canStartLive")
     card: Optional["CardView"] = None
+    downgrade_keep_days: "DowngradeKeepDays" = Field(alias="downgradeKeepDays")
     enabled: bool
     has_paid: bool = Field(alias="hasPaid")
-    in_grace: bool = Field(alias="inGrace")
+    in_below_zero: bool = Field(alias="inBelowZero")
     limits: Optional["Limits2"] = None
     limits_usage: Optional["LimitsUsage"] = Field(default=None, alias="limitsUsage")
     low_balance_alert: "LowBalanceAlertView" = Field(alias="lowBalanceAlert")
@@ -321,6 +390,7 @@ running transcriptions go on below zero, never how far."""
     rates: Optional["Rates"] = None
     retention_deadline: Optional[str] = Field(default=None, alias="retentionDeadline")
     start_block: Optional[str] = Field(default=None, alias="startBlock")
+    start_block_live: Optional[str] = Field(default=None, alias="startBlockLive")
     subscription: Optional["SubscriptionView"] = None
     top_up_url: str = Field(alias="topUpUrl")
 
@@ -363,7 +433,6 @@ design's settings sheet): what a recording made in it starts with."""
 
     confidence: Optional["ConfidencePolicy"] = None
     latency_mode: Optional[LatencyMode] = Field(default=None, alias="latencyMode")
-    llm_fix: Optional[bool] = Field(default=None, alias="llmFix")
     max_duration_s: Optional[int] = Field(default=None, alias="maxDurationS")
     max_pause_s: Optional[int] = Field(default=None, alias="maxPauseS")
     silence_auto_pause_s: Optional[int] = Field(default=None, alias="silenceAutoPauseS")
@@ -452,7 +521,10 @@ class RecordingCharge(_Base):
     """A charge on the wire (`GET /v1/billing/charges`)."""
 
     amount: float
+    audio_seconds: float = Field(alias="audioSeconds")
+    covered_seconds: float = Field(alias="coveredSeconds")
     kind: str
+    minimum_applied: bool = Field(alias="minimumApplied")
     name: Optional[str] = None
     opened_at: str = Field(alias="openedAt")
     rate_per_hour: float = Field(alias="ratePerHour")
@@ -583,6 +655,7 @@ class CreateCheckout(_Base):
     kind: str
     plan_id: Optional[str] = Field(default=None, alias="planId")
     promo_code: Optional[str] = Field(default=None, alias="promoCode")
+    # Deprecated and ignored: `acceptTerms` is the one consent.
     waive_withdrawal: Optional[bool] = Field(default=None, alias="waiveWithdrawal")
 
 
@@ -616,7 +689,6 @@ class SettingsPatch(_Base):
 
     confidence: Optional["ConfidencePolicy"] = None
     latency_mode: Optional[LatencyMode] = Field(default=None, alias="latencyMode")
-    llm_fix: Optional[bool] = Field(default=None, alias="llmFix")
     max_duration_s: Optional[int] = Field(default=None, alias="maxDurationS")
     max_pause_s: Optional[int] = Field(default=None, alias="maxPauseS")
     silence_auto_pause_s: Optional[int] = Field(default=None, alias="silenceAutoPauseS")
@@ -715,6 +787,13 @@ class JobProgress(_Base):
     total_s: Optional[float] = Field(default=None, alias="totalS")
 
 
+class JobQueue(_Base):
+    """Why a `queued` job is waiting, and where it stands (`Job.queue`)."""
+
+    position: int
+    reason: QueueReason
+
+
 class KnownVoice(_Base):
     """One voice a realtime session may recognise a speaker as.
 
@@ -773,8 +852,16 @@ class LedgerPage(_Base):
     next_cursor: Optional[str] = Field(default=None, alias="nextCursor")
 
 
+class PageMedia(_Base):
+    """A recording found on a page."""
+
+    title: Optional[str] = None
+    url: str
+
+
 class LinkProbe(_Base):
     kind: LinkKind
+    media: Optional[List["PageMedia"]] = None
     ok: bool
     problem: Optional[str] = None
     source: str
@@ -820,11 +907,13 @@ class Payment(_Base):
 
     amount: float
     at: str
+    business_purchase: bool = Field(alias="businessPurchase")
     description: str
     document: Optional[str] = None
     id: str
     kind: str
     status: str
+    tax_id: Optional[str] = Field(default=None, alias="taxId")
 
 
 class PaymentDocument(_Base):
@@ -865,9 +954,9 @@ class PlanListing(_Base):
     """One plan on the price list: its current version's rates, prices,
 credit, limits and features."""
 
+    below_zero_limit_on: bool = Field(alias="belowZeroLimitOn")
     billed_externally: bool = Field(alias="billedExternally")
     features: Any
-    grace_on_zero: bool = Field(alias="graceOnZero")
     id: str
     kind: str
     limits: "Limits2"
@@ -883,7 +972,7 @@ class PlanList(_Base):
     """`GET /v1/billing/plans`."""
 
     auto_top_up: "AutoTopUpChoices" = Field(alias="autoTopUp")
-    downgrade_grace_days: int = Field(alias="downgradeGraceDays")
+    downgrade_keep_days: int = Field(alias="downgradeKeepDays")
     enabled: bool
     low_balance_alert: "LowBalanceAlertChoices" = Field(alias="lowBalanceAlert")
     plans: List["PlanListing"]
@@ -1140,7 +1229,6 @@ class SessionOptions(_Base):
     identify_voices: Optional[List["KnownVoice"]] = Field(default=None, alias="identifyVoices")
     input: Optional["InputOptions"] = None
     latency_mode: Optional[LatencyMode] = Field(default=None, alias="latencyMode")
-    llm_fix: Optional[bool] = Field(default=None, alias="llmFix")
     sentences: Optional["SentenceOptions"] = None
     speaker_labels: Optional[SpeakerLabels] = Field(default=None, alias="speakerLabels")
     spoken_language: Optional[str] = Field(default=None, alias="spokenLanguage")
@@ -1153,7 +1241,10 @@ class SessionOptions(_Base):
 class SetInterval(_Base):
     """`POST /v1/billing/subscription/interval`."""
 
+    accept_terms: Optional[bool] = Field(default=None, alias="acceptTerms")
+    expected_price: Optional[float] = Field(default=None, alias="expectedPrice")
     interval: str
+    no_new_withdrawal_period_shown: Optional[bool] = Field(default=None, alias="noNewWithdrawalPeriodShown")
 
 
 class ShareLink(_Base):
@@ -1241,6 +1332,7 @@ class TranscriptionJob(_Base):
     peaks: Optional[List[float]] = None
     preview: Optional[bool] = None
     progress: "JobProgress"
+    queue: Optional["JobQueue"] = None
     recording_id: str = Field(alias="recordingId")
     source: Optional["SourceInfo"] = None
     started_at: Optional[str] = Field(default=None, alias="startedAt")
@@ -1314,6 +1406,36 @@ class UploadRecording(_Base):
     url: Optional[str] = None
 
 
+class UsageCharge(_Base):
+    """One charge as the usage report counts it (`GET /v1/billing/usage/charges`):
+a settled `charge` ledger entry, a `charge_correction` (money given
+back: `correction`, a negative amount), or a charge still open at its
+current amount."""
+
+    amount: float
+    correction: bool
+    date: str
+    kind: str
+    name: Optional[str] = None
+    opened_at: str = Field(alias="openedAt")
+    rate_per_hour: float = Field(alias="ratePerHour")
+    realtime_session_id: Optional[str] = Field(default=None, alias="realtimeSessionId")
+    recording_id: Optional[str] = Field(default=None, alias="recordingId")
+    seconds: float
+    source: str
+    state: str
+    transcription_id: Optional[str] = Field(default=None, alias="transcriptionId")
+
+
+class UsageChargePage(_Base):
+    """`GET /v1/billing/usage/charges`."""
+
+    charges: List["UsageCharge"]
+    count: int
+    next_cursor: Optional[str] = Field(default=None, alias="nextCursor")
+    total: float
+
+
 class UsageRow(_Base):
     """One day, source and kind."""
 
@@ -1396,6 +1518,14 @@ class VoiceTrack(_Base):
     word_times: Optional[Dict[str, List[List[float]]]] = Field(default=None, alias="wordTimes")
 
 
+class YearlyOptIn(_Base):
+    """`POST /v1/billing/subscription/yearly-opt-in`."""
+
+    accept_terms: Optional[bool] = Field(default=None, alias="acceptTerms")
+    expected_price: Optional[float] = Field(default=None, alias="expectedPrice")
+    no_new_withdrawal_period_shown: Optional[bool] = Field(default=None, alias="noNewWithdrawalPeriodShown")
+
+
 class CaptureSourceMic(_Base):
     kind: Literal["mic"] = "mic"
 
@@ -1417,7 +1547,6 @@ class Cancel(_Base):
 
 class SessionUpdate(_Base):
     latency_mode: Optional[LatencyMode] = Field(default=None, alias="latencyMode")
-    llm_fix: Optional[bool] = Field(default=None, alias="llmFix")
     speaker_labels: Optional[SpeakerLabels] = Field(default=None, alias="speakerLabels")
     spoken_language: Optional[str] = Field(default=None, alias="spokenLanguage")
     translate: Optional[List[str]] = None

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/src/vocalstack/client.py

@@ -30,6 +30,7 @@ from .realtime import Realtime
 from .resources import (
     Billing,
     Broadcasts,
+    Connect,
     Corrections,
     Events,
     Jobs,
@@ -88,6 +89,7 @@ class VocalStack:
         self.voices = Voices(t)
         self.search = Search(t)
         self.me = Me(t)
+        self.connect = Connect(t)
         self.billing = Billing(t)
         self.languages = Languages(t)
         self.rtmp = Rtmp(t)

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/src/vocalstack/errors.py

@@ -81,3 +81,17 @@ def from_envelope(
     return VocalStackError(
         "internal", f"unexpected error (status {status})", status=status, headers=headers
     )
+
+
+def from_oauth(
+    body: Any, status: Optional[int] = None, headers: Optional[Mapping[str, str]] = None
+) -> VocalStackError:
+    """A token endpoint's ``400 { error, error_description }`` (RFC 6749
+    §5.2) as a :class:`VocalStackError` whose ``code`` is the ``error``
+    (``invalid_request``, ``invalid_grant``, ``unsupported_grant_type``);
+    any other answer goes through the envelope."""
+    if status == 400 and isinstance(body, dict) and isinstance(body.get("error"), str):
+        return VocalStackError(
+            body["error"], body.get("error_description") or body["error"], status=status, headers=headers
+        )
+    return from_envelope(body, status, headers)

{vocalstack-1.0.0a0 → vocalstack-1.0.0a1}/src/vocalstack/resources.py

@@ -373,11 +373,11 @@ class Recordings(_Group):
         return _one(m.SummaryStatus, data)
 
     async def export(
-        self, id: str, format: str, *, lang: Optional[str] = None, share_code: Optional[str] = None
+        self, id: str, format: str, *, lang: Optional[str] = None, share_code: Optional[str] = None, listener_token: Optional[str] = None
     ) -> bytes:
-        """An export file: ``json``, ``srt``, ``xlsx`` or ``pdf``; ``lang`` makes it read in that language."""
+        """An export file: ``json``, ``srt``, ``xlsx`` or ``pdf``; ``lang`` makes it read in that language. ``listener_token``: a broadcast listener's, once the recording has ended."""
         resp = await self._t.raw(
-            "GET", self._path(id, "/export"), headers={"accept": "*/*"}, query={"format": format, "lang": lang, "shareCode": share_code}
+            "GET", self._path(id, "/export"), headers={"accept": "*/*"}, query={"format": format, "lang": lang, "shareCode": share_code, "listenerToken": listener_token}
         )
         return resp.content
 
@@ -472,7 +472,7 @@ class Recordings(_Group):
         return await websockets.connect(url, max_size=None, additional_headers=headers)
 
 
-_TERMINAL = {"done", "failed", "cropping"}
+_TERMINAL = {"done", "failed", "stopped", "cropping"}
 
 
 class Jobs(_Group):
@@ -701,6 +701,31 @@ class Me(_Group):
         return await self._t.json("GET", "/v1/me")
 
 
+class Connect(_Group):
+    """``vs.connect``: one-click Connect, on the app's server."""
+
+    async def token(self, *, code: str, code_verifier: str, redirect_uri: str) -> Dict[str, Any]:
+        """Redeem the ``code`` the dashboard sent to the app's ``redirect_uri``
+        for an API key (OAuth 2.0 authorization code + PKCE): ``code_verifier``
+        is the verifier whose ``BASE64URL(SHA256(verifier))`` was the link's
+        ``code_challenge``, ``redirect_uri`` exactly the link's. Returns the
+        wire's ``{ access_token, token_type, key_id, scope, account }``;
+        ``access_token`` is the key, shown once. No credential is sent, even
+        when the client has one, and the call is never retried: the code
+        works once. A refusal raises :class:`VocalStackError` whose ``code``
+        is OAuth's ``error`` (``invalid_grant``: an unknown, spent or expired
+        code, or a verifier or ``redirect_uri`` that does not match)."""
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "code_verifier": code_verifier,
+            "redirect_uri": redirect_uri,
+        }
+        return await self._t.json(
+            "POST", "/v1/connect/token", data=form, anonymous=True, no_retry=True, oauth_errors=True
+        )
+
+
 class Billing(_Group):
     """``vs.billing``: the account's plan, credit balance and limits, the
     price list, the ledger and the per-recording charges."""
@@ -723,9 +748,9 @@ class Billing(_Group):
 
     async def create_checkout(self, *, idempotency_key: Optional[str] = None, **fields: Any) -> m.CheckoutView:
         """Open a checkout at the payment provider (``kind="topup", amount=``
-        or ``kind="subscribe", plan_id=, interval=``, with ``accept_terms=True``
-        and ``waive_withdrawal=True``); send the customer to ``url``.  A
-        signed-in person only, never an API key."""
+        or ``kind="subscribe", plan_id=, interval=``, with ``accept_terms=True``:
+        the Terms and the request that the purchase start now); send the
+        customer to ``url``.  A signed-in person only, never an API key."""
         body = _body(m.CreateCheckout, fields)
         return _one(m.CheckoutView, await self._t.json("POST", "/v1/billing/checkouts", json_body=body, idempotency_key=idempotency_key))
 
@@ -760,10 +785,19 @@ class Billing(_Group):
         return _one(m.LowBalanceAlertView, await self._t.json("PUT", "/v1/billing/low-balance-alert", json_body=body))
 
     async def set_interval(self, **fields: Any) -> m.SubscriptionView:
-        """Renew ``interval="month"`` or ``"year"`` from the next period."""
+        """Renew ``interval="month"`` or ``"year"`` from the next period, at
+        ``subscription.switch_prices`` (needs ``accept_terms=True`` and
+        ``no_new_withdrawal_period_shown=True``)."""
         body = _body(m.SetInterval, fields)
         return _one(m.SubscriptionView, await self._t.json("POST", "/v1/billing/subscription/interval", json_body=body))
 
+    async def opt_in_yearly(self, **fields: Any) -> m.SubscriptionView:
+        """Keep the subscription by switching to yearly when monthly billing
+        is withdrawn (``subscription.yearly_opt_in``); needs
+        ``accept_terms=True`` and ``no_new_withdrawal_period_shown=True``."""
+        body = _body(m.YearlyOptIn, fields)
+        return _one(m.SubscriptionView, await self._t.json("POST", "/v1/billing/subscription/yearly-opt-in", json_body=body))
+
     async def unset_interval(self) -> m.SubscriptionView:
         """Take back a scheduled interval switch."""
         return _one(m.SubscriptionView, await self._t.json("DELETE", "/v1/billing/subscription/interval"))
@@ -772,6 +806,21 @@ class Billing(_Group):
         """What the account spent per day (``YYYY-MM-DD`` in ``tz``), source and kind."""
         return _one(m.UsageReport, await self._t.json("GET", "/v1/billing/usage", query={"startDate": start_date, "endDate": end_date, "tz": tz}))
 
+    async def usage_charges(
+        self,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        tz: Optional[str] = None,
+        kind: Optional[str] = None,
+        source: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> m.UsageChargePage:
+        """The usage report's charges one by one, newest first; ``kind`` (``file``/``live``) and ``source`` (``dashboard`` or a key id) filter, ``count`` and ``total`` cover every match."""
+        query = {"startDate": start_date, "endDate": end_date, "tz": tz, "kind": kind, "source": source, "cursor": cursor, "limit": limit}
+        return _one(m.UsageChargePage, await self._t.json("GET", "/v1/billing/usage/charges", query=query))
+
     async def payments(self, *, cursor: Optional[str] = None, limit: Optional[int] = None) -> m.PaymentPage:
         """The payments history, newest first."""
         return _one(m.PaymentPage, await self._t.json("GET", "/v1/billing/payments", query={"cursor": cursor, "limit": limit}))

vocalstack-1.0.0a0/.gitignore

@@ -1,9 +0,0 @@
-# Packaging: hatchling copies the nearest .gitignore into the sdist, so this
-# one stands in for the monorepo root's.
-.venv/
-dist/
-build/
-__pycache__/
-*.egg-info/
-.env
-.env.*