kriskayyal/vapordm

Vapor direct message service

VaporDM

VaporDM is a simple, yet elegant, Swift library that allows you to integrate chat system into your Vapor project.

🔧 Installation

A quick guide, step by step, about how to use this library.

1- Add VaporDM to your project

Add the following dependency to your Package.swift file:

For Pre-release version

.Package(url: "https://github.com/shial4/VaporDM.git", Version(0, 1, 0, prereleaseIdentifiers: ["alpha", "2"]))

For official release version (coming soon)

.Package(url:"https://github.com/shial4/VaporDM.git", majorVersion: 0, minor: 1)

And then make sure to regenerate your xcode project. You can use vapor xcode -y command, if you have the Vapor toolbox installed.

🚀 Usage

1 Import

It's really easy to get started with the VaporDM library! First you need to import the library, by adding this to the top of your Swift file:

import VaporDM

2 Initialize

The easiest way to setup VaporDM is to create object for example in your main.swift file. Like this:

import Vapor
import VaporDM

let drop = Droplet()
let dm = VaporDM<User>(for: drop!)

VaporDM require your User DataBase model to corespond DMParticipant protocol

extension User: DMParticipant {
    public static func directMessage(_ message: JSON, type: DMType) -> JSON? {
        if let senderId: String = try? message.extract(DMKeys.sender) {
            print(senderId)
            
        }
        return message
    }
    public static func directMessageLog(_ log: DMLog) {
        print(log.message)
        
    }
    public static func directMessageEvent(_ event: DMEvent) {
        let users: [Model] = event.users
        print(users)
    }
}

directMessageLog Indicate logs from VaporDM. If some error occure inside modul or warning VaporDM will call this method to inform you directMessageEvent This method is called when message is sent, with status success or failure. Event include as well group of users. For example if VaporDM is unable to send real time message over WebSocket calls this method to provide array of users to which message was not sent. VaporDM calls this method on message sent success and failure, distinguish it by status returned with event. Thanks to this method you are able to send Notification to offline users, of course if you want to inform them about received message.

3 Message format

VaporDM support message Type such as:

connected = "C"
disconnected = "D"
messageText = "M"
beginTyping = "B"
endTyping = "E"
readMessage = "R"

To send text message we will use type M and address it to DMRoom. Vapor Direct Message send messages to room which are dispatch to room participants. Sending Message to non existing room will create that room. DMRoom repreents group of users between messages are sent. Text message example:

{  
   "room":"a5b7c179-ff9f-41f7-a2a7-9c127b8bf1ac",
   "type":"M",
   "body":"This is a text message"
}

To work with VaporDM you will need to know how to use endpoints for creating message rooms adding/removing users and geting list of room participants.

1 Create message room

method: POST uri: /chat/room/${ROOM_ID} To create room we need send JSON with DMRoom object inside. Room require minimum uniqueid and name to be in this json.

{  
   "uniqueid":"a5b7c179-ff9f-41f7-a2a7-9c127b8bf1ac",
   "name":"Room Name"
}

However we can add participants parameter with users ids if we want to add them during room creation

{  
   "uniqueid":"a5b7c179-ff9f-41f7-a2a7-9c127b8bf1ac",
   "name":"Room Name",
   "participants":["1234567890","0987654321"]
}

2 Get room

method: GET uri: /chat/room/${ROOM_ID}

3 Add User/Users to room

method: POST uri: /chat/room/${ROOM_ID} To add users simple send JSON with single user or JSON with array of users.

4 Get room participant

method: GET uri: /chat/room/${ROOM_ID}/participant

2 Connection

To connect under WebSocket simple use this url "ws://${Your_host_and_additional_path}/chat/service/${ROOM_ID}"

⭐ Contributing

Be welcome to contribute to this project! :)

❓ Questions

You can join the Vapor slack. Or you can create an issue on GitHub.

⭐ License

This project was released under the MIT license.