@get-air/stremio-addon-client

A safe, fully typed client for consuming remote Stremio addon protocol endpoints. It does not build addons, execute addon code, maintain an installed-addon list, or persist addon configuration.

The root API uses ordinary Promises and plain TypeScript values:

import { StremioAddon, isStremioAddonError } from "@get-air/stremio-addon-client"

const addon = await StremioAddon.connect("https://example.com/manifest.json")

try {
  const { streams } = await addon.streams("movie", "tt1254207")
  console.log(streams)
} catch (error) {
  if (isStremioAddonError(error)) console.error(error._tag, error.message)
}

Effect applications import the same implementation from the explicit entrypoint:

import { Effect } from "effect"
import { StremioAddon } from "@get-air/stremio-addon-client/effect"

const program = Effect.gen(function* () {
  const addon = yield* StremioAddon.connect("https://example.com/manifest.json")
  return yield* addon.streams("movie", "tt1254207")
})

Protocol coverage

• Manifest discovery from a base URL, manifest.json URL, or stremio:// install URL.
• Catalog, metadata, stream, subtitle, and addon-catalog resources.
• Manifest capability checks before resource requests.
• Correct path encoding and deterministic catalog/subtitle extras.
• Runtime validation of untrusted manifest and resource JSON.

Safety

HTTPS is required by default. Credentials in URL authorities and literal private-network/localhost targets are rejected. Applications may restrict requests further with allowedOrigins or urlPolicy. HTTP and private-network access can be enabled explicitly with allowHttp and allowPrivateNetwork for trusted local addons.

Requests have a 15-second default timeout and a 10 MiB response limit. Redirect destinations are checked against the same URL policy. Non-success status codes, invalid JSON, invalid protocol responses, timeouts, oversized bodies, and unsupported resources have distinct tagged errors.

This library validates protocol data; it does not decide whether a returned stream is legal, trusted, or safe to play. Applications should present P2P warnings and apply their own stream URL policy before playback.

Hostname checks cannot prevent DNS rebinding in a privileged server or desktop process. Applications accepting arbitrary addon URLs should enforce resolved-address policy in their injected transport as well.

Shared transport and Tauri

All networking uses @get-air/http:

import { makeTauriHttpTransport } from "@get-air/http/tauri"
import { StremioAddon } from "@get-air/stremio-addon-client"

const addon = await StremioAddon.connect(manifestUrl, {
  transport: makeTauriHttpTransport({
    connectTimeout: 10_000,
    maxRedirections: 5,
  }),
})

The consuming Tauri app must grant HTTP capabilities for the addon origins it allows.

Optional cache

Pass any @get-air/cache CacheStore. Only validated HTTP response bodies are cached; addon registrations and configuration are never stored. Cache failures are fail-open and can be observed with onCacheError.

import { TauriCacheStore } from "@get-air/cache/tauri"

const cache = await TauriCacheStore.make("air-cache.json")
const addon = await StremioAddon.connect(manifestUrl, { cache })

Cache keys contain SHA-256 URL digests rather than configured addon URLs, so path-based addon credentials are not exposed in persistent keys.

Research basis

The implementation follows the official Stremio addon protocol and SDK response definitions. It also incorporates behavior found in the official addon client, Harbor, and Cremio: capability checks, abortable timeouts, bounded JSON reads, cache-control support, and tolerance for common community-addon response variations.