Skip to content

The settings form (apiVersion 6)

The usual settings hold values your code reads with kino.config. From "apiVersion": 6 (Kino 0.9.50) the form can also show and do things, and every installed plugin gets its own tab in Ajustes. This page has every field type, the three types without a value, the two configuration aids of apiVersion 12, the exports that fill and check them, and a complete example.

For a new UI, use screens

From apiVersion 14 (Kino 0.9.74) the preferred way to build your plugin's configuration, onboarding or a dashboard is screens, which can also show this very form with the settings node. This form keeps working for compatibility.

Its own tab in Ajustes

Every installed plugin that is enabled gets its own tab in Ajustes (phone and TV), named after the plugin, with its Modo debug switch; when it has settings the tab holds their form too, and Plugins ▸ Configurar opens the same form. That is why, from Kino 0.9.50, the auth_required error reads "Configura {plugin} en Ajustes ▸ {plugin}" when your plugin declares settings.

Every field type

The form shows your settings in the order of the manifest, each with its label and, under it, its hint. Eleven types, and a twelfth, qr, from apiVersion 13 (Kino 0.9.74):

type What the person sees What kino.config.get(key) returns Since
text a text field (at most 500 characters) the text, or undefined apiVersion 1
password a hidden text field (at most 500), kept encrypted on the device the text, or undefined apiVersion 1
url an address field (at most 2,048): http/https; that server becomes a host your plugin may reach (The person's own servers) the address as typed, or undefined apiVersion 1
toggle a switch true / false (false when there is no default) apiVersion 1
select a choice among options the chosen value (the first option when there is no default) apiVersion 1
list a list the person builds with "Agregar", each entry a dialog of the list's fields an array of { [field key]: string }, or undefined when empty apiVersion 4
section a heading, with hint as its explanation nothing apiVersion 6
status a read-only line your settingsStatus() fills nothing apiVersion 6
action a button that runs your action(key) nothing apiVersion 6
link a button that opens an https address through the system, only when the person taps it (Configuration aids) nothing apiVersion 12
help a button ("Ayuda") that opens your instructions in a modal (Configuration aids) nothing apiVersion 12
qr a QR code drawn on the device from a text your settingsStatus() returns (A QR code) nothing apiVersion 13 (Kino 0.9.74)

What each entry may carry:

Attribute Types Rule
key all required, ^[a-z][a-zA-Z0-9_]{0,31}$, unique in the list
label all required, 1 to 40 characters (optional on a help: without it the button says "Ayuda")
type all required, one of the eleven above
hint all optional, at most 80 characters: the example or explanation under the field. On a section, up to 300, wrapped over several lines (Kino 0.9.51; builds before 0.9.51 refuse one over 80)
required text, password, url, list optional true/false. A required setting with no value stops every call ("Falta configurar")
default text, password, toggle, select optional. Never on url or list ("… no puede tener valor por defecto: usa "hint"") nor on the types without a value; it must fit its type (a select default is one of its values)
options select only required: 1 to 20 { "value", "label" }, value 1..40 characters and unique, label 1..40
fields list only required: 1 to 4, each { key, label, type, hint?, required? } with type "text" or "url", no default ("Solo un ajuste de tipo list tiene "fields"")
max list only optional whole number 1..50 (default 20): how many entries
confirm action only, apiVersion 6 optional, 1 to 120 characters: asked before the action runs, with Cancelar focused ("Solo un ajuste de tipo action tiene "confirm"")
url link only, apiVersion 12 required: https://, no user name or password, at most 2,048 characters
title, titleEn, body, bodyEn help only, apiVersion 12 the modal's title (at most 60) and text (at most 2,000); body or bodyEn is required
labelEn, hintEn, confirmEn those of label, hint, confirm optional, apiVersion 9 (Kino 0.9.55): the same text in English, with the same limits (English texts)
devices all optional, apiVersion 12: ["phone"], ["tv"] or both, the devices that draw it (one kind of device)
linkOnly action optional true/false, apiVersion 12: never drawn, run only as a link's confirm (linkOnly)
sync password, text optional true/false, apiVersion 13 (Kino 0.9.74): false keeps the value on this device (sync: false)

Any other key in an entry is ignored. A manifest that breaks a rule is refused at install with a message that names the setting (El ajuste "quality" necesita opciones); a list below apiVersion 4 a section/status/action below apiVersion 6 or a link/help below apiVersion 12 is refused too. Limits: 12 settings with a value (text, password, url, toggle, select, list) plus, from apiVersion 6, 16 without one (among them, from apiVersion 12, at most 4 link and 4 help).

There are no conditional fields: every setting is always shown, whatever another one holds. Use a section with a hint to say which fields go together ("Opcional: sin cuenta ves el catálogo gratis"), make them optional, and let validateSettings refuse a combination that makes no sense.

password or sealed secrets? A password setting is the person's credential: they type it, your code reads it, it syncs to their other devices sealed end to end. A key that belongs to you, the author (a fixed API key of the site's own player), goes in the manifest's sealed secrets instead, and your code only ever holds a marker.

