# -*- coding: utf-8 -*- """Stard API SDK for Python 3.8+ — v1.0.0 (standard library only) https://stard-market.ir/docs/sdks · MIT Server-side only: never ship an API key to browsers or mobile apps. from stard import Stard s = Stard("sk_test_...") print(s.stars_price(500)) order = s.buy_stars(quantity=500, recipient="@username") """ import hashlib import hmac import json import time import urllib.error import urllib.parse import urllib.request import uuid __version__ = "1.0.0" DEFAULT_BASE = "https://stard-market.ir/api/v1" class StardError(Exception): def __init__(self, status, body): e = (body or {}).get("error") or {} super().__init__(f"{e.get('code') or 'http_' + str(status)}: {e.get('message') or 'request failed'}") self.status = status self.type = e.get("type") self.code = e.get("code") self.param = e.get("param") self.request_id = e.get("request_id") class Stard: def __init__(self, api_key, base_url=DEFAULT_BASE, timeout=20, max_retries=2): if not api_key or not api_key.startswith(("sk_test_", "sk_live_")): raise ValueError("Stard: a valid API key (sk_test_/sk_live_) is required") self.api_key, self.base_url, self.timeout, self.max_retries = api_key, base_url.rstrip("/"), timeout, max_retries def request(self, method, path, query=None, body=None, idempotency_key=None): url = self.base_url + path if query: q = {k: v for k, v in query.items() if v is not None} if q: url += "?" + urllib.parse.urlencode(q) headers = {"Authorization": f"Bearer {self.api_key}", "Accept": "application/json", "User-Agent": f"stard-python/{__version__}"} data = None if body is not None: data = json.dumps({k: v for k, v in body.items() if v is not None}).encode() headers["Content-Type"] = "application/json" if method == "POST": headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4()) attempt = 0 while True: req = urllib.request.Request(url, data=data, headers=headers, method=method) try: with urllib.request.urlopen(req, timeout=self.timeout) as r: return json.loads(r.read() or b"{}") except urllib.error.HTTPError as e: try: payload = json.loads(e.read() or b"{}") except ValueError: payload = {} if (e.code == 429 or e.code >= 500) and attempt < self.max_retries: time.sleep(float(e.headers.get("Retry-After") or 0.5 * 2 ** attempt)) attempt += 1 continue raise StardError(e.code, payload) from None except urllib.error.URLError: if attempt < self.max_retries: time.sleep(0.5 * 2 ** attempt) attempt += 1 continue raise def ping(self): return self.request("GET", "/ping") def prices(self): return self.request("GET", "/prices") def stars_price(self, quantity): return self.request("GET", "/stars/price", {"quantity": quantity}) def premium_prices(self): return self.request("GET", "/premium/prices") def categories(self): return self.request("GET", "/categories") def products(self, **query): return self.request("GET", "/products", query) def product(self, ref): return self.request("GET", "/products/" + urllib.parse.quote(str(ref), safe="")) def wallet(self): return self.request("GET", "/wallet") def transactions(self, **query): return self.request("GET", "/transactions", query) def buy_stars(self, quantity, recipient, pay_currency=None, metadata=None, idempotency_key=None): """pay_currency: "TON" | "IRT" (default: the source chosen in your dashboard).""" return self.request("POST", "/orders", body={"type": "stars", "quantity": quantity, "recipient": recipient, "pay_currency": pay_currency, "metadata": metadata}, idempotency_key=idempotency_key) def buy_product(self, product_id, recipient=None, gift_message=None, pay_currency=None, metadata=None, idempotency_key=None): return self.request("POST", "/orders", body={"type": "product", "product_id": product_id, "recipient": recipient, "gift_message": gift_message, "pay_currency": pay_currency, "metadata": metadata}, idempotency_key=idempotency_key) def order(self, order_id): return self.request("GET", "/orders/" + urllib.parse.quote(order_id, safe="")) def orders(self, **query): return self.request("GET", "/orders", query) def cancel_order(self, order_id): return self.request("POST", "/orders/" + urllib.parse.quote(order_id, safe="") + "/cancel") def verify_webhook(raw_body, signature_header, secret, tolerance=300): """Verify a Stard webhook. raw_body: bytes exactly as received. Returns the event dict or raises ValueError.""" parts = dict(p.split("=", 1) for p in (signature_header or "").split(",") if "=" in p) try: ts = int(parts["t"]) v1 = parts["v1"] except (KeyError, ValueError): raise ValueError("Stard webhook: malformed signature header") if abs(time.time() - ts) > tolerance: raise ValueError("Stard webhook: timestamp outside tolerance") if isinstance(raw_body, str): raw_body = raw_body.encode() expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, v1): raise ValueError("Stard webhook: invalid signature") return json.loads(raw_body)