Add typescript types

README.md

@@ -10,6 +10,11 @@ Stremio currently supports Windows, macOS, Linux, Android and iOS.
 **Important: We strongly recommend deploying addons to the [BeamUp](./docs/deploying/beamup.md) servers**
 
 
+## TypeScript Support
+
+The Stremio Addon SDK includes built-in TypeScript types. You no longer need to install the community package `@types/stremio-addon-sdk` for type definitions as of Stremio Addon SDK version `>1.6.10`.
+
+
 ## Quick Example
 
 This arbitrary example creates an addon that provides a stream for Big Buck Bunny and outputs a HTTP address where you can access it.

docs/advanced.md

@@ -9,6 +9,7 @@
 - [Using Deep Links in Addons](#using-deep-links-in-addons)
 - [Proxying Other Addons](#proxying-other-addons)
 - [Crawler (Scraping) Addons](#crawler--scraping-addons)
+- [Custom TypeScript Types](#custom-typescript-types)
 
 
 ## Understanding Catalogs
@@ -427,3 +428,26 @@ Scraping HTML pages presumes downloading the HTML source of a web page in order
 A guide showing a simplistic version of doing this is in the readme of the [IMDB Watchlist Addon](https://github.com/jaruba/stremio-imdb-watchlist). The addon uses [needle](https://www.npmjs.com/package/needle) to request the HTML source and [cheerio](https://www.npmjs.com/package/cheerio) to start a jQuery instance in order to simplify getting the desired information.
 
 Cheerio is not the only module that can help with crawling / scraping though, other modules that can aid in this: [jsdom](https://www.npmjs.com/package/jsdom), [xpath](https://www.npmjs.com/package/xpath), etc
+
+
+## Custom TypeScript Types
+### Config
+
+If you accept user data for your addon, you can assign your own custom configuration types to handler functions. For example:
+
+```ts
+type Config = {
+  username: string;
+  password: string;
+};
+
+// ...
+builder.defineStreamHandler<Config>(
+  async ({ id, type, config: { username, password } }) => {
+    // ^ all arguments above are properly typed
+    // ...
+  }
+);
+```
+
+See [Manifest - User Data](./api/responses/manifest.md#user-data) for more information on how to pass user data to your addon.

package.json

@@ -3,6 +3,7 @@
   "version": "1.6.10",
   "description": "An SDK for making and publishing Stremio add-ons",
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "scripts": {
     "pretest": "eslint --ignore-path .gitignore .",
     "test": "tape test/*"

src/builder.d.ts

@@ -0,0 +1,86 @@
+import { 
+    Manifest, 
+    AddonInterface, 
+    Cache, 
+    MetaPreview, 
+    MetaDetail, 
+    Stream, 
+    Subtitle, 
+    AddonCatalog, 
+    DefaultConfig,
+    CatalogHandlerArgs,
+    MetaHandlerArgs,
+    StreamHandlerArgs,
+    SubtitlesHandlerArgs,
+    AddonCatalogHandlerArgs
+} from './types';
+
+/**
+ * Creates an addon builder object with a given manifest.
+ *
+ * The manifest will determine the basic information of your addon (name, description, images), but most importantly, it will determine when and how your addon will be invoked by Stremio.
+ *
+ * Throws an error if the manifest is not valid.
+ */
+declare class addonBuilder {
+    /**
+     * Creates an addon builder object with a given manifest.
+     */
+    constructor(manifest: Manifest);
+
+    /**
+     * Handles catalog requests, including search.
+     *
+     * Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineCatalogHandler.md
+     */
+    defineCatalogHandler<Config = DefaultConfig>(handler: (args: CatalogHandlerArgs<Config>) => Promise<{ metas: MetaPreview[] } & Cache>): this;
+
+    /**
+     * Handles metadata requests (title, year, poster, background, etc.).
+     *
+     * Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineMetaHandler.md
+     */
+    defineMetaHandler<Config = DefaultConfig>(
+        handler: (args: MetaHandlerArgs<Config>) => Promise<{ meta: MetaDetail } & Cache>,
+    ): this;
+
+    /**
+     * Handles stream requests.
+     *
+     * The stream responses should be ordered from highest to lowest quality.
+     *
+     * Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineStreamHandler.md
+     */
+    defineStreamHandler<Config = DefaultConfig>(
+        handler: (args: StreamHandlerArgs<Config>) => Promise<{ streams: Stream[] } & Cache>,
+    ): this;
+
+    /**
+     * Handles subtitle requests.
+     *
+     * Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineSubtitlesHandler.md
+     */
+    defineSubtitlesHandler<Config = DefaultConfig>(
+        handler: (args: SubtitlesHandlerArgs<Config>) => Promise<{ subtitles: Subtitle[] } & Cache>,
+    ): this;
+
+    /**
+     * Handles addon catalog requests
+     *
+     * As opposed to defineCatalogHandler() which handles meta catalogs, this method handles catalogs of addon manifests.
+     * This means that an addon can be used to just pass a list of other addons that can be installed in Stremio.
+     *
+     * Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineResourceHandler.md
+     */
+    defineResourceHandler<Config = DefaultConfig>(resource: string, handler: (args: AddonCatalogHandlerArgs<Config>) => Promise<{ addons: AddonCatalog[] } & Cache>): this;
+
+    /**
+     * Turns the addon into an addonInterface, which is an immutable (frozen) object that has {manifest, get} where:
+     *
+     * * manifest is a regular manifest object
+     * * get is a function that takes one argument of the form { resource, type, id, extra } and returns a Promise
+     */
+    getInterface(): AddonInterface;
+}
+
+export = addonBuilder;

src/getRouter.d.ts

@@ -0,0 +1,8 @@
+import { AddonInterface } from './types';
+
+/**
+ * Turns the addonInterface into an express router that serves the addon according to the protocol and a landing page on the root (/).
+ */
+declare function getRouter(addonInterface: AddonInterface): any;
+
+export = getRouter;

src/index.d.ts

@@ -0,0 +1,6 @@
+export { default as addonBuilder } from './builder';
+export { default as serveHTTP } from './serveHTTP';
+export { default as getRouter } from './getRouter';
+export { default as publishToCentral } from './publishToCentral';
+export { default as landingTemplate } from './landingTemplate';
+export * from './types';

src/index.js

@@ -3,4 +3,5 @@ module.exports = {
 	serveHTTP: require('./serveHTTP'),
 	getRouter: require('./getRouter'),
 	publishToCentral: require('./publishToCentral'),
+	landingTemplate: require('./landingTemplate'),
 }

src/landingTemplate.d.ts

@@ -0,0 +1,12 @@
+import { Manifest } from './types';
+
+/**
+ * Generates an HTML landing page for the addon.
+ * 
+ * This template creates a web page that displays the addon information and provides
+ * an installation button for Stremio. If the addon has configuration options,
+ * it will also generate a form for users to configure the addon before installation.
+ */
+declare function landingTemplate(manifest: Manifest): string;
+
+export = landingTemplate;

src/publishToCentral.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Publish your addon to the central server.
+ *
+ * This method expects a string with the url to your manifest.json file.
+ *
+ * After using this method your addon will be available in the Community Addons list in Stremio for users to install and use.
+ * Please note that your addon needs to be publicly available with a URL in order for this to happen, as local addons that are not publicly available cannot be used by other Stremio users.
+ */
+declare function publishToCentral(url: string, apiURL?: string): Promise<any>;
+
+export = publishToCentral;

src/serveHTTP.d.ts

@@ -0,0 +1,25 @@
+import { AddonInterface } from './types';
+
+/**
+ * Starts the addon server
+ *
+ * This method is also special in that it will react to certain process arguments, such as:
+ * * --launch: launches Stremio in the web browser, and automatically installs/upgrades the addon
+ * * --install: installs the addon in the desktop version of Stremio
+ */
+declare function serveHTTP(
+    addonInterface: AddonInterface,
+    options?: {
+        port?: number | undefined;
+        /**
+         * (in seconds) cacheMaxAge means the Cache-Control header being set to max-age=$cacheMaxAge
+         */
+        cacheMaxAge?: number | undefined;
+        /**
+         * Static directory to serve.
+         */
+        static?: string | undefined;
+    },
+): void;
+
+export = serveHTTP;