Pular para o conteúdo principal

Referência do SDK

O SDK de mini-programas é uma biblioteca JavaScript de ~2 KB que é injetada em todo iframe de mini-programa. Ele fornece o namespace window.ais com métodos para interagir com a plataforma AISCouncil através de uma bridge postMessage segura.

Como o SDK Funciona​

O SDK é injetado como uma tag <script> antes do HTML do seu app no srcdoc do iframe. Você não precisa incluí-lo você mesmo -- ele está sempre disponível como window.ais quando seu código roda.

Toda chamada de método (exceto propriedades platform.*) envia uma mensagem para a página host e retorna uma Promise. O host valida permissões, executa a requisição e envia o resultado de volta.

Seu código de app             SDK                    Plataforma host
      |                        |                          |
      |-- ais.chat.send("oi")-->|                          |
      |                        |-- postMessage({           |
      |                        |     method: "chat.send",  |
      |                        |     args: {text: "oi"}    |
      |                        |   }) ---------------------->|
      |                        |                          |-- verifica permissões
      |                        |                          |-- executa AIS.Chat.send()
      |                        |<-- postMessage({result}) --|
      |<-- Promise resolve ----|                          |
informação

Todos os métodos do SDK estão disponíveis sincronamente como referências de função, mas retornam Promises que resolvem assincronamente. Sempre use await ou .then() para obter resultados.

Suporte TypeScript​

Definições de tipos TypeScript estão disponíveis em sdk/ais.d.ts. Adicione uma referência ao seu projeto:

/// <reference path="./ais.d.ts" />

ais.ready(async () => {
  const history = await ais.chat.getHistory(10);
  // history é tipado como ais.ChatMessage[]
});

Ou copie os tipos AisManifest e AisPermission para validação de manifest em suas ferramentas de build.

Ciclo de Vida​

ais.ready(callback)​

Registra um callback que dispara quando a bridge da plataforma está conectada e pronta. Este é o ponto de entrada do seu app -- envolva toda lógica de inicialização dentro deste callback.

ParâmetroTipoDescrição
callback() => voidFunção para chamar quando a bridge estiver pronta
ais.ready(async function () {
  // Plataforma está conectada, chamadas do SDK funcionarão agora
  const user = await ais.auth.getUser();
  document.getElementById("greeting").textContent = "Olá, " + user.name;
});
cuidado

Não chame outros métodos ais.* antes de ais.ready() disparar. A bridge postMessage pode não estar estabelecida ainda, e as chamadas travarão indefinidamente.

ais.onShow(callback)​

Registra um callback que dispara cada vez que o mini-programa se torna visível (ex: usuário volta para a aba do app).

ParâmetroTipoDescrição
callback() => voidFunção para chamar ao mostrar
ais.onShow(function () {
  // Atualiza dados quando o usuário retorna ao app
  refreshDashboard();
});

ais.onHide(callback)​

Registra um callback que dispara quando o mini-programa é escondido (ex: usuário muda para chat ou outro app).

ParâmetroTipoDescrição
callback() => voidFunção para chamar ao esconder
ais.onHide(function () {
  // Pausa operações custosas
  stopPolling();
});

ais.close()​

Fecha o mini-programa e retorna à visualização de chat. O iframe é destruído após esta chamada.

Retorna: Promise<boolean>

document.getElementById("done-btn").addEventListener("click", function () {
  ais.close();
});

Armazenamento​

Armazenamento chave-valor isolado por app com backing em IndexedDB. Chaves são automaticamente namespaced com mp:{app-name}: então apps não podem acessar dados uns dos outros.

Permissão: Sempre permitido -- nenhuma permissão requerida.

ais.storage.get(key)​

Recupera um valor por chave. Retorna undefined se a chave não existe.

ParâmetroTipoDescrição
keystringA chave de armazenamento

Retorna: Promise<unknown> -- o valor armazenado, ou undefined

const count = await ais.storage.get("visit-count");
console.log("Visitas:", count); // number, string, object, array, ou undefined

ais.storage.set(key, value)​

Armazena um par chave-valor. O valor pode ser qualquer tipo serializável em JSON (string, number, boolean, object, array, null).

ParâmetroTipoDescrição
keystringA chave de armazenamento
valueunknownO valor para armazenar (deve ser serializável em JSON)

Retorna: Promise<boolean> -- true em sucesso

await ais.storage.set("visit-count", 42);
await ais.storage.set("preferences", { theme: "dark", fontSize: 16 });

ais.storage.remove(key)​

Remove uma chave do armazenamento.

ParâmetroTipoDescrição
keystringA chave para remover

