chimerakit 0.1.0__py3-none-any.whl

chimerakit/__init__.py

@@ -0,0 +1,6 @@
+"""chimerakit: the Python client for the Chimera partner bank API. See README.md."""
+from .client import AsyncChimera, Chimera, Line, new_request_id
+from .errors import AccessDenied, ChimeraError, Conflict, InvalidRequest, LimitExceeded, NotFound, RateLimited, Unavailable
+
+__version__ = "0.1.0"
+__all__ = ["AccessDenied", "AsyncChimera", "Chimera", "ChimeraError", "Conflict", "InvalidRequest", "LimitExceeded", "Line", "NotFound", "RateLimited", "Unavailable", "new_request_id"]

chimerakit/client.py

@@ -0,0 +1,358 @@
+"""
+The clients. `Chimera` and `AsyncChimera` have the same methods. Everything that shapes a request or reads an answer is in `_Calls`, so the two cannot drift apart.
+
+Three promises:
+
+    Amounts are exact. They go out as text and come back as Decimal. A float is refused, because it has already been rounded.
+    A retry is safe. A call that creates something carries a request ID, and every retry of it carries the same one, so Chimera acts once. Other calls are reads, or harmless to repeat.
+    A secret goes only over HTTPS. Plain HTTP is allowed to this computer only, for the sandbox.
+"""
+import asyncio
+import random
+import re
+import secrets
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+from typing import Dict, List, Mapping, Optional, Sequence, Union
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import BY_STATUS, ChimeraError, Unavailable
+
+RESOURCES = ("money", "food", "coal", "oil", "uranium", "lead", "iron", "bauxite", "gasoline", "munitions", "steel", "aluminum")
+RETRY_STATUSES = (429, 500, 502, 503, 504)
+TIMEOUT_SECONDS = 15.0
+MAX_ATTEMPTS = 4
+LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1", "testserver")
+CENTS = re.compile(r"[0-9]{1,28}(\.[0-9]{1,2})?")
+
+Number = Union[Decimal, int, str]
+
+
+def new_request_id():
+    """A fresh ID for a call that creates something. Save it before you make the call, so that after a crash you can repeat the call and not act twice."""
+    return "ck-" + secrets.token_urlsafe(24)
+
+
+def _amount(name, value):
+    if name not in RESOURCES:
+        raise ValueError("%r is not something Chimera holds." % (name,))
+    if isinstance(value, bool) or isinstance(value, float):
+        raise TypeError("%s must be a Decimal, int or str: a float has already been rounded." % name)
+    try:
+        number = Decimal(str(value).strip())
+    except InvalidOperation:
+        raise ValueError("%s is not a number." % name)
+    if not number.is_finite():
+        raise ValueError("%s is not a number." % name)
+    text = format(number, "f")
+    if not CENTS.fullmatch(text):
+        raise ValueError("%s must be positive, with at most two decimal places." % name)
+    if not number:
+        raise ValueError("%s is zero. Leave it out." % name)
+    return text
+
+
+def _amounts(amounts):
+    if not amounts:
+        raise ValueError("Give at least one amount.")
+    return {k: _amount(k, v) for k, v in amounts.items()}
+
+
+def _discord(discord_id):
+    text = str(discord_id)
+    if not re.fullmatch(r"[0-9]{1,20}", text):
+        raise ValueError("A Discord ID is digits only.")
+    return text
+
+
+def _money_map(raw):
+    return {k: Decimal(str(v)) for k, v in raw.items()}
+
+
+def _when(text):
+    return datetime.fromisoformat(text) if text else None
+
+
+@dataclass(frozen=True)
+class Line:
+    """One client's share of a handoff."""
+    discord_id: Union[int, str]
+    nation_id: int
+    amounts: Mapping[str, Number]
+
+
+@dataclass(frozen=True)
+class PendingDeposit:
+    deposit_id: int
+    amounts: Dict[str, Decimal]
+    expires_at: Optional[datetime]
+
+
+@dataclass(frozen=True)
+class Account:
+    accountid: int
+    discord_id: int
+    nation_id: int
+    custody: str
+    frozen: bool
+    balances: Dict[str, Decimal]
+    pending_deposits: List[PendingDeposit]
+
+
+@dataclass(frozen=True)
+class Deposit:
+    """Send exactly `amounts` from your registered alliance to Chimera, with `code` as the WHOLE note, nothing around it, before `expires_at`. `status` is waiting, credited, expired or under_review."""
+    deposit_id: int
+    accountid: int
+    discord_id: int
+    nation_id: int
+    alliance_id: int
+    code: str
+    amounts: Dict[str, Decimal]
+    status: str
+    created_at: datetime
+    expires_at: datetime
+    repeat: bool
+
+
+@dataclass(frozen=True)
+class HandoffLine:
+    accountid: int
+    discord_id: int
+    nation_id: int
+    amounts: Dict[str, Decimal]
+
+
+@dataclass(frozen=True)
+class Handoff:
+    """One transfer for many clients. Send exactly `amounts`, the total, with `code` as the whole note. It credits every line or none. `status` is as for a Deposit."""
+    handoff_id: int
+    alliance_id: int
+    code: str
+    amounts: Dict[str, Decimal]
+    lines: List[HandoffLine]
+    status: str
+    created_at: datetime
+    expires_at: datetime
+    repeat: bool
+
+
+@dataclass(frozen=True)
+class Withdrawal:
+    """`status` is processing, sent, completed, failed or under_review. When it is sent, check the in-game record against `code`, pay your client, then call confirm_withdrawal."""
+    withdrawal_id: int
+    accountid: int
+    discord_id: int
+    nation_id: int
+    alliance_id: int
+    code: str
+    amounts: Dict[str, Decimal]
+    status: str
+    created_at: datetime
+    repeat: bool
+
+
+def _account(r):
+    pending = [PendingDeposit(p["deposit_id"], _money_map(p["amounts"]), _when(p["expires_at"])) for p in r.get("pending_deposits", [])]
+    return Account(int(r["accountid"]), int(r["discord_id"]), r["nation_id"], r["custody"], r["frozen"], _money_map(r["balances"]), pending)
+
+
+def _deposit(r):
+    return Deposit(r["deposit_id"], int(r["accountid"]), int(r["discord_id"]), r["nation_id"], r["alliance_id"], r["code"], _money_map(r["amounts"]), r["status"], _when(r["created_at"]), _when(r["expires_at"]), r["repeat"])
+
+
+def _handoff(r):
+    lines = [HandoffLine(int(x["accountid"]), int(x["discord_id"]), x["nation_id"], _money_map(x["amounts"])) for x in r["lines"]]
+    return Handoff(r["handoff_id"], r["alliance_id"], r["code"], _money_map(r["amounts"]), lines, r["status"], _when(r["created_at"]), _when(r["expires_at"]), r["repeat"])
+
+
+def _withdrawal(r):
+    return Withdrawal(r["withdrawal_id"], int(r["accountid"]), int(r["discord_id"]), r["nation_id"], r["alliance_id"], r["code"], _money_map(r["amounts"]), r["status"], _when(r["created_at"]), r["repeat"])
+
+
+class _Call:
+    """One API call: where it goes, what it carries, and how to read a good answer."""
+
+    def __init__(self, method, path, read, body=None, params=None, request_id=None):
+        self.method, self.path, self.read, self.body, self.params, self.request_id = method, path, read, body, params, request_id
+
+
+class _Calls:
+    """Every method of both clients, as a description of the call. Each subclass supplies `_do`, which runs one call with its retries."""
+
+    def _do(self, call):
+        raise NotImplementedError
+
+    def health(self):
+        return self._do(_Call("GET", "/health", lambda r: r["status"] == "ok"))
+
+    def open_account(self, discord_id, nation_id):
+        """The client's account, opened if it has none. Calling it twice is harmless. An account starts empty."""
+        return self._do(_Call("POST", "/v1/accounts", _account, {"discord_id": _discord(discord_id), "nation_id": int(nation_id)}))
+
+    def accounts(self, after=None, limit=100):
+        """One page of your clients' accounts, oldest first, as (accounts, next_after). Pass next_after for the next page. It is None on the last page."""
+        params = {"limit": int(limit)}
+        if after is not None:
+            params["after"] = int(after)
+        return self._do(_Call("GET", "/v1/accounts", lambda r: ([_account(a) for a in r["accounts"]], r["next_after"]), params=params))
+
+    def create_deposit(self, discord_id, nation_id, amounts, request_id=None):
+        """Says you are about to send these funds, and gets the code for the note. Nothing is credited until Chimera sees the transfer in the game's records."""
+        request_id = request_id or new_request_id()
+        body = {"request_id": request_id, "discord_id": _discord(discord_id), "nation_id": int(nation_id), "amounts": _amounts(amounts)}
+        return self._do(_Call("POST", "/v1/deposits", _deposit, body, request_id=request_id))
+
+    def get_deposit(self, deposit_id):
+        return self._do(_Call("GET", "/v1/deposits/%d" % int(deposit_id), _deposit))
+
+    def create_handoff(self, lines: Sequence[Line], request_id=None):
+        """One transfer split across many clients, each with an account already. This is the raid tool. Up to 500 lines."""
+        request_id = request_id or new_request_id()
+        body = {"request_id": request_id, "lines": [{"discord_id": _discord(x.discord_id), "nation_id": int(x.nation_id), "amounts": _amounts(x.amounts)} for x in lines]}
+        return self._do(_Call("POST", "/v1/handoffs", _handoff, body, request_id=request_id))
+
+    def get_handoff(self, handoff_id):
+        return self._do(_Call("GET", "/v1/handoffs/%d" % int(handoff_id), _handoff))
+
+    def create_withdrawal(self, discord_id, nation_id, amounts, request_id=None):
+        """Takes the amounts from the client's balance at once. Chimera sends them to your registered alliance, never to a client."""
+        request_id = request_id or new_request_id()
+        body = {"request_id": request_id, "discord_id": _discord(discord_id), "nation_id": int(nation_id), "amounts": _amounts(amounts)}
+        return self._do(_Call("POST", "/v1/withdrawals", _withdrawal, body, request_id=request_id))
+
+    def get_withdrawal(self, withdrawal_id):
+        return self._do(_Call("GET", "/v1/withdrawals/%d" % int(withdrawal_id), _withdrawal))
+
+    def confirm_withdrawal(self, withdrawal_id, code):
+        """Says the funds reached your alliance. Saying it twice is harmless."""
+        return self._do(_Call("POST", "/v1/withdrawals/%d/confirm" % int(withdrawal_id), _withdrawal, {"code": code}))
+
+
+def _base_url(url):
+    parts = urlsplit(url)
+    if parts.scheme != "https" and not (parts.scheme == "http" and parts.hostname in LOCAL_HOSTS):
+        raise ValueError("Chimera secrets only go over HTTPS.")
+    return url.rstrip("/")
+
+
+def _headers(secret):
+    if not secret:
+        raise ValueError("Give your Chimera secret.")
+    return {"Authorization": "Bearer %s" % secret, "User-Agent": "chimerakit/0.1"}
+
+
+def _result(call, response):
+    """The answer read, or the right error. None means try again."""
+    if response.status_code in (200, 201):
+        return call.read(response.json())
+    if response.status_code in RETRY_STATUSES:
+        return None
+    raise _refusal(call, response)
+
+
+def _refusal(call, response):
+    try:
+        message = response.json().get("detail") or "Refused."
+    except ValueError:
+        message = "Refused."
+    kind = BY_STATUS.get(response.status_code, Unavailable if response.status_code >= 500 else ChimeraError)
+    return kind(str(message), status=response.status_code, request_id=call.request_id)
+
+
+def _gave_up(call, response, error):
+    if response is not None and response.status_code == 429:
+        return _refusal(call, response)
+    what = "Chimera answered %s." % response.status_code if response is not None else "No answer from Chimera: %s." % type(error).__name__
+    return Unavailable(what + " The call may have worked. Repeat it with the same request ID.", status=getattr(response, "status_code", None), request_id=call.request_id)
+
+
+def _pause(attempt, base):
+    return base * (2 ** attempt) * (1 + random.random() / 2)
+
+
+class Chimera(_Calls):
+    """For a blocking program. Use one for the life of your program, and close it, or use `with`. `transport` is for tests."""
+
+    def __init__(self, secret, base_url, timeout=TIMEOUT_SECONDS, attempts=MAX_ATTEMPTS, pause=0.5, transport=None):
+        self.attempts, self.pause = attempts, pause
+        self._http = httpx.Client(base_url=_base_url(base_url), headers=_headers(secret), timeout=timeout, transport=transport, follow_redirects=False)
+
+    def _do(self, call):
+        response = error = None
+        for attempt in range(self.attempts):
+            if attempt:
+                time.sleep(_pause(attempt - 1, self.pause))
+            try:
+                response, error = self._http.request(call.method, call.path, json=call.body, params=call.params), None
+            except httpx.TransportError as e:
+                response, error = None, e
+                continue
+            got = _result(call, response)
+            if got is not None:
+                return got
+        raise _gave_up(call, response, error)
+
+    def iter_accounts(self, page=100):
+        """Every account, a page at a time."""
+        after = None
+        while True:
+            accounts, after = self.accounts(after, page)
+            yield from accounts
+            if after is None:
+                return
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+class AsyncChimera(_Calls):
+    """The same, for a Discord bot or any asyncio program. Every method but iter_accounts and aclose returns something to await."""
+
+    def __init__(self, secret, base_url, timeout=TIMEOUT_SECONDS, attempts=MAX_ATTEMPTS, pause=0.5, transport=None):
+        self.attempts, self.pause = attempts, pause
+        self._http = httpx.AsyncClient(base_url=_base_url(base_url), headers=_headers(secret), timeout=timeout, transport=transport, follow_redirects=False)
+
+    async def _do(self, call):
+        response = error = None
+        for attempt in range(self.attempts):
+            if attempt:
+                await asyncio.sleep(_pause(attempt - 1, self.pause))
+            try:
+                response, error = await self._http.request(call.method, call.path, json=call.body, params=call.params), None
+            except httpx.TransportError as e:
+                response, error = None, e
+                continue
+            got = _result(call, response)
+            if got is not None:
+                return got
+        raise _gave_up(call, response, error)
+
+    async def iter_accounts(self, page=100):
+        """Every account, a page at a time."""
+        after = None
+        while True:
+            accounts, after = await self.accounts(after, page)
+            for account in accounts:
+                yield account
+            if after is None:
+                return
+
+    async def aclose(self):
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()

