postproxy-sdk 1.0.0__tar.gz

postproxy_sdk-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+*.egg
+.venv/

postproxy_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: postproxy-sdk
+Version: 1.0.0
+Summary: Async Python client for the PostProxy API
+Project-URL: Homepage, https://postproxy.dev
+Project-URL: Documentation, https://postproxy.dev/getting-started/overview/
+Project-URL: Repository, https://github.com/postproxy/postproxy-python
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.19; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PostProxy Python SDK
+
+Async Python client for the [PostProxy API](https://postproxy.dev). Fully typed with Pydantic v2 models and async/await via httpx.
+
+## Installation
+
+```bash
+pip install postproxy-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import asyncio
+from postproxy import PostProxy
+
+async def main():
+    async with PostProxy("your-api-key", profile_group_id="pg-abc") as client:
+        # List profiles
+        profiles = await client.profiles.list()
+
+        # Create a post
+        post = await client.posts.create(
+            "Hello from PostProxy!",
+            profiles=[profiles[0].id],
+        )
+        print(post.id, post.status)
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Client
+
+```python
+from postproxy import PostProxy
+
+# Basic
+client = PostProxy("your-api-key")
+
+# With a default profile group (applied to all requests)
+client = PostProxy("your-api-key", profile_group_id="pg-abc")
+
+# With a custom httpx client
+import httpx
+client = PostProxy("your-api-key", httpx_client=httpx.AsyncClient(timeout=30))
+
+# As a context manager (auto-closes the HTTP client)
+async with PostProxy("your-api-key") as client:
+    ...
+
+# Manual cleanup
+await client.close()
+```
+
+### Posts
+
+```python
+# List posts (paginated)
+page = await client.posts.list(page=0, per_page=10, status="draft")
+print(page.total, page.data)
+
+# Filter by platform and schedule
+from datetime import datetime
+page = await client.posts.list(
+    platforms=["instagram", "tiktok"],
+    scheduled_after=datetime(2025, 6, 1),
+)
+
+# Get a single post
+post = await client.posts.get("post-id")
+
+# Create a post
+post = await client.posts.create(
+    "Check out our new product!",
+    profiles=["profile-id-1", "profile-id-2"],
+)
+
+# Create a draft
+post = await client.posts.create(
+    "Draft content",
+    profiles=["profile-id"],
+    draft=True,
+)
+
+# Create with media URLs
+post = await client.posts.create(
+    "Photo post",
+    profiles=["profile-id"],
+    media=["https://example.com/image.jpg"],
+)
+
+# Create with local file uploads
+post = await client.posts.create(
+    "Posted with a local file!",
+    profiles=["profile-id"],
+    media_files=["./photo.jpg", "./video.mp4"],
+)
+
+# Mix media URLs and local files
+post = await client.posts.create(
+    "Mixed media",
+    profiles=["profile-id"],
+    media=["https://example.com/image.jpg"],
+    media_files=["./local-photo.jpg"],
+)
+
+# Create with platform-specific params
+from postproxy import PlatformParams, InstagramParams, TikTokParams
+
+post = await client.posts.create(
+    "Cross-platform post",
+    profiles=["ig-profile", "tt-profile"],
+    platforms=PlatformParams(
+        instagram=InstagramParams(format="reel", collaborators=["@friend"]),
+        tiktok=TikTokParams(format="video", privacy_status="PUBLIC_TO_EVERYONE"),
+    ),
+)
+
+# Schedule a post
+post = await client.posts.create(
+    "Scheduled post",
+    profiles=["profile-id"],
+    scheduled_at="2025-12-25T09:00:00Z",
+)
+
+# Publish a draft
+post = await client.posts.publish_draft("post-id")
+
+# Delete a post
+result = await client.posts.delete("post-id")
+print(result.deleted)  # True
+```
+
+### Profiles
+
+```python
+# List all profiles
+profiles = await client.profiles.list()
+
+# List profiles in a specific group (overrides client default)
+profiles = await client.profiles.list(profile_group_id="pg-other")
+
+# Get a single profile
+profile = await client.profiles.get("profile-id")
+print(profile.name, profile.platform, profile.status)
+
+# Get available placements for a profile
+placements = await client.profiles.placements("profile-id")
+for p in placements:
+    print(p.id, p.name)
+
+# Delete a profile
+result = await client.profiles.delete("profile-id")
+print(result.success)  # True
+```
+
+### Profile Groups
+
+```python
+# List all groups
+groups = await client.profile_groups.list()
+
+# Get a single group
+group = await client.profile_groups.get("pg-id")
+print(group.name, group.profiles_count)
+
+# Create a group
+group = await client.profile_groups.create("My New Group")
+
+# Delete a group (must have no profiles)
+result = await client.profile_groups.delete("pg-id")
+print(result.deleted)  # True
+
+# Initialize a social platform connection
+conn = await client.profile_groups.initialize_connection(
+    "pg-id",
+    platform="instagram",
+    redirect_url="https://yourapp.com/callback",
+)
+print(conn.url)  # Redirect the user to this URL
+```
+
+## Error handling
+
+All errors extend `PostProxyError`, which includes the HTTP status code and raw response body:
+
+```python
+from postproxy import (
+    PostProxyError,
+    AuthenticationError,   # 401
+    BadRequestError,       # 400
+    NotFoundError,         # 404
+    ValidationError,       # 422
+)
+
+try:
+    await client.posts.get("nonexistent")
+except NotFoundError as e:
+    print(e.status_code)  # 404
+    print(e.response)     # {"error": "Not found"}
+except PostProxyError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Types
+
+All responses are parsed into Pydantic v2 models. Key types:
+
+| Model | Fields |
+|---|---|
+| `Post` | id, body, status, scheduled_at, created_at, platforms |
+| `Profile` | id, name, status, platform, profile_group_id, expires_at, post_count |
+| `ProfileGroup` | id, name, profiles_count |
+| `PlatformResult` | platform, status, params, error, attempted_at, insights |
+| `PaginatedResponse[T]` | total, page, per_page, data |
+
+### Platform parameter models
+
+| Model | Platform |
+|---|---|
+| `FacebookParams` | format (`post`, `story`), first_comment, page_id |
+| `InstagramParams` | format (`post`, `reel`, `story`), first_comment, collaborators, cover_url, audio_name, trial_strategy, thumb_offset |
+| `TikTokParams` | format (`video`, `image`), privacy_status, photo_cover_index, auto_add_music, made_with_ai, disable_comment, disable_duet, disable_stitch, brand_content_toggle, brand_organic_toggle |
+| `LinkedInParams` | format (`post`), organization_id |
+| `YouTubeParams` | format (`post`), title, privacy_status, cover_url |
+| `PinterestParams` | format (`pin`), title, board_id, destination_link, cover_url, thumb_offset |
+| `ThreadsParams` | format (`post`) |
+| `TwitterParams` | format (`post`) |
+
+Wrap them in `PlatformParams` when passing to `posts.create()`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy postproxy/
+```
+
+## License
+
+MIT

postproxy_sdk-1.0.0/README.md

@@ -0,0 +1,246 @@
+# PostProxy Python SDK
+
+Async Python client for the [PostProxy API](https://postproxy.dev). Fully typed with Pydantic v2 models and async/await via httpx.
+
+## Installation
+
+```bash
+pip install postproxy-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import asyncio
+from postproxy import PostProxy
+
+async def main():
+    async with PostProxy("your-api-key", profile_group_id="pg-abc") as client:
+        # List profiles
+        profiles = await client.profiles.list()
+
+        # Create a post
+        post = await client.posts.create(
+            "Hello from PostProxy!",
+            profiles=[profiles[0].id],
+        )
+        print(post.id, post.status)
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Client
+
+```python
+from postproxy import PostProxy
+
+# Basic
+client = PostProxy("your-api-key")
+
+# With a default profile group (applied to all requests)
+client = PostProxy("your-api-key", profile_group_id="pg-abc")
+
+# With a custom httpx client
+import httpx
+client = PostProxy("your-api-key", httpx_client=httpx.AsyncClient(timeout=30))
+
+# As a context manager (auto-closes the HTTP client)
+async with PostProxy("your-api-key") as client:
+    ...
+
+# Manual cleanup
+await client.close()
+```
+
+### Posts
+
+```python
+# List posts (paginated)
+page = await client.posts.list(page=0, per_page=10, status="draft")
+print(page.total, page.data)
+
+# Filter by platform and schedule
+from datetime import datetime
+page = await client.posts.list(
+    platforms=["instagram", "tiktok"],
+    scheduled_after=datetime(2025, 6, 1),
+)
+
+# Get a single post
+post = await client.posts.get("post-id")
+
+# Create a post
+post = await client.posts.create(
+    "Check out our new product!",
+    profiles=["profile-id-1", "profile-id-2"],
+)
+
+# Create a draft
+post = await client.posts.create(
+    "Draft content",
+    profiles=["profile-id"],
+    draft=True,
+)
+
+# Create with media URLs
+post = await client.posts.create(
+    "Photo post",
+    profiles=["profile-id"],
+    media=["https://example.com/image.jpg"],
+)
+
+# Create with local file uploads
+post = await client.posts.create(
+    "Posted with a local file!",
+    profiles=["profile-id"],
+    media_files=["./photo.jpg", "./video.mp4"],
+)
+
+# Mix media URLs and local files
+post = await client.posts.create(
+    "Mixed media",
+    profiles=["profile-id"],
+    media=["https://example.com/image.jpg"],
+    media_files=["./local-photo.jpg"],
+)
+
+# Create with platform-specific params
+from postproxy import PlatformParams, InstagramParams, TikTokParams
+
+post = await client.posts.create(
+    "Cross-platform post",
+    profiles=["ig-profile", "tt-profile"],
+    platforms=PlatformParams(
+        instagram=InstagramParams(format="reel", collaborators=["@friend"]),
+        tiktok=TikTokParams(format="video", privacy_status="PUBLIC_TO_EVERYONE"),
+    ),
+)
+
+# Schedule a post
+post = await client.posts.create(
+    "Scheduled post",
+    profiles=["profile-id"],
+    scheduled_at="2025-12-25T09:00:00Z",
+)
+
+# Publish a draft
+post = await client.posts.publish_draft("post-id")
+
+# Delete a post
+result = await client.posts.delete("post-id")
+print(result.deleted)  # True
+```
+
+### Profiles
+
+```python
+# List all profiles
+profiles = await client.profiles.list()
+
+# List profiles in a specific group (overrides client default)
+profiles = await client.profiles.list(profile_group_id="pg-other")
+
+# Get a single profile
+profile = await client.profiles.get("profile-id")
+print(profile.name, profile.platform, profile.status)
+
+# Get available placements for a profile
+placements = await client.profiles.placements("profile-id")
+for p in placements:
+    print(p.id, p.name)
+
+# Delete a profile
+result = await client.profiles.delete("profile-id")
+print(result.success)  # True
+```
+
+### Profile Groups
+
+```python
+# List all groups
+groups = await client.profile_groups.list()
+
+# Get a single group
+group = await client.profile_groups.get("pg-id")
+print(group.name, group.profiles_count)
+
+# Create a group
+group = await client.profile_groups.create("My New Group")
+
+# Delete a group (must have no profiles)
+result = await client.profile_groups.delete("pg-id")
+print(result.deleted)  # True
+
+# Initialize a social platform connection
+conn = await client.profile_groups.initialize_connection(
+    "pg-id",
+    platform="instagram",
+    redirect_url="https://yourapp.com/callback",
+)
+print(conn.url)  # Redirect the user to this URL
+```
+
+## Error handling
+
+All errors extend `PostProxyError`, which includes the HTTP status code and raw response body:
+
+```python
+from postproxy import (
+    PostProxyError,
+    AuthenticationError,   # 401
+    BadRequestError,       # 400
+    NotFoundError,         # 404
+    ValidationError,       # 422
+)
+
+try:
+    await client.posts.get("nonexistent")
+except NotFoundError as e:
+    print(e.status_code)  # 404
+    print(e.response)     # {"error": "Not found"}
+except PostProxyError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Types
+
+All responses are parsed into Pydantic v2 models. Key types:
+
+| Model | Fields |
+|---|---|
+| `Post` | id, body, status, scheduled_at, created_at, platforms |
+| `Profile` | id, name, status, platform, profile_group_id, expires_at, post_count |
+| `ProfileGroup` | id, name, profiles_count |
+| `PlatformResult` | platform, status, params, error, attempted_at, insights |
+| `PaginatedResponse[T]` | total, page, per_page, data |
+
+### Platform parameter models
+
+| Model | Platform |
+|---|---|
+| `FacebookParams` | format (`post`, `story`), first_comment, page_id |
+| `InstagramParams` | format (`post`, `reel`, `story`), first_comment, collaborators, cover_url, audio_name, trial_strategy, thumb_offset |
+| `TikTokParams` | format (`video`, `image`), privacy_status, photo_cover_index, auto_add_music, made_with_ai, disable_comment, disable_duet, disable_stitch, brand_content_toggle, brand_organic_toggle |
+| `LinkedInParams` | format (`post`), organization_id |
+| `YouTubeParams` | format (`post`), title, privacy_status, cover_url |
+| `PinterestParams` | format (`pin`), title, board_id, destination_link, cover_url, thumb_offset |
+| `ThreadsParams` | format (`post`) |
+| `TwitterParams` | format (`post`) |
+
+Wrap them in `PlatformParams` when passing to `posts.create()`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy postproxy/
+```
+
+## License
+
+MIT

postproxy_sdk-1.0.0/examples/create_post.py

@@ -0,0 +1,162 @@
+"""Examples of creating posts with the PostProxy SDK."""
+
+import asyncio
+import os
+
+from postproxy import (
+    PostProxy,
+    PlatformParams,
+    FacebookParams,
+    InstagramParams,
+    TikTokParams,
+    YouTubeParams,
+    PinterestParams,
+    LinkedInParams,
+    ThreadsParams,
+    TwitterParams,
+)
+
+API_KEY = os.environ["POSTPROXY_API_KEY"]
+PROFILE_GROUP_ID = os.environ.get("POSTPROXY_PROFILE_GROUP_ID")
+
+
+async def simple_post():
+    """Create a simple text post."""
+    async with PostProxy(API_KEY, profile_group_id=PROFILE_GROUP_ID) as client:
+        profiles = await client.profiles.list()
+        post = await client.posts.create(
+            "Hello from PostProxy Python SDK!",
+            profiles=[profiles[0].id],
+        )
+        print(f"Created post {post.id} — status: {post.status}")
+
+
+async def post_with_media():
+    """Create a post with media URLs."""
+    async with PostProxy(API_KEY, profile_group_id=PROFILE_GROUP_ID) as client:
+        profiles = await client.profiles.list()
+        facebook_profile = next(
+            (p for p in profiles if p.platform == "facebook"), None
+        )
+        if facebook_profile is None:
+            raise ValueError("No Facebook profile found")
+
+        placements = await client.profiles.placements(id=facebook_profile.id)
+
+        post = await client.posts.create(
+            "Check this out!",
+            profiles=[facebook_profile.id],
+            draft=True,
+            media=[
+                "https://example.com/photo.jpg",
+            ],
+            platforms=PlatformParams(
+                facebook=FacebookParams(
+                    format="post",
+                    page_id=placements[0].id,
+                    first_comment="First!",
+                ),
+            ),
+        )
+        print(f"Created post {post.id} with media — status: {post.status}")
+
+
+async def post_with_local_file():
+    """Create a post with a local file upload."""
+    async with PostProxy(API_KEY, profile_group_id=PROFILE_GROUP_ID) as client:
+        profiles = await client.profiles.list()
+        post = await client.posts.create(
+            "Posted with a local file!",
+            profiles=[profiles[0].id],
+            draft=True,
+            media_files=["./photo.jpg"],
+        )
+        print(f"Created post {post.id} with file upload — status: {post.status}")
+
+
+async def draft_then_publish():
+    """Create a draft post, then publish it."""
+    async with PostProxy(API_KEY, profile_group_id=PROFILE_GROUP_ID) as client:
+        profiles = await client.profiles.list()
+
+        # Create as draft
+        post = await client.posts.create(
+            "This starts as a draft",
+            profiles=[profiles[0].id],
+            draft=True,
+        )
+        print(f"Created draft {post.id} — status: {post.status}")
+
+        # Publish the draft
+        post = await client.posts.publish_draft(post.id)
+        print(f"Published {post.id} — status: {post.status}")
+
+
+async def scheduled_post():
+    """Schedule a post for the future."""
+    async with PostProxy(API_KEY, profile_group_id=PROFILE_GROUP_ID) as client:
+        profiles = await client.profiles.list()
+        post = await client.posts.create(
+            "This post is scheduled!",
+            profiles=[profiles[0].id],
+            scheduled_at="2025-12-25T09:00:00Z",
+        )
+        print(f"Scheduled post {post.id} for {post.scheduled_at}")
+
+
+async def cross_platform_post():
+    """Create a post with platform-specific parameters."""
+    async with PostProxy(API_KEY, profile_group_id=PROFILE_GROUP_ID) as client:
+        profiles = await client.profiles.list()
+
+        profile_ids = [p.id for p in profiles]
+
+        post = await client.posts.create(
+            "Cross-platform post with custom settings per network",
+            profiles=profile_ids,
+            draft=True,
+            media=["https://example.com/video.mp4"],
+            platforms=PlatformParams(
+                facebook=FacebookParams(
+                    format="post",
+                    first_comment="First!",
+                ),
+                instagram=InstagramParams(
+                    format="reel",
+                    collaborators=["@collab_account"],
+                ),
+                tiktok=TikTokParams(
+                    format="video",
+                    privacy_status="PUBLIC_TO_EVERYONE",
+                    auto_add_music=True,
+                ),
+                linkedin=LinkedInParams(
+                    format="post",
+                    organization_id="org-123",
+                ),
+                youtube=YouTubeParams(
+                    format="post",
+                    title="My Video Title",
+                    privacy_status="public",
+                ),
+                pinterest=PinterestParams(
+                    format="pin",
+                    title="Pin Title",
+                    board_id="board-abc",
+                    destination_link="https://example.com",
+                ),
+                threads=ThreadsParams(
+                    format="post",
+                ),
+                twitter=TwitterParams(
+                    format="post",
+                ),
+            ),
+        )
+        print(f"Created cross-platform post {post.id}")
+        for p in post.platforms:
+            print(f"  {p.platform}: {p.status}")
+
+
+if __name__ == "__main__":
+    asyncio.run(simple_post())