fopost 0.1.0__tar.gz

fopost-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+uv.lock

fopost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Porter Bridge, LLC
+
+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.

fopost-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: fopost
+Version: 0.1.0
+Summary: Official Python SDK for the FoPost API. Schedule and publish to 31 social platforms from your code.
+Project-URL: Homepage, https://fopost.com
+Project-URL: Documentation, https://fopost.com/docs
+Project-URL: Repository, https://github.com/fopost/fopost-python
+Project-URL: Issues, https://github.com/fopost/fopost-python/issues
+Project-URL: Support, https://fopost.com/contact
+Author: FoPost, Porter Bridge, LLC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,fopost,instagram,linkedin,publishing,scheduling,sdk,social-media,twitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# fopost
+
+[![PyPI](https://img.shields.io/pypi/v/fopost.svg)](https://pypi.org/project/fopost/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fopost.svg)](https://pypi.org/project/fopost/)
+[![CI](https://github.com/fopost/fopost-python/actions/workflows/ci.yml/badge.svg)](https://github.com/fopost/fopost-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [FoPost](https://fopost.com) API. Schedule and publish to 31 social platforms from your code.
+
+```bash
+pip install fopost
+```
+
+Requires Python 3.10 or newer. Built on `httpx` and `pydantic` v2, fully typed.
+
+> **0.x release.** The public API is still settling and minor versions may
+> contain breaking changes. Pin an exact version if that matters to you.
+
+## Quick start
+
+```python
+from fopost import Fopost
+
+client = Fopost(api_key="osk_...")  # or set FOPOST_API_KEY
+
+workspace = client.workspaces.list()[0]
+accounts = client.accounts.list(workspace_id=workspace.id)
+
+post = client.posts.create(
+    workspace_id=workspace.id,
+    content="Hello from Python",
+    accounts=[a.id for a in accounts],
+)
+
+client.posts.publish(post.id)
+```
+
+`content` takes a string for a single block, or a list for a thread:
+
+```python
+client.posts.create(
+    workspace_id=workspace.id,
+    content=[
+        "First post in the thread",
+        {
+            "text": "Second one, with an image",
+            "media": [
+                {"type": "image", "name": "chart.png", "url": "https://.../chart.png"},
+            ],
+        },
+    ],
+    accounts=[a.id for a in accounts],
+)
+```
+
+## Scheduling
+
+`status` is `"draft"` or `"scheduled"`; a scheduled post needs `schedule_at`. To send something out now, create it and call `publish`.
+
+```python
+from datetime import datetime, timezone
+
+client.posts.create(
+    workspace_id=workspace.id,
+    status="scheduled",
+    schedule_at=datetime(2026, 9, 1, 10, 0, tzinfo=timezone.utc),
+    content="Scheduled with the SDK",
+    accounts=[accounts[0].id],
+)
+```
+
+## Pagination
+
+`posts.list` returns one page and iterates over its items directly. `posts.iter` walks every page for you:
+
+```python
+page = client.posts.list(workspace_id=workspace.id, status="published", per_page=50)
+print(f"{page.meta.total} published posts")
+for post in page:
+    print(post.id, post.status)
+
+# Every post, one page fetched at a time
+for post in client.posts.iter(workspace_id=workspace.id):
+    print(post.id)
+
+# Or page by page, when you want the meta
+for page in client.posts.iter_pages(workspace_id=workspace.id):
+    print(page.meta.current_page, len(page))
+```
+
+## AI features
+
+```python
+balance = client.ai.credits()
+print(f"{balance.credits_remaining} of {balance.credits_total} credits left")
+
+result = client.ai.generate_caption(
+    current_caption="shipping a new feature",
+    platforms=["twitter", "linkedin"],
+)
+print(result.caption)
+```
+
+`rewrite` and `repurpose_url` are wired the same way:
+
+```python
+rewrites = client.ai.rewrite(
+    content="Long article-style draft...",
+    platforms=["twitter", "linkedin", "bluesky"],
+)
+for variant in rewrites.results:
+    print(variant.platform, variant.content)
+
+repurposed = client.ai.repurpose_url(
+    url="https://example.com/blog/post",
+    platforms=["twitter", "linkedin", "bluesky", "threads"],
+)
+```
+
+> **API keys reach `credits` and `generate_caption`.** `rewrite` and
+> `repurpose_url` currently require a signed-in dashboard session and answer
+> `401` to an API key. They are here so the surface is complete once the server
+> opens them up.
+
+## Configuration
+
+```python
+Fopost(
+    api_key="osk_...",  # or FOPOST_API_KEY
+    base_url="https://api.fopost.com/api/v1",  # override for a dev server
+    timeout=30.0,  # seconds, or an httpx.Timeout
+    max_retries=3,  # total attempts on a 429
+    http_client=my_httpx_client,  # bring your own transport
+)
+```
+
+| Env var            | Used for                                     |
+| ------------------ | -------------------------------------------- |
+| `FOPOST_API_KEY` | API key, when not passed to the constructor  |
+
+The client is a context manager, and closes its transport on exit:
+
+```python
+with Fopost() as client:
+    client.posts.list(workspace_id=workspace.id)
+```
+
+A `429` is retried automatically, waiting for the interval the API asks for in
+`Retry-After` (delta-seconds or an HTTP date, capped at 60s). `max_retries`
+counts total attempts, so the default of 3 means two retries.
+
+## Error handling
+
+Every non-2xx response raises `FopostError` or one of its subclasses, carrying
+the API's `status`, `code`, and `message`.
+
+```python
+from fopost import Fopost, FopostError, PaymentRequiredError, RateLimitError
+
+try:
+    client.posts.publish("9b2f6c1e-...")
+except PaymentRequiredError as err:
+    print(f"Out of credits — upgrade at {err.upgrade_url}")
+except RateLimitError as err:
+    print(f"Rate limited, retry in {err.retry_after}s")
+except FopostError as err:
+    print(f"API {err.status} ({err.code}): {err.message}")
+```
+
+| Status | Exception               |
+| ------ | ----------------------- |
+| 401    | `AuthenticationError`   |
+| 402    | `PaymentRequiredError`  |
+| 403    | `PermissionDeniedError` |
+| 404    | `NotFoundError`         |
+| 429    | `RateLimitError`        |
+| other  | `FopostError`         |
+
+## Resources
+
+| Namespace    | Methods                                                                                |
+| ------------ | -------------------------------------------------------------------------------------- |
+| `posts`      | `list`, `iter`, `iter_pages`, `get`, `create`, `update`, `delete`, `publish`, `cancel`, `retry`, `preflight`, `deliveries` |
+| `accounts`   | `list`, `get`, `health`                                                                |
+| `workspaces` | `list`, `get`                                                                          |
+| `labels`     | `list`                                                                                 |
+| `ai`         | `credits`, `generate_caption`, `rewrite`, `repurpose_url`                              |
+
+For an endpoint the SDK does not wrap yet, `client.request` sends an
+authenticated call and hands back the decoded body:
+
+```python
+client.request("GET", "/analytics/summary", params={"workspace_id": workspace.id})
+```
+
+## Example
+
+[`examples/create_post.py`](examples/create_post.py) creates a post against a
+running API:
+
+```bash
+export FOPOST_API_KEY=osk_...
+export FOPOST_BASE_URL=http://localhost:8080/api/v1
+python examples/create_post.py "Hello from the Python SDK" --publish
+```
+
+## Contributing
+
+Issues and pull requests are welcome at
+[fopost/fopost-python](https://github.com/fopost/fopost-python).
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv run mypy
+```
+
+## License
+
+MIT
+
+Questions or a problem: [fopost.com/contact](https://fopost.com/contact).

fopost-0.1.0/README.md

@@ -0,0 +1,223 @@
+# fopost
+
+[![PyPI](https://img.shields.io/pypi/v/fopost.svg)](https://pypi.org/project/fopost/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fopost.svg)](https://pypi.org/project/fopost/)
+[![CI](https://github.com/fopost/fopost-python/actions/workflows/ci.yml/badge.svg)](https://github.com/fopost/fopost-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [FoPost](https://fopost.com) API. Schedule and publish to 31 social platforms from your code.
+
+```bash
+pip install fopost
+```
+
+Requires Python 3.10 or newer. Built on `httpx` and `pydantic` v2, fully typed.
+
+> **0.x release.** The public API is still settling and minor versions may
+> contain breaking changes. Pin an exact version if that matters to you.
+
+## Quick start
+
+```python
+from fopost import Fopost
+
+client = Fopost(api_key="osk_...")  # or set FOPOST_API_KEY
+
+workspace = client.workspaces.list()[0]
+accounts = client.accounts.list(workspace_id=workspace.id)
+
+post = client.posts.create(
+    workspace_id=workspace.id,
+    content="Hello from Python",
+    accounts=[a.id for a in accounts],
+)
+
+client.posts.publish(post.id)
+```
+
+`content` takes a string for a single block, or a list for a thread:
+
+```python
+client.posts.create(
+    workspace_id=workspace.id,
+    content=[
+        "First post in the thread",
+        {
+            "text": "Second one, with an image",
+            "media": [
+                {"type": "image", "name": "chart.png", "url": "https://.../chart.png"},
+            ],
+        },
+    ],
+    accounts=[a.id for a in accounts],
+)
+```
+
+## Scheduling
+
+`status` is `"draft"` or `"scheduled"`; a scheduled post needs `schedule_at`. To send something out now, create it and call `publish`.
+
+```python
+from datetime import datetime, timezone
+
+client.posts.create(
+    workspace_id=workspace.id,
+    status="scheduled",
+    schedule_at=datetime(2026, 9, 1, 10, 0, tzinfo=timezone.utc),
+    content="Scheduled with the SDK",
+    accounts=[accounts[0].id],
+)
+```
+
+## Pagination
+
+`posts.list` returns one page and iterates over its items directly. `posts.iter` walks every page for you:
+
+```python
+page = client.posts.list(workspace_id=workspace.id, status="published", per_page=50)
+print(f"{page.meta.total} published posts")
+for post in page:
+    print(post.id, post.status)
+
+# Every post, one page fetched at a time
+for post in client.posts.iter(workspace_id=workspace.id):
+    print(post.id)
+
+# Or page by page, when you want the meta
+for page in client.posts.iter_pages(workspace_id=workspace.id):
+    print(page.meta.current_page, len(page))
+```
+
+## AI features
+
+```python
+balance = client.ai.credits()
+print(f"{balance.credits_remaining} of {balance.credits_total} credits left")
+
+result = client.ai.generate_caption(
+    current_caption="shipping a new feature",
+    platforms=["twitter", "linkedin"],
+)
+print(result.caption)
+```
+
+`rewrite` and `repurpose_url` are wired the same way:
+
+```python
+rewrites = client.ai.rewrite(
+    content="Long article-style draft...",
+    platforms=["twitter", "linkedin", "bluesky"],
+)
+for variant in rewrites.results:
+    print(variant.platform, variant.content)
+
+repurposed = client.ai.repurpose_url(
+    url="https://example.com/blog/post",
+    platforms=["twitter", "linkedin", "bluesky", "threads"],
+)
+```
+
+> **API keys reach `credits` and `generate_caption`.** `rewrite` and
+> `repurpose_url` currently require a signed-in dashboard session and answer
+> `401` to an API key. They are here so the surface is complete once the server
+> opens them up.
+
+## Configuration
+
+```python
+Fopost(
+    api_key="osk_...",  # or FOPOST_API_KEY
+    base_url="https://api.fopost.com/api/v1",  # override for a dev server
+    timeout=30.0,  # seconds, or an httpx.Timeout
+    max_retries=3,  # total attempts on a 429
+    http_client=my_httpx_client,  # bring your own transport
+)
+```
+
+| Env var            | Used for                                     |
+| ------------------ | -------------------------------------------- |
+| `FOPOST_API_KEY` | API key, when not passed to the constructor  |
+
+The client is a context manager, and closes its transport on exit:
+
+```python
+with Fopost() as client:
+    client.posts.list(workspace_id=workspace.id)
+```
+
+A `429` is retried automatically, waiting for the interval the API asks for in
+`Retry-After` (delta-seconds or an HTTP date, capped at 60s). `max_retries`
+counts total attempts, so the default of 3 means two retries.
+
+## Error handling
+
+Every non-2xx response raises `FopostError` or one of its subclasses, carrying
+the API's `status`, `code`, and `message`.
+
+```python
+from fopost import Fopost, FopostError, PaymentRequiredError, RateLimitError
+
+try:
+    client.posts.publish("9b2f6c1e-...")
+except PaymentRequiredError as err:
+    print(f"Out of credits — upgrade at {err.upgrade_url}")
+except RateLimitError as err:
+    print(f"Rate limited, retry in {err.retry_after}s")
+except FopostError as err:
+    print(f"API {err.status} ({err.code}): {err.message}")
+```
+
+| Status | Exception               |
+| ------ | ----------------------- |
+| 401    | `AuthenticationError`   |
+| 402    | `PaymentRequiredError`  |
+| 403    | `PermissionDeniedError` |
+| 404    | `NotFoundError`         |
+| 429    | `RateLimitError`        |
+| other  | `FopostError`         |
+
+## Resources
+
+| Namespace    | Methods                                                                                |
+| ------------ | -------------------------------------------------------------------------------------- |
+| `posts`      | `list`, `iter`, `iter_pages`, `get`, `create`, `update`, `delete`, `publish`, `cancel`, `retry`, `preflight`, `deliveries` |
+| `accounts`   | `list`, `get`, `health`                                                                |
+| `workspaces` | `list`, `get`                                                                          |
+| `labels`     | `list`                                                                                 |
+| `ai`         | `credits`, `generate_caption`, `rewrite`, `repurpose_url`                              |
+
+For an endpoint the SDK does not wrap yet, `client.request` sends an
+authenticated call and hands back the decoded body:
+
+```python
+client.request("GET", "/analytics/summary", params={"workspace_id": workspace.id})
+```
+
+## Example
+
+[`examples/create_post.py`](examples/create_post.py) creates a post against a
+running API:
+
+```bash
+export FOPOST_API_KEY=osk_...
+export FOPOST_BASE_URL=http://localhost:8080/api/v1
+python examples/create_post.py "Hello from the Python SDK" --publish
+```
+
+## Contributing
+
+Issues and pull requests are welcome at
+[fopost/fopost-python](https://github.com/fopost/fopost-python).
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv run mypy
+```
+
+## License
+
+MIT
+
+Questions or a problem: [fopost.com/contact](https://fopost.com/contact).

fopost-0.1.0/examples/create_post.py

@@ -0,0 +1,83 @@
+"""Create a post and publish it.
+
+Point it at a local dev API:
+
+    export FOPOST_API_KEY=osk_...
+    export FOPOST_BASE_URL=http://localhost:8080/api/v1
+    python examples/create_post.py "Hello from the Python SDK"
+
+Without --publish it stops at a draft, so you can run it against a real
+workspace without anything going out.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from fopost import DEFAULT_BASE_URL, Fopost, FopostError
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create a post with the FoPost SDK.")
+    parser.add_argument(
+        "text",
+        nargs="?",
+        default="Hello from the FoPost Python SDK",
+        help="post body",
+    )
+    parser.add_argument("--workspace", help="workspace id (defaults to the first one)")
+    parser.add_argument(
+        "--publish",
+        action="store_true",
+        help="publish immediately instead of leaving a draft",
+    )
+    args = parser.parse_args()
+
+    api_key = os.environ.get("FOPOST_API_KEY")
+    if not api_key:
+        print("Set FOPOST_API_KEY first.", file=sys.stderr)
+        return 1
+
+    base_url = os.environ.get("FOPOST_BASE_URL", DEFAULT_BASE_URL)
+
+    with Fopost(api_key=api_key, base_url=base_url) as client:
+        try:
+            workspace_id = args.workspace
+            if not workspace_id:
+                workspaces = client.workspaces.list()
+                if not workspaces:
+                    print("No workspaces on this key.", file=sys.stderr)
+                    return 1
+                workspace_id = workspaces[0].id
+                print(f"Workspace: {workspaces[0].name} ({workspace_id})")
+
+            accounts = client.accounts.list(workspace_id=workspace_id)
+            if not accounts:
+                print("No connected accounts in this workspace.", file=sys.stderr)
+                return 1
+            for account in accounts:
+                print(f"  · {account.platform}: @{account.username}")
+
+            post = client.posts.create(
+                workspace_id=workspace_id,
+                content=args.text,
+                accounts=[a.id for a in accounts],
+            )
+            print(f"Created post {post.id} ({post.status})")
+
+            if args.publish:
+                client.posts.publish(post.id)
+                for delivery in client.posts.deliveries(post.id):
+                    print(f"  · {delivery.platform}: {delivery.status}")
+
+            return 0
+
+        except FopostError as err:
+            print(f"API error: {err}", file=sys.stderr)
+            return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fopost-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fopost"
+version = "0.1.0"
+description = "Official Python SDK for the FoPost API. Schedule and publish to 31 social platforms from your code."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "FoPost, Porter Bridge, LLC" }]
+keywords = [
+  "fopost",
+  "social-media",
+  "publishing",
+  "scheduling",
+  "twitter",
+  "linkedin",
+  "instagram",
+  "api",
+  "sdk",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "pydantic>=2.7"]
+
+[project.urls]
+Homepage = "https://fopost.com"
+Documentation = "https://fopost.com/docs"
+Repository = "https://github.com/fopost/fopost-python"
+Issues = "https://github.com/fopost/fopost-python/issues"
+Support = "https://fopost.com/contact"
+
+[dependency-groups]
+dev = ["pytest>=8", "respx>=0.21", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fopost"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/fopost", "tests", "examples", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fopost", "tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/fopost"]