socialapi 0.1.0__tar.gz

socialapi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-type-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format . --check
+
+      - name: Type check
+        run: pyright
+
+      - name: Test
+        run: pytest --cov=socialapi --cov-report=xml

socialapi-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

socialapi-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Type checking
+.pyright/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ruff
+.ruff_cache/
+
+# Block all markdown files by default
+*.md
+
+# Allowlist specific markdown files
+!README.md
+!LICENSE.md
+!CONTRIBUTING.md
+!CHANGELOG.md
+!CODE_OF_CONDUCT.md

socialapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial project structure and SDK skeleton.
+- Exception hierarchy mapped to SocialAPI error codes.
+- Sync (`SocialAPI`) and async (`AsyncSocialAPI`) client stubs.
+- Resource namespace stubs for all API endpoints.
+- Pydantic model stubs for all response types.
+- CI/CD workflows for linting, testing, type checking, and PyPI publishing.

socialapi-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to socialapi-python
+
+Thank you for considering contributing to the SocialAPI Python SDK.
+
+## Development Setup
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/social-api-ai/socialapi-python.git
+   cd socialapi-python
+   ```
+
+2. Create a virtual environment and install dependencies:
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+   pip install -e ".[dev]"
+   ```
+
+## Running Tests
+
+```bash
+# All tests
+pytest
+
+# Single file
+pytest tests/test_accounts.py
+
+# Single test
+pytest tests/test_accounts.py -k "test_list"
+
+# With coverage
+pytest --cov=socialapi
+```
+
+## Linting and Formatting
+
+```bash
+# Lint
+ruff check .
+
+# Auto-fix lint issues
+ruff check . --fix
+
+# Format
+ruff format .
+
+# Format check (CI mode)
+ruff format . --check
+```
+
+## Type Checking
+
+```bash
+pyright
+```
+
+## Pre-Commit Checklist
+
+Run all quality checks before committing:
+
+```bash
+ruff check . && ruff format . --check && pyright && pytest
+```
+
+All four must pass before a pull request can be merged.
+
+## Pull Request Guidelines
+
+1. **Branch from `main`** and open your PR against `main`.
+2. **Keep changes focused** -- one feature or fix per PR.
+3. **Add tests** for any new functionality.
+4. **Update docstrings** using Google-style format.
+5. **Add type annotations** to all public functions and methods.
+6. **Ensure all checks pass** (lint, format, type check, tests).
+7. **Update CHANGELOG.md** with a summary of your changes under the `[Unreleased]` section.
+
+## Code Style
+
+- Follow PEP 8 naming conventions.
+- Use `X | None` union syntax (PEP 604), not `Optional[X]`.
+- Use built-in generics (`list[T]`, `dict[K, V]`), not `typing.List` / `typing.Dict`.
+- Prefix private modules with `_`.
+- Use keyword-only arguments (after `*`) for all optional parameters.
+- Write Google-style docstrings with `Args`, `Returns`, and `Raises` sections.
+
+## Questions?
+
+Open an issue or reach out at contact@social-api.ai.

socialapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SocialAPI.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

