Pular para o conteúdo
miblo

SDK

Apps só de alertas no Miblo: tipos, envio, teste e status

Um app do Miblo sem tela, que só avisa: screen: false, os tipos de alerta, alerts.send, test, status, chave para não repetir, horário de silêncio e cada erro.

O que é um app só de alertas

A maioria dos apps não precisa de tela: só precisa avisar quando algo acontece. Um gol, um site fora do ar, um build que quebrou, uma encomenda que saiu para entrega. Um app só de alertas é isso: não desenha cartão, não entra na vez das telas de apps e nunca fica fixo. Ele declara os tipos de alerta que manda, e a pessoa liga ou desliga cada um no app Miblo (aba Apps).

O alerta aparece por cima de qualquer tela do Miblo por alguns segundos e depois a tela volta. Os alertas do próprio Miblo ("precisa de você", uma sessão que terminou) sempre vêm primeiro: o seu espera por eles.

Em dez linhas

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' },
] });
await alerts.send({ type: 'gol', title: 'GOL do Flamengo!', text: 'Flamengo 2 x 1', key: 'jogo-123-gol-2' });

declare() registra o app como só de alertas (screen: false). Não precisa de screen(), de cartão nem de prévia.

Os tipos de alerta

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

  • id: letras minúsculas, números e -, até 16 (nunca on, off, later, test ou history). É o type de cada alerta.

  • label: o nome que a pessoa vê ao lado do interruptor, até 24 caracteres, texto ou { pt, en }.

  • level: info (o aviso) ou important (a tela pisca antes, como nos alertas do Miblo). É o máximo daquele tipo: um alerta important de um tipo info aparece como info.

  • default: ligado (true, o padrão) ou desligado até a pessoa ligar.

  • cooldownMin: opcional, 0 a 1440. Depois de um alerta desse tipo, os próximos esperam esse tanto de minutos.

send()

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

  • title até 24 caracteres (obrigatório), text até 40, seconds de 1 a 15 (padrão 8).

  • key: uma chave do acontecimento. A mesma chave dentro de dedupeMin minutos (padrão 10) vira um alerta só: a resposta é { ok: true, duplicate: true }. Use para não avisar duas vezes o mesmo gol quando o seu programa lê o placar de novo.

  • whenQuiet: o que fazer no horário de silêncio da pessoa. 'drop' (padrão) descarta; 'later' guarda (até 3 por app) e entrega quando o silêncio acaba. O padrão do cliente vem de miblo.alerts({ id, tool, whenQuiet }).

Para quem só quer disparar e seguir, trySend() (try_send() em Python) nunca lança erro: devolve { ok, code, retryAfter }.

test() e status()

await alerts.test();                 // "Teste · Placar" no Miblo, antes mesmo da permissão
const st = await alerts.status();    // permissão, tipos ligados, silêncio, quantos restam hoje

  • test({ type, title, text }) mostra um alerta com o título começando por "Teste ·". Funciona antes de a pessoa permitir os alertas (é para ver como fica), mas respeita o tipo desligado, o horário de silêncio, o intervalo de 2 minutos e 10 testes por dia.

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

Erros

Cada erro é um MibloError com um code:

  • alerts_off: a pessoa ainda não permitiu os alertas do app (asked: true: o primeiro alerta pediu a permissão no app Miblo) ou desligou (asked: false).

  • type_off: a pessoa desligou esse tipo (type).

  • quiet: é horário de silêncio; retryAfter diz em quantos segundos acaba.

  • rate_limited: retryAfter em segundos; reason diz se foi o cooldown do tipo ou o limit do app (1 a cada 2 minutos, 20 por dia).

  • bad_request com field: um título longo demais, um type que o app não declarou.

Como app da loja

Um app da comunidade só de alertas é um zip com main.js e manifest.json, como qualquer outro (Publicar na loja). No manifest, screen: false e os tipos em alerts:

JSON
{
  "id": "placar",
  "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
}

O main.js exporta run(ctx) e não devolve cartão: manda os alertas com ctx.alerts.send(...) ou os devolve em { alerts: [...] }:

JavaScript
export async function run(ctx) {
  const jogo = await ctx.fetchJson('https://site.api.espn.com/...');
  if (jogo.gols > (ctx.state.gols ?? 0)) {
    ctx.state.gols = jogo.gols;
    return { alerts: [{ type: 'gol', title: 'GOL!', text: jogo.placar, key: `${jogo.id}-${jogo.gols}` }] };
  }
  return {};
}

No assistente de envio, responda "Só manda alertas" na primeira pergunta: em vez do cartão, ele pede os tipos de alerta. Capturas de tela são opcionais (uma foto de um alerta no Miblo ajuda).

O que a pessoa controla

No app Miblo (aba Apps), um app só de alertas aparece com o selo "Alertas", sem prévia de tela:

  • Permitir alertas do app (ou não), e um interruptor por tipo.

  • Testar alerta, para ver como fica.

  • O histórico dos últimos alertas: quando, o tipo, o título, e se foi entregue ou por que não.

  • O horário de silêncio do Miblo (por exemplo, das 22:00 às 08:00), que vale para todos os apps.

No terminal: miblo apps alerts <id> on|off, miblo apps alerts <id> <tipo> on|off, miblo apps alerts <id> test, miblo apps alerts <id> history e miblo apps quiet.