notefeed 0.2.0__tar.gz

notefeed-0.2.0/.gitignore

@@ -0,0 +1,60 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# superpowers scratch
+/.superpowers/
+/.playwright-mcp/
+!.env.example
+
+# Superpowers specs/plans are local working notes; decisions are recorded as ADRs (/ccp:ship-pr).
+/docs/superpowers/
+/site/
+/.venv-docs/
+/data/
+/.dev/
+
+# Client packages
+/packages/python/dist/
+__pycache__/
+*.egg-info/
+/packages/js/dist/
+/packages/js/node_modules/

notefeed-0.2.0/LICENSE

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

notefeed-0.2.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: notefeed
+Version: 0.2.0
+Summary: Post markdown notes to a notefeed server, from Python or the command line.
+Project-URL: Documentation, https://marceltov.github.io/notefeed/clients/
+Project-URL: Source, https://github.com/Marceltov/notefeed
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=9; extra == 'test'
+Description-Content-Type: text/markdown
+
+# notefeed
+
+Post markdown notes to a [notefeed](https://github.com/Marceltov/notefeed) server from Python or the command line. No dependencies.
+
+```sh
+pip install notefeed
+export NOTEFEED_URL=https://notes.example.com NOTEFEED_TOKEN=...
+notefeed post "# Backup finished"
+backup.sh 2>&1 | notefeed post -
+```
+
+```python
+from notefeed import Client
+
+client = Client("https://notes.example.com", token)  # URL and token set once
+print(client.post("# Deploy done\nversion 1.4.2").url)
+```
+
+The `notefeed` command reads `--url` / `--token`, or `NOTEFEED_URL` / `NOTEFEED_TOKEN`. The library itself never reads the environment.
+
+Full documentation: https://marceltov.github.io/notefeed/clients/

notefeed-0.2.0/README.md

@@ -0,0 +1,21 @@
+# notefeed
+
+Post markdown notes to a [notefeed](https://github.com/Marceltov/notefeed) server from Python or the command line. No dependencies.
+
+```sh
+pip install notefeed
+export NOTEFEED_URL=https://notes.example.com NOTEFEED_TOKEN=...
+notefeed post "# Backup finished"
+backup.sh 2>&1 | notefeed post -
+```
+
+```python
+from notefeed import Client
+
+client = Client("https://notes.example.com", token)  # URL and token set once
+print(client.post("# Deploy done\nversion 1.4.2").url)
+```
+
+The `notefeed` command reads `--url` / `--token`, or `NOTEFEED_URL` / `NOTEFEED_TOKEN`. The library itself never reads the environment.
+
+Full documentation: https://marceltov.github.io/notefeed/clients/

notefeed-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "notefeed"
+version = "0.2.0"
+description = "Post markdown notes to a notefeed server, from Python or the command line."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Topic :: Communications",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=9"]
+
+[project.scripts]
+notefeed = "notefeed.cli:main"
+
+[project.urls]
+Documentation = "https://marceltov.github.io/notefeed/clients/"
+Source = "https://github.com/Marceltov/notefeed"

notefeed-0.2.0/src/notefeed/__init__.py

@@ -0,0 +1,9 @@
+"""Post markdown notes to a notefeed server."""
+
+from importlib.metadata import version as _version
+
+__version__ = _version("notefeed")
+
+from .client import AuthError, Client, ConfigError, InvalidNoteError, Note, NotefeedError, NoteTooLargeError  # noqa: E402
+
+__all__ = ["AuthError", "Client", "ConfigError", "InvalidNoteError", "Note", "NotefeedError", "NoteTooLargeError"]

notefeed-0.2.0/src/notefeed/cli.py

@@ -0,0 +1,63 @@
+"""`notefeed post ...` — post a note from the command line."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .client import Client, ConfigError, NotefeedError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="notefeed", description="Post markdown notes to notefeed.")
+    parser.add_argument("--version", action="version", version=f"notefeed {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("post", help="post a note; prints its URL")
+    p.add_argument("text", nargs="?", help='the markdown, or "-" to read stdin')
+    p.add_argument("--file", help="read the markdown from this file")
+    p.add_argument("--url", help="notefeed base URL (default: $NOTEFEED_URL)")
+    p.add_argument("--token", help="API token (default: $NOTEFEED_TOKEN)")
+    args = parser.parse_args(argv)
+
+    try:
+        markdown = _read(args)
+        url = args.url or os.environ.get("NOTEFEED_URL")
+        token = args.token or os.environ.get("NOTEFEED_TOKEN")
+        if not url:
+            raise _UsageError("no URL given; pass --url or set NOTEFEED_URL")
+        if not token:
+            raise _UsageError("no token given; pass --token or set NOTEFEED_TOKEN")
+        note = Client(url, token).post(markdown)
+    except (ConfigError, _UsageError) as e:
+        print(f"notefeed: {e}", file=sys.stderr)
+        return 2
+    except NotefeedError as e:
+        print(f"notefeed: {e}", file=sys.stderr)
+        return 1
+    print(note.url)
+    return 0
+
+
+class _UsageError(Exception):
+    pass
+
+
+def _read(args: argparse.Namespace) -> str:
+    if args.file:
+        try:
+            with open(args.file, "rb") as f:
+                return f.read().decode("utf-8")
+        except OSError as e:
+            raise _UsageError(f"cannot read {args.file}: {e.strerror}") from None
+        except UnicodeDecodeError:
+            raise _UsageError(f"{args.file} is not UTF-8") from None
+    if args.text == "-":
+        try:
+            return sys.stdin.buffer.read().decode("utf-8")
+        except UnicodeDecodeError:
+            raise _UsageError("stdin is not UTF-8") from None
+    if args.text is None:
+        raise _UsageError('give the note text, "-" for stdin, or --file PATH')
+    return args.text

notefeed-0.2.0/src/notefeed/client.py

@@ -0,0 +1,93 @@
+"""A tiny client for notefeed's POST /api/notes. Standard library only."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Note:
+    id: str
+    url: str
+
+
+class NotefeedError(Exception):
+    """Any failure talking to notefeed. `status` is the HTTP status, or None (network, config)."""
+
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+class ConfigError(NotefeedError):
+    """URL or token missing."""
+
+
+class InvalidNoteError(NotefeedError):
+    """The server rejected the note (400, 415): empty, not UTF-8, wrong type."""
+
+
+class AuthError(NotefeedError):
+    """Missing or wrong token (401)."""
+
+
+class NoteTooLargeError(NotefeedError):
+    """The note is over the server's size limit (413)."""
+
+
+_ERRORS = {400: InvalidNoteError, 415: InvalidNoteError, 401: AuthError, 413: NoteTooLargeError}
+
+
+class Client:
+    """A notefeed server. URL and token are set once here; post() takes only the note."""
+
+    def __init__(self, url: str, token: str, timeout: float = 10.0):
+        if not url:
+            raise ConfigError("no url given")
+        if not (token or "").strip():
+            raise ConfigError("no token given")
+        self.url = url.rstrip("/")
+        self.token = token.strip()
+        if re.search(r"[\x00-\x1f\x7f]", self.token):
+            # Never echo the value: it would end up in terminals and CI logs.
+            raise ConfigError("token contains invalid characters")
+        self.timeout = timeout
+
+    def post(self, markdown: str) -> Note:
+        req = urllib.request.Request(
+            f"{self.url}/api/notes",
+            data=markdown.encode("utf-8"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "text/markdown; charset=utf-8",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                status, text = res.status, res.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            raise _http_error(e) from None
+        except (urllib.error.URLError, http.client.HTTPException, OSError) as e:
+            reason = getattr(e, "reason", e)
+            raise NotefeedError(f"could not reach {self.url}: {reason}") from None
+        try:
+            data = json.loads(text)
+            return Note(id=data["id"], url=data["url"])
+        except (ValueError, KeyError, TypeError):
+            raise NotefeedError(f"unexpected response from {self.url} (not a notefeed server?)", status=status) from None
+
+
+def _http_error(e: urllib.error.HTTPError) -> NotefeedError:
+    text = e.read().decode("utf-8", errors="replace")
+    try:
+        message = json.loads(text)["error"]
+    except (ValueError, KeyError, TypeError):
+        message = f"HTTP {e.code}: {' '.join(text[:200].split())}"
+    return _ERRORS.get(e.code, NotefeedError)(message, status=e.code)
+

notefeed-0.2.0/tests/conftest.py

@@ -0,0 +1,49 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+
+class FakeServer:
+    """A local HTTP server that records requests and answers with queued replies."""
+
+    def __init__(self):
+        self.requests = []
+        self.replies = []
+        fake = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                body = self.rfile.read(int(self.headers.get("Content-Length") or 0))
+                fake.requests.append({"method": "POST", "path": self.path, "headers": dict(self.headers), "body": body})
+                status, payload, ctype = fake.replies.pop(0) if fake.replies else (201, {"id": "i", "url": "u"}, "application/json")
+                data = payload.encode() if isinstance(payload, str) else json.dumps(payload).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", ctype)
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def log_message(self, *args):
+                pass
+
+        self.httpd = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.url = f"http://127.0.0.1:{self.httpd.server_port}"
+        threading.Thread(target=self.httpd.serve_forever, kwargs={"poll_interval": 0.05}, daemon=True).start()
+
+    def reply(self, status, payload, ctype="application/json"):
+        self.replies.append((status, payload, ctype))
+
+
+@pytest.fixture
+def server():
+    s = FakeServer()
+    yield s
+    s.httpd.shutdown()
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    monkeypatch.delenv("NOTEFEED_URL", raising=False)
+    monkeypatch.delenv("NOTEFEED_TOKEN", raising=False)

notefeed-0.2.0/tests/test_cli.py

@@ -0,0 +1,103 @@
+import io
+import sys
+
+from notefeed.cli import main
+
+
+def test_post_text_prints_url(server, capsys):
+    server.reply(201, {"id": "i", "url": "https://n.example/n/i"})
+    assert main(["post", "hi", "--url", server.url, "--token", "t"]) == 0
+    assert capsys.readouterr().out.strip() == "https://n.example/n/i"
+    assert server.requests[0]["body"] == b"hi"
+
+
+def test_post_stdin(server, monkeypatch):
+    monkeypatch.setattr(sys, "stdin", io.TextIOWrapper(io.BytesIO("# from stdin\r\nCafé\n".encode())))
+    assert main(["post", "-", "--url", server.url, "--token", "t"]) == 0
+    assert server.requests[0]["body"] == "# from stdin\r\nCafé\n".encode()
+
+
+def test_post_file(server, tmp_path):
+    f = tmp_path / "note.md"
+    f.write_bytes("# File\r\nbody\n".encode())
+    assert main(["post", "--file", str(f), "--url", server.url, "--token", "t"]) == 0
+    assert server.requests[0]["body"] == b"# File\r\nbody\n"
+
+
+def test_missing_file_exits_2(capsys, tmp_path):
+    assert main(["post", "--file", str(tmp_path / "nope.md"), "--url", "http://x", "--token", "t"]) == 2
+    assert capsys.readouterr().err.startswith("notefeed: ")
+
+
+def test_no_text_exits_2_without_reading_stdin(capsys):
+    assert main(["post", "--url", "http://x", "--token", "t"]) == 2
+    assert "notefeed: " in capsys.readouterr().err
+
+
+def test_no_config_exits_2(capsys):
+    assert main(["post", "hi"]) == 2
+    assert "NOTEFEED_URL" in capsys.readouterr().err
+
+
+def test_server_error_exits_1(server, capsys):
+    server.reply(401, {"error": "missing or wrong bearer token"})
+    assert main(["post", "hi", "--url", server.url, "--token", "bad"]) == 1
+    assert capsys.readouterr().err.strip() == "notefeed: missing or wrong bearer token"
+
+
+def test_connection_refused_exits_1_one_line(capsys):
+    assert main(["post", "hi", "--url", "http://127.0.0.1:1", "--token", "t"]) == 1
+    err = capsys.readouterr().err
+    assert err.startswith("notefeed: ") and err.count("\n") == 1
+
+
+def test_version(capsys):
+    try:
+        main(["--version"])
+    except SystemExit as e:
+        assert e.code == 0
+    import notefeed
+
+    assert capsys.readouterr().out.strip() == f"notefeed {notefeed.__version__}"
+
+
+def test_file_not_utf8_exits_2(server, capsys, tmp_path):
+    f = tmp_path / "latin1.md"
+    f.write_bytes(b"# Caf\xe9\n")
+    assert main(["post", "--file", str(f), "--url", server.url, "--token", "t"]) == 2
+    assert "not UTF-8" in capsys.readouterr().err
+    assert server.requests == []
+
+
+def test_stdin_not_utf8_exits_2(server, capsys, monkeypatch):
+    monkeypatch.setattr(sys, "stdin", io.TextIOWrapper(io.BytesIO(b"# Caf\xe9\n")))
+    assert main(["post", "-", "--url", server.url, "--token", "t"]) == 2
+    assert "not UTF-8" in capsys.readouterr().err
+    assert server.requests == []
+
+
+def test_list_item_text(server):
+    assert main(["post", "- buy milk", "--url", server.url, "--token", "t"]) == 0
+    assert server.requests[0]["body"] == b"- buy milk"
+
+
+def test_env_vars(server, monkeypatch):
+    monkeypatch.setenv("NOTEFEED_URL", server.url)
+    monkeypatch.setenv("NOTEFEED_TOKEN", "envtok")
+    assert main(["post", "- buy milk"]) == 0
+    req = server.requests[0]
+    assert req["headers"]["Authorization"] == "Bearer envtok"
+    assert req["body"] == b"- buy milk"
+
+
+def test_flags_win_over_env(server, monkeypatch):
+    monkeypatch.setenv("NOTEFEED_URL", "http://127.0.0.1:1")
+    monkeypatch.setenv("NOTEFEED_TOKEN", "envtok")
+    assert main(["post", "hi", "--url", server.url, "--token", "argtok"]) == 0
+    assert server.requests[0]["headers"]["Authorization"] == "Bearer argtok"
+
+
+def test_no_token_names_flag_and_env(capsys):
+    assert main(["post", "hi", "--url", "http://x"]) == 2
+    err = capsys.readouterr().err
+    assert "--token" in err and "NOTEFEED_TOKEN" in err

notefeed-0.2.0/tests/test_client.py

@@ -0,0 +1,120 @@
+import pytest
+
+from notefeed import AuthError, Client, ConfigError, InvalidNoteError, Note, NotefeedError, NoteTooLargeError
+
+
+def test_post_sends_markdown_and_returns_note(server):
+    server.reply(201, {"id": "20260930T100000Z-cafe", "url": "https://n.example/n/20260930T100000Z-cafe"})
+    note = Client(server.url, "t").post("# Café\r\nx")
+    assert note == Note("20260930T100000Z-cafe", "https://n.example/n/20260930T100000Z-cafe")
+    req = server.requests[0]
+    assert req["path"] == "/api/notes"
+    assert req["headers"]["Authorization"] == "Bearer t"
+    assert req["headers"]["Content-Type"] == "text/markdown; charset=utf-8"
+    assert req["body"] == "# Café\r\nx".encode()
+
+
+def test_trailing_slash_and_subpath(server):
+    Client(server.url + "/sub/", "t").post("x")
+    assert server.requests[0]["path"] == "/sub/api/notes"
+
+
+def test_ignores_environment(server, monkeypatch):
+    # The library takes url and token from code only; env vars are the CLI's business.
+    monkeypatch.setenv("NOTEFEED_URL", "http://127.0.0.1:1")
+    monkeypatch.setenv("NOTEFEED_TOKEN", "envtok")
+    Client(server.url, "argtok").post("x")
+    assert server.requests[0]["headers"]["Authorization"] == "Bearer argtok"
+    with pytest.raises(ConfigError):
+        Client("", "")
+
+
+def test_missing_url_or_token():
+    with pytest.raises(ConfigError, match="url") as e:
+        Client("", "t")
+    assert e.value.status is None
+    with pytest.raises(ConfigError, match="token"):
+        Client("http://x", "")
+    with pytest.raises(TypeError):
+        Client()  # both are required arguments
+
+
+def test_no_module_level_post():
+    import notefeed
+
+    assert not hasattr(notefeed, "post")
+
+
+@pytest.mark.parametrize(
+    ("status", "error"),
+    [(400, InvalidNoteError), (415, InvalidNoteError), (401, AuthError), (413, NoteTooLargeError), (500, NotefeedError)],
+)
+def test_error_mapping(server, status, error):
+    server.reply(status, {"error": f"reason {status}"})
+    with pytest.raises(NotefeedError) as e:
+        Client(server.url, "t").post("x")
+    assert type(e.value) is error
+    assert e.value.status == status
+    assert str(e.value) == f"reason {status}"
+
+
+def test_non_json_error_body(server):
+    server.reply(502, "<html>bad gateway</html>", "text/html")
+    with pytest.raises(NotefeedError) as e:
+        Client(server.url, "t").post("x")
+    assert type(e.value) is NotefeedError
+    assert e.value.status == 502
+    assert "502" in str(e.value)
+
+
+def test_connection_refused():
+    with pytest.raises(NotefeedError) as e:
+        Client("http://127.0.0.1:1", "t").post("x")
+    assert e.value.status is None
+
+
+def test_non_json_success_body(server):
+    server.reply(200, "<html>some other site</html>", "text/html")
+    with pytest.raises(NotefeedError) as e:
+        Client(server.url, "t").post("x")
+    assert type(e.value) is NotefeedError
+    assert e.value.status == 200
+    assert "not a notefeed" in str(e.value)
+
+
+def test_token_whitespace_stripped(server):
+    Client(server.url, "tok\r\n").post("x")
+    assert server.requests[0]["headers"]["Authorization"] == "Bearer tok"
+
+
+def test_token_control_chars_rejected_without_echo():
+    with pytest.raises(ConfigError) as e:
+        Client("http://x", "sec\nret")
+    assert "invalid characters" in str(e.value)
+    assert "sec" not in str(e.value) and "ret" not in str(e.value)
+
+
+def test_non_http_reply():
+    import socket
+    import threading
+
+    srv = socket.create_server(("127.0.0.1", 0))
+
+    def banner():
+        conn, _ = srv.accept()
+        conn.recv(65536)
+        conn.sendall(b"SSH-2.0-OpenSSH_9.6\r\n")
+        conn.close()
+
+    threading.Thread(target=banner, daemon=True).start()
+    with pytest.raises(NotefeedError) as e:
+        Client(f"http://127.0.0.1:{srv.getsockname()[1]}", "t").post("x")
+    assert e.value.status is None
+    srv.close()
+
+
+def test_html_error_body_collapsed(server):
+    server.reply(502, "<html>\n  <body>bad gateway</body>\n</html>\n", "text/html")
+    with pytest.raises(NotefeedError) as e:
+        Client(server.url, "t").post("x")
+    assert str(e.value) == "HTTP 502: <html> <body>bad gateway</body> </html>"

notefeed-0.2.0/tests/test_version.py

@@ -0,0 +1,18 @@
+import json
+from pathlib import Path
+
+import pytest
+
+import notefeed
+
+
+def test_version_matches_pyproject():
+    toml = (Path(__file__).parents[1] / "pyproject.toml").read_text()
+    assert f'\nversion = "{notefeed.__version__}"\n' in toml
+
+
+def test_matches_js_package():
+    pkg = Path(__file__).parents[2] / "js" / "package.json"
+    if not pkg.exists():
+        pytest.skip("JS package not present")
+    assert json.loads(pkg.read_text())["version"] == notefeed.__version__