Retorna: Promise<boolean> -- true em sucesso

await ais.storage.remove("temporary-data");

ais.storage.keys()​

Lista todas as chaves armazenadas por este mini-programa (sem o prefixo interno mp:{name}:).

Retorna: Promise<string[]>

const keys = await ais.storage.keys();
console.log("Chaves armazenadas:", keys); // ['visit-count', 'preferences']

Chat​

Lê histórico de chat, envia mensagens e subscreve a novas mensagens na conversa ativa.

Permissões requeridas: chat:read para leitura, chat:write para envio.

ais.chat.getHistory(limit?)​

Obtém mensagens recentes da sessão de chat ativa.

ParâmetroTipoPadrãoDescrição
limitnumber50Número máximo de mensagens a retornar

Retorna: Promise<ChatMessage[]>

interface ChatMessage {
  role: "user" | "assistant" | "system";
  content: string;
  timestamp?: number;
}
const messages = await ais.chat.getHistory(20);
messages.forEach(function (msg) {
  console.log(msg.role + ": " + msg.content);
});

ais.chat.send(text)​

Envia uma mensagem como o usuário. Isso dispara o modelo de IA ativo para gerar uma resposta.

ParâmetroTipoDescrição
textstringO texto da mensagem para enviar

Retorna: Promise<boolean> -- true em sucesso

await ais.chat.send("Resuma as últimas 5 mensagens");
aviso

Chamar ais.chat.send() dispara uma chamada de API real para o provedor de IA configurado pelo usuário. Isso consome tokens e pode incorrer em custos. Use com responsabilidade e sempre informe o usuário antes de enviar mensagens programaticamente.

ais.chat.onMessage(callback)​

Subscreve a novas mensagens de chat. O callback dispara para toda nova mensagem (tanto do usuário quanto do assistente).

ParâmetroTipoDescrição
callback(msg: ChatMessage) => voidHandler para mensagens recebidas
ais.chat.onMessage(function (msg) {
  if (msg.role === "assistant") {
    // Modelo de IA respondeu
    updateResponseDisplay(msg.content);
  }
});

Config​

Lê a configuração do bot ativo (provedor, modelo, prompt de sistema, etc.).

Permissão requerida: config:read

ais.config.get()​

Obtém o objeto completo de configuração do bot.

Retorna: Promise<BotConfig>

interface BotConfig {
  n?: string; // Nome do bot
  p?: string; // ID do provedor (ex: 'anthropic', 'openai', 'gemini')
  m?: string; // ID do modelo (ex: 'claude-sonnet-4-20250514')
  s?: string; // Prompt de sistema
  t?: number; // Temperatura (0.0 - 2.0)
  x?: number; // Max tokens de saída
  [key: string]: unknown;
}
const config = await ais.config.get();
console.log("Usando modelo:", config.m);
console.log("Prompt de sistema:", config.s);

ais.config.getProvider()​

Obtém o ID do provedor ativo.

Retorna: Promise<string> -- ex: 'anthropic', 'openai', 'gemini', 'xai', 'openrouter', 'ollama'

const provider = await ais.config.getProvider();
if (provider === "ollama") {
  showLocalModelBanner();
}

ais.config.getModel()​

Obtém o ID do modelo ativo.

Retorna: Promise<string> -- ex: 'claude-sonnet-4-20250514', 'gpt-4o', 'gemini-2.5-flash'

const model = await ais.config.getModel();
document.getElementById("model-name").textContent = model;

UI​

Mostra notificações, diálogos de confirmação e atualiza o título do painel de apps.

ais.ui.toast(message, duration?)​

Exibe uma notificação toast temporária na UI da plataforma.

ParâmetroTipoPadrãoDescrição
messagestring--Texto da notificação (máx 200 caracteres)
durationnumber3000Duração em milissegundos

Retorna: Promise<boolean>

Permissão: ui:toast (recomendada mas não estritamente exigida -- toast é de baixo impacto)

await ais.ui.toast("Arquivo salvo com sucesso!");
await ais.ui.toast("Processando...", 5000); // toast de 5 segundos

ais.ui.confirm(title, message)​

Mostra um diálogo de confirmação e aguarda a resposta do usuário.

ParâmetroTipoDescrição
titlestringTítulo do diálogo (máx 100 caracteres)
messagestringTexto do corpo do diálogo (máx 500 caracteres)

Retorna: Promise<boolean> -- true se usuário clicou OK, false se cancelou

Permissão requerida: ui:modal

const confirmed = await ais.ui.confirm(
  "Deletar todos os dados?",
  "Isso removerá permanentemente todos os itens salvos. Esta ação não pode ser desfeita.",
);
if (confirmed) {
  await clearAllData();
}

