Skip to content

Example stores

Available with Kino 0.9.77

Plugin stores are apiVersion 15 and arrive with Kino 0.9.77. Read Plugin stores first.

Two complete plugins you can copy and change. Both pass node sdk/validate.mjs ., ship tests that run without a network with the kit, and use example hosts (raw.githubusercontent.com/your-user/…, plugins.example.org): change hosts, the address of your list and your details. The publisher of a store answers for what it lists; Kino only shows it, with its blocklist and the 18+ code.

To start from scratch: node sdk/init.mjs my-store --host my-site.example --store local (or --store live).

Local store: a static JSON file

The whole list is one file (plugins.json) that you publish anywhere over https; the plugin downloads it in storeSync and hands Kino the whole list (full: true), or an empty change when the file did not change. Kino never asks it anything while the person browses. It only skips the work when it holds a state from before: if Kino lost the store's rows it asks again with no since and no state, and the plugin answers the whole list.

Downloads: kino-plugin.json · plugin.js · plugins.json · test/store.test.mjs

kino-plugin.json

{
  "id": "my-kino-store",
  "name": "My Kino store",
  "version": "1.0.0",
  "apiVersion": 15,
  "entry": "plugin.js",
  "description": "Una tienda de plugins para Kino hecha con un archivo JSON estático. A plugin store for Kino backed by one static JSON file.",
  "author": "your-user",
  "hosts": ["raw.githubusercontent.com"],
  "capabilities": ["pluginStore"],
  "pluginStore": { "mode": "local", "name": "My Kino store" }
}

plugin.js

// A LOCAL plugin store: the whole list is one static JSON file (plugins.json) that you publish anywhere over https, here a
// GitHub repository's raw file. Kino never asks this plugin anything while the person browses: it calls storeSync in the
// background (every 2 hours by default, Wi-Fi only) and when the person presses reload, keeps the entries in its own local
// index and paints the store from there (cards, search, categories, sort). Installing is always Kino's own flow.
//
// Change LIST_URL to where you publish plugins.json, and "hosts" in kino-plugin.json to that host.
const LIST_URL = "https://raw.githubusercontent.com/your-user/my-kino-store/main/plugins.json";

/** One row of plugins.json -> a StoreEntry. Only `address` (or `stremio`), `id` and `name` are required. */
function toEntry(p) {
  return {
    address: p.repo,                  // what Kino installs from: "owner/repo", "owner/repo/path", "owner/repo@ref" or "url:https://.../kino-plugin.json"
    id: p.id,                         // the plugin's own id (its kino-plugin.json "id")
    name: p.name,
    description: p.description,
    categories: p.categories,         // movies, series, anime, live, radio, subtitles, utilities, adult
    icon: p.icon,                     // an https URL; anything else is dropped
    version: p.version,
    author: p.author,
    popularity: p.popularity,         // a number; the "popular" sort
    updatedAt: p.updatedAt,           // ms since 1970; the "recent" sort
  };
}

export async function storeSync({ reason, since, state }) {
  // reason: "schedule" (the background refresh) or "reload" (the person pressed reload)
  // since:  when this store last synced successfully (ms), absent the first time
  // state:  whatever this function returned as `state` the last time (at most 16 KB of JSON)
  const r = await kino.fetch(LIST_URL);
  if (!r.ok) throw kino.error("unavailable", "the list answered " + r.status);
  const list = r.json();

  // Nothing changed since the last sync: say so with an empty delta (full: false, no entries) and keep Kino's rows as they are.
  if (state && state.generatedAt === list.generatedAt) return { full: false, entries: [], state };

  // full: true means `entries` is the WHOLE list: Kino replaces this store's rows, so a plugin you remove from plugins.json
  // leaves the store on its own. (Leaving a store never uninstalls anything a person already installed.)
  return { full: true, entries: list.plugins.map(toEntry), state: { generatedAt: list.generatedAt } };
}

plugins.json (the file you publish)

{
  "generatedAt": 1790000000000,
  "plugins": [
    {
      "repo": "your-user/my-movies-plugin",
      "id": "my-movies",
      "name": "My movies",
      "description": "Películas desde mi sitio favorito. Movies from my favourite site.",
      "categories": ["movies"],
      "icon": "https://raw.githubusercontent.com/your-user/my-movies-plugin/main/icon.png",
      "version": "1.2.0",
      "author": "your-user",
      "popularity": 120,
      "updatedAt": 1789000000000
    },
    {
      "repo": "your-user/my-tools/subtitles-plugin",
      "id": "my-subtitles",
      "name": "My subtitles",
      "description": "Subtítulos para cualquier título. Subtitles for any title.",
      "categories": ["subtitles", "utilities"],
      "version": "0.4.0",
      "author": "your-user",
      "popularity": 40,
      "updatedAt": 1788000000000
    }
  ]
}

Live store: its own API

Besides storeSync (a base list: its featured plugins) it answers while the person browses: storeList (a page of a category, popular or recent) and storeSearch. A live store must export all three functions. The person reads, in red, that what they search in the store will reach its servers. How Kino mixes it with the other stores: Plugin stores.

