daknode-cli 0.1.0__py3-none-any.whl

daknode_cli/__init__.py

@@ -0,0 +1 @@
+"""DakNode CLI. Spec: `.agent/specs/17_agent_toolkit.md#cli`."""

daknode_cli/main.py

@@ -0,0 +1,215 @@
+"""DakNode CLI — the API from a terminal.
+
+Spec: `.agent/specs/17_agent_toolkit.md#cli`.
+
+**Built on `argparse` from the standard library, deliberately.** Click and Typer
+are nicer to write against. They are not the right choice one day after
+`mcp==2.2.0` was installed and silently upgraded `pydantic` from the pinned
+`2.10.4` to `2.13.5`, changing the API's published OpenAPI output. Every
+dependency added here is another chance to move a pin production depends on.
+`argparse` costs some verbosity and cannot move a pin at all.
+
+Every command maps 1:1 onto a published `operationId` — the same rule the MCP
+server follows, so the two surfaces name the same things the same way.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+_SDK = Path(__file__).resolve().parents[1] / "sdk" / "python"
+if str(_SDK) not in sys.path:  # pragma: no cover - import plumbing
+    sys.path.insert(0, str(_SDK))
+
+DEFAULT_BASE_URL = "https://api.daknode.com"
+
+#: Distinguished so a script can tell "the API said no" from "I could not reach
+#: it". Retrying a 422 forever is a different bug from retrying a timeout.
+EXIT_REFUSED = 2
+EXIT_UNREACHABLE = 3
+EXIT_NO_CREDENTIAL = 4
+
+
+class NoCredential(RuntimeError):
+    pass
+
+
+def _client():
+    """Build the SDK client.
+
+    The key comes from the environment and **never from a flag**: argv is
+    visible to every process through `ps`, and shells record it in history.
+    """
+    key = os.environ.get("DAKNODE_API_KEY", "").strip()
+    if not key:
+        raise NoCredential(
+            "DAKNODE_API_KEY is not set. Export it; do not pass it as a flag."
+        )
+    from daknode import AuthenticatedClient
+
+    return AuthenticatedClient(
+        base_url=os.environ.get("DAKNODE_BASE_URL", DEFAULT_BASE_URL).rstrip("/"),
+        token=key,
+    )
+
+
+def _emit(value: Any, fmt: str) -> None:
+    if fmt == "table" and isinstance(value, dict) and "items" in value:
+        rows = value.get("items") or []
+        if not rows:
+            print("(none)")
+            return
+        cols = list(rows[0].keys())[:5]
+        print("  ".join(c.upper() for c in cols))
+        for r in rows:
+            print("  ".join(str(r.get(c, ""))[:38] for c in cols))
+        return
+    print(json.dumps(value, indent=2, default=str))
+
+
+def _unwrap(response) -> tuple[Any, int]:
+    parsed = getattr(response, "parsed", None)
+    status = getattr(response, "status_code", 0)
+    if parsed is not None:
+        body = parsed.to_dict() if hasattr(parsed, "to_dict") else parsed
+        return body, 0
+    raw = (getattr(response, "content", b"") or b"").decode("utf-8", "replace")
+    try:
+        return json.loads(raw), EXIT_REFUSED
+    except ValueError:
+        return {"status": status, "error": raw[:500]}, EXIT_REFUSED
+
+
+# --- commands, each 1:1 with a published operation -------------------------
+
+def cmd_create_inbox(args) -> tuple[Any, int]:
+    from daknode.api.inboxes import create_inbox
+    from daknode.models import InboxCreateRequest
+
+    with _client() as c:
+        return _unwrap(create_inbox.sync_detailed(client=c, body=InboxCreateRequest()))
+
+
+def cmd_list_threads(args) -> tuple[Any, int]:
+    from daknode.api.messages import list_threads
+    from daknode.types import UNSET
+
+    with _client() as c:
+        return _unwrap(list_threads.sync_detailed(
+            inbox_id=args.inbox_id, client=c, limit=args.limit,
+            cursor=args.cursor or UNSET,
+        ))
+
+
+def cmd_list_messages(args) -> tuple[Any, int]:
+    from daknode.api.messages import list_messages
+    from daknode.types import UNSET
+
+    with _client() as c:
+        return _unwrap(list_messages.sync_detailed(
+            inbox_id=args.inbox_id, client=c, limit=args.limit,
+            cursor=args.cursor or UNSET,
+        ))
+
+
+def cmd_get_thread(args) -> tuple[Any, int]:
+    from daknode.api.messages import get_thread
+
+    with _client() as c:
+        return _unwrap(get_thread.sync_detailed(thread_id=args.thread_id, client=c))
+
+
+def cmd_get_message(args) -> tuple[Any, int]:
+    from daknode.api.messages import get_message
+
+    with _client() as c:
+        return _unwrap(get_message.sync_detailed(message_id=args.message_id, client=c))
+
+
+def cmd_search(args) -> tuple[Any, int]:
+    from daknode.api.search import search
+    from daknode.models import SearchRequest
+
+    with _client() as c:
+        return _unwrap(search.sync_detailed(
+            client=c, body=SearchRequest(query=args.query, top_k=args.top_k)
+        ))
+
+
+def cmd_send(args) -> tuple[Any, int]:
+    from daknode.api.send import send
+    from daknode.models import SendRequest
+    from daknode.types import UNSET
+
+    body = SendRequest(
+        inbox_id=args.inbox_id, to=args.to, subject=args.subject,
+        body_text=args.body, thread_id=args.thread_id or UNSET,
+    )
+    if args.dry_run:
+        # A command that emails a real person deserves a way to be inspected
+        # first. Nothing is sent, and the exit code stays 0.
+        return {"dry_run": True, "operation": "send", "body": body.to_dict()}, 0
+    with _client() as c:
+        return _unwrap(send.sync_detailed(client=c, body=body))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="daknode", description="DakNode from a terminal.")
+    p.add_argument("--format", choices=("json", "table"), default="json")
+    sub = p.add_subparsers(dest="resource", required=True)
+
+    inboxes = sub.add_parser("inboxes").add_subparsers(dest="command", required=True)
+    inboxes.add_parser("create").set_defaults(func=cmd_create_inbox, op="create_inbox")
+
+    threads = sub.add_parser("threads").add_subparsers(dest="command", required=True)
+    tl = threads.add_parser("list"); tl.add_argument("--inbox-id", required=True)
+    tl.add_argument("--limit", type=int, default=25); tl.add_argument("--cursor")
+    tl.set_defaults(func=cmd_list_threads, op="list_threads")
+    tg = threads.add_parser("get"); tg.add_argument("thread_id")
+    tg.set_defaults(func=cmd_get_thread, op="get_thread")
+
+    messages = sub.add_parser("messages").add_subparsers(dest="command", required=True)
+    ml = messages.add_parser("list"); ml.add_argument("--inbox-id", required=True)
+    ml.add_argument("--limit", type=int, default=25); ml.add_argument("--cursor")
+    ml.set_defaults(func=cmd_list_messages, op="list_messages")
+    mg = messages.add_parser("get"); mg.add_argument("message_id")
+    mg.set_defaults(func=cmd_get_message, op="get_message")
+
+    se = sub.add_parser("search"); se.add_argument("--query", required=True)
+    se.add_argument("--top-k", type=int, default=10)
+    se.set_defaults(func=cmd_search, op="search", command="search")
+
+    sn = sub.add_parser("send")
+    for flag in ("--inbox-id", "--to", "--subject", "--body"):
+        sn.add_argument(flag, required=True)
+    sn.add_argument("--thread-id", help="reply into this conversation")
+    sn.add_argument("--dry-run", action="store_true",
+                    help="print the request and exit without sending")
+    sn.set_defaults(func=cmd_send, op="send", command="send")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        value, code = args.func(args)
+    except NoCredential as exc:
+        print(f"daknode: {exc}", file=sys.stderr)
+        return EXIT_NO_CREDENTIAL
+    except Exception as exc:  # noqa: BLE001 - a transport failure, not a refusal
+        print(f"daknode: could not reach the API: {exc}", file=sys.stderr)
+        return EXIT_UNREACHABLE
+    if code:
+        print(json.dumps(value, indent=2, default=str), file=sys.stderr)
+        return code
+    _emit(value, args.format)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

daknode_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: daknode-cli
+Version: 0.1.0
+Summary: DakNode's email API from a terminal. JSON to stdout by default.
+Project-URL: Homepage, https://daknode.com
+Project-URL: Documentation, https://daknode.com/developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: daknode<0.2,>=0.1
+
+# DakNode CLI
+
+The API from a terminal. JSON to stdout by default, because the caller is as
+likely to be a script as a person.
+
+## Install
+
+```bash
+pipx install daknode-cli      # or: pip install daknode-cli
+```
+
+Get an API key with the two-request signup at <https://daknode.com/developers>.
+
+```bash
+export DAKNODE_API_KEY=…
+
+daknode inboxes create
+daknode threads list --inbox-id … --limit 10
+daknode threads get <thread_id>
+daknode messages list --inbox-id …
+daknode messages get <message_id>
+daknode search --query "invoice from stripe"
+daknode send --inbox-id … --to … --subject … --body … [--thread-id …]
+```
+
+From a repository checkout, `python -m cli.main` runs the same commands.
+
+`--format table` for reading. `--dry-run` on `send` prints the request and
+exits without sending it — a command that emails a real person deserves a way
+to be inspected first.
+
+## Exit codes
+
+| | |
+| --- | --- |
+| `0` | success |
+| `2` | the API refused the request |
+| `3` | the API could not be reached |
+| `4` | `DAKNODE_API_KEY` is not set |
+
+`2` and `3` are separate on purpose: a script retrying a network failure must
+not retry a `422` forever.
+
+## Two deliberate constraints
+
+**No credential flag.** The key comes from the environment only. argv is visible
+to every process through `ps`, and shells record it in history. A test walks the
+parser and fails if any flag name contains `key` or `token`.
+
+**No third-party dependency.** `argparse` from the standard library, plus the
+first-party generated SDK. Click and Typer are nicer to write against — and one
+day before this was written, installing `mcp` silently upgraded a pinned
+`pydantic` and changed the API's published OpenAPI output. Every dependency here
+is another chance to move a pin production depends on. A test enumerates the
+imports and fails on anything new.
+
+**`send --thread-id` replies into a conversation**; without it the message opens
+a new one in the recipient's client.

daknode_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+daknode_cli/__init__.py,sha256=Fnp2o_AebIG0V_t6uXBfnGMmb6zzw3yHDNJHJYgQ8No,65
+daknode_cli/main.py,sha256=IZ1QOECO9sWwo90VLoF-8COtLEHzwztSPs66OD3inS4,7798
+daknode_cli-0.1.0.dist-info/METADATA,sha256=kMJ-ltWdH0rRU7efhBU0nu6xoys9QSOCkIu3Rrnp2tQ,2289
+daknode_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+daknode_cli-0.1.0.dist-info/entry_points.txt,sha256=9SXrMEBMLMzb-GEVGEaugzSdlrGSOgTZtWHrj_L4-Es,50
+daknode_cli-0.1.0.dist-info/top_level.txt,sha256=Lo1MbBFksaGTXfnRY4_vDZgvd4nqNbZSZ8Cp5fUUuPc,12
+daknode_cli-0.1.0.dist-info/RECORD,,

daknode_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

daknode_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+daknode = daknode_cli.main:main

daknode_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+daknode_cli