flowbase-cli 0.1.0__py3-none-any.whl

flowbase_cli/__init__.py

@@ -0,0 +1,3 @@
+"""FlowBase OpenAPI CLI."""
+
+__version__ = "0.1.0"

flowbase_cli/endpoints.py

@@ -0,0 +1,37 @@
+"""CLI endpoint catalog, contract-tested against the server OpenAPI schema."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    key: str
+    operation_id: str
+    method: str
+    path: str
+    scope: str
+    summary: str
+    example: str
+    requires_confirmation: bool = False
+
+
+ENDPOINTS = (
+    Endpoint("objects.list", "flowbase_objects_list", "GET", "/objects", "metadata:read", "List object metadata.", "flowbase objects list"),
+    Endpoint("objects.get", "flowbase_objects_get", "GET", "/objects/{object_id}", "metadata:read", "Get object and field metadata.", "flowbase objects get obj_xxx"),
+    Endpoint("objects.create", "flowbase_objects_create", "POST", "/objects", "metadata:write", "Create an object draft.", "flowbase objects create --json-file object.json"),
+    Endpoint("objects.update", "flowbase_objects_update", "PUT", "/objects/{object_id}", "metadata:write", "Update an object draft.", "flowbase objects update obj_xxx --label Customer --description 'Customer records'"),
+    Endpoint("objects.delete", "flowbase_objects_delete", "DELETE", "/objects/{object_id}", "metadata:write", "Logically delete an object.", "flowbase objects delete obj_xxx --yes", True),
+    Endpoint("objects.restore", "flowbase_objects_restore", "POST", "/objects/{object_id}/restore", "metadata:write", "Restore an object.", "flowbase objects restore obj_xxx --yes", True),
+    Endpoint("fields.create", "flowbase_fields_create", "POST", "/objects/{object_id}/fields", "metadata:write", "Create a field draft.", "flowbase fields create obj_xxx --json-file field.json"),
+    Endpoint("fields.update", "flowbase_fields_update", "PUT", "/objects/{object_id}/fields/{field_id}", "metadata:write", "Update a field draft.", "flowbase fields update obj_xxx fld_xxx --label Name --description 'Customer name'"),
+    Endpoint("fields.delete", "flowbase_fields_delete", "DELETE", "/objects/{object_id}/fields/{field_id}", "metadata:write", "Logically delete a field.", "flowbase fields delete obj_xxx fld_xxx --yes", True),
+    Endpoint("fields.restore", "flowbase_fields_restore", "POST", "/objects/{object_id}/fields/{field_id}/restore", "metadata:write", "Restore a field.", "flowbase fields restore obj_xxx fld_xxx --yes", True),
+    Endpoint("records.list", "flowbase_records_list", "GET", "/objects/{object_id}/records", "records:read", "List records.", "flowbase records list obj_xxx --page 1"),
+    Endpoint("records.get", "flowbase_records_get", "GET", "/objects/{object_id}/records/{record_id}", "records:read", "Get a record.", "flowbase records get obj_xxx rec_xxx"),
+    Endpoint("records.create", "flowbase_records_create", "POST", "/objects/{object_id}/records", "records:write", "Create a record.", "flowbase records create obj_xxx --json-file record.json"),
+    Endpoint("records.update", "flowbase_records_update", "PUT", "/objects/{object_id}/records/{record_id}", "records:write", "Replace active field values on a record.", "flowbase records update obj_xxx rec_xxx --json-file record.json"),
+    Endpoint("records.delete", "flowbase_records_delete", "DELETE", "/objects/{object_id}/records/{record_id}", "records:write", "Delete a record.", "flowbase records delete obj_xxx rec_xxx --yes", True),
+)
+
+ENDPOINT_BY_KEY = {endpoint.key: endpoint for endpoint in ENDPOINTS}

flowbase_cli/main.py

@@ -0,0 +1,362 @@
+"""Command line client for the FlowBase OpenAPI."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+from flowbase_cli.endpoints import ENDPOINTS, ENDPOINT_BY_KEY, Endpoint
+
+DEFAULT_HOST = "http://flowbase.localhost:5001"
+API_PREFIX = "/api/openapi/v1"
+ENV_HOST = "FLOWBASE_HOST"
+ENV_API_KEY = "FLOWBASE_API_KEY"
+
+
+class CliError(Exception):
+    """Expected user-facing CLI failure."""
+
+
+def api_root(host: str) -> str:
+    normalized = host.strip().rstrip("/")
+    if not normalized:
+        raise CliError("Host cannot be empty.")
+    if normalized.endswith(API_PREFIX):
+        return normalized
+    return f"{normalized}{API_PREFIX}"
+
+
+def get_endpoint(key: str) -> Endpoint:
+    try:
+        return ENDPOINT_BY_KEY[key]
+    except KeyError as exc:
+        raise CliError(f"Unknown endpoint: {key}") from exc
+
+
+def load_json_payload(json_text: str | None, json_file: str | None) -> dict[str, Any]:
+    if json_text and json_file:
+        raise CliError("--json and --json-file cannot be used together.")
+    if not json_text and not json_file:
+        return {}
+    try:
+        source = Path(json_file).read_text(encoding="utf-8") if json_file else (json_text or "{}")
+    except OSError as exc:
+        raise CliError(f"Cannot read JSON file: {exc}") from exc
+    try:
+        payload = json.loads(source)
+    except json.JSONDecodeError as exc:
+        raise CliError(f"Invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise CliError("JSON payload must be an object.")
+    return payload
+
+
+def require_fields(payload: dict[str, Any], *names: str) -> None:
+    missing = [name for name in names if name not in payload or payload[name] is None]
+    if missing:
+        raise CliError(f"Missing request field(s): {', '.join(missing)}")
+
+
+class OpenApiClient:
+    def __init__(self, host: str, api_key: str | None) -> None:
+        self.root = api_root(host)
+        self.api_key = api_key
+
+    def build_url(
+        self,
+        endpoint: Endpoint,
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> str:
+        path = endpoint.path
+        values = path_params or {}
+        for name in _path_parameter_names(endpoint.path):
+            if name not in values:
+                raise CliError(f"Missing path parameter: {name}")
+            path = path.replace("{" + name + "}", quote(str(values[name]), safe=""))
+        clean_query = {key: value for key, value in (query or {}).items() if value is not None}
+        suffix = f"?{urlencode(clean_query, doseq=True)}" if clean_query else ""
+        return f"{self.root}{path}{suffix}"
+
+    def request(
+        self,
+        endpoint_key: str,
+        *,
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> bytes:
+        endpoint = get_endpoint(endpoint_key)
+        if not self.api_key:
+            raise CliError(f"Missing API key. Set {ENV_API_KEY} or pass --api-key.")
+        url = self.build_url(endpoint, path_params, query)
+        headers = {"Accept": "application/json", "Authorization": f"Bearer {self.api_key}"}
+        data = None
+        if body is not None:
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        request = Request(url, data=data, headers=headers, method=endpoint.method)
+        try:
+            with urlopen(request) as response:  # noqa: S310 - the user selects the FlowBase host.
+                return response.read()
+        except HTTPError as exc:
+            payload = exc.read().decode("utf-8", errors="replace")
+            raise CliError(f"HTTP {exc.code} for {endpoint.key}: {_error_detail(payload)}") from exc
+        except URLError as exc:
+            raise CliError(f"Failed to connect to {url}: {exc.reason}") from exc
+
+
+def _path_parameter_names(path: str) -> list[str]:
+    return [part[1:-1] for part in path.split("/") if part.startswith("{") and part.endswith("}")]
+
+
+def _error_detail(payload: str) -> str:
+    try:
+        parsed = json.loads(payload)
+    except json.JSONDecodeError:
+        return payload or "empty response"
+    if isinstance(parsed, dict) and "detail" in parsed:
+        detail = parsed["detail"]
+        return detail if isinstance(detail, str) else json.dumps(detail, ensure_ascii=False)
+    return json.dumps(parsed, ensure_ascii=False)
+
+
+def print_output(data: bytes, *, pretty: bool, raw: bool) -> None:
+    text = data.decode("utf-8", errors="replace")
+    if raw:
+        print(text, end="" if text.endswith("\n") else "\n")
+        return
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        print(text, end="" if text.endswith("\n") else "\n")
+        return
+    indent = 2 if pretty else None
+    separators = None if pretty else (",", ":")
+    print(json.dumps(parsed, ensure_ascii=False, indent=indent, separators=separators))
+
+
+def confirm_change(endpoint: Endpoint, yes: bool) -> None:
+    if not endpoint.requires_confirmation or yes:
+        return
+    if not sys.stdin.isatty():
+        raise CliError("Refusing a state-changing command in non-interactive mode without --yes.")
+    answer = input(f"{endpoint.summary} Continue? [y/N] ").strip().lower()
+    if answer not in {"y", "yes"}:
+        raise CliError("Cancelled.")
+
+
+def client_from_args(args: argparse.Namespace) -> OpenApiClient:
+    host = args.host or os.getenv(ENV_HOST) or DEFAULT_HOST
+    api_key = args.api_key or os.getenv(ENV_API_KEY)
+    return OpenApiClient(host, api_key)
+
+
+def run_request(
+    args: argparse.Namespace,
+    endpoint_key: str,
+    *,
+    path_params: dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+) -> int:
+    endpoint = get_endpoint(endpoint_key)
+    confirm_change(endpoint, getattr(args, "yes", False))
+    data = client_from_args(args).request(endpoint_key, path_params=path_params, query=query, body=body)
+    print_output(data, pretty=args.pretty, raw=args.raw)
+    return 0
+
+
+def handle_docs(args: argparse.Namespace) -> int:
+    if args.docs_action == "list":
+        payload = [
+            {"key": e.key, "operationId": e.operation_id, "method": e.method, "path": e.path, "scope": e.scope, "summary": e.summary}
+            for e in ENDPOINTS
+        ]
+        print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+        return 0
+    endpoint = get_endpoint(args.endpoint)
+    payload = {
+        "key": endpoint.key,
+        "operationId": endpoint.operation_id,
+        "method": endpoint.method,
+        "path": endpoint.path,
+        "scope": endpoint.scope,
+        "summary": endpoint.summary,
+        "requiresConfirmation": endpoint.requires_confirmation,
+        "example": endpoint.example,
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+    return 0
+
+
+def _payload_from_args(args: argparse.Namespace, direct: dict[str, Any], required: tuple[str, ...]) -> dict[str, Any]:
+    payload = load_json_payload(args.json, args.json_file)
+    payload.update({key: value for key, value in direct.items() if value is not None})
+    require_fields(payload, *required)
+    return payload
+
+
+def handle_objects(args: argparse.Namespace) -> int:
+    action = args.objects_action
+    if action == "list":
+        return run_request(args, "objects.list", query={"status": args.status})
+    if action == "get":
+        return run_request(args, "objects.get", path_params={"object_id": args.object_id}, query={"status": args.status})
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {"label": args.label, "key": args.key, "description": args.description},
+            ("label", "key", "description"),
+        )
+        return run_request(args, "objects.create", body=body)
+    if action == "update":
+        body = _payload_from_args(args, {"label": args.label, "description": args.description}, ("label", "description"))
+        return run_request(args, "objects.update", path_params={"object_id": args.object_id}, body=body)
+    return run_request(args, f"objects.{action}", path_params={"object_id": args.object_id})
+
+
+def handle_fields(args: argparse.Namespace) -> int:
+    action = args.fields_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "field_id"):
+        path["field_id"] = args.field_id
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {"label": args.label, "key": args.key, "description": args.description},
+            ("label", "key", "description"),
+        )
+        return run_request(args, "fields.create", path_params=path, body=body)
+    if action == "update":
+        body = _payload_from_args(args, {"label": args.label, "description": args.description}, ("label", "description"))
+        return run_request(args, "fields.update", path_params=path, body=body)
+    return run_request(args, f"fields.{action}", path_params=path)
+
+
+def handle_records(args: argparse.Namespace) -> int:
+    action = args.records_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "record_id"):
+        path["record_id"] = args.record_id
+    if action == "list":
+        return run_request(args, "records.list", path_params=path, query={"page": args.page})
+    if action == "get" or action == "delete":
+        return run_request(args, f"records.{action}", path_params=path)
+    body = load_json_payload(args.json, args.json_file)
+    require_fields(body, "values")
+    if not isinstance(body["values"], dict):
+        raise CliError("Request field 'values' must be an object.")
+    return run_request(args, f"records.{action}", path_params=path, body=body)
+
+
+def add_json_args(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--json", help="Request body as a JSON object.")
+    group.add_argument("--json-file", help="Read the request body from a UTF-8 JSON file.")
+
+
+def add_object_fields(parser: argparse.ArgumentParser, *, include_key: bool) -> None:
+    parser.add_argument("--label")
+    if include_key:
+        parser.add_argument("--key")
+    parser.add_argument("--description")
+    add_json_args(parser)
+
+
+def add_yes(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--yes", action="store_true", help="Skip the interactive confirmation.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="flowbase", description="FlowBase OpenAPI CLI")
+    parser.add_argument("--host", help=f"Environment Base URL. Defaults to ${ENV_HOST} or {DEFAULT_HOST}.")
+    parser.add_argument("--api-key", help=f"API key. Defaults to ${ENV_API_KEY}.")
+    parser.add_argument("--pretty", action=argparse.BooleanOptionalAction, default=True, help="Pretty-print JSON output.")
+    parser.add_argument("--raw", action="store_true", help="Print the response body without JSON formatting.")
+    groups = parser.add_subparsers(dest="group", required=True)
+
+    docs = groups.add_parser("docs", help="Inspect the offline endpoint catalog.")
+    docs_actions = docs.add_subparsers(dest="docs_action", required=True)
+    docs_actions.add_parser("list")
+    docs_show = docs_actions.add_parser("show")
+    docs_show.add_argument("endpoint", choices=sorted(ENDPOINT_BY_KEY))
+    docs.set_defaults(handler=handle_docs)
+
+    objects = groups.add_parser("objects", help="Manage object metadata.")
+    object_actions = objects.add_subparsers(dest="objects_action", required=True)
+    object_list = object_actions.add_parser("list")
+    object_list.add_argument("--status", choices=("active", "deleted"), default="active")
+    object_get = object_actions.add_parser("get")
+    object_get.add_argument("object_id")
+    object_get.add_argument("--status", choices=("active", "deleted"), default="active")
+    add_object_fields(object_actions.add_parser("create"), include_key=True)
+    object_update = object_actions.add_parser("update")
+    object_update.add_argument("object_id")
+    add_object_fields(object_update, include_key=False)
+    for action in ("delete", "restore"):
+        item = object_actions.add_parser(action)
+        item.add_argument("object_id")
+        add_yes(item)
+    objects.set_defaults(handler=handle_objects)
+
+    fields = groups.add_parser("fields", help="Manage field metadata.")
+    field_actions = fields.add_subparsers(dest="fields_action", required=True)
+    field_create = field_actions.add_parser("create")
+    field_create.add_argument("object_id")
+    add_object_fields(field_create, include_key=True)
+    field_update = field_actions.add_parser("update")
+    field_update.add_argument("object_id")
+    field_update.add_argument("field_id")
+    add_object_fields(field_update, include_key=False)
+    for action in ("delete", "restore"):
+        item = field_actions.add_parser(action)
+        item.add_argument("object_id")
+        item.add_argument("field_id")
+        add_yes(item)
+    fields.set_defaults(handler=handle_fields)
+
+    records = groups.add_parser("records", help="Manage business records.")
+    record_actions = records.add_subparsers(dest="records_action", required=True)
+    record_list = record_actions.add_parser("list")
+    record_list.add_argument("object_id")
+    record_list.add_argument("--page", type=int, default=1)
+    record_get = record_actions.add_parser("get")
+    record_get.add_argument("object_id")
+    record_get.add_argument("record_id")
+    record_create = record_actions.add_parser("create")
+    record_create.add_argument("object_id")
+    add_json_args(record_create)
+    record_update = record_actions.add_parser("update")
+    record_update.add_argument("object_id")
+    record_update.add_argument("record_id")
+    add_json_args(record_update)
+    record_delete = record_actions.add_parser("delete")
+    record_delete.add_argument("object_id")
+    record_delete.add_argument("record_id")
+    add_yes(record_delete)
+    records.set_defaults(handler=handle_records)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.handler(args)
+    except CliError as exc:
+        print(f"flowbase: error: {exc}", file=sys.stderr)
+        return 1
+
+
+def entrypoint() -> None:
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    entrypoint()

flowbase_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: flowbase-cli
+Version: 0.1.0
+Summary: Command line client for the FlowBase OpenAPI
+Author: DeepFlowAI
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# FlowBase CLI
+
+Install from this checkout:
+
+```bash
+python -m pip install ./packages/flowbase-cli
+```
+
+Configure an environment Base URL and an API key:
+
+```bash
+export FLOWBASE_HOST=https://flowbase-test-a.deepflowagent.com
+export FLOWBASE_API_KEY=fbk_xxx
+
+flowbase objects list
+flowbase records create obj_xxx --json '{"values":{"name":"Example"}}'
+flowbase docs list
+```
+
+`--host` selects the environment through its Host. The CLI never accepts a separate environment override and never stores API keys on disk. See `flowbase --help` and `flowbase docs list` for the complete command set.

flowbase_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+flowbase_cli/__init__.py,sha256=IXcJbeEA1I_Xo2f3BH-e0nw3DSIcwavbeipyUiYFUnI,51
+flowbase_cli/endpoints.py,sha256=kDP3VJlyz-JPJs29mfwAvsg1WngCfDyNWUUAfaZ2z74,3348
+flowbase_cli/main.py,sha256=lVYeXB4ZxbN-GwvLjhaVFLqwa3l6lD6-wwa_kfvz-B8,14662
+flowbase_cli-0.1.0.dist-info/METADATA,sha256=JnaWIYMmW8wp1Gha2tTRr1rTkRqV-Mjx8p95TypmlwY,807
+flowbase_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+flowbase_cli-0.1.0.dist-info/entry_points.txt,sha256=kb3ZwOcvIIJ-2W3yyWgn7luZVbPsj57YusOyoIOv2YA,58
+flowbase_cli-0.1.0.dist-info/top_level.txt,sha256=As7iuQHHfVT5d2WJ0cCN22Mmp0gTiOcoPpM0OC3XJxQ,13
+flowbase_cli-0.1.0.dist-info/RECORD,,

flowbase_cli-0.1.0.dist-info/WHEEL

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

flowbase_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flowbase = flowbase_cli.main:entrypoint

flowbase_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flowbase_cli