Cartões: comandos da CLI

Cartões

Conheça os tipos de cartões, crie uma instância e atualize seus dados ao vivo. Uma playlist posiciona o ID do cartão retornado.

screenrig cards list --category ops
screenrig cards show gauge
screenrig card create --type gauge --file gauge-params.json
screenrig card list
screenrig card show crd_01EXAMPLEGAUGE000000000
screenrig card params crd_01EXAMPLEGAUGE000000000 --file gauge-params.json
screenrig card data get crd_01EXAMPLEGAUGE000000000
screenrig card data put crd_01EXAMPLEGAUGE000000000 --file gauge-data.json --ttl 30m --expect-rev 1
screenrig card preview crd_01EXAMPLEGAUGE000000000 --output gauge.png
screenrig card delete crd_01EXAMPLEGAUGE000000000

cards show mostra o params_schema e o data_schema do cartão, suas propriedades estáticas e dinâmicas, nível, layouts e feed, e um exemplo para copiar em uma página de playlist. card create retorna o id crd_ da instância, e uma nova execução idêntica após uma resposta perdida reutiliza a chave de idempotência salva.

card data put substitui o documento imediatamente, sem republicar a playlist. A validação do próprio cartão recusa um documento que ele não consegue mostrar (card_data_invalid), e uma expiração deixa os dados em branco em todas as telas quando nada os renova. card delete exclui a instância e seus dados, e responde resource_conflict (saída 5) enquanto uma playlist a posicionar.

card preview desenha o cartão em um Chromium ou Chrome local e grava um PNG; não publica nada. Defina SCREENRIG_BROWSER com o caminho do navegador quando nenhum dos habituais estiver instalado. data.file é o caminho gravado e data.unrendered lista o que a pré-visualização não conseguiu desenhar, como um feed do host que você não forneceu. Abra a imagem antes de publicar. Cartões embutidos descreve os layouts, as propriedades e os feeds de cada cartão.

Webhooks de cartão

Um webhook de cartão é uma URL que grava o documento de dados de um cartão, de modo que um sistema externo, como um CMS, um ponto de venda ou um script, envia dados para um cartão com um único POST HTTP. kv webhook create, list, rotate-secret e delete aceitam --card CARD_ID no lugar de --app-id, nunca os dois; update e deliveries abaixo funcionam apenas com cartões. Um cartão tem no máximo 20 webhooks.

kv webhook create --card CARD_ID [--description TEXT] [--map FILE|-] [--key-template TEMPLATE] [--signing]
                  [--verify VENDOR [--verify-secret-file FILE|-] [--verify-header NAME] [--verify-encoding hex|base64]
                   [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]] [--handshake VENDOR]
kv webhook list --card CARD_ID
kv webhook rotate-secret <webhook_id> --card CARD_ID [--signing]
kv webhook delete <webhook_id> --card CARD_ID

Criar um webhook de cartão não exige chave. --map FILE (ou - para stdin) é o mapeamento, --key-template grava documentos por chave, --signing ativa a assinatura, e --verify e --handshake aceitam as postagens próprias de um fornecedor (Assinaturas e handshakes dos fornecedores). A resposta traz data.secret e, quando o webhook assina, data.signing_secret, cada um exibido uma única vez.

O remetente se autentica como em um webhook de aplicativo: Authorization: Bearer <secret> com o segredo srkw_…, ou HTTP Basic com o ID do webhook como nome de usuário, então https://kvw_ID:srkw_…@api.screenrig.ai/… serve para um remetente que aceita apenas uma URL. O corpo, de no máximo 1 MiB, é JSON ou application/x-www-form-urlencoded; um nome de formulário repetido vira um array. Sem mapeamento, o objeto enviado é o documento de dados do cartão.

