Saltar al contenido
miblo

SDK

Apps del Desk solo de alertas: tipos, envío, prueba y estado

Una app del Desk sin pantalla que solo alerta: screen: false, los tipos de alerta, alerts.send, test, status, una clave contra repeticiones, horas de silencio y cada error.

Qué es una app solo de alertas

La mayoría de las apps no necesitan una pantalla: solo necesitan avisar cuando algo pasa. Un gol, un sitio caído, un build roto, un paquete en camino de entrega. Una app solo de alertas es justo eso: no dibuja ninguna tarjeta, nunca toma un turno entre las pantallas de apps y nunca se fija. Declara los tipos de alerta que envía, y la persona activa o desactiva cada uno en Miblo Hub (pestaña Apps del Desk).

La alerta se muestra sobre lo que Miblo esté mostrando durante unos segundos, y luego vuelve la pantalla. Las alertas propias de Miblo ("te necesita", una sesión terminada) siempre van primero: la tuya espera por ellas.

En diez líneas

import { MibloStatus } from '@miblo/status';

const miblo = new MibloStatus();
const alerts = miblo.alerts({ id: 'placar', tool: 'Placar' });
await alerts.declare({ name: 'Placar', types: [
  { id: 'gol', label: { pt: 'Gol', en: 'Goal' }, level: 'important' },
  { id: 'fim', label: { pt: 'Fim de jogo', en: 'Full time' }, level: 'info' },
] });
const r = await alerts.trySend({ type: 'gol', title: 'GOAL: Flamengo!', text: 'Flamengo 2 x 1', key: 'match-123-goal-2' });
if (!r.ok) console.log(r.code, r.message);   // alerts_off until the person allows the app's alerts

declare() registra la app como solo de alertas (screen: false). No hace falta screen(), tarjeta ni vista previa.

Permite las alertas primero. Las alertas de una app están apagadas hasta que la persona las permite. El primer envío lo pregunta: Miblo Hub le pide a la persona que las permita, y hasta entonces cada alerta responde alerts_off (con send() lanza un error; trySend() lo devuelve). Permítelas en Miblo Hub (Apps del Desk → Permitir alertas) o escribe miblo apps alerts placar on en tu propia terminal: un agente de IA no puede permitir alertas por ti. Luego ejecuta el programa de nuevo.

Los tipos de alerta

Cada tipo es { id, label, level, default, cooldownMin }, de 1 a 8 por app:

  • id: letras minúsculas, dígitos y -, hasta 16 (nunca on, off, later, test ni history). Es el type de cada alerta.

  • label: el nombre que la persona ve junto al interruptor, hasta 24 caracteres, texto o { pt, en }.

  • level: info (el aviso) o important (la pantalla destella primero, como las alertas propias de Miblo). Es el máximo de ese tipo: una alerta important de un tipo info se muestra como info.

  • default: activado (true, por defecto) o apagado hasta que la persona lo active.

  • cooldownMin: opcional, de 0 a 1440. Después de una alerta de este tipo, las siguientes esperan esa cantidad de minutos.

send()

alerts.send({ type, title, text, level, seconds, key, dedupeMin, whenQuiet }) (también alerts.alert()):

  • title hasta 24 caracteres (obligatorio), text hasta 40, seconds de 1 a 15 (por defecto 8).

  • key: una clave para el evento. La misma clave dentro de dedupeMin minutos (por defecto 10) es una sola alerta: la respuesta es { ok: true, duplicate: true }. Úsala para que el mismo gol nunca se avise dos veces cuando tu programa vuelva a leer el marcador.

  • whenQuiet: qué hacer durante las horas de silencio de la persona. 'drop' (por defecto) la descarta; 'later' la guarda (hasta 3 por app) y la entrega cuando terminan las horas de silencio. El valor por defecto del cliente viene de miblo.alerts({ id, tool, whenQuiet }).

Para programas de los que se lanza y se olvida, trySend() (try_send() en Python) nunca lanza un error: devuelve la respuesta con ok: true, o { ok: false, code, message, retryAfter? } (retry_after en Python).

test() y status()

