ttfm-socket 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 TTFM Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# Turntable LIVE Socket Client <!-- omit in toc -->
+
+Welcome to the Turntable LIVE Socket Client! This package provides a TypeScript client to communicate with rooms on Turntable.
+
+- [Installation](#installation)
+- [Joining a Room](#joining-a-room)
+  - [Events](#events)
+    - [`serverMessage`](#servermessage)
+    - [`statefulMessage`](#statefulmessage)
+    - [`statelessMessage`](#statelessmessage)
+    - [`error`](#error)
+    - [Connection States](#connection-states)
+  - [Listening for Messages](#listening-for-messages)
+- [Actions](#actions)
+- [Messages](#messages)
+  - [Stateful Messages](#stateful-messages)
+    - [`userJoined`](#userjoined)
+    - [`userLeft`](#userleft)
+    - [`addedDj`](#addeddj)
+    - [`removedDj`](#removeddj)
+    - [`playedSong`](#playedsong)
+    - [`updatedNextSong`](#updatednextsong)
+    - [`votedOnSong`](#votedonsong)
+    - [`lookedUpSong`](#lookedupsong)
+  - [Stateless Messages](#stateless-messages)
+    - [`playedOneTimeAnimation`](#playedonetimeanimation)
+    - [`kickedFromRoom`](#kickedfromroom)
+    - [`roomReset`](#roomreset)
+- [Examples](#examples)
+- [Support](#support)
+
+## Installation
+
+```
+npm install ttfm-socket
+```
+
+## Joining a Room
+
+To join a room, you'll need to retrieve the UUID for that room using [this endpoint](https://rooms.prod.tt.fm/api/#/Rooms%20data/getRoom). Then create an instance of the `SocketClient` and run the `joinRoom` method:
+
+```ts
+import { SocketClient } from "ttfm-socket";
+
+const client = new SocketClient("https://socket.prod.tt.fm");
+const token = "{your Turntable JWT}";
+
+const { state } = await client.joinRoom(token, {
+  roomUuid: "{room uuid}",
+  password: "{optional room password}",
+});
+```
+
+Assuming you are allowed to join the room (e.g. it's not full, the password is correct, etc.), `joinRoom` will resolve with an object containing `state`, an object representing the current room state. If your join request is rejected for any reason, `joinRoom` will throw an error.
+
+### Events
+
+When the `SocketClient` receives a message broadcast from the server, it emits a corresponding event, which can be listened to.
+
+#### `serverMessage`
+
+This is emitted on all messages broadcast from the server. The value emitted here is the _full_ message object, which contains both our custom `message` as well as other values such as `messageId` and `sentAt`.
+
+#### `statefulMessage`
+
+This is emitted when the `SocketClient` receives a server message that contains `statePatch`. The value emitted here is only our [custom message](#server-messages) without any of the extra values. The type of the message is narrowed so that the listener knows that `statePatch` will exist.
+
+#### `statelessMessage`
+
+This is emitted when the `SocketClient` receives a server message that contains `params` instead of `statePatch`. The value emitted here is only our [custom message](#server-messages) without any of the extra values. The type of the message is narrowed so that the listener knows that `params` will exist.
+
+#### `error`
+
+This is when the Primus connection has an error, or when the server returns an error after trying to run an Action. The value emitted here is a `string` error message, or potentially `undefined` if there is no error message available.
+
+#### Connection States
+
+There are four possible events here: `connected`, `disconnected`, `reconnecting`, and `timeout`. These are emitted when the connection state changes. There is no value emitted with these, so the listener will have 0 arguments.
+
+### Listening for Messages
+
+Once a room has been joined, you should attach listeners to the `SocketClient` to handle incoming [messages](#mesages). To compute the state updates, we recommend the [fast-json-patch](https://www.npmjs.com/package/fast-json-patch) package.
+
+```ts
+import { applyPatch } from "fast-json-patch";
+
+client.on("statefulMessage", (message) => {
+  const newState = applyPatch(
+    prevState,
+    message.statePatch,
+    true,
+    false,
+  ).newDocument;
+  // Save the new state
+});
+
+client.on("statelessMessage", (message) => {
+  // Respond to the message based on its name and params
+});
+```
+
+Listeners can also be added for specific messages:
+
+```ts
+client.on(ServerMessageName.kickedFromRoom, () => {
+  // Clear local state and destroy the client
+});
+```
+
+## Actions
+
+When a client wants to make some sort of update to the room, it can do so with the `action` method in the `SocketClient` class. Documentation for these actions can be found [here](https://socket.prod.tt.fm/swagger.html). For example, to take the stage in a room a client would run the `addDj` action:
+
+```ts
+client.action<AddDjAction>(ActionName.addDj, { song: { ... } })
+```
+
+In this case, `song` is optional but should match the type [MinimalCrateSongResDTO](https://playlists.prod.tt.fm/api/#model-MinimalCrateSongResDTO).
+
+## Messages
+
+After a client or the server successfully runs an action in a room, the server will broadcast a message to every client connected to that room, including the one that ran the Action. As a convention, the names of these messages take the past-tense form of the name of the Action that spawned them. For example, the `addDj` Action correlates to the `addedDj` server message.
+
+### Stateful Messages
+
+Most of the messages sent by the server come after some sort of room state update. For these, the message will take this shape:
+
+```ts
+{
+  name: StatefulServerMessageNameType;
+  statePatch: Operation[];
+}
+```
+
+`statePatch` is a JSON-encoded series of operations for the client to perform in order to update its local state to stay in sync with the server. This adheres the [JSON Patch](https://jsonpatch.com/) format.
+
+These are all of the stateful messages:
+
+#### `userJoined`
+
+Sent by the server to all clients when a user joins the room. This comes after a client successfully runs the `joinRoom` Action and is added to the Actoinhero `chatRoom`.
+
+#### `userLeft`
+
+Sent by the server to all clients when a user leaves the room. When a client sends the Actionhero `roomLeave` message, or when its connection is closed, we enqueue a 20-second delayed Task. If the user has no active connections after that delay, the server will broadcast this `userLeft` message.
+
+#### `addedDj`
+
+Sent by the server to all clients when a user has been successfully added to the DJ lineup. This comes after a client runs the `addDj` Action.
+
+#### `removedDj`
+
+Sent by the server to all clients when a user has been successfully removed from the DJ lineup. This comes after a client or server runs the `removeDj` Action.
+
+#### `playedSong`
+
+Sent by the server to all clients when `nowPlaying` changes. This can be triggered by add/removing DJs, skips, kicks, bans, and the current song ending. This same message is sent when there is no next song to play, in which case `nowPlaying` will be `null`. The only Action that broadcasts this message is `playSong`.
+
+#### `updatedNextSong`
+
+Sent by the server to all clients when a DJ updates their next song via the `updateNextSong` Action. This _might_ be followed by the `playedSong` message, but only if a DJ sends a non-`null` song and there isn't already something playing.
+
+#### `votedOnSong`
+
+Sent by the server to all clients when a user updates their song votes via the `voteOnSong` Action. This currently handles likes/dislikes and stars. The client state will have per-user voting information, as well as a computed `vibeMeter` value and an `allVotes` object that contains arrays of user UUIDs for each type of vote.
+
+#### `lookedUpSong`
+
+Sent by the server to all clients after a successful song lookup. This happens if a client sends a song placeholder with the `addDj` or `updateNextSong` Actions. It's unlikely the clients will need to do anything in response to this message, but it exists to keep the client state in sync with the server state to avoid errors on subsequent patches.
+
+### Stateless Messages
+
+If a message does not accompany a room state update, the shape is slightly different:
+
+```ts
+{
+  name: StatelessServerMessageNameType;
+  params?: StatelessServerMessageParams;
+}
+```
+
+These are all of the stateless messasges:
+
+#### `playedOneTimeAnimation`
+
+Sent by the server to all clients when a user sends a one-time animation. For this message, `params` takes the following shape:
+
+```ts
+{
+  userUuid: string;
+  animation: OneTimeAnimationType;
+  emoji?: string;
+}
+```
+
+`emoji` here is only defined if `animation` is `OneTimeAnimation.emoji`, and will only ever be a string with a single emoji character in it.
+
+#### `kickedFromRoom`
+
+Sent by the server _only_ to the connection(s) for one specific user in a room. This indicates that the user was just kicked (or banned). Immediately following this message, the server will close the connection. This message has no `params`.
+
+#### `roomReset`
+
+Sent by the server after someone hits the `/resetRoom` endpoint for that room. This means that the room's state will be cleared and the server will close all connections that are currenly in the room. In response to this, the clients will need to open a new connection and rejoin the room via the `joinRoom` Action. This message has no `params`.
+
+## Examples
+
+- [Discord Bot](https://github.com/TTFM-Labs/TTLIVE-discord-bot)
+
+## Support
+
+If you have any questions or feedback about this package, please reach out to us on [Discord](https://discord.gg/kvAhYavVtW) or at help@turntabletlive.com.

package/dist-client/actions/addDj.d.ts

@@ -0,0 +1,26 @@
+import { Action, ParamsFrom } from "actionhero";
+import { ActionName, MiddlewareName } from "../types/names";
+export declare class AddDjAction extends Action {
+    name: ActionName.addDj;
+    description: string;
+    inputs: {
+        userUuid: {
+            required: true;
+        };
+        roomUuid: {
+            required: true;
+        };
+        tokenRole: {
+            required: true;
+            formatter: (tokenRole: import("../client").TokenRole) => import("../client").TokenRole;
+        };
+        song: {
+            formatter: (song: import("../client").MinimalCrateSongResDTO) => import("../client").MinimalCrateSongResDTO;
+            description: string;
+        };
+    };
+    middleware: MiddlewareName[];
+    run({ params: { roomUuid, userUuid, tokenRole, song }, }: {
+        params: ParamsFrom<AddDjAction>;
+    }): Promise<import("../types/state").ServerRoomState>;
+}

package/dist-client/actions/joinRoom.d.ts

@@ -0,0 +1,27 @@
+import { Action, ParamsFrom, Connection } from "actionhero";
+import { ActionName } from "../types/names";
+export declare class JoinRoomAction extends Action {
+    name: ActionName.joinRoom;
+    description: string;
+    inputs: {
+        roomUuid: {
+            required: true;
+        };
+        password: {
+            description: string;
+        };
+        guestPassword: {
+            description: string;
+        };
+    };
+    run({ params: { roomUuid, password, guestPassword }, connection, }: {
+        params: ParamsFrom<JoinRoomAction>;
+        connection: Connection;
+    }): Promise<{
+        roomUuid: string;
+        allowedRooms: string[];
+        didCreate: boolean;
+        state: import("../client").RoomState;
+        serverTime: number;
+    }>;
+}

package/dist-client/actions/playOneTimeAnimation.d.ts

@@ -0,0 +1,31 @@
+import { Action, ParamsFrom } from "actionhero";
+import { ActionName, MiddlewareName } from "../types/names";
+import { OneTimeAnimationType } from "../types/messages";
+export declare class PlayOneTimeAnimationAction extends Action {
+    name: ActionName.playOneTimeAnimation;
+    description: string;
+    inputs: {
+        roomUuid: {
+            required: true;
+        };
+        userUuid: {
+            required: true;
+        };
+        animation: {
+            required: true;
+            formatter: (animation: OneTimeAnimationType) => OneTimeAnimationType;
+            validator: (animation: OneTimeAnimationType) => void;
+            description: string;
+        };
+        emoji: {
+            validator: (emojiString: string) => void;
+            description: string;
+        };
+    };
+    middleware: MiddlewareName[];
+    private animationValidator;
+    private emojiValidator;
+    run({ params: { roomUuid, userUuid, animation, emoji }, }: {
+        params: ParamsFrom<PlayOneTimeAnimationAction>;
+    }): Promise<void>;
+}

package/dist-client/actions/removeDj.d.ts

@@ -0,0 +1,26 @@
+import { Action, ParamsFrom } from "actionhero";
+import { ActionName, MiddlewareName } from "../types/names";
+import { ServerRoomState } from "../types/state";
+export declare class RemoveDjAction extends Action {
+    name: ActionName.removeDj;
+    description: string;
+    inputs: {
+        userUuid: {
+            required: true;
+            description: string;
+        };
+        roomUuid: {
+            required: true;
+        };
+        tokenRole: {
+            formatter: (tokenRole: import("../client").TokenRole) => import("../client").TokenRole;
+        };
+        djUuid: {
+            description: string;
+        };
+    };
+    middleware: MiddlewareName[];
+    run({ params: { roomUuid, userUuid, tokenRole, djUuid }, }: {
+        params: ParamsFrom<RemoveDjAction>;
+    }): Promise<ServerRoomState>;
+}

package/dist-client/actions/skipSong.d.ts

@@ -0,0 +1,22 @@
+import { Action, ParamsFrom } from "actionhero";
+import { ActionName, MiddlewareName } from "../types/names";
+export declare class SkipSongAction extends Action {
+    name: ActionName.skipSong;
+    description: string;
+    inputs: {
+        roomUuid: {
+            required: true;
+        };
+        tokenRole: {
+            required: true;
+            formatter: (tokenRole: import("../client").TokenRole) => import("../client").TokenRole;
+        };
+        userUuid: {
+            required: true;
+        };
+    };
+    middleware: MiddlewareName[];
+    run({ params: { roomUuid, userUuid, tokenRole }, }: {
+        params: ParamsFrom<SkipSongAction>;
+    }): Promise<void>;
+}

package/dist-client/actions/updateNextSong.d.ts

@@ -0,0 +1,22 @@
+import { Action, ParamsFrom } from "actionhero";
+import { ActionName, MiddlewareName } from "../types/names";
+export declare class UpdateNextSongAction extends Action {
+    name: ActionName.updateNextSong;
+    description: string;
+    inputs: {
+        roomUuid: {
+            required: true;
+        };
+        userUuid: {
+            required: true;
+        };
+        song: {
+            formatter: (song: import("../client").MinimalCrateSongResDTO | null) => import("../client").MinimalCrateSongResDTO | null;
+            description: string;
+        };
+    };
+    middleware: MiddlewareName[];
+    run({ params: { roomUuid, userUuid, song }, }: {
+        params: ParamsFrom<UpdateNextSongAction>;
+    }): Promise<import("../types/state").ServerRoomState>;
+}

package/dist-client/actions/voteOnSong.d.ts

@@ -0,0 +1,27 @@
+import { Action, ParamsFrom } from "actionhero";
+import { ActionName, MiddlewareName } from "../types/names";
+import { SongVotes } from "../types/state";
+export declare class VoteOnSongAction extends Action {
+    name: ActionName.voteOnSong;
+    description: string;
+    inputs: {
+        roomUuid: {
+            required: true;
+        };
+        userUuid: {
+            required: true;
+        };
+        songVotes: {
+            required: true;
+            formatter: (voteParams: Partial<SongVotes>) => Partial<SongVotes>;
+            validator: (songVotes: Partial<SongVotes>) => void;
+            description: string;
+        };
+    };
+    middleware: MiddlewareName[];
+    private songVotesValidator;
+    private areVotesTheSame;
+    run({ params: { roomUuid, userUuid, songVotes }, }: {
+        params: ParamsFrom<VoteOnSongAction>;
+    }): Promise<import("../types/state").ServerRoomState | undefined>;
+}