Protocolo entre plugins: plugins que se usan entre sí¶
Disponible desde Kino 0.9.81
El protocolo entre plugins es el apiVersion 20 y llega con Kino 0.9.81. Todo Kino anterior rechaza un manifiesto con
"apiVersion": 20 («Este plugin necesita una versión más nueva de Kino»), pero un plugin que se queda en un apiVersion
más bajo igual puede abrir sus puertas con enhancements["20"], que un Kino anterior ignora. Cada número de
esta página está en contract.json, sección protocol (Referencia).
Un plugin de Kino puede apoyarse en otro plugin. Un plugin, el proveedor, abre puertas con nombre en su
manifiesto: unas cuantas llamadas (pregunta y respuesta) y flujos (novedades que publica cada tanto), cada una con la forma
de lo que recibe y de lo que devuelve. Otro plugin, el consumidor, declara las puertas que usa y les pregunta con
await kino.plugins.call(alias, llamada, arg). Kino es el único intermediario: los dos plugins nunca se ven, nunca
comparten memoria y nunca se llaman directamente. Kino encuentra al proveedor, revisa cada petición y cada respuesta contra
los tipos que declaró el proveedor, limita el ritmo y devuelve un código de error claro cuando falta algo.
Para qué existe: para que el trabajo hecho una vez lo reúsen todos. Un plugin que sabe hablar con un servicio (TMDB, un catálogo de música, un feed de deportes) puede ofrecer ese conocimiento como una puerta, y otros plugins (un juego, un widget, una pantalla de recomendaciones) lo usan sin copiar su código, sus hosts ni sus llaves.
La primera pareja real, el ejemplo de toda esta página:
| Plugin | Papel | Repositorio |
|---|---|---|
| TMDB | Proveedor: abre la puerta movies (buscar una película por id, una al azar, buscar por texto y un flujo trending) |
kinotvapp/kino-plugin-tmdb (TMDB 1.3.0 y posteriores) |
| Cine Trivia | Consumidor: una trivia de cine de cinco preguntas que saca cada película de la puerta de TMDB | kinotvapp/kino-plugin-cine-trivia |
TMDB 1.3.0 y posteriores, Kino 0.9.81 o más nuevo
La puerta movies llega en TMDB 1.3.0 y posteriores. Va dentro de enhancements["20"], así que TMDB conserva su
apiVersion y se sigue instalando en los Kino anteriores, pero solo Kino 0.9.81 o más nuevo abre la puerta: en un
Kino anterior, TMDB es el mismo plugin de catálogo de siempre y Cine Trivia (que declara apiVersion 20) no se instala.
En un minuto¶
- Proveedor: declara
providesenkino-plugin.jsony exporta una función por llamada,proto_<puerta>_<llamada>(arg), y una por flujo,proto_<puerta>_<flujo>(cursor). - Consumidor: declara
consumes(un alias, elrepodel proveedor, ladoor, las llamadas y los flujos que usa) y además pone al proveedor enrecommends, para poder ofrecer instalarlo. - La llamada:
const movie = await kino.plugins.call("tmdb", "random", { fromYear: 1990 }). Se resuelve con la respuesta del proveedor, ya revisada contra el tipo declarado, o se rechaza con unErrorcuyocodees uno de siete. - Un flujo: la pantalla del consumidor pone
state.protocol.<alias>.<flujo> = true; Kino consulta al proveedor y entrega lo nuevo ascreenEventcomo el eventoprotocol. - Nada se instala solo. Mientras falta el proveedor, el consumidor dibuja solo una pantalla de instalación con un botón
go.installPlugin. Kino abre su hoja de instalación de siempre; la persona decide. - Kino lo revisa todo: las peticiones con rigor, las respuestas con holgura (los campos no declarados se descartan), 64 KB en cada sentido, 10 s por llamada, 30 llamadas en cualquier ventana de 10 s por puerta. El contenido 18+ nunca pasa a un plugin que no es 18+, y los secretos sellados no pasan nunca.
- Compartir en Kino Social es un consumidor de este protocolo: la puerta
wallde Kino Social y su llamadashare. Mira Compartir.
El modelo mental¶
Kino está en medio de cada intercambio. Ningún plugin sabe dónde vive el otro; solo conocen el nombre de una puerta y los tipos escritos en el manifiesto del proveedor.
sequenceDiagram
autonumber
participant C as Cine Trivia (consumidor)
participant K as Kino
participant T as TMDB (proveedor)
C->>K: kino.plugins.call("tmdb", "random", { fromYear: 1990 })
Note over K: ¿alias en consumes? ¿llamada declarada?<br/>¿proveedor instalado y activo? ¿regla 18+?<br/>¿menos de 30 llamadas / 10 s a esta puerta?
Note over K: argumento revisado contra "in" (estricto)
K->>T: proto_movies_random({ fromYear: 1990 })
T-->>K: { id, title, year, director, internalScore }
Note over K: respuesta revisada contra "out" (holgada):<br/>se descarta internalScore, ningún secreto sellado
K-->>C: { id, title, year, director }
| Quién | Hace | Nunca hace |
|---|---|---|
| El proveedor | Declara sus puertas y sus tipos; responde cada llamada con JSON; decide en código qué comparte | Saber qué plugin preguntó antes de Kino 0.9.84 (desde ahí lo dice ctx.caller); llegar al consumidor; mandar algo que no declaró (Kino lo descarta) |
| El consumidor | Declara lo que usa; llama con un argumento que cumple in; maneja los códigos de error; invita a la persona a instalar al proveedor |
Llamar a una puerta que no declaró; instalar algo; leer el almacenamiento, los ajustes o los secretos del proveedor |
| Kino | Encuentra al proveedor por repositorio, valida en los dos sentidos, limita el ritmo y el tiempo, corre los flujos mientras hay una pantalla abierta, muestra la línea de consentimiento | Guardar algo del intercambio (no hay nada nuevo que sincronizar); preguntarle a la persona en cada llamada |
| La persona | Ve «Usa datos de TMDB (Movie records from TMDB)» en la hoja de instalación del consumidor; instala al proveedor con su propio toque | Recibir un plugin instalado sin tocar Instalar |
Una puerta no es una capacidad. Un proveedor conserva las capacidades del tipo de plugin que es (TMDB sigue siendo un
catálogo con search, home, meta...) y un consumidor conserva las suyas (Cine Trivia es un plugin con screen).
provides y consumes son dos bloques más del manifiesto, al lado de esas capacidades.
Un ejemplo completo: TMDB y Cine Trivia¶
El proveedor: TMDB abre la puerta movies¶
TMDB es un plugin de catálogo que ya existe, con apiVersion 7. Para abrir su puerta sin subir su apiVersion (y
seguir instalándose en todos los Kino que ya soporta) pone provides dentro de enhancements["20"]. Esta es la parte de
kino-plugin.json que agrega TMDB 1.3.0 (el resto del manifiesto, sus capacidades y ajustes, no cambia):
{
"id": "tmdb",
"name": "TMDB",
"version": "1.3.0",
"apiVersion": 7,
"entry": "plugin.js",
"hosts": ["image.tmdb.org"],
"capabilities": ["search", "home", "browse", "episodes", "resolve", "meta"],
"enhancements": {
"20": {
"provides": {
"movies": {
"summary": "Movie records from TMDB",
"calls": {
"byId": { "in": { "id": "number" }, "out": "Movie" },
"random": { "in": { "fromYear": "number?", "toYear": "number?" }, "out": "Movie" },
"search": { "in": { "q": "string" }, "out": "Movie[]" }
},
"streams": {
"trending": { "out": "Movie", "everySeconds": 60 }
},
"types": {
"Movie": { "id": "number", "title": "string", "year": "number", "director": "string?", "overview": "string?", "posterUrl": "string?" }
}
}
}
}
}
}
Léelo como la documentación de la puerta: byId recibe { id } y responde una Movie; random recibe un rango de años
opcional y responde una Movie; search recibe { q } y responde una lista de Movie; trending es un flujo de Movie
que se consulta como mucho una vez por minuto. Una Movie siempre trae id, title y year, y puede traer director,
overview y posterUrl.
Cada llamada y cada flujo es una exportación del archivo de entrada que se llama proto_<puerta>_<nombre>. TMDB responde a
través del servicio propio de Kino, kino.tmdb, así que para esto no necesita ni host ni llave propia:
// La puerta "movies". Kino revisa cada argumento contra "in" antes de llamar, y cada respuesta contra "out" después.
export async function proto_movies_byId(arg) {
return movieById(arg && arg.id); // una petición a kino.tmdb (con los créditos, para el director)
}
export async function proto_movies_random(arg) {
const { fromYear, toYear } = arg || {}; // los dos opcionales: Kino pasa {} cuando el consumidor no manda nada
const params = { include_adult: false, sort_by: "popularity.desc", "vote_count.gte": 100 };
if (Number.isInteger(fromYear)) params["primary_release_date.gte"] = `${fromYear}-01-01`;
if (Number.isInteger(toYear)) params["primary_release_date.lte"] = `${toYear}-12-31`;
const pool = await discoverPool({ ...params, page: 1 + Math.floor(Math.random() * 10) });
if (!pool.length) throw new Error("not_found"); // un throw le llega al consumidor como provider_failed
return movieById(pool[Math.floor(Math.random() * pool.length)].id);
}
export async function proto_movies_search(arg) {
const q = String(arg.q).trim().slice(0, 200);
return q ? moviesOf(await kino.tmdb("/search/movie", { query: q, include_adult: false })) : [];
}
// Un flujo: el argumento es el cursor que devolvió esta función la vez anterior (null la primera vez).
export async function proto_movies_trending(cursor) {
const seen = Array.isArray(cursor) ? cursor : [];
const fresh = moviesOf(await kino.tmdb("/trending/movie/week", {})).filter((m) => !seen.includes(m.id));
return { items: fresh, cursor: seen.concat(fresh.map((m) => m.id)).slice(-200) };
}
movieById, discoverPool y moviesOf son ayudantes propios de TMDB: convierten las filas de TMDB en la Movie declarada
({ id, title, year, director?, overview?, posterUrl? }) y dejan fuera las filas para adultos. El código completo está en
el repositorio de TMDB.
El consumidor: Cine Trivia¶
Cine Trivia no sirve sin TMDB, así que declara apiVersion 20 directamente. Su manifiesto:
{
"id": "cine-trivia",
"name": "Cine Trivia",
"version": "1.0.1",
"apiVersion": 20,
"entry": "plugin.js",
"description": "Cinco preguntas de cine, quince segundos cada una: las películas llegan del plugin TMDB",
"hosts": [],
"capabilities": ["screen"],
"screen": { "label": "Cine Trivia", "labelEn": "Cine Trivia", "icon": "movie", "menuOpens": "screen" },
"recommends": ["kinotvapp/kino-plugin-tmdb"],
"consumes": {
"tmdb": {
"repo": "kinotvapp/kino-plugin-tmdb",
"door": "movies",
"calls": ["random", "byId"],
"streams": ["trending"]
}
}
}
consumes.tmdb:tmdbes un alias local, el primer argumento dekino.plugins.call.repoes el repositorio de GitHub del proveedor,doorel nombre de la puerta,callsystreamsexactamente los nombres que usa Cine Trivia (nunca llama asearch, así que no lo declara).recommendsnombra el mismo repositorio, asíscreenyscreenEventrecibeninstalled["kinotvapp/kino-plugin-tmdb"](mira la puerta de instalación).hostses[]: Cine Trivia es un consumidor solo de pantalla. Los datos de las películas no llegan por la red (llegan por Kino, desde el proveedor), y los pósters que dibuja (elposterUrlde TMDB) son imágenes públicas, que no necesitan declarar su host.
La puerta de instalación¶
Kino nunca instala nada por su cuenta. Hasta que TMDB esté instalado, Cine Trivia muestra solo una pantalla de
instalación con un botón. El go del botón es installPlugin: Kino abre su hoja de
instalación de siempre encima de la pantalla, y la persona toca Instalar (o Cancelar).
const TMDB_REPO = "kinotvapp/kino-plugin-tmdb";
const gateOpen = (installed) => !!installed && installed[TMDB_REPO] === true;
export async function screen({ state = {}, installed } = {}) {
if (!gateOpen(installed)) return installView(); // no se dibuja ni se puede tocar nada más
return gameView(state);
}
function installView() {
return {
type: "Column", padding: 24, gap: 16, crossAxisAlignment: "center", children: [
{ type: "Text", text: "Cine Trivia", textEn: "Cine Trivia", style: "h1", textAlign: "center" },
{ type: "Text", text: "Para jugar necesitas el plugin TMDB: de ahí salen las películas de cada pregunta.",
textEn: "To play you need the TMDB plugin: every question's movies come from it.", textAlign: "center" },
{ type: "ElevatedButton", key: "install", labelText: "Instalar TMDB", labelTextEn: "Install TMDB", autofocus: true,
onPressed: { go: { installPlugin: { repo: TMDB_REPO } } } },
],
};
}
export async function screenEvent({ name, installed } = {}) {
if (!gateOpen(installed)) return null; // ningún evento hace nada hasta que TMDB esté
// ... el juego
}
flowchart TD
A[La persona abre Cine Trivia] --> B{"¿installed[TMDB]?"}
B -- false --> C[Pantalla de instalación:<br/>un botón]
C -- "go.installPlugin" --> D[Hoja de instalación<br/>de Kino para TMDB]
D -- Instalar --> E[installed pasa a true;<br/>Kino vuelve a llamar a screen]
D -- Cancelar --> C
B -- true --> F[El juego]
E --> F
Cuando la persona instala TMDB, installed cambia y Kino vuelve a llamar a screen con la pantalla abierta: el juego
aparece en su lugar, sin volver a abrir el plugin. Desde ahí carga directo. Si más adelante la persona quita TMDB, a Cine
Trivia no le pasa nada: la puerta vuelve a mostrar la pantalla de instalación, y una llamada que estuviera en curso responde
provider_missing.
Qué dice installed, exactamente. installed["<dueño/nombre>"] es true mientras haya en el aparato un plugin instalado
desde ese repositorio, aunque la persona lo haya apagado o le falte configurarse; es false solo cuando no hay ningún plugin
de ese repositorio instalado (nunca se instaló, o se quitó). Por eso la puerta sola no basta: con installed en true una
llamada todavía puede responder provider_missing (el proveedor está apagado, le falta configurarse, o es 18+ y tu plugin no).
Guarda ese código en tu estado y dibuja una frase para él, como «TMDB está apagado o le falta configurarse: revísalo en
Plugins», con un botón para reintentar, no el de instalar (un go.installPlugin de un plugin que ya está instalado solo
muestra el aviso de Kino «Ese plugin ya está instalado»). recommends no hace nada más: Kino no le muestra a la persona una
lista ni una marca por él, solo llena installed (un Kino anterior ignora el campo).
Preguntarle a una puerta¶
Cada ronda le pide a TMDB una película al azar de una época al azar. Kino guarda el estado de la pantalla, así que el
manejador llama, responde con el state nuevo y no mantiene nada vivo entre eventos:
async function round(game) {
try {
const movie = await kino.plugins.call("tmdb", "random", eraArg(Math.random)); // p. ej. { fromYear: 1990, toYear: 1999 }
const q = buildQuestion(movie); // movie es una Movie ya revisada
return { state: { game: { ...game, phase: "question", q, error: null } }, focus: "opt0" };
} catch (e) {
const code = e && typeof e.code === "string" ? e.code : "provider_failed";
return { state: { game: { ...game, phase: "error", error: code } }, focus: "retry" }; // la vista ofrece "Reintentar"
}
}
La respuesta es exactamente la Movie declarada: si TMDB hubiera agregado un campo que la puerta no declara, Kino lo habría
descartado antes de que Cine Trivia lo viera. Si TMDB hubiera respondido sin title, la llamada se habría rechazado con
bad_output.
Novedades en vivo con un flujo¶
Cine Trivia tiene un interruptor «Tendencias en vivo». Al encenderlo pone una marca en el estado; desde ahí Kino consulta el
flujo trending de TMDB mientras la pantalla está abierta y entrega las películas nuevas como el evento protocol:
export async function screenEvent({ name, arg, value, state = {}, installed } = {}) {
if (!gateOpen(installed)) return null;
switch (name) {
case "trending": // el onChanged del Switch
return { state: { protocol: { tmdb: { trending: value === true } }, trendingTitle: null } };
case "protocol": { // arg: { alias: "tmdb", stream: "trending", items: [Movie, ...] }
if (arg.alias !== "tmdb" || arg.stream !== "trending") return null;
const movie = arg.items.find((m) => typeof m.title === "string" && m.title.trim());
return movie ? { state: { trendingTitle: movie.title.slice(0, 120) } } : null;
}
// ...
}
}
Qué pasa en una llamada, paso a paso¶
- El
screenEventde Cine Trivia ejecutakino.plugins.call("tmdb", "random", { fromYear: 1990 }). - Kino busca el alias
tmdben elconsumesde Cine Trivia y revisa querandomesté ahí (si no,not_declared). - Kino busca el plugin instalado cuyo repositorio es
kinotvapp/kino-plugin-tmdb(un fork no cuenta). Si no hay ninguno, o está apagado, o le falta configurarse, o es 18+ y Cine Trivia no, la llamada esprovider_missing. - Kino revisa que la puerta
moviesde TMDB siga declarandorandom(si no,not_declared) y que Cine Trivia haya hecho menos de 30 llamadas a esa puerta en los últimos 10 s (si no,rate_limited). - Kino revisa el argumento contra el
inderandom, con rigor (si no cumple,bad_input). - Kino llama a la exportación
proto_movies_randomde TMDB como llamada en segundo plano, como mucho 10 s (si no,timeout; un throw o una exportación que falta esprovider_failed). - Kino revisa la respuesta contra el
outderandom, con holgura: descarta los campos no declarados y rechaza un campo obligatorio que falta o tiene otro tipo, cualquier cosa de más de 64 KB y cualquier respuesta que lleve uno de los secretos sellados de TMDB (todo eso esbad_output). - La promesa de Cine Trivia se resuelve con la
Movierevisada.
El proveedor en detalle¶
El bloque provides¶
provides asocia el nombre de una puerta con su declaración. Un plugin abre como mucho 4 puertas.
| Campo de una puerta | Qué es | Reglas |
|---|---|---|
summary |
Una frase para la persona: aparece en la línea de consentimiento del consumidor, después del nombre de tu plugin | Opcional, máximo 120 caracteres. Un solo texto para los dos idiomas (no hay summaryEn): que sea corto y claro |
calls |
{ "<llamada>": { "in"?, "out" } }, pregunta y respuesta |
Máximo 16. out es obligatorio; in puede faltar en una llamada sin argumento |
streams |
{ "<flujo>": { "out", "everySeconds"? } }, suscripciones |
Máximo 8. out es el tipo de un ítem; everySeconds se ajusta entre 30 y 86.400 (60 si falta) |
types |
{ "<Tipo>": { "<campo>": "<tipo>" } }, tipos de objeto con nombre |
Los nombres empiezan con mayúscula (^[A-Z][A-Za-z0-9]{0,31}$) y son locales a la puerta |
Los nombres de puerta, llamada, flujo (y, del lado del consumidor, alias) son letras y dígitos que empiezan con letra, máximo
32 (^[A-Za-z][A-Za-z0-9]{0,31}$). Una llamada y un flujo de la misma puerta no pueden compartir nombre. Un bloque mal formado
rechaza todo el manifiesto con un mensaje que nombra la puerta y el campo (por ejemplo door "movies": call "random" needs an
"out"); dentro de enhancements["20"] solo se descarta ese bloque.
Las exportaciones¶
| Declarado | Exportación | Recibe | Devuelve |
|---|---|---|---|
una llamada random de la puerta movies |
proto_movies_random |
el argumento del consumidor, ya revisado contra in ({} cuando el consumidor no mandó nada y todos los campos de in son opcionales) |
JSON que cumple out (un valor o una promesa de uno) |
un flujo trending de la puerta movies |
proto_movies_trending |
el cursor que devolviste la vez anterior, null la primera vez |
{ items: [...], cursor }: items son lo nuevo desde ese cursor, cada uno un out; cursor es un JSON pequeño que quieras recibir la próxima vez: viaja dentro de esta respuesta, como mucho 64 KB junto con los ítems |
- Quién llama (
ctx, Kino 0.9.84). Cada exportaciónproto_recibe además un segundo argumento,ctx, que llena Kino y que el consumidor no puede mandar ni cambiar:ctx.calleres{ id, repo, name, adult }del plugin que llama. Úsalo para responder distinto según quién pregunta; un proveedor que solo declara(arg)sigue funcionando, y un Kino anterior no mandactx. Quita el@refderepoantes de usarlo en ungo.plugin.ctx.caller. - Para fallar, lanza un error. Un error lanzado le llega al consumidor como
provider_failed(el mensaje no viaja, así que no pongas nada privado ahí). Una exportación que falta también esprovider_failed. - Tú decides qué compartes. La exportación es código normal: responde lo que quieras dar y nada más. Kino pone una red de seguridad (descarta los campos no declarados y rechaza los secretos sellados), pero el primer filtro es tuyo.
- Corre como llamada en segundo plano. Un proveedor que tarda más de 10 s hace fallar esa llamada con
timeout, pero Kino no lo marca «No responde» por eso, y una falla del proveedor nunca toca el resto del trabajo del consumidor ni a otros plugins. - Tus propios límites siguen valiendo. El
kino.fetchdel proveedor sigue limitado a sushosts, y los servicios de Kino mantienen sus límites (kino.tmdb: 20 llamadas cada 10 s por plugin con la llave de Kino). Diseña llamadas que cuesten una o dos peticiones (elbyIdde TMDB pide los créditos en la misma petición;randomcuesta dos). - Tu manifiesto es la documentación. Quien escribe un consumidor lee tu
providespara saber qué mandar y qué vuelve. Describe la puerta también en tu README: qué hace cada llamada, sus errores, cada cuánto cambia un flujo.
Cambiar una puerta después¶
Kino vuelve a leer la puerta del proveedor en cada llamada, nunca al instalar el consumidor, así que un cambio vale de inmediato:
| Cambio en una actualización del proveedor | Lo que ven los consumidores |
|---|---|
| Una llamada, un flujo o una puerta nuevos | Nada, hasta que un consumidor lo declare en su propio consumes |
Un campo opcional nuevo en un tipo ("rating": "number?") |
Los consumidores viejos siguen funcionando; Kino deja pasar el campo una vez declarado |
Un campo obligatorio nuevo en un in |
Los consumidores viejos que no lo mandan reciben bad_input: evítalo, agrega uno opcional |
| Una llamada o un flujo quitado o renombrado | Todo consumidor que lo usa recibe not_declared |
Un campo quitado de un tipo de out, o con otro tipo |
Los consumidores que lo leen se rompen en silencio o reciben bad_output |
Así que trata una puerta publicada como una API pública: solo agrega, y solo campos opcionales. Cuando tengas que romperla,
abre una puerta nueva (movies2) al lado de la vieja y mantén las dos un tiempo. Una actualización del proveedor que
amplía una puerta no vuelve a mostrar la línea de consentimiento a quien ya tiene el consumidor.
El lenguaje de tipos¶
Un lenguaje pequeño y cerrado, el mismo para in, out y types:
| Tipo | Significa | Ejemplo |
|---|---|---|
string, number, boolean |
el primitivo de JSON (number es un número finito) |
"id": "number" |
T? |
opcional: ausente o null |
"director": "string?" |
T[] |
una lista de T |
"out": "Movie[]" |
Nombre |
un tipo declarado en los types de la puerta |
"out": "Movie" |
{ ... } |
un objeto en línea de campo a tipo | "in": { "q": "string" } |
Los sufijos se combinan ("string[]?": una lista de textos opcional; "Movie?[]": una lista cuyos ítems pueden ser null).
No hay any, ni uniones, ni enumeraciones, ni mapas: si necesitas un valor libre, mándalo como string (JSON dentro de un
texto, si no queda otra) y documéntalo.
Peticiones (in) |
Respuestas (out, ítems de un flujo) |
|
|---|---|---|
| Se revisan | con rigor | con holgura |
| Un campo no declarado | se rechaza: bad_input |
se descarta en silencio |
| Falta un campo obligatorio | bad_input |
bad_output |
| Un tipo equivocado | bad_input, nunca se convierte ("1990" no es un number) |
bad_output, nunca se convierte |
| Sin argumento | se lee como {} cuando todos los campos de in son opcionales; si no, bad_input |
— |
| Tamaño | máximo 64 KB de JSON (bytes UTF-8) | máximo 64 KB de JSON (bytes UTF-8) |
Solo el argumento mismo se lee como {} cuando falta: un null metido dentro de él (un elemento de un Opts[], por
ejemplo) sigue siendo bad_input.
El consumidor en detalle¶
El bloque consumes¶
consumes asocia un alias local con la puerta que representa. Máximo 8 entradas.
| Campo | Reglas |
|---|---|
| clave (el alias) | Letras y dígitos, empieza con letra, máximo 32. Solo lo ve tu código |
repo |
Obligatorio. El owner/name de GitHub del proveedor, sin más (sin URL, sin subcarpeta, sin @ref), el mismo tipo de texto que recommends. Un fork con otro repositorio no lo cumple |
door |
Obligatorio. El nombre de la puerta en el provides del proveedor |
calls |
Los nombres de las llamadas que usas, máximo 16. Una llamada que no está aquí responde not_declared aunque la puerta la tenga |
streams |
Los nombres de los flujos que usas, máximo 8 |
Dos alias pueden apuntar a la misma puerta (casi nunca sirve): el límite de ritmo es por puerta del proveedor, sin importar qué alias llega a ella. Un proveedor que se instala después del consumidor simplemente empieza a funcionar: nada se resuelve al instalar.
Los hosts del consumidor¶
Los datos que llegan por una puerta no necesitan host: hosts es solo para lo que tu plugin carga por su cuenta con
kino.fetch. Un consumidor cuyo único propósito es una pantalla que muestra lo que le dan sus proveedores es un consumidor solo
de pantalla: apiVersion 20 o mayor, un consumes no vacío y capabilities exactamente ["screen"]. Declara
"hosts": [] (contract.json, protocol.screenOnlyConsumer), como hace Cine Trivia.
- Sin host, sus propias llamadas a
kino.fetchse rechazan, salvo que declare"fetchHosts": "any"(entonces pueden llegar a cualquier host https público, y su hoja de instalación lo dice en rojo) o tenga un ajusteurl, solo o como campo de unalist(los servidores que escribe la persona). Sin una capacidad de fuente, no es una fuente. - Dibujar una imagen no necesita declarar su host: una
Imageacepta cualquier dirección https pública (Image: no hace falta declarar el host, como con toda imagen en Kino). Los pósters que te da un proveedor (elposterUrlde TMDB) se dibujan sinimage.tmdb.orgen tu manifiesto. - Con
"hosts": []y ningún ajuste, su tarjeta en Plugins dice que no se conecta a internet. Cualquier ajuste lo descarta (una dirección escrita es un servidor, y lo que escribe la persona podría salir con la dirección de una imagen). Sigue siendo un consumidor: su hoja de instalación trae la línea «Usa datos de …» de cada puerta que usa. - Si tu pantalla sí descarga algo propio, declara ese host real: el plugin conserva la condición de solo pantalla y la hoja de instalación muestra el host, así que tiene que ser verdad.
- Si agregas cualquier otra capacidad (un catálogo,
tracking, elplayerPanelTabde un panel...), dejasconsumesvacío o te quedas por debajo deapiVersion20 (conconsumessolo enenhancements["20"]), vuelve la regla de siempre: al menos un host, salvo que tenga un ajusteurl(The "hosts" field can only be empty if the plugin has a setting of type "url"). - Nunca publiques un relleno (
example.com, un nombre.testo.invalid, un dominio que nadie maneja): la persona leería un host que no es cierto.node sdk/init.mjs … --kind consumerescribe"hosts": [](o el host que le pases con--host), ynode sdk/validate.mjs .avisa (!, igual lo acepta) conexample.com,*.example.com,example.org,example.nety todo lo que termine en.test,.invalido.example. A un consumidor solo de pantalla el aviso le dicehosts: "example.com" is a placeholder host; a screen-only consumer needs no host: declare none ("hosts": []); its pictures from public https addresses need no declaration (see …); a cualquier otro plugin,… is a placeholder host; declare a host the plugin really loads from.
Un consumidor que solo muestra texto¶
Una pantalla que solo muestra texto (o imágenes de direcciones https públicas) y no carga nada propio es un consumidor solo de
pantalla como cualquier otro: declara "hosts": []. No hay nada que inventar ni que reemplazar:
{ "apiVersion": 20, "hosts": [], "capabilities": ["screen"], "consumes": { "recetas": { "repo": "tu-usuario/kino-plugin-recetas", "door": "recipes", "calls": ["byId"] } } }
El manifiesto vuelve a necesitar hosts reales apenas el plugin declara cualquier capacidad además de screen (entonces pon
cada host al que llega de verdad su propio kino.fetch). Un ajuste url (solo o en una list) o "fetchHosts": "any"
mantienen válido "hosts": [] pero abren la red: el primero llega a los servidores que escribe la persona, el segundo a cualquier
host https público (en rojo en la hoja), y con cualquier ajuste la tarjeta ya no dice que no se conecta. Las imágenes nunca
necesitan host.
Una pantalla de consumidor mínima que se dibuja limpia¶
El consumidor más pequeño que hace todo bien: la puerta de instalación, un Scaffold con un AppBar compacto, un scroll, un
botón que llama a la puerta, una frase de error por código y un interruptor de flujo. Está probado con el kit: con el
proveedor de ejemplo, node sdk/run.mjs --context '{"installed":{"kinotvapp/kino-plugin-tmdb":true}}' --provider <carpeta del
proveedor> . screen no imprime ninguna línea dropped, con installed en true y en false, con --lang en y con
--device tv. node sdk/init.mjs mi-consumidor --kind consumer crea uno más grande con sus propias pruebas.
{
"id": "mini-trivia",
"name": "Mini Trivia",
"version": "0.1.0",
"apiVersion": 20,
"entry": "plugin.js",
"description": "Una pregunta de cine con las películas del plugin TMDB",
"hosts": [],
"capabilities": ["screen"],
"screen": { "label": "Trivia", "labelEn": "Trivia" },
"recommends": ["kinotvapp/kino-plugin-tmdb"],
"consumes": { "tmdb": { "repo": "kinotvapp/kino-plugin-tmdb", "door": "movies", "calls": ["random"], "streams": ["trending"] } }
}
const TMDB = "kinotvapp/kino-plugin-tmdb"; // tal como está escrito en "recommends"
const ERRORS = {
provider_missing: ["TMDB está apagado o le falta configurarse: revísalo en Plugins.", "TMDB is off or needs setting up: check it in Plugins."],
rate_limited: ["Demasiadas preguntas seguidas. Espera un momento.", "Too many questions in a row. Wait a moment."],
};
const OTHER = ["No se pudo traer la película. Intenta otra vez.", "Could not get the movie. Try again."];
const text = (es, en, more = {}) => ({ type: "Text", text: es, textEn: en, ...more });
const page = (children) => ({
type: "Scaffold",
appBar: {
type: "AppBar", title: "Mini Trivia", titleEn: "Mini Trivia", mergeWithKinoBar: true, dense: true,
leading: { type: "IconButton", icon: "close", labelText: "Cerrar", labelTextEn: "Close", onPressed: { close: true } },
},
body: { type: "SingleChildScrollView", children: [{ type: "Column", padding: 16, gap: 12, children }] },
});
export async function screen({ state = {}, installed = {} }) {
if (installed[TMDB] !== true) {
return page([
text("Para jugar necesitas el plugin TMDB.", "To play you need the TMDB plugin."),
{ type: "ElevatedButton", key: "install", labelText: "Instalar TMDB", labelTextEn: "Install TMDB",
onPressed: { go: { installPlugin: { repo: TMDB } } }, autofocus: true },
]);
}
const kids = [];
if (state.movie) {
if (state.movie.poster) kids.push({ type: "Image", url: state.movie.poster, aspect: "2:3", width: 160 }); // image.tmdb.org
kids.push(text(`¿De qué año es ${state.movie.title}?`, `What year is ${state.movie.title} from?`, { style: "h3" }));
}
if (state.error) kids.push(text(...(ERRORS[state.error] || OTHER), { color: "error" }));
kids.push({ type: "ElevatedButton", key: "play", labelText: "Otra película", labelTextEn: "Another movie", onPressed: "play", autofocus: true });
kids.push({ type: "Switch", key: "live", labelText: "Tendencias en vivo", labelTextEn: "Live trending",
value: state.protocol?.tmdb?.trending === true, onChanged: "live" });
if (state.trending) kids.push(text(state.trending, state.trending, { style: "caption" }));
return page(kids);
}
export async function screenEvent({ name, value, arg, state = {}, installed = {} }) {
if (installed[TMDB] !== true) return null; // la puerta: nada funciona hasta que el proveedor esté instalado
if (name === "play") {
try {
const m = await kino.plugins.call("tmdb", "random", {});
return { state: { movie: { title: m.title, year: m.year, poster: m.posterUrl ?? null }, error: null } };
} catch (e) {
return { state: { error: e.code || "provider_failed" } }; // provider_missing, rate_limited, timeout...
}
}
if (name === "live") return { state: { protocol: { tmdb: { trending: value === true } } } };
if (name === "protocol" && Array.isArray(arg?.items)) {
return { state: { trending: arg.items.map((m) => m.title).slice(0, 5).join(", ") } };
}
return null;
}
Tres trampas en las que cae la costumbre de Flutter, y que ni el kit ni Kino dibujan:
| Escribes | Qué pasa | Escribe en cambio |
|---|---|---|
{ type: "SingleChildScrollView", child: { … } } |
un scroll vacío, y ninguna línea dropped te avisa |
children: [ … ], una lista, aunque sea de un solo hijo |
appBar: { title: "…" } (sin type) |
dropped: screen: scaffold appBar must be AppBar: se pierde la barra entera |
appBar: { type: "AppBar", title, titleEn, … } |
{ type: "FilledButton", … } |
unknown widget "FilledButton": el botón se descarta |
ElevatedButton (o TextButton) con labelText + labelTextEn y onPressed |
Un Text cuyo text es "" también se descarta (text is empty): mejor no pongas el nodo.
kino.plugins.call(alias, llamada, arg?)¶
const movie = await kino.plugins.call("tmdb", "byId", { id: 603 });
aliases una clave de tuconsumes,llamadaun nombre declarado ahí,argJSON que cumple elinde la llamada (omítelo, o pasa{}, cuando todos los campos son opcionales).- Se resuelve con la respuesta del proveedor, revisada contra
out, o se rechaza con unErrorcuyocodees uno de los siete códigos de error. - Dónde: en
screen,screenEventy las demás exportaciones que pueden usar los servicios de Kino (también las de un panel del reproductor). No en unjoben segundo plano (se rechaza connot_allowed) ni ensign(). - Detectarlo:
typeof kino.plugins === "object". Sirve cuando un consumidor ofrece el protocolo conenhancements["20"]y se queda en unapiVersionmás bajo (mira Kino anteriores). - Cada llamada es independiente: el estado de una pantalla vive en Kino, así que un manejador llama, responde con el
statenuevo y nada tiene que seguir vivo entre eventos. No guardes respuestas en variables globales esperando que sobrevivan; pon lo que necesitas enstate,kino.storageokino.shared.
Recetas cortas para un consumidor¶
El evento reservado open. Es el primer screenEvent de cada apertura. Mientras installed[repo] no sea true, responde
null, como a cualquier otro evento: la respuesta a open no puede llevar go.installPlugin (solo lo puede el toque o el
envío de la persona), y open descarta todo go salvo go.screen. Con el proveedor instalado, open puede cargar los
primeros datos (llamar a la puerta y responder un parche de state) o responder null y esperar un toque. Cuando la persona
instala el proveedor, Kino vuelve a llamar a screen con el installed nuevo; no manda otro open, así que la vista
principal tiene que funcionar con el state vacío (un botón, o un Skeleton y una carga con el primer toque).
Una caja de búsqueda (tres líneas): un TextField con kind: "search" y onSubmitted; el evento trae el texto escrito en
su value (no en arg).
{ type: "TextField", key: "q", kind: "search", labelText: "Buscar", labelTextEn: "Search", onSubmitted: "search" }
// screenEvent({ name: "search", value }) -> value es el texto escrito: kino.plugins.call("recipes", "search", { q: value })
// kit: node sdk/run.mjs --context "$I" --provider <proveedor> . screenEvent search "" '"tomate"' --trigger submit
En run.mjs el valor es la tercera palabra después de screenEvent (<nombre> [arg] [valor], "" si no hay arg) y
tiene que ser JSON: '"tomate"' con las comillas de adentro, nunca tomate (the value must be JSON). state.inputs.q
también tiene lo que muestra el campo; el campo completo está en formularios.
Una ruta de detalle. Responde { route: { push: "detail", params: { id } } } al toque; screen recibe entonces
route = { name: "detail", params: { id } }; el leading de su AppBar es un botón de atrás cuyo evento responde
{ route: { pop: true } }. Prueba la pantalla de detalle en el kit pasando la ruta en --context:
node sdk/run.mjs --context '{"installed":{"tu-usuario/kino-plugin-recipes":true},"route":{"name":"detail","params":{"id":1}}}' --state '{"item":{"id":1,"text":"Hola"}}' . screen
Un código que no esperabas. Ten una frase por defecto para cualquier code que tu switch no nombre (la de
provider_failed, por ejemplo): un Kino más nuevo puede agregar un código, y un caso que falta no puede lanzar un error fuera
de screenEvent.
focus en una clave dentro de un ítem de ListView. El focus de una respuesta mueve el foco al nodo con esa clave solo
si en ese momento está dibujado un nodo enfocable con ella; si no, se ignora sin dejar registro. ListView dibuja sus ítems a
medida que aparecen, así que un ítem fuera de la pantalla no está dibujado y el focus no hace nada; un ítem en pantalla con
onTap sí lo recibe. El kit acepta cualquier clave y no lo puede saber: no está garantizado. Mejor pon focus en una
clave fuera de la lista (un botón) o en un ítem que sabes que se ve.
Flujos¶
Un flujo es una suscripción que es de Kino y depende de una de tus pantallas. Nada corre en segundo plano cuando no hay ninguna pantalla tuya abierta.
- Enciéndelo con una marca de estado en tu respuesta:
{ state: { protocol: { tmdb: { trending: true } } } }, es decirstate.protocol.<alias>.<flujo> = true.falselo apaga. La claveprotocolse reemplaza entera como cualquier otra clave del estado, así que manda todas tus marcas juntas cuando tienes más de una. - Mientras esa pantalla está abierta, visible y con Kino al frente, Kino llama a
proto_<puerta>_<flujo>(cursor)del proveedor cadaeverySeconds(30 como mínimo, 60 si el proveedor no lo dijo), con el último cursor (nullla primera vez). - Kino revisa cada ítem contra el
outdel flujo y descarta los que no cumplen. - Si hay ítems nuevos, tu
screenEventrecibe el eventoprotocolconarg{ alias, stream, items }. Su respuesta se trata como la de un tic de un temporizadorevery: solo se conservanstate,toast,closeyconfig. - Tres fallas seguidas apagan esa suscripción durante esta apertura de la pantalla. Nunca cuenta para «No responde».
| Regla | Número |
|---|---|
| Suscripciones vivas por plugin | 4 |
Marcas que se leen de state.protocol |
16 |
| Consultas por puerta del proveedor | 8 en cualquier ventana de 10 s, compartidas por todos sus suscriptores (aparte de las 30 llamadas, así tus llamadas nunca dejan sin consultas a tus flujos) |
| Intervalo de consulta | everySeconds de 30 a 86.400; 60 por defecto |
Bueno saberlo:
- Cerrar la pantalla termina la suscripción; nada se guarda. Cuando Kino deja de estar al frente, se detienen todas.
- El cursor de un flujo se pierde cuando se va su último suscriptor: al volver, el proveedor se consulta otra vez desde
null, y un lote ya entregado puede volver a llegar. Haz que tu manejador deprotocoltolere repetidos (Cine Trivia solo muestra el título más nuevo). - Un suscriptor que se suma a un flujo que otros ya comparten recibe solo lo consultado después de sumarse.
- Los flujos son para las pantallas de un plugin, no para una sesión del panel del reproductor.
- El cursor es asunto del proveedor: un desplazamiento, una fecha, la lista de ids ya entregados (TMDB guarda hasta 200 ids). Tiene que ser JSON, y pequeño: es parte de la respuesta del proveedor, que puede medir como mucho 64 KB junto con los ítems, y vuelve en cada consulta. Nunca guardes ahí los ítems mismos.
Errores¶
kino.plugins.call se rechaza con un Error cuyo code es exactamente uno de estos:
code |
Cuándo | Qué debería hacer el consumidor |
|---|---|---|
provider_missing |
El proveedor (el plugin de ese repositorio) no está instalado, está apagado o le falta configurarse, o es 18+ y tu plugin no | Mostrar la puerta de instalación (o «enciende TMDB») |
not_declared |
El alias no está en tu consumes, la llamada o el flujo no está declarado ahí, la puerta del proveedor no lo tiene, o la puerta es de tu propio plugin |
Un error de tu manifiesto, o el proveedor quitó la llamada: regístralo, di «no disponible» |
bad_input |
Tu argumento no cumple el in de la llamada, no es JSON o pasa de 64 KB |
Un error de tu código: revisa los tipos del proveedor |
bad_output |
La respuesta del proveedor no cumple out, no es JSON, pasa de 64 KB o lleva uno de sus secretos sellados |
Un error del proveedor: muestra un error corto con «Reintentar» |
rate_limited |
Más de 30 llamadas en cualquier ventana de 10 s de tu plugin a una puerta de un proveedor (con el alias que sea) | Baja el ritmo; nunca reintentes en bucle |
timeout |
El proveedor tardó más de 10 s | Ofrece «Reintentar» |
provider_failed |
El proveedor lanzó un error, o no exporta proto_<puerta>_<llamada> |
Ofrece «Reintentar»; si sigue fallando, el problema es del proveedor |
En un job en segundo plano, kino.plugins.call se rechaza con not_allowed. El rechazo es un Error normal: espera
siempre la llamada con await dentro de try/catch, y muéstrale a la persona una frase tuya, en español y en inglés, nunca
el código pelado.
try {
const list = await kino.plugins.call("tmdb", "search", { q });
return { state: { results: list } };
} catch (e) {
if (e.code === "provider_missing") return { state: { needsTmdb: true } }; // la pantalla dibuja el botón de instalar
return { toast: { text: "TMDB no respondió, intenta otra vez", textEn: "TMDB did not answer, try again" } };
}
Límites¶
| Qué | Límite |
|---|---|
| Puertas por proveedor | 4 |
| Llamadas / flujos por puerta | 16 / 8 |
summary de una puerta |
120 caracteres |
| Nombres (puerta, llamada, flujo, alias) | ^[A-Za-z][A-Za-z0-9]{0,31}$ |
| Nombres de tipo | ^[A-Z][A-Za-z0-9]{0,31}$ |
Entradas de consumes |
8; cada una declara como mucho 16 llamadas y 8 flujos |
| Petición y respuesta | JSON, máximo 64 KB (65.536 bytes UTF-8) cada una |
| Tiempo por llamada | 10 s |
| Llamadas | 30 en cualquier ventana de 10 s, por consumidor y puerta del proveedor |
| Intervalo de un flujo | everySeconds de 30 a 86.400, 60 por defecto |
| Suscripciones vivas | 4 por consumidor; se leen 16 marcas del estado |
| Consultas | 8 en cualquier ventana de 10 s por puerta del proveedor |
| Dónde | pantallas y las demás exportaciones; nunca un job en segundo plano (not_allowed) ni sign() |
Los mismos números están en Límites y trampas del motor.
Un plugin que solo provee¶
Un plugin cuyo único propósito es abrir puertas no necesita nada más: apiVersion 20, un provides no vacío, ninguna
capacidad (el campo capabilities puede faltar) y ningún ajuste. Ese plugin solo provee y puede declarar "hosts": [].
No reproduce nada, no es una fuente y no aparece en la búsqueda ni en Inicio. Con "hosts": [] su hoja de consentimiento no
reclama red ni papel alguno, y su tarjeta de instalado dice que no se conecta a internet: llega al mundo solo a través de los
servicios de Kino, como kino.tmdb. node sdk/init.mjs mi-proveedor --kind provider crea uno, con su
prueba.
No existe un campo providesOnly: Kino lo deduce de esas condiciones, y node sdk/validate.mjs avisa si escribes uno.
{
"id": "movie-facts",
"name": "Movie Facts",
"version": "1.0.0",
"apiVersion": 20,
"entry": "plugin.js",
"hosts": [],
"provides": {
"facts": {
"summary": "Datos cortos de una película",
"calls": { "forMovie": { "in": { "tmdbId": "number" }, "out": "string[]" } }
}
}
}
- Un proveedor que necesita
kino.fetch(su propia API en vez de un servicio de Kino) pone esos hosts enhosts, como cualquier plugin. Eso no le quita la condición: sin capacidades ni ajustes sigue siendo un plugin que solo provee (no tiene que escribirresolve,searchnihome), pero su hoja de consentimiento ahora muestra esos hosts. - Si declaras cualquier capacidad o cualquier ajuste, o pones
providespor debajo deapiVersion20, vuelven las reglas de siempre (resolveysearchohome, al menos un host...). - El otro lado tiene la misma libertad: un consumidor solo de pantalla (un
consumesno vacío,capabilitiesexactamente["screen"]) también puede declarar"hosts": [].
Kino anteriores: apiVersion 20 o enhancements["20"]¶
| Cómo lo declaras | En Kino 0.9.81 o más nuevo | En un Kino anterior |
|---|---|---|
"apiVersion": 20 con provides / consumes en el nivel principal |
Funciona | El plugin no se instala («Este plugin necesita una versión más nueva de Kino») |
Un apiVersion más bajo con provides / consumes en el nivel principal |
Se rechaza: The "provides" block needs apiVersion 20 |
Se ignora |
Un apiVersion más bajo con "enhancements": { "20": { "provides": … } } |
Funciona: el bloque se mezcla y se revisa como apiVersion 20 |
El bloque se ignora; el plugin se instala y funciona como antes |
- Un proveedor que ya tiene usuarios debería usar
enhancements["20"](como TMDB): nadie se queda sin el plugin. - Un consumidor que solo tiene sentido con su proveedor puede declarar
apiVersion20 (como Cine Trivia). Un consumidor que tiene otros usos puede ponerconsumesenenhancements["20"]y esconder la función contypeof kino.plugins === "object". recommendseinstalledno tienenapiVersionpropio (Kino 0.9.81 los lee con cualquierapiVersion, un Kino anterior los ignora);go.installPluginvale desdeapiVersion19 (por debajo, Kino lo descarta y lo registra).- Un bloque dentro de
enhancementsque rompe una regla se descarta y se registra, nunca rechaza tu plugin: correnode sdk/validate.mjs ., que lista cada descarte. Más en Pantallas sin subir tu apiVersion.
Lo que ve la persona¶
- En la hoja de instalación del consumidor, una línea informativa normal por cada puerta que usa, sin rojo y sin
interruptor: «Usa datos de TMDB (Movie records from TMDB)» («Uses data from TMDB (Movie records from TMDB)» en inglés): el
namedel proveedor y elsummaryde la puerta. Si el proveedor todavía no está instalado, la línea nombra su repositorio («Usa datos de kinotvapp/kino-plugin-tmdb»). - En una actualización que agrega una puerta a
consumes, la línea sale marcada como nueva (también en el aviso de una actualización que Kino aplicó por su cuenta). - No hay pregunta por llamada. Tener el proveedor instalado es el consentimiento.
- Nada se instala en silencio. Un consumidor solo puede mostrar un botón
go.installPlugin; Kino abre su propia hoja de instalación con las líneas de consentimiento del proveedor, y solo el Instalar de la persona lo instala. - En su tarjeta de Plugins, un consumidor solo de pantalla con
"hosts": []y sin ajustes dice que no se conecta a internet; con cualquier ajuste, no. - Quitar al proveedor solo hace que sus puertas respondan
provider_missing; los consumidores no cambian ni se desinstalan. - No hay nada nuevo que sincronizar: el protocolo no guarda nada. Guarda tu propio estado en
kino.storageokino.sharedcomo siempre.
Seguridad y privacidad¶
Tus argumentos le llegan al proveedor
La línea de consentimiento dice que el consumidor usa los datos del proveedor; no dice nada de lo que el consumidor
manda. Cada argumento de cada llamada le llega al proveedor, que puede mandarlo a sus propios hosts (o a cualquier
host público, con "fetchHosts": "any"). Nunca pongas en un argumento lo que no le darías al autor del proveedor: ni
tokens, ni contraseñas, ni nada que la persona escribió en un campo privado.
- 18+: un proveedor 18+ solo le responde a un consumidor 18+. Para cualquier otro plugin sus puertas responden
provider_missing, así el contenido 18+ nunca pasa a un plugin que se muestra con el candado 18+ cerrado. - Los secretos sellados nunca pasan. Una respuesta (o una consulta de un flujo) que lleva uno de los
secretos sellados del proveedor, en cualquier forma, o una marca de secreto, es
bad_output: la misma regla que aplicakino.shared. - Nada de llamarse a sí mismo. Un plugin no puede usar su propia puerta: responde
not_declared(la llamada se esperaría a sí misma hasta el tiempo límite). Dos plugins que usan las puertas del otro no deben llamar de vuelta desde dentro de una respuesta: la segunda llamada puede esperar a la primera hastatimeout. - No se amplían los hosts. Recibir datos de un proveedor no le da al consumidor ningún host nuevo: lo que pide sigue
limitado a sus propios
hostsaprobados. - Solo sale lo declarado. El proveedor decide en código qué responde; Kino descarta todo campo que la puerta no declara.
- Repositorio, no id. Un consumidor nombra a su proveedor por repositorio. Un plugin que copia el
iddel proveedor desde otro repositorio (o un fork) no es ese proveedor.
Probar sin conexión con el kit¶
Empieza con una plantilla. Las dos traen las formas correctas desde la primera línea y una prueba que pasa tal como salen:
node sdk/init.mjs mi-proveedor --kind provider
# solo provee (apiVersion 20, "hosts": [], sin capacidades), puerta "quotes" con una llamada y un flujo, test/plugin.test.mjs
node sdk/init.mjs mi-consumidor --kind consumer --repo tu-usuario/kino-plugin-quotes --door quotes --call byId
# un consumidor solo de pantalla con "hosts": [] (--host <un host del que de verdad descarga> agrega uno), la puerta de instalación, una sola barra compacta (mergeWithKinoBar + dense, un leading que cierra), una
# ruta de detalle con atrás, un error por código, un interruptor de flujo y el foco de TV; test/provider es un proveedor
# DE REEMPLAZO con los mismos nombres de puerta y llamada
node sdk/init.mjs --help
--door, --call y --stream (por defecto quotes, byId, latest) reciben los nombres de la puerta real, también
para un proveedor, para que el consumidor, su reemplazo y el proveedor coincidan. test/provider es un reemplazo, no el
proveedor real (su README.md lo dice): cámbialo por una copia del proveedor real (los mismos nombres de puerta, llamada y
flujo, y los mismos tipos), y después ajusta el argumento y los campos que lee tu código, y la prueba de la plantilla. La
description del consumidor sale como un TODO: en español para reescribir, y screen.labelEn como una etiqueta en inglés (el
nombre de la puerta: revísala).
Después copia el kit junto al plugin nuevo: sdk/ sin sdk/test/ y contract.json (los dos obligatorios; kino.d.ts es
opcional, solo para los tipos de tu editor: el kit nunca lo lee; mira Probar en local), y
cambia el relleno your-user/... de la plantilla por el repositorio real del proveedor. El "hosts": [] del consumidor no es
un relleno: déjalo vacío salvo que la pantalla descargue algo propio.
Un proveedor solo, sin consumidor: proto manda una llamada o una consulta por las revisiones de la app (el argumento,
estricto contra in; la respuesta, flexible contra out) y con sus códigos de error:
node sdk/run.mjs ./mi-proveedor proto quotes.byId '{"id":1}' # una llamada: imprime la respuesta revisada
node sdk/run.mjs ./mi-proveedor proto quotes.byId '{"id":"1"}' # ✗ bad_input: $.id: expected number
node sdk/run.mjs ./mi-proveedor proto quotes.latest # la primera consulta de un flujo (cursor null): imprime { items, cursor }
node sdk/run.mjs ./mi-proveedor proto quotes.latest '2' # la siguiente, desde el cursor que imprimió la anterior
Código de salida 0 con la respuesta en stdout; 1 con ✗ <código>: <mensaje> en stderr cuando Kino rechazaría la llamada (si tu
exportación lanzó un error, su propio mensaje sigue en una línea ·: el consumidor nunca lo ve); 2 para un comando mal escrito
(una puerta o llamada que no existe, y las lista; un JSON que no se puede leer; una carpeta sin provides).
Un consumidor con su proveedor. --provider <carpeta> (se puede repetir) carga el proveedor en su propio sandbox y responde
cada kino.plugins.call con sus exportaciones; sin él, toda llamada se rechaza con provider_missing. Pásale installed
también a screenEvent: un consumidor con puerta de instalación no hace nada mientras está en false.
I='{"installed":{"kinotvapp/kino-plugin-tmdb":true}}'
node sdk/run.mjs ./cine-trivia screen # la puerta de instalación: cada entrada de recommends es false
node sdk/run.mjs --context "$I" --provider ../kino-plugin-tmdb ./cine-trivia screen
node sdk/run.mjs --context "$I" --lang en --provider ../kino-plugin-tmdb ./cine-trivia screen # los textos en inglés
node sdk/run.mjs --context "$I" --device tv --provider ../kino-plugin-tmdb ./cine-trivia screen
node sdk/run.mjs --context "$I" --provider ../kino-plugin-tmdb ./cine-trivia screenEvent play
# un flujo: una consulta, enviada como el evento "protocol" { alias, stream, items }; --cursor consulta desde un cursor dado
node sdk/run.mjs --context "$I" --state '{"protocol":{"tmdb":{"trending":true}}}' --provider ../kino-plugin-tmdb ./cine-trivia screenEvent protocol tmdb.trending
node sdk/run.mjs --context "$I" --cursor '[603]' --provider ../kino-plugin-tmdb ./cine-trivia screenEvent protocol tmdb.trending
- Lee stderr. Una línea
· dropped: …es un nodo que Kino no dibujaría. El código de salida sigue en 0 aunque se descarten nodos, así que una corrida limpia es una sin líneasdropped.node sdk/run.mjssin argumentos imprime todos los comandos. --cursorte deja mandar un cursor que el proveedor ya devolvió, para ver qué hace tu manejador deprotocolcon un lote que quizá ya vio (Kino puede reenviar ítems después de volver).- Qué códigos de error puede provocar el kit. Con una carpeta de proveedor real, solo dos:
provider_missing(corre sin--provider) yprovider_failed(una llamada en la que el proveedor lanza un error, como un id que no tiene);prototambién muestrabad_inputcon un argumento equivocado.not_declared,bad_output,rate_limitedytimeoutnecesitan un manifiesto roto, un proveedor roto o tiempo real, así que prueba que tu pantalla dibuja cada uno poniendo el código en el estado:node sdk/run.mjs --context "$I" --state '{"error":"rate_limited"}' . screen(y un código inventado, para tu frase por defecto). - Revisar que una propiedad se acepta. El árbol que se imprime es el revisado y no repite cada bandera (el
dense: truede unAppBar, por ejemplo, no sale). Un valor equivocado sí:dense: "yes"imprime· dropped: screen: appBar dense "yes" is not true or false, ignored. Así que una corrida sin líneasdroppedquiere decir que se aceptaron todas las propiedades;--rawimprime el árbol tal como lo devolvió tu plugin. La app dibujadenseen un teléfono (4 dp arriba y abajo de la fila de la barra) y lo ignora en la TV y en un panel del reproductor (Una sola barra compacta). - El kit ignora
repo. No tiene repositorios, así que atiende cada entrada deconsumescon el primer proveedor que tiene esa puerta; la app compara elrepode la entrada. Revisa a mano quereposea eldueño/nombreexacto del repositorio de GitHub del proveedor (abrehttps://github.com/<dueño/nombre>), el mismo texto enrecommendsy en la clave que tu código lee deinstalled. - Los servicios propios del proveedor funcionan como siempre en el kit: TMDB necesita
KINO_TMDB_KEYo unKINO_TMDB_FIXTUREparakino.tmdb(Probar en local). node sdk/validate.mjs <carpeta>leeprovidesyconsumes(en el nivel principal y enenhancements) igual que la app. Falla (✗, salida 1) cuando una llamada o un flujo declarado no tiene su exportaciónproto_<puerta>_<nombre>(Kino lo instala, pero toda llamada de un consumidor a eso respondeprovider_failed; el nombre distingue mayúsculas). Avisa (!, salida 0: lee cada aviso) cuando un repositorio consumido no está enrecommends(la puerta de instalación nunca se abriría), cuando eleverySecondsde un flujo está fuera de 30..86.400 (dice el valor que usa Kino), cuando el manifiesto tiene un campoprovidesOnly(no existe) y cuando una entrada dehostses un relleno (example.com,*.example.com,example.org,.test,.invalid,.example; a un consumidor solo de pantalla le dice que no declare ninguno, mira loshostsdel consumidor).- En tus propias pruebas,
createProtocolCallerycreateKino(manifest, { protocol })desdk/protocol.mjste dan el mismo intermediario. --providerysdk/protocol.mjsson del kit de Kino 0.9.81, yproto,--cursor,--langeinit.mjs --kindde sus copias más recientes. Sirun.mjsoinit.mjsno conoce alguno, ovalidate.mjsno conoceprovides, tu copia desdk/,contract.jsonykino.d.tses más vieja: reemplaza las tres desde kinotvapp/kino-plugin-sdk (nunca calles el error quitando los bloques).
Lo que solo revisa la app
El kit no aplica la regla 18+, ni el rechazo de secretos sellados en las respuestas, ni el rechazo de llamarse a sí
mismo, y no compara repo: eso necesita los plugins instalados, y solo Kino los tiene. Antes de publicar, instala los dos
plugins en Kino 0.9.81 o más nuevo y prueba el flujo real: la puerta de instalación, una llamada, el interruptor del flujo
y quitar al proveedor. Más en Lo que el kit no puede copiar.
Listas de revisión¶
Proveedor
providesen el nivel principal con"apiVersion": 20, o enenhancements["20"]para conservar tuapiVersion.- Una exportación por llamada y por flujo:
proto_<puerta>_<nombre>, escrita exactamente como en el manifiesto (mayúsculas incluidas). - Cada respuesta cumple
out; un flujo responde{ items, cursor }. - Nada privado en las respuestas ni en los mensajes de error; ningún secreto sellado en ninguna respuesta.
- Un
summarycorto que la persona entienda; la puerta descrita en tu README. - Después de publicar, los cambios solo agregan (llamadas nuevas, campos opcionales); un cambio que rompe va en una puerta nueva.
node sdk/validate.mjs .no muestra ningún✗(falta una exportaciónproto_= falla) y leíste cada!.- Cada llamada probada con
node sdk/run.mjs . proto <puerta>.<llamada> '<json>'(también con un argumento malo), cada flujo conproto <puerta>.<flujo>y otra vez desde el cursor que imprimió. - Un plugin que solo provee no tiene capacidades, ni ajustes, ni un campo
providesOnly; sushostsson[]o los reales que necesita sukino.fetch.
Consumidor
consumescon elrepoexacto del proveedor, ladoory solo las llamadas y los flujos que usas.- El mismo repositorio en
recommends, y una pantalla de instalación congo.installPluginmientrasinstalled[repo]no seatrue. - Cada
kino.plugins.calldentro detry/catch, con un mensaje en español y en inglés por caso; nada de reintentos en bucle. - Los argumentos no llevan nada que el autor del proveedor no deba ver.
- Ninguna llamada desde un
joben segundo plano. - Un manejador de
protocolque tolera ítems repetidos (pruébalo con--cursor). hostses[]en un consumidor solo de pantalla (soloscreen, unconsumesno vacío), o los hosts reales a los que llega su propiokino.fetch; nuncaexample.comni otro relleno.node sdk/validate.mjs .no muestra ningún!sobrerecommends; tureporevisado a mano (el kit lo ignora).- La pantalla dibujada con
installedentruey enfalse, con--lang eny con--device tv, sin líneasdropped. - Probado con
--provideren el kit, y en la app con el proveedor real instalado, apagado y quitado.