publicdotcom-cli 1.0.0__py3-none-any.whl

publicdotcom_cli/client.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+class MissingTokenError(RuntimeError):
+    """Raised when a secured API endpoint is called without an access token."""
+
+
+@dataclass
+class ApiError(RuntimeError):
+    method: str
+    path: str
+    status_code: int
+    body: Any
+
+    def __str__(self) -> str:
+        return f"{self.method.upper()} {self.path} failed with HTTP {self.status_code}"
+
+
+def _response_body(response: httpx.Response) -> Any:
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return response.text
+
+
+def compact_params(params: dict[str, Any] | None) -> list[tuple[str, Any]]:
+    if not params:
+        return []
+
+    compacted: list[tuple[str, Any]] = []
+    for key, value in params.items():
+        if value is None or value == []:
+            continue
+        if isinstance(value, list):
+            compacted.extend((key, item) for item in value)
+        else:
+            compacted.append((key, value))
+    return compacted
+
+
+class ApiClient:
+    def __init__(self, *, base_url: str, token: str | None, timeout: float) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        authenticated: bool = True,
+    ) -> Any:
+        headers = {"Accept": "application/json"}
+        if authenticated:
+            if not self.token:
+                raise MissingTokenError(
+                    "No access token found. Run `public auth login` or set PUBLIC_ACCESS_TOKEN."
+                )
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        with httpx.Client(base_url=self.base_url, timeout=self.timeout) as client:
+            response = client.request(
+                method,
+                path,
+                params=compact_params(params),
+                json=json_body,
+                headers=headers,
+            )
+
+        body = _response_body(response)
+        if response.status_code >= 400:
+            raise ApiError(method=method, path=path, status_code=response.status_code, body=body)
+        return body

