nexusquant-cli 0.1.0__tar.gz

nexusquant_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/

nexusquant_cli-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: nexusquant-cli
+Version: 0.1.0
+Summary: NexusQuant strategy provider CLI
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# nexusquant-cli
+
+Command line tool for NexusQuant strategy providers.
+
+It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus strategy provider APIs. Provider commands require a Cognito user with `custom:userType=strategyProvider` or `custom:userType=admin`.
+
+## Install
+
+```bash
+python3 -m pip install -e .
+```
+
+## Login
+
+```bash
+nexusquant auth
+nexusquant auth --status
+nexusquant auth --refresh
+nexusquant auth --logout
+```
+
+Tokens are stored in the current OS user's config directory, for example `~/Library/Application Support/nexusquant-cli/credentials.json` on macOS. The file is written with `0600` permissions when supported.
+
+## Strategy Commands
+
+Create or update a strategy:
+
+```bash
+nexusquant strategy create \
+  --strategy-id my_alpha_001 \
+  --name "My Alpha" \
+  --schema-file schema.json \
+  --output-unit SHARE_COUNT
+```
+
+List strategies registered by the current provider. Admin users see all strategies:
+
+```bash
+nexusquant strategy list
+```
+
+List signal history for one strategy:
+
+```bash
+nexusquant strategy signal my_alpha_001 --history --limit 20
+```
+
+Send a single signal:
+
+```bash
+nexusquant strategy signal my_alpha_001 \
+  --strategy-name "My Alpha" \
+  --ticker AAPL \
+  --direction bull \
+  --price 150.25 \
+  --level 0.8 \
+  --quantity 100
+```
+
+Send a multi-route `signals` map:
+
+```bash
+nexusquant strategy signal my_alpha_001 \
+  --strategy-name "My Alpha" \
+  --signals-file signals.json
+```
+
+Get non-PII subscriber config for a strategy:
+
+```bash
+nexusquant strategy sub config my_alpha_001
+```
+
+## JSON Inputs
+
+`--schema-file` must contain the `strategy_schema` object accepted by `nexus-service`, for example:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "window": {
+      "type": "integer",
+      "default": 14,
+      "title": "Window",
+      "source": "user"
+    }
+  },
+  "required": []
+}
+```
+
+`--signals-file` must contain a JSON object whose keys are `default` or user ids:
+
+```json
+{
+  "default": {
+    "ticker": "AAPL",
+    "time": "2026-04-26T19:30:00Z",
+    "price": 150.25,
+    "level": 0.8,
+    "direction": "bull",
+    "quantity": 100,
+    "metadata": {}
+  }
+}
+```
+
+## Environment Overrides
+
+Normal use does not require configuration. For staging or local development:
+
+| Variable | Meaning |
+| --- | --- |
+| `NEXUSQUANT_API_ENDPOINT` | API endpoint host, default `https://api.nexusquant.co`; CLI calls `/api/...` under it |
+| `NEXUSQUANT_API_BASE_URL` | Optional full API base override, e.g. `https://api.nexusquant.co/api` |
+| `NEXUSQUANT_COGNITO_DOMAIN` | Cognito Hosted UI host, default `auth.lookatwallstreet.com` |
+| `NEXUSQUANT_COGNITO_CLIENT_ID` | Cognito app client id |
+| `NEXUSQUANT_REDIRECT_URI` | OAuth callback, default `http://127.0.0.1:8251/callback` |
+
+There is also a hidden typo-compatible alias: `nexusquant startegy ...` maps to `nexusquant strategy ...`.

nexusquant_cli-0.1.0/README.md

