semble-api 0.0.1__py3-none-any.whl

semble/resources/feeds.py

@@ -0,0 +1,121 @@
+"""network.cosmik.feed.* — global and following activity feeds."""
+
+from semble._utils import drop_none
+from semble.resources._base import AsyncResource, SyncResource
+from semble.types import Activity, Page, SortOrder, URLType
+
+
+class Feeds(SyncResource):
+    def get_global(
+        self,
+        *,
+        url_type: URLType | None = None,
+        source: str | None = None,
+        activity_types: list[str] | None = None,
+        include_known_bots: bool | None = None,
+        before_activity_id: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[Activity]:
+        params = drop_none(
+            urlType=url_type,
+            source=source,
+            activityTypes=activity_types,
+            includeKnownBots=include_known_bots,
+            beforeActivityId=before_activity_id,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return self._client.get(
+            "network.cosmik.feed.getGlobal", params, cast_to=Page[Activity]
+        )
+
+    def get_following(
+        self,
+        *,
+        url_type: URLType | None = None,
+        source: str | None = None,
+        activity_types: list[str] | None = None,
+        include_known_bots: bool | None = None,
+        before_activity_id: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[Activity]:
+        params = drop_none(
+            urlType=url_type,
+            source=source,
+            activityTypes=activity_types,
+            includeKnownBots=include_known_bots,
+            beforeActivityId=before_activity_id,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return self._client.get(
+            "network.cosmik.feed.getFollowing", params, cast_to=Page[Activity]
+        )
+
+
+class AsyncFeeds(AsyncResource):
+    async def get_global(
+        self,
+        *,
+        url_type: URLType | None = None,
+        source: str | None = None,
+        activity_types: list[str] | None = None,
+        include_known_bots: bool | None = None,
+        before_activity_id: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[Activity]:
+        params = drop_none(
+            urlType=url_type,
+            source=source,
+            activityTypes=activity_types,
+            includeKnownBots=include_known_bots,
+            beforeActivityId=before_activity_id,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return await self._client.get(
+            "network.cosmik.feed.getGlobal", params, cast_to=Page[Activity]
+        )
+
+    async def get_following(
+        self,
+        *,
+        url_type: URLType | None = None,
+        source: str | None = None,
+        activity_types: list[str] | None = None,
+        include_known_bots: bool | None = None,
+        before_activity_id: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[Activity]:
+        params = drop_none(
+            urlType=url_type,
+            source=source,
+            activityTypes=activity_types,
+            includeKnownBots=include_known_bots,
+            beforeActivityId=before_activity_id,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return await self._client.get(
+            "network.cosmik.feed.getFollowing", params, cast_to=Page[Activity]
+        )

semble/resources/graph.py

@@ -0,0 +1,155 @@
+"""network.cosmik.graph.* — following users and collections."""
+
+from semble._utils import drop_none
+from semble.resources._base import AsyncResource, SyncResource
+from semble.types import Collection, CountResponse, IDResponse, Page, TargetType, User
+
+
+class Graph(SyncResource):
+    def follow(self, target_id: str, target_type: TargetType) -> IDResponse:
+        return self._client.post(
+            "network.cosmik.graph.follow",
+            {"targetId": target_id, "targetType": target_type},
+            cast_to=IDResponse,
+        )
+
+    def unfollow(self, target_id: str, target_type: TargetType) -> IDResponse:
+        return self._client.post(
+            "network.cosmik.graph.unfollow",
+            {"targetId": target_id, "targetType": target_type},
+            cast_to=IDResponse,
+        )
+
+    def get_following(
+        self,
+        identifier: str,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[User]:
+        params = drop_none(identifier=identifier, page=page, limit=limit)
+        return self._client.get(
+            "network.cosmik.graph.getFollowing", params, cast_to=Page[User]
+        )
+
+    def get_followers(
+        self,
+        identifier: str,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[User]:
+        params = drop_none(identifier=identifier, page=page, limit=limit)
+        return self._client.get(
+            "network.cosmik.graph.getFollowers", params, cast_to=Page[User]
+        )
+
+    def get_following_collections(
+        self,
+        identifier: str,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[Collection]:
+        params = drop_none(identifier=identifier, page=page, limit=limit)
+        return self._client.get(
+            "network.cosmik.graph.getFollowingCollections",
+            params,
+            cast_to=Page[Collection],
+        )
+
+    def get_following_count(self, identifier: str) -> CountResponse:
+        return self._client.get(
+            "network.cosmik.graph.getFollowingCount",
+            {"identifier": identifier},
+            cast_to=CountResponse,
+        )
+
+    def get_followers_count(self, identifier: str) -> CountResponse:
+        return self._client.get(
+            "network.cosmik.graph.getFollowersCount",
+            {"identifier": identifier},
+            cast_to=CountResponse,
+        )
+
+    def get_following_collections_count(self, identifier: str) -> CountResponse:
+        return self._client.get(
+            "network.cosmik.graph.getFollowingCollectionsCount",
+            {"identifier": identifier},
+            cast_to=CountResponse,
+        )
+
+
+class AsyncGraph(AsyncResource):
+    async def follow(self, target_id: str, target_type: TargetType) -> IDResponse:
+        return await self._client.post(
+            "network.cosmik.graph.follow",
+            {"targetId": target_id, "targetType": target_type},
+            cast_to=IDResponse,
+        )
+
+    async def unfollow(self, target_id: str, target_type: TargetType) -> IDResponse:
+        return await self._client.post(
+            "network.cosmik.graph.unfollow",
+            {"targetId": target_id, "targetType": target_type},
+            cast_to=IDResponse,
+        )
+
+    async def get_following(
+        self,
+        identifier: str,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[User]:
+        params = drop_none(identifier=identifier, page=page, limit=limit)
+        return await self._client.get(
+            "network.cosmik.graph.getFollowing", params, cast_to=Page[User]
+        )
+
+    async def get_followers(
+        self,
+        identifier: str,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[User]:
+        params = drop_none(identifier=identifier, page=page, limit=limit)
+        return await self._client.get(
+            "network.cosmik.graph.getFollowers", params, cast_to=Page[User]
+        )
+
+    async def get_following_collections(
+        self,
+        identifier: str,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[Collection]:
+        params = drop_none(identifier=identifier, page=page, limit=limit)
+        return await self._client.get(
+            "network.cosmik.graph.getFollowingCollections",
+            params,
+            cast_to=Page[Collection],
+        )
+
+    async def get_following_count(self, identifier: str) -> CountResponse:
+        return await self._client.get(
+            "network.cosmik.graph.getFollowingCount",
+            {"identifier": identifier},
+            cast_to=CountResponse,
+        )
+
+    async def get_followers_count(self, identifier: str) -> CountResponse:
+        return await self._client.get(
+            "network.cosmik.graph.getFollowersCount",
+            {"identifier": identifier},
+            cast_to=CountResponse,
+        )
+
+    async def get_following_collections_count(self, identifier: str) -> CountResponse:
+        return await self._client.get(
+            "network.cosmik.graph.getFollowingCollectionsCount",
+            {"identifier": identifier},
+            cast_to=CountResponse,
+        )

semble/resources/notifications.py

@@ -0,0 +1,87 @@
+"""network.cosmik.notification.* — your notification inbox."""
+
+# Sequence (not list) in mark_read: the `list` methods shadow the builtin
+# inside these class bodies
+from collections.abc import Sequence
+
+from semble._utils import drop_none
+from semble.resources._base import AsyncResource, SyncResource
+from semble.types import CountResponse, IDResponse, Notification, Page, SortOrder
+
+
+class Notifications(SyncResource):
+    def list(
+        self,
+        *,
+        unread_only: bool | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[Notification]:
+        params = drop_none(
+            unreadOnly=unread_only,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return self._client.get(
+            "network.cosmik.notification.list", params, cast_to=Page[Notification]
+        )
+
+    def get_unread_count(self) -> CountResponse:
+        return self._client.get(
+            "network.cosmik.notification.getUnreadCount", cast_to=CountResponse
+        )
+
+    def mark_read(self, notification_ids: Sequence[str]) -> IDResponse:
+        return self._client.post(
+            "network.cosmik.notification.markRead",
+            {"notificationIds": [*notification_ids]},
+            cast_to=IDResponse,
+        )
+
+    def mark_all_read(self) -> IDResponse:
+        return self._client.post(
+            "network.cosmik.notification.markAllRead", {}, cast_to=IDResponse
+        )
+
+
+class AsyncNotifications(AsyncResource):
+    async def list(
+        self,
+        *,
+        unread_only: bool | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[Notification]:
+        params = drop_none(
+            unreadOnly=unread_only,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return await self._client.get(
+            "network.cosmik.notification.list", params, cast_to=Page[Notification]
+        )
+
+    async def get_unread_count(self) -> CountResponse:
+        return await self._client.get(
+            "network.cosmik.notification.getUnreadCount", cast_to=CountResponse
+        )
+
+    async def mark_read(self, notification_ids: Sequence[str]) -> IDResponse:
+        return await self._client.post(
+            "network.cosmik.notification.markRead",
+            {"notificationIds": [*notification_ids]},
+            cast_to=IDResponse,
+        )
+
+    async def mark_all_read(self) -> IDResponse:
+        return await self._client.post(
+            "network.cosmik.notification.markAllRead", {}, cast_to=IDResponse
+        )

semble/resources/search.py

@@ -0,0 +1,135 @@
+"""network.cosmik.search.* — semantic and similarity search."""
+
+from semble._utils import drop_none
+from semble.resources._base import AsyncResource, SyncResource
+from semble.types import Page, SortOrder, URLType, URLView, User
+
+
+class Search(SyncResource):
+    def semantic(
+        self,
+        query: str,
+        *,
+        threshold: float | None = None,
+        url_type: URLType | None = None,
+        identifier: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[URLView]:
+        params = drop_none(
+            query=query,
+            threshold=threshold,
+            urlType=url_type,
+            identifier=identifier,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return self._client.get(
+            "network.cosmik.search.semantic", params, cast_to=Page[URLView]
+        )
+
+    def get_similar_urls(
+        self,
+        url: str,
+        *,
+        threshold: float | None = None,
+        url_type: URLType | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[URLView]:
+        params = drop_none(
+            url=url,
+            threshold=threshold,
+            urlType=url_type,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return self._client.get(
+            "network.cosmik.search.getSimilarUrls", params, cast_to=Page[URLView]
+        )
+
+    def get_accounts(
+        self,
+        *,
+        term: str | None = None,
+        q: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Page[User]:
+        params = drop_none(term=term, q=q, limit=limit, cursor=cursor)
+        return self._client.get(
+            "network.cosmik.search.getAccounts", params, cast_to=Page[User]
+        )
+
+
+class AsyncSearch(AsyncResource):
+    async def semantic(
+        self,
+        query: str,
+        *,
+        threshold: float | None = None,
+        url_type: URLType | None = None,
+        identifier: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[URLView]:
+        params = drop_none(
+            query=query,
+            threshold=threshold,
+            urlType=url_type,
+            identifier=identifier,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return await self._client.get(
+            "network.cosmik.search.semantic", params, cast_to=Page[URLView]
+        )
+
+    async def get_similar_urls(
+        self,
+        url: str,
+        *,
+        threshold: float | None = None,
+        url_type: URLType | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        sort_order: SortOrder | None = None,
+    ) -> Page[URLView]:
+        params = drop_none(
+            url=url,
+            threshold=threshold,
+            urlType=url_type,
+            page=page,
+            limit=limit,
+            sortBy=sort_by,
+            sortOrder=sort_order,
+        )
+        return await self._client.get(
+            "network.cosmik.search.getSimilarUrls", params, cast_to=Page[URLView]
+        )
+
+    async def get_accounts(
+        self,
+        *,
+        term: str | None = None,
+        q: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Page[User]:
+        params = drop_none(term=term, q=q, limit=limit, cursor=cursor)
+        return await self._client.get(
+            "network.cosmik.search.getAccounts", params, cast_to=Page[User]
+        )

semble/settings.py

@@ -0,0 +1,26 @@
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+DEFAULT_BASE_URL = "https://api.semble.so/xrpc"
+
+
+class SembleSettings(BaseSettings):
+    """client configuration from the environment and a local `.env` file.
+
+    every field reads `SEMBLE_`-prefixed sources: `SEMBLE_API_KEY`,
+    `SEMBLE_BASE_URL`, `SEMBLE_TIMEOUT`. explicit client kwargs win over
+    the environment, which wins over `.env`.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="SEMBLE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    api_key: SecretStr | None = Field(
+        default=None, description="API key for authentication"
+    )
+    base_url: str = Field(default=DEFAULT_BASE_URL, description="Base URL for the API")
+    timeout: float = Field(default=30.0, description="Timeout for API requests")