operx-cli 0.1.0__py3-none-any.whl

operx_cli/__init__.py

@@ -0,0 +1,5 @@
+"""OperX's command line (PRODUCT_ROADMAP.md › Platform, step 3): the public
+API (backend/users/api_allowlist.py) from a terminal, with a personal API
+token."""
+
+__version__ = "0.1.0"

operx_cli/app.py

@@ -0,0 +1,87 @@
+"""`operx`: the root of the commands, and what turns a refused call into
+one line instead of a traceback."""
+
+import sys
+from typing import Annotated, Optional
+
+import typer
+from typer.core import TyperGroup
+
+from . import __version__, settings
+from .client import ApiError
+from .commands import account, inventario, lecturas, ordenes, personas, raw, registros, search
+from .commands.common import CliError, Session
+from .lookup import NoSingleMatch
+from .spreadsheet import SpreadsheetError
+
+# What a person can fix: shown as "Error: …", exit code 1.
+EXPECTED_ERRORS = (ApiError, CliError, NoSingleMatch, SpreadsheetError, settings.SettingsError)
+
+
+class ReportedErrors(TyperGroup):
+    def invoke(self, ctx):
+        try:
+            return super().invoke(ctx)
+        except EXPECTED_ERRORS as error:
+            typer.echo(f"Error: {error}", err=True)
+            raise typer.Exit(1) from None
+        except typer.Abort:
+            # Ctrl+C, or a question whose answer never came.
+            typer.echo("Se canceló.", err=True)
+            raise typer.Exit(1) from None
+
+
+app = typer.Typer(
+    cls=ReportedErrors,
+    help="OperX desde la terminal: tu empresa con tu token de API.",
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    # A crash must never print the token, which lives in the client's locals.
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _show_version(value):
+    if value:
+        typer.echo(f"operx {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    perfil: Annotated[
+        Optional[str],
+        typer.Option("--perfil", "-p", help="El perfil: otra API u otra empresa. Sin él, «principal» (o OPERX_PERFIL)."),
+    ] = None,
+    version: Annotated[
+        bool, typer.Option("--version", callback=_show_version, is_eager=True, help="La versión instalada.")
+    ] = False,
+):
+    if ctx.obj is None:
+        ctx.obj = Session()
+    ctx.obj.profile = settings.profile_name(perfil)
+
+
+app.command()(account.entrar)
+app.command()(account.salir)
+app.command()(account.cuenta)
+app.command()(search.buscar)
+app.command()(raw.api)
+app.add_typer(ordenes.app, name="ordenes")
+app.add_typer(registros.equipos, name="equipos")
+app.add_typer(registros.clientes, name="clientes")
+app.add_typer(registros.lugares, name="lugares")
+app.add_typer(inventario.app, name="inventario")
+app.add_typer(lecturas.app, name="lecturas")
+app.add_typer(personas.app, name="personas")
+
+
+def main():
+    # Redirected to a file, Windows would write the results in its own code
+    # page; the CSV and the JSON are UTF-8.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    app()

operx_cli/client.py

