WATCHED.com SDK and tools

This monorepo includes all javascript modules needed to create addons for WATCHED.

Getting started

In best way to create your own WATCHED addon is by cloning our example addon and modify it.

Prerequisites

• nodejs installed on your computer
• A text editor of your choice. Preferred are vscode, atom or Sublime Text
• Basic knowledge in Javascript or Typescript

Cloning the example addon

The best way to start is to clone our watched-addon-example addon:

git clone https://github.com/watchedcom/watched-addon-example.git my-addon

Now open the created folder my-addon with your editor.

Running the addon

Without any modifications, let's start the addon and see what will happen.

1. Start the addon server

Open your terminal, change to the my-addon folder and run:

npm run develop

You should see something like this:

> [email protected] develop /home/myname/my-addon
> ts-node-dev --transpileOnly src

Using ts-node version 8.9.1, typescript version 3.8.3
Using cache: MemoryCache
Mounting addon example
Listening on 3000

2. Enable developer mode

In order to install addons in the WATCHED app, you first need to unlock it:

1. Open the WATCHED app, go to settings and make sure the Developer mode is enabled.
2. Go to the addon manager and deactivate the bundle addon if there is one active.
3. To make things more clean and easy, disabled all currently activated addons.

3. Add your addon

1. Find the local IP of your computer. (TODO: Tutorial on how to do this on different OS)
2. Go to the Add Addon screen, where you can enter an URL.
3. Enter the IP address of your computer. For example 192.168.1.123. On local IP addresses, the port 3000 as well as some other default ports are omitted, so it's enough to only enter your IP.

Go to the start screen and you should see a dashboard of your addon.

Modify your addon

Open the src/index.ts file in your editor and start playing around. The server will restart automatically once you saved a file.

To reload for screens in the app, swipe down until a refresh symbol appears. After the refresh your changes should appear.

When you change the metadata of your addon (like addin a new item or source handler, or adding new item types to your addon), you need to refresh the addon. To do this, go to the addon manager, click on it (I) symbol on the right side of your addon. Within the "addon detail screen", swipe down to refreh your addon.

Documentation

Much of our documentation is in our code. Depending on your editor you should see much of the documentation while writing or when hovering a variable or function.

Please also check out our object schema here: https://www.watched.com/swagger

Publish and rename

• Before renaming the ID of your addon, you should deactivate and delete it from the app.

• Edit the name and addon ID in package.json and src/index.ts.

• Delete all unnecessary action handlers.

Deploy your addon

Please check our deployment documentation at docs/deployment.md.

Tips for development and testing

We created some tools to make the development of addons more easy.

Record and replay requests

Start your development server in the following way:

npm run develop -- --record test-session

This will create a file named test-session.record.js in the current directory. Now load your addon in the app and open directories, items or load sources. In the terminal, you should see some log messages regarding recording.

To replay your recording, run this command:

npm run develop -- replay test-session

To reply and watch for changes, use this:

npm run develop -- replay test-session --watch

Create a test case with a recorded session

Create a test case file, for example src/record.test.ts:

import { replayRecordFile } from "@watchedcom/sdk";
import { yourAddon } from "./index";

test(`Replay recorded actions`, (done) => {
  replayRecordFile([yourAddon], "test-session.record.js")
    .then(done)
    .catch(done);
});

Now run the tests:

npm test

Cache

We offer a very flexible caching solution for your addon. Please see docs/caching.md for more infos.

Translate your addon

For some suggestions regarding translations, please see either our @watchedcom/i18n package found inside packages/i18n, or the documentation at docs/translations.md.

Developing on this repo

Clone this repo and bootstrap it with lerna:

npx lerna bootstrap --hoist