Aller au contenu principal

Référence SDK

Le SDK de mini-programme est une bibliothèque JavaScript d'environ 2 Ko qui est injectée dans chaque iframe de mini-programme. Il fournit l'espace de noms window.ais avec des méthodes pour interagir avec la plateforme AISCouncil via un pont postMessage sécurisé.

Comment Fonctionne le SDK​

Le SDK est injecté comme balise <script> avant le HTML de votre application dans le srcdoc de l'iframe. Vous n'avez pas besoin de l'inclure vous-même — il est toujours disponible en tant que window.ais lorsque votre code s'exécute.

Chaque appel de méthode (sauf les propriétés platform.*) envoie un message à la page hôte et retourne une Promise. L'hôte valide les permissions, exécute la requête et renvoie le résultat.

Votre code d'app             SDK                    Plateforme hôte
      |                        |                          |
      |-- ais.chat.send("hi")-->|                          |
      |                        |-- postMessage({           |
      |                        |     method: "chat.send",  |
      |                        |     args: {text: "hi"}    |
      |                        |   }) ---------------------->|
      |                        |                          |-- vérifier permissions
      |                        |                          |-- exécuter AIS.Chat.send()
      |                        |<-- postMessage({result}) --|
      |<-- Promise résolue ----|                          |
info

Toutes les méthodes SDK sont disponibles de façon synchrone en tant que références de fonction, mais elles retournent des Promises qui se résolvent de façon asynchrone. Utilisez toujours await ou .then() pour obtenir les résultats.

Support TypeScript​

Les définitions de types TypeScript sont disponibles dans sdk/ais.d.ts. Ajoutez une référence à votre projet :

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

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

Ou copiez les types AisManifest et AisPermission pour la validation du manifeste dans vos outils de build.

Cycle de Vie​

ais.ready(callback)​

Enregistre un callback qui se déclenche lorsque le pont de la plateforme est connecté et prêt. C'est le point d'entrée de votre application — enveloppez toute la logique d'initialisation dans ce callback.

ParamètreTypeDescription
callback() => voidFonction à appeler lorsque le pont est prêt
ais.ready(async function () {
  // La plateforme est connectée, les appels SDK fonctionneront maintenant
  const user = await ais.auth.getUser();
  document.getElementById("greeting").textContent = "Bonjour, " + user.name;
});
attention

N'appelez pas d'autres méthodes ais.* avant que ais.ready() ne se déclenche. Le pont postMessage peut ne pas être encore établi, et les appels resteront indéfiniment en attente.

ais.onShow(callback)​

