@oakvini/shipio-electron

SDK oficial do ShipIO para Electron.

Recursos atuais:

• check de update no startup
• dialog de update customizavel
• download com retry e verificacao SHA256
• crash reporting
• eventos de ciclo de vida
• suporte a metadados de release vindos do backend (installer_type e install_support_level)

Instalacao

npm install @oakvini/shipio-electron

Uso basico

const { app } = require('electron')
const { ShipIO } = require('@oakvini/shipio-electron')

await ShipIO.init({
  apiKey: process.env.SHIPIO_API_KEY,
  version: app.getVersion(),
  channel: 'stable',
})

O que acontece no init()

Ao iniciar:

1. envia crash pendente do ultimo run, se existir
2. registra handlers de crash
3. envia evento launched
4. chama /v1/check-update
5. se houver update e o dialog estiver habilitado, mostra o dialog do ShipIO

API publica

ShipIO.init(options)

| Campo | Tipo | Obrigatorio | Descricao | | --- | --- | --- | --- | | apiKey | string | sim | API key do app | | version | string | sim | versao atual do app | | channel | stable \| beta \| canary | nao | canal de update | | dialog | object | nao | configuracao visual do dialog | | installerArgs | string[] | nao | override manual de argumentos do instalador |

ShipIO.checkUpdate()

Retorna o payload do backend ou null.

Exemplo:

{
  has_update: true,
  version: '2.5.0',
  download_url: 'https://...',
  file_size: 52428800,
  file_hash: 'sha256:...',
  changelog: 'Bug fixes',
  mandatory: false,
  installer_type: 'nsis',
  install_support_level: 'installer_handoff'
}

ShipIO.showDialog(update)

Mostra o dialog built-in do ShipIO.

Retorno:

• 'update'
• 'later'
• 'closed'

ShipIO.applyUpdate(update)

Baixa o binario e executa o fluxo de update com base no contrato da release.

ShipIO.downloadUpdate(update, onProgress?)

Baixa o arquivo e retorna o caminho local.

ShipIO.getLogPath()

Retorna o caminho do arquivo de log do updater.

ShipIO.sendCrash(error)

Envia um crash manualmente.

Segurança do dialog

O dialog embutido agora roda com isolamento real do renderer:

• nodeIntegration desativado
• contextIsolation ativado
• bridge mínima via preload
• renderer sem require('electron') nem acesso direto a Node

O HTML do dialog continua recebendo apenas a bridge de:

• sendUpdate()
• sendLater()
• onProgress(listener)

Tratamento de erro HTTP

Chamadas do SDK para o backend agora falham explicitamente quando a API responde com status nao-2xx.

• respostas 4xx/5xx nao sao mais tratadas como payload valido
• o SDK extrai message, code e details do envelope de erro quando presentes
• fluxos como init(), sendCrash() e checkForUpdates() continuam fazendo catch onde apropriado, mas agora recebem um erro real

Contrato de instalador

O SDK agora trata o backend como fonte de verdade para a estrategia de update.

Campos relevantes retornados por /v1/check-update:

• installer_type
• install_support_level

Isso evita inferencia fraca so por extensao do arquivo.

installer_type

| Valor | Significado | | --- | --- | | nsis | instalador Windows NSIS | | inno | instalador Windows Inno Setup | | msi | pacote MSI | | exe_generic | executavel Windows sem suporte oficial forte | | appimage | AppImage Linux | | dmg | imagem DMG | | pkg | pacote PKG | | deb | pacote DEB | | zip_generic | distribuicao ZIP |

install_support_level

| Valor | Significado | | --- | --- | | fully_managed | o SDK controla aplicacao e relaunch | | installer_handoff | o SDK baixa, abre o instalador e encerra o app | | manual | o SDK apenas baixa e revela o arquivo |

Comportamento por plataforma

AppImage

• fluxo fully_managed
• usa staging
• troca o binario
• relanca explicitamente o app

NSIS / Inno / MSI

• fluxo normalmente installer_handoff
• o SDK baixa e abre o instalador
• o app atual e encerrado
• a conclusao depende do instalador

DMG

• o SDK monta o DMG
• copia o .app quando encontra bundle valido
• relanca quando o fluxo e controlado

DEB / PKG

• o SDK entrega ao instalador do sistema
• nao promete confirmar a conclusao da instalacao

ZIP

• fluxo manual
• o SDK nao promete instalar
• o arquivo e deixado pronto para uso manual

Garantias e limites

O SDK nao promete "100% auto update" para qualquer instalador.

Hoje a leitura correta e:

• fully_managed: o ShipIO controla o fluxo inteiro
• installer_handoff: o ShipIO controla download e handoff, nao o instalador
• manual: o ShipIO distribui o artefato, nao instala

Dialog de update

Temas embutidos:

• default
• minimal

Exemplo:

ShipIO.init({
  apiKey: '...',
  version: app.getVersion(),
  dialog: {
    theme: 'minimal',
    title: 'Atualizacao disponivel',
    updateButton: 'Atualizar agora',
    downloadingText: 'Baixando...',
    installingText: 'Instalando...',
    launchingInstallerText: 'Abrindo instalador...',
    restartingText: 'Reiniciando...',
    manualReadyText: 'Arquivo pronto para instalacao manual',
  },
})

UI propria

await ShipIO.init({
  apiKey: '...',
  version: app.getVersion(),
  dialog: { enabled: false },
})

const update = await ShipIO.checkUpdate()

if (update?.has_update) {
  await ShipIO.applyUpdate(update)
}

Seguranca

O SDK inclui:

• verificacao SHA256 do arquivo
• limite maximo de download
• sanitizacao do HTML do dialog
• canais IPC unicos por dialog
• execFileSync no macOS em vez de shell interpolado

Crash reporting

Crashes automaticos:

• uncaughtException
• unhandledRejection

Persistencia local:

• install id em userData/.shipio_id
• crash pendente em userData/.shipio_crash.json
• log do updater em userData/shipio-updater.log

Eventos enviados

Atualmente o SDK envia:

• launched
• updated apenas quando o fluxo gerenciado realmente avancou ao ponto esperado

Desenvolvimento local

Para apontar para backend local:

SHIPIO_URL=http://localhost:3000 npm run dev

Default:

https://api.shipio.dev

Limitacoes atuais

• nao ha script build neste pacote
• installer_handoff depende do comportamento do instalador externo
• o SDK Python agora cobre a mesma API publica principal, mas o dialog built-in dele e mais simples e a ergonomia ainda e menos rica que no Electron