loyaltyvip 1.0.0__tar.gz

loyaltyvip-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.DS_Store

loyaltyvip-1.0.0/LICENSE

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

loyaltyvip-1.0.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: loyaltyvip
+Version: 1.0.0
+Summary: Python client for the LoyaltyVIP API — casino player intelligence: directory, tiers, trips, offers, comps, tax.
+Project-URL: Homepage, https://loyaltyvip.com/developers
+Project-URL: Documentation, https://loyaltyvip.com/developers
+Project-URL: Repository, https://github.com/movaMedia-Inc/loyaltyvip-python
+Project-URL: OpenAPI Spec, https://loyaltyvip.com/openapi.json
+Author: movaMedia
+License: MIT
+License-File: LICENSE
+Keywords: api,casino,loyalty,loyaltyvip,rewards,sdk
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# loyaltyvip (Python)
+
+Official Python client for the [LoyaltyVIP](https://loyaltyvip.com) API — the privacy-first casino player intelligence platform. Standard library only (no dependencies). Python 3.8+.
+
+```bash
+pip install loyaltyvip
+```
+
+```python
+from loyaltyvip import LoyaltyVIP
+
+lv = LoyaltyVIP()  # public directory needs no key
+res = lv.search_casinos(state="NV", has_rewards=True, limit=5)
+for c in res["data"]:
+    print(c["name"], "-", c.get("city"), c.get("state"))
+
+# Your own data needs a key (https://loyaltyvip.com/dashboard/developer):
+import os
+me = LoyaltyVIP(api_key=os.environ["LOYALTYVIP_API_KEY"])
+print(me.player("tier_status"))
+print(me.tax_report("generate_summary", tax_year=2025))  # scope: tax
+```
+
+Methods: `search_casinos`, `get_casino`, `list_rewards_programs`, `get_rewards_program` (public); `me`, `tiers`, `trips`, `offers`, `player`, `comp`, `predict`, `tier_match`, `tax_report` (API key). Errors raise `LoyaltyVIPError` (`status`, `code`, `message`, `docs`).
+
+- Docs: https://loyaltyvip.com/developers
+- OpenAPI 3.1: https://loyaltyvip.com/openapi.json
+- Auth guide: https://loyaltyvip.com/auth.md
+
+LoyaltyVIP is independent and not affiliated with any casino brand — a record-keeping and analytics tool, not a gambling product. MIT © movaMedia.

loyaltyvip-1.0.0/README.md

@@ -0,0 +1,30 @@
+# loyaltyvip (Python)
+
+Official Python client for the [LoyaltyVIP](https://loyaltyvip.com) API — the privacy-first casino player intelligence platform. Standard library only (no dependencies). Python 3.8+.
+
+```bash
+pip install loyaltyvip
+```
+
+```python
+from loyaltyvip import LoyaltyVIP
+
+lv = LoyaltyVIP()  # public directory needs no key
+res = lv.search_casinos(state="NV", has_rewards=True, limit=5)
+for c in res["data"]:
+    print(c["name"], "-", c.get("city"), c.get("state"))
+
+# Your own data needs a key (https://loyaltyvip.com/dashboard/developer):
+import os
+me = LoyaltyVIP(api_key=os.environ["LOYALTYVIP_API_KEY"])
+print(me.player("tier_status"))
+print(me.tax_report("generate_summary", tax_year=2025))  # scope: tax
+```
+
+Methods: `search_casinos`, `get_casino`, `list_rewards_programs`, `get_rewards_program` (public); `me`, `tiers`, `trips`, `offers`, `player`, `comp`, `predict`, `tier_match`, `tax_report` (API key). Errors raise `LoyaltyVIPError` (`status`, `code`, `message`, `docs`).
+
+- Docs: https://loyaltyvip.com/developers
+- OpenAPI 3.1: https://loyaltyvip.com/openapi.json
+- Auth guide: https://loyaltyvip.com/auth.md
+
+LoyaltyVIP is independent and not affiliated with any casino brand — a record-keeping and analytics tool, not a gambling product. MIT © movaMedia.

loyaltyvip-1.0.0/examples/quickstart.py

@@ -0,0 +1,16 @@
+"""Run: python examples/quickstart.py  (no key needed for the directory)."""
+
+import os
+
+from loyaltyvip import LoyaltyVIP
+
+lv = LoyaltyVIP(api_key=os.environ.get("LOYALTYVIP_API_KEY"))
+
+res = lv.search_casinos(state="NV", has_rewards=True, limit=5)
+print(f"Found {res.get('count', len(res['data']))} casinos; first 5:")
+for c in res["data"]:
+    print(f" - {c['name']} ({c.get('city')}, {c.get('state')})")
+
+if os.environ.get("LOYALTYVIP_API_KEY"):
+    print("\nYour tier status:")
+    print(lv.player("tier_status"))

loyaltyvip-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loyaltyvip"
+version = "1.0.0"
+description = "Python client for the LoyaltyVIP API — casino player intelligence: directory, tiers, trips, offers, comps, tax."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "movaMedia" }]
+keywords = ["loyaltyvip", "casino", "loyalty", "rewards", "api", "sdk"]
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://loyaltyvip.com/developers"
+Documentation = "https://loyaltyvip.com/developers"
+Repository = "https://github.com/movaMedia-Inc/loyaltyvip-python"
+"OpenAPI Spec" = "https://loyaltyvip.com/openapi.json"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loyaltyvip"]

loyaltyvip-1.0.0/src/loyaltyvip/__init__.py