@@ -0,0 +1,134 @@
+"""The calls to OperX's API, with a personal API token: the only module that
+talks to the network. The MCP server can use it as it is.
+
+A write carries an Idempotency-Key, so the views that honour it (stock
+moves, a work order's status, Ambiental's records) never do it twice. Only a
+429 is repeated by itself: it changed nothing. A write that timed out or
+failed on the server is never repeated, because on a view without the key a
+second try could create the record twice.
+"""
+
+import time
+import uuid
+
+import httpx
+
+from . import __version__
+
+USER_AGENT = f"operx-cli/{__version__}"
+WRITES = ("POST", "PUT", "PATCH", "DELETE")
+# A list asks for this many rows a page: the API's cap (utils/pagination.py).
+PAGE_SIZE = 200
+# How many times a 429 is waited out before giving up, and the longest wait.
+RETRIES_ON_429 = 3
+LONGEST_WAIT = 60
+
+SIGN_IN_AGAIN = "Entra de nuevo con `operx entrar`."
+TIMED_OUT_WRITE = (
+    "La API no respondió a tiempo. Revisa en la app si el cambio quedó hecho antes de repetirlo."
+)
+
+
+class ApiError(Exception):
+    """An answer the API refused, or no answer at all (status 0)."""
+
+    def __init__(self, status, message):
+        super().__init__(message)
+        self.status = status
+
+
+def api_path(path):
+    """'/api/v1/work-orders/12' → 'work-orders/12/': the part after /api/v1/,
+    with the trailing slash Django's addresses need."""
+    path = path.strip().lstrip("/")
+    if path.startswith("api/v1/"):
+        path = path[len("api/v1/"):]
+    address, separator, query = path.partition("?")
+    if not address.endswith("/"):
+        address += "/"
+    return address + separator + query
+
+
+def error_message(response):
+    """The API's own words: its "detail", or each field with its errors."""
+    try:
+        body = response.json()
+    except ValueError:
+        return f"La API respondió {response.status_code}."
+    if isinstance(body, dict) and isinstance(body.get("detail"), str):
+        return body["detail"]
+    if isinstance(body, dict) and body:
+        lines = []
+        for field, errors in body.items():
+            text = " ".join(str(error) for error in errors) if isinstance(errors, list) else str(errors)
+            lines.append(f"{field}: {text}")
+        return "\n".join(lines)
+    return f"La API respondió {response.status_code}."
+
+
+def seconds_to_wait(response):
+    try:
+        return min(int(response.headers.get("Retry-After", "5")), LONGEST_WAIT)
+    except ValueError:
+        return 5
+
+
+class ApiClient:
+    def __init__(self, address, token, transport=None, sleep=time.sleep):
+        self.address = address.rstrip("/")
+        self.sleep = sleep
+        self.http = httpx.Client(
+            base_url=self.address + "/api/v1/",
+            headers={"Authorization": f"Bearer {token}", "User-Agent": USER_AGENT, "Accept": "application/json"},
+            timeout=60,
+            transport=transport,
+        )
+
+    def send(self, method, path, params=None, json=None, files=None, data=None):
+        """One call; its answer, or ApiError when the API refused it."""
+        method = method.upper()
+        headers = {"Idempotency-Key": str(uuid.uuid4())} if method in WRITES else {}
+        waits = 0
+        while True:
+            response = self._request(method, path, params, json, files, data, headers)
+            if response.status_code != 429 or waits == RETRIES_ON_429:
+                break
+            self.sleep(seconds_to_wait(response))
+            waits += 1
+        if response.status_code >= 400:
+            message = error_message(response)
+            if response.status_code == 401:
+                message = f"{message}\n{SIGN_IN_AGAIN}"
+            raise ApiError(response.status_code, message)
+        return response
+
+    def _request(self, method, path, params, json, files, data, headers):
+        try:
+            return self.http.request(
+                method, api_path(path), params=params, json=json, files=files, data=data, headers=headers,
+            )
+        except httpx.TimeoutException:
+            if method in WRITES:
+                raise ApiError(0, TIMED_OUT_WRITE)
+            raise ApiError(0, "La API no respondió a tiempo. Intenta de nuevo.")
+        except httpx.HTTPError as error:
+            raise ApiError(0, f"No se pudo conectar con {self.address}: {error}")
+
+    def get(self, path, params=None):
+        """A read's answer, as JSON."""
+        return self.send("GET", path, params=params).json()
+
+    def all_pages(self, path, params):
+        """Every row of a list, page by page. An address that isn't paginated
+        answers a plain list, taken as it comes. The pages are asked by number:
+        the "next" the API sends can name the wrong host behind Cloudflare."""
+        page = 1
+        rows = []
+        while True:
+            answer = self.get(path, {**params, "page": page, "page_size": PAGE_SIZE})
+            if isinstance(answer, list):
+                return answer
+            rows.extend(answer.get("results", []))
+            if not answer.get("next"):
+                return rows
+            page += 1

