Services and permissions

A PlayerVox OverCrow widget has no access of its own: no network, no file, no clipboard, no data about the game. Everything outside its own state comes from a service of OverCrow, which the logic calls through @overcrow/sdk. A service answers only when the widget declared the matching permission in its manifest and the user granted it.

// Without the grant the host would refuse the subscription: show the
// unknown duration instead of asking.
if (hasGrant("session.read")) {
  session.subscribe((update) => {
    state.session = anchor(update);
  });
}

That is the whole use of a service in the Session widget: it declares the session.read capability, checks that the user granted it, and subscribes.

Declare, then ask the user

Two kinds of authority exist, both declared in permissions of the manifest:

• four permissions for general services: network, storage, clipboardWrite and gameEvents;
• capabilities, listed under permissions.capabilities, for the data and actions of PlayerVox OverCrow itself and of the user's accounts: the frame rate, the media player, notes, PlayerVox ratings, Twitch chat…

  "permissions": {
    "network": [
      {
        "origin": "https://api.example.com",
        "method": "GET",
        "path": "/v1/forecast/{city}",
        "pathParams": { "city": { "type": "slug", "maxLength": 32 } },
        "queryParams": {
          "units": { "type": "enum", "values": ["metric", "imperial"], "required": true }
        }
      }
    ],
    "storage": true
  },

A declaration grants nothing by itself. The Control Center shows the user what the widget asks for; the user may uncheck an item, or take it back later, which restarts the widget without it. The widgets tagged built-in in the signed catalog (PlayerVox widgets only) start with their declared permissions granted. Declare the least you need: reviewers read every permission, and users see them before they consent.

hasGrant(capability) tells whether a capability was granted. Check it before you subscribe, and show a useful state when it is missing: a refused widget must still look right.

if (hasGrant("fps.read")) {
  fps.subscribe((update) => {
    Object.assign(state, reading(update));
  });
} else {
  state.status = "unavailable";
}

Calls and subscriptions

A service is one of two kinds.

A call asks once and returns a promise:

async function readStored(key: string): Promise<JsonValue | undefined> {
  try {
    return await storage.get({ key });
  } catch {
    state.error = "storage_unavailable";
    return undefined;
  }
}

A subscription takes a listener. PlayerVox OverCrow calls it with the current value at once, then with each new value, until you cancel() it or it ends with a failure. The listener comes last; a service with parameters takes them first.

  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);
    }
  });

Each update is { ok: true, value, final } or { ok: false, error, final: true }. A failed update is always the last one: the subscription is over.

Services are grouped in namespaces of the SDK: storage, http, clipboard, gameEvents, and one per data source (fps, telemetry, session, media, stopwatch, notes, playervox, journal, twitch). Every service, with its parameters and its result, is in the service reference.

PlayerVox OverCrow checks every call when it arrives, in this order: the permission or capability, the parameters, the user action when the service needs one, then the account when it needs one. The SDK's types help you call a service right; they are not what enforces the rules.

Errors

A failed call rejects with a ServiceError, whose code says why. A subscription that fails delivers the same error in its last update.

  try {
    const url = `https://api.example.com/v1/forecast/${state.city}?units=${state.units}`;
    const { status, body } = await http.fetch(url, { as: "json" });
    const value = (body as { temperature?: unknown } | null)?.temperature;
    if (status !== 200 || typeof value !== "number") {
      state.status = "unavailable";
      return;
    }
    state.temperature = value;
    state.status = "updated";
    await storage.set({ key, value });
  } catch (error) {
    // permission_denied until the user consents, transport_failed offline…
    state.status = error instanceof ServiceError ? "unavailable" : "failed";
  }

Three habits cover most cases:

• Show a state, not an error message. The codes are for your logic; the user sees "Forecast unavailable", not transport_failed.
• Retry a subscription that ended. A source of PlayerVox OverCrow can fail while the widget runs (the media player's session, for instance): the subscription ends with unavailable. Subscribe again a few seconds later with timers.after; OverCrow restarts the source for the new subscription. The Media widget waits five seconds:

    // 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);
    }

• Do not retry in a loop. busy and quota_exceeded mean that a bound is reached: wait, or do less.

Calls that need a user action

Services that change something for the user, or put something where other programs read it, can be called only during a user action: while the logic handles one of these events of the view.

activate, contextmenu, keydown, input, change, submit.

export function toggle(): void {
  command(() => stopwatch.toggle());
}

toggle is the on:activate handler of the stopwatch's button: the click is the user action, and stopwatch.toggle() is called while it is handled. The same call from a timer, from the answer of another service, from onHost or from a row of the options menu is refused with gesture_required.

• One user action allows one protected call. Call the service directly in the handler, not after an await on something else.
• Widgets receive input only in PlayerVox OverCrow's Interactive mode, so a protected call can only happen there.
• notes.delete and journal.delete also ask the user to confirm, in a dialog drawn by PlayerVox OverCrow; a declined confirmation is cancelled.

The tables below say, for each service, when it can be called.

Permissions

“Only during a user action” is explained in Calls that need a user action.

