Metadata-Version: 2.4
Name: postdom
Version: 0.1.0
Summary: Typed sync and async Python client for the Postdom short-form publishing API.
Project-URL: Homepage, https://postdom.com
Project-URL: Repository, https://github.com/deanfankhauser/postdom
Project-URL: Issues, https://github.com/deanfankhauser/postdom/issues
Author-email: Postdom <support@postdom.com>
License: Proprietary
Keywords: ai agent,instagram reels api,schedule posts api,short-form video,social media api,tiktok api,youtube shorts api
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Description-Content-Type: text/markdown

# postdom

Typed synchronous and asynchronous Python clients for the [Postdom](https://postdom.com)
short-form publishing API.

```bash
pip install postdom
```

```python
from pathlib import Path
import os

from postdom import Postdom

with Postdom(os.environ["POSTDOM_API_KEY"]) as postdom:
    upload = postdom.upload_media(
        Path("launch.mp4").read_bytes(),
        content_type="video/mp4",
        platforms=["tiktok"],
    )
    media = postdom.wait_for_media(upload.media_handle)
    if media.status != "stored":
        raise RuntimeError(f"Media is {media.status}")

    submission = postdom.publish_video(
        account_ids=["account-tiktok"],
        media_handle=media.media_handle,
        caption="Launch day. Here is what we shipped.",
        intent="Announce the launch",
    )
    result = postdom.wait_for_publish(submission.id)
    print(result.status)
```

The async client has the same Python operation names:

```python
import os

from postdom import AsyncPostdom


async def workspace_status():
    async with AsyncPostdom(os.environ["POSTDOM_API_KEY"]) as postdom:
        return await postdom.get_workspace_status()
```

## Contract

The package mirrors the 14 agent-authority operations in `@postdom/sdk`:

- `get_workspace_status`, `list_accounts`, `connect_account`
- `create_media_upload`, `get_media_status`, `upload_media`, `wait_for_media`
- `submit_plan`, `get_plan`
- `publish_video`, `get_post`, `wait_for_publish`
- `get_post_performance`, `get_account_performance`, `get_best_posts`
- `get_brief`, `get_digest`

Responses are Pydantic v2 models. Models allow additive server fields so a harmless API addition
does not break existing applications. The checked-in contract suite locks operation paths,
platforms, statuses, metrics, limits, and media handles to the audited Node SDK, which is itself
drift-tested against the live API route table and `@postdom/core`.

## Authentication and safety

Use a workspace `pd_live_` API key or `pd_oauth_` OAuth access token. Both carry agent authority:
approval, billing, and dashboard administration remain human-only and return
`403 agent_token_forbidden` by design. Credentials are held as Pydantic `SecretStr` values and
never appear in client representations or SDK-generated errors.

`publish_video` defaults TikTok to `SELF_ONLY`, Instagram to a Reel with AI disclosure, and YouTube
to private with synthetic-media disclosure. It generates one idempotency key and reuses it across
safe retries. `connect_account` is never retried because it has no idempotency key.

`upload_media` sends bytes through a separate HTTP client directly to the short-lived signed
storage URL. The Postdom bearer credential is never attached to that PUT, the PUT is never
retried, and the signed URL is not returned from the high-level result.

## Errors

Non-2xx responses raise typed subclasses of `PostdomAPIError`, including
`PostdomAuthenticationError`, `PostdomScopeError`, `PostdomHumanRouteError`,
`PostdomBillingError`, `PostdomRateLimitError`, and `PostdomServerError`. Network and deadline
failures use `PostdomConnectionError` and `PostdomTimeoutError`.

## Release status

Version `0.1.0` is the initial package version. PyPI publishing is held until Dean explicitly
authorizes it; building and audit do not imply registry publication.