Um mapeamento é um modelo JSON que constrói o documento a partir do corpo. Uma string com marcadores como {{body.alert.title}} ou {{body.items[0].name}} é texto, e uma string que é exatamente um marcador mantém o tipo do valor. Um caminho começa com body ou query (os parâmetros de consulta da URL), e um caminho que não contém nada fica vazio no texto e omite um valor isolado. $each mapeia um array com item e index no escopo, $group com $by agrupa na ordem da primeira ocorrência, $number lê 1,234.50, $3.50, 3,50 € ou 12% (adicione "$decimal": "," para uma vírgula decimal), $bool lê true, yes, y, 1 e x, e $text com $max corta o texto. O modelo é verificado ao salvar: invalid_request indica o lugar que falhou.

{
  "title": "{{body.alert.title}}",
  "body": "{{body.alert.message}}",
  "items": { "$each": "{{body.items}}", "$limit": 20, "$template": { "text": "{{item.name}}" } }
}

curl https://api.screenrig.ai/api/cards/crd_01EXAMPLEBOARD0000000000/kv-webhooks/kvw_01EXAMPLEWEBHOOK00000/write \
  -H "Authorization: Bearer $CARD_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"alert":{"title":"Fire drill","message":"Leave by the east door"},"items":[{"name":"Floor 2"}]}'

--key-template TEMPLATE grava documentos por chave no lugar do documento próprio do cartão. O modelo é uma chave de dados do cartão com tokens {screen.field.NAME}, como room-{screen.field.room}, e o objeto mapeado (ou o corpo postado, sem mapeamento) contém apenas um array documents de objetos {fields, document}: cada objeto fields preenche o modelo e cada document é gravado na chave que ele produz. Um item de página que informa o mesmo modelo como seu data mostra a cada tela o documento dos seus próprios campos. Cada documento é verificado antes de gravar qualquer um, e uma chave repetida é recusada. Uma falha de armazenamento pode deixar parte do lote gravada: reenvie o mesmo corpo com o mesmo Idempotency-Key. As chaves que uma postagem omite mantêm seus dados, e um webhook não define expiração. Documentos por chave mostra um mapeamento.

Cada envio é verificado como dados do próprio cartão: card_data_invalid nomeia o caminho e nada é gravado. Um documento igual ao atual do cartão recebe a resposta unchanged e não grava nada, então nenhuma tela é acordada. Um envio aceito não conta no limite de solicitações de agente, um webhook aceita no máximo 120 envios por minuto e um cabeçalho Idempotency-Key deduplica as novas tentativas de um remetente por 24 horas.

Um endereço errado, um segredo errado ou ausente, um webhook desativado, uma assinatura ausente ou errada e todo GET recebem a mesma resposta 404, então uma pré-visualização de link ou um palpite não revela nada. kv webhook deliveries informa o motivo.

Com --signing, cada envio também deve levar ScreenRig-Signature: t=<unix seconds>,v1=<hex>, em que v1 é o HMAC-SHA256 de t, um ponto e o corpo bruto com o segredo de assinatura whsec_…, e t deve estar a no máximo cinco minutos do relógio do servidor. É o formato das assinaturas de webhook do próprio screenRIG.

Assinaturas e handshakes dos fornecedores

Os fornecedores assinam suas postagens do seu jeito, e alguns não conseguem enviar o seu segredo de jeito nenhum. Um webhook de cartão pode verificar a assinatura do fornecedor no lugar do segredo e responder ao handshake de configuração do fornecedor, então GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana, Microsoft Graph, monday.com, Trello e Azure Event Grid postam direto nele, sem intermediário. Qualquer outro remetente que assine com HMAC também funciona. Defina-os com --verify e --handshake em kv webhook create e altere-os com kv webhook update.

