operx-cli 0.10.0__tar.gz → 0.11.0__tar.gz

{operx_cli-0.10.0 → operx_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: operx-cli
-Version: 0.10.0
+Version: 0.11.0
 Summary: La línea de comandos de OperX: tu empresa desde la terminal, con tu token de API.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -216,6 +216,17 @@ operx chat leido mantenimiento
 Chat va solo por canales: los mensajes directos, los grupos y los archivos
 son de la app.
 
+```
+operx connect dispositivos                                  # los que envían datos de las máquinas, y su estado
+operx connect canales "Broker planta"                       # qué envía cada canal y a qué punto va
+operx connect mensajes d-7f3k2m --cuantos 5                 # lo que llegó, tal cual
+operx connect mapear d-7f3k2m planta/comp2/temp --equipo "Compresor 2" --punto "Temperatura rodamiento"
+operx connect silenciar d-7f3k2m planta/comp2/temp --hasta "05/11/2026 18:00" --motivo "Mantenimiento"
+```
+
+Las claves de los dispositivos no pasan por el CLI: se crean y se ven en la
+app, en la pestaña Clave del dispositivo.
+
 SG-SST y Ambiental van por empresa: sin `--empresa`, la de tu cuenta. Si
 llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
 `operx ambiental empresas` las listan.

{operx_cli-0.10.0 → operx_cli-0.11.0}/README.md

@@ -202,6 +202,17 @@ operx chat leido mantenimiento
 Chat va solo por canales: los mensajes directos, los grupos y los archivos
 son de la app.
 
+```
+operx connect dispositivos                                  # los que envían datos de las máquinas, y su estado
+operx connect canales "Broker planta"                       # qué envía cada canal y a qué punto va
+operx connect mensajes d-7f3k2m --cuantos 5                 # lo que llegó, tal cual
+operx connect mapear d-7f3k2m planta/comp2/temp --equipo "Compresor 2" --punto "Temperatura rodamiento"
+operx connect silenciar d-7f3k2m planta/comp2/temp --hasta "05/11/2026 18:00" --motivo "Mantenimiento"
+```
+
+Las claves de los dispositivos no pasan por el CLI: se crean y se ven en la
+app, en la pestaña Clave del dispositivo.
+
 SG-SST y Ambiental van por empresa: sin `--empresa`, la de tu cuenta. Si
 llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
 `operx ambiental empresas` las listan.

{operx_cli-0.10.0 → operx_cli-0.11.0}/operx_cli/AGENTES.md

@@ -309,6 +309,11 @@ operx chat canales --json
 operx chat leer mantenimiento --json
 operx chat escribir mantenimiento "@Pedro Pérez la bomba 4 quedó lista" --si --json
 
+# Lo que envía un dispositivo de Connect, y asignar un canal a un punto (después de su sí)
+operx connect canales d-7f3k2m --json
+operx connect mensajes d-7f3k2m --cuantos 5 --json
+operx connect mapear d-7f3k2m planta/comp2/temp --equipo "Compresor 2" --punto "Temperatura rodamiento" --si --json
+
 # Una reacción y un canal nuevo en Chat (no tienen comando propio)
 operx api POST chat/messages/123/reactions/ -d '{"emoji": "✅"}' --si
 operx api POST chat/conversations/ -d '{"kind": "public", "name": "turno-noche", "topic": "Lo de la noche"}' --si --json

{operx_cli-0.10.0 → operx_cli-0.11.0}/operx_cli/__init__.py

@@ -2,4 +2,4 @@
 API (backend/users/api_allowlist.py) from a terminal, with a personal API
 token."""
 
-__version__ = "0.10.0"
+__version__ = "0.11.0"

{operx_cli-0.10.0 → operx_cli-0.11.0}/operx_cli/app.py

@@ -14,7 +14,7 @@ from . import __version__, settings, shell
 from .agent_guide import guide_text
 from .client import ApiError
 from .commands import (
-    account, ambiental, articulos, avisos, campos, chat, completar, inventario, lecturas, muestreo, ordenes, personas,
+    account, ambiental, articulos, avisos, campos, chat, completar, connect, inventario, lecturas, muestreo, ordenes, personas,
     planta, preventivos, raw, registros, reportes, rutinas, search, sst, update,
 )
 from .commands.common import CliError, Session
@@ -162,6 +162,7 @@ app.add_typer(sst.app, name="sst")
 app.add_typer(ambiental.app, name="ambiental")
 app.add_typer(muestreo.app, name="muestreo")
 app.add_typer(chat.app, name="chat")
+app.add_typer(connect.app, name="connect")
 
 
 @app.command()

operx_cli-0.11.0/operx_cli/commands/connect.py

@@ -0,0 +1,152 @@
+"""`operx connect`: the devices that send machine data, what each sends, and mapping
+their channels to the machines' points (CONNECT_SPEC.md › API, CLI and MCP). Keys
+never pass through here: a device's key is made and shown in the app."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from ..client import ApiError
+from ..lookup import NoSingleMatch, find_in, find_one
+from ..output import print_rows
+from .common import CliError, CsvOption, JsonOption, YesOption, answer_of, client_of, confirm_write, moment, number, output_format, print_result
+
+app = typer.Typer(help="Connect: los dispositivos que envían datos de las máquinas y sus canales.", no_args_is_help=True)
+
+# The app's words (web/src/products/connect/components/parts.tsx, ChannelsTab.tsx, MessagesTab.tsx).
+DEVICE_STATES = {
+    "receiving": "Recibiendo", "silent": "Sin datos", "errors": "Con errores", "waiting": "Esperando el primer mensaje", "paused": "Pausado",
+}
+CHANNEL_STATES = {"unmapped": "Sin asignar", "counting": "Contando", "out_of_range": "Fuera del rango", "in_range": "Dentro del rango"}
+RESULTS = {"read": "leído", "partly_read": "leído en parte", "refused": "rechazado", "paused": "en pausa"}
+DEVICE_COLUMNS = [
+    ("uid", "Id"), ("name", "Dispositivo"), ("model_label", "Tipo"), ("place_name", "Lugar"), ("estado", "Estado"),
+    ("last_seen", "Último envío"), ("channels_total", "Canales"), ("channels_mapped", "Asignados"),
+]
+CHANNEL_COLUMNS = [("key", "Canal"), ("punto", "Punto"), ("estado", "Estado"), ("last_value", "Último valor"), ("last_raw", "Llega")]
+MESSAGE_COLUMNS = [("llego", "Llegó"), ("way", "Vía"), ("resultado", "Resultado"), ("values_in", "Valores"), ("reason", "Motivo"), ("body", "Mensaje")]
+BODY_SHOWN = 120
+FIRST_MAPPING = "Es un contador y lo que marca el equipo no cuadra con lo anotado: decídelo en la app, en el canal del dispositivo."
+
+
+def _when(text):
+    return (text or "")[:16].replace("T", " ")
+
+
+def device_named(client, dispositivo):
+    """A device by its id (d-…), its name or its number."""
+    devices = client.get("connect/devices").get("devices", [])
+    try:
+        return find_in(devices, dispositivo, ["uid", "name"], "dispositivo")
+    except NoSingleMatch:
+        by_number = [device for device in devices if str(device["id"]) == str(dispositivo).strip()]
+        if by_number:
+            return by_number[0]
+        raise
+
+
+def channel_named(device, canal):
+    return find_in(device.get("channels", []), canal, ["key", "label"], "canal")
+
+
+@app.command()
+def dispositivos(ctx: typer.Context, as_json: JsonOption = False, as_csv: CsvOption = False):
+    """Los dispositivos: su estado, cuándo enviaron y cuántos canales ya van a un punto."""
+    devices = client_of(ctx).get("connect/devices").get("devices", [])
+    output = output_format(as_json, as_csv)
+    rows = devices if output == "json" else [
+        {**device, "estado": DEVICE_STATES.get(device["state"], device["state"]), "last_seen": _when(device.get("last_seen_at"))} for device in devices
+    ]
+    print_rows(DEVICE_COLUMNS, rows, output)
+
+
+@app.command()
+def canales(
+    ctx: typer.Context,
+    dispositivo: Annotated[str, typer.Argument(help="El id (d-…), el nombre o el número del dispositivo.")],
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Los canales de un dispositivo: lo último que llegó y a qué punto va cada uno."""
+    client = client_of(ctx)
+    device = client.get(f"connect/devices/{device_named(client, dispositivo)['id']}")
+    output = output_format(as_json, as_csv)
+    channels = device.get("channels", [])
+    rows = channels if output == "json" else [{
+        **channel,
+        "punto": f"{channel['point']['machine_name']} · {channel['point']['name']}" if channel.get("point") else "",
+        "estado": channel.get("state_note") or CHANNEL_STATES.get(channel["state"], channel["state"]),
+    } for channel in channels]
+    print_rows(CHANNEL_COLUMNS, rows, output)
+
+
+@app.command()
+def mensajes(
+    ctx: typer.Context,
+    dispositivo: Annotated[str, typer.Argument(help="El id (d-…), el nombre o el número del dispositivo.")],
+    cuantos: Annotated[int, typer.Option("--cuantos", help="Cuántos, del más nuevo: hasta 50.")] = 10,
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Lo que envió un dispositivo, tal como llegó, con lo que se leyó y lo que se rechazó."""
+    client = client_of(ctx)
+    device = device_named(client, dispositivo)
+    messages = client.get(f"connect/devices/{device['id']}/messages").get("messages", [])[:max(1, min(cuantos, 50))]
+    output = output_format(as_json, as_csv)
+    rows = messages if output == "json" else [{
+        **message, "llego": _when(message["received_at"]), "resultado": RESULTS.get(message["result"], message["result"]),
+        "body": message["body"] if len(message["body"]) <= BODY_SHOWN else message["body"][:BODY_SHOWN] + "…",
+    } for message in messages]
+    print_rows(MESSAGE_COLUMNS, rows, output)
+
+
+@app.command()
+def mapear(
+    ctx: typer.Context,
+    dispositivo: Annotated[str, typer.Argument(help="El id (d-…), el nombre o el número del dispositivo.")],
+    canal: Annotated[str, typer.Argument(help="El canal tal como lo envía: planta/comp2/temp.")],
+    equipo: Annotated[str, typer.Option("--equipo", help="La máquina, por su código o nombre.")],
+    punto: Annotated[str, typer.Option("--punto", help="El punto de medición de esa máquina, por su nombre.")],
+    escala: Annotated[Optional[str], typer.Option("--escala", help="Por cuánto se multiplica lo que llega: 0,1.")] = None,
+    si: YesOption = False,
+    as_json: JsonOption = False,
+):
+    """Asigna un canal a un punto de medición de una máquina."""
+    client = client_of(ctx)
+    device = client.get(f"connect/devices/{device_named(client, dispositivo)['id']}")
+    channel = channel_named(device, canal)
+    machine = find_one(client, "assets", equipo, ["code", "name"], "equipo")
+    points = [row["point"] for row in client.get("connect/mappable-points").get("points", []) if row["point"]["machine_id"] == machine["id"]]
+    point = find_in(points, punto, ["name"], "punto")
+    change = {"point": point["id"]}
+    if escala:
+        change["scale"] = number(escala)
+    confirm_write(f"{device['name']} · {channel['key']} irá a {machine['name']} · {point['name']}.", si)
+    try:
+        changed = answer_of(client.send("PATCH", f"connect/channels/{channel['id']}", json=change))
+    except ApiError as error:
+        # A counter's first mapping that doesn't fit what people wrote down: a person decides.
+        if error.status != 409:
+            raise
+        raise CliError(FIRST_MAPPING) from None
+    print_result(changed, as_json, f"{channel['key']} va ahora a {machine['name']} · {point['name']}.")
+
+
+@app.command()
+def silenciar(
+    ctx: typer.Context,
+    dispositivo: Annotated[str, typer.Argument(help="El id (d-…), el nombre o el número del dispositivo.")],
+    canal: Annotated[str, typer.Argument(help="El canal tal como lo envía.")],
+    hasta: Annotated[Optional[str], typer.Option("--hasta", help="Hasta cuándo no avisa: 05/11/2026 18:00. Sin --hasta termina el silencio.")] = None,
+    motivo: Annotated[Optional[str], typer.Option("--motivo", help="Por qué: Mantenimiento del compresor.")] = None,
+    si: YesOption = False,
+    as_json: JsonOption = False,
+):
+    """Silencia los avisos de un canal hasta una hora; las lecturas siguen."""
+    client = client_of(ctx)
+    device = client.get(f"connect/devices/{device_named(client, dispositivo)['id']}")
+    channel = channel_named(device, canal)
+    until = moment(hasta) if hasta else None
+    confirm_write(f"{'Silenciar' if until else 'Quitar el silencio de'} {device['name']} · {channel['key']}.", si)
+    changed = answer_of(client.send("POST", f"connect/channels/{channel['id']}/silence", json={"until": until, "reason": motivo or ""}))
+    print_result(changed, as_json, f"{channel['key']}: {changed.get('state_note') or 'sin silencio'}.")

{operx_cli-0.10.0 → operx_cli-0.11.0}/operx_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: operx-cli
-Version: 0.10.0
+Version: 0.11.0
 Summary: La línea de comandos de OperX: tu empresa desde la terminal, con tu token de API.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -216,6 +216,17 @@ operx chat leido mantenimiento
 Chat va solo por canales: los mensajes directos, los grupos y los archivos
 son de la app.
 
+```
+operx connect dispositivos                                  # los que envían datos de las máquinas, y su estado
+operx connect canales "Broker planta"                       # qué envía cada canal y a qué punto va
+operx connect mensajes d-7f3k2m --cuantos 5                 # lo que llegó, tal cual
+operx connect mapear d-7f3k2m planta/comp2/temp --equipo "Compresor 2" --punto "Temperatura rodamiento"
+operx connect silenciar d-7f3k2m planta/comp2/temp --hasta "05/11/2026 18:00" --motivo "Mantenimiento"
+```
+
+Las claves de los dispositivos no pasan por el CLI: se crean y se ven en la
+app, en la pestaña Clave del dispositivo.
+
 SG-SST y Ambiental van por empresa: sin `--empresa`, la de tu cuenta. Si
 llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
 `operx ambiental empresas` las listan.

{operx_cli-0.10.0 → operx_cli-0.11.0}/operx_cli.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ operx_cli/commands/campos.py
 operx_cli/commands/chat.py
 operx_cli/commands/common.py
 operx_cli/commands/completar.py
+operx_cli/commands/connect.py
 operx_cli/commands/empresas.py
 operx_cli/commands/inventario.py
 operx_cli/commands/lecturas.py
@@ -56,6 +57,7 @@ tests/test_cards.py
 tests/test_chat.py
 tests/test_client.py
 tests/test_completar.py
+tests/test_connect.py
 tests/test_daily_flows.py
 tests/test_inventario_lecturas.py
 tests/test_json_writes.py

{operx_cli-0.10.0 → operx_cli-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "operx-cli"
-version = "0.10.0"
+version = "0.11.0"
 description = "La línea de comandos de OperX: tu empresa desde la terminal, con tu token de API."
 readme = "README.md"
 requires-python = ">=3.10"

operx_cli-0.11.0/tests/test_connect.py

@@ -0,0 +1,111 @@
+"""`operx connect`: the devices, a device's channels and messages, mapping a channel
+and silencing it. Fixtures: answers copied from what a personal token gets
+(backend/connect/payloads.py; backend/connect/tests/test_api_tokens.py), taken from a
+local run on 2026-11-05, as connect/api_descriptions.py describes them."""
+
+import json
+
+import pytest
+
+from .fake_api import FakeApi, page, run
+
+POINT_HOURS = {"id": 2, "name": "Horómetro", "machine_id": 1, "machine_name": "Compresor 2", "kind": "counter", "unit": "h", "min_value": None, "max_value": None}
+POINT_TEMP = {
+    "id": 1, "name": "Temperatura rodamiento", "machine_id": 1, "machine_name": "Compresor 2", "kind": "condition", "unit": "°C",
+    "min_value": "70.0000", "max_value": "95.0000",
+}
+# GET /v1/connect/devices/ (payloads.py › device_cards)
+CARD = {
+    "id": 3, "uid": "d-fwd000001", "name": "Broker planta", "preset": "broker", "model_label": "Broker de la planta", "place_name": "Planta Yumbo",
+    "status": "active", "state": "receiving", "last_seen_at": "2026-11-05T10:39:35.188451-05:00", "silent_since": None, "last_error": "",
+    "every_minutes": 5, "channels_total": 2, "channels_mapped": 0, "main": None, "strip": ["gap", "ok"], "strip_from": "2026-11-04T11:15:36.712052-05:00",
+}
+
+
+def channel(channel_id, key, value, point=None, state="unmapped", note=""):
+    """A channel as payloads.py › channel_rows writes it."""
+    return {
+        "id": channel_id, "key": key, "label": "", "point": point, "is_active": True, "scale": "1", "offset": "0.0000", "every_minutes": 15,
+        "confirm_after": 3, "clear_after": 3, "margin": None, "wrap_at": None, "margin_used": None, "max_rise_per_hour": None,
+        "last_value": value, "last_raw": value.rstrip("0").rstrip("."), "last_value_at": "2026-11-05T10:38:15.957537-05:00", "recent": [],
+        "state": state, "state_note": note, "silenced_until": None, "alarm_id": None, "question": None,
+    }
+
+
+# GET /v1/connect/devices/3/ (payloads.py › device_detail)
+DEVICE = {
+    "id": 3, "uid": "d-fwd000001", "name": "Broker planta", "preset": "broker", "model_label": "Broker de la planta", "way": "mqtt",
+    "mqtt": {"host": "mqtt.connect.operx.pro", "port": 8883, "username": "d-fwd000001", "client_id": "d-fwd000001", "topic": "operx/d-fwd000001/up"},
+    "place_id": 1, "place_name": "Planta Yumbo", "time_zone": "America/Bogota", "use_arrival_time": False, "every_minutes": 5, "status": "active",
+    "state": "receiving", "last_seen_at": "2026-11-05T10:39:35.188451-05:00", "last_error": "", "silent_since": None,
+    "ingest_address": "https://api.operx.pro/api/v1/connect/ingest",
+    "channels": [channel(31, "planta/comp2/temp", "80.5000"), channel(32, "planta/comp2/horas", "1200.0000")],
+}
+MESSAGE = {
+    "id": 46, "received_at": "2026-11-05T10:39:35.188451-05:00", "way": "mqtt", "result": "read", "values_in": 1, "values_written": 0,
+    "values_skipped": 0, "reason": "", "alarm": None, "body": '{"readings": [{"channel": "planta/comp2/temp", "value": "80.5"}]}',
+}
+MAPPABLE = {"points": [
+    {"point": POINT_HOURS, "read_by": None, "read_by_channel": None, "in_round": None},
+    {"point": POINT_TEMP, "read_by": None, "read_by_channel": None, "in_round": None},
+]}
+# GET /v1/assets/?search= (Registros' machines; only the fields the lookup reads matter here)
+MACHINE = {"id": 1, "code": "CP-02", "name": "Compresor 2"}
+PLANT = {
+    ("GET", "assets/"): page(MACHINE),
+    ("GET", "connect/devices/"): {"devices": [CARD]},
+    ("GET", "connect/devices/3/"): DEVICE,
+    ("GET", "connect/mappable-points/"): MAPPABLE,
+}
+
+
+@pytest.fixture(autouse=True)
+def signed_in(monkeypatch):
+    monkeypatch.setenv("OPERX_TOKEN", "opx_test")
+
+
+def test_dispositivos_says_each_state_as_the_app_does():
+    result = run(FakeApi(PLANT), "connect", "dispositivos")
+    assert result.exit_code == 0, result.output
+    for text in ("d-fwd000001", "Broker planta", "Recibiendo", "Planta Yumbo"):
+        assert text in result.output
+
+
+def test_canales_shows_what_arrives_and_where_it_goes():
+    result = run(FakeApi(PLANT), "connect", "canales", "Broker planta", "--csv")
+    assert result.exit_code == 0, result.output
+    # Spanish Excel's CSV: «;» between fields, a decimal comma, no trailing zeros.
+    assert result.output.splitlines()[1].split(";")[:4] == ["planta/comp2/temp", "", "Sin asignar", "80,5"]
+
+
+def test_mensajes_shows_them_as_they_arrived():
+    fake = FakeApi({**PLANT, ("GET", "connect/devices/3/messages/"): {"messages": [MESSAGE]}})
+    result = run(fake, "connect", "mensajes", "d-fwd000001", "--json")
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.output)[0]["body"] == MESSAGE["body"]
+
+
+def test_mapear_sends_the_point_and_the_scale():
+    fake = FakeApi({**PLANT, ("PATCH", "connect/channels/31/"): channel(31, "planta/comp2/temp", "8.0500", point=POINT_TEMP, state="in_range")})
+    result = run(fake, "connect", "mapear", "d-fwd000001", "planta/comp2/temp", "--equipo", "CP-02", "--punto", "Temperatura rodamiento", "--escala", "0,1", "--si")
+    assert result.exit_code == 0, result.output
+    assert fake.sent("PATCH", "connect/channels/31/") == {"point": 1, "scale": "0.1"}
+    assert "Compresor 2 · Temperatura rodamiento" in result.output
+
+
+def test_mapear_leaves_a_counter_that_doesnt_fit_to_a_person():
+    refused = (409, {"first_mapping": {"kind": "lower", "device_value": "12.0000", "point_value": "1200.0000", "unit": "h"}})
+    fake = FakeApi({**PLANT, ("PATCH", "connect/channels/32/"): refused})
+    result = run(fake, "connect", "mapear", "d-fwd000001", "planta/comp2/horas", "--equipo", "Compresor 2", "--punto", "Horómetro", "--si")
+    assert result.exit_code != 0
+    assert "decídelo en la app" in result.output
+
+
+def test_silenciar_sends_until_when_and_why():
+    silenced = channel(31, "planta/comp2/temp", "80.5000", state="silenced", note="Silenciado hasta 18:00")
+    fake = FakeApi({**PLANT, ("POST", "connect/channels/31/silence/"): silenced})
+    result = run(fake, "connect", "silenciar", "d-fwd000001", "planta/comp2/temp", "--hasta", "05/11/2026 18:00", "--motivo", "Mantenimiento", "--si")
+    assert result.exit_code == 0, result.output
+    sent = fake.sent("POST", "connect/channels/31/silence/")
+    assert sent["reason"] == "Mantenimiento" and sent["until"].startswith("2026-11-05T18:00")
+    assert "Silenciado hasta 18:00" in result.output