Downloads: kino-plugin.json · plugin.js · sample-api.json · test/store.test.mjs

kino-plugin.json

{
  "id": "my-live-store",
  "name": "My live store",
  "version": "1.0.0",
  "apiVersion": 15,
  "entry": "plugin.js",
  "description": "Una tienda de plugins para Kino con su propia API: lista, busca y pagina en vivo. A plugin store for Kino with its own API: it lists, searches and pages live.",
  "author": "your-user",
  "hosts": ["plugins.example.org"],
  "capabilities": ["pluginStore"],
  "pluginStore": { "mode": "live", "name": "My live store" }
}

plugin.js

// A LIVE plugin store: its list lives behind your own API. Like every store it exports storeSync (a base list Kino keeps in
// its local index, so the store shows up at once and offline), and because it is live it also answers WHILE the person
// browses: storeList (a category page, popular or recent) and storeSearch (a search the base list may not hold).
//
// How Kino mixes it: the local list paints first; this store's live results are appended at the end as they arrive (never
// inserted above what is on screen), entries whose address is already shown are skipped, and Kino's blocklist, 18+ code and
// "de <store>" badge apply to them as to any entry. When the person picks this store in the store filter, the list is only
// its live answers. Each call may take 5 s at most and a store gets 20 calls a minute (past either, that call adds nothing);
// Kino keeps a live page for 30 minutes. Because every search reaches your server, Kino shows the person a red line about it
// before they install the store. Change API and the manifest's "hosts" to your own server.
const API = "https://plugins.example.org/api";

/** One API row -> a StoreEntry. Only `address` (or `stremio`), `id` and `name` are required. */
function toEntry(p) {
  return {
    address: p.repo,
    id: p.id,
    name: p.name,
    description: p.summary,
    categories: p.categories,   // movies, series, anime, live, radio, subtitles, utilities, adult
    icon: p.iconUrl,            // https only
    version: p.version,
    author: p.author,
    popularity: p.downloads,    // the "popular" sort
    updatedAt: p.updatedAt,     // ms; the "recent" sort
  };
}

async function get(path, params) {
  const query = Object.entries(params)
    .filter(([, v]) => v !== undefined && v !== null && v !== "")
    .map(([k, v]) => encodeURIComponent(k) + "=" + encodeURIComponent(v))
    .join("&");
  const r = await kino.fetch(API + path + (query ? "?" + query : ""));
  if (r.status === 429) throw kino.error("rate_limited", "too many requests");
  if (!r.ok) throw kino.error("unavailable", "the store answered " + r.status);
  return r.json();
}

/** The base list: your featured plugins. A full list, so a plugin you drop from /featured leaves the store on the next sync. */
export async function storeSync({ reason, since, state }) {
  const data = await get("/featured", {});
  return { full: true, entries: data.plugins.map(toEntry) };
}

/** A page of one category (or of everything): sort is "popular" or "recent"; cursor is whatever you returned as `next`. */
export async function storeList({ category, sort, cursor }) {
  const data = await get("/plugins", { category, sort, cursor });
  return { entries: data.plugins.map(toEntry), next: data.next || undefined };
}

/** A search the person typed (Kino waits until they stop typing and cancels an older search when a newer one starts). */
export async function storeSearch({ q, category, cursor }) {
  const data = await get("/search", { q, category, cursor });
  return { entries: data.plugins.map(toEntry), next: data.next || undefined };
}

sample-api.json (what the test's made-up API answers)

{
  "$comment": "What the example's API answers, made up. /featured and /plugins and /search all answer { plugins: [...], next? }. The test serves these through a fake fetch.",
  "plugins": [
    { "repo": "your-user/live-series", "id": "live-series", "name": "Live series", "summary": "Series desde mi servidor. Series from my server.", "categories": ["series"], "iconUrl": "https://plugins.example.org/icons/live-series.png", "version": "2.0.1", "author": "your-user", "downloads": 900, "updatedAt": 1789500000000 },
    { "repo": "your-user/live-anime", "id": "live-anime", "name": "Live anime", "summary": "Anime en vivo. Live anime.", "categories": ["anime"], "version": "1.1.0", "author": "your-user", "downloads": 450, "updatedAt": 1789000000000 },
    { "repo": "your-user/live-radio", "id": "live-radio", "name": "Live radio", "summary": "Radio por internet. Internet radio.", "categories": ["radio", "live"], "version": "0.9.0", "author": "your-user", "downloads": 80, "updatedAt": 1788000000000 }
  ],
  "next": "page-2"
}

Trying them

Copy an example's folder, put the kit's sdk/ and contract.json inside it and run:

node sdk/validate.mjs .
node --test test/store.test.mjs                  # offline: the list comes from a sample file
node sdk/run.mjs . storeSync                     # online: downloads the real list
node sdk/run.mjs . storeList popular series      # live store
node sdk/run.mjs . storeSearch "anime"           # live store

Other examples

  • Kino Plugins, the store that ships in the app, is a real local store that combines a list it carries, a daily index and small changes: Plugin stores.
  • Kino Social, a Kino screen plugin, is the worked example of identity and notifications.