• --verify VENDOR aceita a assinatura própria de um fornecedor, com --verify-secret-file FILE (ou - para stdin, nunca como argumento) contendo o segredo que o fornecedor mostra. Para generic_hmac, --verify-header NAME nomeia o cabeçalho que carrega a assinatura, --verify-encoding é hex (o padrão) ou base64, --verify-timestamp-header NAME nomeia um cabeçalho que carrega a hora Unix, e --verify-tolerance SECONDS é o quanto ela pode se afastar do relógio do servidor (300 por padrão). Uma postagem que traz a assinatura válida do fornecedor é aceita sem o segredo srkw_ do próprio webhook, que continua funcionando ao lado. O segredo do fornecedor é armazenado selado e mostrado apenas como set e uma hint dos seus quatro últimos caracteres. Em kv webhook update, --verify sem --verify-secret-file mantém o segredo armazenado enquanto o fornecedor for o mesmo, e --clear-verify remove a verificação e seu segredo. --verify e --signing se excluem mutuamente.
• --handshake VENDOR é microsoft_graph, monday, trello ou azure_event_grid, e --clear-handshake o remove. O Slack e o Asana respondem aos próprios handshakes por --verify.

A chave de cada HMAC é o texto do segredo como o fornecedor o mostra (o do Stripe inclui whsec_). Uma assinatura é conferida no corpo exatamente como chegou, em tempo constante, antes de a postagem consumir orçamento de escrita, e é julgada antes do seu carimbo de data e hora: timestamp_stale sempre significa que o segredo estava certo. Um corpo pode ser JSON, um formulário ou multipart/form-data, em que um campo de texto é body.FIELD e os arquivos são contados, não lidos.

Um handshake só é respondido para um webhook configurado para esse fornecedor, antes de qualquer credencial ser pedida, a uma solicitação que é esse handshake, e nunca por um webhook desativado. Ele não grava nada, nunca é cobrado e não gasta orçamento de taxa. O Microsoft Graph, o monday.com, o Trello e o Azure Event Grid não enviam nenhum cabeçalho que o screenRIG verifique, então as entregas deles só são aceitas com o segredo do webhook. O Azure Event Grid o leva como um cabeçalho de entrega estático, Authorization: Bearer srkw_…, marcado como segredo, e seus eventos chegam como um array, então um mapeamento lê body[0].

echo '{"title":"{{body.repository.full_name}}","body":"{{body.head_commit.message}}"}' |
  screenrig kv webhook create --card crd_01EXAMPLEBOARD0000000000 --description "Pushes" \
    --verify github --verify-secret-file github.secret --map -

Um remetente que assina com o próprio HMAC nomeia o cabeçalho, a codificação e, se assina um carimbo de data e hora, o cabeçalho do carimbo:

echo '{"title":"{{body.sensor}}","body":"{{body.state}}"}' |
  screenrig kv webhook create --card crd_01EXAMPLEBOARD0000000000 --verify generic_hmac --verify-secret-file acme.secret \
    --verify-header X-Acme-Signature --verify-encoding base64 --verify-timestamp-header X-Acme-Time --verify-tolerance 120 \
    --map -

ts=$(date +%s); body='{"sensor":"door","state":"open"}'
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$SECRET" -binary | openssl base64 -A)
curl "$URL" -H "Content-Type: application/json" -H "X-Acme-Time: $ts" -H "X-Acme-Signature: $sig" -d "$body"

Toda falha dá o mesmo 404 de qualquer outra recusa. kv webhook deliveries mostra o motivo, e um handshake aparece com o resultado handshake:

kv webhook update <webhook_id> --card CARD_ID [--description TEXT] [--map FILE|-] [--clear-map]
                   [--key-template TEMPLATE] [--clear-key-template] [--enable|--disable] [--signing|--no-signing]
                   [--verify VENDOR [--verify-secret-file FILE|-] [--verify-header NAME] [--verify-encoding hex|base64]
                    [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]] [--clear-verify]
                   [--handshake VENDOR] [--clear-handshake]

screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --map alert-map.json
screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --verify stripe --verify-secret-file stripe.secret
screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --clear-verify

kv webhook deliveries <webhook_id> --card CARD_ID [--limit N]

screenrig kv webhook deliveries kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000