pico-store-lab 0.1.2__tar.gz

pico_store_lab-0.1.2/.gitignore

@@ -0,0 +1,19 @@
+node_modules/
+apps/website/.local/
+apps/website/.wrangler/
+apps/android/.gradle/
+apps/android/build/
+apps/android/app/build/
+packages/ts/dist/
+packages/python/dist/
+__pycache__/
+*.pyc
+target/
+packages/kotlin/build/
+build/
+dist/
+*.apk
+*.part
+*.auth.json
+*mirror-config.json
+.DS_Store

pico_store_lab-0.1.2/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: pico-store-lab
+Version: 0.1.2
+Summary: PICO app search, sign-in, and downloads for Python and the command line
+Project-URL: Repository, https://github.com/nkanf-dev/pico-store-lab
+Project-URL: Issues, https://github.com/nkanf-dev/pico-store-lab/issues
+Author: PICO Store Lab contributors
+License-Expression: MIT
+Keywords: pico,sdk,store,vr
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Requires-Dist: keyring<26,>=25.6
+Description-Content-Type: text/markdown
+
+# PICO Store Lab — Python SDK
+
+PICO app search, sign-in, and downloads for Python, with a `pico-store-py` command-line tool for Windows, macOS, and Linux. This package is part of [PICO Store Lab](https://github.com/nkanf-dev/pico-store-lab).
+
+Install with `python -m pip install pico-store-lab`.
+
+```python
+from pathlib import Path
+from pico_store_lab import PicoStoreClient, StoreTarget
+
+client = PicoStoreClient()
+found = client.search("YouTube VR").items[0]
+target = StoreTarget(found.item_id, found.package_name)
+client.item(target)
+client.send_code(email)
+auth = client.login(email, code_from_user)
+client.download(target, auth, Path("selected-app.apk"))
+```
+
+Configure the request identity and region with `StoreConfig`:
+
+```python
+from pico_store_lab import StoreConfig
+
+client = PicoStoreClient(
+    config=StoreConfig(
+        device_name="YOUR_DEVICE", language="en", zone="Europe/London", web_region="uk"
+    )
+)
+```
+
+Other fields include `store_host`, `account_host`, `web_store_host`, `manifest_version_code`, `app_id`, `client_type`, `passport_aid`, and `device_platform`. The default profile reflects the observed A9210/Japanese-language overseas-store requests. Select any exact `StoreTarget` from search. `download()` confirms ownership, acquires an available free offer if necessary, then gets the APK metadata. Paid offers are purchased on the official store.
+
+`email` and `code_from_user` come from your app's UI. `PicoStoreClient` performs the requests and verified download; pass a custom transport if you need different HTTP behavior. Low-level builders and parsers remain public. Use `pico-store-py --help` for the smaller CLI surface.
+
+The [player guide](https://github.com/nkanf-dev/pico-store-lab#player-guide) gives the complete `search` → `status` → `send-code` → `login` → `download` command sequence, including device installation.

pico_store_lab-0.1.2/README.md

@@ -0,0 +1,36 @@
+# PICO Store Lab — Python SDK
+
+PICO app search, sign-in, and downloads for Python, with a `pico-store-py` command-line tool for Windows, macOS, and Linux. This package is part of [PICO Store Lab](https://github.com/nkanf-dev/pico-store-lab).
+
+Install with `python -m pip install pico-store-lab`.
+
+```python
+from pathlib import Path
+from pico_store_lab import PicoStoreClient, StoreTarget
+
+client = PicoStoreClient()
+found = client.search("YouTube VR").items[0]
+target = StoreTarget(found.item_id, found.package_name)
+client.item(target)
+client.send_code(email)
+auth = client.login(email, code_from_user)
+client.download(target, auth, Path("selected-app.apk"))
+```
+
+Configure the request identity and region with `StoreConfig`:
+
+```python
+from pico_store_lab import StoreConfig
+
+client = PicoStoreClient(
+    config=StoreConfig(
+        device_name="YOUR_DEVICE", language="en", zone="Europe/London", web_region="uk"
+    )
+)
+```
+
+Other fields include `store_host`, `account_host`, `web_store_host`, `manifest_version_code`, `app_id`, `client_type`, `passport_aid`, and `device_platform`. The default profile reflects the observed A9210/Japanese-language overseas-store requests. Select any exact `StoreTarget` from search. `download()` confirms ownership, acquires an available free offer if necessary, then gets the APK metadata. Paid offers are purchased on the official store.
+
+`email` and `code_from_user` come from your app's UI. `PicoStoreClient` performs the requests and verified download; pass a custom transport if you need different HTTP behavior. Low-level builders and parsers remain public. Use `pico-store-py --help` for the smaller CLI surface.
+
+The [player guide](https://github.com/nkanf-dev/pico-store-lab#player-guide) gives the complete `search` → `status` → `send-code` → `login` → `download` command sequence, including device installation.

pico_store_lab-0.1.2/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pico-store-lab"
+version = "0.1.2"
+description = "PICO app search, sign-in, and downloads for Python and the command line"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["keyring>=25.6,<26"]
+license = "MIT"
+authors = [{ name = "PICO Store Lab contributors" }]
+keywords = ["pico", "vr", "sdk", "store"]
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
+
+[project.urls]
+Repository = "https://github.com/nkanf-dev/pico-store-lab"
+Issues = "https://github.com/nkanf-dev/pico-store-lab/issues"
+
+[project.scripts]
+pico-store-py = "pico_store_lab.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pico_store_lab"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "D", "UP", "B", "ANN"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

pico_store_lab-0.1.2/src/pico_store_lab/__init__.py

@@ -0,0 +1,79 @@
+"""Typed PICO store protocol and mirror policy SDK."""
+
+from pico_store_lab.client import (
+    PicoStoreClient,
+    StoreResponse,
+    download_verified_apk,
+    send_request,
+)
+from pico_store_lab.mirror import (
+    DEFAULT_MIRROR_POLICY,
+    MirrorDecision,
+    MirrorPolicy,
+    mirror_decision,
+)
+from pico_store_lab.protocol import (
+    ACCOUNT_HOST,
+    DEFAULT_TARGET,
+    OFFICIAL_STORE_URL,
+    PICO_ITEM_ID,
+    PICO_PACKAGE,
+    STORE_HOST,
+    DownloadInfo,
+    PicoAuth,
+    PublicItem,
+    RequestSpec,
+    SearchItem,
+    SearchResults,
+    StoreConfig,
+    StoreTarget,
+    encode_account_field,
+    make_account_item_request,
+    make_account_request,
+    make_download_info_request,
+    make_free_acquisition_request,
+    make_public_item_request,
+    make_search_request,
+    parse_download_info,
+    parse_free_acquisition,
+    parse_official_json,
+    parse_public_item,
+    parse_search_results,
+)
+
+__all__ = [
+    "ACCOUNT_HOST",
+    "DEFAULT_MIRROR_POLICY",
+    "OFFICIAL_STORE_URL",
+    "PICO_ITEM_ID",
+    "PICO_PACKAGE",
+    "STORE_HOST",
+    "DEFAULT_TARGET",
+    "DownloadInfo",
+    "MirrorDecision",
+    "MirrorPolicy",
+    "PicoAuth",
+    "PicoStoreClient",
+    "PublicItem",
+    "RequestSpec",
+    "StoreTarget",
+    "StoreConfig",
+    "make_account_item_request",
+    "make_free_acquisition_request",
+    "parse_free_acquisition",
+    "StoreResponse",
+    "SearchItem",
+    "SearchResults",
+    "download_verified_apk",
+    "encode_account_field",
+    "make_account_request",
+    "make_download_info_request",
+    "make_public_item_request",
+    "make_search_request",
+    "mirror_decision",
+    "parse_download_info",
+    "parse_official_json",
+    "parse_public_item",
+    "parse_search_results",
+    "send_request",
+]

pico_store_lab-0.1.2/src/pico_store_lab/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m pico_store_lab` as a zero-install CLI."""
+
+from pico_store_lab.cli import main
+
+raise SystemExit(main())

pico_store_lab-0.1.2/src/pico_store_lab/cli.py

@@ -0,0 +1,116 @@
+"""Small bilingual command-line client built on the Python SDK."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+from pathlib import Path
+
+from pico_store_lab import credentials
+from pico_store_lab.client import PicoStoreClient
+from pico_store_lab.protocol import StoreTarget
+
+MESSAGES = {
+    "en": {
+        "sent": "PICO verification email sent.",
+        "saved": "Signed in.",
+        "downloaded": "Downloaded: {path}",
+        "signed_out": "Signed out.",
+        "error": "Error: {message}",
+    },
+    "zh-CN": {
+        "sent": "PICO 验证码邮件已发送。",
+        "saved": "已登录。",
+        "downloaded": "已下载：{path}",
+        "signed_out": "已退出登录。",
+        "error": "错误：{message}",
+    },
+}
+
+
+def _message(locale: str, key: str, **values: str) -> str:
+    return MESSAGES[locale][key].format(**values)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the stable CLI argument parser."""
+    parser = argparse.ArgumentParser(prog="pico-store-py", description="PICO Store Lab Python CLI")
+    parser.add_argument("--locale", choices=("en", "zh-CN"), default="en")
+    sub = parser.add_subparsers(dest="command", required=True)
+    search = sub.add_parser("search", help="Search official PICO apps")
+    search.add_argument("word")
+    status = sub.add_parser("status", help="Show an official PICO item")
+    status.add_argument("--item-id", required=True)
+    status.add_argument("--package", required=True)
+    send = sub.add_parser("send-code", help="Send a PICO email code")
+    send.add_argument("--email", required=True)
+    login = sub.add_parser("login", help="Sign in to your PICO international account")
+    login.add_argument("--email", required=True)
+    sub.add_parser("logout", help="Sign out")
+    download = sub.add_parser("download", help="Download an app")
+    download.add_argument("--output", required=True, type=Path)
+    download.add_argument("--item-id", required=True)
+    download.add_argument("--package", required=True)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one command; return a process exit status without leaking credentials."""
+    args = build_parser().parse_args(argv)
+    client = PicoStoreClient()
+    try:
+        if args.command == "search":
+            result = client.search(args.word)
+            print(
+                json.dumps(
+                    [
+                        {
+                            "name": item.name,
+                            "itemId": item.item_id,
+                            "packageName": item.package_name,
+                            "versionCode": item.version_code,
+                        }
+                        for item in result.items
+                    ],
+                    indent=2,
+                )
+            )
+        elif args.command == "status":
+            target = StoreTarget(args.item_id, args.package)
+            item = client.item(target)
+            print(
+                json.dumps(
+                    {
+                        "name": item.name,
+                        "versionCode": item.version_code,
+                        "price": item.price,
+                        "officialUrl": item.official_url,
+                    },
+                    indent=2,
+                )
+            )
+        elif args.command == "send-code":
+            client.send_code(args.email)
+            print(_message(args.locale, "sent"))
+        elif args.command == "login":
+            code = getpass.getpass("PICO email code: ")
+            auth = client.login(args.email, code)
+            credentials.save(auth)
+            print(_message(args.locale, "saved"))
+        elif args.command == "logout":
+            credentials.clear()
+            print(_message(args.locale, "signed_out"))
+        elif args.command == "download":
+            target = StoreTarget(args.item_id, args.package)
+            client.download(target, credentials.load(), args.output)
+            print(_message(args.locale, "downloaded", path=str(args.output)))
+    except (OSError, ValueError, RuntimeError) as error:
+        print(_message(args.locale, "error", message=str(error)), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pico_store_lab-0.1.2/src/pico_store_lab/client.py

@@ -0,0 +1,227 @@
+"""Composable network client for the complete PICO store acquisition flow."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from email.message import Message
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from pico_store_lab.protocol import (
+    DEFAULT_CONFIG,
+    DownloadInfo,
+    PicoAuth,
+    PublicItem,
+    RequestSpec,
+    SearchResults,
+    StoreConfig,
+    StoreTarget,
+    make_account_item_request,
+    make_account_request,
+    make_download_info_request,
+    make_free_acquisition_request,
+    make_public_item_request,
+    make_search_request,
+    parse_download_info,
+    parse_free_acquisition,
+    parse_official_json,
+    parse_public_item,
+    parse_search_results,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class StoreResponse:
+    """Decoded API payload and raw response headers."""
+
+    data: object
+    headers: Message
+
+
+Transport = Callable[[RequestSpec, int], StoreResponse]
+
+
+def send_request(spec: RequestSpec, retries: int = 3) -> StoreResponse:
+    """Send a protocol request with bounded retries for transient failures."""
+    if retries < 1:
+        raise ValueError("at least one request attempt required")
+    last_error: Exception | None = None
+    for attempt in range(retries):
+        request = Request(
+            spec.url, data=spec.body.encode("utf-8"), headers=spec.headers, method=spec.method
+        )
+        try:
+            with urlopen(request, timeout=25) as response:  # noqa: S310 - SDK selects official URLs
+                body = response.read(4 * 1024 * 1024 + 1)
+                if len(body) > 4 * 1024 * 1024:
+                    raise RuntimeError("PICO response exceeds 4 MiB")
+                return StoreResponse(parse_official_json(body.decode()), response.headers)
+        except HTTPError as error:
+            if error.code < 500 and error.code != 429:
+                raise RuntimeError(f"PICO HTTP {error.code}") from error
+            last_error = error
+        except URLError as error:
+            last_error = error
+        if attempt + 1 < retries:
+            time.sleep(min(attempt + 1, 5))
+    raise RuntimeError(f"PICO request failed: {last_error}")
+
+
+def _account_data(response: StoreResponse) -> dict[str, object]:
+    data = response.data
+    if not isinstance(data, dict) or data.get("message") != "success":
+        raise RuntimeError("PICO account request rejected")
+    body = data.get("data")
+    return body if isinstance(body, dict) else {}
+
+
+def download_verified_apk(info: DownloadInfo, output: Path, retries: int = 8) -> Path:
+    """Download official APK bytes and verify the provided MD5 before publishing a file."""
+    if retries < 1:
+        raise ValueError("at least one download attempt required")
+    if output.suffix.lower() != ".apk" or output.exists():
+        raise ValueError("new .apk output path required")
+    temporary = output.with_name(f"{output.stem}.part.apk")
+    last_error: Exception | None = None
+    for attempt in range(retries):
+        digest = hashlib.md5()  # noqa: S324 - official APK metadata supplies MD5
+        try:
+            with urlopen(info.url, timeout=60) as response:  # noqa: S310 - validated HTTPS URL
+                with temporary.open("wb") as stream:
+                    while chunk := response.read(65536):
+                        digest.update(chunk)
+                        stream.write(chunk)
+            if digest.hexdigest() != info.md5:
+                temporary.unlink(missing_ok=True)
+                raise ValueError("APK digest mismatch")
+            os.link(temporary, output)
+            temporary.unlink()
+            return output
+        except (OSError, URLError) as error:
+            last_error = error
+            if attempt + 1 < retries:
+                time.sleep(min(attempt + 1, 5))
+    raise RuntimeError(f"APK download failed: {last_error}")
+
+
+class PicoStoreClient:
+    """High-level SDK interface; callers may replace transport at any point."""
+
+    def __init__(
+        self, transport: Transport = send_request, config: StoreConfig = DEFAULT_CONFIG
+    ) -> None:
+        """Use the standard HTTP transport unless one is injected."""
+        self.transport = transport
+        self.config = config
+
+    def search(self, word: str, next_id: int = 1) -> SearchResults:
+        """Search the official public app catalog."""
+        response = self.transport(
+            make_search_request(
+                word, next_id=next_id, language=self.config.language, config=self.config
+            ),
+            3,
+        )
+        return parse_search_results(response.data)
+
+    def item(self, target: StoreTarget, auth: PicoAuth | None = None) -> PublicItem:
+        """Read and validate public metadata for the selected app."""
+        request = (
+            make_account_item_request(auth, target, self.config)
+            if auth
+            else make_public_item_request(
+                target=target,
+                language=self.config.language,
+                zone=self.config.zone,
+                config=self.config,
+            )
+        )
+        response = self.transport(request, 3)
+        return parse_public_item(response.data, target, self.config)
+
+    def acquire_free(self, item: PublicItem, auth: PicoAuth) -> str:
+        """Request a free app for the signed-in account."""
+        return parse_free_acquisition(
+            self.transport(make_free_acquisition_request(auth, item, self.config), 1).data
+        )
+
+    def ensure_entitlement(self, target: StoreTarget, auth: PicoAuth) -> PublicItem:
+        """Confirm ownership or acquire a free offer before downloading."""
+        current = self.item(target, auth)
+        if current.entitlement_status == 1:
+            return current
+        if current.offer_exists is not True:
+            raise RuntimeError("PICO has no offer for this account region")
+        if not re.fullmatch(r"0(?:\.0+)?", current.price):
+            raise RuntimeError("PICO app is not free or already owned")
+        acquisition_error: Exception | None = None
+        try:
+            self.acquire_free(current, auth)
+        except Exception as error:
+            acquisition_error = error
+        for attempt in range(3):
+            try:
+                updated = self.item(target, auth)
+            except Exception as error:
+                if attempt == 2:
+                    if acquisition_error is not None:
+                        raise acquisition_error from error
+                    raise
+                time.sleep(0.4)
+                continue
+            if updated.entitlement_status == 1:
+                return updated
+            if attempt < 2:
+                time.sleep(0.4)
+        if acquisition_error is not None:
+            raise acquisition_error
+        raise RuntimeError("PICO entitlement was not confirmed after free acquisition")
+
+    def send_code(self, email: str) -> None:
+        """Send one PICO email verification code."""
+        _account_data(
+            self.transport(make_account_request("send-code", email, config=self.config), 1)
+        )
+
+    def login(self, email: str, code: str) -> PicoAuth:
+        """Exchange the email code for the caller's PICO account session."""
+        response = self.transport(make_account_request("login", email, code, self.config), 1)
+        data = _account_data(response)
+        cookies: dict[str, str] = {}
+        for line in response.headers.get_all("Set-Cookie", []):
+            key, separator, value = line.split(";", 1)[0].partition("=")
+            if separator:
+                cookies[key] = value
+        auth = PicoAuth(
+            str(data.get("user_id_str") or data.get("user_id") or "0"),
+            str(response.headers.get("x-tt-token", "")),
+            cookies,
+        )
+        if not auth.x_tt_token and not auth.cookies:
+            raise RuntimeError("PICO login returned no usable session")
+        return auth
+
+    def download_info(self, target: StoreTarget, auth: PicoAuth) -> DownloadInfo:
+        """Read download metadata authorized for the caller's own account."""
+        response = self.transport(
+            make_download_info_request(
+                auth,
+                target=target,
+                language=self.config.language,
+                zone=self.config.zone,
+                config=self.config,
+            ),
+            3,
+        )
+        return parse_download_info(response.data, target)
+
+    def download(self, target: StoreTarget, auth: PicoAuth, output: Path) -> Path:
+        """Get and verify an official APK in one call."""
+        self.ensure_entitlement(target, auth)
+        return download_verified_apk(self.download_info(target, auth), output)

pico_store_lab-0.1.2/src/pico_store_lab/credentials.py

@@ -0,0 +1,81 @@
+"""Account persistence through the platform credential store."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from keyring.backend import KeyringBackend
+
+from pico_store_lab.protocol import PicoAuth
+
+SERVICE = "dev.nkanf.picostore.python"
+ACCOUNT = "current"
+
+
+def _backend() -> KeyringBackend:
+    # Select native stores directly: never load a configured plaintext/null backend.
+    if sys.platform == "darwin":
+        from keyring.backends.macOS import Keyring
+
+        return Keyring()
+    if sys.platform == "win32":
+        from keyring.backends.Windows import WinVaultKeyring
+
+        return WinVaultKeyring()
+    if sys.platform.startswith("linux"):
+        from keyring.backends.SecretService import Keyring
+
+        return Keyring()
+    raise RuntimeError("Sign-in requires Windows, macOS, or Linux.")
+
+
+def save(auth: PicoAuth) -> None:
+    """Save a usable account session."""
+    if not auth.x_tt_token and not auth.cookies:
+        raise ValueError("Sign-in returned no usable session. Please sign in again.")
+    value = json.dumps({"uid": auth.uid, "x_tt_token": auth.x_tt_token, "cookies": auth.cookies})
+    try:
+        _backend().set_password(SERVICE, ACCOUNT, value)
+    except Exception:
+        raise RuntimeError(
+            "Unable to save sign-in. Unlock the system credential store and try again."
+        ) from None
+
+
+def load() -> PicoAuth:
+    """Read the current account session."""
+    try:
+        raw = _backend().get_password(SERVICE, ACCOUNT)
+    except Exception:
+        raise RuntimeError(
+            "Unable to read sign-in. Unlock the system credential store and try again."
+        ) from None
+    if raw is None:
+        raise ValueError("Please run pico-store-py login first.")
+    try:
+        data = json.loads(raw)
+        if not isinstance(data, dict) or not isinstance(data.get("cookies", {}), dict):
+            raise ValueError
+        auth = PicoAuth(
+            str(data.get("uid", "0")),
+            str(data.get("x_tt_token", "")),
+            {str(key): str(value) for key, value in data.get("cookies", {}).items()},
+        )
+        if not auth.x_tt_token and not auth.cookies:
+            raise ValueError
+    except (ValueError, TypeError):
+        raise ValueError("Sign-in could not be read. Please sign in again.") from None
+    return auth
+
+
+def clear() -> None:
+    """Remove the current account session."""
+    try:
+        backend = _backend()
+        if backend.get_password(SERVICE, ACCOUNT) is not None:
+            backend.delete_password(SERVICE, ACCOUNT)
+    except Exception:
+        raise RuntimeError(
+            "Could not sign out. Unlock the system credential store and try again."
+        ) from None