operx_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""One module per group of commands: `operx ordenes …`, `operx equipos …`."""

operx_cli/commands/account.py

@@ -0,0 +1,68 @@
+"""`operx entrar`, `operx salir` and `operx cuenta`: the token of a profile,
+and who it acts as."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from .. import settings
+from ..client import ApiClient
+from ..output import print_record
+from .common import CliError, JsonOption, Session, client_of
+
+TOKEN_PREFIX = "opx_"
+PRODUCT_LABELS = {
+    "maintenance": "Trabajos", "people": "Personas", "inventory": "Inventario",
+    "equipment": "Equipos", "sst": "SG-SST", "environment": "Ambiental",
+}
+
+
+def full_name(me):
+    return " ".join(f"{me.get('first_name', '')} {me.get('last_name', '')}".split()) or me.get("email", "")
+
+
+def entrar(
+    ctx: typer.Context,
+    direccion: Annotated[
+        Optional[str], typer.Option("--direccion", help="La dirección de la API. Sin ella, la de producción.")
+    ] = None,
+):
+    """Guarda tu token de API en el llavero del sistema. Créalo en la app: menú de tu cuenta › Acceso por API."""
+    session = ctx.find_object(Session)
+    token = typer.prompt("Pega tu token (no se mostrará)", hide_input=True).strip()
+    if not token.startswith(TOKEN_PREFIX):
+        raise CliError("Eso no es un token de OperX: empieza por «opx_». Créalo en la app, en Acceso por API.")
+    address = direccion.rstrip("/") if direccion else session.address()
+    # Checked before it's kept: a token the API refuses is never saved.
+    me = ApiClient(address, token, transport=session.transport).get("auth/me")
+    settings.save_token(session.profile, token)
+    if direccion:
+        settings.save_address(session.profile, address)
+    typer.echo(f"Listo: entraste como {full_name(me)} en {me.get('client_name')}.")
+    typer.echo(f"Perfil «{session.profile}», {address}.")
+
+
+def salir(ctx: typer.Context):
+    """Borra el token de este perfil del llavero. El token sigue vivo: revócalo en Acceso por API si ya no lo usas."""
+    session = ctx.find_object(Session)
+    settings.forget_token(session.profile)
+    typer.echo(f"Se borró el token del perfil «{session.profile}».")
+
+
+def cuenta(ctx: typer.Context, as_json: JsonOption = False):
+    """Quién eres para la API: tu nombre, tu empresa y tu rol."""
+    session = ctx.find_object(Session)
+    me = client_of(ctx).get("auth/me")
+    if as_json:
+        print_record(me, "json")
+        return
+    roles = [me.get("role")] + list(me.get("extra_roles") or [])
+    print_record({
+        "Nombre": full_name(me),
+        "Correo": me.get("email"),
+        "Empresa": me.get("client_name"),
+        "Rol": [role for role in roles if role],
+        "Productos": [PRODUCT_LABELS.get(product, product) for product in me.get("products") or []],
+        "Perfil": session.profile,
+        "Dirección": session.address(),
+    }, "tabla")

operx_cli/commands/common.py

@@ -0,0 +1,116 @@
+"""What every command shares: the session (which profile, which API), the
+options that choose how results are shown, and the question before a
+write."""
+
+import sys
+from dataclasses import dataclass
+from typing import Annotated, Optional
+
+import typer
+
+from .. import settings
+from ..client import ApiClient
+from ..output import note
+from ..values import decimal_text, iso_date, iso_datetime
+
+NOT_SIGNED_IN = "No has entrado en este perfil. Usa `operx entrar` con un token de Acceso por API."
+NEEDS_SI = "Esto cambia datos de tu empresa. Fuera de una terminal agrega --si para confirmarlo."
+
+
+class CliError(Exception):
+    """Something the person typed that can't be done: shown as one line."""
+
+
+@dataclass
+class Session:
+    profile: str = settings.DEFAULT_PROFILE
+    # httpx's transport: None goes to the network; the tests pass a fake API.
+    transport: object = None
+
+    def address(self):
+        return settings.address_of(self.profile)
+
+    def client(self):
+        token = settings.token_of(self.profile)
+        if not token:
+            raise CliError(NOT_SIGNED_IN)
+        return ApiClient(self.address(), token, transport=self.transport)
+
+
+def client_of(ctx):
+    return ctx.find_object(Session).client()
+
+
+JsonOption = Annotated[bool, typer.Option("--json", help="Todo lo que responde la API, en JSON.")]
+CsvOption = Annotated[bool, typer.Option("--csv", help="En CSV para Excel (UTF-8, separado por punto y coma).")]
+AllOption = Annotated[bool, typer.Option("--todas", help="Todas las páginas, no solo la primera.")]
+YesOption = Annotated[bool, typer.Option("--si", help="Escribe sin preguntar (para scripts y tareas programadas).")]
+SearchOption = Annotated[Optional[str], typer.Option("--buscar", help="Solo lo que contenga este texto.")]
+
+
+def output_format(json_flag, csv_flag):
+    if json_flag and csv_flag:
+        raise CliError("Usa --json o --csv, no los dos.")
+    if json_flag:
+        return "json"
+    return "csv" if csv_flag else "tabla"
+
+
+def list_rows(client, path, params, all_pages):
+    """The first page of a list, or every page with --todas."""
+    params = {key: value for key, value in params.items() if value not in (None, "")}
+    if all_pages:
+        return client.all_pages(path, params)
+    answer = client.get(path, params)
+    if isinstance(answer, list):
+        return answer
+    rows = answer.get("results", [])
+    if answer.get("next"):
+        note(f"Mostrando {len(rows)} de {answer.get('count')}. Usa --todas para verlos todos.")
+    return rows
+
+
+YES_ANSWERS = ("s", "si", "sí", "y", "yes")
+
+
+def can_ask():
+    return sys.stdin.isatty()
+
+
+def confirm_write(what, yes):
+    """Ask before changing anything, unless --si. A script can't answer, so
+    it needs --si: without a terminal, or when the answer never comes
+    (Windows' NUL device passes for a terminal)."""
+    if yes:
+        return
+    if not can_ask():
+        raise CliError(NEEDS_SI)
+    try:
+        answer = typer.prompt(f"{what} ¿Confirmas? (s/n)", default="n", show_default=False)
+    except typer.Abort:
+        raise CliError(NEEDS_SI) from None
+    if answer.strip().casefold() not in YES_ANSWERS:
+        raise CliError("No se cambió nada.")
+
+
+def number(text):
+    try:
+        return decimal_text(text)
+    except ValueError as error:
+        raise CliError(str(error)) from None
+
+
+def moment(text):
+    try:
+        return iso_datetime(text)
+    except ValueError as error:
+        raise CliError(str(error)) from None
+
+
+def day(text):
+    return iso_date(text) if text else None
+
+
+def without_empty(fields):
+    """The fields someone gave: an option left out isn't sent."""
+    return {key: value for key, value in fields.items() if value not in (None, "")}