@@ -0,0 +1,121 @@
+# nexusquant-cli
+
+Command line tool for NexusQuant strategy providers.
+
+It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus strategy provider APIs. Provider commands require a Cognito user with `custom:userType=strategyProvider` or `custom:userType=admin`.
+
+## Install
+
+```bash
+python3 -m pip install -e .
+```
+
+## Login
+
+```bash
+nexusquant auth
+nexusquant auth --status
+nexusquant auth --refresh
+nexusquant auth --logout
+```
+
+Tokens are stored in the current OS user's config directory, for example `~/Library/Application Support/nexusquant-cli/credentials.json` on macOS. The file is written with `0600` permissions when supported.
+
+## Strategy Commands
+
+Create or update a strategy:
+
+```bash
+nexusquant strategy create \
+  --strategy-id my_alpha_001 \
+  --name "My Alpha" \
+  --schema-file schema.json \
+  --output-unit SHARE_COUNT
+```
+
+List strategies registered by the current provider. Admin users see all strategies:
+
+```bash
+nexusquant strategy list
+```
+
+List signal history for one strategy:
+
+```bash
+nexusquant strategy signal my_alpha_001 --history --limit 20
+```
+
+Send a single signal:
+
+```bash
+nexusquant strategy signal my_alpha_001 \
+  --strategy-name "My Alpha" \
+  --ticker AAPL \
+  --direction bull \
+  --price 150.25 \
+  --level 0.8 \
+  --quantity 100
+```
+
+Send a multi-route `signals` map:
+
+```bash
+nexusquant strategy signal my_alpha_001 \
+  --strategy-name "My Alpha" \
+  --signals-file signals.json
+```
+
+Get non-PII subscriber config for a strategy:
+
+```bash
+nexusquant strategy sub config my_alpha_001
+```
+
+## JSON Inputs
+
+`--schema-file` must contain the `strategy_schema` object accepted by `nexus-service`, for example:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "window": {
+      "type": "integer",
+      "default": 14,
+      "title": "Window",
+      "source": "user"
+    }
+  },
+  "required": []
+}
+```
+
+`--signals-file` must contain a JSON object whose keys are `default` or user ids:
+
+```json
+{
+  "default": {
+    "ticker": "AAPL",
+    "time": "2026-04-26T19:30:00Z",
+    "price": 150.25,
+    "level": 0.8,
+    "direction": "bull",
+    "quantity": 100,
+    "metadata": {}
+  }
+}
+```
+
+## Environment Overrides
+
+Normal use does not require configuration. For staging or local development:
+
+| Variable | Meaning |
+| --- | --- |
+| `NEXUSQUANT_API_ENDPOINT` | API endpoint host, default `https://api.nexusquant.co`; CLI calls `/api/...` under it |
+| `NEXUSQUANT_API_BASE_URL` | Optional full API base override, e.g. `https://api.nexusquant.co/api` |
+| `NEXUSQUANT_COGNITO_DOMAIN` | Cognito Hosted UI host, default `auth.lookatwallstreet.com` |
+| `NEXUSQUANT_COGNITO_CLIENT_ID` | Cognito app client id |
+| `NEXUSQUANT_REDIRECT_URI` | OAuth callback, default `http://127.0.0.1:8251/callback` |
+
+There is also a hidden typo-compatible alias: `nexusquant startegy ...` maps to `nexusquant strategy ...`.

nexusquant_cli-0.1.0/nexusquant_cli/__init__.py

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

nexusquant_cli-0.1.0/nexusquant_cli/__main__.py

@@ -0,0 +1,4 @@
+from nexusquant_cli.main import app
+
+if __name__ == "__main__":
+    app()

