diff --git a/CHANGELOG.md b/CHANGELOG.md index c58432f..fb2b411 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,25 @@ 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.10.0] - 2026-11-08 + +One person, one CabalSpy ID. A platform may create an account for its user, but the person +owns it: when they prove through your platform (X, Telegram or a paid wallet) an identity +their own CabalSpy ID holds, your link moves to that ID; when they sign in themselves, they +manage it. Your `external_id` always stays. + +### Added + +- Webhook events `platform_user.merged` (`previous_csid_id`, `reason`, `skipped_wallets`), + `platform_user.self_managed` and `platform_user.telegram_linked` in `PLATFORM_WEBHOOK_EVENTS`. +- `PlatformUser` fields `self_managed`, `self_managed_at` and `merged_from`. + +### Deprecated + +- `platform_user_claim_link()`: claim links are gone, the API answers 410 `claim_removed`. + `claimed` / `claimed_at` are the old names of `self_managed` / `self_managed_at`; + `platform_user.claimed` is no longer sent. + ## [0.9.1] - 2026-11-08 ### Fixed diff --git a/README.md b/README.md index 5b04e12..09c6ca2 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ except RateLimitError as err: | `PermissionError` | 403 | `invalid_api_key`, `product_not_enabled`, `no_instance`, `scope_not_allowed`, `claim_disabled`, `feature_not_enabled`, `kol_only`, `not_a_holder`, `invalid_account`, `posting_paused`, `consent_required`, `sandbox_user`, `trading_private` | | `PlanUserLimitError` | 403 | `plan_user_limit` | | `NotFoundError` | 404 | `profile_not_found`, `wallet_not_found`, `instance_not_found`, `platform_user_not_found`, `verification_not_found`, `competition_not_found`, `callout_not_found`, `trader_not_found`, `not_in_trade_feed`, `not_found` | -| `ConflictError` | 409 | `account_claimed`, `last_wallet`, `too_many_wallets`, `wallet_already_verified`, `kol_badge`, `x_required`, `kol_not_eligible`, `competition_limit`, `competition_closed`, `competition_full`, `late_join_closed`, `already_called`, `copy_managed_elsewhere`, `already_reported`, `trade_feed_full` | +| `ConflictError` | 409 | `self_managed`, `already_linked`, `last_wallet`, `too_many_wallets`, `wallet_already_verified`, `kol_badge`, `x_required`, `kol_not_eligible`, `competition_limit`, `competition_closed`, `competition_full`, `late_join_closed`, `already_called`, `copy_managed_elsewhere`, `already_reported`, `trade_feed_full` | | `RateLimitError` | 429 | `rate_limit_exceeded`, `rate_limited` (also the Trade Feed's 120 changes per hour; not retried), `too_many_open_verifications`, `callout_cooldown` | | `ServerError` | 5xx | `internal_error`, `service_unavailable` | | `APIConnectionError` | – | network failure, timeout | @@ -302,7 +302,7 @@ Every platform-users method that takes a user accepts the `external_id` position | `platform_settings()` / `update_platform_settings(...)` | `GET` / `POST /v1/platform-users/settings` | | `platform_inbound()` / `enable_platform_inbound()` / `disable_platform_inbound()` | `/v1/platform-users/inbound[/enable\|/disable]` | | `platform_user_session(external_id)` | `POST /v1/platform-users/session` (verify widget, 15 min) | -| `platform_user_claim_link(external_id, return_url=)` | `POST /v1/platform-users/claim-link` | +| ~~`platform_user_claim_link()`~~ | removed: 410 `claim_removed` (one CabalSpy ID per person, see below) | | `connect_platform_user_x(external_id, return_url=)` / `disconnect_platform_user_x(external_id)` | `POST /v1/platform-users/x/connect`, `/x/disconnect` | | `link_platform_user_telegram` / `platform_user_telegram` / `unlink_platform_user_telegram` | `/v1/platform-users/telegram[/link\|/unlink]` | | `platform_user_kol` / `request_platform_user_volume_check` / `apply_platform_user_kol` | `/v1/platform-users/kol[/volume-check\|/apply]` | @@ -328,7 +328,9 @@ Individual competitions between your platform users, at most 5 scheduled + runni The competition routes page by `offset`; the `iter_*` helpers walk them until `pagination.total`. -Webhooks: `platform_user.created`, `platform_user.claimed`, `platform_user.x_connected`, `wallet.added`, `verification.expired`, and per instance `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (`PLATFORM_WEBHOOK_EVENTS`, `COMPETITION_WEBHOOK_EVENTS`). +**One person, one CabalSpy ID.** You may create an account for your user, but the person owns it: when they connect X or Telegram, or verify a wallet, that their own CabalSpy ID already holds, your link moves there (`platform_user.merged` with the new `csid_id`; your `external_id` stays), and once they sign in themselves they manage profile, X and Telegram (`platform_user.self_managed`, `self_managed: True`). Wallets you report stay yours: other platforms do not see them. + +Webhooks: `platform_user.created`, `platform_user.merged`, `platform_user.self_managed`, `platform_user.x_connected`, `platform_user.telegram_linked`, `wallet.added`, `verification.expired`, and per instance `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (`PLATFORM_WEBHOOK_EVENTS`, `COMPETITION_WEBHOOK_EVENTS`). ## Callouts (on request) @@ -667,7 +669,7 @@ The server sends a heartbeat every 30 seconds. The client reconnects with expone ## Webhooks -Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) spec (`webhook-id`, `webhook-timestamp`, `webhook-signature`, secret `whsec_...`) and are retried for about 2 days. Events: `wallet.verified`, `wallet.removed`, `profile.updated`, `kol.granted`, `consent.revoked`, `thesis.created`, `thesis.reply`, `thesis.reaction` — only for users within the plan's limit. White-label adds `platform_user.created`, `platform_user.claimed`, `platform_user.x_connected`, `wallet.added`, `verification.expired` and the instance-level `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (these carry `competition_id` instead of `sub`). Callouts add `callout.created`, `callout.milestone`, `callout.scored`, `callout.final` (`data.callout`; `CALLOUT_WEBHOOK_EVENTS`). Copy trading adds `copy_trade.instruction` (one per user and copied trade; `data` is the instruction plus `external_id`; `COPY_TRADING_WEBHOOK_EVENTS`). The Trade Feed adds `trade_feed.trade` and `trade_feed.thesis` (one per trade or thesis, not per user; `data` is the feed item plus `recipients` and `recipients_external`; `TradeFeedTradeEvent` / `TradeFeedThesisEvent`; `TRADE_FEED_WEBHOOK_EVENTS`). +Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) spec (`webhook-id`, `webhook-timestamp`, `webhook-signature`, secret `whsec_...`) and are retried for about 2 days. Events: `wallet.verified`, `wallet.removed`, `profile.updated`, `kol.granted`, `consent.revoked`, `thesis.created`, `thesis.reply`, `thesis.reaction` — only for users within the plan's limit. White-label adds `platform_user.created`, `platform_user.merged`, `platform_user.self_managed`, `platform_user.x_connected`, `platform_user.telegram_linked`, `wallet.added`, `verification.expired` and the instance-level `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (these carry `competition_id` instead of `sub`). Callouts add `callout.created`, `callout.milestone`, `callout.scored`, `callout.final` (`data.callout`; `CALLOUT_WEBHOOK_EVENTS`). Copy trading adds `copy_trade.instruction` (one per user and copied trade; `data` is the instruction plus `external_id`; `COPY_TRADING_WEBHOOK_EVENTS`). The Trade Feed adds `trade_feed.trade` and `trade_feed.thesis` (one per trade or thesis, not per user; `data` is the feed item plus `recipients` and `recipients_external`; `TradeFeedTradeEvent` / `TradeFeedThesisEvent`; `TRADE_FEED_WEBHOOK_EVENTS`). ```python from cabalspy_id import verify_webhook diff --git a/cabalspy_id/_client.py b/cabalspy_id/_client.py index d70ebd5..582e6a2 100644 --- a/cabalspy_id/_client.py +++ b/cabalspy_id/_client.py @@ -1206,11 +1206,11 @@ def platform_user_session(self, external_id: str | None = None, *, csid_id: str def platform_user_claim_link( self, external_id: str | None = None, *, return_url: str | None = None, csid_id: str | None = None ) -> Any: - """POST /v1/platform-users/claim-link — a 24-hour link that lets the person take the account - into their own CabalSpy ID. ``return_url`` must be on your verified domains or registered - origins. Off with ``white_label`` unless ``claim_links`` is on (``claim_disabled``). + """Deprecated: claim links are gone, the API answers 410 ``claim_removed``. - Returns :class:`~cabalspy_id.PlatformClaimLink`. + A CabalSpy ID is one account for every platform now: your link moves to the person's + own ID by itself when they connect X or Telegram or verify a wallet it holds (webhook + ``platform_user.merged``; your ``external_id`` stays). """ body = _who(external_id, csid_id) if return_url: diff --git a/cabalspy_id/_constants.py b/cabalspy_id/_constants.py index fc26623..7c27d24 100644 --- a/cabalspy_id/_constants.py +++ b/cabalspy_id/_constants.py @@ -4,7 +4,7 @@ from typing import Literal -SDK_VERSION = "0.9.1" +SDK_VERSION = "0.10.0" USER_AGENT = f"cabalspy-id-python/{SDK_VERSION}" DEFAULT_BASE_URL = "https://api-id.cabalspy.xyz/v1" @@ -43,8 +43,11 @@ #: Webhook events about platform users (white-label). ``data.sub`` is the user's csid_id. PLATFORM_WEBHOOK_EVENTS: tuple[str, ...] = ( "platform_user.created", + "platform_user.merged", + "platform_user.self_managed", "platform_user.claimed", "platform_user.x_connected", + "platform_user.telegram_linked", "wallet.added", "verification.expired", ) diff --git a/cabalspy_id/_types.py b/cabalspy_id/_types.py index b2cd5fa..09bdcd7 100644 --- a/cabalspy_id/_types.py +++ b/cabalspy_id/_types.py @@ -858,10 +858,17 @@ class PlatformUser(TypedDict): csid_id: str external_id: str - #: True once the person took the account into their own CabalSpy ID (claim link). + #: The person signs in to their CabalSpy ID themselves and manages profile, X and + #: Telegram; you can still report wallets for them. + self_managed: bool + self_managed_at: str | None + #: Deprecated: old names of ``self_managed`` / ``self_managed_at``. claimed: bool claimed_at: str | None + #: Created by a platform and not taken over by the person yet. managed: bool + #: The platform account this link moved from when the person proved their own CabalSpy ID. + merged_from: str | None display_name: str | None avatar_url: str | None #: Beyond the plan's user limit: no data until the platform upgrades. diff --git a/pyproject.toml b/pyproject.toml index 3096851..5f1d89c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "cabalspy-id" -version = "0.9.1" +version = "0.10.0" 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_trade_feed.py b/tests/test_trade_feed.py index 9fa53ef..45a25cb 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.1" + assert cabalspy_id.__version__ == "0.10.0" 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