langchain-xdataapi 0.1.0__tar.gz → 0.1.3__tar.gz

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langchain-xdataapi
-Version: 0.1.0
+Version: 0.1.3
 Summary: LangChain tools for xdataapi.io: read-only public X (Twitter) profiles, tweets, threads, followers and search.
 Project-URL: Homepage, https://xdataapi.io
 Project-URL: Documentation, https://xdataapi.io/docs
@@ -68,8 +68,8 @@ print(search.invoke({"q": "from:vercel since:2026-09-01", "count": 10}))
 | Tool | Reads | Credits |
 |---|---|---|
 | `x_search_tweets` | Search with the x.com operators | 1 per result |
-| `x_get_user` | One profile | 1 |
-| `x_get_users` | Up to 100 profiles in one call | 1 per profile |
+| `x_get_user` | One profile, by `handle` or by numeric user `id` | 1 |
+| `x_get_users` | Up to 100 profiles in one call, by `handles` or by `ids` | 1 per profile |
 | `x_get_user_tweets` | Latest posts of a user | 1 per post |
 | `x_get_tweet` | One post | 1 |
 | `x_get_tweets` | Up to 100 posts in one call | 1 per post |

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.3}/README.md

@@ -46,8 +46,8 @@ print(search.invoke({"q": "from:vercel since:2026-09-01", "count": 10}))
 | Tool | Reads | Credits |
 |---|---|---|
 | `x_search_tweets` | Search with the x.com operators | 1 per result |
-| `x_get_user` | One profile | 1 |
-| `x_get_users` | Up to 100 profiles in one call | 1 per profile |
+| `x_get_user` | One profile, by `handle` or by numeric user `id` | 1 |
+| `x_get_users` | Up to 100 profiles in one call, by `handles` or by `ids` | 1 per profile |
 | `x_get_user_tweets` | Latest posts of a user | 1 per post |
 | `x_get_tweet` | One post | 1 |
 | `x_get_tweets` | Up to 100 posts in one call | 1 per post |

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langchain-xdataapi"
-version = "0.1.0"
+version = "0.1.3"
 description = "LangChain tools for xdataapi.io: read-only public X (Twitter) profiles, tweets, threads, followers and search."
 readme = "README.md"
 license = "MIT"

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.3}/src/langchain_xdataapi/tools.py

@@ -7,19 +7,34 @@ model that plans a multi-step read knows what the plan costs before it runs it.
 from __future__ import annotations
 
 import json
+import re
 from typing import Any, Literal, Sequence
+from urllib.parse import quote
 
 from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
 from langchain_core.tools import BaseTool
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .client import XdataapiClient
 
 
+_USER_ID = re.compile(r"^\d{1,19}$")
+
+
 def _handle(value: str) -> str:
     return value.strip().lstrip("@")
 
 
+def _seg(value: Any) -> str:
+    """One URL path segment. The value comes from a model, so nothing in it may
+    act as a path: a slash is sent percent-encoded, and a segment that is empty
+    or only dots ("..") is refused, because encoding does not change a dot."""
+    s = str(value).strip()
+    if s.strip(".") == "":
+        raise ValueError("a handle, user or id must not be empty or only dots")
+    return quote(s, safe="")
+
+
 def _dump(payload: dict[str, Any]) -> str:
     return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
 
@@ -47,39 +62,80 @@ class _Base(BaseTool):
 # --- users ---------------------------------------------------------------
 
 
+def _one_of(first: Any, second: Any, names: str) -> None:
+    """A user is named by handle or by id, never by both and never by neither."""
+    if (first is None) == (second is None):
+        raise ValueError(f"give {names}, one of the two")
+
+
 class _UserArgs(BaseModel):
-    handle: str = Field(description="X handle, with or without the leading @.")
+    handle: str | None = Field(default=None, description="X handle, with or without the leading @.")
+    id: str | None = Field(
+        default=None,
+        pattern=r"^\d{1,19}$",
+        description="Numeric user id. It stays the same when the user changes the handle.",
+    )
     fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
 
+    @model_validator(mode="after")
+    def _handle_or_id(self) -> "_UserArgs":
+        _one_of(self.handle, self.id, "handle or id")
+        return self
+
 
 class GetUser(_Base):
     name: str = "x_get_user"
     description: str = (
-        "Public profile of one X (Twitter) user by handle: bio, counts, verified state, "
-        "created date. Costs 1 credit."
+        "Public profile of one X (Twitter) user, by handle or by numeric user id (give one of "
+        "the two): bio, counts, verified state, created date. The id stays the same when the "
+        "user changes the handle. Costs 1 credit."
     )
     args_schema: type[BaseModel] = _UserArgs
 
