IMDb Collaboration Bot

The previous story, Introducing the Circuit APIs, described the different Circuit APIs and then walked through a client-side web app which uses the Circuit JavaScript SDK for chatting.

This story enhances the IMDb Collaboration app with a server-side bot. Source code is available on github and the new live app is here.

In summary the enhancements are:

• Search movie database rather than four predefined shows
• Show post for unauthenticated users
• Dynamically create corresponding Circuit conversation
• Dynamically add user to conversation
• Use webpack 2 to build and package
• Remove lit-html-element dependency and use lit-html directly
• … and rewrite most of the client app

For the first 4 bullets above a server-side Node.js application is used. This server-side application serves two main purposes:

1. Proxy requests to the movie API (OMDb API) to overcome the limitation of the OMDb API not supporting SSL.
2. Circuit Bot to
   - Lookup corresponding conversation
   - Create of conversation
   - Add user as conversation member
   - Fetch posts for unauthenticated users

Application flow

Searching for movies and TV shows is done via the new imdb-search web component. This component shows an input field with search results. Requests are sent to the server application and proxied to the OMDb API.

Search page

Selecting a movie routes to a new page which displays the movie details together with the Circuit chat.

At this time the server-side application, which authenticated to Circuit as bot (Client Credentials grant), looks up the Circuit conversation corresponding to the movie. If conversation does not exists yet, the bot creates one. And if the user is signed in, the user is added as member of this conversation.

The circuit-chat web component then requests the posts for this conversation. Fetching the posts is done via the bot so that unauthenticated users can view the posts as well.

Movie page viewed as authenticated user

Unauthenticated users are asked to authenticated via OAuth 2.0 and accept the permissions when trying to post a message.

Recently signed in users are automatically signed in.

Bot application

As mentioned above the server-side bot application is written in Node.js and uses the Circuit Node.js SDK to act as a bot. The bot is a member of any IMDb conversation (actually even creator) and therefore able to add other participants to the conversation.

The bot provides the following endpoints.

/find/:imdb endpoint

This endpoint is the most complicated. It uses the startBasicSearch API with CONVERSATION scope to find the conversation by it’s name. The conversations are named IMDB: <imdb ID>. Search results are raised via events basicSearchResults and searchStatus.

/join/:conv/:user endpoint

This endpoint is called for authenticated users when visiting a new movie page, or signing in while on a movie page. Calling this endpoint adds the user to the conversation which thens allow the user to post messages and see the avatars of other users.

/posts/:conv endpoint

This endpoint fetches the 50 most recent posts of a conversation. Paging is supported by the Circuit SDK, but not implemented here for simplicity.

The posts only contain the creatorId, not the complete user object. The code below identifies the unique creators (authors of the posts) and uses the getUsersById API to fetch their user objects. The client-side app only needs the avatar and displayName attributes, so these attributes are copied to the post objects.

/user/:userId endpoint

This endpoint fetches a user object by its userId. It is used when a new post is added by somebody else, while on the same page. The Circuit SDK event itemAdded contains the post with the creatorId only, not the user object. So using this endpoint the client is able to get the avatar and displayName.

The users variable is a cache of user objects and reduces the need to fetch the user from Circuit. Ideally this app would periodically check if the avatar or display name of the cached users have changed.

/search/:query and /details/:idendpoints

These endpoint are used to search for movies and get movie details from the OMDb API. The endpoints are straight forwards and unrelated to the Circuit SDK, so not shown here in detail.

Updated client-side application

The app, imdb-header and circuit-chat web components remain, but are mostly rewritten to utilize the new endpoints provided by the bot. They also don’t depend on lit-html-element anymore, and instead use lit-html’s lit-extended directly.

A new component imdb-search has been added to show an input field to search for movies and display the results. This component does not use the Circuit SDK, so we won’t go into details.

Build and package using webpack

webpack is a module bundler, but is capable of much more. In this application its used to transpile ES6 code to older browsers using babel, find dependencies, bundle JavaScript files, use of Hot Module Replacement and webpack-dev-server and packing for production.

I plan to write a follow up post with:

1. Ad-hoc audio/video conference calls for users on the same movie page
2. Enhance the bot with AI to answer simple questions in the chat
3. Show analytics as to what are the most searched movies, most comments, etc

Let me know in the comments which of those enhancements you’d like to see in the next article, or any other enhancement you’d like to see.