chimerakit/errors.py

@@ -0,0 +1,40 @@
+"""What can go wrong, as one exception per kind of answer."""
+
+
+class ChimeraError(Exception):
+    """Anything the API refused or could not answer. `status` is the HTTP status, or None if no answer came. `request_id` is set on a call that made one: retry with it, never a new one."""
+
+    def __init__(self, message, status=None, request_id=None):
+        super().__init__(message)
+        self.status, self.request_id = status, request_id
+
+
+class AccessDenied(ChimeraError):
+    """401: a wrong, revoked or expired secret, a secret without this permission, or a bank that is not switched on. The answer does not say which, on purpose."""
+
+
+class LimitExceeded(ChimeraError):
+    """403: over the bank's limit for one transfer or for the day."""
+
+
+class NotFound(ChimeraError):
+    """404: missing, or another bank's. The answer does not say which, on purpose."""
+
+
+class Conflict(ChimeraError):
+    """409: it cannot go ahead as things stand. A frozen account, not enough funds, a deposit already in progress, or a request ID used for something else."""
+
+
+class InvalidRequest(ChimeraError):
+    """422: the request itself is wrong, such as an amount that is not a positive number."""
+
+
+class RateLimited(ChimeraError):
+    """429, after the retries ran out."""
+
+
+class Unavailable(ChimeraError):
+    """No clear answer, after the retries ran out. THE CALL MAY HAVE WORKED. Retry it with `request_id` from this error, and it cannot happen twice."""
+
+
+BY_STATUS = {401: AccessDenied, 403: LimitExceeded, 404: NotFound, 409: Conflict, 422: InvalidRequest, 429: RateLimited}