Enregistre un callback qui se déclenche chaque fois que le mini-programme devient visible (ex., l'utilisateur revient à l'onglet de l'application).

ParamètreTypeDescription
callback() => voidFonction à appeler lors de l'affichage
ais.onShow(function () {
  // Rafraîchir les données lorsque l'utilisateur revient à l'app
  refreshDashboard();
});

ais.onHide(callback)​

Enregistre un callback qui se déclenche lorsque le mini-programme est masqué (ex., l'utilisateur passe au chat ou à une autre application).

ParamètreTypeDescription
callback() => voidFonction à appeler lors du masquage
ais.onHide(function () {
  // Mettre en pause les opérations coûteuses
  stopPolling();
});

ais.close()​

Ferme le mini-programme et retourne à la vue de chat. L'iframe est détruite après cet appel.

Retourne : Promise<boolean>

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

Stockage​

Stockage clé-valeur isolé par application, sauvegardé par IndexedDB. Les clés sont automatiquement préfixées avec mp:{app-name}: pour que les applications ne puissent pas accéder aux données des autres.

Permission : Toujours autorisé — aucune permission requise.

ais.storage.get(key)​

Récupère une valeur par clé. Retourne undefined si la clé n'existe pas.

ParamètreTypeDescription
keystringLa clé de stockage

Retourne : Promise<unknown> — la valeur stockée, ou undefined

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

ais.storage.set(key, value)​

Stocke une paire clé-valeur. La valeur peut être n'importe quel type sérialisable en JSON (string, number, boolean, object, array, null).

ParamètreTypeDescription
keystringLa clé de stockage
valueunknownLa valeur à stocker (doit être sérialisable en JSON)

Retourne : Promise<boolean> — true en cas de succès

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

ais.storage.remove(key)​

Supprime une clé du stockage.

ParamètreTypeDescription
keystringLa clé à supprimer

Retourne : Promise<boolean> — true en cas de succès

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

ais.storage.keys()​

Liste toutes les clés stockées par ce mini-programme (sans le préfixe interne mp:{name}:).

Retourne : Promise<string[]>

const keys = await ais.storage.keys();
console.log("Clés stockées:", keys); // ['visit-count', 'preferences']

Chat​

Lire l'historique de chat, envoyer des messages et s'abonner aux nouveaux messages dans la conversation active.

Permissions requises : chat:read pour lire, chat:write pour envoyer.

ais.chat.getHistory(limit?)​

Obtenir les messages récents de la session de chat active.

ParamètreTypeDéfautDescription
limitnumber50Nombre maximum de messages à retourner

Retourne : 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)​

Envoyer un message en tant qu'utilisateur. Cela déclenche le modèle IA actif pour générer une réponse.

ParamètreTypeDescription
textstringLe texte du message à envoyer

Retourne : Promise<boolean> — true en cas de succès

await ais.chat.send("Résume les 5 derniers messages");
avertissement

Appeler ais.chat.send() déclenche un véritable appel API vers le fournisseur IA configuré par l'utilisateur. Cela consomme des tokens et peut entraîner des coûts. Utilisez de manière responsable et informez toujours l'utilisateur avant d'envoyer des messages programmatiquement.

ais.chat.onMessage(callback)​

S'abonner aux nouveaux messages de chat. Le callback se déclenche pour chaque nouveau message (utilisateur et assistant).

ParamètreTypeDescription
callback(msg: ChatMessage) => voidGestionnaire pour les messages entrants
ais.chat.onMessage(function (msg) {
  if (msg.role === "assistant") {
    // Le modèle IA a répondu
    updateResponseDisplay(msg.content);
  }
});

Config​

Lire la configuration du bot actif (fournisseur, modèle, prompt système, etc.).

Permission requise : config:read

ais.config.get()​

Obtenir l'objet de configuration complet du bot.

Retourne : Promise<BotConfig>

interface BotConfig {
  n?: string; // Nom du bot
  p?: string; // ID du fournisseur (ex., 'anthropic', 'openai', 'gemini')
  m?: string; // ID du modèle (ex., 'claude-sonnet-4-20250514')
  s?: string; // Prompt système
  t?: number; // Température (0.0 - 2.0)
  x?: number; // Max tokens de sortie
  [key: string]: unknown;
}
const config = await ais.config.get();
console.log("Modèle utilisé:", config.m);
console.log("Prompt système:", config.s);

ais.config.getProvider()​

Obtenir l'ID du fournisseur actif.

Retourne : Promise<string> — ex., 'anthropic', 'openai', 'gemini', 'xai', 'openrouter', 'ollama'

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

ais.config.getModel()​

Obtenir l'ID du modèle actif.

Retourne : 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​

Afficher des notifications, des boîtes de dialogue de confirmation et mettre à jour le titre du panneau des applications.

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

Afficher une notification toast temporaire dans l'interface de la plateforme.

ParamètreTypeDéfautDescription
messagestring--Texte de notification (max 200 caractères)
durationnumber3000Durée en millisecondes

Retourne : Promise<boolean>

Permission : ui:toast (recommandée mais pas strictement appliquée — toast est peu impact)

await ais.ui.toast("Fichier sauvegardé avec succès !");
await ais.ui.toast("Traitement...", 5000); // Toast de 5 secondes

ais.ui.confirm(title, message)​

Afficher une boîte de dialogue de confirmation et attendre la réponse de l'utilisateur.

ParamètreTypeDescription
titlestringTitre de la boîte de dialogue (max 100 caractères)
messagestringTexte du corps de la boîte de dialogue (max 500 caractères)

Retourne : Promise<boolean> — true si l'utilisateur a cliqué OK, false si annulé

Permission requise : ui:modal

const confirmed = await ais.ui.confirm(
  "Supprimer toutes les données ?",
  "Cela supprimera définitivement tous les éléments sauvegardés. Cette action est irréversible.",
);
if (confirmed) {
  await clearAllData();
}

ais.ui.setTitle(title)​

Définir le texte affiché dans la barre de titre du panneau des applications.

ParamètreTypeDescription
titlestringTexte du titre (max 100 caractères)

Retourne : Promise<boolean>

ais.ui.setTitle("Compteur de Mots - 1 234 mots");

Auth​

Lire des informations sur l'utilisateur actuellement connecté.

Permission requise : auth:read

ais.auth.getUser()​

Obtenir les informations de profil de l'utilisateur actuel.

Retourne : Promise<UserInfo | null> — null si non connecté

interface UserInfo {
  name: string; // Nom d'affichage
  email: string; // Adresse email
  picture: string; // URL de la photo de profil
}
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 = "Invité";
}

