pyfb-kit 0.1.0__tar.gz

pyfb_kit-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.3
+Name: pyfb-kit
+Version: 0.1.0
+Summary: A wrapper for the facebook-sdk which provides an ergonomic way to manage common interactions using the facebook-sdk
+Author: NovaH00
+Author-email: NovaH00 <trantay2006super@gmail.com>
+Requires-Dist: facebook-sdk>=3.1.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# PyFB-kit
+
+A Python wrapper for the Facebook Graph API that provides convenient abstractions for managing and moderating Facebook pages and comments.
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install pyfb-kit
+```
+
+Or using uv (recommended):
+
+```bash
+uv add pyfb-kit
+```
+
+## Prerequisites
+
+Before using this library, you need to obtain a long-lived user access token with the appropriate permissions:
+
+1. Create a Facebook developer application at [developers.facebook.com/apps](https://developers.facebook.com/apps/)
+2. Add the following permissions to your application:
+   - `pages_manage_engagement`
+   - `pages_read_engagement`
+   - `pages_read_user_content`
+   - `pages_show_list`
+3. Generate a short-lived user access token via the Graph API Explorer with the above permissions
+4. Exchange it for a long-lived token (valid for up to 60 days) using the following request:
+
+```python
+import requests
+
+params = {
+    "grant_type": "fb_exchange_token",
+    "client_id": "<YOUR_APP_ID>",
+    "fb_exchange_token": "<SHORT_LIVED_TOKEN>",
+    "client_secret": "<YOUR_APP_SECRET>",
+}
+
+response = requests.get("https://graph.facebook.com/v24.0/oauth/access_token", params=params)
+long_lived_token = response.json()["access_token"]
+```
+
+## Usage
+
+### Basic Setup
+
+```python
+from pyfb_kit import Client, Account, Post, Comment
+
+# Initialize the client with your user access token
+client = Client(user_access_token="your_long_lived_token_here")
+```
+
+### Managing Accounts
+
+Retrieve all Facebook pages associated with your account:
+
+```python
+# Get all accessible accounts/pages
+accounts = client.get_accounts()
+
+# Print account information
+for account in accounts:
+    print(f"Page Name: {account.name}, ID: {account.id}")
+```
+
+### Working with Posts
+
+Fetch posts from a specific page:
+
+```python
+# Get posts from a specific account
+first_account = accounts[0]
+posts = client.get_posts(first_account)
+
+# Print post information
+for post in posts:
+    print(f"Post ID: {post.id}, Message: {post.message[:50]}...")
+```
+
+### Comment Management
+
+Interact with comments on posts:
+
+```python
+# Get comments from a specific post
+first_post = posts[0]
+comments = client.get_comments(first_account, first_post)
+
+# Print comment information
+for comment in comments:
+    print(f"Comment by {comment.from_info.name}: {comment.message[:50]}...")
+
+# Post a new comment on a post
+client.put_comment(first_account, first_post, "This is a new comment!")
+
+# Reply to an existing comment
+first_comment = comments[0]
+client.reply_comment(first_account, first_comment, "Thanks for your comment!")
+```
+
+### Advanced Comment Operations
+
+Retrieve replies to a specific comment:
+
+```python
+# Get all replies to a specific comment
+replies = client.get_comment_replies(first_account, first_comment)
+
+for reply in replies:
+    print(f"Reply by {reply.from_info.name}: {reply.message[:50]}...")
+```

pyfb_kit-0.1.0/README.md

@@ -0,0 +1,115 @@
+# PyFB-kit
+
+A Python wrapper for the Facebook Graph API that provides convenient abstractions for managing and moderating Facebook pages and comments.
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install pyfb-kit
+```
+
+Or using uv (recommended):
+
+```bash
+uv add pyfb-kit
+```
+
+## Prerequisites
+
+Before using this library, you need to obtain a long-lived user access token with the appropriate permissions:
+
+1. Create a Facebook developer application at [developers.facebook.com/apps](https://developers.facebook.com/apps/)
+2. Add the following permissions to your application:
+   - `pages_manage_engagement`
+   - `pages_read_engagement`
+   - `pages_read_user_content`
+   - `pages_show_list`
+3. Generate a short-lived user access token via the Graph API Explorer with the above permissions
+4. Exchange it for a long-lived token (valid for up to 60 days) using the following request:
+
+```python
+import requests
+
+params = {
+    "grant_type": "fb_exchange_token",
+    "client_id": "<YOUR_APP_ID>",
+    "fb_exchange_token": "<SHORT_LIVED_TOKEN>",
+    "client_secret": "<YOUR_APP_SECRET>",
+}
+
+response = requests.get("https://graph.facebook.com/v24.0/oauth/access_token", params=params)
+long_lived_token = response.json()["access_token"]
+```
+
+## Usage
+
+### Basic Setup
+
+```python
+from pyfb_kit import Client, Account, Post, Comment
+
+# Initialize the client with your user access token
+client = Client(user_access_token="your_long_lived_token_here")
+```
+
+### Managing Accounts
+
+Retrieve all Facebook pages associated with your account:
+
+```python
+# Get all accessible accounts/pages
+accounts = client.get_accounts()
+
+# Print account information
+for account in accounts:
+    print(f"Page Name: {account.name}, ID: {account.id}")
+```
+
+### Working with Posts
+
+Fetch posts from a specific page:
+
+```python
+# Get posts from a specific account
+first_account = accounts[0]
+posts = client.get_posts(first_account)
+
+# Print post information
+for post in posts:
+    print(f"Post ID: {post.id}, Message: {post.message[:50]}...")
+```
+
+### Comment Management
+
+Interact with comments on posts:
+
+```python
+# Get comments from a specific post
+first_post = posts[0]
+comments = client.get_comments(first_account, first_post)
+
+# Print comment information
+for comment in comments:
+    print(f"Comment by {comment.from_info.name}: {comment.message[:50]}...")
+
+# Post a new comment on a post
+client.put_comment(first_account, first_post, "This is a new comment!")
+
+# Reply to an existing comment
+first_comment = comments[0]
+client.reply_comment(first_account, first_comment, "Thanks for your comment!")
+```
+
+### Advanced Comment Operations
+
+Retrieve replies to a specific comment:
+
+```python
+# Get all replies to a specific comment
+replies = client.get_comment_replies(first_account, first_comment)
+
+for reply in replies:
+    print(f"Reply by {reply.from_info.name}: {reply.message[:50]}...")
+```

pyfb_kit-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "pyfb-kit"
+version = "0.1.0"
+description = "A wrapper for the facebook-sdk which provides an ergonomic way to manage common interactions using the facebook-sdk"
+readme = "README.md"
+authors = [
+    { name = "NovaH00", email = "trantay2006super@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "facebook-sdk>=3.1.0",
+    "pydantic>=2.12.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"

pyfb_kit-0.1.0/src/pyfb_kit/__init__.py

@@ -0,0 +1,11 @@
+from .client import Client, AsyncClient
+from .models import Account, Post, Comment 
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "Account",
+    "Post",
+    "Comment"
+]
+

pyfb_kit-0.1.0/src/pyfb_kit/client/__init__.py

@@ -0,0 +1,7 @@
+from .sync import Client
+from .asycn import AsyncClient
+
+__all__ = [
+    "Client",
+    "AsyncClient"
+]

pyfb_kit-0.1.0/src/pyfb_kit/client/asycn.py

@@ -0,0 +1,3 @@
+
+class AsyncClient:
+    pass

pyfb_kit-0.1.0/src/pyfb_kit/client/sync.py

@@ -0,0 +1,228 @@
+from typing import Any, cast
+from collections.abc import Iterator
+
+import facebook
+from facebook import GraphAPI
+
+from ..models import (
+    Account,
+    Post,
+    Comment
+)
+
+from ..types.graph_api import (
+    Response,
+    Data,
+)
+
+class Client:
+    """
+    Synchronous client for interacting with the Facebook Graph API.
+
+    Provides methods to manage Facebook pages, posts, and comments.
+    """
+
+    def __init__(self, user_access_token: str):
+        """
+        Initialize the client with a user access token.
+
+        Args:
+            user_access_token: A valid Facebook user access token with appropriate permissions
+        """
+        self._user_access_token: str = user_access_token
+
+    def _get_data(
+        self,
+        graph: facebook.GraphAPI,
+        id: str,
+        connection_name: str,
+        **kwargs: Any
+    ) -> Data:
+        """
+        Internal method to retrieve paginated data from the Facebook Graph API.
+
+        This method handles pagination automatically by following the cursors in the response
+        and concatenating all pages to produce a single data response.
+
+        Args:
+            graph: An initialized GraphAPI instance
+            id: The ID of the object to query (e.g., user ID, page ID, post ID)
+            connection_name: The connection name to query (e.g., "posts", "comments", "accounts")
+            **kwargs: Additional parameters to pass to the Graph API call
+
+        Returns:
+            A list of raw Facebook Graph API objects extracted from the 'data' field
+        """
+        all_data: Data = []
+        
+        while True:
+            # Request the current page
+            res = graph.get_connections( # pyright: ignore
+                id,
+                connection_name,
+                **kwargs
+            ) 
+            res = cast(Response, res)
+
+            current_data: Data = res.get("data") # pyright: ignore
+            
+            if current_data:
+                all_data.extend(current_data)
+
+            # Check for the next page cursor ('after')
+            # Facebook Structure: {'paging': {'cursors': {'after': '...'}}}
+            try:
+                paging = res.get("paging", None)
+                if not paging: break
+                    
+                cursors = paging.get("cursors")
+                if not cursors: break
+                    
+                after = cursors.get("after")
+                if not after: break
+                
+                # Update kwargs with the 'after' cursor for the next iteration
+                kwargs["after"] = after
+                
+            except (AttributeError, TypeError):
+                # If the response structure is unexpected, stop pagination
+                break
+                
+        return all_data 
+
+    def get_accounts(self) -> list[Account]:
+        """
+        Retrieve all Facebook accounts/pages associated with the authenticated user.
+
+        This method fetches all Facebook pages that the user has access to, along with
+        their access tokens and other metadata.
+
+        Returns:
+            A list of Account objects representing the Facebook pages accessible to the user
+        """
+        accounts: Data = self._get_data(
+            graph=GraphAPI(self._user_access_token),
+            id="me",
+            connection_name="accounts"
+        )
+
+        return [
+            Account.model_validate(acc)
+            for acc in accounts
+        ]
+    
+    def get_posts(self, account: Account) -> list[Post]:
+        """
+        Retrieve all posts from a specific Facebook page/account.
+
+        This method fetches all posts from the given Facebook page, including their
+        content, creation time, and attachments.
+
+        Args:
+            account: Account object containing the access token and ID for the Facebook page
+
+        Returns:
+            A list of Post objects representing the posts on the Facebook page
+        """
+        posts: Data = self._get_data(
+            graph=GraphAPI(account.access_token),
+            id=account.id,
+            connection_name="posts",
+            fields="id,message,created_time,attachments{media,type,subattachments}",
+        )
+
+        return [
+            Post.model_validate(p)
+            for p in posts
+        ]
+    
+    def get_comments(self, account: Account, post: Post) -> list[Comment]:
+        """
+        Retrieve all comments for a given post using the account's access token.
+
+        Args:
+            account: Account object containing the access token for the Facebook page
+            post: Post object containing the post information
+
+        Returns:
+            A list of Comment objects representing the comments on the post
+        """
+        comments: Data = self._get_data(
+            graph=GraphAPI(account.access_token),
+            id=post.id,
+            connection_name="comments",
+            fields="id,from,message,created_time,like_count,parent"
+        )
+
+        return [
+            Comment.model_validate(comment)
+            for comment in comments
+        ]
+
+    def put_comment(self, account: Account, post: Post, message: str) -> None:
+        """
+        Post a direct comment on a post using the account's access token.
+
+        Args:
+            account: Account object containing the access token for the Facebook page
+            post: Post object containing the post information
+            message: The message content for the comment
+
+        Returns:
+            None
+        """
+        graph = GraphAPI(account.access_token)
+
+        # Use the Facebook Graph API to post a comment on the specific post
+        _ = graph.put_object( # pyright: ignore
+            parent_object=post.id,
+            connection_name="comments",
+            message=message
+        )
+
+    def reply_comment(self, account: Account, comment: Comment, reply_message: str) -> None:
+        """
+        Reply to a specific comment using the account's access token.
+        This creates a reply to the given comment.
+
+        Args:
+            account: Account object containing the access token for the Facebook page
+            comment: Comment object representing the comment to reply to
+            reply_message: The message content for the reply
+
+        Returns:
+            None
+        """
+        graph = GraphAPI(account.access_token)
+
+        # Use the Facebook Graph API to reply to the specific comment
+        _ = graph.put_object( # pyright: ignore
+            parent_object=comment.id,
+            connection_name="comments",
+            message=reply_message
+        )
+
+    def get_comment_replies(self, account: Account, comment: Comment) -> list[Comment]:
+        """
+        Retrieve all replies to a specific comment using the account's access token.
+
+        Args:
+            account: Account object containing the access token for the Facebook page
+            comment: Comment object representing the parent comment whose replies are to be retrieved
+
+        Returns:
+            A list of Comment objects representing the replies to the given comment
+        """
+        replies: Data = self._get_data(
+            graph=GraphAPI(account.access_token),
+            id=comment.id,
+            connection_name="comments",
+            fields="id,from,message,created_time,like_count,parent"
+        )
+
+        return [
+            Comment.model_validate(reply)
+            for reply in replies
+        ]
+
+    # TODO: Add hide/unhide comments methods

pyfb_kit-0.1.0/src/pyfb_kit/models/__init__.py

@@ -0,0 +1,10 @@
+from .accounts import Account 
+from .posts import Post 
+from .comments import Comment 
+
+__all__ = [
+    "Account",
+    "Post",
+    "Comment"
+]
+

pyfb_kit-0.1.0/src/pyfb_kit/models/accounts.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field
+
+class Account(BaseModel):
+    access_token: str = Field(description="The access token needed to do operation using this account")
+    id: str = Field(description="The ID of the account")
+    name: str = Field(description="The name of the account")
+    tasks: list[str] = Field(description="The roles of CURRENT USER for this account")
+
+

pyfb_kit-0.1.0/src/pyfb_kit/models/comments.py

@@ -0,0 +1,48 @@
+from typing import Any
+from datetime import datetime
+from pydantic import BaseModel, Field, model_validator
+
+
+class From(BaseModel):
+    id: str = Field(..., description="ID of the user who made the comment")
+    name: str = Field(..., description="Name of the user who made the comment")
+
+
+class Comment(BaseModel):
+    """
+    Normalized DTO for a Facebook comment.
+
+    IMPORTANT:
+    This model expects the raw input to include comment data from the
+    Facebook Graph API. When querying comments, you MUST request the following
+    fields for validation and normalization to work correctly:
+
+        ...get_connections(
+            post_id,
+            "comments",
+            fields="id,from,message,created_time,like_count,parent"
+        )
+
+    If required fields are missing from the response, validation will fail.
+    """
+    id: str = Field(..., description="Unique identifier of the Facebook comment")
+    message: str = Field(..., description="Text content of the comment")
+    created_time: datetime = Field(..., description="Timestamp when the comment was created (ISO-8601)")
+    from_info: From = Field(..., alias="from", description="Information about the user who made the comment")
+    like_count: int = Field(default=0, description="Number of likes on the comment")
+    parent_id: str | None = Field(None, description="ID of the parent comment if this is a reply, otherwise None")
+
+    @model_validator(mode="before")
+    @classmethod
+    def extract_facebook_payload(cls, raw: dict[str, Any]):
+        return {
+            "id": raw["id"],
+            "message": raw["message"],
+            "created_time": raw["created_time"],
+            "from": {
+                "id": raw["from"]["id"],
+                "name": raw["from"]["name"]
+            },
+            "like_count": raw.get("like_count", 0),
+            "parent_id": raw.get("parent", {}).get("id") if raw.get("parent") else None
+        }

pyfb_kit-0.1.0/src/pyfb_kit/models/posts.py

@@ -0,0 +1,66 @@
+from typing import Any
+from datetime import datetime
+from pydantic import BaseModel, Field, model_validator
+
+
+class Image(BaseModel):
+    src: str = Field(..., description="Direct URL to the image hosted by Facebook")
+    width: int = Field(..., description="Width of the image in pixels")
+    height: int = Field(..., description="Height of the image in pixels")
+
+
+class Attachments(BaseModel):
+    images: list[Image] | None = Field(None, description="List of images attached to the post, if any")
+    # TODO: Add other attachment types here (videos, links, etc.)
+
+class Post(BaseModel):
+    """
+    Normalized DTO for a Facebook Page post.
+
+    IMPORTANT:
+    This model expects the raw input to include attachment data from the
+    Facebook Graph API. When querying posts, you MUST request the following
+    fields for validation and normalization to work correctly:
+
+        ...get_connections(
+            account_id,
+            "posts",
+            fields="id,message,created_time,attachments{media,type,subattachments}"
+        )
+
+    If `attachments` or `attachments.media.image` are missing from the
+    response, `attachments.images` will be set to None.
+    """
+    id: str = Field(..., description="Unique identifier of the Facebook post")
+    created_time: datetime = Field(..., description="Timestamp when the post was created (ISO-8601)")
+    message: str | None = Field(None, description="Text content of the post")
+    attachments: Attachments | None = Field(None, description="Normalized attachments associated with the post")
+
+    @model_validator(mode="before")
+    @classmethod
+    def extract_facebook_payload(cls, raw: dict[str, Any]):
+        images: list[Image] = []
+
+        for att in raw.get("attachments", {}).get("data", []):
+            if att.get("type") != "photo":
+                continue
+
+            image = att.get("media", {}).get("image")
+            if not image:
+                continue
+
+            images.append(
+                Image(
+                    src=image["src"],
+                    width=image["width"],
+                    height=image["height"],
+                )
+            )
+
+        return {
+            "id": raw["id"],
+            "created_time": raw["created_time"],
+            "message": raw.get("message"),
+            "attachments": {"images": images} if images else None,
+        }
+

pyfb_kit-0.1.0/src/pyfb_kit/types/graph_api.py

@@ -0,0 +1,12 @@
+from typing import Annotated, Any
+
+type Response = Annotated[
+    dict[str, Any],
+    "Raw Facebook Graph API response object returned by get_connections()."
+]
+
+type Data = Annotated[
+    list[dict[str, Any]],
+    "List of raw Facebook Graph API objects extracted from the 'data' field."
+]
+