socialchimp 0.1.0__tar.gz

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

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Check types
+        run: uv run mypy
+
+      - name: Run tests
+        run: uv run pytest

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

@@ -0,0 +1,80 @@
+name: Publish
+
+# Publishes to PyPI when you publish a GitHub release.
+#
+# There is no API token anywhere. PyPI is told to trust this one workflow, in
+# this one repository, and GitHub proves who it is at the moment it uploads.
+# Nothing to store, nothing to leak, nothing to rotate.
+#
+# To set it up, add a publisher at https://pypi.org/manage/account/publishing/
+# with these exact values:
+#
+#     PyPI project name   socialchimp
+#     Owner               raghulj
+#     Repository name     socialchimp
+#     Workflow name       publish.yml
+#     Environment name    pypi
+#
+# See docs/releasing.md for the whole procedure.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # Publishing a broken release cannot be undone: PyPI never lets a version
+  # be replaced. So everything is checked again here, rather than trusting
+  # that the commit was green when it was tagged.
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest
+
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+
+      # Check the built files are actually uploadable before we try, so a
+      # bad description or a missing field fails here rather than half way
+      # through claiming the version number.
+      - run: uvx twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: packages
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/socialchimp
+    permissions:
+      # Lets GitHub prove to PyPI that this workflow is what it says it is.
+      # This is what replaces the API token.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: packages
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

socialchimp-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Secrets - never commit real credentials
+.env
+.env.*
+!.env.example

socialchimp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,49 @@
+# Checks that run before every commit and push.
+#
+# Install once after cloning:
+#     uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+#
+# Fast checks (format, lint, types) run on commit.
+# The test suite runs on push, because it is slower.
+
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=512]
+      - id: detect-private-key
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      # Fix what can be fixed, then fail on what is left.
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (strict)
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest (100% coverage required)
+        entry: uv run pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: [pre-push]

