flashdata-youtube-transcript 0.1.1__tar.gz → 0.2.0__tar.gz

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/.gitignore

@@ -1,9 +1,9 @@
-.venv/
-__pycache__/
-.pytest_cache/
-.ruff_cache/
-packages/
-dist/
-evidence/
-
-publish-dist/
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+packages/
+dist/
+evidence/
+
+publish-dist/

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/LICENSE

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

flashdata_youtube_transcript-0.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: flashdata-youtube-transcript
+Version: 0.2.0
+Summary: Export timestamped automatic captions for retrieval with the FlashData JSON CLI
+Project-URL: Homepage, https://flashdata.dev/docs/sources/youtube_transcript
+Project-URL: Documentation, https://flashdata.dev/docs/sources/youtube_transcript
+Project-URL: Pricing, https://flashdata.dev/pricing
+Project-URL: Support, https://flashdata.dev
+Project-URL: Source, https://github.com/flashdatadev/flashdata-mcp/tree/main/packages/python-cli
+Author-email: FlashData <support@flashdata.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,flashdata,json,uvx,youtube-transcript
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: pydantic<3,>=2.7.4
+Description-Content-Type: text/markdown
+
+# YouTube Transcript CLI — FlashData
+
+Export timestamped automatic captions for retrieval. This command calls the `youtube_transcript` API and returns JSON for your
+shell script, data pipeline or agent tool runner. It does not invoke a language model.
+
+Reads an existing track. No ASR, translation, or automatic fallback to uploader captions.
+
+## Install and run
+
+Requires Python 3.10 or newer. [uv installation](https://docs.astral.sh/uv/getting-started/installation/)
+provides `uvx`, which runs this package in an isolated environment.
+
+1. [Create a FlashData account](https://flashdata.dev/signup), obtain an API Key and fund Credits.
+2. Set `FLASHDATA_API_KEY` using your shell or secret manager. The CLI does not accept a key flag
+   or persist credentials. [Authentication and source documentation](https://flashdata.dev/docs/sources/youtube_transcript).
+3. Run this example after reviewing the input and cost:
+
+```sh
+uvx flashdata-youtube-transcript@0.2.0 --video-id dQw4w9WgXcQ --options-json '{"language": "en", "auto": true}' --output result.json
+```
+
+`--output` creates a new file with owner-only permissions where supported and refuses existing
+files before making a paid request. Without it, the full JSON response goes to stdout. Errors
+go to stderr. Exit 0 means the response was exported, 2 means local input/configuration failure,
+and 1 means request or output failure. For downloads, exit 0 can describe an unfinished job.
+
+For repeated use, install `uv tool install flashdata-youtube-transcript==0.2.0`; the command name is `flashdata-youtube-transcript`.
+Alternatively use `python -m pip install flashdata-youtube-transcript==0.2.0` in your virtual environment.
+
+## Inputs and output
+
+Use `--video-id` for the primary input. Additional options use
+`--options-json` as a JSON object, with strict field/type/range validation. Source is fixed by
+this package. Google count and locale options remain omitted unless supplied.
+
+| Option | Meaning |
+| --- | --- |
+| `language` | One code or 1–10 distinct codes. Omit to prefer en-orig, then en. Lists return tracks and per-language errors. Default: `null`. |
+| `auto` | True requests automatic captions; false requests manually authored captions. Default: `true`. |
+
+Run `uvx flashdata-youtube-transcript@0.2.0 --schema` to inspect all fields, nested filters, allowed values and
+defaults without a Key or an API call. `--help` and `--version` are also local-only.
+
+The JSON output preserves the API result envelope and optional fields: results[]: single track with segments/fullText, or tracks and per-language errors for a language list; usage.credits.
+Missing fields remain missing; empty results remain empty. No article text, translated captions,
+model conclusions, rights grants or keyword volumes are invented. Exact source contracts are
+documented [here](https://flashdata.dev/docs/sources/youtube_transcript).
+
+## Fees and failure handling
+
+This MIT-licensed CLI is free to install. FlashData API requests consume paid Credits;
+[current pricing](https://flashdata.dev/pricing) applies. Extended YouTube Search has a separate
+rate. Media delivery is billed by delivered volume, and your cloud-storage costs are separate.
+There is no automatic pagination, retry, polling, scheduled execution or model call.
+
+Each HTTP request has a 120-second network timeout (15-second connect timeout) and a 20-MiB response
+limit. A timeout or failure may occur after a paid request has been accepted. Check Jobs in
+the [FlashData console](https://flashdata.dev) before resubmitting. HTTP 401 means check the Key;
+402 means insufficient Credits; 429 means rate/quota limit. A partial output file is retained
+on failure. Do not retry a paid query just because output handling failed.
+
+Input values and your API Key are sent to FlashData to perform the request. A completed
+download-result read may fetch a signed JSON object from the result origin returned by
+FlashData; the API Key is never sent to that object URL. Only process data appropriate for
+your output destination. [Privacy policy](https://flashdata.dev/legal/privacy).
+
+Source and MIT license are included in the source distribution.
+
+[Source documentation](https://flashdata.dev/docs/sources/youtube_transcript) ·
+[Pricing](https://flashdata.dev/pricing) · [Sign up](https://flashdata.dev/signup)

flashdata_youtube_transcript-0.2.0/README.md

@@ -0,0 +1,70 @@
+# YouTube Transcript CLI — FlashData
+
+Export timestamped automatic captions for retrieval. This command calls the `youtube_transcript` API and returns JSON for your
+shell script, data pipeline or agent tool runner. It does not invoke a language model.
+
+Reads an existing track. No ASR, translation, or automatic fallback to uploader captions.
+
+## Install and run
+
+Requires Python 3.10 or newer. [uv installation](https://docs.astral.sh/uv/getting-started/installation/)
+provides `uvx`, which runs this package in an isolated environment.
+
+1. [Create a FlashData account](https://flashdata.dev/signup), obtain an API Key and fund Credits.
+2. Set `FLASHDATA_API_KEY` using your shell or secret manager. The CLI does not accept a key flag
+   or persist credentials. [Authentication and source documentation](https://flashdata.dev/docs/sources/youtube_transcript).
+3. Run this example after reviewing the input and cost:
+
+```sh
+uvx flashdata-youtube-transcript@0.2.0 --video-id dQw4w9WgXcQ --options-json '{"language": "en", "auto": true}' --output result.json
+```
+
+`--output` creates a new file with owner-only permissions where supported and refuses existing
+files before making a paid request. Without it, the full JSON response goes to stdout. Errors
+go to stderr. Exit 0 means the response was exported, 2 means local input/configuration failure,
+and 1 means request or output failure. For downloads, exit 0 can describe an unfinished job.
+
+For repeated use, install `uv tool install flashdata-youtube-transcript==0.2.0`; the command name is `flashdata-youtube-transcript`.
+Alternatively use `python -m pip install flashdata-youtube-transcript==0.2.0` in your virtual environment.
+
+## Inputs and output
+
+Use `--video-id` for the primary input. Additional options use
+`--options-json` as a JSON object, with strict field/type/range validation. Source is fixed by
+this package. Google count and locale options remain omitted unless supplied.
+
+| Option | Meaning |
+| --- | --- |
+| `language` | One code or 1–10 distinct codes. Omit to prefer en-orig, then en. Lists return tracks and per-language errors. Default: `null`. |
+| `auto` | True requests automatic captions; false requests manually authored captions. Default: `true`. |
+
+Run `uvx flashdata-youtube-transcript@0.2.0 --schema` to inspect all fields, nested filters, allowed values and
+defaults without a Key or an API call. `--help` and `--version` are also local-only.
+
+The JSON output preserves the API result envelope and optional fields: results[]: single track with segments/fullText, or tracks and per-language errors for a language list; usage.credits.
+Missing fields remain missing; empty results remain empty. No article text, translated captions,
+model conclusions, rights grants or keyword volumes are invented. Exact source contracts are
+documented [here](https://flashdata.dev/docs/sources/youtube_transcript).
+
+## Fees and failure handling
+
+This MIT-licensed CLI is free to install. FlashData API requests consume paid Credits;
+[current pricing](https://flashdata.dev/pricing) applies. Extended YouTube Search has a separate
+rate. Media delivery is billed by delivered volume, and your cloud-storage costs are separate.
+There is no automatic pagination, retry, polling, scheduled execution or model call.
+
+Each HTTP request has a 120-second network timeout (15-second connect timeout) and a 20-MiB response
+limit. A timeout or failure may occur after a paid request has been accepted. Check Jobs in
+the [FlashData console](https://flashdata.dev) before resubmitting. HTTP 401 means check the Key;
+402 means insufficient Credits; 429 means rate/quota limit. A partial output file is retained
+on failure. Do not retry a paid query just because output handling failed.
+
+Input values and your API Key are sent to FlashData to perform the request. A completed
+download-result read may fetch a signed JSON object from the result origin returned by
+FlashData; the API Key is never sent to that object URL. Only process data appropriate for
+your output destination. [Privacy policy](https://flashdata.dev/legal/privacy).
+
+Source and MIT license are included in the source distribution.
+
+[Source documentation](https://flashdata.dev/docs/sources/youtube_transcript) ·
+[Pricing](https://flashdata.dev/pricing) · [Sign up](https://flashdata.dev/signup)

flashdata_youtube_transcript-0.2.0/flashdata_youtube_transcript_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/flashdata_youtube_transcript_cli/_capability.py

@@ -1,2 +1,2 @@
-SOURCE = 'youtube_transcript'
-COMMAND = 'flashdata-youtube-transcript'
+SOURCE = 'youtube_transcript'
+COMMAND = 'flashdata-youtube-transcript'

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/flashdata_youtube_transcript_cli/_client.py

@@ -27,7 +27,7 @@ class Client:
         self.transport = transport
 
     def _request(self, method, url, payload=None, *, authenticated=True):
-        headers = {"Accept": "application/json", "User-Agent": "flashdata-cli/0.1.1"}
+        headers = {"Accept": "application/json", "User-Agent": "flashdata-cli/0.2.0"}
         if authenticated:
             headers.update({"X-API-Key": self.api_key, "X-Request-Id": str(uuid4())})
         try:

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/flashdata_youtube_transcript_cli/_inputs.py

@@ -125,9 +125,27 @@ class YouTubeMetadataInput(_VideoInput):
 
 
 class YouTubeTranscriptInput(_VideoInput):
-    """YouTube transcript parameters; no implicit language or caption fallback."""
+    """Existing automatic captions, with optional language selection."""
+
+    language: (
+        Language
+        | Annotated[
+            list[Language],
+            Field(min_length=1, max_length=10, json_schema_extra={"uniqueItems": True}),
+        ]
+        | None
+    ) = Field(
+        default=None,
+        description="One code or 1–10 distinct codes. Omit to prefer en-orig, then en. Lists return tracks and per-language errors.",
+    )
+
+    @field_validator("language")
+    @classmethod
+    def distinct_languages(cls, value):
+        if isinstance(value, list) and len(set(value)) != len(value):
+            raise ValueError("language codes must be distinct")
+        return value
 
-    language: Language = Field(default="en", description="Requested caption language code.")
     auto: bool = Field(
         default=True,
         description="True requests automatic captions; false requests manually authored captions.",
@@ -135,7 +153,7 @@ class YouTubeTranscriptInput(_VideoInput):
 
 
 class YouTubeCaptionsInput(YouTubeTranscriptInput):
-    """Select uploader captions by default, without fallback."""
+    """Select uploaded captions without switching caption source."""
 
     auto: bool = Field(default=False, description="False selects manual; true automatic captions.")
 

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/flashdata_youtube_transcript_cli/cli.py

@@ -1,201 +1,201 @@
-"""CLI entry point shared at build time by fifteen independently named packages."""
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-from urllib.parse import urlsplit
-
-from pydantic import ValidationError
-
-from . import __version__
-from ._client import UNKNOWN_OUTCOME, Client, FlashDataError
-from ._inputs import (
-    DownloadJobInput,
-    GoogleInput,
-    YouTubeCaptionsInput,
-    YouTubeChannelInput,
-    YouTubeDownloadInput,
-    YouTubeExtendedSearchInput,
-    YouTubeMetadataInput,
-    YouTubeSearchInput,
-    YouTubeSuggestionsInput,
-    YouTubeTrainabilityInput,
-    YouTubeTranscriptInput,
-)
-from ._storage import storage_config
-
-CONTRACTS = {
-    **{
-        f"google_{kind}": GoogleInput
-        for kind in ("search", "news", "images", "shopping", "videos", "places")
-    },
-    "youtube_search": YouTubeSearchInput,
-    "youtube_search_extended": YouTubeExtendedSearchInput,
-    "youtube_metadata": YouTubeMetadataInput,
-    "youtube_transcript": YouTubeTranscriptInput,
-    "youtube_captions": YouTubeCaptionsInput,
-    "youtube_trainability": YouTubeTrainabilityInput,
-    "youtube_channel": YouTubeChannelInput,
-    "youtube_suggestions": YouTubeSuggestionsInput,
-    "youtube_download": YouTubeDownloadInput,
-}
-
-
-class Parser(argparse.ArgumentParser):
-    def error(self, message):
-        raise FlashDataError("Invalid command arguments. Use --help for supported options.")
-
-
-def parser_for(source, command):
-    parser = Parser(
-        prog=command,
-        description=(
-            f"Run the {source} FlashData API and export JSON. API calls use paid Credits. "
-            "Read FLASHDATA_API_KEY from the environment; never pass credentials as arguments."
-        ),
-    )
-    parser.add_argument("--version", action="version", version=f"{command} {__version__}")
-    parser.add_argument(
-        "--schema", action="store_true", help="Print the input schema; no API call."
-    )
-    parser.add_argument(
-        "--output", type=Path, help="New JSON file (0600); existing files are refused."
-    )
-    primary = (
-        "handle"
-        if source == "youtube_channel"
-        else "query"
-        if (
-            source.startswith("google_")
-            or source in ("youtube_search", "youtube_search_extended", "youtube_suggestions")
-        )
-        else "video-id"
-    )
-    parser.add_argument("--" + primary, help="Primary query, channel handle, or YouTube ID/URL.")
-    parser.add_argument(
-        "--options-json", help="Source options as a JSON object, without credentials."
-    )
-    if source == "youtube_download":
-        parser.add_argument("--operation", choices=["status", "result", "submit"], default="status")
-        parser.add_argument("--job-id", help="Previously saved job ID for status/result.")
-        parser.add_argument(
-            "--allow-submit", action="store_true", help="Permit one paid storage write."
-        )
-    return parser
-
-
-def payload_for(source, args, environ):
-    operation = getattr(args, "operation", "query")
-    if operation in ("status", "result"):
-        if args.video_id or args.options_json or args.allow_submit:
-            raise FlashDataError("Status/result accepts --job-id, without submission inputs.")
-        return operation, DownloadJobInput(job_id=args.job_id).model_dump()
-    try:
-        options = json.loads(args.options_json) if args.options_json is not None else {}
-    except ValueError:
-        raise FlashDataError("--options-json must be a JSON object.") from None
-    if not isinstance(options, dict) or any(
-        field in options for field in ("source", "query", "video_id", "handle", "storage")
-    ):
-        raise FlashDataError(
-            "Use dedicated primary inputs; source is fixed and secrets use env vars."
-        )
-    values = dict(options)
-    for primary in ("query", "video_id", "handle"):
-        value = getattr(args, primary, None)
-        if value is not None:
-            values[primary] = value
-    data = CONTRACTS[source].model_validate(values).model_dump(exclude_none=True, by_alias=True)
-    primary = next(key for key in ("query", "video_id", "handle") if key in data)
-    payload = {"source": source, primary: data.pop(primary), "params": data}
-    if operation == "submit":
-        if args.job_id or not args.allow_submit:
-            raise FlashDataError(
-                "New delivery requires --allow-submit; saved jobs use status/result."
-            )
-        storage = storage_config(environ.get("FLASHDATA_DOWNLOAD_STORAGE", ""))
-        endpoint = storage.get("endpoint_url")
-        if endpoint:
-            url = urlsplit(endpoint)
-            if (
-                url.scheme != "https"
-                or not url.hostname
-                or url.username
-                or url.password
-                or url.query
-                or url.fragment
-            ):
-                raise FlashDataError("Storage endpoint must be an HTTPS URL without credentials.")
-        payload["params"]["storage"] = storage
-    return operation, payload
-
-
-def run(
-    source, command, argv=None, *, environ=None, stdout=None, stderr=None, client_factory=Client
-):
-    environ = os.environ if environ is None else environ
-    stdout = sys.stdout if stdout is None else stdout
-    stderr = sys.stderr if stderr is None else stderr
-    output = None
-    request_started = False
-    output_complete = False
-    try:
-        args = parser_for(source, command).parse_args(argv)
-        if args.schema:
-            stdout.write(json.dumps(CONTRACTS[source].model_json_schema(), indent=2) + "\n")
-            return 0
-        operation, payload = payload_for(source, args, environ)
-        key = environ.get("FLASHDATA_API_KEY", "").strip()
-        if not key or any(ord(c) < 32 or ord(c) == 127 for c in key):
-            raise FlashDataError("Set a valid FLASHDATA_API_KEY environment variable.")
-        if args.output:
-            # Reserve the new path before spending Credits, without replacing user files.
-            fd = os.open(args.output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
-            output = os.fdopen(fd, "w", encoding="utf-8")
-        client = client_factory(key)
-        request_started = True
-        result = (
-            client.query(payload)
-            if operation == "query"
-            else client.submit(payload)
-            if operation == "submit"
-            else client.status(payload["job_id"])
-            if operation == "status"
-            else client.result(payload["job_id"])
-        )
-        destination = output if output else stdout
-        destination.write(json.dumps(result, ensure_ascii=False, allow_nan=False, indent=2) + "\n")
-        destination.flush()
-        output_complete = True
-        return 0
-    except ValidationError:
-        stderr.write("Invalid source input. See --schema for fields, types, ranges and defaults.\n")
-        return 2
-    except FlashDataError as error:
-        stderr.write(str(error) + "\n")
-        return 1 if request_started else 2
-    except (OSError, ValueError, TypeError):
-        stderr.write(
-            (
-                "Could not save the response. " + UNKNOWN_OUTCOME
-                if request_started
-                else "Could not prepare output or inputs. Check the new output path."
-            )
-            + "\n"
-        )
-        return 1 if request_started else 2
-    finally:
-        if output:
-            output.close()
-            if not output_complete:
-                stderr.write(
-                    "The newly reserved output file is incomplete; check Jobs before retrying.\n"
-                )
-
-
-def main():
-    from ._capability import COMMAND, SOURCE
-
-    raise SystemExit(run(SOURCE, COMMAND))
+"""CLI entry point shared at build time by fifteen independently named packages."""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from pydantic import ValidationError
+
+from . import __version__
+from ._client import UNKNOWN_OUTCOME, Client, FlashDataError
+from ._inputs import (
+    DownloadJobInput,
+    GoogleInput,
+    YouTubeCaptionsInput,
+    YouTubeChannelInput,
+    YouTubeDownloadInput,
+    YouTubeExtendedSearchInput,
+    YouTubeMetadataInput,
+    YouTubeSearchInput,
+    YouTubeSuggestionsInput,
+    YouTubeTrainabilityInput,
+    YouTubeTranscriptInput,
+)
+from ._storage import storage_config
+
+CONTRACTS = {
+    **{
+        f"google_{kind}": GoogleInput
+        for kind in ("search", "news", "images", "shopping", "videos", "places")
+    },
+    "youtube_search": YouTubeSearchInput,
+    "youtube_search_extended": YouTubeExtendedSearchInput,
+    "youtube_metadata": YouTubeMetadataInput,
+    "youtube_transcript": YouTubeTranscriptInput,
+    "youtube_captions": YouTubeCaptionsInput,
+    "youtube_trainability": YouTubeTrainabilityInput,
+    "youtube_channel": YouTubeChannelInput,
+    "youtube_suggestions": YouTubeSuggestionsInput,
+    "youtube_download": YouTubeDownloadInput,
+}
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise FlashDataError("Invalid command arguments. Use --help for supported options.")
+
+
+def parser_for(source, command):
+    parser = Parser(
+        prog=command,
+        description=(
+            f"Run the {source} FlashData API and export JSON. API calls use paid Credits. "
+            "Read FLASHDATA_API_KEY from the environment; never pass credentials as arguments."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"{command} {__version__}")
+    parser.add_argument(
+        "--schema", action="store_true", help="Print the input schema; no API call."
+    )
+    parser.add_argument(
+        "--output", type=Path, help="New JSON file (0600); existing files are refused."
+    )
+    primary = (
+        "handle"
+        if source == "youtube_channel"
+        else "query"
+        if (
+            source.startswith("google_")
+            or source in ("youtube_search", "youtube_search_extended", "youtube_suggestions")
+        )
+        else "video-id"
+    )
+    parser.add_argument("--" + primary, help="Primary query, channel handle, or YouTube ID/URL.")
+    parser.add_argument(
+        "--options-json", help="Source options as a JSON object, without credentials."
+    )
+    if source == "youtube_download":
+        parser.add_argument("--operation", choices=["status", "result", "submit"], default="status")
+        parser.add_argument("--job-id", help="Previously saved job ID for status/result.")
+        parser.add_argument(
+            "--allow-submit", action="store_true", help="Permit one paid storage write."
+        )
+    return parser
+
+
+def payload_for(source, args, environ):
+    operation = getattr(args, "operation", "query")
+    if operation in ("status", "result"):
+        if args.video_id or args.options_json or args.allow_submit:
+            raise FlashDataError("Status/result accepts --job-id, without submission inputs.")
+        return operation, DownloadJobInput(job_id=args.job_id).model_dump()
+    try:
+        options = json.loads(args.options_json) if args.options_json is not None else {}
+    except ValueError:
+        raise FlashDataError("--options-json must be a JSON object.") from None
+    if not isinstance(options, dict) or any(
+        field in options for field in ("source", "query", "video_id", "handle", "storage")
+    ):
+        raise FlashDataError(
+            "Use dedicated primary inputs; source is fixed and secrets use env vars."
+        )
+    values = dict(options)
+    for primary in ("query", "video_id", "handle"):
+        value = getattr(args, primary, None)
+        if value is not None:
+            values[primary] = value
+    data = CONTRACTS[source].model_validate(values).model_dump(exclude_none=True, by_alias=True)
+    primary = next(key for key in ("query", "video_id", "handle") if key in data)
+    payload = {"source": source, primary: data.pop(primary), "params": data}
+    if operation == "submit":
+        if args.job_id or not args.allow_submit:
+            raise FlashDataError(
+                "New delivery requires --allow-submit; saved jobs use status/result."
+            )
+        storage = storage_config(environ.get("FLASHDATA_DOWNLOAD_STORAGE", ""))
+        endpoint = storage.get("endpoint_url")
+        if endpoint:
+            url = urlsplit(endpoint)
+            if (
+                url.scheme != "https"
+                or not url.hostname
+                or url.username
+                or url.password
+                or url.query
+                or url.fragment
+            ):
+                raise FlashDataError("Storage endpoint must be an HTTPS URL without credentials.")
+        payload["params"]["storage"] = storage
+    return operation, payload
+
+
+def run(
+    source, command, argv=None, *, environ=None, stdout=None, stderr=None, client_factory=Client
+):
+    environ = os.environ if environ is None else environ
+    stdout = sys.stdout if stdout is None else stdout
+    stderr = sys.stderr if stderr is None else stderr
+    output = None
+    request_started = False
+    output_complete = False
+    try:
+        args = parser_for(source, command).parse_args(argv)
+        if args.schema:
+            stdout.write(json.dumps(CONTRACTS[source].model_json_schema(), indent=2) + "\n")
+            return 0
+        operation, payload = payload_for(source, args, environ)
+        key = environ.get("FLASHDATA_API_KEY", "").strip()
+        if not key or any(ord(c) < 32 or ord(c) == 127 for c in key):
+            raise FlashDataError("Set a valid FLASHDATA_API_KEY environment variable.")
+        if args.output:
+            # Reserve the new path before spending Credits, without replacing user files.
+            fd = os.open(args.output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            output = os.fdopen(fd, "w", encoding="utf-8")
+        client = client_factory(key)
+        request_started = True
+        result = (
+            client.query(payload)
+            if operation == "query"
+            else client.submit(payload)
+            if operation == "submit"
+            else client.status(payload["job_id"])
+            if operation == "status"
+            else client.result(payload["job_id"])
+        )
+        destination = output if output else stdout
+        destination.write(json.dumps(result, ensure_ascii=False, allow_nan=False, indent=2) + "\n")
+        destination.flush()
+        output_complete = True
+        return 0
+    except ValidationError:
+        stderr.write("Invalid source input. See --schema for fields, types, ranges and defaults.\n")
+        return 2
+    except FlashDataError as error:
+        stderr.write(str(error) + "\n")
+        return 1 if request_started else 2
+    except (OSError, ValueError, TypeError):
+        stderr.write(
+            (
+                "Could not save the response. " + UNKNOWN_OUTCOME
+                if request_started
+                else "Could not prepare output or inputs. Check the new output path."
+            )
+            + "\n"
+        )
+        return 1 if request_started else 2
+    finally:
+        if output:
+            output.close()
+            if not output_complete:
+                stderr.write(
+                    "The newly reserved output file is incomplete; check Jobs before retrying.\n"
+                )
+
+
+def main():
+    from ._capability import COMMAND, SOURCE
+
+    raise SystemExit(run(SOURCE, COMMAND))

flashdata_youtube_transcript-0.2.0/input.schema.json

@@ -0,0 +1,46 @@
+{
+  "additionalProperties": false,
+  "description": "Existing automatic captions, with optional language selection.",
+  "properties": {
+    "video_id": {
+      "description": "11-character YouTube video ID or a YouTube video URL.",
+      "title": "Video Id",
+      "type": "string"
+    },
+    "language": {
+      "anyOf": [
+        {
+          "pattern": "^[A-Za-z0-9-]{1,35}$",
+          "type": "string"
+        },
+        {
+          "items": {
+            "pattern": "^[A-Za-z0-9-]{1,35}$",
+            "type": "string"
+          },
+          "maxItems": 10,
+          "minItems": 1,
+          "type": "array",
+          "uniqueItems": true
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "One code or 1\u201310 distinct codes. Omit to prefer en-orig, then en. Lists return tracks and per-language errors.",
+      "title": "Language"
+    },
+    "auto": {
+      "default": true,
+      "description": "True requests automatic captions; false requests manually authored captions.",
+      "title": "Auto",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "video_id"
+  ],
+  "title": "YouTubeTranscriptInput",
+  "type": "object"
+}

{flashdata_youtube_transcript-0.1.1 → flashdata_youtube_transcript-0.2.0}/pyproject.toml

@@ -1,29 +1,29 @@
-[build-system]
-requires = ["hatchling>=1.27,<2"]
-build-backend = "hatchling.build"
-
-[project]
-name = "flashdata-youtube-transcript"
-version = "0.1.1"
-description = "Retrieve existing YouTube transcripts as timestamped segments and full text in JSON; automatic captions by default."
-readme = "README.md"
-requires-python = ">=3.10"
-license = "MIT"
-license-files = ["LICENSE"]
-authors = [{name = "FlashData", email = "support@flashdata.dev"}]
-keywords = ["youtube-transcript", "cli", "json", "uvx", "flashdata"]
-classifiers = ["Intended Audience :: Developers", "Programming Language :: Python :: 3", "Environment :: Console"]
-dependencies = ["httpx>=0.28.1,<1", "pydantic>=2.7.4,<3", "jsonschema>=4.23,<5"]
-
-[project.scripts]
-flashdata-youtube-transcript = "flashdata_youtube_transcript_cli.cli:main"
-
-[project.urls]
-Homepage = "https://flashdata.dev/docs/sources/youtube_transcript"
-Documentation = "https://flashdata.dev/docs/sources/youtube_transcript"
-Pricing = "https://flashdata.dev/pricing"
-Support = "https://flashdata.dev"
-Source = "https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli"
-
-[tool.hatch.build.targets.wheel]
-packages = ["flashdata_youtube_transcript_cli"]
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flashdata-youtube-transcript"
+version = "0.2.0"
+description = "Export timestamped automatic captions for retrieval with the FlashData JSON CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "FlashData", email = "support@flashdata.dev"}]
+keywords = ["youtube-transcript", "cli", "json", "uvx", "flashdata"]
+classifiers = ["Intended Audience :: Developers", "Programming Language :: Python :: 3", "Environment :: Console"]
+dependencies = ["httpx>=0.28.1,<1", "pydantic>=2.7.4,<3", "jsonschema>=4.23,<5"]
+
+[project.scripts]
+flashdata-youtube-transcript = "flashdata_youtube_transcript_cli.cli:main"
+
+[project.urls]
+Homepage = "https://flashdata.dev/docs/sources/youtube_transcript"
+Documentation = "https://flashdata.dev/docs/sources/youtube_transcript"
+Pricing = "https://flashdata.dev/pricing"
+Support = "https://flashdata.dev"
+Source = "https://github.com/flashdatadev/flashdata-mcp/tree/main/packages/python-cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["flashdata_youtube_transcript_cli"]

flashdata_youtube_transcript-0.1.1/PKG-INFO

@@ -1,95 +0,0 @@
-Metadata-Version: 2.5
-Name: flashdata-youtube-transcript
-Version: 0.1.1
-Summary: Retrieve existing YouTube transcripts as timestamped segments and full text in JSON; automatic captions by default.
-Project-URL: Homepage, https://flashdata.dev/docs/sources/youtube_transcript
-Project-URL: Documentation, https://flashdata.dev/docs/sources/youtube_transcript
-Project-URL: Pricing, https://flashdata.dev/pricing
-Project-URL: Support, https://flashdata.dev
-Project-URL: Source, https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli
-Author-email: FlashData <support@flashdata.dev>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: cli,flashdata,json,uvx,youtube-transcript
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.10
-Requires-Dist: httpx<1,>=0.28.1
-Requires-Dist: jsonschema<5,>=4.23
-Requires-Dist: pydantic<3,>=2.7.4
-Description-Content-Type: text/markdown
-
-# YouTube Transcript CLI
-
-Retrieve existing YouTube transcripts as timestamped segments and full text in JSON; automatic captions by default.
-
-Uses the [FlashData YouTube Transcript API](https://flashdata.dev/docs/sources/youtube_transcript).
-
-## Installation
-
-Requires Python 3.10 or newer:
-
-```sh
-python -m pip install flashdata-youtube-transcript==0.1.1
-```
-
-Or run it without a persistent install using [uvx](https://docs.astral.sh/uv/guides/tools/),
-as in the examples below. The installed command is `flashdata-youtube-transcript`.
-
-## Quick start
-
-Create a [FlashData API key](https://flashdata.dev/app/api-keys) with `youtube_transcript` access,
-then set `FLASHDATA_API_KEY` in your environment or secret manager. API calls use your
-FlashData Credits.
-
-```sh
-export FLASHDATA_API_KEY='YOUR_API_KEY'
-uvx flashdata-youtube-transcript@0.1.1 --video-id dQw4w9WgXcQ --options-json '{"language": "en", "auto": true}' --output result.json
-```
-
-Omit `--output` to write JSON to stdout. An output file must not already exist; the CLI
-checks this before making a request. API keys are read from the environment, not command flags.
-
-## Inputs
-
-Use `--video-id` for the primary input. Pass additional fields through
-`--options-json`. Options are validated against this package's source schema.
-
-| Option | Meaning |
-| --- | --- |
-| `language` | Requested caption language code. Default: `"en"`. |
-| `auto` | True requests automatic captions; false requests manually authored captions. Default: `true`. |
-
-Inspect all fields, nested filters and defaults locally:
-
-```sh
-uvx flashdata-youtube-transcript@0.1.1 --schema
-```
-
-`--schema`, `--help` and `--version` do not require an API key or make an API call.
-
-## Output and limits
-
-The JSON response preserves the API envelope and available fields: results[]: videoId, languageCode, isAutoGenerated, segments, fullText; usage.credits.
-
-Reads an existing track. No ASR, translation, or automatic fallback to uploader captions.
-
-## Pricing and errors
-
-This MIT-licensed CLI is free to install. API calls use your own
-[FlashData Credits](https://flashdata.dev/pricing).
-
-Requests are not automatically retried. A timeout can occur after a request is accepted;
-check your FlashData query history before resubmitting. Each HTTP request has a 120-second
-network timeout, a 15-second connect timeout and a 20-MiB response limit.
-
-Errors go to stderr. Exit codes: `0` for exported output, `2` for local input/configuration
-errors, and `1` for request/output errors.
-A partial output file is retained on failure; check the request before retrying because of
-an output error. HTTP `401` indicates an API key issue, `402` insufficient Credits, and
-`429` a rate or quota limit.
-
-[API reference](https://flashdata.dev/docs/sources/youtube_transcript) ·
-[Privacy policy](https://flashdata.dev/legal/privacy) ·
-[Source code](https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli)

flashdata_youtube_transcript-0.1.1/README.md

@@ -1,73 +0,0 @@
-# YouTube Transcript CLI
-
-Retrieve existing YouTube transcripts as timestamped segments and full text in JSON; automatic captions by default.
-
-Uses the [FlashData YouTube Transcript API](https://flashdata.dev/docs/sources/youtube_transcript).
-
-## Installation
-
-Requires Python 3.10 or newer:
-
-```sh
-python -m pip install flashdata-youtube-transcript==0.1.1
-```
-
-Or run it without a persistent install using [uvx](https://docs.astral.sh/uv/guides/tools/),
-as in the examples below. The installed command is `flashdata-youtube-transcript`.
-
-## Quick start
-
-Create a [FlashData API key](https://flashdata.dev/app/api-keys) with `youtube_transcript` access,
-then set `FLASHDATA_API_KEY` in your environment or secret manager. API calls use your
-FlashData Credits.
-
-```sh
-export FLASHDATA_API_KEY='YOUR_API_KEY'
-uvx flashdata-youtube-transcript@0.1.1 --video-id dQw4w9WgXcQ --options-json '{"language": "en", "auto": true}' --output result.json
-```
-
-Omit `--output` to write JSON to stdout. An output file must not already exist; the CLI
-checks this before making a request. API keys are read from the environment, not command flags.
-
-## Inputs
-
-Use `--video-id` for the primary input. Pass additional fields through
-`--options-json`. Options are validated against this package's source schema.
-
-| Option | Meaning |
-| --- | --- |
-| `language` | Requested caption language code. Default: `"en"`. |
-| `auto` | True requests automatic captions; false requests manually authored captions. Default: `true`. |
-
-Inspect all fields, nested filters and defaults locally:
-
-```sh
-uvx flashdata-youtube-transcript@0.1.1 --schema
-```
-
-`--schema`, `--help` and `--version` do not require an API key or make an API call.
-
-## Output and limits
-
-The JSON response preserves the API envelope and available fields: results[]: videoId, languageCode, isAutoGenerated, segments, fullText; usage.credits.
-
-Reads an existing track. No ASR, translation, or automatic fallback to uploader captions.
-
-## Pricing and errors
-
-This MIT-licensed CLI is free to install. API calls use your own
-[FlashData Credits](https://flashdata.dev/pricing).
-
-Requests are not automatically retried. A timeout can occur after a request is accepted;
-check your FlashData query history before resubmitting. Each HTTP request has a 120-second
-network timeout, a 15-second connect timeout and a 20-MiB response limit.
-
-Errors go to stderr. Exit codes: `0` for exported output, `2` for local input/configuration
-errors, and `1` for request/output errors.
-A partial output file is retained on failure; check the request before retrying because of
-an output error. HTTP `401` indicates an API key issue, `402` insufficient Credits, and
-`429` a rate or quota limit.
-
-[API reference](https://flashdata.dev/docs/sources/youtube_transcript) ·
-[Privacy policy](https://flashdata.dev/legal/privacy) ·
-[Source code](https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli)

flashdata_youtube_transcript-0.1.1/flashdata_youtube_transcript_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.1"

flashdata_youtube_transcript-0.1.1/input.schema.json

@@ -1,29 +0,0 @@
-{
-  "additionalProperties": false,
-  "description": "YouTube transcript parameters; no implicit language or caption fallback.",
-  "properties": {
-    "video_id": {
-      "description": "11-character YouTube video ID or a YouTube video URL.",
-      "title": "Video Id",
-      "type": "string"
-    },
-    "language": {
-      "default": "en",
-      "description": "Requested caption language code.",
-      "pattern": "^[A-Za-z0-9-]{1,35}$",
-      "title": "Language",
-      "type": "string"
-    },
-    "auto": {
-      "default": true,
-      "description": "True requests automatic captions; false requests manually authored captions.",
-      "title": "Auto",
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "video_id"
-  ],
-  "title": "YouTubeTranscriptInput",
-  "type": "object"
-}