English texts (apiVersion 9, Kino 0.9.55)

Kino speaks Spanish or English since 0.9.54 (Ajustes ▸ App ▸ Idioma). From Kino 0.9.55, with "apiVersion": 9, each text of your form can carry its English version next to it, under the same key with En at the end:

Where English keys Limit
any setting labelEn, hintEn those of label (1 to 40) and hint (80; 300 on a section)
an action with confirm confirmEn 1 to 120, and only next to confirm
a select's option labelEn 1 to 40
a list field labelEn, hintEn 1 to 40 and 80
the manifest's section labelEn 1 to 20 (The manifest)
{ "key": "quality", "label": "Calidad", "labelEn": "Quality", "type": "select",
  "hint": "La más alta gasta más datos", "hintEn": "The highest uses more data",
  "options": [{ "value": "hd", "label": "Alta", "labelEn": "High" }, { "value": "sd", "label": "Normal" }] }
  • The usual text is the Spanish one and the fallback: with the app in English, Kino shows every English version there is and, where one is missing, the usual text (above, the "Normal" option reads the same in both languages). With the app in Spanish nothing changes.
  • Your code never notices: keys, types, values and defaults are the same in both languages, and kino.config returns the same. To know the language, read kino.lang.
  • From apiVersion 9: below 9 these keys are unknown and ignored without being checked, as on an older Kino (which does not take "apiVersion": 9 either).
  • The same rules as the usual text: an empty one, one over the limit or one that is not a text refuses the manifest at install ("\"labelEn\" del ajuste \"quality\" debe ser un texto de 1 a 40 caracteres"; on an option, "Una opción del ajuste \"quality\" no es válida"); null is the same as leaving it out. confirmEn only goes on an action ("Solo un ajuste de tipo action tiene \"confirmEn\"") and next to confirm ("…necesita también \"confirm\"").
  • Kino only speaks Spanish and English: any other language key (labelPt, labelFr) is an unknown key and ignored.

node sdk/validate.mjs checks the same limits and, once your plugin uses an English version, tells you how many texts have one and which do not.

Three types that hold no value

From apiVersion 6 there are three types that hold no value (never in kino.config, never required, no default), at most 16 of them on top of the 12 valued settings:

"settings": [
  { "key": "account", "label": "Tu cuenta", "type": "section", "hint": "Opcional: sin cuenta usas la sesión anónima" },
  { "key": "email", "label": "Correo", "type": "text" },
  { "key": "password", "label": "Contraseña", "type": "password" },
  { "key": "linked", "label": "Estado", "type": "status" },
  { "key": "logout", "label": "Cerrar sesión", "type": "action", "confirm": "¿Cerrar la sesión de esta cuenta?" }
]
  • section: a heading; hint is its explanation.
  • status: a read-only line. Kino calls your settingsStatus() when the form opens (10 s) and shows the text you return under that key: { linked: "Vinculada como ana@…" } (at most 200 characters). Until it answers the line reads "Cargando…"; a missing key or a value that is not a text shows "Sin información"; a timeout or an error shows "No se pudo consultar". The rest of the form keeps working either way. Required export when a status setting exists.
  • action: a button. Kino calls your action(key) (30 s), one action at a time (the other buttons and Guardar wait), and shows the message you return (at most 300 characters) or "Listo"; if it throws or times out, the person sees the error text instead. Kino asks settingsStatus() again after every action (and when the form opens), so the status lines describe what it just did; refresh: true is still accepted and changes nothing. confirm (1 to 120 characters) asks first, with Cancelar focused. Required export when an action setting exists.

