eledoctl 1.0.0__tar.gz

eledoctl-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.env
+.DS_Store
+.idea

eledoctl-1.0.0/LICENSE

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

eledoctl-1.0.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: eledoctl
+Version: 1.0.0
+Summary: Command-line toolkit and async Python API client for Eledo.
+Author: Eledo
+License: MIT License
+        
+        Copyright (c) 2026 Eledo
+        
+        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.
+License-File: LICENSE
+Keywords: api,automation,cli,documents,eledo,pdf,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Provides-Extra: repl
+Requires-Dist: prompt-toolkit>=3.0; extra == 'repl'
+Description-Content-Type: text/markdown
+
+# eledoctl
+[![CI](https://github.com/eledo-online/eledoctl/actions/workflows/ci.yml/badge.svg)](https://github.com/eledo-online/eledoctl/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/eledo-online/eledoctl/graph/badge.svg?token=IVVXIPSQHM)](https://codecov.io/gh/eledo-online/eledoctl)
+[![Release](https://img.shields.io/github/v/release/eledo-online/eledoctl)](https://github.com/eledo-online/eledoctl/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Eledo](https://img.shields.io/badge/Eledo-green.svg)](https://eledo.online/)
+![Eledo PDF automation overview](https://github.com/user-attachments/assets/31ee16e8-7a60-4989-8a73-cf2c3097cfa4)
+
+`eledoctl` is an open-source command-line toolkit for Eledo.
+
+It contains two Python modules:
+
+* `pyeledo` — async-native Python API client for Eledo REST APIs
+* `eledoctl` — CLI, REPL, and automation layer built on top of `pyeledo`
+
+The project is MIT licensed. Public functionality is exposed through `pyeledo` and `eledoctl`, while internal Eledo tooling is implemented as optional extensions.
+
+## Architecture
+
+```text
+repo/
+├── src/
+│   ├── pyeledo/       # Async SDK / REST client
+│   └── eledoctl/      # CLI / REPL / orchestration
+└── tests/
+    ├── pyeledo/
+    └── eledoctl/
+```
+
+`pyeledo` is async-first and async-only. It never stores credentials. Tokens are passed to the client by the caller.
+
+```python
+from pyeledo import EledoClient, TemplateScope
+
+async with EledoClient(token="...") as client:
+    profile = await client.get_profile()
+    templates = await client.get_templates(scope=TemplateScope.PRIVATE)
+```
+
+## Initial CLI Tree
+
+```bash
+eledoctl profile
+eledoctl templates list
+eledoctl templates schema TEMPLATE_ID
+eledoctl pdf generate TEMPLATE_ID --payload payload.json --output output.pdf
+eledoctl internal docs sync docs
+```
+
+For now the CLI passes an empty token unless `--token` is provided. Persistent token storage will be added later in `eledoctl`, not in `pyeledo`.
+
+## Installation
+
+```bash
+pip install eledoctl
+```
+
+## Development
+
+The project uses modern Python tooling based on `uv`.
+
+### Create or update the development environment
+
+```bash
+uv sync --group dev
+```
+
+### Run the test suite
+
+```bash
+uv run pytest
+```
+
+### Run the CLI
+
+```bash
+uv run eledoctl --help
+```
+
+### Format the code
+
+```bash
+uv run ruff format .
+```
+
+### Run linting
+
+```bash
+uv run ruff check .
+```
+
+### Run type checking
+
+```bash
+uv run mypy src
+```
+
+### Full validation
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```

eledoctl-1.0.0/README.md

@@ -0,0 +1,105 @@
+# eledoctl
+[![CI](https://github.com/eledo-online/eledoctl/actions/workflows/ci.yml/badge.svg)](https://github.com/eledo-online/eledoctl/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/eledo-online/eledoctl/graph/badge.svg?token=IVVXIPSQHM)](https://codecov.io/gh/eledo-online/eledoctl)
+[![Release](https://img.shields.io/github/v/release/eledo-online/eledoctl)](https://github.com/eledo-online/eledoctl/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Eledo](https://img.shields.io/badge/Eledo-green.svg)](https://eledo.online/)
+![Eledo PDF automation overview](https://github.com/user-attachments/assets/31ee16e8-7a60-4989-8a73-cf2c3097cfa4)
+
+`eledoctl` is an open-source command-line toolkit for Eledo.
+
+It contains two Python modules:
+
+* `pyeledo` — async-native Python API client for Eledo REST APIs
+* `eledoctl` — CLI, REPL, and automation layer built on top of `pyeledo`
+
+The project is MIT licensed. Public functionality is exposed through `pyeledo` and `eledoctl`, while internal Eledo tooling is implemented as optional extensions.
+
+## Architecture
+
+```text
+repo/
+├── src/
+│   ├── pyeledo/       # Async SDK / REST client
+│   └── eledoctl/      # CLI / REPL / orchestration
+└── tests/
+    ├── pyeledo/
+    └── eledoctl/
+```
+
+`pyeledo` is async-first and async-only. It never stores credentials. Tokens are passed to the client by the caller.
+
+```python
+from pyeledo import EledoClient, TemplateScope
+
+async with EledoClient(token="...") as client:
+    profile = await client.get_profile()
+    templates = await client.get_templates(scope=TemplateScope.PRIVATE)
+```
+
+## Initial CLI Tree
+
+```bash
+eledoctl profile
+eledoctl templates list
+eledoctl templates schema TEMPLATE_ID
+eledoctl pdf generate TEMPLATE_ID --payload payload.json --output output.pdf
+eledoctl internal docs sync docs
+```
+
+For now the CLI passes an empty token unless `--token` is provided. Persistent token storage will be added later in `eledoctl`, not in `pyeledo`.
+
+## Installation
+
+```bash
+pip install eledoctl
+```
+
+## Development
+
+The project uses modern Python tooling based on `uv`.
+
+### Create or update the development environment
+
+```bash
+uv sync --group dev
+```
+
+### Run the test suite
+
+```bash
+uv run pytest
+```
+
+### Run the CLI
+
+```bash
+uv run eledoctl --help
+```
+
+### Format the code
+
+```bash
+uv run ruff format .
+```
+
+### Run linting
+
+```bash
+uv run ruff check .
+```
+
+### Run type checking
+
+```bash
+uv run mypy src
+```
+
+### Full validation
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```

eledoctl-1.0.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "eledoctl"
+version = "1.0.0"
+description = "Command-line toolkit and async Python API client for Eledo."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [
+  { name = "Eledo" }
+]
+keywords = ["eledo", "cli", "sdk", "pdf", "automation", "api", "documents"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = [
+  "click>=8.1",
+  "httpx>=0.27",
+  "platformdirs>=4.2",
+]
+
+[project.optional-dependencies]
+repl = [
+  "prompt-toolkit>=3.0",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.2",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5.0",
+  "ruff>=0.5",
+  "mypy>=1.10",
+]
+
+[project.scripts]
+eledoctl = "eledoctl.cli.main:main"
+
+[tool.hatch.build]
+include = [
+  "src/pyeledo/**",
+  "src/eledoctl/**",
+  "README.md",
+  "LICENSE",
+]
+
+exclude = [
+  ".github/**",
+  "tests/**",
+  "CONTRIBUTING.md",
+  "uv.lock",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyeledo", "src/eledoctl"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+addopts = "--cov=pyeledo --cov=eledoctl --cov-report=term-missing"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+mypy_path = "src"
+packages = ["pyeledo", "eledoctl"]

eledoctl-1.0.0/src/eledoctl/__init__.py

@@ -0,0 +1 @@
+"""Command-line toolkit for Eledo."""

eledoctl-1.0.0/src/eledoctl/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI command definitions."""

eledoctl-1.0.0/src/eledoctl/cli/common.py

@@ -0,0 +1,25 @@
+"""Shared CLI utilities."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Coroutine
+from typing import Any
+
+import click
+
+from eledoctl.config.settings import ConnectionSettings, load_connection_settings
+
+
+def run[T](coro: Coroutine[Any, Any, T]) -> T:
+    """Run an asynchronous command implementation."""
+    return asyncio.run(coro)
+
+
+def require_connection_settings() -> ConnectionSettings:
+    """Load persisted connection settings or raise a user-facing CLI error."""
+    try:
+        return load_connection_settings()
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        raise click.ClickException(str(exc)) from exc

eledoctl-1.0.0/src/eledoctl/cli/documents.py

@@ -0,0 +1,195 @@
+"""PDF generation CLI commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from eledoctl.cli.common import require_connection_settings, run
+from eledoctl.config.settings import ConnectionSettings
+from pyeledo import EledoClient
+from pyeledo.types import JsonObject
+from pyeledo.utils import parse_json_object
+
+
+@click.group("documents")
+def documents_group() -> None:
+    """Document generation commands."""
+
+
+@documents_group.command("generate")
+@click.argument("template_id")
+@click.option("--template-version", type=int, default=None, help="Optional template version.")
+@click.option(
+    "--payload",
+    type=str,
+    default=None,
+    help='Inline JSON containing the Eledo "file" object.',
+)
+@click.option(
+    "--payload-file",
+    type=click.Path(path_type=Path, exists=True, dir_okay=False),
+    default=None,
+    help='Read the Eledo "file" object from a JSON file.',
+)
+@click.option(
+    "--payload-stdin",
+    is_flag=True,
+    help='Read the Eledo "file" object from standard input.',
+)
+@click.option(
+    "--add-field",
+    "fields",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help=("Add a top-level primitive field. May be repeated. Ignored when a JSON payload source is provided."),
+)
+@click.option(
+    "--output",
+    "output_path",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=None,
+    help="Document output path. Defaults to filename returned by Eledo.",
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(path_type=Path, file_okay=False),
+    default=None,
+    help="Directory for the generated document when --output is not provided.",
+)
+@click.option("--base64-json", is_flag=True, help="Print JSON metadata with base64 PDF content.")
+def generate_pdf(
+    template_id: str,
+    template_version: int | None,
+    payload: str | None,
+    payload_file: Path | None,
+    payload_stdin: bool,
+    fields: tuple[str, ...],
+    output_path: Path | None,
+    output_dir: Path | None,
+    base64_json: bool,
+) -> None:
+    """Generate a PDF document from an Eledo template."""
+    settings = require_connection_settings()
+    run(
+        _generate_pdf(
+            template_id=template_id,
+            settings=settings,
+            template_version=template_version,
+            file_data=_resolve_payload(
+                payload=payload, payload_file=payload_file, payload_stdin=payload_stdin, fields=fields
+            ),
+            output_path=output_path,
+            output_dir=output_dir,
+            base64_json=base64_json,
+        )
+    )
+
+
+async def _generate_pdf(
+    *,
+    template_id: str,
+    settings: ConnectionSettings,
+    template_version: int | None,
+    file_data: JsonObject | None,
+    output_path: Path | None,
+    output_dir: Path | None,
+    base64_json: bool,
+) -> None:
+    async with EledoClient(base_url=settings.base_url, token=settings.token) as client:
+        result = await client.generate_pdf(
+            template_id=template_id,
+            template_version=template_version,
+            file_data=file_data,
+        )
+
+    if base64_json:
+        click.echo(json.dumps(result.as_json(), indent=2))
+        return
+
+    destination = _resolve_output_path(
+        filename=result.filename,
+        output_path=output_path,
+        output_dir=output_dir,
+    )
+    destination.write_bytes(result.content)
+    click.echo(str(destination))
+
+
+def _resolve_payload(
+    *,
+    payload: str | None,
+    payload_file: Path | None,
+    payload_stdin: bool,
+    fields: tuple[str, ...],
+) -> JsonObject | None:
+    """Read and parse document data from one configured input source."""
+    source_count = sum(
+        (
+            payload is not None,
+            payload_file is not None,
+            payload_stdin,
+        )
+    )
+
+    if source_count > 1:
+        raise click.ClickException("Use only one of --payload, --payload-file, or --payload-stdin.")
+
+    if source_count == 1 and fields:
+        click.echo(
+            "Warning: --add-field values are ignored because a JSON payload was provided.",
+            err=True,
+        )
+
+    if payload is not None:
+        return parse_json_object(payload) or None
+
+    if payload_file is not None:
+        return parse_json_object(payload_file.read_text(encoding="utf-8")) or None
+
+    if payload_stdin:
+        return parse_json_object(click.get_text_stream("stdin").read()) or None
+
+    return _build_field_payload(fields)
+
+
+def _build_field_payload(fields: tuple[str, ...]) -> JsonObject | None:
+    """Build a JSON object from repeated KEY=VALUE field arguments."""
+    if not fields:
+        return None
+
+    payload: JsonObject = {}
+
+    for field in fields:
+        key, separator, value = field.partition("=")
+
+        if separator == "":
+            raise click.ClickException(f"Invalid field {field!r}. Expected KEY=VALUE.")
+
+        key = key.strip()
+
+        if not key:
+            raise click.ClickException(f"Invalid field {field!r}. Field name cannot be empty.")
+
+        payload[key] = value
+
+    return payload
+
+
+def _resolve_output_path(
+    *,
+    filename: str,
+    output_path: Path | None,
+    output_dir: Path | None,
+) -> Path:
+    """Resolve the destination path for a generated document."""
+    if output_path is not None:
+        return output_path
+
+    if output_dir is not None:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        return output_dir / filename
+
+    return Path(filename)

eledoctl-1.0.0/src/eledoctl/cli/internal/docs.py

@@ -0,0 +1,37 @@
+"""Internal documentation synchronization CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.group("internal")
+def internal_group() -> None:
+    """Internal Eledo operational tooling."""
+
+
+@internal_group.group("docs")
+def internal_docs_group() -> None:
+    """Internal documentation synchronization tooling."""
+
+
+@internal_docs_group.command("sync")
+@click.argument("path", type=click.Path(path_type=Path))
+@click.option(
+    "--review-report",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=None,
+    help="Optional path where manual review report will be written.",
+)
+@click.option("--dry-run", is_flag=True, help="Analyze without uploading changes.")
+def sync_docs(path: Path, review_report: Path | None, dry_run: bool) -> None:
+    """Synchronize Git documentation into Eledo CMS.
+
+    Implementation will be added after the Eledo CMS CRUD API is available.
+    """
+    click.echo("Documentation sync scaffold is ready, but implementation is pending.")
+    click.echo(f"path={path}")
+    click.echo(f"review_report={review_report}")
+    click.echo(f"dry_run={dry_run}")