From 067fe9d7fd5995ffd2715153db08e48b828358be Mon Sep 17 00:00:00 2001 From: Kabzelife <141412378+Kabzelife@users.noreply.github.com> Date: Sun, 8 Nov 2026 10:38:35 +0100 Subject: [PATCH] 0.9.1: theses with external_id, history mint filter Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 14 ++++++ README.md | 20 ++++----- cabalspy_id/_client.py | 93 +++++++++++++++++++++++++++------------ cabalspy_id/_constants.py | 2 +- cabalspy_id/_types.py | 4 ++ pyproject.toml | 2 +- tests/test_theses.py | 35 +++++++++++++++ tests/test_trade_feed.py | 2 +- 8 files changed, 130 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 040b422..c58432f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,20 @@ All notable changes to this package are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/). +## [0.9.1] - 2026-11-08 + +### Fixed + +- Theses in the name of a platform user: `thesis_eligibility`, `post_thesis`, `reply_to_thesis`, + `react_to_thesis`, `report_thesis`, `delete_thesis`, `thesis_notifications` and + `appeal_thesis_decision` take `external_id=` in place of `csid_id` (they accepted only + `csid_id` before). Exactly one of the two. + +### Added + +- `history(mint=)`: only the trades of one token, for example to mark a user's buys and sells on + a price chart. History trades carry `token_amount` and `price_usd`. + ## [0.9.0] - 2026-11-01 Trade Feed: read and manage your users' Trade Feeds from your backend (the traders they follow, diff --git a/README.md b/README.md index 8408e37..5b04e12 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,7 @@ The API key is the **same key as the CabalSpy API**, with the per-key toggle "Ca | `profile(username= \| csid_id= \| address=)` | `GET /v1/profile` | | `wallet_lookup(address)` | `GET /v1/wallets/lookup` | | `tracker(blockchain=, address=, period=)` | `GET /v1/wallets/tracker` | -| `history(blockchain=, address=, limit=, cursor=)` | `GET /v1/wallets/history` | +| `history(blockchain=, address=, limit=, cursor=, mint=)` | `GET /v1/wallets/history` | | `holdings(blockchain=, address=)` | `GET /v1/wallets/holdings` | | `pnl_calendar(blockchain=, address=)` | `GET /v1/wallets/pnl_calendar` | | `leaderboard(blockchain=, period=, sort=, limit=, cursor=, scope=)` | `GET /v1/wallets/leaderboard` | @@ -558,15 +558,15 @@ if ok["can_post"]: | `thesis_replies(id, limit=, cursor=)` / `iter_thesis_replies()` | `GET /v1/theses/replies` | | `latest_theses(blockchain=, users="all" \| "instance", limit=, cursor=)` | `GET /v1/theses/latest` | | `user_theses(csid_id= \| username=)` | `GET /v1/theses/user` | -| `thesis_eligibility(blockchain=, mint=, csid_id=)` | `GET /v1/theses/eligibility` | -| `post_thesis(blockchain=, mint=, body=, stance=, csid_id=)` | `POST /v1/theses` | -| `reply_to_thesis(thesis_id=, body=, csid_id=)` | `POST /v1/theses/replies` | -| `react_to_thesis(thesis_id=, emoji=, on=, csid_id=)` | `POST /v1/theses/reactions` | -| `report_thesis(thesis_id=, reason=, note=, csid_id=)` | `POST /v1/theses/report` | -| `delete_thesis(thesis_id=, csid_id=)` | `POST /v1/theses/delete` | - -| `thesis_notifications(csid_id)` | `GET /v1/theses/notifications` | -| `appeal_thesis_decision(csid_id, notification_id, message)` | `POST /v1/theses/appeal` | +| `thesis_eligibility(blockchain=, mint=, csid_id= \| external_id=)` | `GET /v1/theses/eligibility` | +| `post_thesis(blockchain=, mint=, body=, stance=, csid_id= \| external_id=)` | `POST /v1/theses` | +| `reply_to_thesis(thesis_id=, body=, csid_id= \| external_id=)` | `POST /v1/theses/replies` | +| `react_to_thesis(thesis_id=, emoji=, on=, csid_id= \| external_id=)` | `POST /v1/theses/reactions` | +| `report_thesis(thesis_id=, reason=, note=, csid_id= \| external_id=)` | `POST /v1/theses/report` | +| `delete_thesis(thesis_id=, csid_id= \| external_id=)` | `POST /v1/theses/delete` | + +| `thesis_notifications(csid_id \| external_id=)` | `GET /v1/theses/notifications` | +| `appeal_thesis_decision(csid_id, notification_id, message, external_id=)` | `POST /v1/theses/appeal` | Every thesis carries `reacted_by` (the latest reactions with who reacted) and, for theses, `latest_replies` (a preview of the newest replies). diff --git a/cabalspy_id/_client.py b/cabalspy_id/_client.py index a1702a6..d70ebd5 100644 --- a/cabalspy_id/_client.py +++ b/cabalspy_id/_client.py @@ -678,16 +678,25 @@ def history( limit: int | None = None, cursor: str | None = None, scope: Scope | None = None, + mint: str | None = None, ) -> Any: """GET /v1/wallets/history — lifetime stats, token overview and one page - of trades (``limit`` 1-1000, default 500). + of trades (``limit`` 1-1000, default 500). ``mint``: only the trades of + this token (the stats then cover this token only). Returns :class:`~cabalspy_id.HistoryResponse`. """ _wallet(blockchain, address) return self._get( "/wallets/history", - {"blockchain": blockchain, "address": address, "limit": limit, "cursor": cursor, "scope": scope}, + { + "blockchain": blockchain, + "address": address, + "limit": limit, + "cursor": cursor, + "scope": scope, + "mint": mint, + }, ) def holdings(self, *, blockchain: Chain, address: str, scope: Scope | None = None) -> Any: @@ -847,86 +856,112 @@ def user_theses( }, ) - def thesis_eligibility(self, *, blockchain: Chain, mint: str, csid_id: str) -> Any: + def thesis_eligibility( + self, *, blockchain: Chain, mint: str, csid_id: str | None = None, external_id: str | None = None + ) -> Any: """GET /v1/theses/eligibility — may this user post (holder, not paused) and reply here through your app? ``reason`` says why not (consent_required, plan_user_limit, sandbox_user). Returns :class:`~cabalspy_id.ThesisEligibility`. """ _token(blockchain, mint) - _required(csid_id, "csid_id") - return self._get("/theses/eligibility", {"blockchain": blockchain, "mint": mint, "csid_id": csid_id}) + return self._get("/theses/eligibility", {"blockchain": blockchain, "mint": mint, **_who(external_id, csid_id)}) # Writing happens in the name of one of your users: ``csid_id`` is the ``sub`` - # of their ID token. They must have signed in with the scope "thesis". + # of their ID token (they signed in with the scope "thesis"), or + # ``external_id`` for a platform user (white-label). Exactly one of them. def post_thesis( - self, *, blockchain: Chain, mint: str, body: str, csid_id: str, stance: ThesisStance | None = None + self, + *, + blockchain: Chain, + mint: str, + body: str, + csid_id: str | None = None, + external_id: str | None = None, + stance: ThesisStance | None = None, ) -> Any: """POST /v1/theses — posts a thesis (up to 1000 characters). Holders only (``not_a_holder``).""" _token(blockchain, mint) _required(body, "body") - _required(csid_id, "csid_id") + who = _who(external_id, csid_id) _one_of(stance, ("bull", "bear"), "stance") - payload: dict[str, Any] = {"blockchain": blockchain, "mint": mint, "body": body, "csid_id": csid_id} + payload: dict[str, Any] = {"blockchain": blockchain, "mint": mint, "body": body, **who} if stance: payload["stance"] = stance return self._post("/theses", payload) - def reply_to_thesis(self, *, thesis_id: str, body: str, csid_id: str) -> Any: + def reply_to_thesis( + self, *, thesis_id: str, body: str, csid_id: str | None = None, external_id: str | None = None + ) -> Any: """POST /v1/theses/replies — replies to a thesis.""" _required(thesis_id, "thesis_id") _required(body, "body") - _required(csid_id, "csid_id") - return self._post("/theses/replies", {"thesis_id": thesis_id, "body": body, "csid_id": csid_id}) + return self._post("/theses/replies", {"thesis_id": thesis_id, "body": body, **_who(external_id, csid_id)}) - def react_to_thesis(self, *, thesis_id: str, emoji: ThesisEmoji, csid_id: str, on: bool = True) -> Any: + def react_to_thesis( + self, + *, + thesis_id: str, + emoji: ThesisEmoji, + csid_id: str | None = None, + external_id: str | None = None, + on: bool = True, + ) -> Any: """POST /v1/theses/reactions — adds (or with ``on=False`` removes) a reaction. Returns ``{"id", "reactions"}`` with the new counts. """ _required(thesis_id, "thesis_id") _one_of(emoji, THESIS_EMOJIS, "emoji") - _required(csid_id, "csid_id") - return self._post("/theses/reactions", {"thesis_id": thesis_id, "emoji": emoji, "on": on, "csid_id": csid_id}) + who = _who(external_id, csid_id) + return self._post("/theses/reactions", {"thesis_id": thesis_id, "emoji": emoji, "on": on, **who}) def report_thesis( - self, *, thesis_id: str, reason: ThesisReportReason, csid_id: str, note: str | None = None + self, + *, + thesis_id: str, + reason: ThesisReportReason, + csid_id: str | None = None, + external_id: str | None = None, + note: str | None = None, ) -> Any: """POST /v1/theses/report — reports a post (hidden for review after 3 reports).""" _required(thesis_id, "thesis_id") _one_of(reason, THESIS_REPORT_REASONS, "reason") - _required(csid_id, "csid_id") - payload: dict[str, Any] = {"thesis_id": thesis_id, "reason": reason, "csid_id": csid_id} + payload: dict[str, Any] = {"thesis_id": thesis_id, "reason": reason, **_who(external_id, csid_id)} if note: payload["note"] = note return self._post("/theses/report", payload) - def thesis_notifications(self, csid_id: str) -> Any: + def thesis_notifications(self, csid_id: str | None = None, *, external_id: str | None = None) -> Any: """GET /v1/theses/notifications — moderation notifications of one of your users (warnings, hidden posts, pauses, appeal results), with the unread count. Returns :class:`~cabalspy_id.ThesisNotifications`. """ - _required(csid_id, "csid_id") - return self._get("/theses/notifications", {"csid_id": csid_id}) + return self._get("/theses/notifications", _who(external_id, csid_id)) - def appeal_thesis_decision(self, csid_id: str, notification_id: int, message: str) -> Any: + def appeal_thesis_decision( + self, + csid_id: str | None = None, + notification_id: int | None = None, + message: str | None = None, + *, + external_id: str | None = None, + ) -> Any: """POST /v1/theses/appeal — appeals a moderation decision in the user's name (an ``appealable`` notification, within 30 days; message 10-1000 characters). """ - _required(csid_id, "csid_id") + who = _who(external_id, csid_id) _required(notification_id, "notification_id") _required(message, "message") - return self._post( - "/theses/appeal", {"csid_id": csid_id, "notification_id": notification_id, "message": message} - ) + return self._post("/theses/appeal", {**who, "notification_id": notification_id, "message": message}) - def delete_thesis(self, *, thesis_id: str, csid_id: str) -> Any: + def delete_thesis(self, *, thesis_id: str, csid_id: str | None = None, external_id: str | None = None) -> Any: """POST /v1/theses/delete — deletes the user's own thesis or reply.""" _required(thesis_id, "thesis_id") - _required(csid_id, "csid_id") - return self._post("/theses/delete", {"thesis_id": thesis_id, "csid_id": csid_id}) + return self._post("/theses/delete", {"thesis_id": thesis_id, **_who(external_id, csid_id)}) # ── white-label: platform users ────────────────────────────────────── # Your platform keeps its own login and addresses its users by its own user diff --git a/cabalspy_id/_constants.py b/cabalspy_id/_constants.py index 288ade2..fc26623 100644 --- a/cabalspy_id/_constants.py +++ b/cabalspy_id/_constants.py @@ -4,7 +4,7 @@ from typing import Literal -SDK_VERSION = "0.9.0" +SDK_VERSION = "0.9.1" USER_AGENT = f"cabalspy-id-python/{SDK_VERSION}" DEFAULT_BASE_URL = "https://api-id.cabalspy.xyz/v1" diff --git a/cabalspy_id/_types.py b/cabalspy_id/_types.py index 96e27a7..b2cd5fa 100644 --- a/cabalspy_id/_types.py +++ b/cabalspy_id/_types.py @@ -312,6 +312,10 @@ class HistoryTrade(TypedDict): value: float value_usd: float currency: Currency + token_amount: float | None + """Tokens bought or sold.""" + price_usd: float | None + """USD price per token at the trade (value_usd / token_amount).""" created_at: str diff --git a/pyproject.toml b/pyproject.toml index ee88410..3096851 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "cabalspy-id" -version = "0.9.0" +version = "0.9.1" description = "SocialFi API & SDK for CabalSpy ID — add a social layer to any app: login with X + verified wallets, live trades and PnL of your users, token theses, leaderboards and copy trading on Solana, BNB Chain, Base, Ethereum and Robinhood Chain." readme = "README.md" license = "MIT" diff --git a/tests/test_theses.py b/tests/test_theses.py index c4e112a..f0d0fb8 100644 --- a/tests/test_theses.py +++ b/tests/test_theses.py @@ -147,6 +147,41 @@ def handler(r: httpx.Request) -> httpx.Response: assert rec.requests[0].headers["content-type"] == "application/json" +def test_platform_user_writes_by_external_id() -> None: + def handler(r: httpx.Request) -> httpx.Response: + if r.url.path.endswith("/reactions"): + return ok({"id": "t1", "reactions": {"like": 1}}) + if r.url.path.endswith("/eligibility"): + return ok({"can_post": True, "can_reply": True, "holder": True, "paused": False}) + if r.url.path.endswith("/notifications"): + return ok({"unread": 0, "items": []}) + return ok(thesis()) + + csid, rec = make(handler) + csid.thesis_eligibility(blockchain="solana", mint=MINT, external_id="user_1") + csid.post_thesis(blockchain="solana", mint=MINT, body="gm", external_id="user_1") + csid.reply_to_thesis(thesis_id="t1", body="Nice call", external_id="user_2") + csid.react_to_thesis(thesis_id="t1", emoji="like", external_id="user_2") + csid.thesis_notifications(external_id="user_1") + csid.thesis_notifications(USER) + assert [(r.method, pq(r), json.loads(r.content) if r.content else None) for r in rec.requests] == [ + ("GET", f"/v1/theses/eligibility?blockchain=solana&mint={MINT}&external_id=user_1", None), + ("POST", "/v1/theses?", {"blockchain": "solana", "mint": MINT, "body": "gm", "external_id": "user_1"}), + ("POST", "/v1/theses/replies?", {"thesis_id": "t1", "body": "Nice call", "external_id": "user_2"}), + ("POST", "/v1/theses/reactions?", {"thesis_id": "t1", "emoji": "like", "on": True, "external_id": "user_2"}), + ("GET", "/v1/theses/notifications?external_id=user_1", None), + ("GET", f"/v1/theses/notifications?csid_id={USER}", None), + ] + with pytest.raises(BadRequestError): + csid.post_thesis(blockchain="solana", mint=MINT, body="x", csid_id=USER, external_id="u") + + +def test_history_mint_filter() -> None: + csid, rec = make(lambda r: ok({"trades": []})) + csid.history(blockchain="solana", address=MINT, mint="TokenMint1") + assert pq(rec.requests[0]) == f"/v1/wallets/history?blockchain=solana&address={MINT}&mint=TokenMint1" + + def test_validation() -> None: csid, rec = make(lambda r: ok({})) with pytest.raises(BadRequestError): diff --git a/tests/test_trade_feed.py b/tests/test_trade_feed.py index f6c44c1..9fa53ef 100644 --- a/tests/test_trade_feed.py +++ b/tests/test_trade_feed.py @@ -375,7 +375,7 @@ def test_trade_feed_webhook_events() -> None: def test_exports() -> None: import cabalspy_id - assert cabalspy_id.__version__ == "0.9.0" + assert cabalspy_id.__version__ == "0.9.1" assert api.TradeFeedStream is cabalspy_id.TradeFeedStream assert cabalspy_id.TRADE_FEED_EVENTS == ("trade_feed.trade", "trade_feed.thesis") assert "ready" in cabalspy_id.TRADE_FEED_STREAM_EVENTS