operx_cli/commands/inventario.py

@@ -0,0 +1,105 @@
+"""`operx inventario`: stock per place, and stock in and out. Each move is
+a line in the ledger; a mistake is undone in the app with "Revertir"."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from ..lookup import find_in, find_one
+from ..output import print_rows
+from .common import (
+    AllOption, CsvOption, JsonOption, SearchOption, YesOption, client_of, confirm_write, list_rows, moment, number,
+    output_format, without_empty,
+)
+
+app = typer.Typer(help="Inventario: existencias, entradas y salidas.", no_args_is_help=True)
+
+STOCK_COLUMNS = [
+    ("item_code", "Código"), ("item_name", "Artículo"), ("location_name", "Lugar"), ("on_hand", "Existencias"),
+    ("unit", "Unidad"), ("min_qty", "Mínimo"), ("is_low", "Bajo el mínimo"),
+]
+# inventory.Reason.used_for: the reasons for taking stock out.
+FOR_ISSUE = "issue"
+
+ItemOption = Annotated[str, typer.Option("--articulo", help="El código o nombre del artículo.")]
+PlaceOption = Annotated[str, typer.Option("--lugar", help="El nombre de la bodega o el vehículo.")]
+QuantityOption = Annotated[str, typer.Option("--cantidad", help="Cuánto: 10 o 2,5.")]
+NoteOption = Annotated[Optional[str], typer.Option("--nota")]
+WhenOption = Annotated[Optional[str], typer.Option("--fecha", help="Cuándo pasó, si no fue ahora: 22/10/2026 08:00.")]
+
+
+def _item_and_place(client, articulo, lugar):
+    item = find_one(client, "inventory/items", articulo, ["code", "name"], "artículo")
+    place = find_one(client, "locations", lugar, ["name"], "lugar")
+    return item, place
+
+
+@app.command()
+def existencias(
+    ctx: typer.Context,
+    buscar: SearchOption = None,
+    todas: AllOption = False,
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Cuánto hay de cada artículo en cada lugar."""
+    rows = list_rows(client_of(ctx), "inventory/stock", {"search": buscar}, todas)
+    print_rows(STOCK_COLUMNS, rows, output_format(as_json, as_csv))
+
+
+@app.command()
+def entrada(
+    ctx: typer.Context,
+    articulo: ItemOption,
+    lugar: PlaceOption,
+    cantidad: QuantityOption,
+    costo_unitario: Annotated[str, typer.Option("--costo-unitario", help="Lo que costó cada unidad: 1.500,50.")],
+    proveedor: Annotated[Optional[str], typer.Option("--proveedor", help="El nombre o NIT del proveedor.")] = None,
+    nota: NoteOption = None,
+    fecha: WhenOption = None,
+    si: YesOption = False,
+):
+    """Registra una entrada de stock."""
+    client = client_of(ctx)
+    item, place = _item_and_place(client, articulo, lugar)
+    move = without_empty({
+        "item": item["id"],
+        "location": place["id"],
+        "quantity": number(cantidad),
+        "unit_cost": number(costo_unitario),
+        "supplier": find_one(client, "customers", proveedor, ["name", "tax_id"], "proveedor")["id"] if proveedor else None,
+        "note": nota,
+        "occurred_at": moment(fecha) if fecha else None,
+    })
+    confirm_write(f"Entrada de {cantidad} de «{item['name']}» en {place['name']}.", si)
+    client.send("POST", "inventory/actions/entrada", json=move)
+    typer.echo(f"Entrada registrada: {cantidad} de {item['name']} en {place['name']}.")
+
+
+@app.command()
+def salida(
+    ctx: typer.Context,
+    articulo: ItemOption,
+    lugar: PlaceOption,
+    cantidad: QuantityOption,
+    motivo: Annotated[str, typer.Option("--motivo", help="El motivo de salida, como en Ajustes de Inventario.")],
+    nota: NoteOption = None,
+    fecha: WhenOption = None,
+    si: YesOption = False,
+):
+    """Registra una salida de stock."""
+    client = client_of(ctx)
+    item, place = _item_and_place(client, articulo, lugar)
+    reasons = [reason for reason in client.get("inventory/reasons") if reason.get("used_for") == FOR_ISSUE]
+    reason = find_in(reasons, motivo, ["name"], "motivo de salida")
+    move = without_empty({
+        "item": item["id"],
+        "location": place["id"],
+        "quantity": number(cantidad),
+        "reason": reason["id"],
+        "note": nota,
+        "occurred_at": moment(fecha) if fecha else None,
+    })
+    confirm_write(f"Salida de {cantidad} de «{item['name']}» de {place['name']} ({reason['name']}).", si)
+    client.send("POST", "inventory/actions/salida", json=move)
+    typer.echo(f"Salida registrada: {cantidad} de {item['name']} de {place['name']}.")

