SDK reference

@overcrow/sdk 1.0 is the API of the logic of a PlayerVox OverCrow widget: the state, the data of the host, services, timers, drawing, the options menu, messages, logs and formatting. This page lists every export of the package. The logic and services and permissions explain how to use them.

The SDK is on npm, and the command below adds it to a project. A project made by overcrow-widget init already lists it: run npm install there.

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";

The SDK is bundled into the widget's logic.js when it is packaged, and runs inside the widget's VM; loading it anywhere else throws an error. Unused parts are removed from the bundle. It is a convenience, not a security boundary: PlayerVox OverCrow checks every call, parameter and value that leaves the VM.

State and view

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

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

Host data

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

Every service answers through PlayerVox OverCrow, which checks its permission or capability, its parameters and the user action at each call.

The listener always comes last, and a service without parameters takes none:

  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 sends a string body as text/plain and any other body as JSON, unless contentType says otherwise, and decodes the answer as as asks. A response without a body gives null, "" or an empty ArrayBuffer.

The types of the other namespaces are generated from the schema: ClipboardServices, FpsServices, GameEventsServices, JournalServices, MediaServices, NotesServices, PlayervoxServices, SessionServices, StopwatchServices, StorageServices, TelemetryServices and TwitchServices. Each service is described in the service reference.

Timers

• At most 16 timers, never shorter than 100 ms: a shorter interval is raised to it.
• No timer ticks while the widget is hidden. A repeating timer skips the hidden ticks; a one-shot timer that fell due while hidden ticks once when the widget is shown again.
• atEach("second" | "minute" | "hour" | "day", callback) calls callback at each boundary of the user's local time, and once when the widget is shown again. It also wakes when the user's UTC offset changes.

      retry = timers.after(RETRY_MS, subscribe);

Drawing, menu, messages and log

The draw commands are typed tuples, listed in drawing.

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

Time, dates and numbers

The VM has no Intl, and its local time is UTC: Date never gives the user's time. These helpers format from host.region. Numbers follow the user's number format (1,234.5, 1 234,5 or 1.234,5), whatever the interface language; dates are numeric, in the user's date order; times are 24-hour. Each helper also accepts its region values as options, so it runs in a unit test outside the VM.

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

Month and weekday names, 12-hour clocks and plural rules are not part of 1.0.

Generated types

These types are generated from the widget schema, so they always match what PlayerVox OverCrow accepts.

Limit constants

The limits a widget's logic works against are exported as constants, so the code never repeats a number: 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 and VM_MESSAGES_PER_TURN.

Unit tests: @overcrow/sdk/testing

A second entry point, never bundled into a widget, replaces PlayerVox OverCrow in a unit test of the logic: installRuntime() gives virtual time, settles the service calls and pushes the subscription values. See unit tests.