transcriptdock 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+transcriptdock/__init__.py,sha256=ABS-yKAdHxz_8hqmtjnk1bY5rkwD0BkeXK1Daa3xF_0,10711
+transcriptdock-0.1.0.dist-info/METADATA,sha256=rgLsn3oqoW7qI1gvco474UztrgxIKaCT7iPzr31pGFA,6181
+transcriptdock-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+transcriptdock-0.1.0.dist-info/licenses/LICENSE,sha256=PlrCALGeq75kxiCPnmB1r7omsS774wwjE7djN0DfMQw,1072
+transcriptdock-0.1.0.dist-info/RECORD,,

transcriptdock-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

transcriptdock-0.1.0.dist-info/licenses/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.