rightos-sdk 0.1.0__tar.gz

rightos_sdk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+.next/
+out/
+# 永続化データ（トークンのハッシュ等を含むためコミットしない）
+.data/
+*.log
+.DS_Store
+.env*
+!.env.example
+next-env.d.ts
+*.tsbuildinfo
+# YouTubeアップロード用の秘密情報（コミット禁止）
+video/oauth-client.json
+video/token.json
+video/.venv/
+video/work/

rightos_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,77 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rightos-sdk"
+version = "0.1.0"
+description = "Official Python SDK for RightOS - privacy-preserving rights verification API (digital QR tickets for queues, reservations, EV charging, package pickup)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "I-S3 Software Division" }]
+requires-python = ">=3.9"
+keywords = ["rightos", "queue", "digital-ticket", "qr", "verification", "i-s3"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://rightos.i-s3.com/software/rightos/docs"
+Repository = "https://github.com/suomimasuda/rightos-sdk"
+"API Spec" = "https://rightos.i-s3.com/openapi.json"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rightos"]

rightos_sdk-0.1.0/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/test_live.py

@@ -0,0 +1,49 @@
+"""Live smoke test for the Python SDK against production.
+
+Read-heavy: issues exactly one demo token, verifies it, marks it used.
+"""
+import sys
+
+from rightos import RightOS, RightOSError
+
+demo = RightOS(api_key="rk_demo_00000000000000000000")
+pub = RightOS()
+failures = 0
+
+
+def check(name, ok, extra=""):
+    global failures
+    print(f"{'OK ' if ok else 'NG '} {name}{' - ' + str(extra) if extra else ''}")
+    if not ok:
+        failures += 1
+
+
+plans = pub.list_plans()
+check("list_plans returns 5 plans", len(plans) == 5, len(plans))
+
+policy = pub.get_location_policy("loc_ev")
+check("loc_ev policy is non-transferable", policy["policy"]["transferable"] is False)
+
+try:
+    RightOS(api_key="rk_live_invalid").list_locations()
+    check("invalid key raises RightOSError(401)", False)
+except RightOSError as e:
+    check("invalid key raises RightOSError(401)", e.status == 401, e.code)
+
+locations = demo.list_locations()
+check("demo list_locations > 0", len(locations) > 0, len(locations))
+
+issued = demo.issue_token(location_id=locations[0]["id"], title="SDK live test (py)")
+check("issue_token returns walletUrl", issued["token"]["id"] in issued["walletUrl"])
+
+verified = pub.verify_token(issued["token"]["id"], issued["verificationCode"])
+check("verify_token -> success", verified["result"] == "success", verified["result"])
+
+used = demo.use_token(issued["token"]["id"])
+check("use_token -> used", used["status"] == "used", used["status"])
+
+again = pub.verify_token(issued["token"]["id"], issued["verificationCode"])
+check("re-verify -> already_used", again["result"] == "already_used", again["result"])
+
+print("ALL PASS" if failures == 0 else f"{failures} FAILURES")
+sys.exit(0 if failures == 0 else 1)