publicdotcom_cli/config.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from base64 import urlsafe_b64decode
+from binascii import Error as BinasciiError
+from pathlib import Path
+from typing import Any
+
+import keyring
+from keyring.errors import KeyringError
+from platformdirs import user_config_dir
+
+SERVICE_NAME = "publicdotcom-cli"
+TOKEN_USERNAME = "access-token"
+SECRET_USERNAME = "personal-secret"
+TOKEN_ENV_VAR = "PUBLIC_ACCESS_TOKEN"
+SECRET_ENV_VAR = "PUBLIC_PERSONAL_SECRET"
+ACCOUNT_ID_ENV_VAR = "PUBLIC_ACCOUNT_ID"
+BASE_URL_ENV_VAR = "PUBLIC_API_BASE_URL"
+AUTO_REFRESH_ENV_VAR = "PUBLIC_AUTO_REFRESH"
+DEFAULT_BASE_URL = "https://api.public.com"
+
+
+def token_file() -> Path:
+    return Path(user_config_dir("publicdotcom-cli", "publicdotcom")) / "token.json"
+
+
+def settings_file() -> Path:
+    return Path(user_config_dir("publicdotcom-cli", "publicdotcom")) / "settings.json"
+
+
+def _read_settings() -> dict[str, Any]:
+    path = settings_file()
+    if not path.exists():
+        return {}
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+    return data if isinstance(data, dict) else {}
+
+
+def _write_settings(settings: dict[str, Any]) -> str:
+    path = settings_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    path.chmod(0o600)
+    return str(path)
+
+
+def get_token() -> str | None:
+    env_token = os.getenv(TOKEN_ENV_VAR)
+    if env_token:
+        return env_token
+
+    try:
+        token = keyring.get_password(SERVICE_NAME, TOKEN_USERNAME)
+    except (KeyringError, RuntimeError, ImportError):
+        token = None
+
+    if token:
+        return token
+
+    path = token_file()
+    if not path.exists():
+        return None
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    token = data.get("accessToken")
+    return token if isinstance(token, str) and token else None
+
+
+def get_personal_secret() -> str | None:
+    env_secret = os.getenv(SECRET_ENV_VAR)
+    if env_secret:
+        return env_secret
+
+    try:
+        secret = keyring.get_password(SERVICE_NAME, SECRET_USERNAME)
+    except (KeyringError, RuntimeError, ImportError):
+        secret = None
+
+    if secret:
+        return secret
+
+    path = token_file().with_name("secret.json")
+    if not path.exists():
+        return None
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    secret = data.get("personalSecret")
+    return secret if isinstance(secret, str) and secret else None
+
+
+def get_default_account_id() -> str | None:
+    env_account_id = os.getenv(ACCOUNT_ID_ENV_VAR)
+    if env_account_id:
+        return env_account_id
+
+    account_id = _read_settings().get("defaultAccountId")
+    return account_id if isinstance(account_id, str) and account_id else None
+
+
+def set_token(token: str) -> str:
+    try:
+        keyring.set_password(SERVICE_NAME, TOKEN_USERNAME, token)
+        return "keyring"
+    except (KeyringError, RuntimeError, ImportError):
+        path = token_file()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"accessToken": token}, indent=2), encoding="utf-8")
+        path.chmod(0o600)
+        return str(path)
+
+
+def set_personal_secret(secret: str) -> str:
+    try:
+        keyring.set_password(SERVICE_NAME, SECRET_USERNAME, secret)
+        return "keyring"
+    except (KeyringError, RuntimeError, ImportError):
+        path = token_file().with_name("secret.json")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"personalSecret": secret}, indent=2), encoding="utf-8")
+        path.chmod(0o600)
+        return str(path)
+
+
+def set_default_account_id(account_id: str) -> str:
+    settings = _read_settings()
+    settings["defaultAccountId"] = account_id
+    return _write_settings(settings)
+
+
+def clear_token() -> None:
+    try:
+        keyring.delete_password(SERVICE_NAME, TOKEN_USERNAME)
+    except (KeyringError, RuntimeError, ImportError, keyring.errors.PasswordDeleteError):
+        pass
+
+    path = token_file()
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def clear_personal_secret() -> None:
+    try:
+        keyring.delete_password(SERVICE_NAME, SECRET_USERNAME)
+    except (KeyringError, RuntimeError, ImportError, keyring.errors.PasswordDeleteError):
+        pass
+
+    path = token_file().with_name("secret.json")
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def clear_default_account_id() -> None:
+    settings = _read_settings()
+    settings.pop("defaultAccountId", None)
+    path = settings_file()
+    if settings:
+        _write_settings(settings)
+        return
+
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def mask_token(token: str | None) -> str:
+    if not token:
+        return "not set"
+    if len(token) <= 12:
+        return "*" * len(token)
+    return f"{token[:6]}...{token[-6:]}"
+
+
+def _decode_jwt_payload(token: str) -> dict[str, Any] | None:
+    parts = token.split(".")
+    if len(parts) < 2:
+        return None
+
+    payload = parts[1]
+    payload += "=" * (-len(payload) % 4)
+    try:
+        decoded = urlsafe_b64decode(payload.encode("ascii"))
+        data = json.loads(decoded.decode("utf-8"))
+    except (BinasciiError, ValueError, UnicodeDecodeError):
+        return None
+
+    return data if isinstance(data, dict) else None
+
+
+def token_expires_soon(token: str | None, *, skew_seconds: int = 60) -> bool:
+    if not token:
+        return True
+
+    payload = _decode_jwt_payload(token)
+    if not payload:
+        return False
+
+    expires_at = payload.get("exp")
+    if not isinstance(expires_at, int | float):
+        return False
+
+    return expires_at <= time.time() + skew_seconds

publicdotcom_cli/output.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def print_json(data: Any) -> None:
+    console.print_json(json.dumps(data, default=str))
+
+
+def print_error(message: str) -> None:
+    err_console.print(f"[red]{message}[/red]")
+
+
+def print_accounts(data: Any) -> None:
+    accounts = data.get("accounts") if isinstance(data, dict) else None
+    if not accounts:
+        print_json(data)
+        return
+
+    table = Table(title="Accounts")
+    table.add_column("Account ID")
+    table.add_column("Type")
+    table.add_column("Brokerage")
+    table.add_column("Options")
+    table.add_column("Permissions")
+
+    for account in accounts:
+        table.add_row(
+            str(account.get("accountId", "")),
+            str(account.get("accountType", "")),
+            str(account.get("brokerageAccountType", "")),
+            str(account.get("optionsLevel", "")),
+            str(account.get("tradePermissions", "")),
+        )
+    console.print(table)
+
+
+def print_quotes(data: Any) -> None:
+    quotes = data.get("quotes") if isinstance(data, dict) else None
+    if not quotes:
+        print_json(data)
+        return
+
+    table = Table(title="Quotes")
+    table.add_column("Symbol")
+    table.add_column("Type")
+    table.add_column("Outcome")
+    table.add_column("Last", justify="right")
+    table.add_column("Bid", justify="right")
+    table.add_column("Ask", justify="right")
+    table.add_column("Volume", justify="right")
+
+    for quote in quotes:
+        instrument = quote.get("instrument") or {}
+        table.add_row(
+            str(instrument.get("symbol", "")),
+            str(instrument.get("type", "")),
+            str(quote.get("outcome", "")),
+            str(quote.get("last", "")),
+            str(quote.get("bid", "")),
+            str(quote.get("ask", "")),
+            str(quote.get("volume", "")),
+        )
+    console.print(table)
+
+
+def exit_with_error(message: str, code: int = 1) -> None:
+    print_error(message)
+    raise typer.Exit(code)