socialchimp-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+Notable changes, newest first. Versions follow
+[semantic versioning](https://semver.org): while this is 0.x, a change to the
+middle number may break something.
+
+## 0.1.0 - 2026-08-31
+
+The first release. Nine networks work end to end.
+
+### Networks
+
+**Mastodon**, **Bluesky**, **Facebook Pages**, **Instagram**, **YouTube**,
+**TikTok**, **X**, **Pinterest**, **Threads**.
+
+Each one signs people in, keeps their token working, posts, and reports what
+happened. What a network cannot do it says so, rather than approximating:
+Bluesky has no scheduling, YouTube has no post of words alone, Pinterest has
+no comments, Instagram cannot take an upload and needs a web address.
+
+### What is in it
+
+- **One way to work with every network**, and direct access to any of them
+  when the shared way is not enough. Direct access still renews your token,
+  retries, and respects rate limits - only the request is yours.
+- **Your app keeps its own database.** No models, no migrations. Five methods
+  in a class you write.
+- **Tokens renewed before they run out**, under a lock so two workers cannot
+  renew at once. That matters on Bluesky, Pinterest and TikTok, which replace
+  the refresh token every time it is used: without the lock, whichever worker
+  loses is left holding a token the network has already thrown away, and that
+  account is disconnected until the person signs in again.
+- **Updates the same shape either way** - pushed where a network supports it,
+  found by checking on a timer where it does not.
+- **Helpers for Django, FastAPI and Flask.** Django works on ordinary
+  synchronous views and lets you write your storage as plain Django ORM code.
+- **A test kit** so a network you write yourself can prove it behaves like
+  the ones here. You do not need a pull request to this repository to add a
+  network; publish a package, and socialchimp finds it.
+
+### Getting started
+
+```bash
+pip install socialchimp
+```
+
+Then [docs/getting-started.md](docs/getting-started.md), which goes from
+nothing to a post on Mastodon in six steps.
+
+### Worth knowing
+
+- **Facebook, Instagram, Threads, YouTube, TikTok, X and Pinterest all need
+  you to create the app by hand**, and several review it before it works.
+  That review is the slowest part of getting started, so begin it early.
+  [docs/platforms.md](docs/platforms.md) says what each one needs.
+- **Three networks have a trap that makes working code look broken.** An
+  unaudited TikTok app posts everything as private. Pinterest on Trial shows
+  your pins only to you. X answers 403 when your plan does not allow
+  something. All three are called out where you will meet them.
+- **The way platforms are written is now settled.** See
+  [the promise about changes](docs/adding-a-platform.md#what-we-promise-about-changes).
+
+### Quality
+
+1706 tests. 100% of lines and branches covered, enforced - the suite fails
+below it. `mypy --strict` with no ignores anywhere. Checked on Python 3.11,
+3.12 and 3.13.

socialchimp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+Thanks for helping. This page covers how to get set up and the three rules
+that are not negotiable.
+
+## Getting set up
+
+```bash
+git clone https://github.com/raghulj/socialchimp
+cd socialchimp
+uv sync --all-extras --dev
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+The hooks check formatting, style and types before each commit, and run the
+tests before each push. That is deliberate: it means a broken push is hard to
+do by accident.
+
+## The three rules
+
+**1. Tests come first.** Write the failing test, watch it fail for the reason
+you expect, then write the code. A test written afterwards tends to describe
+what the code does rather than what it should do.
+
+**2. Coverage stays at 100%.** `uv run pytest` fails below it. This is not
+about the number - it is that a line nobody tested is a line nobody has ever
+run, and in a library that talks to fifteen different networks those lines
+pile up fast.
+
+Coverage is a floor, not a finish line. A test that runs a line without
+checking anything meaningful passes the gate and helps nobody. Worth trying
+on anything tricky: break your own code on purpose and check a test notices.
+
+**3. Types are strict.** `uv run mypy` passes with no `# type: ignore`. If a
+type is hard to write, that is usually the design telling you something.
+
+## Language
+
+Write in plain words, in code, docs and error messages alike.
+
+Someone reading this library is usually in the middle of a problem: a token
+stopped working, a post did not arrive. They should not also have to decode
+our vocabulary. Say "the shared way", not "the abstraction layer". Say
+"checking on a timer", not "polling-based virtual webhooks". If a name needs
+a glossary, pick a different name.
+
+Error messages should say what went wrong **and what to do about it**.
+
+## Comments
+
+Comments explain *why*, not *what*. The code already says what it does.
+
+The comments worth writing are the ones that stop someone undoing a decision
+they do not understand - for example, why token renewal takes a lock and then
+reads the connection a second time. Without the why, that reads like a
+pointless extra query, and someone will remove it.
+
+## Before you push
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
+```
+
+Please do not push red. CI emails are nobody's idea of a good time.
+
+## Adding a network
+
+You do not need to add it here. Publish your own package that registers
+itself and socialchimp will find it. See [docs/adding-a-platform.md](docs/adding-a-platform.md).
+
+If you would like it built in, open an issue first so we can agree where it
+goes in the order - see [docs/PLAN.md](docs/PLAN.md).
+
+## Licence
+
+By contributing you agree your work is released under the MIT licence.

socialchimp-0.1.0/LICENSE

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

socialchimp-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: socialchimp
+Version: 0.1.0
+Summary: One simple way to connect your app to social networks.
+Project-URL: Homepage, https://github.com/raghulj/socialchimp
+Project-URL: Documentation, https://github.com/raghulj/socialchimp/tree/main/docs
+Project-URL: Issues, https://github.com/raghulj/socialchimp/issues
+Author-email: Raghul Jagannathan <raghulj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bluesky,django,fastapi,flask,instagram,mastodon,oauth,pinterest,social,threads,tiktok,twitter,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: bluesky
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: facebook
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == 'flask'
+Provides-Extra: instagram
+Provides-Extra: mastodon
+Provides-Extra: pinterest
+Provides-Extra: testing
+Requires-Dist: pytest>=8.3; extra == 'testing'
+Provides-Extra: threads
+Provides-Extra: tiktok
+Provides-Extra: x
+Provides-Extra: youtube
+Description-Content-Type: text/markdown
+
+# socialchimp
+
+[![CI](https://github.com/raghulj/socialchimp/actions/workflows/ci.yml/badge.svg)](https://github.com/raghulj/socialchimp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/socialchimp?color=0b7285)](https://pypi.org/project/socialchimp/)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/socialchimp/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](CONTRIBUTING.md)
+[![Types](https://img.shields.io/badge/types-mypy%20strict-blue)](pyproject.toml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Licence](https://img.shields.io/badge/licence-MIT-black)](LICENSE)
+
+One simple way to connect your app to social networks.
+
+> **Status: 0.1.0, the first release.** All nine networks below work. The way
+> platforms are written is now settled - see
+> [the promise about changes](docs/adding-a-platform.md#what-we-promise-about-changes)
+> before you write your own.
+
+**Mastodon · Bluesky · Facebook Pages · Instagram · YouTube · TikTok · X · Pinterest · Threads**
+
+---
+
+## What it does
+
+Your app needs to let people connect their social accounts, then post for
+them and read what happens. Every network does this differently. socialchimp
+gives you one way to do it, and gets out of the way when you need the network's
+own features.
+
+- **Connect accounts.** Sign in with Mastodon, Bluesky, Facebook, Instagram,
+  YouTube, TikTok, X, Pinterest, Threads and more.
+- **Keep tokens working.** Refresh them before they expire, safely, even when
+  several workers run at once.
+- **Post and read.** Text, pictures, video. Read posts and their numbers back.
+- **Know what happened.** Comments and likes reach you the same way whether the
+  network pushes them to you or we have to check on a timer.
+
+## What it does not do
+
+- **It does not touch your database.** No models, no migrations. You write a
+  small storage class, socialchimp hands you data to save. Your schema stays
+  yours, and it works the same on Django, FastAPI, Flask, or nothing at all.
+- **It does not pretend networks are the same.** Pinterest needs a board.
+  Bluesky cannot schedule. YouTube has no text-only post. Where networks
+  differ, the API says so instead of guessing for you.
+
+---
+
+## Install
+
+```bash
+pip install socialchimp
+```
+
+Add your framework if you want the ready-made routes:
+
+```bash
+pip install "socialchimp[django]"    # or [fastapi], or [flask]
+```
+
+## A first look
+
+```python
+from socialchimp import SocialChimp, Post
+
+sc = SocialChimp(storage=MyStorage())
+
+# Post to a connected account.
+account = sc.account(connection_id)
+result = await account.post(Post(text="Hello from socialchimp"))
+print(result.url)
+```
+
+Need something only that network can do? Same connection, direct access:
+
+```python
+await account.direct.post(
+    "/api/v1/statuses",
+    json={"status": "Hello", "visibility": "unlisted"},
+)
+```
+
+Tokens, retries and rate limits are still handled for you. Only the request
+is yours.
+
+---
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) - from nothing to a post
+- [Networks](docs/platforms.md) - what each one can do, and what it needs
+- [Frameworks](docs/frameworks.md) - ready-made routes for Django,
+  FastAPI and Flask
+- [Adding a platform](docs/adding-a-platform.md) - a network we do not
+  support yet
+- [Plan](docs/PLAN.md) - what is built and what is coming
+- [Changelog](CHANGELOG.md) - what changed, and what it means for you
+- [Releasing](docs/releasing.md) - how a release goes out
+- [Examples](examples/) - runnable programs
+
+## Contributing
+
+Contributions are welcome. A few things to know first:
+
+- **Tests come first.** Write the failing test, then make it pass.
+- **Coverage must stay at 100%.** CI fails below it.
+- **Types must be strict.** `mypy --strict` with no ignores.
+
+```bash
+git clone https://github.com/raghulj/socialchimp
+cd socialchimp
+uv sync --all-extras --dev
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+uv run pytest
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

socialchimp-0.1.0/README.md

@@ -0,0 +1,118 @@
+# socialchimp
+
+[![CI](https://github.com/raghulj/socialchimp/actions/workflows/ci.yml/badge.svg)](https://github.com/raghulj/socialchimp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/socialchimp?color=0b7285)](https://pypi.org/project/socialchimp/)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/socialchimp/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](CONTRIBUTING.md)
+[![Types](https://img.shields.io/badge/types-mypy%20strict-blue)](pyproject.toml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Licence](https://img.shields.io/badge/licence-MIT-black)](LICENSE)
+
+One simple way to connect your app to social networks.
+
+> **Status: 0.1.0, the first release.** All nine networks below work. The way
+> platforms are written is now settled - see
+> [the promise about changes](docs/adding-a-platform.md#what-we-promise-about-changes)
+> before you write your own.
+
+**Mastodon · Bluesky · Facebook Pages · Instagram · YouTube · TikTok · X · Pinterest · Threads**
+
+---
+
+## What it does
+
+Your app needs to let people connect their social accounts, then post for
+them and read what happens. Every network does this differently. socialchimp
+gives you one way to do it, and gets out of the way when you need the network's
+own features.
+
+- **Connect accounts.** Sign in with Mastodon, Bluesky, Facebook, Instagram,
+  YouTube, TikTok, X, Pinterest, Threads and more.
+- **Keep tokens working.** Refresh them before they expire, safely, even when
+  several workers run at once.
+- **Post and read.** Text, pictures, video. Read posts and their numbers back.
+- **Know what happened.** Comments and likes reach you the same way whether the
+  network pushes them to you or we have to check on a timer.
+
+## What it does not do
+
+- **It does not touch your database.** No models, no migrations. You write a
+  small storage class, socialchimp hands you data to save. Your schema stays
+  yours, and it works the same on Django, FastAPI, Flask, or nothing at all.
+- **It does not pretend networks are the same.** Pinterest needs a board.
+  Bluesky cannot schedule. YouTube has no text-only post. Where networks
+  differ, the API says so instead of guessing for you.
+
+---
+
+## Install
+
+```bash
+pip install socialchimp
+```
+
+Add your framework if you want the ready-made routes:
+
+```bash
+pip install "socialchimp[django]"    # or [fastapi], or [flask]
+```
+
+## A first look
+
+```python
+from socialchimp import SocialChimp, Post
+
+sc = SocialChimp(storage=MyStorage())
+
+# Post to a connected account.
+account = sc.account(connection_id)
+result = await account.post(Post(text="Hello from socialchimp"))
+print(result.url)
+```
+
+Need something only that network can do? Same connection, direct access:
+
+```python
+await account.direct.post(
+    "/api/v1/statuses",
+    json={"status": "Hello", "visibility": "unlisted"},
+)
+```
+
+Tokens, retries and rate limits are still handled for you. Only the request
+is yours.
+
+---
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) - from nothing to a post
+- [Networks](docs/platforms.md) - what each one can do, and what it needs
+- [Frameworks](docs/frameworks.md) - ready-made routes for Django,
+  FastAPI and Flask
+- [Adding a platform](docs/adding-a-platform.md) - a network we do not
+  support yet
+- [Plan](docs/PLAN.md) - what is built and what is coming
+- [Changelog](CHANGELOG.md) - what changed, and what it means for you
+- [Releasing](docs/releasing.md) - how a release goes out
+- [Examples](examples/) - runnable programs
+
+## Contributing
+
+Contributions are welcome. A few things to know first:
+
+- **Tests come first.** Write the failing test, then make it pass.
+- **Coverage must stay at 100%.** CI fails below it.
+- **Types must be strict.** `mypy --strict` with no ignores.
+
+```bash
+git clone https://github.com/raghulj/socialchimp
+cd socialchimp
+uv sync --all-extras --dev
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+uv run pytest
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).