amoorion 0.3.0__tar.gz

amoorion-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sett Sarverott
+
+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.

amoorion-0.3.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: amoorion
+Version: 0.3.0
+Summary: Universal tool for administration of chatting and communication platforms
+Author: Sett Sarverott
+Author-email: Sett Sarverott <sett@sarverott.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: fastapi>=0.162.0
+Requires-Dist: mcp[cli]>=2.3.0
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: python-dotenv>=1.2.4
+Requires-Dist: requests>=2.34.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: uvicorn>=0.54.0
+Requires-Dist: pykeepass>=4.2.0 ; extra == 'keepassxc'
+Requires-Python: >=3.12
+Provides-Extra: keepassxc
+Description-Content-Type: text/markdown
+
+# amoorion
+Universal tool for administration of chatting and communication platforms
+
+---
+
+## **EARLY STAGE OF PROJECT**
+
+The core works end to end, with plugins for Bluesky, Mastodon, X, Tumblr,
+Blogger, Facebook, Discord (bot or webhook), Telegram and Matrix, tested
+only against fakes of their APIs so far, not yet against real accounts. `dryrun` sends nothing, for trying.
+Plan: [docs/devlog/VISION.md](docs/devlog/VISION.md).
+
+---
+
+## What it will do
+
+Write once, post everywhere, read and answer from one place, and link it
+with the services around it.
+
+#### Publication platforms
+- twitter (x.com) posting by api
+- bluesky posting
+- tumblr posting by api
+- blogger posting by mail
+- facebook posting
+- mastodon posting
+
+#### Communication platforms
+- discord
+- telegram
+- matrix
+- ~whatsapp~
+- ~signal~
+
+#### Additional functionality
+- email client
+- ~rss feed receiver~
+- ~phone manage by adb~
+- webhooks - standard linkings with services like gitlab, github, discord etc.
+- ntfy notifications
+- nats.io
+
+## How it is built
+
+One core (model, view, controller) and namespaces on it: **plugins** (one
+per platform), **methods** (what amoorion can do), and the faces that expose
+the methods: **CLI**, **HTTP API**, **MCP** server for AI agents, and a
+**daemon** for long-running services. Secrets come only from a **vault**
+(Bitwarden / Vaultwarden, HashiCorp Vault / OpenBao, or a KeePassXC file);
+`.env` holds just the link to it. Each platform is its own package in
+`packages/` (a uv workspace). Details: [docs/structure.md](docs/structure.md), writing a plugin:
+[docs/plugins.md](docs/plugins.md).
+
+## Usage
+
+```sh
+uv sync
+cp example.env .env                          # the link to the vault
+
+uv run amoorion                              # asks step by step what to do (or: amoorion -i)
+uv run amoorion plugins                      # platforms and what they can do
+uv run amoorion accounts                     # which have their secrets in the vault
+uv run amoorion publish --text "hello" --to dryrun bluesky
+uv run amoorion --json read --platform bluesky
+uv run amoorion reply --platform bluesky --to "at://…" --text "thanks"
+uv run amoorion inbox                        # everything read or received so far
+uv run task help                             # help of every command
+
+uv run amoorion api                          # HTTP API on 127.0.0.1:8000
+uv run amoorion mcp                          # MCP server (stdio) for agents
+uv run amoorion daemon                       # long-running services
+```
+
+The API needs the secret `api/token` in the vault (sent as `Authorization:
+Bearer`), and every hook its own secret; without them they refuse calls.
+Where each backend keeps a secret: [docs/structure.md](docs/structure.md#vault).
+Each platform's secrets are listed in its package's README, e.g.
+[packages/amoorion-bluesky](packages/amoorion-bluesky/README.md).
+
+Run locally first; a Dockerfile and compose come next (phase 6 of the plan).
+
+## Development
+
+```sh
+uv run task init               # tools, git hooks, .env, then check
+uv run task check              # tests, YAML, commit messages, docs (= CI)
+uv run task docs:build         # the docs site into docs/_build/html
+uv run task plugin:new -- <platform> <Class> "<description>"   # a new platform
+uv run task test:live -- bluesky mastodon    # one real test post on each platform named
+```
+
+Examples of usage: Jupyter notebooks in [examples/](examples/)
+(`uv run task examples:build` makes marimo notebooks and pages of them). The docs
+(this README, the guides, the plan and an API reference generated from the
+code) are built by Sphinx from [docs/](docs/) for Read the Docs.
+Plan and open questions: [docs/devlog/](docs/devlog/). Guide for agents and
+contributors: [AGENTS.md](AGENTS.md).
+
+## License
+
+Free, under the MIT License, © 2024–present Sett Sarverott:
+[LICENSE](LICENSE), https://sett.mit-license.org

amoorion-0.3.0/README.md

@@ -0,0 +1,102 @@
+# amoorion
+Universal tool for administration of chatting and communication platforms
+
+---
+
+## **EARLY STAGE OF PROJECT**
+
+The core works end to end, with plugins for Bluesky, Mastodon, X, Tumblr,
+Blogger, Facebook, Discord (bot or webhook), Telegram and Matrix, tested
+only against fakes of their APIs so far, not yet against real accounts. `dryrun` sends nothing, for trying.
+Plan: [docs/devlog/VISION.md](docs/devlog/VISION.md).
+
+---
+
+## What it will do
+
+Write once, post everywhere, read and answer from one place, and link it
+with the services around it.
+
+#### Publication platforms
+- twitter (x.com) posting by api
+- bluesky posting
+- tumblr posting by api
+- blogger posting by mail
+- facebook posting
+- mastodon posting
+
+#### Communication platforms
+- discord
+- telegram
+- matrix
+- ~whatsapp~
+- ~signal~
+
+#### Additional functionality
+- email client
+- ~rss feed receiver~
+- ~phone manage by adb~
+- webhooks - standard linkings with services like gitlab, github, discord etc.
+- ntfy notifications
+- nats.io
+
+## How it is built
+
+One core (model, view, controller) and namespaces on it: **plugins** (one
+per platform), **methods** (what amoorion can do), and the faces that expose
+the methods: **CLI**, **HTTP API**, **MCP** server for AI agents, and a
+**daemon** for long-running services. Secrets come only from a **vault**
+(Bitwarden / Vaultwarden, HashiCorp Vault / OpenBao, or a KeePassXC file);
+`.env` holds just the link to it. Each platform is its own package in
+`packages/` (a uv workspace). Details: [docs/structure.md](docs/structure.md), writing a plugin:
+[docs/plugins.md](docs/plugins.md).
+
+## Usage
+
+```sh
+uv sync
+cp example.env .env                          # the link to the vault
+
+uv run amoorion                              # asks step by step what to do (or: amoorion -i)
+uv run amoorion plugins                      # platforms and what they can do
+uv run amoorion accounts                     # which have their secrets in the vault
+uv run amoorion publish --text "hello" --to dryrun bluesky
+uv run amoorion --json read --platform bluesky
+uv run amoorion reply --platform bluesky --to "at://…" --text "thanks"
+uv run amoorion inbox                        # everything read or received so far
+uv run task help                             # help of every command
+
+uv run amoorion api                          # HTTP API on 127.0.0.1:8000
+uv run amoorion mcp                          # MCP server (stdio) for agents
+uv run amoorion daemon                       # long-running services
+```
+
+The API needs the secret `api/token` in the vault (sent as `Authorization:
+Bearer`), and every hook its own secret; without them they refuse calls.
+Where each backend keeps a secret: [docs/structure.md](docs/structure.md#vault).
+Each platform's secrets are listed in its package's README, e.g.
+[packages/amoorion-bluesky](packages/amoorion-bluesky/README.md).
+
+Run locally first; a Dockerfile and compose come next (phase 6 of the plan).
+
+## Development
+
+```sh
+uv run task init               # tools, git hooks, .env, then check
+uv run task check              # tests, YAML, commit messages, docs (= CI)
+uv run task docs:build         # the docs site into docs/_build/html
+uv run task plugin:new -- <platform> <Class> "<description>"   # a new platform
+uv run task test:live -- bluesky mastodon    # one real test post on each platform named
+```
+
+Examples of usage: Jupyter notebooks in [examples/](examples/)
+(`uv run task examples:build` makes marimo notebooks and pages of them). The docs
+(this README, the guides, the plan and an API reference generated from the
+code) are built by Sphinx from [docs/](docs/) for Read the Docs.
+Plan and open questions: [docs/devlog/](docs/devlog/). Guide for agents and
+contributors: [AGENTS.md](AGENTS.md).
+
+## License
+
+Free, under the MIT License, © 2024–present Sett Sarverott:
+[LICENSE](LICENSE), https://sett.mit-license.org

amoorion-0.3.0/pyproject.toml

@@ -0,0 +1,127 @@
+[project]
+name = "amoorion"
+version = "0.3.0"
+description = "Universal tool for administration of chatting and communication platforms"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.162.0",
+    "mcp[cli]>=2.3.0",
+    "pydantic>=2.14.1",
+    "python-dotenv>=1.2.4",
+    "requests>=2.34.2",
+    "rich>=15.0.0",
+    "uvicorn>=0.54.0",
+]
+
+[[project.authors]]
+name = "Sett Sarverott"
+email = "sett@sarverott.com"
+
+[project.scripts]
+amoorion = "amoorion:main"
+
+[project.entry-points."amoorion.plugins"]
+dryrun = "amoorion.plugins.dryrun:DryRun"
+
+[project.optional-dependencies]
+keepassxc = ["pykeepass>=4.2.0"]
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "amoorion-blogger",
+    "amoorion-bluesky",
+    "amoorion-dev",
+    "amoorion-discord",
+    "amoorion-facebook",
+    "amoorion-mastodon",
+    "amoorion-matrix",
+    "amoorion-telegram",
+    "amoorion-tumblr",
+    "amoorion-x",
+    "commitizen>=4.19.3",
+    "go-task-bin>=3.54.0",
+    "httpx>=0.28.1",
+    "ipykernel>=7.4.0",
+    "lefthook>=2.2.2",
+    "nbclient>=0.11.0",
+    "nbformat>=5.11.1",
+    "pykeepass>=4.2.0",
+    "pytest>=9.1.1",
+    "yamllint>=1.38.0",
+]
+examples = ["marimo>=0.25.2"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "uv"
+tag_format = "v$version"
+major_version_zero = true
+version_files = [
+    "packages/amoorion-blogger/pyproject.toml:^version",
+    "packages/amoorion-bluesky/pyproject.toml:^version",
+    "packages/amoorion-discord/pyproject.toml:^version",
+    "packages/amoorion-facebook/pyproject.toml:^version",
+    "packages/amoorion-mastodon/pyproject.toml:^version",
+    "packages/amoorion-matrix/pyproject.toml:^version",
+    "packages/amoorion-telegram/pyproject.toml:^version",
+    "packages/amoorion-tumblr/pyproject.toml:^version",
+    "packages/amoorion-x/pyproject.toml:^version",
+]
+pre_bump_hooks = ["uv lock"]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "packages",
+    "tools",
+]
+addopts = [
+    "--import-mode=importlib",
+    "-m",
+    "not live",
+]
+markers = ["live: posts on a real platform account (task test:live -- <platform>…)"]
+
+[tool.uv.workspace]
+members = [
+    "packages/*",
+    "tools/*",
+    "docs",
+]
+
+[tool.uv.sources.amoorion-bluesky]
+workspace = true
+
+[tool.uv.sources.amoorion-mastodon]
+workspace = true
+
+[tool.uv.sources.amoorion-x]
+workspace = true
+
+[tool.uv.sources.amoorion-tumblr]
+workspace = true
+
+[tool.uv.sources.amoorion-blogger]
+workspace = true
+
+[tool.uv.sources.amoorion-facebook]
+workspace = true
+
+[tool.uv.sources.amoorion-discord]
+workspace = true
+
+[tool.uv.sources.amoorion-telegram]
+workspace = true
+
+[tool.uv.sources.amoorion-matrix]
+workspace = true
+
+[tool.uv.sources.amoorion-dev]
+workspace = true

