transcriptdock 0.1.0__tar.gz

transcriptdock-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Check and release Python package
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish the checked version to PyPI
+        type: boolean
+        default: false
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.10', '3.12', '3.14']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: ${{ matrix.python }}
+      - run: PYTHONPATH=src python -W error::ResourceWarning -m unittest discover -s tests -v
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.12'
+      - run: python -m pip install build==1.6.1 twine==7.0.0
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: distributions
+          path: dist/*
+  publish:
+    if: github.event_name == 'workflow_dispatch' && inputs.publish && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086

transcriptdock-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+__pycache__/
+*.pyc
+.venv/

transcriptdock-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Transcript Dock
+
+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.

transcriptdock-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: transcriptdock
+Version: 0.1.0
+Summary: Python client for the Transcript Dock video transcription API
+Project-URL: Homepage, https://www.transcriptdock.com
+Project-URL: Documentation, https://www.transcriptdock.com/docs
+Project-URL: Repository, https://github.com/TranscriptDock/transcriptdock-python
+Project-URL: Issues, https://github.com/TranscriptDock/transcriptdock-python/issues
+Author-email: Transcript Dock <transcriptdock@volods.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,mcp,subtitles,tiktok,transcription,youtube
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Transcript Dock for Python
+
+A synchronous client for the [Transcript Dock API](https://www.transcriptdock.com/docs).
+Python 3.10 or newer. No runtime dependencies.
+
+Install from PyPI:
+
+```sh
+python -m pip install transcriptdock
+```
+
+For local development, use `python -m pip install .` from this directory.
+
+## Submit and read a transcript
+
+Set `TRANSCRIPTDOCK_API_KEY` in your environment. Keep it out of source control.
+
+```python
+import os
+from uuid import uuid4
+from transcriptdock import TranscriptDock, JobTimeoutError
+
+client = TranscriptDock(os.environ["TRANSCRIPTDOCK_API_KEY"])
+print(client.capabilities())
+
+# Generate once per intended operation. Save this key and the returned job ID.
+# Reuse the same key and exact body if a submission's response is lost.
+submission_key = str(uuid4())
+job = client.create_job(
+    {"source": {"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
+     "mode": "captions_only", "max_credits": 1},
+    idempotency_key=submission_key,
+)
+try:
+    job = client.wait_for_job(job["id"], timeout=120)
+except JobTimeoutError as error:
+    print("Still running", error.job)
+else:
+    if job["status"] == "succeeded":
+        transcript = client.get_transcript(job["result_id"])
+        print(transcript)
+        print(client.export_transcript(job["result_id"], "srt"))
+    else:
+        print(job["status"], job.get("error"))
+```
+
+Creating a job can spend credits. This example caps the request at one credit
+and requests captions only. It does not enable AI fallback. Check capabilities
+and your plan before selecting other modes. Never blindly resubmit after a
+network failure: check the job ID or replay the same body with the same
+idempotency key. The client does not retry requests automatically.
+
+## Supported operations
+
+All responses are dictionaries retaining the API's fields. Request bodies use
+the API's exact field names; the server validates supported options. See the
+[OpenAPI definition](https://www.transcriptdock.com/docs/openapi.yaml) for bodies.
+
+* `capabilities()`, `usage()`
+* `create_job(body, idempotency_key=...)`, `get_job(id, wait=0)`,
+  `list_jobs(limit=20, cursor=None)`, `cancel_job(id)`,
+  `retry_job(id, idempotency_key=..., max_credits=None)`, `wait_for_job(id, ...)`
+* `get_transcript(id)`, `export_transcript(id, format="txt")`, `delete_transcript(id)`
+* `create_batch(body, idempotency_key=...)`, `get_batch(id)`
+* `create_video_discovery(body, idempotency_key=...)`, `get_video_discovery(id)`
+* `create_language_discovery(body, idempotency_key=...)`, `get_language_discovery(id)`
+* `create_upload(body)`, `complete_upload(id)`
+* `list_webhook_endpoints()`, `create_webhook_endpoint(body)`, `delete_webhook_endpoint(id)`
+
+`export_transcript` returns a string for JSON, TXT, SRT and VTT, preserving the
+export response. `get_transcript` preserves raw timing fields without converting
+units. `wait_for_job` returns succeeded, failed or cancelled jobs; inspect status
+before using `result_id`. Timeout leaves the job running and exposes its last
+observed response as `JobTimeoutError.job` (or `None` if no poll was possible).
+
+`create_upload` creates an upload slot only. Transfer bytes to the returned signed
+upload URL separately following the API instructions, without sending your
+Transcript Dock API key to the storage host. Then call `complete_upload`.
+Webhook secrets are sensitive; store them privately and verify callback
+signatures in your receiver according to the API documentation.
+
+`request(method, "/v1/...", body=..., query=...)` supports public endpoints added
+later. It rejects absolute URLs, traversal paths and redirects. Custom API
+origins must use HTTPS, except loopback HTTP for local development. The default
+origin is `https://www.transcriptdock.com`; the apex domain redirects.
+
+## Errors
+
+```python
+from transcriptdock import ApiError
+
+try:
+    jobs = client.list_jobs(limit=10)
+except ApiError as error:
+    print(error.code, error.status, error.request_id)
+    # retryable and retry_after_seconds describe the API response.
+    # Decide whether to retry using the operation's idempotency rules.
+```
+
+Transport failures use `NETWORK_ERROR`; malformed responses use `INVALID_RESPONSE`.
+API messages redact bearer tokens. Error responses do not expose raw HTML pages.
+
+## Development and release
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+uv build
+uvx --from twine==7.0.0 twine check dist/*
+```
+
+Build backend versions are pinned in `pyproject.toml`; runtime dependencies are
+empty. Tests use a loopback fixture server and spend no credits.
+
+Before publishing, review artifacts, configure the Transcript Dock publisher on
+PyPI, enable two factor authentication and use a scoped token or trusted
+publishing. The founder handles registry sign-in. Upload only the reviewed
+version with `uv publish`; verify the public package version afterward. Never
+put registry or API credentials in this directory. A local build is not a release.
+
+
+For the first release, add a pending trusted publisher in PyPI with:
+
+| Field | Value |
+| --- | --- |
+| Project name | `transcriptdock` |
+| Owner | `TranscriptDock` |
+| Repository | `transcriptdock-python` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+Then run the GitHub Actions workflow on `main` with `publish` enabled. The
+normal push workflow checks and builds only. Sign-in and initial publisher
+registration are still required; no PyPI account has been created for you.

transcriptdock-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Transcript Dock for Python
+
+A synchronous client for the [Transcript Dock API](https://www.transcriptdock.com/docs).
+Python 3.10 or newer. No runtime dependencies.
+
+Install from PyPI:
+
+```sh
+python -m pip install transcriptdock
+```
+
+For local development, use `python -m pip install .` from this directory.
+
+## Submit and read a transcript
+
+Set `TRANSCRIPTDOCK_API_KEY` in your environment. Keep it out of source control.
+
+```python
+import os
+from uuid import uuid4
+from transcriptdock import TranscriptDock, JobTimeoutError
+
+client = TranscriptDock(os.environ["TRANSCRIPTDOCK_API_KEY"])
+print(client.capabilities())
+
+# Generate once per intended operation. Save this key and the returned job ID.
+# Reuse the same key and exact body if a submission's response is lost.
+submission_key = str(uuid4())
+job = client.create_job(
+    {"source": {"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
+     "mode": "captions_only", "max_credits": 1},
+    idempotency_key=submission_key,
+)
+try:
+    job = client.wait_for_job(job["id"], timeout=120)
+except JobTimeoutError as error:
+    print("Still running", error.job)
+else:
+    if job["status"] == "succeeded":
+        transcript = client.get_transcript(job["result_id"])
+        print(transcript)
+        print(client.export_transcript(job["result_id"], "srt"))
+    else:
+        print(job["status"], job.get("error"))
+```
+
+Creating a job can spend credits. This example caps the request at one credit
+and requests captions only. It does not enable AI fallback. Check capabilities
+and your plan before selecting other modes. Never blindly resubmit after a
+network failure: check the job ID or replay the same body with the same
+idempotency key. The client does not retry requests automatically.
+
+## Supported operations
+
+All responses are dictionaries retaining the API's fields. Request bodies use
+the API's exact field names; the server validates supported options. See the
+[OpenAPI definition](https://www.transcriptdock.com/docs/openapi.yaml) for bodies.
+
+* `capabilities()`, `usage()`
+* `create_job(body, idempotency_key=...)`, `get_job(id, wait=0)`,
+  `list_jobs(limit=20, cursor=None)`, `cancel_job(id)`,
+  `retry_job(id, idempotency_key=..., max_credits=None)`, `wait_for_job(id, ...)`
+* `get_transcript(id)`, `export_transcript(id, format="txt")`, `delete_transcript(id)`
+* `create_batch(body, idempotency_key=...)`, `get_batch(id)`
+* `create_video_discovery(body, idempotency_key=...)`, `get_video_discovery(id)`
+* `create_language_discovery(body, idempotency_key=...)`, `get_language_discovery(id)`
+* `create_upload(body)`, `complete_upload(id)`
+* `list_webhook_endpoints()`, `create_webhook_endpoint(body)`, `delete_webhook_endpoint(id)`
+
+`export_transcript` returns a string for JSON, TXT, SRT and VTT, preserving the
+export response. `get_transcript` preserves raw timing fields without converting
+units. `wait_for_job` returns succeeded, failed or cancelled jobs; inspect status
+before using `result_id`. Timeout leaves the job running and exposes its last
+observed response as `JobTimeoutError.job` (or `None` if no poll was possible).
+
+`create_upload` creates an upload slot only. Transfer bytes to the returned signed
+upload URL separately following the API instructions, without sending your
+Transcript Dock API key to the storage host. Then call `complete_upload`.
+Webhook secrets are sensitive; store them privately and verify callback
+signatures in your receiver according to the API documentation.
+
+`request(method, "/v1/...", body=..., query=...)` supports public endpoints added
+later. It rejects absolute URLs, traversal paths and redirects. Custom API
+origins must use HTTPS, except loopback HTTP for local development. The default
+origin is `https://www.transcriptdock.com`; the apex domain redirects.
+
+## Errors
+
+```python
+from transcriptdock import ApiError
+
+try:
+    jobs = client.list_jobs(limit=10)
+except ApiError as error:
+    print(error.code, error.status, error.request_id)
+    # retryable and retry_after_seconds describe the API response.
+    # Decide whether to retry using the operation's idempotency rules.
+```
+
+Transport failures use `NETWORK_ERROR`; malformed responses use `INVALID_RESPONSE`.
+API messages redact bearer tokens. Error responses do not expose raw HTML pages.
+
+## Development and release
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+uv build
+uvx --from twine==7.0.0 twine check dist/*
+```
+
+Build backend versions are pinned in `pyproject.toml`; runtime dependencies are
+empty. Tests use a loopback fixture server and spend no credits.
+
+Before publishing, review artifacts, configure the Transcript Dock publisher on
+PyPI, enable two factor authentication and use a scoped token or trusted
+publishing. The founder handles registry sign-in. Upload only the reviewed
+version with `uv publish`; verify the public package version afterward. Never
+put registry or API credentials in this directory. A local build is not a release.
+
+
+For the first release, add a pending trusted publisher in PyPI with:
+
+| Field | Value |
+| --- | --- |
+| Project name | `transcriptdock` |
+| Owner | `TranscriptDock` |
+| Repository | `transcriptdock-python` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+Then run the GitHub Actions workflow on `main` with `publish` enabled. The
+normal push workflow checks and builds only. Sign-in and initial publisher
+registration are still required; no PyPI account has been created for you.

transcriptdock-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "transcriptdock"
+version = "0.1.0"
+description = "Python client for the Transcript Dock video transcription API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Transcript Dock", email = "transcriptdock@volods.com"}]
+keywords = ["transcription", "youtube", "tiktok", "subtitles", "api", "mcp"]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://www.transcriptdock.com"
+Documentation = "https://www.transcriptdock.com/docs"
+Repository = "https://github.com/TranscriptDock/transcriptdock-python"
+Issues = "https://github.com/TranscriptDock/transcriptdock-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/transcriptdock"]

transcriptdock-0.1.0/src/transcriptdock/__init__.py

@@ -0,0 +1,221 @@
+"""Transcript Dock public API client. No runtime dependencies."""
+
+import ipaddress
+import json
+import math
+import re
+import time
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, unquote, urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+__version__ = "0.1.0"
+
+
+class ApiError(Exception):
+    """An API or transport failure. Requests are never automatically retried."""
+
+    def __init__(self, code, message, *, status=None, retryable=False,
+                 request_id=None, retry_after_seconds=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.retryable = retryable
+        self.request_id = request_id
+        self.retry_after_seconds = retry_after_seconds
+
+
+class JobTimeoutError(TimeoutError):
+    """Polling expired; job contains the last observed response."""
+
+    def __init__(self, job):
+        super().__init__("The job is still running. Check it again using its ID.")
+        self.job = job
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        # Keep bearer credentials on the configured origin, including for GETs.
+        return None
+
+
+def _positive(value, name):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be a finite positive number.")
+    return value
+
+
+def _id(value):
+    if not isinstance(value, str) or not value or value in (".", ".."):
+        raise ValueError("Provide a nonempty ID.")
+    return quote(value, safe="")
+
+
+class TranscriptDock:
+    """Synchronous API client. Responses retain every field returned by the API."""
+
+    def __init__(self, api_key, *, base_url="https://www.transcriptdock.com", timeout=30):
+        if not isinstance(api_key, str) or not api_key or any(ord(c) < 33 or ord(c) > 126 for c in api_key):
+            raise ValueError("Provide an API key without whitespace or control characters.")
+        parsed = urlsplit(base_url)
+        try:
+            loopback = ipaddress.ip_address(parsed.hostname or "").is_loopback
+        except ValueError:
+            loopback = parsed.hostname == "localhost"
+        if (parsed.scheme != "https" and not (parsed.scheme == "http" and loopback)) or not parsed.hostname:
+            raise ValueError("Use an HTTPS origin, or HTTP on loopback for local development.")
+        if parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in ("", "/"):
+            raise ValueError("The API origin cannot contain credentials, a path, query or fragment.")
+        # Validate the port before any request is made.
+        parsed.port
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self.timeout = _positive(timeout, "timeout")
+        self._opener = build_opener(_NoRedirect())
+
+    def _redact(self, value):
+        value = str(value).replace(self._api_key, "[REDACTED]")
+        return re.sub(r"td_live_[A-Za-z0-9_-]+|Bearer\s+\S+", "[REDACTED]", value, flags=re.I)
+
+    def request(self, method, path, *, body=None, query=None, idempotency_key=None, text=False, timeout=None):
+        """Call a public /v1 endpoint; no redirects or automatic retries."""
+        if not isinstance(method, str):
+            raise ValueError("Provide an HTTP method.")
+        method = method.upper()
+        if method not in ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"):
+            raise ValueError("Provide a supported HTTP method.")
+        if not isinstance(path, str) or not path.startswith("/v1/") or any(c in path for c in ("?", "#", "\\")):
+            raise ValueError("Use a /v1/ path and pass query parameters separately.")
+        if any(part in (".", "..") for part in unquote(path).split("/")):
+            raise ValueError("API paths cannot contain traversal segments.")
+        needs_key = method == "POST" and (path in ("/v1/jobs", "/v1/batches", "/v1/video-discoveries", "/v1/language-discoveries") or path.endswith("/retry"))
+        if needs_key and idempotency_key is None:
+            raise ValueError("Provide an idempotency key for this submission.")
+        headers = {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json",
+                   "User-Agent": f"transcriptdock-python/{__version__}"}
+        if idempotency_key is not None:
+            if not isinstance(idempotency_key, str) or not re.fullmatch(r"[ -~]{8,128}", idempotency_key):
+                raise ValueError("Idempotency keys must contain 8 to 128 printable ASCII characters.")
+            headers["Idempotency-Key"] = idempotency_key
+        data = None
+        if body is not None:
+            data = json.dumps(body, allow_nan=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        url = self._base_url + path
+        if query:
+            url += "?" + urlencode({k: v for k, v in query.items() if v is not None})
+        request = Request(url, data=data, headers=headers, method=method)
+        try:
+            with self._opener.open(request, timeout=self.timeout if timeout is None else _positive(timeout, "timeout")) as response:
+                raw = response.read().decode("utf-8")
+        except HTTPError as exc:
+            try:
+                with exc:
+                    envelope = json.loads(exc.read().decode("utf-8"))
+            except (ValueError, UnicodeError):
+                envelope = {}
+            envelope = envelope if isinstance(envelope, dict) else {}
+            error = envelope.get("error")
+            error = error if isinstance(error, dict) else {}
+            raise ApiError(self._redact(error.get("code", "HTTP_ERROR")),
+                           self._redact(error.get("message") or f"Request failed with status {exc.code}."),
+                           status=exc.code, retryable=bool(error.get("retryable", exc.code == 429 or exc.code >= 500)),
+                           request_id=self._redact(envelope["request_id"]) if envelope.get("request_id") else None,
+                           retry_after_seconds=error.get("retry_after_seconds")) from None
+        except (URLError, TimeoutError, OSError):
+            raise ApiError("NETWORK_ERROR", "Could not reach the API. Check the job before retrying a submission.", retryable=True) from None
+        except UnicodeError:
+            raise ApiError("INVALID_RESPONSE", "The API response is not UTF-8 text.") from None
+        if text:
+            return raw
+        try:
+            result = json.loads(raw)
+        except ValueError:
+            raise ApiError("INVALID_RESPONSE", "The API did not return JSON.") from None
+        if not isinstance(result, dict):
+            raise ApiError("INVALID_RESPONSE", "The API did not return a JSON object.")
+        return result
+
+    def capabilities(self):
+        return self.request("GET", "/v1/capabilities")
+
+    def create_job(self, body, *, idempotency_key):
+        return self.request("POST", "/v1/jobs", body=body, idempotency_key=idempotency_key)
+
+    def get_job(self, job_id, *, wait=0):
+        return self.request("GET", f"/v1/jobs/{_id(job_id)}", query={"wait": wait})
+
+    def list_jobs(self, *, limit=20, cursor=None):
+        return self.request("GET", "/v1/jobs", query={"limit": limit, "cursor": cursor})
+
+    def cancel_job(self, job_id):
+        return self.request("POST", f"/v1/jobs/{_id(job_id)}/cancel")
+
+    def retry_job(self, job_id, *, idempotency_key, max_credits=None):
+        body = {} if max_credits is None else {"max_credits": max_credits}
+        return self.request("POST", f"/v1/jobs/{_id(job_id)}/retry", body=body, idempotency_key=idempotency_key)
+
+    def get_transcript(self, transcript_id):
+        return self.request("GET", f"/v1/transcripts/{_id(transcript_id)}")
+
+    def export_transcript(self, transcript_id, format="txt"):
+        if format not in ("json", "txt", "srt", "vtt"):
+            raise ValueError("Choose json, txt, srt or vtt.")
+        return self.request("GET", f"/v1/transcripts/{_id(transcript_id)}/export", query={"format": format}, text=True)
+
+    def delete_transcript(self, transcript_id):
+        return self.request("DELETE", f"/v1/transcripts/{_id(transcript_id)}")
+
+    def create_batch(self, body, *, idempotency_key):
+        return self.request("POST", "/v1/batches", body=body, idempotency_key=idempotency_key)
+
+    def get_batch(self, batch_id):
+        return self.request("GET", f"/v1/batches/{_id(batch_id)}")
+
+    def create_video_discovery(self, body, *, idempotency_key):
+        return self.request("POST", "/v1/video-discoveries", body=body, idempotency_key=idempotency_key)
+
+    def get_video_discovery(self, discovery_id):
+        return self.request("GET", f"/v1/video-discoveries/{_id(discovery_id)}")
+
+    def create_language_discovery(self, body, *, idempotency_key):
+        return self.request("POST", "/v1/language-discoveries", body=body, idempotency_key=idempotency_key)
+
+    def get_language_discovery(self, discovery_id):
+        return self.request("GET", f"/v1/language-discoveries/{_id(discovery_id)}")
+
+    def create_upload(self, body):
+        """Request an upload URL. Upload file bytes separately without the API key."""
+        return self.request("POST", "/v1/uploads", body=body)
+
+    def complete_upload(self, upload_id):
+        return self.request("POST", f"/v1/uploads/{_id(upload_id)}/complete")
+
+    def usage(self):
+        return self.request("GET", "/v1/usage")
+
+    def list_webhook_endpoints(self):
+        return self.request("GET", "/v1/webhook-endpoints")
+
+    def create_webhook_endpoint(self, body):
+        return self.request("POST", "/v1/webhook-endpoints", body=body)
+
+    def delete_webhook_endpoint(self, endpoint_id):
+        return self.request("DELETE", f"/v1/webhook-endpoints/{_id(endpoint_id)}")
+
+    def wait_for_job(self, job_id, *, timeout=120, poll_interval=3):
+        """Return any terminal job; raise JobTimeoutError with the last job on timeout."""
+        deadline = time.monotonic() + _positive(timeout, "timeout")
+        _positive(poll_interval, "poll_interval")
+        job = None
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise JobTimeoutError(job)
+            job = self.request("GET", f"/v1/jobs/{_id(job_id)}", timeout=min(self.timeout, remaining))
+            if job.get("status") in ("succeeded", "failed", "cancelled"):
+                return job
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise JobTimeoutError(job)
+            time.sleep(min(poll_interval, remaining))

transcriptdock-0.1.0/tests/test_client.py

@@ -0,0 +1,152 @@
+"""Local fixtures only. No production traffic or credits."""
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest.mock import patch
+
+from transcriptdock import ApiError, JobTimeoutError, TranscriptDock
+
+KEY = "td_live_local_fixture_only"
+
+
+class Handler(BaseHTTPRequestHandler):
+    calls = []
+
+    def log_message(self, *args):
+        pass
+
+    def do_GET(self):
+        self.respond()
+
+    def do_POST(self):
+        self.respond()
+
+    def respond(self):
+        body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+        self.calls.append((self.command, self.path, dict(self.headers), body))
+        code, headers = 200, {}
+        payload = {"id": "fixture-job", "status": "succeeded", "future_field": 42}
+        if self.path == "/v1/redirect":
+            code, headers, payload = 302, {"Location": "/v1/leak"}, {}
+        elif self.path == "/v1/rate-limit":
+            code = 429
+            payload = {"error": {"code": "RATE_LIMITED", "message": KEY,
+                                  "retryable": True, "retry_after_seconds": 4}, "request_id": "fixture-request"}
+        elif self.path in ("/v1/budget", "/v1/conflict", "/v1/jobs/not-owned"):
+            code, label = {"/v1/budget": (402, "BUDGET_EXCEEDED"), "/v1/conflict": (409, "IDEMPOTENCY_CONFLICT"), "/v1/jobs/not-owned": (404, "NOT_FOUND")}[self.path]
+            payload = {"error": {"code": label, "message": "Fixture rejection", "retryable": False}}
+        elif self.path == "/v1/gateway":
+            code, payload = 502, b"<html>upstream failed</html>"
+        elif self.path == "/v1/malformed":
+            payload = b"not json"
+        elif self.path.endswith("/export?format=srt"):
+            payload = b"1\n00:00:00,000 --> 00:00:01,000\nFixture\n"
+        raw = payload if isinstance(payload, bytes) else json.dumps(payload).encode()
+        self.send_response(code)
+        for k, v in headers.items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+
+class ClientTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        cls.client = TranscriptDock(KEY, base_url=f"http://127.0.0.1:{cls.server.server_port}")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+        cls.thread.join()
+
+    def setUp(self):
+        Handler.calls.clear()
+
+    def test_submission_preserves_body_key_and_unknown_response_fields(self):
+        body = {"source": {"url": "https://www.youtube.com/watch?v=fixture"},
+                "mode": "captions_only", "max_credits": 1}
+        for _ in range(2):
+            result = self.client.create_job(body, idempotency_key="fixture-replay-01")
+            self.assertEqual(result["future_field"], 42)
+        self.assertEqual(len(Handler.calls), 2)
+        for method, path, headers, raw in Handler.calls:
+            self.assertEqual((method, path), ("POST", "/v1/jobs"))
+            self.assertEqual(headers["Authorization"], "Bearer " + KEY)
+            self.assertEqual(headers["Idempotency-Key"], "fixture-replay-01")
+            self.assertEqual(json.loads(raw), body)
+
+    def test_no_automatic_retry_and_safe_errors(self):
+        with self.assertRaises(ApiError) as ctx:
+            self.client.request("GET", "/v1/rate-limit")
+        self.assertEqual(len(Handler.calls), 1)
+        self.assertEqual(ctx.exception.code, "RATE_LIMITED")
+        self.assertEqual(ctx.exception.status, 429)
+        self.assertEqual(ctx.exception.retry_after_seconds, 4)
+        self.assertTrue(ctx.exception.retryable)
+        self.assertNotIn(KEY, str(ctx.exception))
+        with self.assertRaises(ApiError) as ctx:
+            self.client.request("GET", "/v1/gateway")
+        self.assertNotIn("html", str(ctx.exception))
+        with self.assertRaises(ApiError) as ctx:
+            self.client.request("GET", "/v1/malformed")
+        self.assertEqual(ctx.exception.code, "INVALID_RESPONSE")
+
+    def test_budget_conflict_and_inaccessible_job_errors_are_not_retried(self):
+        for path, status, code in [("/v1/budget", 402, "BUDGET_EXCEEDED"),
+                                   ("/v1/conflict", 409, "IDEMPOTENCY_CONFLICT"),
+                                   ("/v1/jobs/not-owned", 404, "NOT_FOUND")]:
+            with self.assertRaises(ApiError) as ctx:
+                self.client.request("GET", path)
+            self.assertEqual((ctx.exception.status, ctx.exception.code), (status, code))
+            self.assertFalse(ctx.exception.retryable)
+        self.assertEqual(len(Handler.calls), 3)
+
+    def test_redirect_never_followed(self):
+        with self.assertRaises(ApiError) as ctx:
+            self.client.request("GET", "/v1/redirect")
+        self.assertEqual(ctx.exception.status, 302)
+        self.assertEqual([x[1] for x in Handler.calls], ["/v1/redirect"])
+
+    def test_query_and_id_encoding_and_raw_export(self):
+        self.client.list_jobs(cursor="a/b?c&d", limit=7)
+        self.assertIn("cursor=a%2Fb%3Fc%26d", Handler.calls[-1][1])
+        self.client.get_job("id/other?x")
+        self.assertTrue(Handler.calls[-1][1].startswith("/v1/jobs/id%2Fother%3Fx"))
+        self.assertIn("Fixture", self.client.export_transcript("fixture", "srt"))
+
+    def test_rejects_credential_and_submission_hazards_before_network(self):
+        for base in ("http://example.com", "https://user:password@example.com", "https://example.com/path", "https://example.com?x=1"):
+            with self.assertRaises(ValueError):
+                TranscriptDock(KEY, base_url=base)
+        with self.assertRaises(ValueError):
+            TranscriptDock("bad\nkey")
+        for key in (None, "short", "has\nnewline"):
+            with self.assertRaises(ValueError):
+                self.client.create_job({}, idempotency_key=key)
+        for path in ("https://example.com", "/v1/../secret", "/v1/%2e%2e/secret", "/v1/jobs?x=1"):
+            with self.assertRaises(ValueError):
+                self.client.request("GET", path)
+        with self.assertRaises(ValueError):
+            self.client.request("post", "/v1/jobs", body={})
+        self.assertEqual(Handler.calls, [])
+
+    def test_polling_terminal_failure_and_timeout_preserve_state(self):
+        with patch.object(self.client, "request", return_value={"id": "fixture", "status": "failed"}):
+            self.assertEqual(self.client.wait_for_job("fixture")["status"], "failed")
+        job = {"id": "fixture", "status": "processing"}
+        with patch.object(self.client, "request", return_value=job), patch("transcriptdock.time.monotonic", side_effect=[0, 0, 2]):
+            with self.assertRaises(JobTimeoutError) as ctx:
+                self.client.wait_for_job("fixture", timeout=1)
+        self.assertEqual(ctx.exception.job, job)
+        with self.assertRaises(ValueError):
+            self.client.wait_for_job("fixture", timeout=float("nan"))
+
+
+if __name__ == "__main__":
+    unittest.main()

transcriptdock-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "transcriptdock"
+version = "0.1.0"
+source = { editable = "." }