gopro-api 0.0.6__py3-none-any.whl

gopro_api/__init__.py

@@ -0,0 +1 @@
+"""Unofficial Python client for the GoPro cloud API (api.gopro.com)."""

gopro_api/api/__init__.py

@@ -0,0 +1,7 @@
+"""Sync and async HTTP clients for api.gopro.com."""
+
+from .gopro import GoProAPI
+from .async_gopro import AsyncGoProAPI
+
+
+__all__ = ["GoProAPI", "AsyncGoProAPI"]

gopro_api/api/async_gopro.py

@@ -0,0 +1,93 @@
+"""Asynchronous GoPro cloud API client (``aiohttp``)."""
+
+import aiohttp
+
+from gopro_api.config import GP_ACCESS_TOKEN
+from gopro_api.api.models import (
+    GoProMediaSearchParams,
+    GoProMediaDownloadResponse,
+    GoProMediaSearchResponse,
+)
+
+
+class AsyncGoProAPI:
+    """Async client for ``https://api.gopro.com`` (Quik / cloud library).
+
+    Use as an async context manager so an ``aiohttp.ClientSession`` is opened
+    and closed around ``search`` and ``download``. Pass ``access_token`` to
+    override ``gopro_api.config.GP_ACCESS_TOKEN``.
+    """
+
+    def __init__(self, access_token: str | None = None, timeout: float = 10.0) -> None:
+        """Create an async client.
+
+        ``access_token``: cookie value; defaults to ``GP_ACCESS_TOKEN``.
+        ``timeout``: total HTTP client timeout in seconds.
+        """
+        self.access_token = access_token or GP_ACCESS_TOKEN
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._session: aiohttp.ClientSession | None = None
+
+    @property
+    def base_url(self) -> str:
+        """API origin (``https://api.gopro.com``)."""
+        return "https://api.gopro.com"
+
+    def get_headers(self, accept: str) -> dict[str, str]:
+        """Build ``Cookie`` and ``Accept`` headers for an API call."""
+        return {
+            "Cookie": "gp_access_token=" + self.access_token,
+            "Accept": accept,
+        }
+
+    async def __aenter__(self) -> "AsyncGoProAPI":
+        """Open an ``aiohttp.ClientSession`` for the ``async with`` body."""
+        self._session = aiohttp.ClientSession(
+            base_url=self.base_url,
+            timeout=self._timeout,
+        )
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Close the session."""
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    def _session_or_raise(self) -> aiohttp.ClientSession:
+        """Return the active session or raise if not inside ``async with``."""
+        session = self._session
+        if session is None:
+            msg = (
+                "Use AsyncGoProAPI as an async context manager: "
+                "async with AsyncGoProAPI() as api: ..."
+            )
+            raise RuntimeError(msg)
+        return session
+
+    async def download(self, media_id: str) -> GoProMediaDownloadResponse:
+        """``GET /media/{media_id}/download`` — metadata and CDN URLs for files."""
+        headers = self.get_headers("application/vnd.gopro.jk.media+json; version=2.0.0")
+        session = self._session_or_raise()
+        async with session.get(
+            f"/media/{media_id}/download",
+            headers=headers,
+        ) as response:
+            response.raise_for_status()
+            body = await response.text()
+        return GoProMediaDownloadResponse.model_validate_json(body)
+
+    async def search(self, params: GoProMediaSearchParams) -> GoProMediaSearchResponse:
+        """``GET /media/search`` using ``params.model_dump()`` as query string."""
+        headers = self.get_headers(
+            "application/vnd.gopro.jk.media.search+json; version=2.0.0",
+        )
+        session = self._session_or_raise()
+        async with session.get(
+            "/media/search",
+            headers=headers,
+            params=params.model_dump(),
+        ) as response:
+            response.raise_for_status()
+            body = await response.text()
+        return GoProMediaSearchResponse.model_validate_json(body)

gopro_api/api/gopro.py

@@ -0,0 +1,86 @@
+"""Synchronous GoPro cloud API client (``requests``)."""
+
+import requests
+
+from gopro_api.config import GP_ACCESS_TOKEN
+from gopro_api.api.models import (
+    GoProMediaDownloadResponse,
+    GoProMediaSearchParams,
+    GoProMediaSearchResponse,
+)
+
+
+class GoProAPI:
+    """Synchronous client for ``https://api.gopro.com`` (Quik / cloud library).
+
+    Use as a context manager so a ``requests.Session`` is created and closed
+    around ``search`` and ``download``. Pass ``access_token`` to override
+    ``gopro_api.config.GP_ACCESS_TOKEN``.
+    """
+
+    def __init__(self, access_token: str | None = None, timeout: float = 10.0) -> None:
+        """Create a sync client.
+
+        ``access_token``: cookie value; defaults to ``GP_ACCESS_TOKEN``.
+        ``timeout``: per-request timeout in seconds.
+        """
+        self.access_token = access_token or GP_ACCESS_TOKEN
+        self._timeout = timeout
+        self._session: requests.Session | None = None
+
+    @property
+    def base_url(self) -> str:
+        """API origin (``https://api.gopro.com``)."""
+        return "https://api.gopro.com"
+
+    def get_headers(self, accept: str) -> dict[str, str]:
+        """Build ``Cookie`` and ``Accept`` headers for an API call."""
+        return {
+            "Cookie": "gp_access_token=" + self.access_token,
+            "Accept": accept,
+        }
+
+    def __enter__(self) -> "GoProAPI":
+        """Open a ``requests.Session`` for the duration of the ``with`` block."""
+        self._session = requests.Session()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        """Close the session."""
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+
+    def _session_or_raise(self) -> requests.Session:
+        """Return the active session or raise if used outside a context manager."""
+        if self._session is None:
+            msg = "Use GoProAPI as a context manager: with GoProAPI() as api: ..."
+            raise RuntimeError(msg)
+        return self._session
+
+    def download(self, media_id: str) -> GoProMediaDownloadResponse:
+        """``GET /media/{media_id}/download`` — metadata and CDN URLs for files."""
+        headers = self.get_headers("application/vnd.gopro.jk.media+json; version=2.0.0")
+        session = self._session_or_raise()
+        response = session.get(
+            f"{self.base_url}/media/{media_id}/download",
+            headers=headers,
+            timeout=self._timeout,
+        )
+        response.raise_for_status()
+        return GoProMediaDownloadResponse.model_validate_json(response.text)
+
+    def search(self, params: GoProMediaSearchParams) -> GoProMediaSearchResponse:
+        """``GET /media/search`` using ``params.model_dump()`` as query string."""
+        headers = self.get_headers(
+            "application/vnd.gopro.jk.media.search+json; version=2.0.0",
+        )
+        session = self._session_or_raise()
+        response = session.get(
+            f"{self.base_url}/media/search",
+            headers=headers,
+            params=params.model_dump(),
+            timeout=self._timeout,
+        )
+        response.raise_for_status()
+        return GoProMediaSearchResponse.model_validate_json(response.text)

gopro_api/api/models.py

@@ -0,0 +1,166 @@
+"""Pydantic models for GoPro cloud media search and download JSON."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, model_serializer
+
+
+DEFAULT_PROCESSING_STATES: List[str] = [
+    "rendering",
+    "pretranscoding",
+    "transcoding",
+    "stabilizing",
+    "ready",
+    "failure",
+]
+DEFAULT_FIELDS: List[str] = ["id", "capturedate"]
+DEFAULT_MEDIA_TYPES: List[str] = [
+    "Burst",
+    "BurstVideo",
+    "Continuous",
+    "LoopedVideo",
+    "Photo",
+    "TimeLapse",
+    "TimeLapseVideo",
+    "Video",
+    "MultiClipEdit",
+    "Edit",
+]
+
+
+class CapturedRange(BaseModel):
+    """Capture window for search; serialized to the API ``captured_range`` string."""
+
+    start: datetime
+    end: datetime
+
+    @model_serializer
+    def _serialize_captured_range(self) -> str:
+        """Emit the ``captured_range`` query fragment expected by the API."""
+        return (
+            f"{self.start.isoformat()}T00:00:00.000Z,"
+            f"{self.end.isoformat()}T00:00:00.000Z"
+        )
+
+
+class GoProMediaSearchParams(BaseModel):
+    """Query parameters for ``GET /media/search`` (lists as comma-separated values)."""
+
+    processing_states: List[str] = DEFAULT_PROCESSING_STATES
+    fields: List[str] = DEFAULT_FIELDS
+    type: List[str] = DEFAULT_MEDIA_TYPES
+    captured_range: CapturedRange = CapturedRange(
+        start=datetime.min,
+        end=datetime.max,
+    )
+    page: int = 1
+    per_page: int = 1
+
+    @field_serializer("processing_states", "fields", "type")
+    def _serialize_csv_lists(self, value: List[str]) -> str:
+        """Join list fields into one comma-separated string for the query."""
+        return ",".join(value)
+
+
+class GoProMediaSearchItem(BaseModel):
+    """Single item in ``_embedded.media`` from a media search response."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    gopro_user_id: str
+    source_gumi: str
+    source_mgumi: Optional[str]
+
+
+class GoProMediaSearchEmbedded(BaseModel):
+    """``_embedded`` object on a media search response."""
+
+    model_config = ConfigDict(extra="allow")
+
+    media: List[GoProMediaSearchItem]
+    errors: List[Any] = []
+
+
+class GoProMediaSearchPages(BaseModel):
+    """Pagination block ``_pages`` on a media search response."""
+
+    current_page: int
+    per_page: int
+    total_items: int
+    total_pages: int
+
+
+class GoProMediaSearchResponse(BaseModel):
+    """Top-level JSON body from ``GET /media/search``."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    embedded: GoProMediaSearchEmbedded = Field(alias="_embedded")
+    pages: GoProMediaSearchPages = Field(alias="_pages")
+
+
+class GoProMediaDownloadFile(BaseModel):
+    """One downloadable file under ``_embedded.files`` from download metadata."""
+
+    model_config = ConfigDict(extra="allow")
+
+    url: str
+    head: str
+    camera_position: str
+    item_number: int
+    width: int
+    height: int
+    orientation: int
+    available: bool
+
+
+class GoProMediaDownloadVariation(BaseModel):
+    """Rendered size / quality variant in ``_embedded.variations``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    url: str
+    head: str
+    width: int
+    height: int
+    label: str
+    type: str
+    quality: str
+    available: bool
+
+
+class GoProMediaDownloadSidecarFile(BaseModel):
+    """Sidecar asset (e.g. zip) in ``_embedded.sidecar_files``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    url: str
+    head: str
+    label: str
+    type: str
+    fps: int
+    available: bool
+
+
+class GoProMediaDownloadEmbedded(BaseModel):
+    """``_embedded`` on a media download metadata response."""
+
+    model_config = ConfigDict(extra="allow")
+
+    files: List[GoProMediaDownloadFile]
+    variations: List[GoProMediaDownloadVariation]
+    sprites: List[Any]
+    sidecar_files: List[GoProMediaDownloadSidecarFile]
+
+
+class GoProMediaDownloadResponse(BaseModel):
+    """Top-level JSON body from ``GET /media/{id}/download``."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    filename: str
+    embedded: GoProMediaDownloadEmbedded = Field(alias="_embedded")

gopro_api/cli.py

@@ -0,0 +1,339 @@
+"""Command-line interface for gopro-api."""
+
+from __future__ import annotations
+
+import argparse
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from datetime import datetime
+import json
+import os
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+import requests
+
+from gopro_api.api import GoProAPI
+from gopro_api.api.models import (
+    CapturedRange,
+    GoProMediaDownloadVariation,
+    GoProMediaSearchParams,
+)
+from gopro_api.config import GP_ACCESS_TOKEN
+
+
+def _version() -> str:
+    try:
+        return version("gopro-api")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def _parse_dt(raw: str) -> datetime:
+    """Accept YYYY-MM-DD or ISO datetime."""
+    raw = raw.strip()
+    if len(raw) == 10 and raw[4] == "-" and raw[7] == "-":
+        return datetime.fromisoformat(raw)
+    return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+
+
+def _is_video_filename(filename: str) -> bool:
+    base = filename.rsplit(".", 1)
+    return len(base) == 2 and base[1].lower() == "mp4"
+
+
+def _positive_int(raw: str) -> int:
+    value = int(raw)
+    if value <= 0:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return value
+
+
+def _select_video_variation(
+    variations: list[GoProMediaDownloadVariation],
+    *,
+    target_height: int | None,
+    target_width: int | None,
+) -> GoProMediaDownloadVariation:
+    """Pick one variation: closest to target size, or tallest when no target."""
+    if not variations:
+        sys.stderr.write("error: API returned no video variations for this media id.\n")
+        raise SystemExit(2)
+    if target_height is None and target_width is None:
+        return max(variations, key=lambda var: var.height)
+
+    def score(variation: GoProMediaDownloadVariation) -> int:
+        delta_h = (
+            0 if target_height is None else (variation.height - target_height) ** 2
+        )
+        delta_w = 0 if target_width is None else (variation.width - target_width) ** 2
+        return delta_h + delta_w
+
+    best = min(score(variation) for variation in variations)
+    tied = [variation for variation in variations if score(variation) == best]
+    return max(tied, key=lambda var: (var.height, var.width))
+
+
+def _require_token() -> None:
+    if not GP_ACCESS_TOKEN:
+        sys.stderr.write(
+            "error: GP_ACCESS_TOKEN is not set. "
+            "Add it to your environment or a .env file.\n",
+        )
+        raise SystemExit(2)
+
+
+class CliSubcommand(ABC):
+    """One subcommand: its parser arguments and execution."""
+
+    name: str
+    help: str
+
+    @abstractmethod
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Configure the subparser for this command."""
+
+    @abstractmethod
+    def run(self, args: argparse.Namespace) -> None:
+        """Execute after global parse.
+
+        ``args`` includes parent options (for example ``timeout``).
+        """
+
+
+class SearchCommand(CliSubcommand):
+    """``search`` — list media ids in a capture date range."""
+
+    name = "search"
+    help = "List media ids in a capture date range"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--start",
+            required=True,
+            help="Range start: YYYY-MM-DD or ISO datetime",
+        )
+        parser.add_argument(
+            "--end",
+            required=True,
+            help=(
+                "Range end: YYYY-MM-DD or ISO datetime "
+                "(API treats range as in query string)"
+            ),
+        )
+        parser.add_argument(
+            "--page", type=int, default=1, help="Page number (default: 1)"
+        )
+        parser.add_argument(
+            "--per-page",
+            type=int,
+            default=30,
+            metavar="N",
+            help="Page size (default: 30)",
+        )
+        parser.add_argument(
+            "--all-pages",
+            action="store_true",
+            help="Keep requesting pages until a page returns no media",
+        )
+        parser.add_argument(
+            "--json",
+            action="store_true",
+            help="Print full API JSON (with --all-pages: list of page payloads)",
+        )
+
+    def run(self, args: argparse.Namespace) -> None:
+        _require_token()
+        start = _parse_dt(args.start)
+        end = _parse_dt(args.end)
+        per_page = args.per_page
+        page = args.page
+
+        with GoProAPI(timeout=args.timeout) as api:
+            if args.all_pages:
+                all_pages: list[dict] = []
+                while True:
+                    params = GoProMediaSearchParams(
+                        captured_range=CapturedRange(start=start, end=end),
+                        page=page,
+                        per_page=per_page,
+                    )
+                    page_result = api.search(params)
+                    if not page_result.embedded.media:
+                        break
+                    if args.json:
+                        all_pages.append(
+                            page_result.model_dump(by_alias=True, mode="json"),
+                        )
+                    else:
+                        for item in page_result.embedded.media:
+                            print(item.id)
+                    page += 1
+                if args.json:
+                    print(json.dumps(all_pages, indent=2))
+                return
+
+            params = GoProMediaSearchParams(
+                captured_range=CapturedRange(start=start, end=end),
+                page=page,
+                per_page=per_page,
+            )
+            page_result = api.search(params)
+            if args.json:
+                print(
+                    json.dumps(
+                        page_result.model_dump(by_alias=True, mode="json"),
+                        indent=2,
+                    ),
+                )
+            else:
+                for item in page_result.embedded.media:
+                    print(item.id)
+
+
+class InfoCommand(CliSubcommand):
+    """``info`` — show download metadata for one media id."""
+
+    name = "info"
+    help = "Show download metadata (URLs, sizes) for one media id"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("media_id", help="Media id from search")
+        parser.add_argument(
+            "--json",
+            action="store_true",
+            help="Print full API JSON",
+        )
+
+    def run(self, args: argparse.Namespace) -> None:
+        _require_token()
+        with GoProAPI(timeout=args.timeout) as api:
+            meta = api.download(args.media_id)
+        if args.json:
+            print(
+                json.dumps(
+                    meta.model_dump(by_alias=True, mode="json"),
+                    indent=2,
+                ),
+            )
+        else:
+            print(meta.filename)
+
+            if _is_video_filename(meta.filename):
+                media_list = meta.embedded.variations
+            else:
+                media_list = meta.embedded.files
+
+            for idx, media_item in enumerate(media_list):
+                print(
+                    f"  {idx:>3}  {media_item.width}x{media_item.height}  "
+                    f"{media_item.url}",
+                )
+
+
+class PullCommand(CliSubcommand):
+    """``pull`` — download files for one media id."""
+
+    name = "pull"
+    help = "Download files from a media id"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("media_id", help="Media id from search")
+        parser.add_argument("destination", help="Path to save the file")
+        parser.add_argument(
+            "--height",
+            type=_positive_int,
+            default=None,
+            metavar="PX",
+            help=(
+                "For video: pick the variation whose height is closest to PX "
+                "(default: tallest)"
+            ),
+        )
+        parser.add_argument(
+            "--width",
+            type=_positive_int,
+            default=None,
+            metavar="PX",
+            help=(
+                "For video: pick the variation whose width is closest to PX "
+                "(default: tallest)"
+            ),
+        )
+
+    def run(self, args: argparse.Namespace) -> None:
+        _require_token()
+        with GoProAPI(timeout=args.timeout) as api:
+            meta = api.download(args.media_id)
+
+            if _is_video_filename(meta.filename):
+                chosen = _select_video_variation(
+                    meta.embedded.variations,
+                    target_height=args.height,
+                    target_width=args.width,
+                )
+                media_list = [chosen]
+            else:
+                media_list = meta.embedded.files
+
+            for idx, file_entry in enumerate(media_list):
+                os.makedirs(args.destination, exist_ok=True)
+                media_name = meta.filename.split(".")[0]
+                media_type = meta.filename.split(".")[-1]
+                item_number = str(idx).zfill(3)
+                media_file_name = f"{media_name}{item_number}.{media_type}"
+                dest_path = f"{args.destination}/{media_file_name}"
+                with open(dest_path, "wb") as outfile:
+                    response = requests.get(file_entry.url, timeout=args.timeout)
+                    response.raise_for_status()
+                    outfile.write(response.content)
+
+
+class CliBuilder:  # pylint: disable=too-few-public-methods
+    """Assembles the root parser and one subparser per registered command."""
+
+    def __init__(self, commands: Sequence[CliSubcommand]) -> None:
+        self._commands = list(commands)
+
+    def build(self) -> argparse.ArgumentParser:
+        """Return the root parser with global options and subcommands."""
+        parser = argparse.ArgumentParser(
+            prog="gopro-api",
+            description="CLI for the unofficial GoPro cloud API (api.gopro.com).",
+        )
+        parser.add_argument(
+            "--version",
+            action="version",
+            version=f"%(prog)s {_version()}",
+        )
+        parser.add_argument(
+            "--timeout",
+            type=float,
+            default=60.0,
+            help="HTTP timeout in seconds (default: 60)",
+        )
+
+        sub = parser.add_subparsers(dest="command", required=True)
+        for cmd in self._commands:
+            subparser = sub.add_parser(cmd.name, help=cmd.help)
+            cmd.add_arguments(subparser)
+            subparser.set_defaults(func=cmd.run)
+
+        return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse CLI arguments and dispatch to the selected subcommand handler."""
+    builder = CliBuilder(
+        [
+            SearchCommand(),
+            InfoCommand(),
+            PullCommand(),
+        ],
+    )
+    args = builder.build().parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

gopro_api/config.py

@@ -0,0 +1,9 @@
+"""Environment-backed settings (e.g. ``GP_ACCESS_TOKEN`` from ``.env``)."""
+
+import os
+from dotenv import load_dotenv
+
+
+load_dotenv()
+
+GP_ACCESS_TOKEN = os.getenv("GP_ACCESS_TOKEN")

gopro_api-0.0.6.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: gopro-api
+Version: 0.0.6
+Summary: Unofficial Python client for the GoPro cloud API (api.gopro.com): sync and async clients, Pydantic models, and a CLI.
+Home-page: https://github.com/himewel/gopro-api
+Author: himewel
+Author-email: welberthime@gmail.com
+License: MIT
+Project-URL: Bug Tracker, https://github.com/himewel/gopro-api/issues
+Project-URL: Source, https://github.com/himewel/gopro-api
+Keywords: gopro quik cloud api async aiohttp media gopro-api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Digital Camera
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp~=3.11.14
+Requires-Dist: python-dotenv~=1.0.1
+Requires-Dist: pydantic~=2.10.6
+Requires-Dist: requests~=2.32.3
+Provides-Extra: dev
+Requires-Dist: build~=1.0.0; extra == "dev"
+Requires-Dist: black~=24.10.0; extra == "dev"
+Requires-Dist: pylint~=3.3.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# gopro-api
+
+Unofficial Python client for the **GoPro cloud / Quik** HTTP API at [`api.gopro.com`](https://api.gopro.com): **search** your library and **fetch download metadata** (CDN URLs, filenames, variants). Built with **Pydantic** models, plus **sync** (`requests`) and **async** (`aiohttp`) clients and a small **`gopro-api`** CLI.
+
+This project is not affiliated with or endorsed by GoPro.
+
+## Features
+
+- **`GoProAPI`** — synchronous client (`requests`), `with` context manager  
+- **`AsyncGoProAPI`** — async client (`aiohttp`), `async with` context manager  
+- **Pydantic** request/response types in `gopro_api.api.models`  
+- **CLI** — `gopro-api search`, `gopro-api info`, `gopro-api pull`  
+- **`GP_ACCESS_TOKEN`** from environment / `.env` (browser cookie value)
+
+## Requirements
+
+- Python **3.10+**
+- **`GP_ACCESS_TOKEN`** — see [Configuration](#configuration)
+
+## Install
+
+From the repository root:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+From a local wheel (name matches your build):
+
+```bash
+pip install ./dist/gopro_api-*-py3-none-any.whl
+```
+
+Published package on PyPI (distribution name **`gopro-api`**, import **`gopro_api`**):
+
+```bash
+pip install gopro-api
+```
+
+## CLI
+
+After install, **`gopro-api`** is on your `PATH`:
+
+```bash
+gopro-api --help
+gopro-api --version
+gopro-api search --start 2026-03-01 --end 2026-03-03 --per-page 30
+gopro-api search --start 2026-03-01 --end 2026-03-03 --all-pages
+gopro-api search --start 2026-03-01 --end 2026-03-03 --json
+gopro-api info MEDIA_ID
+gopro-api info MEDIA_ID --json
+gopro-api pull MEDIA_ID ./downloads
+gopro-api pull MEDIA_ID ./downloads --height 1080
+gopro-api pull MEDIA_ID ./downloads --width 1920 --height 1080
+```
+
+| Command | Purpose |
+|--------|---------|
+| **`search`** | List media in a capture range. Default: one **id** per line. **`--json`**: full API-shaped response; with **`--all-pages`**, a JSON array of every page. |
+| **`info`** | Show download metadata for one media id (filename + file lines with size and URL), or **`--json`** for the full payload. |
+| **`pull`** | Download asset(s) for a media id into **`destination`** (directory; created if missing). Videos (`.mp4` extension, case-insensitive): one **`variations`** entry — **tallest** by default, or closest to **`--height`** / **`--width`** (sum of squared pixel deltas; ties broken by larger resolution). Photos: uses **`files`** (one request per file). |
+
+Global **`--timeout`** (seconds, default **`60`**) applies to API calls and to **`pull`** CDN downloads (`requests.get`).
+
+Run without an installed script:
+
+```bash
+python -m gopro_api.cli search --start 2026-03-01 --end 2026-03-02
+python -m gopro_api.cli info MEDIA_ID
+python -m gopro_api.cli pull MEDIA_ID ./out
+python -m gopro_api.cli pull MEDIA_ID ./out --height 720
+```
+
+## Configuration
+
+`gopro_api.config` loads **`.env`** from the current working directory and reads **`GP_ACCESS_TOKEN`**.
+
+Example `.env`:
+
+```env
+GP_ACCESS_TOKEN=your_token_here
+```
+
+The clients send it as a cookie: `gp_access_token=<value>`. Put **only the token string** in `GP_ACCESS_TOKEN` (not the `gp_access_token=` prefix).
+
+You can override the token in code: `GoProAPI(access_token="...")` or `AsyncGoProAPI(access_token="...")`.
+
+### Retrieving `gp_access_token` from your browser
+
+Sign in to the GoPro web app (e.g. [gopro.com](https://gopro.com) media / Quik). The site sets a cookie **`gp_access_token`**.
+
+**Chrome / Edge / Brave**
+
+1. Open the site while logged in.  
+2. **F12** → **Application** → **Cookies** → choose the origin (often `https://quik.gopro.com` or another `*.gopro.com` host).  
+3. Copy the **Value** of **`gp_access_token`**.
+
+**Firefox**
+
+**F12** → **Storage** → **Cookies** → same idea.
+
+**Network panel (Chromium)**
+
+1. **Network** → trigger requests to **`api.gopro.com`**.  
+2. Pick a request → **Headers** → **Cookie**.  
+3. Copy the value after `gp_access_token=` up to the next `;` (or end of string).
+
+**Notes**
+
+- If the cookie is **HttpOnly**, use the **Network** method.  
+- Tokens **expire**; refresh from the browser if you get **401**.  
+- Treat the token like a password.
+
+**Security:** Do not commit `.env` or tokens. Keep `.env` in `.gitignore`.
+
+## Library usage
+
+### Async (`AsyncGoProAPI`)
+
+```python
+import asyncio
+from datetime import datetime
+
+from gopro_api.api import AsyncGoProAPI
+from gopro_api.api.models import CapturedRange, GoProMediaSearchParams
+
+
+async def main() -> None:
+    params = GoProMediaSearchParams(
+        captured_range=CapturedRange(
+            start=datetime.fromisoformat("2026-03-01"),
+            end=datetime.fromisoformat("2026-03-02"),
+        ),
+        per_page=50,
+        page=1,
+    )
+
+    async with AsyncGoProAPI() as api:
+        search = await api.search(params)
+        for item in search.embedded.media:
+            meta = await api.download(item.id)
+            print(meta.filename, len(meta.embedded.files), "files")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Sync (`GoProAPI`)
+
+```python
+from datetime import datetime
+
+from gopro_api.api import GoProAPI
+from gopro_api.api.models import CapturedRange, GoProMediaSearchParams
+
+
+def main() -> None:
+    params = GoProMediaSearchParams(
+        captured_range=CapturedRange(
+            start=datetime.fromisoformat("2026-03-01"),
+            end=datetime.fromisoformat("2026-03-02"),
+        ),
+        per_page=50,
+        page=1,
+    )
+
+    with GoProAPI() as api:
+        search = api.search(params)
+        for item in search.embedded.media:
+            meta = api.download(item.id)
+            print(meta.filename, len(meta.embedded.files), "files")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+### Models
+
+- **Requests:** `GoProMediaSearchParams`, `CapturedRange`, etc. in **`gopro_api.api.models`**.  
+- **Responses:** search and download JSON shapes (including `_embedded` / `_pages` aliases).
+
+List fields in search params are serialized to comma-separated strings when you call **`model_dump()`** (used by the HTTP clients).
+
+## Project layout
+
+| Path | Role |
+|------|------|
+| `gopro_api/api/gopro.py` | `GoProAPI` — sync `search`, `download` |
+| `gopro_api/api/async_gopro.py` | `AsyncGoProAPI` — async `search`, `download` |
+| `gopro_api/api/models.py` | Pydantic request/response models |
+| `gopro_api/api/__init__.py` | Re-exports `GoProAPI`, `AsyncGoProAPI` |
+| `gopro_api/config.py` | `load_dotenv`, `GP_ACCESS_TOKEN` |
+| `gopro_api/cli.py` | `gopro-api` CLI |
+| `setup.py` | Package metadata, dependencies, console entry point |
+
+## CI and releases
+
+[`.github/workflows/release.yml`](.github/workflows/release.yml):
+
+- **Push to `main`** — builds wheel + source `.zip`, uploads **workflow artifacts**.  
+- **Push tag `v*`** (e.g. `v0.0.5`) — attaches the same files to a **GitHub Release**.
+
+## License
+
+[MIT License](LICENSE).
+
+GoPro, Quik, and related marks are trademarks of their respective owners.

gopro_api-0.0.6.dist-info/RECORD

@@ -0,0 +1,13 @@
+gopro_api/__init__.py,sha256=OF04vDQPWRwOxppyTxP6LjWcSlArjBcAh4viis_6yf0,72
+gopro_api/cli.py,sha256=3gMktNwQsCGHSbyseBXJ3m89sgIkLam5jbWI-fOqakU,10891
+gopro_api/config.py,sha256=MIKsKv95nzbISQSbL7MryE04zUiSrbNl6tFtku1hbhI,182
+gopro_api/api/__init__.py,sha256=CHBzJUwHYec4T--JiRp1u-SK4Oxwi9pXA1AnKX2c27E,163
+gopro_api/api/async_gopro.py,sha256=LreKyDhUvQbucjIxihodbS0A7i8ry32aDlEMqx4rJyU,3487
+gopro_api/api/gopro.py,sha256=PsnomdSlSF_tKQWbyyb8K1FVeOxDYdvnZEobQAdx8Ck,3227
+gopro_api/api/models.py,sha256=igLHjcpYwyxrC2U4kIsv21_uQoxiB3KZ1PF5ZPtxy5U,4142
+gopro_api-0.0.6.dist-info/licenses/LICENSE,sha256=o8Gx-7kDb40cl02Zh-vwDIi7cSA72W7-MhSpjf0DazM,1064
+gopro_api-0.0.6.dist-info/METADATA,sha256=qIPNoitm03KK29rtD7euYHXtzL7_YMdANekPd4DGKpc,8776
+gopro_api-0.0.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gopro_api-0.0.6.dist-info/entry_points.txt,sha256=HA98CKe5NaBbf6oxIGmvrOD8H-nMef7fTMtn9-Xa4aA,49
+gopro_api-0.0.6.dist-info/top_level.txt,sha256=0kYRNrDZ3FffqZmUuq8VG5VB6HKSdSvAtYi6AatvNVY,10
+gopro_api-0.0.6.dist-info/RECORD,,

gopro_api-0.0.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gopro_api-0.0.6.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gopro-api = gopro_api.cli:main

gopro_api-0.0.6.dist-info/licenses/LICENSE

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

gopro_api-0.0.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+gopro_api