-    def _call(self, handle: str, fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/users/{_handle(handle)}", {"fresh": fresh}
+    def _call(
+        self, handle: str | None = None, id: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        _one_of(handle, id, "handle or id")
+        if id is not None:
+            if not _USER_ID.match(id.strip()):
+                raise ValueError("id must be a numeric user id")
+            return f"/v1/users/id/{_seg(id)}", {"fresh": fresh}
+        return f"/v1/users/{_seg(_handle(handle or ''))}", {"fresh": fresh}
 
 
 class _UsersArgs(BaseModel):
-    handles: Sequence[str] = Field(description="Up to 100 handles in one call.")
+    handles: Sequence[str] | None = Field(default=None, description="Up to 100 handles in one call.")
+    ids: Sequence[str] | None = Field(
+        default=None, description="Up to 100 numeric user ids in one call, in place of handles."
+    )
     fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
 
+    @model_validator(mode="after")
+    def _handles_or_ids(self) -> "_UsersArgs":
+        _one_of(self.handles, self.ids, "handles or ids")
+        return self
+
 
 class GetUsers(_Base):
     name: str = "x_get_users"
     description: str = (
-        "Profiles of up to 100 X users in ONE call. Prefer this over repeated single reads: "
+        "Profiles of up to 100 X users in ONE call, by handle (handles) or by numeric user id "
+        "(ids); give one of the two lists. Prefer this over repeated single reads: "
         "it is one request and one rate-limit slot. Costs 1 credit per profile found; "
-        "handles that do not exist are listed in errors and cost nothing."
+        "inputs that do not exist are listed in errors and cost nothing."
     )
     args_schema: type[BaseModel] = _UsersArgs
 
-    def _call(self, handles: Sequence[str], fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
-        return "/v1/users/batch", {"handles": ",".join(_handle(h) for h in handles), "fresh": fresh}
+    def _call(
+        self,
+        handles: Sequence[str] | None = None,
+        ids: Sequence[str] | None = None,
+        fresh: bool | None = None,
+    ) -> tuple[str, dict[str, Any] | None]:
+        _one_of(handles, ids, "handles or ids")
+        if ids is not None:
+            return "/v1/users/batch", {"ids": ",".join(i.strip() for i in ids), "fresh": fresh}
+        return "/v1/users/batch", {"handles": ",".join(_handle(h) for h in handles or []), "fresh": fresh}
 
 
 class _PageArgs(BaseModel):
@@ -99,7 +155,7 @@ class GetUserTweets(_Base):
     def _call(
         self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/users/{_handle(user)}/tweets", {
+        return f"/v1/users/{_seg(_handle(user))}/tweets", {
             "count": self.client.cap(count),
             "cursor": cursor,
             "fresh": fresh,
@@ -117,7 +173,7 @@ class GetFollowers(_Base):
     def _call(
         self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/users/{_handle(user)}/followers", {
+        return f"/v1/users/{_seg(_handle(user))}/followers", {
             "count": self.client.cap(count),
             "cursor": cursor,
             "fresh": fresh,
@@ -135,7 +191,7 @@ class GetFollowerIds(_Base):
     def _call(
         self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/users/{_handle(user)}/followers/ids", {
+        return f"/v1/users/{_seg(_handle(user))}/followers/ids", {
             "count": self.client.cap(count),
             "cursor": cursor,
             "fresh": fresh,
@@ -153,7 +209,7 @@ class GetFollowing(_Base):
     def _call(
         self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/users/{_handle(user)}/following", {
+        return f"/v1/users/{_seg(_handle(user))}/following", {
             "count": self.client.cap(count),
             "cursor": cursor,
             "fresh": fresh,
@@ -220,7 +276,7 @@ class GetTweet(_Base):
     args_schema: type[BaseModel] = _TweetArgs
 
     def _call(self, id: str, fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/tweets/{id}", {"fresh": fresh}
+        return f"/v1/tweets/{_seg(id)}", {"fresh": fresh}
 
 
 class _TweetsArgs(BaseModel):
@@ -257,7 +313,7 @@ class GetThread(_Base):
     def _call(
         self, id: str, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/tweets/{id}/thread", {"cursor": cursor, "fresh": fresh}
+        return f"/v1/tweets/{_seg(id)}/thread", {"cursor": cursor, "fresh": fresh}
 
 
 class GetReplies(_Base):
@@ -268,7 +324,7 @@ class GetReplies(_Base):
     def _call(
         self, id: str, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/tweets/{id}/replies", {"cursor": cursor, "fresh": fresh}
+        return f"/v1/tweets/{_seg(id)}/replies", {"cursor": cursor, "fresh": fresh}
 
 
 class _CountedTweetArgs(BaseModel):
@@ -286,7 +342,7 @@ class GetQuotes(_Base):
     def _call(
         self, id: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/tweets/{id}/quotes", {
+        return f"/v1/tweets/{_seg(id)}/quotes", {
             "count": self.client.cap(count),
             "cursor": cursor,
             "fresh": fresh,
@@ -304,7 +360,7 @@ class GetRetweeters(_Base):
     def _call(
         self, id: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
     ) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/tweets/{id}/retweeters", {
+        return f"/v1/tweets/{_seg(id)}/retweeters", {
             "count": self.client.cap(count),
             "cursor": cursor,
             "fresh": fresh,

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.3}/tests/test_tools.py

@@ -8,6 +8,7 @@ from langchain_xdataapi import (
     GetBalance,
     GetTweets,
     GetUser,
+    GetUsers,
     SearchTweets,
     XdataapiAuthError,
     XdataapiClient,
@@ -32,6 +33,65 @@ def test_get_user_strips_the_at_sign():
     assert json.loads(out)["credits_charged"] == 1
 
 
+@respx.mock
+def test_get_user_by_id_reads_the_id_route():
+    route = respx.get(f"{BASE}/v1/users/id/783214").mock(
+        return_value=httpx.Response(200, json={"data": {"id": "783214", "handle": "X"}, "credits_charged": 1})
+    )
+    out = GetUser(client=client()).invoke({"id": "783214"})
+    assert route.called
+    assert json.loads(out)["data"]["handle"] == "X"
+
+
+def test_get_user_wants_a_handle_or_an_id_and_not_both():
+    tool = GetUser(client=client())
+    with pytest.raises(Exception, match="handle or id"):
+        tool.invoke({})
+    with pytest.raises(Exception, match="handle or id"):
+        tool.invoke({"handle": "x", "id": "783214"})
+    with pytest.raises(Exception):
+        tool.invoke({"id": "not-a-number"})
+
+
+@respx.mock
+def test_a_model_argument_cannot_leave_its_path_segment():
+    from langchain_xdataapi import GetTweet, GetUserTweets
+
+    route = respx.route(method="GET", host="api.xdataapi.io").mock(return_value=httpx.Response(404, json={"error": {"code": "not_found"}}))
+    GetUser(client=client()).invoke({"handle": "../me"})
+    assert route.calls.last.request.url.raw_path.startswith(b"/v1/users/..%2Fme")
+    GetUserTweets(client=client()).invoke({"user": "x/../../me"})
+    assert route.calls.last.request.url.raw_path.startswith(b"/v1/users/x%2F..%2F..%2Fme/tweets")
+    GetTweet(client=client()).invoke({"id": "20/../../me"})
+    assert route.calls.last.request.url.raw_path.startswith(b"/v1/tweets/20%2F..%2F..%2Fme")
+    # Encoding does not change a dot, so a segment of only dots is refused.
+    before = route.call_count
+    for bad in ("..", ".", " "):
+        with pytest.raises(ValueError, match="only dots"):
+            GetUserTweets(client=client()).invoke({"user": bad})
+        with pytest.raises(ValueError, match="only dots"):
+            GetTweet(client=client()).invoke({"id": bad})
+    assert route.call_count == before
+    # The id route takes digits only, also when the tool is called without its schema.
+    with pytest.raises(ValueError, match="numeric user id"):
+        GetUser(client=client())._call(id="1/../../me")
+
+
+@respx.mock
+def test_users_batch_by_ids_sends_ids_and_no_handles():
+    route = respx.get(f"{BASE}/v1/users/batch").mock(return_value=httpx.Response(200, json={"data": []}))
+    GetUsers(client=client()).invoke({"ids": ["783214", "13334762"]})
+    params = route.calls.last.request.url.params
+    assert params["ids"] == "783214,13334762"
+    assert "handles" not in params
+    GetUsers(client=client()).invoke({"handles": ["@x", "github"]})
+    params = route.calls.last.request.url.params
+    assert params["handles"] == "x,github"
+    assert "ids" not in params
+    with pytest.raises(Exception, match="handles or ids"):
+        GetUsers(client=client()).invoke({"handles": ["x"], "ids": ["1"]})
+
+
 @respx.mock
 def test_search_passes_the_operators_through_untouched():
     route = respx.get(f"{BASE}/v1/tweets/search").mock(