nexusquant_cli-0.1.0/nexusquant_cli/api_client.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from nexusquant_cli.auth_pkce import ensure_fresh_id_token
+from nexusquant_cli.config import api_base_url
+
+
+def _headers() -> dict[str, str]:
+    token = ensure_fresh_id_token()
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+    }
+
+
+def _raise_for_error(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    try:
+        detail: Any = response.json()
+    except json.JSONDecodeError:
+        detail = response.text
+    raise RuntimeError(f"HTTP {response.status_code}: {detail}")
+
+
+def get_json(
+    path: str, *, params: dict[str, Any] | None = None, timeout: float = 60.0
+) -> Any:
+    with httpx.Client(timeout=timeout) as client:
+        response = client.get(
+            f"{api_base_url()}{path}", headers=_headers(), params=params
+        )
+    _raise_for_error(response)
+    return response.json()
+
+
+def post_json(path: str, body: Any, *, timeout: float = 60.0) -> Any:
+    headers = {**_headers(), "Content-Type": "application/json"}
+    with httpx.Client(timeout=timeout) as client:
+        response = client.post(f"{api_base_url()}{path}", headers=headers, json=body)
+    _raise_for_error(response)
+    return response.json()
+
+
+def create_strategy(body: dict[str, Any]) -> Any:
+    """POST /strategy-signal/register/ — create/update an external strategy."""
+    return post_json("/strategy-signal/register/", body)
+
+
+def list_provider_strategies() -> Any:
+    """GET /strategy-signal/provider-strategies/ — owned strategies, or all for admin."""
+    return get_json("/strategy-signal/provider-strategies/")
+
+
+def get_provider_signal_history(
+    strategy_id: str,
+    *,
+    limit: int,
+    offset: int,
+    direction: str | None = None,
+    status: str | None = None,
+) -> Any:
+    """GET /strategy-signal/provider-signals/{strategy_id}/ — scoped signal history."""
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if direction:
+        params["direction"] = direction
+    if status:
+        params["status"] = status
+    return get_json(f"/strategy-signal/provider-signals/{strategy_id}/", params=params)
+
+
+def send_strategy_signal(body: dict[str, Any]) -> Any:
+    """POST /strategy-signal/ — send one signal or a signals map."""
+    return post_json("/strategy-signal/", body)
+
+
+def get_subscriber_configs(strategy_id: str) -> Any:
+    """GET /strategy-signal/subscriber-configs/{strategy_id}/ — non-PII subscriber config."""
+    return get_json(f"/strategy-signal/subscriber-configs/{strategy_id}/")

nexusquant_cli-0.1.0/nexusquant_cli/auth_pkce.py

@@ -0,0 +1,234 @@
+"""
+Cognito Hosted UI login via OAuth 2.0 Authorization Code + PKCE.
+
+Nexus service reads ``custom:userType`` from JWT claims for provider/admin
+authorization, so the CLI stores and sends the ID token as ``Authorization:
+Bearer``. Refresh uses the Cognito refresh token when the ID token is near expiry.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+import httpx
+
+from nexusquant_cli.config import (
+    cognito_client_id,
+    cognito_domain_host,
+    load_credentials,
+    redirect_uri,
+    save_credentials,
+)
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(48)
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+def _parse_query(path: str) -> dict[str, str]:
+    query = urllib.parse.urlparse(path).query
+    return dict(urllib.parse.parse_qsl(query))
+
+
+def _token_url(domain_host: str) -> str:
+    return f"https://{domain_host}/oauth2/token"
+
+
+def _post_token(domain_host: str, body: dict[str, Any]) -> dict[str, Any]:
+    with httpx.Client(timeout=30.0) as client:
+        response = client.post(
+            _token_url(domain_host),
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+    if response.status_code >= 400:
+        try:
+            detail: Any = response.json()
+        except json.JSONDecodeError:
+            detail = response.text
+        raise RuntimeError(
+            f"Cognito token endpoint error ({response.status_code}): {detail}"
+        )
+    return response.json()
+
+
+def refresh_tokens(
+    *,
+    domain_host: str,
+    client_id: str,
+    refresh_token: str,
+) -> dict[str, Any]:
+    return _post_token(
+        domain_host,
+        {
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+    )
+
+
+def exchange_code_for_tokens(
+    *,
+    domain_host: str,
+    client_id: str,
+    code: str,
+    redirect_uri_value: str,
+    code_verifier: str,
+) -> dict[str, Any]:
+    return _post_token(
+        domain_host,
+        {
+            "grant_type": "authorization_code",
+            "client_id": client_id,
+            "code": code,
+            "redirect_uri": redirect_uri_value,
+            "code_verifier": code_verifier,
+        },
+    )
+
+
+def run_browser_login() -> dict[str, Any]:
+    domain_host = cognito_domain_host()
+    client_id = cognito_client_id()
+    redirect_uri_value = redirect_uri()
+    verifier, challenge = _pkce_pair()
+
+    auth_params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri_value,
+        "scope": "openid email phone",
+        "code_challenge_method": "S256",
+        "code_challenge": challenge,
+    }
+    auth_url = (
+        f"https://{domain_host}/oauth2/authorize?{urllib.parse.urlencode(auth_params)}"
+    )
+
+    code_holder: dict[str, str | None] = {"code": None, "error": None}
+    done = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, _format: str, *_args: object) -> None:
+            return
+
+        def do_GET(self) -> None:  # noqa: N802
+            params = _parse_query(self.path)
+            if "code" in params:
+                code_holder["code"] = params["code"]
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    b"<html><body><p>NexusQuant login successful. You can close this tab.</p></body></html>"
+                )
+            else:
+                error = (
+                    params.get("error_description")
+                    or params.get("error")
+                    or "unknown_error"
+                )
+                code_holder["error"] = error
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    f"<html><body><p>NexusQuant login failed: {error}</p></body></html>".encode(
+                        "utf-8"
+                    )
+                )
+            done.set()
+
+    parsed = urllib.parse.urlparse(redirect_uri_value)
+    if parsed.hostname not in ("127.0.0.1", "localhost") or not parsed.port:
+        raise RuntimeError("NEXUSQUANT_REDIRECT_URI must be localhost with a port.")
+
+    bind_host = "127.0.0.1" if parsed.hostname == "localhost" else parsed.hostname
+    server = HTTPServer((bind_host or "127.0.0.1", parsed.port), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    webbrowser.open(auth_url)
+
+    if not done.wait(timeout=300):
+        server.shutdown()
+        raise TimeoutError("No OAuth callback received within 5 minutes.")
+    server.shutdown()
+
+    if code_holder["error"]:
+        raise RuntimeError(f"Cognito error: {code_holder['error']}")
+    code = code_holder["code"]
+    if not code:
+        raise RuntimeError("No authorization code in callback.")
+
+    tokens = exchange_code_for_tokens(
+        domain_host=domain_host,
+        client_id=client_id,
+        code=code,
+        redirect_uri_value=redirect_uri_value,
+        code_verifier=verifier,
+    )
+    if "id_token" not in tokens:
+        raise RuntimeError("Cognito token response missing id_token.")
+    return tokens
+
+
+def persist_tokens(tokens: dict[str, Any]) -> None:
+    save_credentials(
+        {
+            "id_token": tokens["id_token"],
+            "access_token": tokens.get("access_token"),
+            "refresh_token": tokens.get("refresh_token"),
+            "expires_in": int(tokens.get("expires_in") or 0),
+            "saved_at": time.time(),
+        }
+    )
+
+
+def ensure_fresh_id_token(*, force_refresh: bool = False) -> str:
+    creds = load_credentials()
+    if not creds or not creds.get("id_token"):
+        raise RuntimeError("尚未登录。请先执行：nexusquant auth")
+
+    expires_in = int(creds.get("expires_in") or 0)
+    saved_at = float(creds.get("saved_at") or 0)
+    remaining = saved_at + expires_in - time.time() if expires_in > 0 else 999999
+    refresh_token = creds.get("refresh_token")
+    if not force_refresh and (remaining > 120 or not refresh_token):
+        return str(creds["id_token"])
+    if not refresh_token:
+        return str(creds["id_token"])
+
+    new_tokens = refresh_tokens(
+        domain_host=cognito_domain_host(),
+        client_id=cognito_client_id(),
+        refresh_token=refresh_token,
+    )
+    merged = {
+        "id_token": new_tokens.get("id_token") or creds["id_token"],
+        "access_token": new_tokens.get("access_token") or creds.get("access_token"),
+        "refresh_token": new_tokens.get("refresh_token") or refresh_token,
+        "expires_in": int(new_tokens.get("expires_in") or expires_in),
+        "saved_at": time.time(),
+    }
+    save_credentials(merged)
+    return str(merged["id_token"])
+
+
+def login_and_save() -> None:
+    persist_tokens(run_browser_login())

nexusquant_cli-0.1.0/nexusquant_cli/commands/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import typer
+
+from nexusquant_cli.commands.auth.cmd import register as register_auth
+from nexusquant_cli.commands.strategy.cmd import register as register_strategy
+
+
+def register_all(app: typer.Typer) -> None:
+    register_auth(app)
+    register_strategy(app)

nexusquant_cli-0.1.0/nexusquant_cli/commands/_util.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+
+def print_json_or_exit(console: Console, fetch: Callable[[], Any]) -> None:
+    try:
+        data = fetch()
+    except Exception as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1) from e
+    console.print_json(data=data)
+
+
+def load_json_option(value: str | None, *, label: str) -> Any:
+    if value is None:
+        return None
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"{label} must be valid JSON: {e}") from e
+
+
+def load_json_file(path: Path, *, label: str) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except OSError as e:
+        raise typer.BadParameter(f"Cannot read {label}: {e}") from e
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"{label} must contain valid JSON: {e}") from e

nexusquant_cli-0.1.0/nexusquant_cli/commands/auth/__init__.py

@@ -0,0 +1 @@
+

nexusquant_cli-0.1.0/nexusquant_cli/commands/auth/cmd.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from nexusquant_cli.auth_pkce import ensure_fresh_id_token, login_and_save
+from nexusquant_cli.config import CREDENTIALS_PATH, clear_credentials, load_credentials
+
+console = Console()
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "auth",
+        help=(
+            "Login with Cognito Hosted UI and save local tokens. Use --refresh to force "
+            "refresh, --status to inspect local login state, or --logout to clear tokens."
+        ),
+    )
+    def auth(
+        logout: bool = typer.Option(
+            False,
+            "--logout",
+            help="Remove locally saved Cognito tokens and exit.",
+        ),
+        refresh: bool = typer.Option(
+            False,
+            "--refresh",
+            help="Refresh the saved ID token using the saved refresh token.",
+        ),
+        status: bool = typer.Option(
+            False,
+            "--status",
+            help="Print whether credentials are saved locally without showing token values.",
+        ),
+    ) -> None:
+        """
+        Authenticate this machine for NexusQuant strategy provider API calls.
+
+        Output: tokens are stored in the current OS user's config directory with 0600
+        permissions when supported. Commands send the ID token as Authorization: Bearer
+        because the backend checks ``custom:userType`` for strategyProvider/admin access.
+        """
+        if logout:
+            clear_credentials()
+            console.print(
+                "[green]已退出登录（本机保存的 NexusQuant token 已清除）。[/green]"
+            )
+            raise typer.Exit(0)
+
+        if status:
+            creds = load_credentials()
+            if creds and creds.get("id_token"):
+                console.print(f"[green]已登录。本地凭据: {CREDENTIALS_PATH}[/green]")
+            else:
+                console.print("[yellow]尚未登录。请执行：nexusquant auth[/yellow]")
+            raise typer.Exit(0)
+
+        try:
+            if refresh:
+                ensure_fresh_id_token(force_refresh=True)
+                console.print("[green]token 已刷新。[/green]")
+            else:
+                login_and_save()
+                console.print("[green]登录成功，token 已保存在本机。[/green]")
+        except Exception as e:
+            console.print(f"[red]{e}[/red]")
+            raise typer.Exit(1) from e

nexusquant_cli-0.1.0/nexusquant_cli/commands/strategy/__init__.py

@@ -0,0 +1 @@
+

nexusquant_cli-0.1.0/nexusquant_cli/commands/strategy/cmd.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from nexusquant_cli import api_client
+from nexusquant_cli.commands._util import (
+    load_json_file,
+    load_json_option,
+    print_json_or_exit,
+)
+
+console = Console()
+
+strategy_app = typer.Typer(
+    help=(
+        "Strategy provider commands. Security model: strategyProvider users can only "
+        "create, list, signal, and inspect subscriber configs for strategies they own; "
+        "admin users can operate across strategies."
+    ),
+    no_args_is_help=True,
+)
+sub_app = typer.Typer(
+    help="Subscriber-related provider commands for one strategy. Returns non-PII config only.",
+    no_args_is_help=True,
+)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _strategy_name_arg(strategy_name: str | None, strategy_id: str) -> str:
+    return strategy_name or strategy_id
+
+
+@strategy_app.command(
+    "create",
+    help=(
+        "Create or update an external strategy via POST /strategy-signal/register/. "
+        "Requires custom:userType=strategyProvider or admin."
+    ),
+)
+def create_strategy(
+    strategy_id: Annotated[
+        str,
+        typer.Option(
+            "--strategy-id",
+            "-i",
+            help="Stable strategy id used in future signal calls, e.g. my_alpha_001.",
+        ),
+    ],
+    strategy_name: Annotated[
+        str,
+        typer.Option("--name", "-n", help="Human-readable strategy name shown in UI."),
+    ],
+    schema_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--schema-file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help=(
+                "UTF-8 JSON file containing strategy_schema. Shape: JSON Schema object "
+                "with type/properties/required as accepted by nexus-service."
+            ),
+        ),
+    ] = None,
+    schema_json: Annotated[
+        str | None,
+        typer.Option(
+            "--schema-json",
+            help="Inline JSON object for strategy_schema. Use this or --schema-file.",
+        ),
+    ] = None,
+    output_unit: Annotated[
+        str,
+        typer.Option(
+            "--output-unit",
+            help=(
+                "Signal output unit. One of CASH_AMOUNT, SHARE_COUNT, "
+                "PERCENTAGE_BALANCE, PERCENTAGE_EQUITY."
+            ),
+        ),
+    ] = "SHARE_COUNT",
+    description: Annotated[
+        str | None,
+        typer.Option("--description", "-d", help="Optional strategy description."),
+    ] = None,
+    config_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--config-file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help="Optional UTF-8 JSON file for provider metadata stored as Strategy.config.",
+        ),
+    ] = None,
+    config_json: Annotated[
+        str | None,
+        typer.Option("--config-json", help="Inline JSON object for Strategy.config."),
+    ] = None,
+    enabled_execution_key: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--enabled-execution-key",
+            help=(
+                "Execution key exposed to users. Repeatable. Supported examples: "
+                "max_order_cash_usd, symbols_allowlist. Omit for platform default."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """
+    Register an external strategy owned by the logged-in provider/admin.
+
+    AI usage example:
+    ``nexusquant strategy create -i demo -n Demo --schema-file schema.json --output-unit SHARE_COUNT``
+    """
+    if schema_file and schema_json:
+        raise typer.BadParameter("Use only one of --schema-file or --schema-json.")
+    if config_file and config_json:
+        raise typer.BadParameter("Use only one of --config-file or --config-json.")
+
+    strategy_schema = (
+        load_json_file(schema_file, label="strategy schema")
+        if schema_file
+        else load_json_option(schema_json, label="strategy schema")
+    )
+    if strategy_schema is None:
+        strategy_schema = {"type": "object", "properties": {}, "required": []}
+
+    config = (
+        load_json_file(config_file, label="strategy config")
+        if config_file
+        else load_json_option(config_json, label="strategy config")
+    )
+    body: dict[str, Any] = {
+        "strategy_id": strategy_id,
+        "strategy_name": strategy_name,
+        "strategy_schema": strategy_schema,
+        "output_unit": output_unit,
+    }
+    if description is not None:
+        body["description"] = description
+    if config is not None:
+        body["config"] = config
+    if enabled_execution_key is not None:
+        body["enabled_execution_keys"] = enabled_execution_key
+
+    print_json_or_exit(console, lambda: api_client.create_strategy(body))
+
+
+@strategy_app.command(
+    "list",
+    help=(
+        "List strategies registered by the current provider. Admin users see all strategies. "
+        "Calls GET /strategy-signal/provider-strategies/."
+    ),
+)
+def list_strategies() -> None:
+    """
+    Output: JSON with strategies, total_count, ownership metadata, signal counts, and schema.
+    """
+    print_json_or_exit(console, api_client.list_provider_strategies)
+
+
+@strategy_app.command(
+    "signal",
+    help=(
+        "Send a strategy signal, send a signals map, or list signal history for one strategy. "
+        "Without send fields, this lists history."
+    ),
+)
+def strategy_signal(
+    strategy_id: Annotated[
+        str,
+        typer.Argument(help="Strategy id in the URL/path and request body."),
+    ],
+    strategy_name: Annotated[
+        str | None,
+        typer.Option(
+            "--strategy-name",
+            "--name",
+            help="Strategy display name sent with a signal. Defaults to strategy_id.",
+        ),
+    ] = None,
+    history: Annotated[
+        bool,
+        typer.Option(
+            "--history",
+            help="List signal history instead of sending. This is the default when no send fields are provided.",
+        ),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", help="History page size.", min=1, max=500),
+    ] = 50,
+    offset: Annotated[
+        int,
+        typer.Option("--offset", help="History offset for pagination.", min=0),
+    ] = 0,
+    status_filter: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            help="History filter: received, sent_to_broker, completed, failed.",
+        ),
+    ] = None,
+    ticker: Annotated[
+        str | None,
+        typer.Option("--ticker", help="Ticker symbol for a single signal, e.g. AAPL."),
+    ] = None,
+    direction: Annotated[
+        str | None,
+        typer.Option("--direction", help="Signal direction: bull or bear."),
+    ] = None,
+    price: Annotated[
+        float | None,
+        typer.Option(
+            "--price",
+            help="Reference price. Required for send and notional_usd sizing.",
+        ),
+    ] = None,
+    level: Annotated[
+        float | None,
+        typer.Option("--level", help="Signal strength/level, e.g. 0.8."),
+    ] = None,
+    time_value: Annotated[
+        str | None,
+        typer.Option(
+            "--time",
+            help="Signal timestamp in ISO-8601. Defaults to current UTC time when sending.",
+        ),
+    ] = None,
+    sizing_kind: Annotated[
+        str | None,
+        typer.Option(
+            "--sizing-kind", help="Optional explicit sizing: shares or notional_usd."
+        ),
+    ] = None,
+    quantity: Annotated[
+        int | None,
+        typer.Option(
+            "--quantity", help="Share quantity for shares sizing. Positive integer."
+        ),
+    ] = None,
+    notional_usd: Annotated[
+        float | None,
+        typer.Option(
+            "--notional-usd",
+            help="USD notional for notional_usd sizing. Positive number.",
+        ),
+    ] = None,
+    metadata_json: Annotated[
+        str | None,
+        typer.Option(
+            "--metadata-json", help="Inline JSON object attached to signal.metadata."
+        ),
+    ] = None,
+    signals_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--signals-file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help=(
+                "UTF-8 JSON object for multi-route signals map. Keys are default or user_id; "
+                "values are signal objects. When provided, single-signal options are ignored."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """
+    Send or inspect signal history.
+
+    History:
+    ``nexusquant strategy signal my_alpha --history --limit 20``
+
+    Single signal:
+    ``nexusquant strategy signal my_alpha --ticker AAPL --direction bull --price 150 --level 0.8 --quantity 100``
+
+    Signals map:
+    ``nexusquant strategy signal my_alpha --signals-file signals.json --strategy-name "My Alpha"``
+    """
+    should_send_single = any(
+        value is not None
+        for value in (
+            ticker,
+            direction,
+            price,
+            level,
+            quantity,
+            notional_usd,
+            signals_file,
+        )
+    )
+    if history or not should_send_single:
+        print_json_or_exit(
+            console,
+            lambda: api_client.get_provider_signal_history(
+                strategy_id,
+                limit=limit,
+                offset=offset,
+                direction=direction if history else None,
+                status=status_filter,
+            ),
+        )
+        return
+
+    body: dict[str, Any] = {
+        "strategy_id": strategy_id,
+        "strategy_name": _strategy_name_arg(strategy_name, strategy_id),
+    }
+    if signals_file is not None:
+        signals = load_json_file(signals_file, label="signals map")
+        if not isinstance(signals, dict):
+            raise typer.BadParameter("--signals-file must contain a JSON object.")
+        body["signals"] = signals
+        print_json_or_exit(console, lambda: api_client.send_strategy_signal(body))
+        return
+
+    missing = [
+        name
+        for name, value in {
+            "--ticker": ticker,
+            "--direction": direction,
+            "--price": price,
+            "--level": level,
+        }.items()
+        if value is None
+    ]
+    if missing:
+        raise typer.BadParameter(
+            f"Sending a single signal requires: {', '.join(missing)}"
+        )
+
+    signal: dict[str, Any] = {
+        "ticker": ticker,
+        "time": time_value or _now_iso(),
+        "price": price,
+        "level": level,
+        "direction": direction,
+    }
+    if sizing_kind is not None:
+        signal["sizing_kind"] = sizing_kind
+    if quantity is not None:
+        signal["quantity"] = quantity
+    if notional_usd is not None:
+        signal["notional_usd"] = notional_usd
+    metadata = load_json_option(metadata_json, label="metadata")
+    if metadata is not None:
+        signal["metadata"] = metadata
+    body["signal"] = signal
+    print_json_or_exit(console, lambda: api_client.send_strategy_signal(body))
+
+
+@sub_app.command(
+    "config",
+    help=(
+        "Get all active subscribers' non-PII config snapshot for one strategy. "
+        "Provider must own the strategy unless logged in as admin."
+    ),
+)
+def subscriber_config(
+    strategy_id: Annotated[str, typer.Argument(help="Strategy id to inspect.")],
+) -> None:
+    """
+    Output: user_id and uses_default_config for each active subscriber. For non-default
+    subscribers, includes normalized personal_config and effective_config. No email,
+    username, Cognito ID, container ID, or subscription time is returned.
+    """
+    print_json_or_exit(console, lambda: api_client.get_subscriber_configs(strategy_id))
+
+
+strategy_app.add_typer(sub_app, name="sub")
+
+
+def register(app: typer.Typer) -> None:
+    app.add_typer(strategy_app, name="strategy")
+    app.add_typer(strategy_app, name="startegy", hidden=True)

nexusquant_cli-0.1.0/nexusquant_cli/config.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+CONFIG_DIR = Path(user_config_dir("nexusquant-cli", appauthor=False))
+CREDENTIALS_PATH = CONFIG_DIR / "credentials.json"
+
+DEFAULT_API_ENDPOINT = "https://api.nexusquant.co"
+DEFAULT_COGNITO_DOMAIN = "auth.lookatwallstreet.com"
+DEFAULT_COGNITO_CLIENT_ID = "5o7hhd4hn4birr8c29vndehiat"
+DEFAULT_REDIRECT_URI = "http://127.0.0.1:8251/callback"
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    value = os.environ.get(name)
+    if value is not None and value.strip():
+        return value.strip()
+    return default
+
+
+def api_base_url() -> str:
+    endpoint = (
+        _env("NEXUSQUANT_API_ENDPOINT", DEFAULT_API_ENDPOINT) or DEFAULT_API_ENDPOINT
+    ).rstrip("/")
+    # Backwards-compatible override: allow either host-only endpoint or full /api base.
+    base_override = _env("NEXUSQUANT_API_BASE_URL")
+    if base_override:
+        return base_override.rstrip("/")
+    return f"{endpoint}/api"
+
+
+def cognito_domain_host() -> str:
+    domain = (
+        _env("NEXUSQUANT_COGNITO_DOMAIN", DEFAULT_COGNITO_DOMAIN)
+        or DEFAULT_COGNITO_DOMAIN
+    )
+    return domain.removeprefix("https://").removeprefix("http://").split("/")[0]
+
+
+def cognito_client_id() -> str:
+    return (
+        _env("NEXUSQUANT_COGNITO_CLIENT_ID", DEFAULT_COGNITO_CLIENT_ID)
+        or DEFAULT_COGNITO_CLIENT_ID
+    )
+
+
+def redirect_uri() -> str:
+    return _env("NEXUSQUANT_REDIRECT_URI", DEFAULT_REDIRECT_URI) or DEFAULT_REDIRECT_URI
+
+
+def load_credentials() -> dict[str, Any] | None:
+    if not CREDENTIALS_PATH.is_file():
+        return None
+    try:
+        return json.loads(CREDENTIALS_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save_credentials(data: dict[str, Any]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    try:
+        CREDENTIALS_PATH.chmod(0o600)
+    except OSError:
+        pass
+
+
+def clear_credentials() -> None:
+    try:
+        CREDENTIALS_PATH.unlink(missing_ok=True)
+    except OSError:
+        pass

nexusquant_cli-0.1.0/nexusquant_cli/main.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from nexusquant_cli import __version__
+from nexusquant_cli.commands import register_all
+
+console = Console()
+app = typer.Typer(
+    name="nexusquant",
+    help=(
+        "NexusQuant strategy provider CLI. Login once with Cognito, then create "
+        "strategies, send strategy signals, list signal history, and fetch non-PII "
+        "subscriber configs. Requires custom:userType=strategyProvider or admin for "
+        "provider commands."
+    ),
+    no_args_is_help=True,
+)
+
+register_all(app)
+
+
+@app.command("version", help="Print this CLI package version string.")
+def version_cmd() -> None:
+    """Print CLI version."""
+    console.print(__version__)
+
+
+if __name__ == "__main__":
+    app()

nexusquant_cli-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nexusquant-cli"
+version = "0.1.0"
+description = "NexusQuant strategy provider CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27",
+  "platformdirs>=4.2",
+  "rich>=13.7",
+  "typer>=0.12",
+]
+
+[project.scripts]
+nexusquant = "nexusquant_cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nexusquant_cli"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"