amoorion-0.3.0/pyproject.toml.orig

@@ -0,0 +1,111 @@
+[project]
+name = "amoorion"
+version = "0.3.0"
+description = "Universal tool for administration of chatting and communication platforms"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Sett Sarverott", email = "sett@sarverott.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.162.0",
+    "mcp[cli]>=2.3.0",
+    "pydantic>=2.14.1",
+    "python-dotenv>=1.2.4",
+    "requests>=2.34.2",
+    "rich>=15.0.0",
+    "uvicorn>=0.54.0",
+]
+
+[project.scripts]
+amoorion = "amoorion:main"
+
+# Platform plugins, found through this group; the packages in packages/ add theirs the same way.
+[project.entry-points."amoorion.plugins"]
+dryrun = "amoorion.plugins.dryrun:DryRun"
+
+[project.optional-dependencies]
+keepassxc = [
+    "pykeepass>=4.2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "amoorion-blogger",
+    "amoorion-bluesky",
+    "amoorion-dev",
+    "amoorion-discord",
+    "amoorion-facebook",
+    "amoorion-mastodon",
+    "amoorion-matrix",
+    "amoorion-telegram",
+    "amoorion-tumblr",
+    "amoorion-x",
+    "commitizen>=4.19.3",
+    "go-task-bin>=3.54.0",
+    "httpx>=0.28.1",
+    "ipykernel>=7.4.0",
+    "lefthook>=2.2.2",
+    "nbclient>=0.11.0",
+    "nbformat>=5.11.1",
+    "pykeepass>=4.2.0",
+    "pytest>=9.1.1",
+    "yamllint>=1.38.0",
+]
+examples = [
+    "marimo>=0.25.2",
+]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "uv"
+tag_format = "v$version"
+# CHANGELOG.md is written by `amoorion-dev version final`, not on every bump.
+major_version_zero = true
+# Every package of the workspace is released with the same version.
+version_files = [
+    "packages/amoorion-blogger/pyproject.toml:^version",
+    "packages/amoorion-bluesky/pyproject.toml:^version",
+    "packages/amoorion-discord/pyproject.toml:^version",
+    "packages/amoorion-facebook/pyproject.toml:^version",
+    "packages/amoorion-mastodon/pyproject.toml:^version",
+    "packages/amoorion-matrix/pyproject.toml:^version",
+    "packages/amoorion-telegram/pyproject.toml:^version",
+    "packages/amoorion-tumblr/pyproject.toml:^version",
+    "packages/amoorion-x/pyproject.toml:^version",
+]
+# uv.lock records the packages' versions too.
+pre_bump_hooks = ["uv lock"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "packages", "tools"]
+# Test modules of several packages may share a name. Live tests post for
+# real: left out unless asked for (task test:live).
+addopts = ["--import-mode=importlib", "-m", "not live"]
+markers = ["live: posts on a real platform account (task test:live -- <platform>…)"]
+
+# Platform plugins, one package each (decision Q10).
+[tool.uv.workspace]
+members = [
+    "packages/*",
+    "tools/*",
+    "docs",
+]
+
+[tool.uv.sources]
+amoorion-bluesky = { workspace = true }
+amoorion-mastodon = { workspace = true }
+amoorion-x = { workspace = true }
+amoorion-tumblr = { workspace = true }
+amoorion-blogger = { workspace = true }
+amoorion-facebook = { workspace = true }
+amoorion-discord = { workspace = true }
+amoorion-telegram = { workspace = true }
+amoorion-matrix = { workspace = true }
+amoorion-dev = { workspace = true }