ais.ui.setTitle(title)​

Define o texto exibido na barra de título do painel de apps.

ParâmetroTipoDescrição
titlestringTexto do título (máx 100 caracteres)

Retorna: Promise<boolean>

ais.ui.setTitle("Contador de Palavras - 1.234 palavras");

Auth​

Lê informações sobre o usuário atualmente logado.

Permissão requerida: auth:read

ais.auth.getUser()​

Obtém as informações de perfil do usuário atual.

Retorna: Promise<UserInfo | null> -- null se não estiver logado

interface UserInfo {
  name: string; // Nome de exibição
  email: string; // Endereço de email
  picture: string; // URL da foto de perfil
}
const user = await ais.auth.getUser();
if (user) {
  document.getElementById("avatar").src = user.picture;
  document.getElementById("name").textContent = user.name;
} else {
  document.getElementById("name").textContent = "Convidado";
}

ais.auth.getTier()​

Obtém o nível de assinatura do usuário.

Retorna: Promise<string> -- ex: 'free', 'pro', 'team'

const tier = await ais.auth.getTier();
if (tier === "free") {
  showUpgradePrompt();
}

Secrets​

Lê e escreve chaves de API para cenários de transferência dispositivo-para-dispositivo. Esta é uma API privilegiada usada por apps como Device Sync.

Permissão requerida: secrets:sync

cuidado

A permissão secrets:sync concede acesso às chaves de API armazenadas do usuário. Solicite esta permissão apenas se seu app genuinamente precisa transferir ou fazer backup de credenciais. Usuários verão um aviso claro no diálogo de permissão.

ais.secrets.list()​

Lista nomes de provedores que têm chaves de API armazenadas.

Retorna: Promise<string[]> -- ex: ['anthropic', 'openai', 'gemini']

ais.secrets.get(provider)​

Obtém um valor de chave de API por nome de provedor.

ParâmetroTipoDescrição
providerstringNome do provedor (ex: 'anthropic', 'openai')

Retorna: Promise<string | null>

ais.secrets.set(provider, value)​

Armazena uma chave de API para um provedor.

ParâmetroTipoDescrição
providerstringNome do provedor
valuestringValor da chave de API (máx 1024 caracteres)

Retorna: Promise<boolean>

Sync​

Sincroniza perfis, configurações e sinalização WebRTC para transferência dispositivo-para-dispositivo.

Permissão requerida: secrets:sync

ais.sync.getProfiles()​

Obtém todos os perfis de usuário da plataforma host.

Retorna: Promise<Profile[]>

ais.sync.setProfiles(profiles)​

Importa perfis para a plataforma host.

ParâmetroTipoDescrição
profilesProfile[]Array de objetos de perfil para importar

Retorna: Promise<number> -- contagem de perfis importados

ais.sync.getSettings()​

Obtém configurações do app (tema, locale, etc.) do host.

Retorna: Promise<Record<string, string>>

ais.sync.setSettings(settings)​

Escreve configurações do app no host.

ParâmetroTipoDescrição
settingsRecord<string, string>Configurações chave-valor para escrever

Retorna: Promise<boolean>

ais.sync.signal(code, type, sdp)​

Posta uma oferta/resposta SDP para o relay da API para sinalização WebRTC.

ParâmetroTipoDescrição
codestringCódigo de pareamento
type'offer' | 'answer'Tipo SDP
sdpRTCSessionDescriptionInitDados SDP

Retorna: Promise<boolean>

ais.sync.pollSignal(code, type)​

Poll para uma oferta/resposta SDP do relay da API.

ParâmetroTipoDescrição
codestringCódigo de pareamento
type'offer' | 'answer'Tipo SDP para poll

Retorna: Promise<RTCSessionDescriptionInit | null>

Hooks​

Registra e dispara eventos de hook customizados para estender comportamento da plataforma ou comunicar entre apps.

Permissões requeridas: hooks:action para disparar eventos, hooks:filter para registrar handlers de filtro.

ais.hooks.on(hookName, handler)​

Escuta um evento de hook nomeado.

ParâmetroTipoDescrição
hookNamestringNome do hook (ex: 'chat:before-send')
handler(data: unknown) => voidHandler do evento

Retorna: Promise<boolean>

ais.hooks.on("chat:before-send", function (data) {
  console.log("Mensagem prestes a ser enviada:", data);
});

ais.hooks.fire(hookName, data?)​

Dispara um evento de hook nomeado. Todos os handlers registrados para este hook serão chamados.