@@ -0,0 +1,9 @@
+"""LoyaltyVIP Python SDK — casino player intelligence API client.
+
+See https://loyaltyvip.com/developers for docs.
+"""
+
+from .client import DEFAULT_BASE_URL, LoyaltyVIP, LoyaltyVIPError
+
+__version__ = "1.0.0"
+__all__ = ["LoyaltyVIP", "LoyaltyVIPError", "DEFAULT_BASE_URL", "__version__"]

loyaltyvip-1.0.0/src/loyaltyvip/client.py

@@ -0,0 +1,153 @@
+"""LoyaltyVIP API client (standard library only).
+
+The public casino directory needs no key. A player's own data requires a
+personal API key (``lvip_live_...``) minted at
+https://loyaltyvip.com/dashboard/developer.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+DEFAULT_BASE_URL = "https://nbhagdwegk.execute-api.us-east-1.amazonaws.com"
+
+__all__ = ["LoyaltyVIP", "LoyaltyVIPError", "DEFAULT_BASE_URL"]
+
+
+class LoyaltyVIPError(Exception):
+    """Raised on any non-2xx API response. Carries the typed error envelope."""
+
+    def __init__(self, status: int, code: str, message: str, docs: Optional[str] = None) -> None:
+        super().__init__(f"{status} ({code}): {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.docs = docs
+
+
+class LoyaltyVIP:
+    """A thin, typed-ish client for the LoyaltyVIP REST API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ── Public directory (no key) ────────────────────────────────────────
+
+    def search_casinos(
+        self,
+        q: Optional[str] = None,
+        state: Optional[str] = None,
+        type: Optional[str] = None,  # noqa: A002 - mirrors the API param name
+        has_rewards: Optional[bool] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """Search the public U.S. casino directory."""
+        return self._get(
+            "/v1/casinos",
+            {"q": q, "state": state, "type": type, "has_rewards": has_rewards, "limit": limit, "offset": offset},
+        )
+
+    def get_casino(self, slug: str) -> dict[str, Any]:
+        """Casino detail including rewards program and full tier ladder."""
+        return self._get(f"/v1/casinos/{urllib.parse.quote(slug)}")
+
+    def list_rewards_programs(
+        self, search: Optional[str] = None, brand: Optional[str] = None, limit: Optional[int] = None
+    ) -> dict[str, Any]:
+        """List casino rewards / players-club programs."""
+        return self._get("/v1/rewards-programs", {"search": search, "brand": brand, "limit": limit})
+
+    def get_rewards_program(self, program_id: str) -> dict[str, Any]:
+        """A single rewards program with its tier ladder."""
+        return self._get(f"/v1/rewards-programs/{urllib.parse.quote(program_id)}")
+
+    # ── Account / actions (API key required) ─────────────────────────────
+
+    def me(self) -> dict[str, Any]:
+        return self._get("/v1/me", auth=True)
+
+    def tiers(self) -> dict[str, Any]:
+        return self._get("/v1/tiers", auth=True)
+
+    def trips(self) -> dict[str, Any]:
+        return self._get("/v1/trips", auth=True)
+
+    def offers(self) -> dict[str, Any]:
+        return self._get("/v1/offers", auth=True)
+
+    def player(self, action: str, **params: Any) -> dict[str, Any]:
+        """Invoke any /v1/player action (read/write/tax/host scopes apply)."""
+        return self._post("/v1/player", {"action": action, **params}, auth=True)
+
+    def comp(self, action: str, **params: Any) -> dict[str, Any]:
+        return self._post("/v1/comp/calculate", {"action": action, **params}, auth=True)
+
+    def predict(self, action: str, **params: Any) -> dict[str, Any]:
+        return self._post("/v1/comp/predict", {"action": action, **params}, auth=True)
+
+    def tier_match(self, action: str, **params: Any) -> dict[str, Any]:
+        return self._post("/v1/tier-match", {"action": action, **params}, auth=True)
+
+    def tax_report(self, action: str, **params: Any) -> dict[str, Any]:
+        """IRS gambling tax documents (scope: tax)."""
+        return self._post("/v1/tax-report", {"action": action, **params}, auth=True)
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    def _headers(self, auth: bool) -> dict[str, str]:
+        headers = {"accept": "application/json"}
+        if auth and not self.api_key:
+            raise LoyaltyVIPError(401, "invalid_token", "This call requires an API key. Pass api_key=...")
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _get(self, path: str, query: Optional[dict[str, Any]] = None, auth: bool = False) -> dict[str, Any]:
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None and v != ""}
+            if clean:
+                # Booleans must serialize as lowercase true/false.
+                for k, v in list(clean.items()):
+                    if isinstance(v, bool):
+                        clean[k] = "true" if v else "false"
+                url += "?" + urllib.parse.urlencode(clean)
+        return self._request("GET", url, None, auth)
+
+    def _post(self, path: str, body: dict[str, Any], auth: bool = False) -> dict[str, Any]:
+        return self._request("POST", self.base_url + path, body, auth)
+
+    def _request(self, method: str, url: str, body: Optional[dict[str, Any]], auth: bool) -> dict[str, Any]:
+        headers = self._headers(auth)
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8") or "{}")
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode("utf-8", "replace")
+            try:
+                err = json.loads(raw).get("error", {})
+            except json.JSONDecodeError:
+                err = {}
+            raise LoyaltyVIPError(
+                exc.code,
+                err.get("code", "error"),
+                err.get("message", f"Request failed with {exc.code}"),
+                err.get("docs"),
+            ) from None