amoorion-0.3.0/src/amoorion/__init__.py

@@ -0,0 +1,12 @@
+"""amoorion: administration of chatting and communication platforms."""
+
+from importlib.metadata import version
+
+# From the installed package, so the docs, the API and `--version` never lag behind pyproject.toml.
+__version__ = version("amoorion")
+
+
+def main() -> int:
+    from amoorion.cli import main
+
+    return main()

amoorion-0.3.0/src/amoorion/api/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API: the methods and the hooks over HTTP."""
+
+from amoorion.api.base import create_app, serve
+
+__all__ = ["create_app", "serve"]

amoorion-0.3.0/src/amoorion/api/__main__.py

@@ -0,0 +1,5 @@
+from amoorion.cli import main
+
+# Only when run (python -m); importing it, as the API reference does, starts nothing.
+if __name__ == "__main__":
+    raise SystemExit(main(["api"]))

amoorion-0.3.0/src/amoorion/api/base.py

@@ -0,0 +1,87 @@
+"""API: `POST /methods/<name>` with the method's params as the body,
+`POST /hooks/<name>` for incoming webhooks (kept in the inbox), `GET /` for
+what is there.
+
+Method calls need `Authorization: Bearer <api/token from the vault>`; without
+that secret in the vault every method call is refused. Hooks verify
+themselves (see amoorion.hooks).
+"""
+
+import argparse
+import hmac
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from amoorion import __version__
+from amoorion.core import AmoorionError, JsonView
+from amoorion.hooks import HOOKS, Forbidden
+from amoorion.inbox import Inbox
+from amoorion.methods import METHODS, Method
+from amoorion.vault import Vault, open_vault
+
+bearer = HTTPBearer(auto_error=False)
+
+
+def create_app(vault: Vault | None = None, inbox: Inbox | None = None) -> FastAPI:
+    vault = vault or open_vault()
+    inbox = inbox or Inbox()
+    app = FastAPI(title="amoorion", version=__version__)
+
+    def authorized(credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer)]) -> None:
+        try:
+            token = vault.get("api/token")
+        except AmoorionError:
+            raise HTTPException(503, "no api/token in the vault: method calls are off") from None
+        if credentials is None or not hmac.compare_digest(credentials.credentials.encode(), token.encode()):
+            raise HTTPException(401, "wrong or missing bearer token")
+
+    @app.get("/")
+    def index() -> dict[str, Any]:
+        return {"name": "amoorion", "version": __version__, "methods": METHODS.names(), "hooks": HOOKS.names()}
+
+    def add_method(method: type[Method]) -> None:
+        Params = method.Params
+
+        def call(params: Params) -> Any:  # type: ignore[valid-type]
+            try:
+                return JsonView().render(method(vault, inbox=inbox).run(params))
+            except AmoorionError as error:
+                raise HTTPException(400, str(error)) from None
+
+        app.post(
+            f"/methods/{method.name}",
+            summary=method.description,
+            dependencies=[Depends(authorized)],
+            name=method.name,
+        )(call)
+
+    for name in METHODS.names():
+        add_method(METHODS.get(name))
+
+    @app.post("/hooks/{name}")
+    async def hook(name: str, request: Request) -> Any:
+        if name not in HOOKS:
+            raise HTTPException(404, f"no hook named {name!r}")
+        body = await request.body()
+        try:
+            payload = await request.json()
+        except ValueError:
+            raise HTTPException(400, "body is not JSON") from None
+        try:
+            message = HOOKS.get(name)(vault).handle(body, request.headers, payload)
+        except Forbidden as error:
+            raise HTTPException(403, str(error)) from None
+        except AmoorionError as error:
+            raise HTTPException(400, str(error)) from None
+        [kept] = inbox.keep([message])
+        return JsonView().render(kept)
+
+    return app
+
+
+def serve(args: argparse.Namespace) -> None:
+    import uvicorn
+
+    uvicorn.run(create_app(), host=args.host, port=args.port)

amoorion-0.3.0/src/amoorion/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command line: one subcommand per method, plus the servers."""
+
+from amoorion.cli.base import RichView, build_parser, main
+
+__all__ = ["RichView", "build_parser", "main"]

amoorion-0.3.0/src/amoorion/cli/__main__.py

@@ -0,0 +1,5 @@
+from amoorion.cli.base import main
+
+# Only when run (python -m); importing it, as the API reference does, starts nothing.
+if __name__ == "__main__":
+    raise SystemExit(main())