ParâmetroTipoDescrição
hookNamestringNome do hook para disparar
dataunknownPayload de dados opcional

Retorna: Promise<unknown>

await ais.hooks.fire("my-app:data-updated", { count: 42 });

Pages​

Publica páginas web em bcz.co com um slug customizado. Usado pelo mini-programa App Builder.

Permissão requerida: pages:publish

ais.pages.getInfo()​

Obtém informações sobre a página publicada do usuário.

Retorna: Promise<PageInfo>

interface PageInfo {
  slug: string | null;
  url: string | null;
  title: string | null;
  updatedAt: number | null;
  hasPage: boolean;
}

ais.pages.claim(slug)​

Reivindica um slug (username) para bcz.co/@slug.

ParâmetroTipoDescrição
slugstringSlug desejado

Retorna: Promise<{ slug: string; url: string }>

ais.pages.publish(specBase64, opts?)​

Publica ou atualiza uma página. O spec é um documento PDL codificado em base64.

ParâmetroTipoDescrição
specBase64stringSpec de página codificado em base64
opts{ title?: string; description?: string }Metadados opcionais

Retorna: Promise<PublishResult>

ais.pages.unpublish()​

Despublica e libera o slug.

Retorna: Promise<boolean>

Informações da Plataforma​

Propriedades somente leitura com metadados da plataforma. Estas são síncronas -- sem Promise, sem permissão requerida.

ais.platform.version​

A string de versão da plataforma (semver).

Tipo: string -- atualmente '1.0.0'

ais.platform.abi​

O número de versão da ABI. Usado para verificar compatibilidade entre o SDK e a plataforma host.

Tipo: number -- atualmente 1

if (ais.platform.abi !== 1) {
  ais.ui.toast("Este app requer versão de ABI 1");
  ais.close();
}

Tratamento de Erros​

Todas as chamadas do SDK que requerem permissões rejeitarão com um erro PermissionDenied se o app não tiver a permissão necessária:

try {
  const history = await ais.chat.getHistory();
} catch (err) {
  if (err.message.includes("PermissionDenied")) {
    console.log("App não tem permissão chat:read");
  }
}

Métodos desconhecidos retornam um erro com a mensagem Unknown method: {method}.

Se a plataforma host encontra um erro inesperado, a Promise rejeita com a string da mensagem de erro.

dica

Sempre envolva chamadas do SDK em blocos try/catch, especialmente para APIs controladas por permissão. Isso torna seu app resiliente mesmo se a versão da plataforma do usuário diferir da que você testou.

Exemplo Completo​

Um app mínimo que usa múltiplas funcionalidades do SDK:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      body {
        font-family: system-ui;
        padding: 16px;
        color: #e0e0e0;
        background: #1a1a2e;
      }
      button {
        min-height: 48px;
        padding: 8px 16px;
        font-size: 16px;
        border: 1px solid #444;
        border-radius: 6px;
        background: #2a2a4e;
        color: #e0e0e0;
        cursor: pointer;
      }
      button:hover {
        background: #3a3a5e;
      }
      pre {
        background: #111;
        padding: 12px;
        border-radius: 6px;
        overflow: auto;
      }
    </style>
  </head>
  <body>
    <h2>Inspetor de Chat</h2>
    <button id="load">Carregar Histórico</button>
    <button id="close">Fechar</button>
    <pre id="output">Clique "Carregar Histórico" para começar...</pre>

    <script>
      ais.ready(async function () {
        // Mostra qual modelo está ativo
        var model = await ais.config.getModel();
        ais.ui.setTitle("Inspetor de Chat - " + model);

        document
          .getElementById("load")
          .addEventListener("click", async function () {
            var messages = await ais.chat.getHistory(25);
            var output = messages
              .map(function (m) {
                return "[" + m.role + "] " + m.content.slice(0, 100);
              })
              .join("\n");
            document.getElementById("output").textContent =
              output || "(sem mensagens)";
            ais.ui.toast("Carregadas " + messages.length + " mensagens");
          });

        document.getElementById("close").addEventListener("click", function () {
          ais.close();
        });

        // Subscreve a novas mensagens em tempo real
        ais.chat.onMessage(function (msg) {
          var el = document.getElementById("output");
          el.textContent += "\n[" + msg.role + "] " + msg.content.slice(0, 100);
        });
      });
    </script>
  </body>
</html>

Manifest para este exemplo:

{
  "name": "chat-inspector",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "description": "Visualize e monitore o histórico de chat",
  "entry": "index.html",
  "base_url": "https://seu-cdn.com/chat-inspector/",
  "permissions": ["chat:read", "config:read", "ui:toast"]
}