ais.auth.getTier()​

Obtenir le niveau d'abonnement de l'utilisateur.

Retourne : Promise<string> — ex., 'free', 'pro', 'team'

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

Secrets​

Lire et écrire les clés API pour les scénarios de transfert entre appareils. C'est une API privilégiée utilisée par des applications comme Device Sync.

Permission requise : secrets:sync

attention

La permission secrets:sync donne accès aux clés API stockées par l'utilisateur. Ne demandez cette permission que si votre application a réellement besoin de transférer ou sauvegarder des identifiants. Les utilisateurs verront un avertissement clair dans la boîte de dialogue de permission.

ais.secrets.list()​

Lister les noms de fournisseurs qui ont des clés API stockées.

Retourne : Promise<string[]> — ex., ['anthropic', 'openai', 'gemini']

ais.secrets.get(provider)​

Obtenir une valeur de clé API par nom de fournisseur.

ParamètreTypeDescription
providerstringNom du fournisseur (ex., 'anthropic', 'openai')

Retourne : Promise<string | null>

ais.secrets.set(provider, value)​

Stocker une clé API pour un fournisseur.

ParamètreTypeDescription
providerstringNom du fournisseur
valuestringValeur de la clé API (max 1024 caractères)

Retourne : Promise<boolean>

Sync​

Synchroniser les profils, paramètres et signalisation WebRTC pour le transfert entre appareils.

Permission requise : secrets:sync

ais.sync.getProfiles()​

Obtenir tous les profils utilisateur depuis la plateforme hôte.

Retourne : Promise<Profile[]>

ais.sync.setProfiles(profiles)​

Importer des profils dans la plateforme hôte.

ParamètreTypeDescription
profilesProfile[]Tableau d'objets profil à importer

Retourne : Promise<number> — nombre de profils importés

ais.sync.getSettings()​

Obtenir les paramètres de l'application (thème, locale, etc.) depuis l'hôte.

Retourne : Promise<Record<string, string>>

ais.sync.setSettings(settings)​

Écrire les paramètres de l'application vers l'hôte.

ParamètreTypeDescription
settingsRecord<string, string>Paramètres clé-valeur à écrire

Retourne : Promise<boolean>

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

Poster une offre/réponse SDP vers le relais API pour la signalisation WebRTC.

ParamètreTypeDescription
codestringCode de couplage
type'offer' | 'answer'Type SDP
sdpRTCSessionDescriptionInitDonnées SDP

Retourne : Promise<boolean>

ais.sync.pollSignal(code, type)​

Sonder pour une offre/réponse SDP depuis le relais API.

ParamètreTypeDescription
codestringCode de couplage
type'offer' | 'answer'Type SDP à sonder

Retourne : Promise<RTCSessionDescriptionInit | null>

Hooks​

Enregistrer et déclencher des événements hook personnalisés pour étendre le comportement de la plateforme ou communiquer entre applications.

