SDK

SDK do Miblo: programas e apps na tela do Miblo

Documentação do SDK do Miblo: a Status API no seu computador, o token, a tela App, os apps e a publicação na loja. TypeScript e Python, nada sai do computador.

O que é

O SDK do Miblo deixa os seus próprios programas aparecerem no Miblo: um script de build, um job de dados, um robô que vigia um site, uma IA que o Miblo não conecta. Um programa pode:

virar uma sessão no aparelho, no app Miblo e no celular (trabalhando, precisa de você, parada ou concluída), com aviso quando precisa de você;
pôr uma mensagem curta na tela, iniciar um foco (Pomodoro) ou um timer;
desenhar a tela App, uma tela do rodízio do Miblo que é só dele: um card com números, anéis, barras e gráficos, uma imagem de fundo, ou os dois;
virar um app: com nome, configurações que a pessoa preenche no app Miblo e o Miblo cuidando de rodá-lo. Os apps oficiais do Miblo (Processador, Bitcoin e Cripto e os que vêm com cada versão) são exatamente isso.

O SDK faz status e nada mais. Ele não aprova, não responde e não inicia tarefas nas suas IAs, e nada nele liga essas funções. É a regra do Miblo: ele mostra, não interfere.

Há dois pacotes, com a mesma API: @miblo/status para Node.js 20+ (TypeScript, com tipos, sem dependências) e miblo-status para Python 3.9+ (só a biblioteca padrão). Qualquer outra linguagem fala o mesmo protocolo: está tudo na referência.

Como funciona

A ponte do Miblo (o bridge) é o processo do Miblo que já roda no seu computador: é ela que conversa com as suas ferramentas de IA, com o aparelho e com o celular. Ela abre a Status API v1 só em 127.0.0.1:47821, a sua própria máquina.
Seu programa fala com a ponte por HTTP local, com um token só de status que você entrega a ele (miblo sdk token). Cada pedido leva um desafio de uso único assinado com HMAC-SHA256, e cada resposta vem assinada de volta: o programa sabe que falou com o Miblo, e a ponte sabe que o programa tem o token.
A ponte valida tudo (tamanhos, limites, frases reservadas do Miblo) e repassa ao aparelho pela sua rede local, com o pareamento dele, e ao app Miblo e ao celular, junto com o status que eles já recebem (no celular, cifrado de ponta a ponta).
O aparelho desenha. Um card vira pixels no próprio Miblo, com as fontes e cores dele; uma imagem é convertida no computador para o formato do Miblo antes de ir.

O token

O token (miblo_sdk_ + 64 caracteres hexadecimais) é separado da chave da ponte: ele só alcança as rotas /sdk/v1/*. Com ele um programa mostra status; não lê comandos, prompts, arquivos, custos ou nada do Miblo+, não aprova nada e não mexe em configurações do aparelho. Se vazar (um log de CI, um script compartilhado), o vazamento fica limitado a status e miblo sdk token --rotate encerra.

Você pega o token no terminal (miblo sdk token) ou no app Miblo → Programas (SDK). Os detalhes estão em Instalação.

O que dá para fazer

Quero...	Use	Página
Mostrar que meu script está rodando e avisar quando precisar de mim	`session()`, `needsYou()`, `done()`	Sessões e status
Pôr uma mensagem, um foco ou um timer no aparelho	`say()`, `focus()`, `timer()`	Sessões e status
Saber quem está trabalhando e quem precisa de mim	`snapshot()`	Sessões e status
Desenhar uma tela própria com números e gráficos	`screen.card()`, `screen.layer()`	A tela App
Ter configurações que a pessoa preenche no app Miblo	`app.declare()`, `app.settings`	Apps e configurações
Ler a agenda da conta Google ou Microsoft da pessoa	`app.connect`	Apps e configurações
Deixar o Miblo rodar meu programa sempre	`miblo apps add`	Instalação
Publicar meu app na loja	miblo.ai/apps	Publicar na loja

Por onde começar

Instale o pacote e pegue o token, e rode o primeiro programa (10 linhas).
Leia Sessões e status para avisos, e A tela App para desenhar.
Quer que outras pessoas usem? Transforme em app e publique na loja.

Versões

A API v1 nunca quebra: campos só são acrescentados, nenhum é removido ou muda de sentido, nenhum limite fica mais rígido. Uma mudança incompatível iria para /sdk/v2/, com a v1 mantida ao lado.
Os pacotes seguem semver, e todo 1.x fala a v1. A tela App precisa do Miblo 1.25 ou mais novo no computador e no aparelho (um aparelho mais antigo responde unsupported).
Os pacotes saem só do miblo.ai (não estão no npm nem no PyPI), com assinatura Ed25519 ao lado de cada arquivo.

O que é#

Como funciona#

O token#

O que dá para fazer#

Por onde começar#