La API kino¶
kino es un objeto global, congelado, que siempre está. Nada más del mundo exterior está.
kino.apiVersion // 8 on Kino 0.9.54 (7 on 0.9.51 to 0.9.53) -- the highest apiVersion this build of Kino understands, not your manifest's
kino.appVersion // the version of Kino, for example "1.42.0"
kino.lang // "es-CO"; from Kino 0.9.54 "en-US" too, when Kino speaks English
kino.fetchAnyHost // Kino 0.9.55+: true when this install's kino.fetch may reach any public host; undefined before
kino.device // Kino 0.9.55+: "tv" or "phone", the UI Kino shows on this device; undefined before
kino.pluginApiVersion // Kino 0.9.88+: your plugin's feature apiVersion (your apiVersion or the highest enhancements key applied); undefined before
kino.seed(session) // Kino 0.9.55+: share one anonymous guest session (see below); absent before
kino.sync // Kino 0.9.74+: { remoteChanged() } for a realtime sync provider (see below); absent before
kino.ws // apiVersion 13 (Kino 0.9.74), capability "socket": outbound WebSockets (see below); absent otherwise
kino.catalog // apiVersion 13 (Kino 0.9.74), capability "catalog": a SQLite catalog of your items; absent otherwise
kino.qr // apiVersion 13 (Kino 0.9.74), capability "qrScan": { scan() }, the phone's QR scanner; absent otherwise
kino.plugins // apiVersion 20 (Kino 0.9.81): { call() }, the doors of the plugins your manifest consumes; absent before
kino.files // apiVersion 21 (Kino 0.9.82), capability "files": files on the person's device (pick, read, url); absent otherwise
kino.progress // apiVersion 22 (Kino 0.9.83), capability "progress": where the person is in an element of yours (set, get, list, clear); absent otherwise
kino.apiVersion responde 13 en Kino 0.9.74 y 11 en Kino 0.9.71 a 0.9.73.
(kino.apiVersion es el apiVersion más alto que entiende esta versión de Kino, no el de tu
manifiesto; kino.appVersion es la versión de Kino.)
kino.lang: el idioma de la persona¶
kino.lang es el idioma en que Kino le habla a la persona. Hasta Kino 0.9.53 es siempre "es-CO". Desde Kino 0.9.54
sigue el idioma de la app: "es-CO" mientras Kino está en español, "en-US" mientras está en
inglés. La persona lo elige en Ajustes ▸ App ▸ Idioma (Automático, Español o English, sincronizado entre sus aparatos);
Automático habla español en un aparato configurado en cualquier variante de español, e inglés en cualquier otro. Sin
apiVersion nuevo y sin nada que comprobar: léelo donde lo necesites.
- Un sandbox conserva el
kino.langcon que se abrió. Cuando la persona cambia de idioma, Kino cierra el sandbox de tu plugin y la siguiente llamada abre uno nuevo con el valor nuevo (el nivel superior de tu módulo vuelve a correr;kino.storagese conserva). El sandbox que corresign()sigue abierto, así que un video que se está reproduciendo sigue firmándose. - Con el cambio, Kino también vacía la caché de
kino.metay vuelve a pedir tus filas de Inicio, sin usar su caché. - Escribe en ese idioma lo que lee la persona: los títulos de tus filas, tu
userMessage, un encabezadoAccept-Language. Kino muestra tu texto tal como lo escribiste. Ellangdekino.metaacepta la etiqueta tal cual (lang: kino.lang) o su código corto (kino.lang.split("-")[0]). - En el kit de Node,
kino.langes siempre"es-CO"(Probar en local).
kino.device: ¿TV o celular?¶
Desde Kino 0.9.55, kino.device es "tv" o "phone": la interfaz que Kino muestra en este aparato, la misma decisión
con la que dibuja sus pantallas de TV (control remoto, pantalla a distancia) o las del celular. Una tableta recibe lo que
Kino le muestre, normalmente "phone". No cambia mientras Kino corre, no pide permiso y sirve en todo apiVersion. En un
Kino anterior es undefined, así que trata todo lo que no sea "tv" como celular:
const enTv = kino.device === "tv";
const tamano = enTv ? 20 : 40; // menos elementos por petición en una caja de TV
const pista = enTv ? "Elige otra fuente con el control" : "Toca otra fuente";
Úsalo para lo que de verdad cambia: menos elementos por petición, una copia que decodifique bien en una caja, un
userMessage que diga «en el control» en vez de «toca». El kit de Node dice "phone" salvo que le pases --device tv a
run.mjs (Probar en local).
kino.fetchAnyHost: ¿llega kino.fetch a cualquier host?¶
Desde Kino 0.9.55, kino.fetchAnyHost es true solo cuando el kino.fetch de esta instalación puede llegar a
cualquier host público: tu manifiesto declara "fetchHosts": "any", tu plugin califica
(apiVersion 9 o más, o un scraper de Nuvio convertido) y la persona lo aprobó en rojo. Si falta algo es false,
y en un Kino anterior no existe (undefined). Úsalo para decidir antes de pedir:
const url = kino.fetchAnyHost === true ? enlaceDelExtractor : await miRespaldo(enlaceDelExtractor);
Aun en true, un host que no declaraste solo se alcanza por https en el puerto 443 (y con un cupo de peticiones), la red
de la casa sigue rechazada y un secreto sellado solo va a tus hosts declarados (las reglas). En el kit de Node es true cuando el manifiesto pide "fetchHosts": "any" con apiVersion 9 (el kit da
la aprobación por hecha).
kino.pluginApiVersion: el apiVersion con que corren tus funciones¶
Desde Kino 0.9.88, kino.pluginApiVersion es el apiVersion efectivo de tu plugin en este Kino: el apiVersion de tu
manifiesto, o la clave más alta de tus enhancements que aplicó este Kino, la que sea mayor. Una función
que depende de él está encendida justo cuando es lo bastante alto, así que un plugin que conserva un apiVersion bajo para los
Kino anteriores igual puede saber si este lee, por ejemplo, clockLive (27). No es
kino.apiVersion: ese es el apiVersion más alto que entiende esta versión de Kino, el mismo para todo plugin. En Kino 0.9.87 y
anteriores es undefined:
const conReloj = typeof kino.pluginApiVersion === "number" && kino.pluginApiVersion >= 27;
Sin apiVersion nuevo; el kit de Node da el mismo número, a partir de tu manifiesto y sus enhancements.
Kino también pone los globales web que le faltan a QuickJS, escritos en JavaScript y congelados:
URL, URLSearchParams, atob, btoa, TextEncoder y TextDecoder (solo UTF-8). Se comportan
como los del navegador (comparados con Node sobre un corpus de casos), salvo que URL no convierte
nombres de dominio internacionales a punycode. Una URL se puede cambiar en el sitio con los setters
de siempre (protocol, username, password, host, hostname, port, pathname, search,
hash, href), que, como en el navegador, nunca lanzan error: un valor que no pueden usar deja la
URL como estaba.
Toda la API está declarada en kino.d.ts para tu editor.
await kino.fetch(url, options?)¶
const r = await kino.fetch("https://archive.org/metadata/" + encodeURIComponent(id), {
method: "GET", // GET (default), POST, PUT, PATCH, DELETE or HEAD
headers: { Accept: "application/json" },
body: "a=1&b=2", // see "Bodies" below; sent only with POST, PUT and PATCH
redirect: "follow", // or "manual": get the 3xx itself, with its Location header
cookies: true, // false: neither send nor store cookies for this request
timeoutMs: 20000, // default 15000, at most 30000
maxBytes: 65536, // apiVersion 14: read at most this many bytes of the body (1 to 2000000)
stopAt: "</head>", // apiVersion 14: end the read at this marker (1 to 32 ASCII characters), kept
});
r.ok // true for 200 to 299
r.status // the HTTP status
r.url // the final URL, after redirects
r.headers // { "content-type": "...", ... }: names in lowercase, repeated headers joined with ", "
r.text() // the body as a string (already downloaded)
r.json() // JSON.parse of the body
r.base64() // the body bytes as base64: for anything that is not text
r.truncated // apiVersion 14: true when the body was cut at maxBytes or stopAt
Las opciones: method es GET (por defecto), POST, PUT, PATCH, DELETE o HEAD; body solo
se envía con POST, PUT y PATCH; redirect: "manual" te entrega la respuesta 3xx misma, con su
header Location; cookies: false ni envía ni guarda cookies en esa petición; timeoutMs es 15000
por defecto y máximo 30000. La respuesta: r.ok es true de 200 a 299, r.url es la URL final
después de las redirecciones, y r.headers tiene los nombres en minúsculas, con los headers repetidos
unidos con ", ".
Kino le entrega a tu código el texto o los bytes de un cuerpo, según su Content-Type; la otra forma
se convierte dentro del motor cuando la pides, y para un cuerpo de varios MB eso toma segundos del
tiempo de tu llamada. Pide la forma que tiene el contenido.
maxBytes(apiVersion 14, Kino 0.9.74). Kino lee el cuerpo hasta esa cantidad de bytes y se detiene: el resto nunca se descarga, yr.truncatedestrue(esfalsecuando el cuerpo entero cupo). Úsalo cuando te basta con la cabecera de una página (sus etiquetas<meta>): un servidor que ignoraRangete cuesta igual solo lo que pediste, y un cuerpo que pasaría el límite de 5 MB se corta en vez de rechazarse. Se cuentan los bytes del cuerpo después de la descompresión del transporte, y un texto cortado puede terminar en medio de un carácter. Un plugin que declarasecretssellados recibe la misma respuesta, pero Kino entonces lee el cuerpo entero (hasta 5 MB) y lo censura antes de cortarlo, así que para él la lectura no se detiene antes. Fuera de 1 a 2.000.000, o si no es un número entero, la petición falla coninvalid_request; por debajo de apiVersion 14 la opción se ignora.stopAt(apiVersion 14, Kino 0.9.74). Kino deja de leer en cuanto el texto contiene el marcador (de 1 a 32 caracteres ASCII imprimibles, comparados sin distinguir mayúsculas ASCII) y conserva todo hasta él, incluido;r.truncatedestruecuando seguía algo más. Solo para respuestas de texto (una respuesta en bytes falla coninvalid_request). ConmaxBytesgana el primer límite alcanzado; un marcador que nunca llega deja a cargo amaxBytes(o al límite de 5 MB).{ stopAt: "</head>", maxBytes: 65536 }lee los metadatos de una página y nada más. Por debajo de apiVersion 14 la opción se ignora.- Cuerpos. Un texto se envía tal cual (
text/plainsalvo que pongasContent-Type).{ json: value }envíaJSON.stringify(value)comoapplication/json;{ form: { a: 1 } }envíaapplication/x-www-form-urlencoded;{ base64: "…" }envía esos bytes. - Solo https, y solo tus hosts. El host de la petición y de cada salto de redirección tiene
que coincidir con
hosts(*.xcoincide con los subdominios dex, no conx), o ser un servidor que la persona escribió en tus ajustes, exactamente como lo escribió. Una petición a cualquier otra cosa falla antes de salir del dispositivo. Una URLhttpen un host declarado también falla, salvo que hayas declarado ese host{ "host": "…", "insecureHttp": true }(apiVersion 2, mira el manifiesto). Una dirección IP o un nombre local (localhost,.local, …) siempre se rechaza salvo que la persona lo haya escrito. Kino también rechaza un nombre declarado que resuelve a una dirección dentro de la red de la persona (loopback, privada, link-local, NAT de operador, multicast, y los prefijos IPv6 que llevan una de esas adentro), y nunca manda tu tráfico por un proxy configurado en el dispositivo. - Las redirecciones (301, 302, 303, 307, 308) las sigue Kino, hasta 10 saltos; cada salto se
revisa y cuenta como una petición -- también cuenta un salto que Kino rechaza (o por el que le
pregunta a la persona). Un 303, o un 301/302 después de un POST, se vuelve un GET sin
cuerpo. Con
redirect: "manual"recibes la respuesta 3xx (un formulario de login suele responder 302 cuando sale bien). - Por un host que se te olvidó se puede preguntar, solo durante
resolveyepisodes. Cuando una de esas llamadas pide un hosthttpsque no declaraste (incluido un salto de redirección), Kino le pregunta a la persona ("Quiere conectarse por primera vez a<host>. ¿Permitir?"). El reloj de tu llamada se detiene mientras decide, y la petición sigue después de "Permitir" (el host queda aprobado para siempre); "Rechazar" o Atrás la hacen fallar comohost_not_allowedy queda recordado. La pregunta se quita sin respuesta, sin recordar nada, si tu llamada termina antes (falló, se pasó del tiempo o la persona se fue). Una llamada pregunta por máximo 3 hosts, y por ninguno más una vez que la persona rechaza uno en ella: desde ahí, cualquier otro host no declarado de esa llamada simplemente falla comohost_not_allowed.search,home,browse, las listas en vivo, una descarga y una llamada que ya terminó nunca preguntan: la petición falla comohost_not_allowed. No te confíes: declara tus hosts. - Una respuesta que no es 2xx no lanza error: revisa
r.ok. Todo lo demás que salga mal lanza un error con uncodeque puedes revisar (e.code === "timeout"):
e.code |
Cuándo |
|---|---|
host_not_allowed |
el host (o un salto de redirección) no es uno que declaraste o que escribió la persona, o es http en un host declarado que no está marcado insecureHttp; con fetchHosts aprobado, un host que llega solo por ese permiso por http, por un puerto distinto de 443 o con un nombre de una sola etiqueta, o una dirección de la red de la casa |
rate_limited |
con fetchHosts aprobado, demasiadas peticiones a hosts que llegan solo por ese permiso: más de 60 por minuto a un mismo sitio o 600 cada 10 minutos en total (250 y 2500 en un plugin convertido de Nuvio) |
timeout |
no llegó una respuesta completa dentro de timeoutMs |
network |
la conexión falló, o hubo demasiadas redirecciones |
too_large |
la petición pasa del tope de tamaño, o un cuerpo de más de 5 MB |
invalid_request |
una URL, método, redirect o body inválidos, o más peticiones de las que permite una llamada |
Desde Kino 0.9.54 los mensajes de error de Kino (e.message) están en inglés y pueden cambiar; compara el code.
Desde Kino 0.9.55, un host_not_allowed de kino.fetch trae e.host: el host que Kino rechazó (hasta 253 caracteres), para que no tengas que sacarlo del mensaje; falta en un Kino anterior y cuando no se rechazó un solo host.
- Límites: 15 s por petición por defecto (30 s como máximo), un cuerpo de máximo 5 MB
(decodificado con el charset de su
Content-Type, UTF-8 por defecto), una petición (URL, headers y cuerpo; un cuerpo{ base64 }cuenta como su texto en base64) de máximo 1 MB, y máximo 60 peticiones en una llamada a tu plugin, incluidos los saltos de redirección y los rechazados (un plugin que Kino convirtió desde un scraper de Nuvio tiene 250). Máximo 6 de tus peticiones corren al mismo tiempo; las demás esperan su turno. - Solo dentro de
syncPullysyncPushde un proveedor de sincronización (Kino 0.9.74), la petición y el cuerpo de la respuesta pueden llegar a ceil(sync.maxBlobBytes× 4/3) + 64 KB en vez de 1 MB y 5 MB, y lo mismo el resultado de la llamada, para que el blob quepa en una sola petición. Los hosts, los cupos, las redirecciones y los tiempos no cambian, y todas las demás llamadas del plugin siguen con los topes de siempre. Mira Proveedores de sincronización. - Los headers que pones se envían tal cual, salvo
Host,Content-Length,Transfer-Encoding,Connection,Cookie2yAccept-Encoding(Kino pide gzip por su cuenta y siempre te entrega el cuerpo descomprimido; unAccept-Encodingcopiado de un navegador te traería bytes comprimidos). Si no ponesUser-Agent, Kino envíaKino/<version> (plugin <id>). Un headerContent-Typefija el tipo del cuerpo. - Cookies: cada plugin tiene su propio tarro de cookies. Kino guarda lo que ponen tus hosts
(
Set-Cookienunca le llega a tu código) y lo devuelve en las peticiones siguientes, con las reglas de siempre (dominio, ruta,Secure, vencimiento). El tarro se guarda en el dispositivo, así que un login sobrevive al sandbox y a que la app se reinicie; se borra cuando la persona cambia tus ajustes o desinstala el plugin. - Un marcador de
kino.secreten la URL, un header o el cuerpo se cambia por su valor real justo antes de que salga la petición, y esa petición queda sujeta a una regla más estricta que la de arriba: solo loshostsde tu manifiesto, porhttps, en cada salto.
kino.cookies¶
kino.cookies.get("https://site.example/", "session") // the value, or null
kino.cookies.clear() // forget every cookie of this plugin
get devuelve el valor o null, y solo responde para URL a las que tu plugin puede llegar; clear
olvida todas las cookies del plugin. Máximo 50 cookies por dominio y 64 KB en total.
kino.secret(name) (apiVersion 4)¶
const key = kino.secret("apiKey"); // un marcador, no el valor; cualquier otro nombre lanza error
await kino.fetch(`https://api.example.org/v1/list?key=${key}`);
Un marcador de posición para un valor sellado en el campo secrets de tu
manifiesto. Lleva el marcador a donde llevarías el valor. Kino abre cada sello como mucho una vez por
ejecución y nunca deja que tu código vea el valor en claro. Puedes llamarlo en el nivel superior de
tu módulo (const KEY = kino.secret("apiKey");): la revisión que Kino corre al instalar también
responde un marcador para cada nombre que declara tu manifiesto, así que la instalación pasa.
Dónde el marcador se vuelve el valor: solo dentro de kino.fetch. En la ruta y la query de la URL
(codificado con porcentajes, para que el valor no pueda partir un segmento ni agregar un parámetro;
un : queda tal cual, así que un token id:secreto como el de un bot de Telegram llega a
/bot<token>/… como se envió), dentro de un cuerpo JSON (escapado como JSON), y tal cual en los headers, un cuerpo de texto o un
campo de formulario. Un marcador en el esquema, el userinfo, el host, el puerto o el fragmento de la
URL se deja como texto: un valor nunca pasa a ser parte del host al que Kino se conecta. Un header cuyo
valor llevaría un carácter de control una vez puesto el secreto se rechaza en vez de enviarse.
A dónde puede ir esa petición: solo a un host que lista el hosts de tu manifiesto, por https, en
cada salto de redirección. Nunca a un host aprobado mientras el plugin corre, nunca a un servidor
que la persona escribió en tus ajustes, y ni streamHosts: "any" ni liveStreamHosts: "any" llegan
hasta ahí. Un salto a cualquier otra parte falla como host_not_allowed: "this plugin can't
send sealed data to <host>" para un host que no declaraste, "... without https to <host>" para
http plano aunque el host esté declarado. (Son los mensajes de Kino 0.9.54; 0.9.53 y anteriores los dicen en español. Compara el code.)
kino.crypto. Un marcador puede ser la key completa de un encrypt/decrypt AES --
exactamente un marcador, nada más en el texto -- o parte de una key más larga de HMAC o del
password/salt de PBKDF2. Siempre se rechaza, con "a sealed value can't be used here", como
data, iv o aad, como parte de una key de cifrado más larga, y como llave de un cifrado que no
es AES (des-ede3-*) -- salvo una llave de cifrado con tipo (apiVersion 6),
que sirve como llave completa de cualquier cifrado, des-ede3 incluido, y de nada más. No es una raya arbitraria: un iv o un aad conocidos bajo una llave sellada
permiten convertir un cifrado en una forma de calcular la llave de vuelta, y una llave rellenada con
bytes conocidos reduce la búsqueda a la parte desconocida. HMAC y PBKDF2 pasan toda su entrada por un
hash, así que un prefijo o sufijo conocido nunca separa el secreto.
Tapado. Todo lo que Kino le devuelve a tu código y que podría llevar un valor sellado --
r.text(), r.url, los valores de los headers, el r.base64() de un cuerpo de texto,
kino.cookies.get, un mensaje de error, una respuesta de kino.crypto y cada línea de kino.log --
trae el valor cambiado de nuevo por su marcador, haya usado o no esta ejecución el secreto. Las
formas que se detectan: en crudo, codificado con porcentajes (estricto, + por espacio y %20 por
espacio), escapado como JSON (incluso con \/ por / y \uXXXX para lo que no es ASCII, en
mayúsculas o minúsculas, como lo escriben PHP y Python) y base64/base64url. Una URL que el servidor
devuelve con el valor adentro vuelve con el marcador, así que un Stream armado con ella no se
reproduce: los marcadores solo se cambian en las peticiones de kino.fetch, nunca en lo que tu plugin
le devuelve a Kino. No se detecta: una respuesta binaria (r.base64() de algo que nunca fue texto),
el nombre de un header de respuesta, un %xx en minúsculas que un servidor devuelva, y un valor que
el servidor transforma a propósito (con hash, al revés…). Un error de kino.crypto todavía puede
decir cuántos bytes tenía una llave sellada, o si era hex o base64 válido -- metadatos, nunca el
valor. Prefiere valores de al menos 8 bytes: uno más corto igual se tapa donde aparezca dentro de
texto sin relación, lo que se vuelve más ruidoso entre más corto sea.
kino.crypto¶
Funciones síncronas para lo que hacen los sitios para esconder sus enlaces. Cada argumento de texto
es texto en una codificación que tú escoges (utf8, hex o base64); los errores traen
code: "crypto_error".
kino.crypto.hash("sha256", "hola") // hex by default
kino.crypto.hmac("sha1", "key", "data", { outputEncoding: "base64" })
kino.crypto.decrypt("aes-128-cbc", { key: "0123456789abcdef", iv: "abcdef9876543210", data: b64 })
kino.crypto.encrypt("aes-256-gcm", { key: k, keyEncoding: "hex", iv: n, ivEncoding: "hex", data: "hola" })
kino.crypto.pbkdf2("sha256", "password", "salt", 10000, 32) // hex
kino.crypto.randomBytes(16) // hex
kino.crypto.uuid()
encryptrecibe texto (utf8) y devuelvebase64;decryptrecibebase64y devuelve texto. Cambia cualquiera de los dos coninputEncoding/outputEncoding; las llaves, los IV y elaadde GCM usankeyEncoding,ivEncoding,aadEncoding(por defectoutf8).hash,pbkdf2yrandomBytesdevuelvenhexpor defecto.- CBC y ECB usan relleno PKCS#7 salvo que pases
padding: "none". GCM pega su etiqueta de 16 bytes al final del texto cifrado, y la espera ahí para descifrar (como la mandan casi todos los sitios). - Un tamaño de llave equivocado, un relleno malo o una etiqueta GCM que no cuadra lanzan un error; nunca devuelven basura en silencio.
- Un marcador de
kino.secretsolo se acepta como lakeycompleta de unencrypt/decryptAES, o como parte de unakeyde HMAC o delpassword/saltdepbkdf2-- nunca endata,ivoaad, ni como llavedes-ede3. Una llave de cifrado con tipo (apiVersion 6) es la excepción: la llave completa de cualquier cifrado,des-ede3incluido, y nada más.
| Función | Algoritmos |
|---|---|
hash, hmac |
md5, sha1, sha256, sha512 |
encrypt, decrypt |
aes-128-cbc, aes-192-cbc, aes-256-cbc, aes-128-ecb, aes-192-ecb, aes-256-ecb, aes-128-ctr, aes-192-ctr, aes-256-ctr, aes-128-gcm, aes-192-gcm, aes-256-gcm, des-ede3-cbc, des-ede3-ecb |
pbkdf2 |
sha1, sha256, sha512 |
| codificaciones | utf8, hex, base64 |
generateKeyPair (apiVersion 6) |
ec, ed25519, x25519; ec en P-256, P-384; máximo 64 llaves privadas vivas por runtime (una nueva descarta la más vieja) |
sign, verify (apiVersion 6) |
ECDSA con SHA-256, SHA-384 como der o ieee-p1363; Ed25519; una firma de máximo 512 bytes |
importKey, deriveSharedSecret (apiVersion 6) |
llaves públicas como jwk, spki, raw; ECDH (misma curva) y X25519 |
Operaciones de bytes (Kino 0.9.74: revisa si están)¶
Para protocolos binarios (MTProto y parecidos), Kino 0.9.74 tiene cinco operaciones más
sobre textos en cualquiera de las tres codificaciones. Dependen del Kino en el que corres, no de tu manifiesto: cada plugin
recibe el kino.crypto de la versión de ese Kino, declare el apiVersion que declare, y un Kino anterior a una de ellas no
la tiene (Kino 0.9.74 tiene las cinco, un Kino más viejo ninguna; las versiones de desarrollo anteriores a 0.9.74 no tienen convert ni aesIgeVerify). Revisa cada una y ten
un plan B: typeof kino.crypto.convert === "function". No necesitan capacidad.
kino.crypto.aesIge("decrypt", keyHex, ivHex, dataHex, { keyEncoding: "hex", ivEncoding: "hex", inputEncoding: "hex", outputEncoding: "hex" })
kino.crypto.aesIgeVerify(keyHex, ivHex, dataHex, { mac: msgKeyHex, macPrefix: authKeySliceHex, macOffset: 8,
keyEncoding: "hex", ivEncoding: "hex", inputEncoding: "hex", outputEncoding: "hex" }) // decrypt + SHA-256 MAC check
kino.crypto.modPow(baseHex, expHex, modHex) // big-endian hex (at most 4,096 bits), padded to the modulus' width
kino.crypto.gunzip(b64) // base64 in, text out by default
kino.crypto.convert(hex, "hex", "base64") // re-encode natively, no JavaScript loop over the bytes
aesIge es AES-256-IGE (llave de 32 bytes, iv de 32 bytes, datos múltiplos de 16 bytes); aesIgeVerify responde el
texto descifrado solo cuando los bytes macOffset a macOffset + mac.length de SHA-256(macPrefix || plaintext) son
iguales a mac, y si no falla con "the mac doesn't match". Un valor sellado se rechaza en cualquier campo; cualquier cosa
mal formada falla con "invalid crypto operation". Para qué existen y cómo usarlas sobre un trozo de 1 MiB: Sockets y
bytes del plugin.
Pares de llaves, firmas y acuerdo de llaves (apiVersion 6)¶
Algunos reproductores demuestran que son un reproductor de verdad firmando un reto: crean un par de
llaves, firman lo que manda el servidor con la llave privada y devuelven la llave pública.
kino.crypto lo hace con llaves que nunca salen de Kino:
// Node: const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
// WebCrypto: await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign"]);
async function createAttest(challenge) {
const { privateKey, publicKey } = kino.crypto.generateKeyPair({ type: "ec", namedCurve: "P-256" });
// La firma ECDSA de WebCrypto es r||s (64 bytes en P-256): format "ieee-p1363". La de Node es "der".
const signature = kino.crypto.sign({ key: privateKey, data: challenge, hash: "SHA-256", format: "ieee-p1363" });
return { publicKey: publicKey.jwk, signature }; // signature en base64; outputEncoding: "hex" para hex
}
generateKeyPair({ type: "ec", namedCurve: "P-256" | "P-384" }),{ type: "ed25519" }o{ type: "x25519" }responde{ privateKey, publicKey }.publicKeyes{ type, namedCurve?, jwk, spki, raw }: el objeto JWK en el orden de llaves de WebCrypto ({ crv, kty, x, y }, base64url), el SubjectPublicKeyInfo DER en base64, y la llave cruda en base64 (04||x||yparaec, 32 bytes en los demás).privateKeyes un manejador,{ type, namedCurve?, handle }: la llave misma se queda dentro de Kino. Un manejador sirve solo en el sandbox que lo creó: no en el carril de firma design(), no después de que el plugin se reinicia (se cierra tras unos minutos sin uso), nunca en otro aparato; así que crea la llave en la llamada que la usa. Máximo 64 vivas a la vez; una nueva descarta la más vieja. Las llaves privadas no se pueden importar ni exportar.sign({ key, data, encoding?, hash?, format?, outputEncoding? })leedatacomoutf8salvo que digashexobase64, y responde en base64.ec:hash"SHA-256"(por defecto) o"SHA-384",format"der"(por defecto) o"ieee-p1363"(64 bytes en P-256, 96 en P-384).ed25519: 64 bytes, sinhash.verify({ key, data, signature, signatureEncoding?, hash?, format? })respondetrue/false; una firma mal formada esfalse.keyes una llave pública (la tuya, o la de otro desdeimportKey), un{ jwk }suelto, o tu propia llave privada.importKey({ format: "jwk", key: objetoJwk }),{ format: "spki", key: base64 }o{ format: "raw", key: base64, type, namedCurve? }responde una llave pública con la misma forma; un punto fuera de su curva lanza un error.deriveSharedSecret({ privateKey, publicKey })es ECDH (las dosecen la misma curva: 32 bytes en P-256, 48 en P-384) o X25519 (32 bytes), en base64 por defecto. Pásalo por un hash (o un HKDF conhmac) antes de usarlo como llave.- Ninguna de estas cinco funciones acepta un marcador de
kino.secret.
| Node / WebCrypto | kino.crypto |
|---|---|
generateKeyPairSync("ec", { namedCurve: "P-256" }) / subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, …) |
generateKeyPair({ type: "ec", namedCurve: "P-256" }) |
generateKeyPairSync("ed25519") / generateKeyPairSync("x25519") |
generateKeyPair({ type: "ed25519" }) / { type: "x25519" } |
publicKey.export({ format: "jwk" }) / subtle.exportKey("jwk", publicKey) |
publicKey.jwk |
publicKey.export({ format: "der", type: "spki" }).toString("base64") / exportKey("spki", …) |
publicKey.spki |
subtle.exportKey("raw", publicKey) |
publicKey.raw (base64) |
crypto.sign("sha256", data, privateKey) |
sign({ key: privateKey, data, hash: "SHA-256" }) (DER) |
crypto.sign("sha256", data, { key, dsaEncoding: "ieee-p1363" }) / subtle.sign({ name: "ECDSA", hash: "SHA-256" }, …) |
sign({ key, data, hash: "SHA-256", format: "ieee-p1363" }) |
crypto.sign(null, data, ed25519Key) / subtle.sign("Ed25519", …) |
sign({ key, data }) |
crypto.verify(…) / subtle.verify(…) |
verify({ key: publicKey, data, signature, … }) |
createPublicKey({ key: jwk, format: "jwk" }) / subtle.importKey("jwk", …) |
importKey({ format: "jwk", key: jwk }) |
crypto.diffieHellman({ privateKey, publicKey }) / subtle.deriveBits({ name: "ECDH" o "X25519", public }, …) |
deriveSharedSecret({ privateKey, publicKey }) |
Los Buffers se vuelven textos: pasa encoding/outputEncoding (hex o base64) donde Node recibe o
entrega un Buffer. No existe kino.crypto.generateKeyPairSync: una librería de Node o de navegador que lo
llame hay que adaptarla a estas llamadas. Un plugin que las usa debe declarar "apiVersion": 6, para
que un Kino sin ellas se niegue a instalarlo (validate lo dice).
kino.browser (apiVersion 6)¶
Solo con "browser": true (solo captura) o "browser": "pages" (captura y lectura de páginas) en el
manifiesto, aprobado en rojo por la persona. kino.browser.capture(url,
options?) abre una página en una vista web oculta dentro de un resolve que empezó la persona y
devuelve las peticiones de video que hizo, con los encabezados y cookies para reproducirlas;
kino.browser.page(url, options?) devuelve el HTML de una página cuando ya pasó la revisión automática
del sitio. Kino nunca resuelve un captcha: una página que pide una persona termina la llamada con
blocked. Prefiere kino.fetch siempre que funcione. Todo -- dónde se puede llamar cada una, el modelo
de seguridad, los tiempos, los errores y un ejemplo completo -- está en Navegador oculto. Desde
Kino 0.9.54 una captura también puede juntar todas las peticiones que coinciden, esperar una cookie y responder lo que
tenía cuando se acaba el tiempo (captureAll y compañía; comprueba antes
kino.browser.captureAll === true), y kino.browser.page también se puede llamar desde la exportación
details (apiVersion 8).
kino.cloudstream (solo plugins generados)¶
Solo existe en los plugins que Kino mismo genera cuando la persona instala un plugin desde un repositorio de CloudStream
(Kino 0.9.54); un plugin que escribes tú nunca lo tiene (typeof kino.cloudstream es "undefined"), diga lo que diga su
manifiesto. Sus cuatro funciones (search, mainPage, load, loadLinks, con sus tipos en
kino.d.ts) corren un proveedor de CloudStream dentro de la app complemento de CloudStream, que va
aparte. Lanzan not_found cuando el propio proveedor falló y unavailable en todo lo demás (no hay complemento, un
plugin incompatible, se acabó el tiempo, una petición rechazada; el mensaje dice cuál).
await kino.meta(query): preguntarle a Kino por un título (Kino 0.9.53)¶
if (typeof kino.meta === "function") { // Kino 0.9.53 o superior: antes no existe, compruébalo
const m = await kino.meta({ type: "series", ids: { imdb: "tt0944947" }, lang: kino.lang });
if (m) {
// { title, overview, year, poster, backdrop, logo, genres, runtimeMinutes, tagline, certification, directors,
// episodes: [{ season, number, title, overview, still, airDate, id: "tt0944947:1:1" }],
// ids: { imdb, tmdb, tvdb, kitsu, mal, anilist }, ratings, cast, sources: ["tmdb", ...] }
}
}
Kino responde lo que sabe de un título, y tu plugin nunca toca una llave de TMDB para eso. La respuesta se arma igual
que la ficha de Kino arma la página de un título: primero la consulta de TMDB de Kino (una función de la app, con la
llave de Kino, en español es-MX, o desde Kino 0.9.54 en el idioma de la app: es-MX o en-US; ninguna llave llega a tu código), luego AniList para un anime (con el mapeo de ids
de anime, así que también sirve un id kitsu, mal o anilist), y luego los plugins meta que la persona tiene
instalados (por ejemplo un addon de metadatos de Stremio configurado con su propia llave). Cada fuente siguiente solo
llena lo que las anteriores dejaron vacío; las notas se suman. null quiere decir que nadie conocía el título: nunca es
un error.
- La consulta:
type("movie"o"series") y al menos un id:imdb("tt0133093"), otmdb,tvdb,kitsu,mal,anilistcomo enteros positivos (un número o un texto de dígitos, hasta 2147483647).lang("es","es-MX") va a los plugins meta de la persona. Una consulta mal formada lanzainvalid_request; la consulta entera ocupa como máximo 4.096 caracteres en JSON. - La respuesta: cada campo aparece solo cuando se conoce, menos
ids(todos los ids que Kino conoce del título, incluidos los tuyos: pregunta con un id de IMDb y recibe los de TMDB y TVDB) ysources("tmdb","anilist","plugin": quién aportó).episodessolo para una serie (máximo 5.000; se recortan desde el final para que la respuesta entera quede por debajo de 1.000.000 de caracteres), cada uno con suidal estilo de Stremio.ratingsmáximo 6 (la nota de TMDB es{ source: "tmdb" }),castmáximo 20,genresmáximo 5. - Nunca tú mismo: a tu propio export
metanunca se le pregunta en tu nombre, y unkino.metallamado desde dentro de un exportmetano le pregunta a ningún plugin (solo a TMDB y AniList), así que dos plugins meta no pueden preguntarse uno al otro en bucle. - Límites: máximo 30 llamadas por minuto por plugin (luego
rate_limited; es un balde de fichas que recupera una llamada cada 2 s); como mucho 8 s (6 s por cada plugin meta; se responde lo que se sepa para entonces), contados dentro del límite de tiempo de tu propia llamada; la parte de TMDB y AniList queda en caché 30 minutos por consulta y las respuestas de los plugins meta comparten la caché de 30 minutos de la ficha. No desdesign()(not_allowed). Ningún destino de red nuevo: TMDB y AniList son de Kino, y cada plugin meta usa sus propios hosts aprobados. La telemetría de Kino solo cuenta llamadas y códigos de error, nunca los ids. - Sin
apiVersionnuevo:kino.metaestá en todos los plugins desde Kino 0.9.53, diga lo que diga su manifiesto; las versiones anteriores no tienen esa función, así que compruébala (typeof kino.meta === "function").node sdk/validate.mjsavisa si tu código la llama sin esa comprobación.
Por título, sin ids (apiVersion 9, Kino 0.9.55)¶
if (typeof kino.meta === "function" && kino.meta.byTitle === true) { // Kino 0.9.55 o superior
const m = await kino.meta({ type: "movie", title: "Matrix", year: 1999 });
if (m) console.log(m.ids.tmdb, m.ids.imdb); // 603, "tt0133093"
}
Cuando tu fuente solo te da el nombre y el año, pásaselos a Kino en vez de los ids: { type, title, year?, lang? }.
- Cómo lo busca: Kino busca el título en TMDB (la búsqueda de películas o la de series según
type, en español es-MX, la primera página) y se queda con el resultado cuyo título en español o título original es igual al tuyo, sin mayúsculas, tildes ni signos («¡Amélie!» y «amelie» son el mismo). Conyear, gana el de ese año exacto; si no hay, uno que esté a un año (la fecha de estreno puede variar según el país). Una película nunca responde por una serie, ni al revés. - Nunca adivina: si dos resultados empatan (el mismo título y el mismo año, o el mismo título y no diste año) o
ninguno coincide, la respuesta es
null. Si tienes el año, mándalo: es lo que separa una película de su remake. - La misma respuesta de siempre: si lo encuentra, responde exactamente como si hubieras preguntado por su id, con
idslleno (TMDB, IMDb, TVDB…), y a los pluginsmetade la persona se les pregunta por esos ids. Mismos límites (30 por minuto, 8 s), y la caché de 30 minutos es por tipo, título normalizado y año. - La consulta:
titlede 1 a 200 caracteres;yearde 1870 a 2100 (un número o un texto de 4 dígitos), y solo junto atitle. Cualquier otra cosa lanzainvalid_request. Si mandasidsytitle, ganan los ids. - Necesita
"apiVersion": 9; compruebakino.meta.byTitle === true: por debajo de 9kino.meta.byTitleno existe y el título no llega, igual que en un Kino anterior, así que la consulta respondeinvalid_request(«necesita al menos un id»).node sdk/validate.mjsavisa si llamaskino.metacontitlesin esa comprobación.
Con el kit, la búsqueda de TMDB de Kino no existe: el archivo de KINO_META_FIXTURE responde con claves
"movie:title:the matrix:1999" (el tipo, title, el título normalizado y el año, o sin el año), y pickMetaTitle de
sdk/kino-shim.mjs te dice qué escogería Kino entre resultados de TMDB que traigas tú.
Lo contrario -- que tu plugin describa títulos para la ficha de Kino -- es la capacidad meta. Con el
kit de Node, kino.meta responde null salvo que apuntes KINO_META_FIXTURE a un archivo JSON de respuestas (claves
"movie:imdb:tt0133093" o "tmdb:1399", y por título "movie:title:the matrix:1999"; ver Probar en local).
await kino.tmdb(path, params?): TMDB sin una llave en tu código (Kino 0.9.53)¶
async function tmdb(path, params) {
if (typeof kino.tmdb === "function") return kino.tmdb(path, params); // Kino 0.9.53+: Kino pone la llave, nunca tu código
// Kino anterior: tu propio ajuste "tmdbKey", como antes.
const key = kino.config.get("tmdbKey");
if (!key) throw kino.error("auth_required", "falta la llave de TMDB");
const q = new URLSearchParams({ ...params, api_key: key });
const r = await kino.fetch(`https://api.themoviedb.org/3${path}?${q}`);
if (!r.ok) throw kino.error(r.status === 404 ? "not_found" : "unavailable", "TMDB respondió " + r.status);
return r.json();
}
const semana = await tmdb("/trending/movie/week", { language: "es-MX" });
Una puerta de solo lectura a la API v3 de TMDB. Tu plugin nunca lleva una llave: Kino pone una, en este orden:
- La llave propia de Kino, siempre. Sus llamadas pasan por la caché de TMDB de Kino (la misma de las pantallas de Kino, guardada en disco; una petición que ya va en camino se comparte, no se repite) y por límites propios, para que los plugins no gasten la cuota de TMDB de Kino: máximo 20 llamadas cada 10 s por plugin y 60 cada 10 s entre todos los plugins llegan a TMDB con la llave de Kino.
- La llave de la persona, solo si la de Kino falla: TMDB rechaza la llave de Kino (401/403), TMDB la limita (429), o se agotó uno de los dos límites de arriba. Entonces la misma petición sale otra vez con la llave que la persona escribió en Ajustes de todos los perfiles ▸ Llaves ▸ Tu llave de TMDB (opcional; una API key v3 de 32 caracteres hexadecimales, o un token de lectura v4; se sincroniza entre sus aparatos) o, si no hay, con la que configuró en un addon de Stremio instalado (Kino busca en la configuración guardada de cada addon un campo cuyo nombre contenga "tmdb", ninguno se nombra en el código, y la usa solo después de que la persona dijo que sí una vez a "Usar la llave de TMDB de tu addon <nombre>", también sincronizado).
- Sin ninguna de las dos: una copia de la caché de hasta 7 días cuando la hay; si no,
rate_limited(el límite de Kino, o el 429 de TMDB) ounavailable(TMDB rechazó la llave de Kino).
no_tmdb_key queda para una versión de Kino sin llave propia y una persona sin llave: e.userMessage es entonces la
frase de Kino para la persona, en su idioma: "Agrega tu llave de TMDB en Ajustes de todos los perfiles ▸ Llaves" /
"Add your TMDB key in Settings for all profiles ▸ Keys" (Kino 0.9.53 también mencionaba un addon de TMDB de Stremio). Si no
la atrapas, la persona lee esa misma frase. En esa versión, una llave de la persona que TMDB rechaza también es
no_tmdb_key.
Una llave que tu plugin guarda en sus propios ajustes (un ajuste tmdbKey) es asunto de tu plugin: Kino nunca la lee para
kino.tmdb. Kino pone la llave él mismo (como api_key para una llave v3, como encabezado Authorization: Bearer para un
token v4): tu código nunca ve ninguna, ni la de Kino ni la de la persona, y ni las respuestas, ni los errores, ni los
registros la llevan. No declaras api.themoviedb.org en hosts para esto.
path: empieza por/discover,/trending,/search,/movie,/tv,/find,/genre,/configuration,/persono/collection("/movie"o"/movie/603/credits"), sin la versión/3, sin texto de consulta, sin..y sin//. Cualquier otra ruta (una cuenta, una lista, una calificación: lo que escribe o lee la cuenta de la persona) esinvalid_request. Solo GET.params: un objeto simple de máximo 20 textos, números o booleanos, cada uno de máximo 500 caracteres como texto, con nombres comolanguage,page,with_genres,vote_count.gte,append_to_response. Nuncaapi_key,session_id,guest_session_id,request_tokenniaccess_token(invalid_request).- La respuesta: el cuerpo ya convertido desde JSON.
404esnot_found, un cuerpo de más de 2 MiB estoo_large; cuando TMDB no responde en 15 s (timeout), no se puede alcanzar (network) o responde 5xx (unavailable), llega en su lugar la copia de la caché (de hasta 7 días) si la hay. Cualquier otra cosa que no sea un 2xx con JSON esunavailable. - Límites: máximo 40 llamadas cada 10 s por plugin, conteste la llave que conteste (un balde de fichas), más los dos
límites de la llave de Kino de arriba; una respuesta fresca de la caché no cuenta en los de Kino. En caché 10 minutos en
memoria por ruta y parámetros (o sea, por
language; solo cuerpos de hasta 512 KiB), y en disco con la caché de TMDB de Kino (desde 1 hora para listas y búsquedas hasta 7 días para/findy/genre), la haya traído la llave que sea. No cuenta en las 60 peticiones por llamada dekino.fetch. No desdesign()(not_allowed). La telemetría de Kino solo cuenta llamadas según cómo se respondieron (caché, llave de Kino, llave de la persona) y códigos de error, nunca una ruta ni una llave. - Una llamada que Kino dejó de esperar (una falla corregida en Kino 0.9.54): cuando Kino abandona una de tus llamadas
(la persona salió de la pantalla, se acabó el tiempo) pero igual le pasa su respuesta tardía a una llamada idéntica que
la está esperando,
kino.tmdbykino.metasiguen respondiendo hasta que tu código termina. Kino 0.9.53 respondíanot_alloweddesde ese momento, así que un Inicio armado con muchas llamadas akino.tmdbpodía quedarse solo con su primera fila hasta reiniciar. - Sin
apiVersionnuevo: Kino 0.9.53 o superior; compruébala (typeof kino.tmdb === "function") y deja tu propio ajuste de llave solo como respaldo para versiones anteriores de Kino, como arriba. Un plugin que arma su catálogo con TMDB ya no necesita pedirle una llave a cada persona. Un ejemplo completo: Un catálogo de TMDB sin llave en el plugin.
Con el kit de Node, kino.tmdb usa tu llave de KINO_TMDB_KEY (o "tmdbKey" en sdk/config.json) donde la app usa la
de Kino, con el límite más estricto de la llave de Kino (20 cada 10 s; el kit no tiene una llave de la persona a la que
pasar), y con KINO_TMDB_FIXTURE responde sin red desde un archivo JSON con claves "<path>?<params ordenados por
nombre>" o "<path>". Sin ninguno de los dos lanza no_tmdb_key, como una versión de Kino sin llave propia.
await kino.image.thumbnail(url, { maxWidth?, maxBytes? }) (Kino 0.9.84)¶
Kino descarga una imagen https con las mismas reglas de red que tu kino.fetch (tus hosts, solo https, nunca la red de
la casa, tu cupo de peticiones; máximo 5 MB) y responde un JPEG pequeño como "data:image/jpeg;base64,…", para que una
tarjeta lleve su imagen dentro de un mensaje. maxWidth de 32 a 400 (200 por defecto), maxBytes de 2.048 a 32.768 (16.384
por defecto), máximo 20 llamadas por minuto. Errores: bad_request, host_not_allowed, not_found, network, timeout,
too_large, not_image, rate_limited, not_allowed (desde sign()). Sin apiVersion nuevo: revisa
typeof kino.image === "object". La guía completa, con el kit: kino.image.thumbnail.
kino.nuvio (apiVersion 11, Kino 0.9.71)¶
Experimento. Con la capacidad nuvio y nuvioRepos en el manifiesto, tu plugin le pide a Kino que instale y use los scrapers de un repositorio de Nuvio: kino.nuvio.available({ repo }), use({ repo, scrapers }), scrapers({ repo }) y streams({ repo, type, tmdbId, season?, episode?, scrapers?, timeoutMs? }). Solo dentro de tus funciones; 20 llamadas por minuto; detéctalo con typeof kino.nuvio === "object". Todo, con un ejemplo completo, en Plugins que usan scrapers de Nuvio.
kino.seed(session): compartir una sesión anónima de invitado (Kino 0.9.55)¶
Algunas fuentes dan una sesión de invitado anónima y gratuita a quien la pida, y bloquean regiones enteras para iniciar
sesión. kino.seed deja que tu plugin le entregue a Kino una de esas sesiones para que las personas de esas regiones
tengan sesiones vivas a las que recurrir. Es de mejor esfuerzo y síncrona: no responde nada y nunca lanza hacia tu plugin,
así que la llamas y sigues.
if (typeof kino.seed === "function") {
kino.seed({ sn, userId, userToken, jwtToken, mintedAt }); // una sesión de invitado nueva, ya comprobada
}
- Qué enviar. Una sesión que acabas de crear para esto y nada más, nunca la de la persona, y solo después de comprobar que funciona (por ejemplo, leyendo una página del catálogo con ella). Si un aparato no puede crear una sesión de invitado que funcione (región bloqueada, un rechazo, una respuesta vacía), no envía nada.
- Qué guarda Kino. Solo estas claves, cada una un texto corto (máximo 2.048 caracteres) o un número finito:
sn,userId,userToken,jwtToken,mintedAt,customer,activeTimeyavailableTime. Cualquier otra clave se descarta. Sisn,userIdyuserTokenno están todas y con contenido, se descarta la sesión entera. La sesión ya limpia tiene como máximo 8.192 caracteres, y una sesión cuyo JSON pase de 16.384 caracteres ni siquiera cruza. - Consentimiento. Kino la envía a su propio tablero de errores solo cuando el consentimiento de telemetría de plugins
está activo para tu plugin (el mismo que usa
kino.log.report, con"telemetry": trueen tu manifiesto); con él apagado, nada sale del aparato. Es anónima: no nombra ninguna cuenta ni lleva nada de la persona. Dilo en la descripción de tu plugin y dale a la persona un ajuste para apagar el aporte. - Frecuencia. No crees una en cada Inicio. Guarda una marca de tiempo en
kino.storagey comparte como máximo una sesión cada pocas horas por aparato. - Detéctalo. Un Kino anterior no tiene
kino.seed; la comprobación de arriba es toda la compatibilidad. La secciónkinoSeeddel contrato trae las mismas claves y límites (contract.json). - En el kit de Node
kino.seedtambién existe: no envía nada, aplica el mismo filtro y registra qué claves conservaría Kino (nunca los valores), avisando cuando tu manifiesto no tiene"telemetry"y la app no enviaría nada.
kino.sync.remoteChanged(): avisarle a Kino que la copia remota cambió (Kino 0.9.74)¶
Solo para un proveedor de sincronización que declara
"sync": { "mode": "realtime" }. Cuando tu código se entera de que otro aparato guardó una copia nueva,
se lo dice a Kino, y Kino la trae de una vez en vez de esperar al siguiente pullEveryMs:
export async function syncStatus() {
const head = await readRemoteHead(); // una petición liviana, nunca el blob
if (typeof kino.sync === "object" && head.version !== kino.storage.get("lastSeen")) {
kino.storage.set("lastSeen", head.version);
kino.sync.remoteChanged();
}
return { ready: true };
}
- Síncrona y liviana: no responde nada. Kino acepta como mucho un aviso cada 30 segundos y descarta uno que llega mientras ya corre una lectura (esa lectura ya ve la copia remota), así que llámala cuando notes un cambio, nunca en un ciclo.
- Avisa desde
syncStatus, no desdesyncPull: un aviso enviado durante una lectura se descarta. Tu código solo corre mientras Kino lo llama, así que no puedes dejar una conexión abierta entre llamadas; de todos modos Kino sigue trayendo la copia cadapullEveryMs. not_allowedpara cualquier otro plugin: lanza{ code: "not_allowed" }salvo que el plugin declare la capacidadsyncProviderconmode: "realtime".- Detéctala con
typeof kino.sync === "object": un Kino anterior no tienekino.sync.
kino.sync.active() y kino.sync.setActive(on) (Kino 0.9.78)¶
Aditivo, para un plugin con la capacidad syncProvider aprobada. Kino mantiene un solo proveedor de sincronización a la vez, así
que tu plugin puede dejar que la persona cambie a él, o se aleje de él, desde su propia pantalla, en vez de mandarla a Ajustes ▸ Conectar:
if (typeof kino.sync.setActive === "function") {
const on = await kino.sync.active(); // ¿este plugin es el proveedor en ESTE aparato?
await kino.sync.setActive(!on); // desde un botón que la persona tocó: true le pregunta primero, false vuelve a la sincronización local
}
setActive(true)muestra la pregunta propia de Kino (el nombre con que instalaron tu plugin y las palabras de Kino; no puedes cambiarlas) y, si la persona acepta, hace de tu plugin el único proveedor activo: el actual se apaga. Si lo rechaza, respondefalsey nada cambia. Si ya estaba activo, respondetruey no pregunta nada.setActive(false)no pregunta nada y devuelve a la persona a la sincronización local de Kino, solo cuando tu plugin es el activo.- Ambos solo corren dentro de una llamada que la persona inició con un toque (un
actionde ajustes, unpanelActiono elscreenEventde una pantalla tras su propia pulsación), nunca desde un trabajo, un temporizador ni elopende una pantalla: allí rechazan connot_allowed. Leeractive()funciona en cualquier llamada. - Los rechazos traen
code:not_allowed,unavailable(el plugin no puede ser proveedor ahora),busy,timeout(dos minutos sin respuesta) einvalid_request(no es un booleano). - Fija la llave que tu proveedor necesita (
sync.keySecret) antes de ofrecer el interruptor: un proveedor sin llave aparece como «no configurado». - No es un
apiVersion: un Kino anterior no tiene ninguna de las dos funciones, así que detéctalas contypeof kino.sync.setActive === "function"y dejago: { syncProvider: true }(abre los ajustes de proveedor de Kino; mira Referencia de pantallas) como camino para las versiones viejas.
Mira Proveedores de sincronización.
kino.ws: WebSockets (apiVersion 13, Kino 0.9.74)¶
Con la capacidad socket: await kino.ws.open(url, { protocol? }) abre un WebSocket de salida y responde un socket con
send(data, { encoding? }), recv(timeoutMs?, { encoding? }) y close(). wss:// por el puerto 443 a un host que tu
manifiesto declara y que la persona aprobó, nunca la red local ni una IP literal; máximo 4 sockets abiertos por plugin,
8 MiB en cola sin leer por socket, 786.000 bytes por frame enviado, 60 s por recv. Los frames son Uint8Array, o
textos hex / base64 con { encoding } (el camino rápido: ningún ciclo de JavaScript sobre los bytes). Errores:
not_https, host_not_allowed (con host), limit, closed, network, timeout, too_large, invalid_request.
La guía completa: Sockets y bytes del plugin.
kino.catalog (apiVersion 13, Kino 0.9.74)¶
Con la capacidad catalog: upsert(items), search({ q?, limit?, offset?, order? }), get(ids), remove(ids),
clear() y count() sobre un catálogo SQLite de tus propios ítems (hasta 100.000, en un solo archivo de 64 MiB solo
para tu plugin, solo en el aparato). Cada llamada es async; no hay SQL. La guía completa, con cada regla, límite y
error: Catálogo y almacenamiento grande.
kino.qr.scan(options?) (apiVersion 13, Kino 0.9.74)¶
Con la capacidad qrScan: abre el lector de cámara de Kino en pantalla completa en el teléfono y resuelve con el texto
leído (de 1 a 4.096 caracteres) o con null cuando la persona lo cierra. { title?, titleEn? }, de máximo 80
caracteres cada uno. Solo desde un ajuste action, un panelAction o un screenEvent que sigue a un toque o un envío de la persona (apiVersion 14; not_allowed desde cualquier otra cosa);
unavailable en una TV o sin cámara; busy, timeout (120 s), permission_denied, invalid_request. Mostrar un QR no
necesita capacidad: el tipo qr del formulario de ajustes. Mira Códigos QR para las reglas, los errores y una
receta de inicio de sesión entre dos aparatos.
kino.files (apiVersion 21, Kino 0.9.82)¶
Con la capacidad files: archivos que están en el aparato de la persona. pick({ kinds?, multiple?, copy? }) y
pickFolder({ kinds? }) abren el selector (solo desde una pulsación de la persona; not_allowed desde cualquier otra cosa) y
responden handles opacos, nunca una dirección; list, folders, info, read, readText (como máximo 2.000.000 bytes por
llamada), forget y url (kino-file:<id>, para el url de un stream o de una pista de audio) no necesitan pulsación.
Errores: unavailable, not_allowed, busy, timeout, invalid_request, gone, too_large, denied, quota. Nada se
sube ni se envía. La guía completa, con cada regla y límite: Archivos del aparato.
kino.progress (apiVersion 22, Kino 0.9.83)¶
Con la capacidad progress (sin línea de consentimiento): dónde va la persona en un elemento de tu plugin (un capítulo y una
página de manga, una posición en un libro). set({ id, fraction, title?, poster?, label?, labelEn?, resume?, done?, doneAt? }),
get(id) (la entrada o null), list({ limit?, sinceMs? }) (el último que se guardó primero, cada entrada con su id; limit
de 1 a 100, 50 por defecto) y clear(id). resume es cualquier valor JSON de hasta 1024 bytes serializado que Kino nunca lee.
Un elemento está terminado con done: true o cuando fraction >= doneAt (0,9 por defecto). Se guarda por perfil, se sincroniza
entre los aparatos de la persona y va en las copias de seguridad; Kino no dibuja nada con esto, tu plugin arma su propio
estante con list. Se rechaza (not_allowed) en un trabajo que corre para un perfil distinto del activo. Errores:
not_allowed, bad_request, too_large. La guía completa: Guardar dónde va la persona.
kino.screen (apiVersion 14, Kino 0.9.74)¶
Lo que dibuja la pantalla de este Kino, para detectar funciones: kino.screen.names (los tipos de nodo como los escribe
esta guía, Column, TextField, titleRail...), kino.screen.widgets (los mismos con sus nombres anteriores) y
kino.screen.version (el número propio del contrato de pantallas, 1 por ahora). undefined en un Kino anterior. Mira
Pantallas. kino.screen.httpImages (Kino 0.9.88, sin apiVersion nuevo) es true cuando este Kino también
dibuja las imágenes de una pantalla por http en un host público, como dibuja un póster; undefined antes, donde son solo https
(imágenes http).
kino.library, kino.room, kino.ai y kino.shared (apiVersion 14, Kino 0.9.74)¶
Cada uno necesita su capacidad: lo que la persona vio y guardó (library; desde apiVersion 17 también kino.library.stats), una sala por internet
alojada en el aparato (room), una pregunta a la IA de texto de Kino (ai) y
unos pocos resultados pequeños sincronizados entre los aparatos de la persona (shared). Un
job(ctx) en segundo plano (schedule) está en Trabajos en segundo plano.
kino.identity y kino.notifications (apiVersion 15)¶
Cada una necesita su capacidad (declarativa, no exportas nada): kino.identity.telegram({ challenge? }) responde un seudónimo
de la persona para tu plugin y, para las llaves de autor en las que Kino confía (kinoIdentity.tokenAuthors), el token
firmado que lo prueba; desde Kino 0.9.88 cualquier otro autor recibe el seudónimo y la atestación sin el token
(identity); kino.notifications.post({ id, title, titleEn?, text?, textEn?, go? }) y clear(id?) dejan y
quitan avisos en la campanita de Inicio (notifications). Detéctalas con
typeof kino.identity === "object" y typeof kino.notifications === "object". En una serie vista,
kino.library.watched() trae además season y episode (Salas, biblioteca y control del reproductor).
Un plugin que es una tienda no llama a kino: exporta storeSync (Tiendas de plugins).
kino.coins (apiVersion 16, Kino 0.9.78)¶
coins (apiVersion 16, una capacidad declarativa que nunca va sola y no se ofrece con enhancements) deja que tu plugin muestre
los kinos de la persona y los regale. Los kinos son una moneda gratuita compartida por todo Kino: la persona gana 1 kino cada 10
minutos vistos, como máximo 20 por día UTC, y los regala de uno en uno. await kino.coins.balance() responde
{ balance, earnedToday, capToday }; await kino.coins.give({ to, postId }) regala UN kino a la cuenta to (de 1 a 128
caracteres: el id del destinatario en el servicio de kinos, que te entrega tu propio servidor, por ejemplo el coinsAccount de
Kino Social) por la publicación postId (de 1 a 64 caracteres) y responde { balance, postTotal } (el saldo que queda y los
kinos que tiene ahora la publicación).
El cliente propio de Kino habla con el servicio de kinos, con la sesión de la validación de Telegram del aparato: tu plugin nunca
conoce la dirección del servicio ni su sesión, y no necesita hosts para él.
- Cuándo:
givesolo dentro de una llamada que la persona inició desdescreen,screenEventopanelAction(nunca un temporizador ni un trabajo);balancetambién desde un temporizador y desde tujobprogramado (un aviso diario del saldo conkino.notifications). 30 llamadas por minuto por plugin. - Errores: ambas rechazan con un KinoError cuyo
codeespermission_denied,not_available(el servicio está caído o lento, o este aparato nunca se validó con una cuenta de Telegram: mantén tu pantalla funcionando sin kinos),rate_limited,bad_request,disabled(la persona apagó los kinos en los Ajustes de Kino, mensaje "kino.coins is switched off in Kino's settings": no muestres nada de kinos, ni botón, ni saldo, ni aviso), o los propios del servicio:no_balance(nada que regalar),self_gift(a sí misma) yunknown_account. - Aprobación: una línea de consentimiento en rojo («Podrá ver tu saldo de kinos y regalar tus kinos»), que Kino nunca aprueba por su cuenta y que viene sin marcar en una importación del kit. No tiene interruptor propio: la persona la revoca al desactivar o quitar tu plugin.
- Detéctalo con
typeof kino.coins === "object": un Kino anterior no tienekino.coins, así que oculta allí tu botón de kinos (kinoCoinsen el contrato,contract.json). - Vender un tema no necesita nada de esto: un tema de la app con precio (apiVersion 18) se compra en la hoja propia de Kino, que muestra el precio y el saldo y le paga al autor; tu plugin nunca ve la compra.
kino.library.stats (apiVersion 17): los hábitos de un mes¶
const s = await kino.library.stats({ month: "2026-10" }); // por defecto: el mes actual
// { month, estimated, seconds, secondsByKind: { movie, series, live },
// secondsByBand: { morning, afternoon, night, lateNight } | null,
// titles, episodes, activeDays, longestStreakDays,
// top: [{ title, year?, kind, ids: { tmdb?, imdb? }, poster?, genres?, seconds }] /* como máximo 20 */ }
La misma capacidad (library) y el mismo interruptor que watched y saved (Salas, biblioteca y control del reproductor),
pero solo un plugin que declara "apiVersion": 17 o más tiene la función (detéctala con
typeof kino.library.stats === "function"). Como la línea de consentimiento en rojo ahora dice que el plugin puede leer cuánto
y a qué hora ve la persona, una actualización que sube a apiVersion 17 un plugin que ya tiene library le pregunta de nuevo a
la persona.
- Solo el perfil activo, con todos los aparatos de la persona sumados. Nada más fino que los agregados del mes: sin serie por
día y sin marcas de tiempo.
monthesyyyy-mm(un mes real); cualquier otro valor, o cualquier otra opción, esbad_request. - Nunca 18+: un título que Kino sabe que es 18+ cuando preguntas sale de los totales y de
top. Un título que Kino simplemente no puede ubicar ahora (su plugin ya no está) se queda en los totales y no está entop. Los canales en vivo cuentan en los totales y nunca se nombran. titlescuenta películas y series distintas;episodes, los capítulos distintos de series reproducidos en el mes (repetir uno no suma).posterygenresson solo lo que Kino ya tiene del ítem, sin llamadas de red; un campo que Kino no tiene se omite. Hoy Kino no guarda géneros de los ítems de su biblioteca, así quegenressuele faltar: llena el hueco conkino.tmdb.- Antes del contador: Kino cuenta los segundos realmente reproducidos desde la versión que lo trajo. Un mes anterior se
estima a partir del historial de reproducción (
estimated: true,secondsByBand: null); el mes de esa versión mezcla ambos, y susecondsByBandcubre solo la parte contada. - Las mismas reglas de llamada, el mismo límite (30 por minuto junto con
watchedysaved) y los mismos códigos de error que el resto dekino.library; responde también desde un trabajo. - Kit: el
statsdel fixture es{ "2026-10": { seconds, secondsByKind, secondsByBand, titles, episodes, activeDays, longestStreakDays, top } }.
kino.plugins.call(alias, llamada, arg?) (apiVersion 20, Kino 0.9.81)¶
Le pregunta a una puerta que abre otro plugin, a través de Kino: el protocolo entre plugins. alias es una
clave del consumes de tu manifiesto, llamada un nombre declarado ahí, arg JSON (máximo 64 KB)
que cumple el in de la llamada.
if (typeof kino.plugins === "object") { // no existe en un Kino anterior a 0.9.81
try {
const movie = await kino.plugins.call("tmdb", "random", { fromYear: 1990 }); // la respuesta del proveedor, revisada contra "out"
} catch (e) {
// e.code: provider_missing, not_declared, bad_input, bad_output, rate_limited, timeout o provider_failed
}
}
- Se resuelve con la respuesta del proveedor revisada contra el
outde la llamada (los campos que la puerta no declara se descartan). - Se rechaza con un
Errorcuyocodeesprovider_missing,not_declared,bad_input,bad_output,rate_limited(más de 30 llamadas en cualquier ventana de 10 s a una puerta de un proveedor),timeout(10 s) oprovider_failed; en unjoben segundo plano,not_allowed. Qué significa cada uno y qué hacer: Errores. - Se puede usar donde se usan los demás servicios de Kino (
screen,screenEvent, las exportaciones de un panel...); nunca en unjobni ensign(). argle llega al proveedor, que puede mandarlo a sus propios hosts: no pongas nada privado ahí.- Los flujos de un proveedor no se llaman con esta función: tu pantalla los enciende con
state.protocol.<alias>.<flujo> = truey recibe el eventoprotocol(Flujos). - Desde Kino 0.9.84 el proveedor sabe quién llama: sus exportaciones
proto_recibenctx.caller(ctx.caller). Para compartir en Kino Social con esta función, mira Compartir.
kino.visualBrowser.open(options) (apiVersion 20, Kino 0.9.81)¶
Con "visualBrowser": true en el manifest: abre una ventana web que la persona ve y maneja (para iniciar sesión, resolver una
verificación, aceptar términos) sobre tus hosts declarados, y se resuelve con { status: "done" | "closed" | "timeout", finalUrl?,
cookies?, html?, stored?, storedNames?, userAgent? }. Kino le pregunta a la persona en su propia hoja en cada apertura. Solo desde una
action de ajustes, una panelAction o un screenEvent que la persona tocó (forbidden desde cualquier otra cosa); errores
bad_args, forbidden, unavailable, busy y store_failed. kino.visualBrowser es undefined sin la clave del manifest o en un
Kino anterior a 0.9.81, y kino.visualBrowser.available es false en el escritorio y en un aparato sin WebView (Android TV tiene uno:
experimental allí). Las reglas, los topes de cookies, storeAs y la receta "Vincular cuenta" están en
Una ventana de navegador que la persona maneja.
kino.sleep(ms) y kino.error(code, message?, { userMessage }?)¶
await kino.sleep(1500) espera de 0 a 5000 ms (para un sitio que te limita las peticiones); el tiempo
cuenta dentro del límite de la llamada. kino.error arma los errores con tipo de
Errores que la gente entiende; su { userMessage } opcional (apiVersion 6) es tu
propia frase para la persona, que se muestra bajo sus reglas como
"Mensaje de <tu plugin>: …".
Errores que tu código puede atrapar¶
Toda falla que reporta una llamada kino.* es un Error normal que recibe tu try/catch (tus
propios throw siguen teniendo la trampa del rechazo). Compara
e.code, nunca el texto de e.message: ese texto es para el log y puede cambiar (en español hasta Kino 0.9.53, en
inglés desde Kino 0.9.54).
| Dónde | e.code |
|---|---|
kino.fetch |
host_not_allowed, timeout, network, too_large, invalid_request, y rate_limited con fetchHosts (la tabla) |
kino.crypto |
crypto_error |
kino.browser.capture |
browser_unavailable, timeout, blocked, busy, not_allowed, invalid_request |
kino.browser.page |
los mismos, más rate_limited (Navegador oculto) |
kino.plugins.call |
provider_missing, not_declared, bad_input, bad_output, rate_limited, timeout, provider_failed; not_allowed en un job (el protocolo entre plugins) |
dentro de sign() |
host_not_allowed desde kino.fetch; not_allowed desde kino.storage, kino.cookies y kino.sleep |
kino.storage por encima de 256 KB o con un ttlMs inválido, kino.html.select por encima de sus límites, kino.secret con un nombre no declarado |
sin code: un Error simple con un mensaje (en español hasta Kino 0.9.53, en inglés desde Kino 0.9.54) |
Desde Kino 0.9.50 una llamada kino.* síncrona que falla (un kino.storage lleno, una clave de
cifrado mala, un selector demasiado largo) la atrapa tu try/catch como cualquier otro error. Kino
0.9.49 y anteriores terminaban ahí la llamada entera aunque estuviera dentro de un try/catch, así
que en esas versiones vigila lo que guardas.
kino.error(code, message?, { userMessage }?) arma un Error cuyo name es KinoError_<code>
(KinoError_not_found), con code y, si pasaste una, userMessage. Un código que no es uno de los
cinco queda como code: "unknown", y la persona lee un error simple. Lánzalo tal cual, o vuelve a lanzar
uno que atrapaste: el código le llega a la persona solo si el error sale de tu función con él. Lo que
lances (un Error, un texto, lo que sea) le llega a Kino como texto, cortado a 2.000 caracteres.
try {
kino.storage.set("cache:" + key, JSON.stringify(rows), { ttlMs: 3600000 });
} catch (e) {
kino.log("cache: not saved", e.message); // almacenamiento lleno: sigue sin el caché
}
try {
return await api("/play/" + encodeURIComponent(ref));
} catch (e) {
if (e.code === "timeout" || e.code === "network") return backupStream(ref);
throw e; // un kino.error conserva su código y su userMessage
}
kino.config¶
kino.config.get("server") // text, url, password, select: un texto; toggle: true/false
kino.config.get("sources") // list (apiVersion 4): [{ url: "https://…", category: "Noticias" }, …]
kino.config.all() // todos los ajustes que tienen valor, como un objeto
get devuelve el valor de un ajuste: un texto en text, url, password y select; true/false
en un toggle; y en una list (apiVersion 4) un arreglo de objetos, uno por entrada, con las claves
de sus fields ([{ url: "https://…", category: "Noticias" }, …]), recortados y sin entradas en
blanco. all devuelve todos los ajustes que tienen valor, como un objeto. Solo lectura: los valores que
guardó la persona, o el default de un ajuste que no tocó. Un toggle sin default vale false y un
select sin default vale su primera opción, así que los dos siempre tienen valor. Un text o un
password sin valor y sin default, un url vacío (nunca tiene default) y una list vacía son
undefined. Los tipos section, status y action no guardan valor y nunca salen aquí. Todos los
tipos están en Formulario de ajustes.
kino.html.select(html, css)¶
Analiza html y devuelve [{ text, html, attrs }] por cada elemento que cumple el selector CSS
(la sintaxis de selectores de Jsoup): text es su texto, html su HTML interno, attrs un objeto
con sus atributos. Solo se leen los primeros 2.000.000 caracteres de html, vuelven máximo 500
elementos, y lanza un error si el texto y el HTML de las coincidencias juntos pasan de 5.242.880
caracteres (5 MB). Un selector de más de 10.000 caracteres lanza
Error("CSS selector too long (over 10000 characters)") (Kino 0.9.53 y anteriores:
"selector CSS demasiado largo (más de 10000 caracteres)"). Solo existe dentro de Kino: la
versión del kit de Node lanza un error, así que prueba en la app todo lo que lo use.
kino.storage¶
kino.storage.get("key") // the string, or null
kino.storage.set("key", "v") // values are converted to strings
kino.storage.set("key", "v", { ttlMs: 3600000 }) // expires after that many milliseconds
kino.storage.remove("key")
kino.storage.keys() // every key, as an array (expired keys are already gone)
get devuelve el texto o null; set convierte los valores a texto; keys() devuelve todas las
claves como arreglo (las vencidas ya no están). Es síncrono, privado de tu plugin, y sobrevive a los
reinicios del sandbox y de la app. Máximo 256 KB en total (medido como el JSON de todas las claves y
valores); pasarse lanza Error("plugin storage full (256 KB)") (Kino 0.9.53 y anteriores:
"almacenamiento del plugin lleno (256 KB)"). Se borra cuando la
persona desinstala el plugin, y no se borra cuando cambia tus ajustes.
Un almacén más grande (storageLarge, apiVersion 13, Kino 0.9.74). Un plugin que declara storageLarge tiene la
misma API con 16 MB en total, máximo 2 MB por valor y máximo 1.000 llaves de máximo 256 caracteres, guardado en un
archivo por valor solo en el aparato: nunca se sincroniza y no va en ninguna copia de seguridad (declararlo también
mueve ahí tus llaves existentes). Guarda las credenciales en secretos sellados o en los ajustes, y parte los datos grandes
en valores de unos 512 KB. Para buscar entre miles de registros usa kino.catalog. Las reglas.
El tercer argumento de set es opcional: déjalo por fuera para una entrada permanente, exactamente
como antes de que existiera esta opción. Pasa { ttlMs } para que la entrada venza -- después de esa
cantidad de milisegundos get devuelve null y keys() ya no la lista, incluso después de reiniciar
la app. ttlMs tiene que ser un número entero mayor que 0 y de máximo 2.592.000.000 (30 días);
cualquier otra cosa lanza un error antes de tocar tu entrada, igual que ya pasa con un valor demasiado
grande. Una entrada vencida nunca cuenta para el tope de 256 KB (16 MB con storageLarge): se descarta la próxima vez que tu
plugin lee o escribe en el almacenamiento. Ejemplo, una fila de Inicio guardada por una hora:
export async function home() {
const cached = kino.storage.get("home-rows");
if (cached) return JSON.parse(cached);
const rows = await buildHomeRows();
kino.storage.set("home-rows", JSON.stringify(rows), { ttlMs: 60 * 60 * 1000 });
return rows;
}
kino.log(...args)¶
También console.log, console.info, console.warn y console.error: todos van al log (etiqueta
KinoPlugin en adb logcat; KinoPlugin/<tu id> en una compilación de depuración de Kino, o en
cualquier compilación mientras el Modo debug de tu plugin está encendido: "debug": true solo lo deja así de entrada), los objetos se escriben como JSON, y un mensaje se corta a los 2000
caracteres. En el kit de Node van a stderr.
Cuando una llamada de un plugin cuyo manifiesto dice "telemetry": true o "verbose" (apiVersion 6)
falla (lanza un error, se pasa del tiempo, devuelve algo inservible, incluidos sign,
settingsStatus, action y validateSettings), las líneas que registró durante esa llamada (las
últimas 30, cada una cortada a 300 caracteres) viajan con el reporte de la falla al registro de
errores de quienes mantienen Kino como plugin_log; así que un kino.log("home: status", r.status)
antes del throw es como ves por qué falló en el celular de otra persona. Cada reporte va marcado con
el id y la versión de tu plugin; máximo un reporte por función y tipo de falla por hora. No se envía
nada de una llamada que sale bien, ni ninguna línea de un plugin que no declara telemetry (recomendado o
no, un scraper de Nuvio convertido): de esos Kino solo anota que la llamada falló (tu id y versión, la
función, el tipo de falla). Hasta Kino 0.9.53 las líneas de un plugin que lo declara se envían
siempre; desde Kino 0.9.54 la persona puede apagar "Enviar registros de errores y de reproducción" en la pestaña de tu
plugin en Ajustes (mira Registro y telemetría), y entonces no se envía nada mientras esté
apagado. Antes de salir del aparato, a cada línea se le
quitan URL, nombres de host, IP, correos, ids largos, tiras largas de hex/base64, texto con forma de
credencial, los valores de los ajustes de la persona y el texto de su búsqueda o del título, y el
total se limita a 2 KB (ganan las líneas más nuevas). Aun así: registra lo que pasó (un estado, un
paso, un conteo), nunca lo que la persona escribió ni un secreto, y nunca el valor de un ajuste.
Funciona en cualquier apiVersion.
kino.log.report(...args) (apiVersion 6, con telemetry) escribe una línea como kino.log y
además le avisa al registro de errores que tu plugin entregó un resultado degradado, aunque la
llamada funcionó: usó una cuenta compartida de respaldo, una fuente de reserva, recortó una lista. Los
detalles (el área, los topes) están en Registro y telemetría.
kino.rank¶
Para un backend de búsqueda que solo compara una bolsa suelta de palabras en común, no un título completo: si le preguntas por un título largo puede devolver veinte resultados sin relación que solo comparten una palabra común, con la coincidencia real enterrada en la página dos. Estas tres funciones puras hacen que un backend así se comporte como una búsqueda por título, sin tocar su propia forma de JSON.
kino.rank.shortQuery(query)
kino.rank.sortBySimilarity(items, query, getTitle?)
kino.rank.filterRelevant(items, query, getTitle?)
shortQuery(query)devuelve la CABEZA del título, hasta su primer:,,,|, raya corta (en dash) o raya larga (em dash): pregúntale eso a tu backend en vez del título completo, para que su propio orden tenga menos ruido. Una cabeza de una o dos letras ("El", "A") no identifica nada, así que en ese caso vuelve el texto completo (sin espacios en los extremos); un-simple nunca es punto de corte (partiría "Spider-Man"). Pruébalo primero con tu backend -- algunos funcionan peor con una consulta corta, no mejor.sortBySimilarity(items, query, getTitle?)reordenaitemspara que primero queden los que comparten más palabras conquery; en los empates se conserva el orden del backend.filterRelevant(items, query, getTitle?)descarta los ítems que solo comparten una palabra suelta conquery. Reordenar solo igual muestra una página llena de casi-aciertos cuando el título de verdad no está en el backend; esto hace que un título ausente vuelva con 0 resultados.
query es un título, o un arreglo con varias formas de uno que vale la pena probar juntas --
[query.q, query.originalTitle, ...query.altTitles], porque un backend puede conocer un título solo en
un idioma. getTitle lee un título de uno de tus items; por defecto es (item) => item.title, y
también puede devolver un arreglo, igual que query, cuando un ítem guarda el título en más de un
campo o idioma (se combinan las palabras de todas las formas). La comparación ignora tildes y
mayúsculas y las palabras de 1-2 letras (los "el", "de", "of" que hacen parecer iguales títulos que no
tienen nada que ver); filterRelevant conserva un ítem cuando comparte al menos el 60% de las
palabras distintivas de un título pedido.
Una entrada mala nunca lanza error. A diferencia de kino.fetch/kino.crypto/kino.sleep, estas
tres nunca lanzan un kino.error por un argumento mal formado: items que no es un arreglo responde
[] en cualquiera de las dos funciones. Un ítem sin título utilizable -- null, undefined,
getTitle que devuelve algo que no es un texto (o un arreglo sin ninguno), o getTitle que lanza un
error -- se trata como "sin título" en vez de tumbar tu llamada: filterRelevant lo descarta como un
casi-acierto más, y sortBySimilarity lo pone después de todos los que sí tienen título, en el orden
de tu propia lista entre ellos.
export async function search(query) {
const titles = [query.q, query.originalTitle, ...query.altTitles];
const r = await kino.fetch(BASE + "/search?q=" + encodeURIComponent(kino.rank.shortQuery(query.q)));
const found = r.json().results; // whatever shape your backend answers with
const relevant = kino.rank.filterRelevant(found, titles, (x) => x.name);
return kino.rank.sortBySimilarity(relevant, titles, (x) => x.name).map(toItem);
}
Si tu backend ya ordena bien un título completo, sáltate shortQuery y usa solo
filterRelevant/sortBySimilarity sobre lo que te da para query.q tal como se escribió.
Dos cosas quedaron por fuera a propósito. Ninguna reintenta con el título completo: si la cabeza de
shortQuery resulta ser una palabra común (p. ej. "Love, Death & Robots" -> "Love") y el backend no
devuelve nada relevante, reintenta tú search con el título completo cuando la corta vuelva vacía. Y
ninguna hace nada con números ni orden de temporadas: cómo escribe un backend "temporada 2" en sus
títulos ("T2", "Temporada 2", …) es propio de ese backend, no algo que estas funciones puedan
absorber.