Permissions requises : hooks:action pour déclencher des événements, hooks:filter pour enregistrer des gestionnaires de filtre.

ais.hooks.on(hookName, handler)​

Écouter un événement hook nommé.

ParamètreTypeDescription
hookNamestringNom du hook (ex., 'chat:before-send')
handler(data: unknown) => voidGestionnaire d'événement

Retourne : Promise<boolean>

ais.hooks.on("chat:before-send", function (data) {
  console.log("Message sur le point d'être envoyé:", data);
});

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

Déclencher un événement hook nommé. Tous les gestionnaires enregistrés pour ce hook seront appelés.

ParamètreTypeDescription
hookNamestringNom du hook à déclencher
dataunknownDonnées optionnelles à transmettre

Retourne : Promise<unknown>

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

Pages​

Publier des pages web sur bcz.co avec un slug personnalisé. Utilisé par le mini-programme App Builder.

Permission requise : pages:publish

ais.pages.getInfo()​

Obtenir des informations sur la page publiée par l'utilisateur.

Retourne : Promise<PageInfo>

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

ais.pages.claim(slug)​

Réclamer un slug (nom d'utilisateur) pour bcz.co/@slug.

ParamètreTypeDescription
slugstringSlug désiré

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

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

Publier ou mettre à jour une page. Le spec est un document PDL encodé en base64.

ParamètreTypeDescription
specBase64stringSpécification de page encodée en base64
opts{ title?: string; description?: string }Métadonnées optionnelles

Retourne : Promise<PublishResult>

ais.pages.unpublish()​

Dépublier et libérer le slug.

Retourne : Promise<boolean>

Informations de Plateforme​

Propriétés en lecture seule avec des métadonnées de plateforme. Celles-ci sont synchrones — pas de Promise, pas de permission requise.

ais.platform.version​

La chaîne de version de la plateforme (semver).

Type : string — actuellement '1.0.0'

ais.platform.abi​

Le numéro de version ABI. Utilisé pour vérifier la compatibilité entre le SDK et la plateforme hôte.

Type : number — actuellement 1

if (ais.platform.abi !== 1) {
  ais.ui.toast("Cette application nécessite la version ABI 1");
  ais.close();
}

Gestion des Erreurs​

Tous les appels SDK qui nécessitent des permissions rejetteront avec une erreur PermissionDenied si l'application n'a pas la permission requise :

try {
  const history = await ais.chat.getHistory();
} catch (err) {
  if (err.message.includes("PermissionDenied")) {
    console.log("L'application n'a pas la permission chat:read");
  }
}

Les méthodes inconnues retournent une erreur avec le message Unknown method: {method}.

Si la plateforme hôte rencontre une erreur inattendue, la Promise rejette avec le message d'erreur sous forme de chaîne.

astuce

Enveloppez toujours les appels SDK dans des blocs try/catch, en particulier pour les APIs contrôlées par permissions. Cela rend votre application résiliente même si la version de la plateforme de l'utilisateur diffère de celle que vous avez testée.

Exemple Complet​

Une application minimale qui utilise plusieurs fonctionnalités 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>Inspecteur de Chat</h2>
    <button id="load">Charger l'Historique</button>
    <button id="close">Fermer</button>
    <pre id="output">Cliquez sur "Charger l'Historique" pour commencer...</pre>

    <script>
      ais.ready(async function () {
        // Afficher quel modèle est actif
        var model = await ais.config.getModel();
        ais.ui.setTitle("Inspecteur 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 || "(pas de messages)";
            ais.ui.toast(messages.length + " messages chargés");
          });

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

        // S'abonner aux nouveaux messages en temps réel
        ais.chat.onMessage(function (msg) {
          var el = document.getElementById("output");
          el.textContent += "\n[" + msg.role + "] " + msg.content.slice(0, 100);
        });
      });
    </script>
  </body>
</html>

Manifeste pour cet exemple :

{
  "name": "chat-inspector",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "description": "View and monitor chat history",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/chat-inspector/",
  "permissions": ["chat:read", "config:read", "ui:toast"]
}