chimerakit/sandbox.py

@@ -0,0 +1,328 @@
+"""
+A pretend Chimera on your own computer. It holds no real funds, reaches nothing outside your computer, and forgets everything when it stops.
+
+    python -m chimerakit.sandbox
+
+    Chimera(SANDBOX_SECRET, base_url="http://127.0.0.1:8099")
+
+In real use the funds move in the game. Here you act that out by hand:
+
+    POST /sandbox/arrive    {"code": "...", "money": "100.00"}     the in-game transfer reaches Chimera. Add "note" to send a wrong note, and "alliance_id" to send from the wrong alliance
+    POST /sandbox/send      {"withdrawal_id": 1}                   Chimera sends a withdrawal to your alliance
+
+In Python, use the same two steps directly: `sandbox.arrive(code, money="100.00")` and `sandbox.send(withdrawal_id)`.
+
+Every answer has the same shape and status as the real API, and a test in Chimera's own repository holds the two together. Set `transfer_limit` and `daily_limit` to try your limit errors.
+"""
+import argparse
+import json
+import secrets
+import threading
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlsplit
+
+from .client import CENTS, RESOURCES
+
+SANDBOX_SECRET = "chim_sandbox_not-a-real-secret"
+ALLIANCE_ID = 1000
+CODE_LETTERS = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+WINDOW_MINUTES = 30
+MAX_PAGE = 500
+MAX_LINES = 500
+
+
+class _Refused(Exception):
+    def __init__(self, status, detail):
+        super().__init__(detail)
+        self.status, self.detail = status, detail
+
+
+def _text(amounts):
+    return {k: str(v) for k, v in amounts.items()}
+
+
+def _parse(amounts):
+    if not isinstance(amounts, dict) or not amounts:
+        raise _Refused(422, "Enter an amount.")
+    out = {}
+    for k, v in amounts.items():
+        if k not in RESOURCES or not isinstance(v, str) or not CENTS.fullmatch(v) or not Decimal(v):
+            raise _Refused(422, "Invalid request.")
+        out[k] = Decimal(v)
+    return out
+
+
+class Sandbox:
+    """The pretend bank and its web server. Use `with Sandbox() as s:` and give a client s.url."""
+
+    def __init__(self, port=0, alliance_id=ALLIANCE_ID, transfer_limit=Decimal(10) ** 12, daily_limit=Decimal(10) ** 13):
+        self.alliance_id, self.transfer_limit, self.daily_limit = alliance_id, Decimal(transfer_limit), Decimal(daily_limit)
+        self.lock = threading.RLock()
+        self.accounts, self.requests, self.used, self.next_id = {}, {}, {}, 1
+        self.server = ThreadingHTTPServer(("127.0.0.1", port), _handler(self))
+        self.url = "http://127.0.0.1:%d" % self.server.server_address[1]
+
+    def __enter__(self):
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        return self
+
+    def __exit__(self, *_):
+        self.server.shutdown()
+        self.server.server_close()
+
+    def _id(self):
+        self.next_id += 1
+        return self.next_id - 1
+
+    def _code(self):
+        return "".join(secrets.choice(CODE_LETTERS) for _ in range(16))
+
+    def _account_of(self, discord_id, nation_id, message="That account was not found."):
+        a = self.accounts.get(int(discord_id))
+        if a is None or a["nation_id"] != nation_id:
+            raise _Refused(404, message)
+        return a
+
+    def _limits(self, kind, amounts):
+        if any(v > self.transfer_limit for v in amounts.values()):
+            raise _Refused(403, "That is over this bank's limit for one transfer.")
+        if any(sum((r["amounts"].get(k, 0) for r in self.requests.values() if r["group"] == kind), Decimal(0)) + v > self.daily_limit for k, v in amounts.items()):
+            raise _Refused(403, "That is over this bank's limit for the day.")
+
+    def _status(self, r):
+        return r["status"]
+
+    def _account_view(self, a, with_pending=False):
+        view = {"accountid": str(a["accountid"]), "discord_id": str(a["discord_id"]), "nation_id": a["nation_id"], "custody": "chimera", "frozen": a["frozen"], "balances": {k: str(a["balances"][k]) for k in RESOURCES}}
+        if with_pending:
+            view["pending_deposits"] = [{"deposit_id": r["id"], "amounts": _text(amounts), "expires_at": r["expires_at"].isoformat()} for r in self.requests.values() if r["status"] == "waiting"
+                                        for acct, amounts in r["lines"] if acct is a]
+        return view
+
+    def _deposit_view(self, r, repeat=False):
+        a = r["lines"][0][0]
+        return {"deposit_id": r["id"], "accountid": str(a["accountid"]), "discord_id": str(a["discord_id"]), "nation_id": a["nation_id"], "alliance_id": self.alliance_id, "code": r["code"],
+                "amounts": _text(r["amounts"]), "status": r["status"], "created_at": r["created_at"].isoformat(), "expires_at": r["expires_at"].isoformat(), "repeat": repeat}
+
+    def _handoff_view(self, r, repeat=False):
+        lines = [{"accountid": str(a["accountid"]), "discord_id": str(a["discord_id"]), "nation_id": a["nation_id"], "amounts": _text(m)} for a, m in r["lines"]]
+        return {"handoff_id": r["id"], "alliance_id": self.alliance_id, "code": r["code"], "amounts": _text(r["amounts"]), "lines": lines, "status": r["status"],
+                "created_at": r["created_at"].isoformat(), "expires_at": r["expires_at"].isoformat(), "repeat": repeat}
+
+    def _withdrawal_view(self, r, repeat=False):
+        a = r["lines"][0][0]
+        return {"withdrawal_id": r["id"], "accountid": str(a["accountid"]), "discord_id": str(a["discord_id"]), "nation_id": a["nation_id"], "alliance_id": self.alliance_id, "code": r["code"],
+                "amounts": _text(r["amounts"]), "status": r["status"], "created_at": r["created_at"].isoformat(), "repeat": repeat}
+
+    def _new(self, kind, group, lines, amounts, key):
+        now = datetime.now(timezone.utc)
+        r = {"id": self._id(), "kind": kind, "group": group, "lines": lines, "amounts": amounts, "code": self._code(), "status": "waiting" if group == "deposit" else "processing", "key": key,
+             "created_at": now, "expires_at": now + timedelta(minutes=WINDOW_MINUTES), "confirmed": False}
+        self.requests[r["id"]] = r
+        return r
+
+    def _repeat(self, key):
+        return next((r for r in self.requests.values() if r["key"] == key), None)
+
+    def _find(self, kind, request_id, message):
+        r = self.requests.get(request_id)
+        if r is None or r["kind"] != kind:
+            raise _Refused(404, message)
+        return r
+
+    # -- the API --------------------------------------------------------------
+    def open_account(self, body):
+        d, nation = int(body["discord_id"]), body["nation_id"]
+        a = self.accounts.get(d)
+        if a is not None and a["nation_id"] != nation or any(x["nation_id"] == nation and x["discord_id"] != d for x in self.accounts.values()):
+            raise _Refused(422, "That Discord ID and nation do not match this bank's records.")
+        if a is None:
+            a = self.accounts[d] = {"accountid": 1000000 + len(self.accounts), "discord_id": d, "nation_id": nation, "frozen": False, "balances": {k: Decimal("0.00") for k in RESOURCES}}
+        return self._account_view(a)
+
+    def list_accounts(self, after, limit):
+        rows = sorted((a for a in self.accounts.values() if a["accountid"] > after), key=lambda a: a["accountid"])[:limit]
+        return {"accounts": [self._account_view(a, True) for a in rows], "next_after": str(rows[-1]["accountid"]) if len(rows) == limit else None}
+
+    def create_deposit(self, body):
+        amounts, key = _parse(body["amounts"]), "d:" + body["request_id"]
+        again = self._repeat(key)
+        if again:
+            a = again["lines"][0][0]
+            if (str(a["discord_id"]), a["nation_id"]) != (body["discord_id"], body["nation_id"]) or again["amounts"] != amounts:
+                raise _Refused(409, "That request ID was already used for a different deposit.")
+            return self._deposit_view(again, True)
+        a = self._account_of(body["discord_id"], body["nation_id"])
+        if a["frozen"]:
+            raise _Refused(409, "That account is frozen.")
+        self._limits("deposit", amounts)
+        if any(r["kind"] == "deposit" and r["status"] in ("waiting", "under_review") and r["lines"][0][0] is a for r in self.requests.values()):
+            raise _Refused(409, "That client already has a deposit in progress.")
+        return self._deposit_view(self._new("deposit", "deposit", [(a, amounts)], amounts, key))
+
+    def create_handoff(self, body):
+        wanted, total = [], {}
+        lines = body["lines"]
+        if len({x["discord_id"] for x in lines}) != len(lines):
+            raise _Refused(422, "A client can only appear once in a handoff.")
+        for x in lines:
+            m = _parse(x["amounts"])
+            wanted.append((x, m))
+            for k, v in m.items():
+                total[k] = total.get(k, Decimal(0)) + v
+        key = "h:" + body["request_id"]
+        again = self._repeat(key)
+        if again:
+            if {(a["discord_id"], tuple(sorted(m.items()))) for a, m in again["lines"]} != {(int(x["discord_id"]), tuple(sorted(m.items()))) for x, m in wanted}:
+                raise _Refused(409, "That request ID was already used for a different handoff.")
+            return self._handoff_view(again, True)
+        accounts = []
+        for x, m in wanted:
+            a = self._account_of(x["discord_id"], x["nation_id"], "The account for client %s was not found." % x["discord_id"])
+            if a["frozen"]:
+                raise _Refused(409, "The account for client %s is frozen." % x["discord_id"])
+            accounts.append((a, m))
+        self._limits("deposit", total)
+        return self._handoff_view(self._new("handoff", "deposit", accounts, total, key))
+
+    def create_withdrawal(self, body):
+        amounts, key = _parse(body["amounts"]), "w:" + body["request_id"]
+        again = self._repeat(key)
+        if again:
+            a = again["lines"][0][0]
+            if (str(a["discord_id"]), a["nation_id"]) != (body["discord_id"], body["nation_id"]) or again["amounts"] != amounts:
+                raise _Refused(409, "That request ID was already used for a different withdrawal.")
+            return self._withdrawal_view(again, True)
+        a = self._account_of(body["discord_id"], body["nation_id"])
+        if a["frozen"]:
+            raise _Refused(409, "That account is frozen.")
+        self._limits("withdraw", amounts)
+        if any(a["balances"][k] < v for k, v in amounts.items()):
+            raise _Refused(409, "That account does not hold enough.")
+        for k, v in amounts.items():
+            a["balances"][k] -= v
+        return self._withdrawal_view(self._new("withdrawal", "withdraw", [(a, amounts)], amounts, key))
+
+    def confirm_withdrawal(self, withdrawal_id, code):
+        r = self._find("withdrawal", withdrawal_id, "That withdrawal was not found.")
+        if r["code"] != code:
+            raise _Refused(409, "That code does not match this withdrawal.")
+        if r["status"] not in ("sent", "completed"):
+            raise _Refused(409, "That withdrawal has not been sent.")
+        view = self._withdrawal_view(r)                 # as on the real API: this answer shows what was true when the bank called
+        r["status"] = "completed"
+        return view
+
+    # -- acting out the game ----------------------------------------------------
+    def arrive(self, code, note=None, alliance_id=None, **amounts):
+        """The in-game transfer reaches Chimera. Returns what happened: credited, or under_review with the reason the real worker would give."""
+        with self.lock:
+            r = next((x for x in self.requests.values() if x["code"] == code and x["group"] == "deposit"), None)
+            if r is None:
+                raise _Refused(404, "No deposit has that code.")
+            sent = {k: Decimal(str(v)) for k, v in amounts.items()}
+            why = ("The funds came from another alliance." if alliance_id not in (None, self.alliance_id) else "The note is not exactly the code." if (code if note is None else note) != code
+                   else "This code was already used." if r["status"] == "credited" else "The amounts sent do not match the request." if sent != r["amounts"] else None)
+            if why:
+                r["status"] = "under_review" if r["status"] != "credited" else r["status"]
+                return {"status": "under_review", "reason": why}
+            for a, m in r["lines"]:
+                for k, v in m.items():
+                    a["balances"][k] += v
+            r["status"] = "credited"
+            return {"status": "credited", "reason": None}
+
+    def send(self, withdrawal_id):
+        """Chimera sends the withdrawal. Check `code` against your in-game record, then confirm."""
+        with self.lock:
+            r = self._find("withdrawal", withdrawal_id, "That withdrawal was not found.")
+            r["status"] = "sent"
+            return {"status": "sent", "code": r["code"]}
+
+
+def _handler(box):
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *_):
+            pass
+
+        def _answer(self, status, body):
+            data = json.dumps(body).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        def _route(self, method, path, query, body):
+            if path == "/health":
+                return 200, {"status": "ok"}
+            if path == "/sandbox/arrive":
+                kw = dict(body)
+                return 200, box.arrive(kw.pop("code"), **kw)
+            if path == "/sandbox/send":
+                return 200, box.send(body["withdrawal_id"])
+            if self.headers.get("Authorization") != "Bearer " + SANDBOX_SECRET:
+                raise _Refused(401, "Not authorized.")
+            if (method, path) == ("POST", "/v1/accounts"):
+                return 201, box.open_account(body)
+            if (method, path) == ("GET", "/v1/accounts"):
+                limit = int(query.get("limit", ["100"])[0])
+                if not 1 <= limit <= MAX_PAGE:
+                    raise _Refused(422, "Invalid request.")
+                return 200, box.list_accounts(int(query.get("after", ["0"])[0]), limit)
+            if (method, path) == ("POST", "/v1/deposits"):
+                return 201, box.create_deposit(body)
+            if (method, path) == ("POST", "/v1/handoffs"):
+                if not 1 <= len(body.get("lines", [])) <= MAX_LINES:
+                    raise _Refused(422, "Invalid request.")
+                return 201, box.create_handoff(body)
+            if (method, path) == ("POST", "/v1/withdrawals"):
+                return 201, box.create_withdrawal(body)
+            parts = path.strip("/").split("/")
+            if method == "GET" and len(parts) == 3 and parts[0] == "v1" and parts[2].isdigit():
+                found = {"deposits": ("deposit", box._deposit_view, "That deposit was not found."), "handoffs": ("handoff", box._handoff_view, "That handoff was not found."),
+                         "withdrawals": ("withdrawal", box._withdrawal_view, "That withdrawal was not found.")}.get(parts[1])
+                if found:
+                    return 200, found[1](box._find(found[0], int(parts[2]), found[2]))
+            if method == "POST" and len(parts) == 4 and parts[:2] == ["v1", "withdrawals"] and parts[3] == "confirm" and parts[2].isdigit():
+                return 200, box.confirm_withdrawal(int(parts[2]), body.get("code"))
+            raise _Refused(404, "Not Found")
+
+        def _serve(self, method):
+            url = urlsplit(self.path)
+            length = int(self.headers.get("Content-Length") or 0)
+            try:
+                body = json.loads(self.rfile.read(length) or b"{}")
+                with box.lock:
+                    status, answer = self._route(method, url.path, parse_qs(url.query), body)
+            except _Refused as e:
+                status, answer = e.status, {"detail": e.detail}
+            except (KeyError, TypeError, ValueError):
+                status, answer = 422, {"detail": "Invalid request."}
+            self._answer(status, answer)
+
+        def do_GET(self):
+            self._serve("GET")
+
+        def do_POST(self):
+            self._serve("POST")
+
+    return Handler
+
+
+def main():
+    parser = argparse.ArgumentParser(description="A pretend Chimera on your own computer. No real funds.")
+    parser.add_argument("--port", type=int, default=8099)
+    args = parser.parse_args()
+    box = Sandbox(args.port)
+    print("Sandbox at %s\nTest secret: %s\nPress Ctrl+C to stop. Everything is forgotten when it stops." % (box.url, SANDBOX_SECRET), flush=True)
+    try:
+        box.server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