await alerts.test();                 // "Teste · Gol" on the Miblo, even before permission
const st = await alerts.status();    // permission, types on, quiet hours, how many left today

  • test({ type, title, text }) muestra una alerta titulada "Teste · " (o "Test · ", en el idioma que habla Miblo) seguida de tu title, si no del nombre del tipo (el primer tipo que esté activado), si no del nombre de la app. Funciona antes de que la persona permita las alertas (está para ver cómo se ve), pero respeta un tipo apagado, las horas de silencio y 10 pruebas al día, y comparte con las alertas reales el intervalo de 2 minutos de la app: un envío o una prueba justo después de una recibe rate_limited. Las pruebas no cuentan para las 20 al día.

  • status() devuelve { permission, types: [{ id, label, level, on }], quiet: { on, from, to, active, endsInS }, limit: { left, nextInS }, queued, last }.

Errores

Cada error es un MibloError con un code:

  • alerts_off: la persona aún no permitió las alertas de la app (asked: true: la primera alerta se lo preguntó en Miblo Hub) o las apagó (asked: false).

  • type_off: la persona apagó ese tipo (type).

  • quiet: son horas de silencio; retryAfter dice en cuántos segundos terminan.

  • rate_limited: retryAfter en segundos; reason dice si fue el cooldown del tipo o el limit de la app (1 cada 2 minutos, 20 al día). Todas las apps del computador comparten además un solo balde: 5 a la vez, luego 1 cada 10 s.

  • bad_request con field: un type que la app no declaró, un level o seconds fuera de rango, un título o texto que empieza como uno de los avisos propios de Miblo. Un título o texto demasiado largo se corta (24 y 40 caracteres), no se rechaza.

Como app de la tienda de apps del Desk

Una app de la comunidad solo de alertas es un zip con main.js y manifest.json, como cualquier otra (Publicar en la tienda de apps del Desk). En el manifest, screen: false y los tipos en alerts:

JSON
{
  "id": "placar",
  "api": 2,
  "name": { "pt": "Placar", "en": "Score" },
  "promise": { "pt": "Avisa os gols do seu time", "en": "Tells you your team's goals" },
  "screen": false,
  "alerts": [
    { "id": "gol", "label": { "pt": "Gol", "en": "Goal" }, "level": "important", "default": true },
    { "id": "fim", "label": { "pt": "Fim de jogo", "en": "Full time" }, "level": "info", "default": true }
  ],
  "settings": [],
  "network": ["site.api.espn.com"],
  "intervalMs": 60000
}

main.js exporta run(ctx) y no devuelve ninguna tarjeta: envía alertas con ctx.alerts.send(...) o las devuelve en { alerts: [...] }:

JavaScript
export async function run(ctx) {
  const match = await ctx.fetchJson('https://site.api.espn.com/...');
  const before = ctx.state.goals ?? match.goals;   // the first run only takes note of the score
  ctx.state.goals = match.goals;
  if (match.goals > before) {
    return { alerts: [{ type: 'gol', title: 'GOAL!', text: match.score, key: `${match.id}-${match.goals}` }] };
  }
  return {};
}

ctx.state vive en memoria: tras un reinicio empieza vacío, por eso la primera ejecución de arriba solo toma nota del marcador (y la key evita que una repetición se muestre dentro de 10 minutos). Para conservar algo entre reinicios, usa ctx.cached(key, ttlMs, fetcher) o un archivo en ctx.stateDir. Una ejecución puede devolver como máximo 3 alertas; ctx.alerts.send() también funciona.

En el asistente de envío, responde "Solo envía alertas" a la primera pregunta: en vez de la tarjeta, pide los tipos de alerta. Las capturas de pantalla son opcionales (ayuda una foto de una alerta en el Miblo).

Lo que controla la persona

En Miblo Hub (pestaña Apps del Desk), una app solo de alertas aparece con una insignia "Alertas" y sin vista previa de pantalla:

  • Permitir alertas de la app (o no), y un interruptor por tipo.

  • Probar alerta, para ver cómo se ve.

  • El historial de las últimas alertas: cuándo, el tipo, el título, y si se entregó o por qué no.

  • Las horas de silencio del Miblo (digamos, de 22:00 a 08:00), que retienen las alertas de todas las apps.

En una terminal (permitiendo las alertas solo en la tuya, nunca a través de un agente de IA): miblo apps alerts <id> on|off|later, miblo apps alerts <id> <type> on|off, miblo apps alerts <id> test, miblo apps alerts <id> history y miblo apps quiet.