socialapi-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: socialapi
+Version: 0.1.0
+Summary: Official Python SDK for SocialAPI -- unified social media inbox API
+Project-URL: Homepage, https://social-api.ai
+Project-URL: Documentation, https://docs.social-api.ai
+Project-URL: Repository, https://github.com/social-api-ai/socialapi-python
+Project-URL: Changelog, https://github.com/social-api-ai/socialapi-python/blob/main/CHANGELOG.md
+Author-email: SocialAPI <contact@social-api.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SocialAPI Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/socialapi.svg)](https://pypi.org/project/socialapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/socialapi.svg)](https://pypi.org/project/socialapi/)
+[![CI](https://github.com/social-api-ai/socialapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/social-api-ai/socialapi-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+The official Python SDK for [SocialAPI](https://social-api.ai) -- a unified social media inbox API that reads and responds to comments, DMs, reviews, and mentions across Instagram, Facebook, Google Reviews, TikTok, YouTube, X/Twitter, Trustpilot, and LinkedIn through a single REST API.
+
+## Installation
+
+```bash
+pip install socialapi
+```
+
+Requires Python 3.10 or later.
+
+## Quick Start
+
+### Synchronous
+
+```python
+from socialapi import SocialAPI
+
+client = SocialAPI(api_key="sapi_key_...")
+
+# List connected accounts
+accounts = client.accounts.list()
+for account in accounts.data:
+    print(f"{account.platform}: {account.name}")
+
+# List comments on a post
+comments = client.comments.list("acc_123", "post_456")
+for comment in comments.data:
+    print(comment.content.text)
+
+# Reply to a comment
+reply = client.interactions.reply("acc_123", "sapi_cmt_abc", text="Thanks!")
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from socialapi import AsyncSocialAPI
+
+async def main():
+    async with AsyncSocialAPI(api_key="sapi_key_...") as client:
+        accounts = await client.accounts.list()
+        for account in accounts.data:
+            print(f"{account.platform}: {account.name}")
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass your API key directly or set the `SOCIALAPI_API_KEY` environment variable:
+
+```python
+# Explicit
+client = SocialAPI(api_key="sapi_key_...")
+
+# From environment variable
+import os
+os.environ["SOCIALAPI_API_KEY"] = "sapi_key_..."
+client = SocialAPI()
+```
+
+API keys are created in the [SocialAPI dashboard](https://app.social-api.ai/keys) or via the API. The full key is shown once at creation -- store it securely.
+
+## Usage Examples
+
+### Managing Accounts
+
+```python
+# Connect a new account via OAuth
+result = client.accounts.connect("instagram", metadata={"redirect_uri": "https://..."})
+
+# Disconnect an account
+client.accounts.disconnect("acc_123")
+```
+
+### Publishing Posts
+
+```python
+# Create a post across multiple accounts
+post = client.posts.create(
+    account_ids=["acc_123", "acc_456"],
+    text="Hello from SocialAPI!",
+)
+
+# Schedule a post
+post = client.posts.create(
+    account_ids=["acc_123"],
+    text="Scheduled post",
+    scheduled_at="2026-04-01T12:00:00Z",
+)
+```
+
+### Direct Messages
+
+```python
+# List DM threads
+dms = client.dms.list("acc_123")
+
+# Send a DM
+client.dms.send("acc_123", thread_id="thread_789", text="Hello!")
+```
+
+### Media Upload
+
+```python
+# Upload media for use in posts
+upload_info = client.media.upload_url(media_type="image", filename="photo.jpg")
+# Upload to the presigned URL, then verify:
+client.media.verify(media_id=upload_info.id)
+```
+
+## Error Handling
+
+The SDK raises typed exceptions for all API errors:
+
+```python
+from socialapi import (
+    SocialAPIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    PlanLimitError,
+    PlatformRateLimitError,
+    ValidationError,
+    NotSupportedError,
+)
+
+try:
+    client.comments.list("acc_123", "post_456")
+except NotFoundError as e:
+    print(f"Not found: {e.message} (code: {e.code})")
+except PlanLimitError:
+    print("Monthly limit exceeded -- upgrade your plan")
+except PlatformRateLimitError:
+    print("Platform rate limit hit -- will auto-retry")
+except AuthenticationError:
+    print("Invalid API key")
+except SocialAPIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Pagination
+
+### Single Page
+
+```python
+response = client.comments.list("acc_123", "post_456", limit=10)
+print(response.data)   # list of comments
+print(response.count)  # total count
+```
+
+### Auto-Pagination
+
+```python
+# Synchronous -- iterates through all pages automatically
+for comment in client.comments.list_auto("acc_123", "post_456"):
+    print(comment.content.text)
+
+# Asynchronous
+async for comment in async_client.comments.list_auto("acc_123", "post_456"):
+    print(comment.content.text)
+```
+
+## Configuration
+
+```python
+client = SocialAPI(
+    api_key="sapi_key_...",
+    base_url="https://api.social-api.ai",  # default
+    timeout=30.0,                           # seconds, default
+    max_retries=3,                          # default
+)
+```
+
+### Context Manager
+
+Both clients support context managers for proper resource cleanup:
+
+```python
+with SocialAPI(api_key="sapi_key_...") as client:
+    accounts = client.accounts.list()
+
+async with AsyncSocialAPI(api_key="sapi_key_...") as client:
+    accounts = await client.accounts.list()
+```
+
+### Custom HTTP Client
+
+For advanced use cases, inject your own httpx client:
+
+```python
+import httpx
+
+http_client = httpx.Client(verify=False)  # custom SSL settings, proxies, etc.
+client = SocialAPI(api_key="sapi_key_...", http_client=http_client)
+```
+
+## API Reference
+
+For full endpoint documentation, visit [docs.social-api.ai](https://docs.social-api.ai).
+
+### Resources
+
+| Resource | Description |
+|---|---|
+| `client.accounts` | Manage connected social accounts |
+| `client.posts` | Create, update, delete, and retry posts |
+| `client.comments` | List and moderate comments |
+| `client.interactions` | Reply to comments, reviews, and mentions |
+| `client.dms` | List and send direct messages |
+| `client.reviews` | List reviews |
+| `client.mentions` | List mentions |
+| `client.media` | Upload and manage media files |
+| `client.usage` | Check usage statistics |
+| `client.keys` | Manage API keys |
+| `client.users` | Manage user profile |
+| `client.webhooks` | Configure webhook endpoints |
+| `client.billing` | Manage billing and subscriptions |
+| `client.oauth` | OAuth token exchange |
+| `client.search` | Search across accounts |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.