publicdotcom_cli/payloads.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+import sys
+import uuid
+from pathlib import Path
+from typing import Any, Iterable
+
+
+def load_json_file(path: Path) -> Any:
+    if str(path) == "-":
+        raw = sys.stdin.read()
+    else:
+        raw = path.read_text(encoding="utf-8")
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+
+
+def instrument(symbol: str, security_type: str) -> dict[str, str]:
+    return {"symbol": symbol.upper(), "type": security_type.upper()}
+
+
+def instruments(symbols: Iterable[str], security_type: str) -> list[dict[str, str]]:
+    return [instrument(symbol, security_type) for symbol in symbols]
+
+
+def ensure_order_id(body: dict[str, Any]) -> str:
+    order_id = body.get("orderId")
+    if isinstance(order_id, str) and order_id:
+        return order_id
+    order_id = str(uuid.uuid4())
+    body["orderId"] = order_id
+    return order_id

publicdotcom_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: publicdotcom-cli
+Version: 1.0.0
+Summary: Command-line client for the Public.com Trading API
+Project-URL: Homepage, https://github.com/publicdotcom/publicdotcom-cli
+Project-URL: Repository, https://github.com/publicdotcom/publicdotcom-cli
+Project-URL: Issues, https://github.com/publicdotcom/publicdotcom-cli/issues
+Project-URL: Public.com API, https://public.com/api
+Author-email: "Public.com" <developers@public.com>
+Maintainer-email: "Public.com" <developers@public.com>
+License-Expression: Apache-2.0
+Keywords: api,brokerage,cli,crypto,options,public.com,stocks,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.2.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.16.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.11.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# publicdotcom-cli
+
+Command-line client for the Public.com Trading API.
+
+Use `public` to authenticate, inspect accounts, retrieve portfolio and market data, run
+preflight checks, and submit order-related requests from your terminal.
+
+## Install
+
+The recommended installation method for command-line Python tools is `pipx`:
+
+```bash
+pipx install publicdotcom-cli
+```
+
+You can also install with `uv`:
+
+```bash
+uv tool install publicdotcom-cli
+```
+
+Confirm the CLI is available:
+
+```bash
+public --help
+```
+
+## Quick Start
+
+Generate a personal secret from your Public.com settings, then authenticate:
+
+```bash
+public auth login
+public accounts list
+public accounts set-default ACCOUNT_ID
+public portfolio show
+public market quotes AAPL MSFT
+```
+
+Most account-scoped commands use the configured default account. You can override it with
+`--account-id ACCOUNT_ID` or `PUBLIC_ACCOUNT_ID=ACCOUNT_ID`.
+
+## Important Disclosures
+
+This CLI is a developer tool for interacting with the Public API. It is not investment,
+financial, legal, tax, accounting, or trading advice, and it does not recommend any
+security, strategy, account type, order type, or transaction.
+
+Trading involves risk, including the possible loss of principal. You are responsible for
+reviewing all request payloads, account IDs, symbols, quantities, prices, order sides,
+time-in-force values, and other order instructions before submitting a trading command.
+
+Order placement, replacement, and cancellation requests may be asynchronous. A successful
+API response confirms submission to the API, not execution, cancellation, fill price,
+availability, or final order state. Always verify order status after submitting,
+replacing, or cancelling an order.
+
+Market data, quotes, option chains, greeks, account data, and preflight calculations are
+provided for informational and operational use through the API. They may be incomplete,
+delayed, unavailable, or different from final execution values.
+
+You are responsible for complying with all applicable laws, regulations, exchange rules,
+API terms, account agreements, and internal policies that apply to your use of this CLI.
+Do not use this tool unless you are authorized to access the relevant account and API
+credentials.
+
+Personal secrets and access tokens can authorize account access and trading activity.
+Keep them private, do not commit them to source control, and rotate or revoke them if
+you believe they were exposed.
+
+## Authenticate
+
+Generate a personal secret from Public, then run:
+
+```bash
+public auth login
+```
+
+The access token is stored with your OS keychain when available. If no keychain backend
+is available, the CLI falls back to a user-only config file.
+
+Access tokens are short-lived. To let the CLI refresh them automatically, opt in to
+storing your personal secret:
+
+```bash
+public auth login --store-secret
+```
+
+Because the personal secret is long-lived, this is optional. The CLI stores it in your
+OS keychain when available, otherwise it falls back to a user-only config file.
+
+After that, secured commands automatically mint a fresh access token before the current
+token expires or after a `401 Unauthorized` response. You can also refresh manually:
+
+```bash
+public auth refresh
+```
+
+You can also bypass stored credentials for automation:
+
+```bash
+PUBLIC_ACCESS_TOKEN=ey... public accounts list
+PUBLIC_PERSONAL_SECRET=... public accounts list
+```
+
+Remove stored credentials with:
+
+```bash
+public auth logout
+public auth logout --all
+```
+
+## Default Account
+
+Most API operations require the `accountId` returned by `public accounts list`. You can
+store a default account once:
+
+```bash
+public accounts set-default ACCOUNT_ID
+public accounts get-default
+```
+
+Then omit `--account-id` from account-scoped commands:
+
+```bash
+public portfolio show
+public market quotes AAPL MSFT
+public order get ORDER_ID
+```
+
+You can override the default at any time:
+
+```bash
+public portfolio show --account-id ACCOUNT_ID
+PUBLIC_ACCOUNT_ID=ACCOUNT_ID public portfolio show
+public accounts clear-default
+```
+
+## Example Commands
+
+```bash
+public accounts list
+public accounts set-default ACCOUNT_ID
+public portfolio show
+public history list --page-size 25
+public instruments get AAPL EQUITY
+public market quotes AAPL MSFT --type EQUITY
+public market option-expirations AAPL
+public market option-chain AAPL 2026-05-15
+public options greeks "AAPL  260515C00200000"
+```
+
+Trading requests use JSON files so the exact payload is visible before submission:
+
+```bash
+public order preflight-single --file examples/order.single-leg.market-buy.json
+public order place --file examples/order.single-leg.market-buy.json
+public order get ORDER_ID
+public order cancel ORDER_ID
+```
+
+Trading commands prompt before submitting order placement, replacement, or cancellation
+requests. Use `--yes` only when your automation has already performed equivalent
+validation and approval.
+
+## JSON Output
+
+Use `--json` before the command group to print raw JSON:
+
+```bash
+public --json accounts list
+public --json market quotes AAPL MSFT
+```
+
+## Configuration
+
+The CLI supports these environment variables:
+
+```bash
+PUBLIC_ACCESS_TOKEN=...
+PUBLIC_PERSONAL_SECRET=...
+PUBLIC_ACCOUNT_ID=...
+PUBLIC_API_BASE_URL=https://api.public.com
+PUBLIC_AUTO_REFRESH=true
+```
+
+`PUBLIC_API_BASE_URL` is optional and defaults to `https://api.public.com`.
+
+## Upgrade
+
+```bash
+pipx upgrade publicdotcom-cli
+# or
+uv tool upgrade publicdotcom-cli
+```
+
+## Development
+
+For local development from a checkout:
+
+```bash
+uv sync --extra dev
+uv run public --help
+uv run pytest
+```
+
+## Regenerate The OpenAPI Client
+
+The package ships with a generated API client. Contributors who need to regenerate it
+must place the local OpenAPI spec at the repository root as `spec.yaml`, then run:
+
+```bash
+uv run python scripts/generate_client.py
+```
+
+The raw spec uses `*/*` for many JSON responses, which some Python generators do not
+parse as JSON. The regeneration script normalizes those response content types before
+running `openapi-python-client`. This requires network access the first time because it
+uses `uvx openapi-python-client`.