rightos-sdk 0.1.0__py3-none-any.whl

rightos/__init__.py

@@ -0,0 +1,226 @@
+"""RightOS Python SDK (zero-dependency, urllib-based).
+
+RightOS is privacy-preserving rights verification infrastructure:
+digital QR tickets ("Right Tokens") for queues, reservations, EV charging,
+and package pickup. It verifies that a valid right is present - never who
+the person is.
+
+API reference: https://rightos.i-s3.com/openapi.json
+
+Example:
+    >>> from rightos import RightOS
+    >>> client = RightOS(api_key="rk_live_...")
+    >>> issued = client.issue_token(location_id="loc_...", title="Queue ticket")
+    >>> # Hand issued["walletUrl"] (QR page) to your customer.
+    >>> outcome = client.verify_token(issued["token"]["id"], issued["verificationCode"])
+    >>> outcome["result"]
+    'success'
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+__all__ = ["RightOS", "RightOSError", "DEFAULT_BASE_URL"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://rightos.i-s3.com"
+
+
+class RightOSError(Exception):
+    """Raised for any non-2xx API response.
+
+    Attributes:
+        status: HTTP status code.
+        code: Machine-readable error code (e.g. "invalid_api_key",
+            "policy_transfer_disabled", "transfer_limit_reached").
+        retry_after_sec: Seconds to wait before retrying (present on 429).
+    """
+
+    def __init__(self, status: int, code: str, retry_after_sec: Optional[int] = None):
+        super().__init__(f"RightOS API error {status}: {code}")
+        self.status = status
+        self.code = code
+        self.retry_after_sec = retry_after_sec
+
+
+class RightOS:
+    """RightOS API client.
+
+    Operator methods require ``api_key``. Public methods (verify_token,
+    transfer_token, get_token, get_location_policy, list_plans,
+    register_organization) work without a key.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---------- internals ----------
+
+    def _request(self, method: str, path: str, body: Any = ...) -> Any:
+        headers = {"User-Agent": f"rightos-sdk-python/{__version__}"}
+        data = None
+        if body is not ...:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if self.api_key:
+            headers["x-rightos-key"] = self.api_key
+        req = urllib.request.Request(
+            f"{self.base_url}{path}", data=data, headers=headers, method=method
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return json.loads(res.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            code = "unknown_error"
+            try:
+                payload = json.loads(e.read().decode("utf-8"))
+                code = payload.get("error", code)
+            except Exception:
+                pass
+            retry_after = e.headers.get("Retry-After")
+            raise RightOSError(
+                e.code, code, int(retry_after) if retry_after else None
+            ) from None
+
+    # ---------- Public endpoints (no API key required) ----------
+
+    def list_plans(self) -> list[dict]:
+        """List pricing plans (globally uniform pricing)."""
+        return self._request("GET", "/api/rightos/plans")["plans"]
+
+    def get_token(self, token_id: str) -> dict:
+        """Get a Right Token (never includes the secret hash)."""
+        return self._request("GET", f"/api/rightos/tokens/{token_id}")["token"]
+
+    def verify_token(self, token_id: str, verification_code: str) -> dict:
+        """Verify a Right Token by its verificationCode.
+
+        Returns ``{"result": "success" | "failed" | "expired" | "cancelled"
+        | "already_used", "token": {...}}``. Rate limited: 10/min per
+        IP+token, 60/min per IP.
+        """
+        return self._request(
+            "POST",
+            f"/api/rightos/tokens/{token_id}/verify",
+            {"verificationCode": verification_code},
+        )
+
+    def transfer_token(self, token_id: str, current_verification_code: str) -> dict:
+        """Transfer a right (re-keying). Only the current holder can transfer.
+
+        Subject to the location policy - raises RightOSError with code
+        "policy_transfer_disabled" or "transfer_limit_reached" (HTTP 409).
+        The new verificationCode and walletUrl are returned exactly once.
+        """
+        return self._request(
+            "POST",
+            f"/api/rightos/tokens/{token_id}/transfer",
+            {"verificationCode": current_verification_code},
+        )
+
+    def get_location_policy(self, location_id: str) -> dict:
+        """Get a location's effective policy (public, for transparency)."""
+        return self._request("GET", f"/api/rightos/locations/{location_id}/policy")
+
+    def register_organization(
+        self, name: str, contact_email: str, plan_id: str = "free", country: str = "JP"
+    ) -> dict:
+        """Register an organization.
+
+        The returned apiKey is shown EXACTLY ONCE - store it securely.
+        Rate limited: 5/hour per IP.
+        """
+        return self._request(
+            "POST",
+            "/api/rightos/organizations",
+            {"name": name, "contactEmail": contact_email, "planId": plan_id, "country": country},
+        )
+
+    # ---------- Operator endpoints (API key required) ----------
+
+    def list_locations(self) -> list[dict]:
+        """List your organization's locations."""
+        return self._request("GET", "/api/rightos/locations")["locations"]
+
+    def create_location(
+        self,
+        name: str,
+        address: str = "",
+        type: str = "other",
+        timezone: str = "Asia/Tokyo",
+    ) -> dict:
+        """Create a location. Raises 402 when the plan's location limit is exceeded."""
+        return self._request(
+            "POST",
+            "/api/rightos/locations",
+            {"name": name, "address": address, "type": type, "timezone": timezone},
+        )["location"]
+
+    def set_location_policy(self, location_id: str, patch: Optional[dict]) -> dict:
+        """Override a location's policy (partial update).
+
+        Pass ``None`` to reset to the industry preset.
+        """
+        return self._request(
+            "PUT", f"/api/rightos/locations/{location_id}/policy", patch
+        )
+
+    def issue_token(
+        self,
+        location_id: str,
+        title: str,
+        description: str = "",
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+    ) -> dict:
+        """Issue a Right Token.
+
+        The verificationCode and walletUrl are returned exactly once -
+        hand the walletUrl (QR page) to the end user. Raises 402 when the
+        plan's monthly token limit is exceeded.
+        """
+        body: dict[str, Any] = {"locationId": location_id, "title": title}
+        if description:
+            body["description"] = description
+        if start_time:
+            body["startTime"] = start_time
+        if end_time:
+            body["endTime"] = end_time
+        return self._request("POST", "/api/rightos/tokens/issue", body)
+
+    def use_token(self, token_id: str) -> dict:
+        """Mark a token as used (own organization only)."""
+        return self._request("POST", f"/api/rightos/tokens/{token_id}/use")["token"]
+
+    def cancel_token(self, token_id: str) -> dict:
+        """Cancel a token (own organization only)."""
+        return self._request("POST", f"/api/rightos/tokens/{token_id}/cancel")["token"]
+
+    def export_data(self) -> dict:
+        """Export all organization data as JSON (no lock-in; contains no secrets)."""
+        return self._request("GET", "/api/rightos/export")
+
+    def rotate_api_key(self) -> str:
+        """Re-issue the API key. The old key is invalidated immediately.
+
+        The new key is returned exactly once. This client switches to the
+        new key automatically.
+        """
+        new_key = self._request("POST", "/api/rightos/organizations/rotate-key")["apiKey"]
+        self.api_key = new_key
+        return new_key
+
+    def delete_organization(self, confirm_name: str) -> dict:
+        """Permanently delete the organization and all its data (irreversible).
+
+        ``confirm_name`` must exactly match the organization name.
+        """
+        return self._request(
+            "POST", "/api/rightos/organizations/delete", {"confirm": confirm_name}
+        )

rightos_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: rightos-sdk
+Version: 0.1.0
+Summary: Official Python SDK for RightOS - privacy-preserving rights verification API (digital QR tickets for queues, reservations, EV charging, package pickup).
+Project-URL: Homepage, https://rightos.i-s3.com/software/rightos/docs
+Project-URL: Repository, https://github.com/suomimasuda/rightos-sdk
+Project-URL: API Spec, https://rightos.i-s3.com/openapi.json
+Author: I-S3 Software Division
+License: MIT
+Keywords: digital-ticket,i-s3,qr,queue,rightos,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# rightos-sdk — RightOS Python SDK
+
+Official Python SDK for [RightOS](https://rightos.i-s3.com/software/rightos) — privacy-preserving rights verification infrastructure. Issue and verify digital QR tickets ("Right Tokens") for queues, reservations, EV charging, and package pickup, without ever collecting end users' names or phone numbers.
+
+- Zero dependencies (standard library only), Python ≥ 3.9
+- Machine-readable spec: [openapi.json](https://rightos.i-s3.com/openapi.json) · AI-agent docs: [llms-full.txt](https://rightos.i-s3.com/llms-full.txt)
+
+> RightOS is not a taxi or ride-hailing service. It does not arrange vehicles, set fares, assign drivers, or broker dispatch.
+
+## Install
+
+```bash
+pip install rightos-sdk
+```
+
+## Quickstart (60 seconds)
+
+```python
+from rightos import RightOS
+
+# 1. Register once (the apiKey is returned EXACTLY ONCE — store it securely)
+pub = RightOS()
+reg = pub.register_organization(name="My Shop", contact_email="you@example.com", plan_id="free")
+api_key = reg["apiKey"]
+
+# 2. Operator client
+client = RightOS(api_key=api_key)
+
+# 3. Issue a digital QR ticket
+location = client.list_locations()[0]
+issued = client.issue_token(location_id=location["id"], title="Queue ticket")
+print("Hand this to your customer:", issued["walletUrl"])
+
+# 4. Verify on arrival (no API key needed)
+outcome = RightOS().verify_token(issued["token"]["id"], issued["verificationCode"])
+print(outcome["result"])  # "success"
+
+# 5. Mark as used after service
+client.use_token(issued["token"]["id"])
+```
+
+## Location policies (Policy Engine)
+
+```python
+policy = client.get_location_policy(location["id"])["policy"]
+# {"transferable": True, "maxTransfers": 3, "defaultValidityMinutes": 720, ...}
+
+client.set_location_policy(location["id"], {"transferable": False})  # override
+client.set_location_policy(location["id"], None)  # reset to industry preset
+```
+
+## Error handling
+
+```python
+from rightos import RightOS, RightOSError
+
+try:
+    RightOS().transfer_token(token_id, code)
+except RightOSError as e:
+    if e.code == "policy_transfer_disabled":
+        ...  # this location forbids transfers
+    elif e.status == 429:
+        ...  # rate limited; wait e.retry_after_sec
+```
+
+Common codes: `missing_api_key` / `invalid_api_key` (401), plan limits (402), `policy_transfer_disabled` / `transfer_limit_reached` (409), `rate_limited` (429).
+
+## Try it against the live demo
+
+```python
+demo = RightOS(api_key="rk_demo_00000000000000000000")  # shared demo org
+print(demo.list_locations())
+```
+
+## License
+
+MIT © I-S3 Inc.

rightos_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+rightos/__init__.py,sha256=5jfdJpWpzk8FNadCoqoQO6s_muFu0ltzHdIXxl0gTN4,8459
+rightos_sdk-0.1.0.dist-info/METADATA,sha256=8eOKbLj25FXhcoz-ytpyoDMmum40_8jrLblKTKso-ms,3313
+rightos_sdk-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+rightos_sdk-0.1.0.dist-info/RECORD,,

rightos_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any