A QR code: qr (apiVersion 13, Kino 0.9.74)

A fourth type that holds no value, counted among the 16: a QR code drawn on the form, on the device (nothing goes to a network to draw it). It is how a TV shows a login code for a phone to scan.

{ "key": "login", "label": "Escanéalo desde tu teléfono", "labelEn": "Scan it from your phone", "type": "qr", "refreshMs": 5000 }
  • Its text is what your settingsStatus() returns under that key, like a status line, but kept whole: 1 to 512 characters with no control character; an http/https address only https on a public host (never the home network); any other text (an app link such as exampleapp://login?token=…, a pairing code) is drawn as it is. A longer text, a non-text or one that holds one of your sealed secrets draws no QR, and a qr with no text draws nothing at all (no label, no placeholder line, no empty row), so a QR that only one step of a sign-in needs simply is not there in the others.
  • refreshMs (2000 to 60000; only a qr setting has it): Kino asks settingsStatus() when the form opens, after every action and every that many ms while the form is on screen and the app in front. A refresh never starts while the previous call is still running, and the QR on screen stays up until the new text replaces it. That is how a code that expires every 30 s stays scannable, and how a status line next to it turns into "Listo" once the code was used.
  • Required export: settingsStatus. Showing a QR needs no capability; scanning one (kino.qr.scan) needs qrScan. The whole two-device recipe: QR codes.

Hiding items while they are not needed (hide, apiVersion 13, Kino 0.9.74)

Your settingsStatus() answer may carry hide: a list of keys of your own settings that the form (phone and TV) does not draw while that answer is current. Use it for a form that changes with a step: the sign-in button, its QR and the password step once the person is signed in, or "Cerrar sesión" while signed out.

export async function settingsStatus() {
  if (signedIn()) return { status: "Conectado", hide: ["qr_login", "login_qr", "tg_password", "check_password"] };
  return { status: "Falta iniciar sesión", hide: ["logout"] };
}
  • Their stored values stay and nothing is deleted; they still count for the form's own rules (a required one you hide still blocks Guardar).
  • Unknown keys and non-strings are ignored, at most 32 entries are read, and a failed answer hides nothing.
  • Kino asks settingsStatus() again after every action, so the form follows the step the action just reached.
  • Below apiVersion 13 the key is ignored. sdk/contract.mjs exports statusHide(answer, manifest), which gives the keys the app would hide.

Configuration aids: link and help (apiVersion 12, Kino 0.9.74)

Two setting types help the person configure your plugin. Neither holds a value (never in kino.config, never required, no default), and both count among the 16 settings without a value.

"settings": [
  { "key": "steps", "type": "help", "title": "Qué necesitas", "titleEn": "What you need",
    "body": "1. Crea un bot con @BotFather y copia su token.\n2. Pégalo aquí y toca Guardar.",
    "bodyEn": "1. Create a bot with @BotFather and copy its token.\n2. Paste it here and tap Save." },
  { "key": "botfather", "type": "link", "label": "Abrir @BotFather", "labelEn": "Open @BotFather", "url": "https://t.me/BotFather" },
  { "key": "botToken", "label": "Token del bot", "type": "password" }
]
  • link: a button that opens url through the system only when the person taps it (on a phone, https://t.me/... opens the Telegram app when it is installed). Kino shows its own "Abrir enlace" and the host under the button, makes no request to that host, and does not count it as a network access of your plugin. On a TV (usually without a browser) the tap shows the address as text and as a QR to open on a phone. url must be https://, without a user name or password, at most 2,048 characters; label is required. An address that holds one of your stored secrets is not shown. Kino opens the canonical form of the address (host in lower case), the same one it names. There is no other way for a plugin to have Kino open an address.
  • help: a small button ("Ayuda" / "Help", or your own label) that opens a modal with your instructions, titled with your plugin's name. Plain text only: newlines are kept, markup is shown literally, nothing in it is tappable (use a link for an address). title at most 60 characters, body at most 2,000 (body or bodyEn is required); a missing Spanish or English text falls back to the other; everything is scrubbed of your secrets. On a TV it scrolls with the remote, focus starts on Cerrar and Back closes it.

A link's label and a help's label, title and body may not hold control characters (a body keeps its line breaks), invisible formatting or direction overrides; the manifest is refused otherwise. At most 4 links and 4 helps per plugin. Older Kino builds refuse apiVersion 12, so a plugin that uses them declares "apiVersion": 12.

Keep the help short and practical: what the plugin needs and where to get it, in a few lines. If the plugin talks to a server the person runs, the help does not teach how to build it: add a link to the complete guide (the technical cap of 2,000 characters is not a target).

Settings for one kind of device (devices, apiVersion 12, Kino 0.9.74)

Any settings item (a field, a section, a status, an action, a link or a help) may say which devices draw it: "devices": ["phone"], ["tv"] or both; without it the item shows everywhere.

{ "key": "botToken", "label": "Token del bot", "labelEn": "Bot token", "type": "password", "devices": ["phone"] }

It is only about drawing. On a device it leaves out, the form neither draws nor checks the item (a hidden required field never blocks Guardar there), but its value is still stored, saved back unchanged, synced to the person's other devices, handed over by sync.provision and read by your code through kino.config. Use it for setup a TV cannot do well, like a token pasted on the phone: Sync-Gram and Sync Servidor draw their setup only on the phone, and the TV receives the values with "Recibir configuración" ("Receive settings"). An unknown device, an empty list or a repeated one refuses the manifest ("devices" of the setting "<key>" must be a list of different devices: "phone", "tv"); below apiVersion 12 the key is ignored. The Node kit renders no form: validate.mjs only checks the field.

A setting the 18+ code guards (unlockWith, apiVersion 14, Kino 0.9.74)

Available with Kino 0.9.74

Available from Kino 0.9.74. Below apiVersion 14 the key is ignored.

A toggle or a select may say "unlockWith": "adultCode": before the person moves it away from its default (a toggle off its default, a select to any other option), Kino asks the device's 18+ code with its own prompt (the «Código» field of Ajustes on the phone, the padlock's keyboard dialog on a TV; while the default code still rules, the prompt says so, as every 18+ prompt does). The change applies only once the code is right; a wrong code says «Código incorrecto» and keeps the old value, and Cancelar or Back leave the control as it was. Moving it back toward the default never asks. Your plugin never sees the code, and giving it unlocks nothing else (no 18+ entry shows because of it). Use it for a filter the person should not switch off on a whim, like the news example's «No mostrar noticias +18» (default on).

{ "key": "hideAdult", "label": "No mostrar noticias +18", "labelEn": "Hide 18+ news", "type": "toggle", "default": true, "unlockWith": "adultCode" }

It works in Kino's settings form wherever it is drawn: your tab in Ajustes, and a screen's or a panel's settings node. Your own code may only move the setting toward its default: an answer's config that moves it away is dropped (is locked (unlockWith adultCode): only the person moves it away from its default, in Kino's settings form), an action's setSettings that does is refused whole, and a field may not bind it (bind "<key>" is locked (unlockWith adultCode): show it in a settings node): show it with { "type": "settings", "keys": ["<key>"] }. The value syncs to the person's other devices like any setting (and travels with «Enviar a otro aparato»); the code is asked on each device at the moment of the change. unlockWith on any other type, or a value other than "adultCode", refuses the manifest (Only a setting of type toggle or select has "unlockWith" ("<key>"), "unlockWith" of the setting "<key>" must be one of: adultCode). The Node kit renders no form: validate.mjs checks the field and run.mjs applies the same config, bind and setSettings rules.

An action may say "linkOnly": true: it is never drawn on any device and runs only as the confirm of another action's link, after Kino's own question. A "find, then confirm" pair then shows the person one button (Sync-Gram's Verificar mensaje en el chat); without it the confirm action is a second button. linkOnly on anything but an action, or not a boolean, refuses the manifest.

Forgetting settings from an action (clearSettings)

An action may also forget settings of your own with clearSettings: up to 12 keys of your declared valued settings (text, url, password, toggle, select, list). After the action returns, Kino empties them exactly as if the person had emptied the fields and pressed Guardar (a password also leaves the Keystore), closes your sandbox and forgets cookies and cached Home rows as for any saved change (kino.storage survives), reloads the form and asks settingsStatus() again; your message is still shown. It is how a "Cerrar sesión" button stops the next expired token from signing the person in again with the saved account.

export async function action(key) {
  if (key === "logout") {
    await api.logout();                       // tell the server first: a throw here keeps the saved account
    return { message: "Sesión cerrada", clearSettings: ["email", "password"] };
  }
}

(email and password must be optional settings here; mark the account required only if the plugin cannot work signed out.)

Limits:

  • Only the action's own plugin is ever touched.
  • An entry that is not a string, is unknown, names a section/status/action, names a required setting (clearing it would make every later call fail), repeats, or comes after the twelfth is dropped with a log line (run.mjs shows [dropped by Kino]); a value that is not an array is ignored.
  • An action that throws or times out clears nothing.

Filling your own settings from an action (setSettings, Kino 0.9.74)

An action may also fill settings of your own with setSettings: up to 8 keys of your text or select settings, each with a string value. It is how a "Vincular" action stores the chat it found, so the person types nothing. Kino trims each value, checks it like a typed one (length, one of the options) and saves the values through the form's own Guardar: they reach the person's other devices and stay in the profile in use like typed values, and your sandbox closes as for any saved change. It is additive (no new apiVersion): an older Kino ignores it.

return { message: "Vinculado", setSettings: { chatId: String(chat.id) } };
  • Never a url (its value becomes a server your plugin may reach, so only the person types one), a toggle, a list or a setting without a value; a required setting is never emptied this way. A password only from apiVersion 13 (below); below it the whole field is refused.
  • Kino does not run your validateSettings on these values (you chose them), and it refuses a value that contains one of your stored secrets instead of copying it into a plain, synced setting.
  • An unknown or secret key, a value that is not a string or fails its check, a key that is also in clearSettings, a value that holds one of your stored secrets, or more than 8 keys refuse the whole field: nothing is applied, your message still shows and Kino adds its generic error under it.
  • It works from your settings form (any action, including the confirm action of a link).

Filling a password (apiVersion 13, Kino 0.9.74)

An action may fill one of your own password settings, for a value your plugin makes up instead of asking the person to type one:

return { message: "Clave creada", setSettings: { syncKey: kino.crypto.randomBytes(32) } };   // 64 hex characters

Kino stores it exactly like a typed password: sealed in the Keystore, synced sealed end to end to the person's other devices (or kept on this device only when the setting says "sync": false), and masked in the form. It is never logged, and every password value your answer names is scrubbed from that same answer's message and link, so it is never shown back on the page. The usual rules apply (at most 500 characters, a required one never emptied, a value holding another of your secrets refused). Only an action the person ran fills a setting: a settingsStatus answer is never read for setSettings. node sdk/run.mjs . action <key> prints such a value masked. A sync provider that only needs a random key does not need this: sync.generateKey makes Kino create it.

Use it when an action finds who to link and the person must say it is them: for example a sync provider whose bot reads the latest message ("write something to your bot") and finds @ana. Your plugin never links on its own: it answers a candidate, and Kino asks.

export async function action(key) {
  if (key === "findMe") {
    const who = await bot.latestSender();          // null while nobody wrote yet
    if (!who) return { message: "Escríbele algo a tu bot y vuelve a tocar Buscar" };
    kino.storage.set("pending", who.id);
    return { link: { candidate: "@" + who.username, confirm: "linkMe" } };
  }
  if (key === "linkMe") {                           // runs only after the person confirms
    const chat = kino.storage.get("pending");
    return { message: "Vinculado", setSettings: { chatId: String(chat) } };
  }
}
  • Kino shows its own question, "¿Eres tú, @ana?" / "Is this you, @ana?", and names your plugin in it by the name of your manifest. It has "Sí, soy yo" / "Yes, it's me" and Cancelar (Cancelar focused). You cannot change its words.
  • Cancelar runs nothing: your plugin is not called and hears nothing. Only "Sí, soy yo" runs the confirm action, exactly once, like a press of that button (same settings, same 30 s). If it cannot start right then (another action or a save is running, or the person's unsaved edits cannot be saved), the question stays open and says so.
  • candidate: a string, 1 to 64 characters after trimming, with runs of spaces collapsed to one. It may not hold control or invisible formatting characters, any space but the ordinary one, or the fillers that draw nothing (U+115F, U+1160, U+3164, U+FFA0, U+2800). It goes through the same secret scrubbing as your status lines and is shown as plain text.
  • confirm: the key of another action setting of your plugin (not the one that is answering) that has no confirm question of its own: an action that asks "¿Borrar todo?" can never be presented as "Is this you?".
  • Anything else refuses the link: your message is still shown, with Kino's generic error ("No se pudo completar. Inténtalo de nuevo.") under it.
  • A message in the same answer is shown too. A link in the confirm action's own answer is ignored (no chains). One question at a time: a newer link replaces a waiting one, and leaving the form drops it.
  • An older Kino ignores link (it is additive, no new apiVersion), so also say in message (or a status line) what to do.
  • An action that only serves as a confirm can be hidden with "linkOnly": true: the person then sees one button, and only Kino's question runs the confirm action.

Checking before saving (validateSettings)

validateSettings(values) (optional, 20 s) runs before Kino saves. values holds only the valued settings: strings trimmed, toggles as booleans, lists as arrays of objects.

  • Return null to accept.
  • { password: "La contraseña no es correcta" } refuses with that text under the field (at most 200 characters), or a text refuses with a general message. A key that is not one of your valued settings also refuses, its text shown as the general message.
  • Nothing is saved on a refusal and the person keeps what they typed.
  • If it throws, times out or answers something Kino cannot read (an array, a number…), nothing is saved either, and the form offers "Guardar sin comprobar"; that button is offered only then, never after a refusal with messages.

Common rules

  • Texts you return are shown after Kino removes any of your stored secrets from them.
  • These three exports run even while a required setting is still empty, so a status line can say what is missing.
  • Saving any setting closes your sandbox, as always; kino.storage survives.
  • If you declare telemetry, a failure of settingsStatus, action or validateSettings is reported like any other function's (Logs and telemetry).

Try them with the kit (it prints what the app would keep): node sdk/run.mjs . settingsStatus, node sdk/run.mjs . action logout, node sdk/run.mjs . validateSettings '{"email":"ana@x.co"}' (or node sdk/validate.mjs . --run … with the same arguments, which also says what Kino shows and flags a call it never makes; --raw prints your answer untouched). The kit does not apply the app's secret scrubbing, and validateSettings receives exactly the JSON you type: the app sends only valued settings, trimmed. A working example is plugins/sdk/test/settings-demo in Kino's repository.

A complete example

An account that is optional, a status line, a "Cerrar sesión" button, a quality choice, a switch and a list of the person's own mirrors, all read the way kino.d.ts declares them:

{
  "id": "mi-cuenta", "name": "Mi cuenta", "version": "1.0.0", "apiVersion": 6, "entry": "plugin.js",
  "hosts": ["api.example.com"],
  "capabilities": ["search", "resolve"],
  "settings": [
    { "key": "account", "label": "Tu cuenta", "type": "section", "hint": "Opcional: sin cuenta ves el catálogo gratis" },
    { "key": "email", "label": "Correo", "type": "text", "hint": "ana@correo.com" },
    { "key": "password", "label": "Contraseña", "type": "password" },
    { "key": "linked", "label": "Estado", "type": "status" },
    { "key": "logout", "label": "Cerrar sesión", "type": "action", "confirm": "¿Cerrar la sesión de esta cuenta?" },
    { "key": "playback", "label": "Reproducción", "type": "section" },
    { "key": "quality", "label": "Calidad", "type": "select", "default": "auto",
      "options": [{ "value": "auto", "label": "Automática" }, { "value": "hd", "label": "Alta" }, { "value": "sd", "label": "Ahorro de datos" }] },
    { "key": "spanishSubs", "label": "Solo subtítulos en español", "type": "toggle", "default": true },
    { "key": "mirrors", "label": "Espejos propios", "type": "list", "max": 5,
      "fields": [{ "key": "url", "label": "Dirección", "type": "url", "required": true, "hint": "https://espejo.example.org" },
                 { "key": "name", "label": "Nombre", "type": "text", "hint": "Espejo de la casa" }] }
  ]
}
const API = "https://api.example.com";
// Keyed by the account: settings can change under the plugin (another device, clearSettings).
const sessionKey = () => `session:${kino.config.get("email") ?? ""}`;

async function login(email, password) {
  const r = await kino.fetch(`${API}/login`, { method: "POST", body: { json: { email, password } } });
  if (r.status === 401) throw kino.error("auth_required", "login 401");
  if (!r.ok) throw kino.error("unavailable", `login ${r.status}`);
  return r.json().token;
}

async function session() {
  await null;                                    // the first await before anything can throw
  const email = kino.config.get("email");        // undefined: signed out, free catalog
  if (!email) return null;
  const saved = kino.storage.get(sessionKey());
  if (saved) return saved;
  const token = await login(email, kino.config.get("password") ?? "");
  kino.storage.set(sessionKey(), token, { ttlMs: 12 * 60 * 60 * 1000 });
  return token;
}

export async function settingsStatus() {         // one text per "status" key
  const email = kino.config.get("email");
  if (!email) return { linked: "Sin cuenta: ves el catálogo gratis" };
  try {
    await session();
    return { linked: "Cuenta vinculada" };
  } catch (e) {
    return { linked: e.code === "auth_required" ? "El correo o la contraseña no coinciden" : "No se pudo revisar la cuenta ahora" };
  }
}

export async function action(key) {             // one call per "action" button
  if (key !== "logout") return null;
  const token = kino.storage.get(sessionKey());
  if (token) await kino.fetch(`${API}/logout`, { method: "POST", headers: { Authorization: `Bearer ${token}` } });
  kino.storage.remove(sessionKey());
  return { message: "Sesión cerrada", clearSettings: ["email", "password"] };
}

export async function validateSettings(values) { // before saving: null accepts
  await null;
  if (values.email && !values.password) return { password: "Escribe la contraseña de esa cuenta" };
  if (values.password && !values.email) return { email: "Escribe el correo de la cuenta" };
  if (values.email) {
    try {
      await login(values.email, values.password);
    } catch (e) {
      if (e.code === "auth_required") return { password: "El correo o la contraseña no coinciden" };
      throw e;                                    // the person may "Guardar sin comprobar"
    }
  }
  return null;
}

export async function search(query) {
  const token = await session();
  const r = await kino.fetch(`${API}/search?q=${encodeURIComponent(query.q)}`,
    { headers: token ? { Authorization: `Bearer ${token}` } : {} });
  if (!r.ok) throw kino.error("unavailable", `search ${r.status}`);
  return r.json().results.map((x) => ({ id: String(x.id), ref: String(x.id), title: x.title, kind: "movie" }));
}

export async function resolve(ref) {
  const token = await session();
  const quality = kino.config.get("quality");    // "auto", "hd" or "sd": a select always has a value
  const r = await kino.fetch(`${API}/play/${encodeURIComponent(ref)}?q=${quality}`,
    { headers: token ? { Authorization: `Bearer ${token}` } : {} });
  if (!r.ok) throw kino.error("not_found", `play ${r.status}`);
  const s = r.json();                            // { url, path, subtitles: [{ lang, url }] }
  const mirrors = kino.config.get("mirrors") ?? []; // [{ url, name? }]: each url is a server the person typed
  return {
    url: s.url,
    label: "Principal",
    subtitles: kino.config.get("spanishSubs") ? s.subtitles.filter((t) => t.lang === "es") : s.subtitles,
    alternatives: mirrors.slice(0, 8).map((m) => ({ url: m.url.replace(/\/+$/, "") + s.path, label: m.name || "Espejo" })),
  };
}

What the person gets: a tab "Mi cuenta" in Ajustes with two headings; "Estado" reads "Sin cuenta: ves el catálogo gratis" until they type an account; Guardar checks the account before saving it; "Cerrar sesión" asks first, then empties the correo and the contraseña on every device of theirs; each mirror shows up as one more copy in the player's Servidor menu.

A value that stays on this device ("sync": false, apiVersion 13, Kino 0.9.74)

A password may say "sync": false to stay on the device where the person typed it: use it for a value that only makes sense once, on one device, such as a two-step verification password your plugin sends right away and then clears (clearSettings). Without it a password reaches the person's paired devices, sealed end to end, like every other password (below).

{ "key": "tg_password", "label": "Contraseña de verificación", "type": "password", "sync": false }
  • The value is never sent to a paired device, and a value another device sends never sets or clears it.
  • It is in no backup and no kit.
  • A sync provider's sync.provision may still name it, for a one-shot secret handed once to a new device (a TV that should not type a two-step password): see Sync providers. It can never be the sync.keySecret ("The \"keySecret\" of the \"sync\" field can't name a setting with \"sync\": false").
  • Your plugin reads it with kino.config.get and clears it as any password.
  • A text may say "sync": false too, for a value that must stay on the device but is no secret to hide, such as a phone number the person types to sign in on that device: it is drawn as a plain text field (nothing masked) and kept exactly like a device-only password (never synced, never in a backup or a kit). It may not appear in sync.provision ("The \"provision\" of the \"sync\" field can't name a text setting with \"sync\": false").
  • sync on any other type refuses the manifest ("Only a setting of type password or text has \"sync\" (\"key\")"), and so does a value that is not true or false. Below apiVersion 13, and in a Kino build without it, the key is ignored and the password syncs as usual. node sdk/validate.mjs checks all of this like the app.

On the person's other devices

When the person pairs two of their devices (phone and TV), Kino keeps their plugins in step. What crosses, and what does not:

  • Crosses: install, updates, on/off, uninstall, and the host approvals. Each device fetches your code itself; only the address and the approval travel. The other device installs silently when what it fetched asks for nothing beyond what the person approved on the first one; if you now ask for more (a new host, permission or capability), it waits in "Plugins de tus otros aparatos" for the normal consent sheet.
  • Crosses: the values of text, select, toggle, url and list settings (a list that has a password field does not travel), and password settings (except a password or text with "sync": false, apiVersion 13), sealed end to end with the key the devices agreed when they paired, never readable on the way.
  • Crosses: clears. A field the person empties, or an action's clearSettings, empties it on their other devices too (passwords included). A required setting is never cleared remotely. A device running an older Kino build ignores clears and keeps its value.
  • Never crosses: kino.storage, cookies, the cached Home rows.
  • A sync provider can also hand its settings to another device with "Enviar configuración" (the ones its sync.provision names): see Sync providers.

A value that arrives this way is applied without your validateSettings, and, like any saved change, closes your sandbox. So write the plugin as if a setting can change under it at any time: key any session you keep in kino.storage by the account it belongs to, and never put a device identity in a setting, because it would be copied to the other device.

const sessionKey = `session:${kino.config.get("email") ?? ""}`;   // not just "session"

A signed plugin installed from two different repositories on two devices counts as the same plugin when both have the same id and the same author key: see The same plugin at two addresses.