Référence du SDK

@overcrow/sdk 1.0 est l’API de la logique d’un widget PlayerVox OverCrow : l’état, les données de l’hôte, les services, les minuteurs, le dessin, le menu d’options, les messages, les journaux et le formatage. Cette page liste tous les exports du paquet. La logique et Services et permissions expliquent comment s’en servir.

Le SDK est sur npm, et la commande ci-dessous l’ajoute à un projet. Un projet créé par overcrow-widget init le liste déjà : lancez-y npm install.

npm install --save-dev --save-exact @overcrow/sdk@1.0.0

import {
  formatDate,
  formatTime,
  initState,
  onHost,
  option,
  t,
  timers,
  type DateOrder,
  type Timer,
} from "@overcrow/sdk";

Le SDK est assemblé dans le logic.js du widget à l’empaquetage et s’exécute dans la VM du widget ; le charger ailleurs lève une erreur. Les parties inutilisées sont retirées du script assemblé. C’est une commodité, pas une barrière de sécurité : PlayerVox OverCrow vérifie chaque appel, chaque paramètre et chaque valeur qui sort de la VM.

État et vue

declare module "@overcrow/sdk" {
  interface WidgetState {
    values: number[];
  }
}

const state = initState({ values: [50] as number[] });

Données de l’hôte

onHost((changed) => {
  if (changed.includes("options")) {
    const values = menuValues();
    const unitChanged = values.seconds !== state.seconds;
    Object.assign(state, values);
    if (unitChanged) {
      start();
    }
  }
  // A new UTC offset (time zone or summer time) shows at once.
  if (changed.includes("region")) {
    tick();
  }
});

Services

Chaque service répond par l’intermédiaire de PlayerVox OverCrow, qui vérifie à chaque appel sa permission ou sa capability, ses paramètres et l’action de l’utilisateur.

L’écouteur vient toujours en dernier, et un service sans paramètres n’en prend aucun :

  fps.subscribe((update) => {
    Object.assign(state, reading(update));
  });

  const current = media.subscribe({ cover: state.showCover }, (update) => {
    if (update.ok) {
      state.media = update.value;
      state.unavailable = false;
      return;
    }
    // The subscription ended: the host's source failed. Show it and ask
    // again later; hidden, the timer waits until the widget shows.
    if (subscription === current) {
      subscription = null;
      state.media = null;
      state.unavailable = true;
      retry = timers.after(RETRY_MS, subscribe);
    }
  });

http.fetch envoie un corps de type chaîne en text/plain et tout autre corps en JSON, sauf si contentType en dit autrement, et décode la réponse comme le demande as. Une réponse sans corps donne null, "" ou un ArrayBuffer vide.

Les types des autres espaces de noms sont générés à partir du schéma : ClipboardServices, FpsServices, GameEventsServices, JournalServices, MediaServices, NotesServices, PlayervoxServices, SessionServices, StopwatchServices, StorageServices, TelemetryServices et TwitchServices. Chaque service est décrit dans la référence des services.

Minuteurs

• 16 minuteurs au plus, jamais plus courts que 100 ms : un intervalle plus court est porté à cette valeur.
• Aucun minuteur ne se déclenche tant que le widget est masqué. Un minuteur répétitif saute les déclenchements manqués ; un minuteur à usage unique arrivé à échéance pendant ce temps se déclenche une fois quand le widget réapparaît.
• atEach("second" | "minute" | "hour" | "day", callback) appelle callback à chaque changement d’unité de l’heure locale de l’utilisateur, et une fois quand le widget réapparaît. Il se réveille aussi quand le décalage UTC de l’utilisateur change.

      retry = timers.after(RETRY_MS, subscribe);

Dessin, menu, messages et journal

Les commandes de dessin sont des tuples typés, listés dans Dessin.

    dots.push(["circle", 6 + index * 14, 6, 4], ["fill", "var(--color-accent)"]);

Heure, dates et nombres

La VM n’a pas d’Intl, et son heure locale est UTC : Date ne donne jamais l’heure de l’utilisateur. Ces fonctions formatent à partir de host.region. Les nombres suivent le format de nombre de l’utilisateur (1,234.5, 1 234,5 ou 1.234,5), quelle que soit la langue de l’interface ; les dates sont numériques, dans l’ordre de date de l’utilisateur ; les heures s’affichent sur 24 heures. Chaque fonction accepte aussi ses valeurs régionales en options : elle peut ainsi tourner dans un test unitaire, hors de la VM.

export function clockDate(now: number, order: DateOrder): string {
  return formatDate(now, { order });
}

Les noms de mois et de jours de la semaine, l’affichage sur 12 heures et les règles de pluriel ne font pas partie de la version 1.0.

Types générés

Ces types sont générés à partir du schéma des widgets : ils correspondent donc toujours à ce que PlayerVox OverCrow accepte.

Constantes de limites

Les limites que la logique d’un widget doit respecter sont exportées sous forme de constantes, pour que le code ne répète jamais un nombre : MAX_TIMERS, MIN_TIMER_INTERVAL_MS, MAX_SERVICE_CALLS_IN_FLIGHT, MAX_SUBSCRIPTIONS, MAX_STORAGE_KEYS, MAX_STORAGE_KEY_BYTES, MAX_STORAGE_VALUE_BYTES, STORAGE_QUOTA_BYTES, MAX_REQUEST_URL_BYTES, MAX_HTTP_REQUEST_BYTES, MAX_HTTP_RESPONSE_BYTES, MAX_HTTP_DECLARED_RESPONSE_BYTES, MAX_CLIPBOARD_BYTES, MAX_OBJECT_ID_BYTES, MAX_NOTES, MAX_NOTE_ITEMS, MAX_NOTE_TITLE_BYTES, MAX_NOTE_BODY_BYTES, MAX_NOTE_ITEM_BYTES, MAX_REVIEW_CHARS, MAX_CHAT_CHANNEL_BYTES, MAX_CHAT_MESSAGE_CHARS, MAX_CHAT_FRAGMENTS, MAX_CHAT_FAVORITES, MAX_DRAW_COMMANDS, MAX_DRAW_STATE_DEPTH, MAX_PATH_POINTS, MAX_PATCH_BYTES, MAX_SCENE_NODES, MAX_CHILDREN, MAX_NODE_TEXT_BYTES, MAX_ATTRIBUTE_TEXT_BYTES, MAX_LABEL_BYTES, MAX_FIELD_TEXT_BYTES, MAX_LOCALE_ENTRIES, MAX_LOG_BYTES, VM_HEAP_BYTES, VM_MAX_HEAP_BYTES, VM_TURN_BUDGET_MS, VM_JOBS_PER_TURN et VM_MESSAGES_PER_TURN.

Tests unitaires : @overcrow/sdk/testing

Un second point d’entrée, jamais assemblé dans un widget, remplace PlayerVox OverCrow dans un test unitaire de la logique : installRuntime() fournit un temps virtuel, fait aboutir les appels de service et pousse les valeurs des abonnements. Voir les tests unitaires.