chimerakit-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: chimerakit
+Version: 0.1.0
+Summary: Python client for the Chimera partner bank API
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+
+# chimerakit
+
+The Python client for the Chimera partner bank API. Your bank keeps its own bot and its own clients. Chimera holds the funds and the ledger.
+
+    pip install ./chimerakit
+
+```python
+from chimerakit import Chimera
+
+chimera = Chimera(os.environ["CHIMERA_SECRET"], base_url="https://api.projectimagite.com")
+```
+
+**The pilot is deposits only.** Deposits, handoffs and balances work. **Withdrawals are not available yet** — your secret will not carry that scope, so `create_withdrawal` is refused with `AccessDenied` until Chimera turns it on. Everything about withdrawals below is written for when it does; build against it if you like, but you cannot exercise it outside the sandbox. Getting funds back out during the pilot is arranged with Chimera directly, and the terms say how.
+
+## Try it first, with no real funds
+
+The sandbox is a pretend Chimera on your own computer. It holds no real funds and needs no account. Start it with:
+
+    python -m chimerakit.sandbox
+
+Then point your own bot at it:
+
+```python
+from chimerakit import Chimera
+from chimerakit.sandbox import SANDBOX_SECRET
+
+chimera = Chimera(SANDBOX_SECRET, base_url="http://127.0.0.1:8099")
+```
+
+The sandbox gives the same answers as the real API, and a test in Chimera's repository holds the two together. It has no `under_review` queue with staff behind it, and it never expires a code.
+
+## Using it
+
+`Chimera` is for a blocking program. `AsyncChimera` has the same methods for a Discord bot or anything on asyncio. Worked examples for both — `quickstart.py` and `discord_bot.py` — come with the source rather than the installed package; ask Chimera for them if you do not have the repository.
+
+| Method | What it does |
+|---|---|
+| `open_account(discord_id, nation_id)` | Opens an empty account. Harmless to repeat |
+| `accounts(after, limit)`, `iter_accounts()` | Your clients' balances, each with any deposits on the way |
+| `create_deposit(discord_id, nation_id, amounts, request_id)` | Says funds are coming, and gets the code |
+| `get_deposit(deposit_id)` | `waiting`, `credited`, `expired` or `under_review` |
+| `create_handoff(lines, request_id)` | One transfer for up to 500 clients |
+| `get_handoff(handoff_id)` | The same four statuses |
+| `create_withdrawal(discord_id, nation_id, amounts, request_id)` | Takes the amounts off the balance at once |
+| `get_withdrawal(withdrawal_id)` | `processing`, `sent`, `completed`, `failed` or `under_review` |
+| `confirm_withdrawal(withdrawal_id, code)` | Says the funds reached your alliance |
+
+### A deposit
+
+1. `create_deposit` gives you a `code`, an `alliance_id` and `amounts`.
+2. Send exactly those amounts, in the game, from your registered alliance to Chimera (alliance 15065).
+3. The code must be the **whole note**, with nothing around it. A note like `deposit ABCD...` is not credited.
+4. Do it before `expires_at`. Funds that arrive late are not lost, but a person has to settle them.
+5. Watch `get_deposit` until it says `credited`.
+
+Only a transfer from your registered alliance counts. Sends from a nation, by trade or from another alliance are never credited automatically.
+
+A client can have one deposit in progress at a time.
+
+### A handoff
+
+The tool for a raid: everything leaves your alliance in one transfer, and each client is credited their share.
+
+```python
+from chimerakit import Line
+
+handoff = chimera.create_handoff([
+    Line(discord_id="1100000000000000001", nation_id=111, amounts={"money": "250.00"}),
+    Line(discord_id="1100000000000000002", nation_id=222, amounts={"money": "750.00", "steel": "10"}),
+])
+```
+
+Send `handoff.amounts`, the total, with `handoff.code` as the whole note. It credits every line or none. Every client needs an account first, and a client frozen or unknown refuses the whole handoff. If the amounts differ by a cent, nobody is credited and a person settles it, so send the total exactly. Limits count the total.
+
+A handoff doesn't stop a client depositing, and a client can be in more than one.
+
+### A withdrawal
+
+**Not available in the pilot** — your secret has no `withdrawals` scope, so these three calls return `AccessDenied`. The sandbox supports them, so you can still build and test against it.
+
+1. `create_withdrawal` takes the funds off the client's balance at once.
+2. Chimera sends them to your registered alliance, never to a client. The note is the withdrawal's `code`.
+3. When the status is `sent`, find the transfer in your alliance's bank record and check that its note equals `code`.
+4. Pay your client, then call `confirm_withdrawal`.
+5. It becomes `completed` when your confirmation and the game's record agree.
+
+A large withdrawal may wait for a person, and it stays `processing` or shows `under_review` while it does. Keep checking, and don't send a second one.
+
+## Amounts
+
+Give amounts as `Decimal`, `int` or `str`, with at most two decimal places. A `float` is refused, because it has already been rounded. Amounts come back as `Decimal`.
+
+The names are `money`, `food`, `coal`, `oil`, `uranium`, `lead`, `iron`, `bauxite`, `gasoline`, `munitions`, `steel` and `aluminum`.
+
+## Retries
+
+Failed calls are tried again automatically, up to four tries in all, and a retry cannot act twice. Each deposit, handoff and withdrawal carries a request ID, and Chimera acts on an ID once.
+
+If you let the client make the ID, it still protects its own retries. To be safe across a crash, make the ID yourself with `new_request_id()`, save it, and only then make the call.
+
+If the tries run out you get `Unavailable`. **That doesn't mean the call failed.** It means there was no clear answer. Repeat the call with `e.request_id`, and never with a new ID: a new ID on a withdrawal could take the funds twice.
+
+Using an ID again with different details is refused with `Conflict`.
+
+## Errors
+
+Each one has `status` and `request_id`, and they all come from `ChimeraError`.
+
+| Error | Means | What to do |
+|---|---|---|
+| `AccessDenied` | Wrong or revoked secret, or your bank isn't switched on | Don't retry. Talk to Chimera |
+| `LimitExceeded` | Over your bank's limit for one transfer or the day | Don't retry. Limits are set by Chimera |
+| `NotFound` | Missing, or not yours | Don't retry |
+| `Conflict` | Frozen, not enough funds, a deposit in progress, an ID reused | Read the message |
+| `InvalidRequest` | The request itself is wrong | Fix it |
+| `RateLimited` | Over 300 calls a minute, after the retries | Slow down |
+| `Unavailable` | No clear answer, after the retries | Repeat with the same ID |
+
+## Your secret
+
+Treat it like a key to your clients' funds, because it is one. Keep it in an environment variable. Never commit it or log it. If it leaks, tell Chimera at once: it can be replaced in seconds, and your clients' balances don't change. The client refuses to send it anywhere but HTTPS, apart from this computer for the sandbox, and it doesn't follow redirects.
+
+Your secret begins `chim_`. Chimera stores only a hash of it, so nobody there can read it back to you — if it is lost, it is replaced rather than recovered.
+
+### What your secret is allowed to do
+
+A secret carries **scopes**, and each call needs the right one. Chimera decides which yours has; you cannot change them.
+
+| Scope | Lets you call | In the pilot |
+|---|---|---|
+| `balances` | `open_account`, `accounts`, `iter_accounts` | **yes** |
+| `deposits` | `create_deposit`, `get_deposit`, `create_handoff`, `get_handoff` | **yes** |
+| `withdrawals` | `create_withdrawal`, `get_withdrawal`, `confirm_withdrawal` | no — see the note at the top |
+| `transfers` | reserved for moving funds between clients. **No methods use it yet** | no |
+
+A call outside your scopes fails with `AccessDenied`, and so does a wrong secret, a revoked one, an expired one, or a bank that is switched off. **They are deliberately the same error** — it tells you nothing about which, so that a stolen secret learns nothing by probing. If you get `AccessDenied` and believe you should not have, ask Chimera rather than retrying; retrying never helps.

chimerakit-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+chimerakit/__init__.py,sha256=941xBfReZ_bVimP32SPgYQajWK5FcUmhLuPIj9ej768,487
+chimerakit/client.py,sha256=iC1GBxZaFN7g8c-TxWRfjjRba07uGNqU06iLNHwk_uM,14415
+chimerakit/errors.py,sha256=ivN4cgtKyZ7wuFaF-H9YD6BnfUXwPyXgYfeuYFq1NIs,1613
+chimerakit/sandbox.py,sha256=AmTN04d844JIrkvYT5_5hF6x3VhiKWnFYJyRzf85Xx4,17193
+chimerakit-0.1.0.dist-info/METADATA,sha256=W5BI4SN8FLnlLv4iMHKJ4kxPe_Mg9xuenw6bWtG_6Nw,8373
+chimerakit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+chimerakit-0.1.0.dist-info/top_level.txt,sha256=Ybv8scEO7gb9kiEdLf0TrU681Q8SI0EAWlDNu0mk9m0,11
+chimerakit-0.1.0.dist-info/RECORD,,

chimerakit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chimerakit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chimerakit