Network rules

network is a list of rules. A rule allows requests to exactly one HTTPS origin, one method and one path; a {name} segment of the path is a typed parameter, and only the declared query parameters are accepted.

  "permissions": {
    "network": [
      {
        "origin": "https://api.warframe.market",
        "method": "GET",
        "path": "/v2/versions",
        "maxResponseBytes": 4096
      },
      {
        "origin": "https://api.warframe.market",
        "method": "GET",
        "path": "/v2/items",
        "maxResponseBytes": 3145728
      },
      {
        "origin": "https://api.warframe.market",
        "method": "GET",
        "path": "/v2/orders/item/{slug}",
        "pathParams": {
          "slug": {
            "type": "slug",
            "maxLength": 96
          }
        },
        "maxResponseBytes": 2097152
      }
    ],
    "storage": true,
    "clipboardWrite": true
  },

Each path and query parameter has a constraint:

The request leaves through PlayerVox OverCrow's broker, never from the widget's process. The broker:

• refuses any URL that no rule allows (permission_denied), before any DNS query;
• follows no redirection, and sends no cookie, credential or proxy header;
• refuses local and private addresses, so a widget cannot reach the user's router or another program of the machine;
• bounds each exchange: 256 KiB for a request body, 30 seconds in all, and 1 MiB for a response body unless the rule declares a larger maxResponseBytes, up to 3 MiB. Reviewers and users see that bound.

http.fetch(url, { as }) decodes the body as you ask: "json", "text", "bytes" (an ArrayBuffer) or "image", which gives an image handle to bind to an image element instead of the bytes. A string body is sent as text/plain and any other value as JSON, unless contentType says otherwise. An HTTP error status is not a failure of the call: check status.

    const url = `https://api.example.com/v1/forecast/${state.city}?units=${state.units}`;
    const { status, body } = await http.fetch(url, { as: "json" });
    const value = (body as { temperature?: unknown } | null)?.temperature;
    if (status !== 200 || typeof value !== "number") {
      state.status = "unavailable";
      return;
    }

At most four requests of a widget are in flight at once, and they share a budget of response bytes: a request that does not fit fails with busy at once.

Storage

storage is a key-value store that PlayerVox OverCrow keeps for your widget only: storage.get({ key }), storage.set({ key, value }), storage.remove({ key }) and storage.keys(). A value is any JSON value. There is no file access.

function setRounds(rounds: number): void {
  state.rounds = rounds;
  paint();
  // Storage needs the user's consent: without it the count lasts as long
  // as the widget runs.
  storage.set({ key: "rounds", value: rounds }).catch(() => {});
}

The store holds at most 512 keys and 256 KiB in all, 64 KiB per value; beyond, storage.set fails with quota_exceeded and changes nothing. A write is answered once it is on disk. Uninstalling the widget erases its store, and a development session (overcrow-widget dev) never reads or writes the store of an installed widget.

Clipboard

clipboard.writeText({ text }) puts text on the clipboard, only during a user action. A widget cannot read the clipboard.

  clipboard.writeText({ text: whisperLine(order, detail.name) }).then(
    () => {
      if (mine === selection) state.copy = { side, id, state: "copied" };
    },
    () => {
      if (mine === selection) state.copy = { side, id, state: "failed" };
    },
  );

Text that the user selects in a text element with the selectable attribute is copied by PlayerVox OverCrow itself, and needs no permission.

Game events

gameEvents lists the named game events the widget wants, each of the form overcrow.game.<name>.v1. gameEvents.subscribe(listener) then delivers { event, at } for each one that happens.

Capabilities

A capability gives access to data or actions that PlayerVox OverCrow holds: what the game's use of the machine, the media player, the user's notes, their PlayerVox and Twitch accounts.

“Only during a user action” is explained in Calls that need a user action.

A row whose service is a form is a write that the user types: see forms that write user data.

Sensitive capabilities

A sensitive capability reveals personal data or the game being played. A widget that declares one:

• cannot also declare network or clipboardWrite: the manifest is refused;
• has a storage that lasts only as long as its process, and is emptied when the widget restarts.

So what such a widget reads cannot leave the machine through it. If your widget needs both an HTTP API and a sensitive capability, make two widgets.

Accounts

Some capabilities need the user's PlayerVox or Twitch account. The connection belongs to PlayerVox OverCrow: it draws the sign-in, keeps the tokens and shows its own panel over the widget while the account is signed out. A widget never sees a token; it receives only the data its capability describes, and its calls fail with not_connected while the account is not connected.

Data that changes

• A subscription may deliver null (no active game, no media player): show an empty state.
• Some subscriptions say what to read rather than the data itself. playervox.reviews.subscribe and journal.subscribe deliver a revision: when it changes, read your page again with playervox.reviews.page or journal.page.
• twitch.chat.subscribe delivers changes rather than the whole chat, at most every 100 ms: the new messages, the changed ones (same id), the IDs of the removed ones, and the whole list when reset is set.
• A timestamp that comes with its own offsetMinutes must be formatted with it; see time, dates and numbers.

The shape of every result is in result shapes.