operx_cli/commands/lecturas.py

@@ -0,0 +1,57 @@
+"""`operx lecturas`: Equipos' measurement points and their readings, what a
+sensor, a SCADA or a scheduled job sends. A wrong reading is voided in the
+app, never edited."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from ..lookup import find_one
+from ..output import print_rows
+from ..values import now_iso
+from .common import CsvOption, JsonOption, YesOption, client_of, confirm_write, moment, number, output_format
+
+app = typer.Typer(help="Lecturas de Equipos: los puntos de medición y sus lecturas.", no_args_is_help=True)
+
+POINT_COLUMNS = [
+    ("id", "Punto"), ("name", "Nombre"), ("unit", "Unidad"), ("min_value", "Mínimo"), ("max_value", "Máximo"),
+    ("last_value", "Última lectura"), ("last_at", "Tomada"),
+]
+
+
+def _with_last_reading(point):
+    last = point.get("last") or {}
+    return {**point, "last_value": last.get("value"), "last_at": (last.get("taken_at") or "")[:16].replace("T", " ")}
+
+
+@app.command()
+def puntos(
+    ctx: typer.Context,
+    equipo: Annotated[str, typer.Argument(help="El código, nombre o id del equipo.")],
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Los puntos de medición de un equipo, con su última lectura."""
+    client = client_of(ctx)
+    asset = find_one(client, "assets", equipo, ["code", "name"], "equipo")
+    points = client.get("measurements/points", {"asset": asset["id"]})
+    output = output_format(as_json, as_csv)
+    print_rows(POINT_COLUMNS, points if output == "json" else [_with_last_reading(point) for point in points], output)
+
+
+@app.command()
+def registrar(
+    ctx: typer.Context,
+    punto: Annotated[int, typer.Option("--punto", help="El número del punto (operx lecturas puntos EQUIPO).")],
+    valor: Annotated[str, typer.Option("--valor", help="La lectura: 73,4.")],
+    fecha: Annotated[Optional[str], typer.Option("--fecha", help="Cuándo se tomó, si no fue ahora: 22/10/2026 08:00.")] = None,
+    reinicio: Annotated[bool, typer.Option("--reinicio", help="El contador volvió a cero.")] = False,
+    si: YesOption = False,
+):
+    """Registra una lectura."""
+    reading = {"point": punto, "value": number(valor), "taken_at": moment(fecha) if fecha else now_iso()}
+    if reinicio:
+        reading["is_reset"] = True
+    confirm_write(f"Lectura {valor} en el punto {punto}.", si)
+    client_of(ctx).send("POST", "measurements/readings", json=reading)
+    typer.echo(f"Lectura registrada: {valor} en el punto {punto}.")