From 51a23a7f788dff62396338cf2838dd36c37f56a1 Mon Sep 17 00:00:00 2001
From: Friedrich von Never <friedrich@fornever.me>
Date: Tue, 30 Jul 2019 23:53:10 +0700
Subject: [PATCH] Update the async XMPP API proposal (#18)

---
 Emulsion/Xmpp/AsyncXmppClient.fs | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/Emulsion/Xmpp/AsyncXmppClient.fs b/Emulsion/Xmpp/AsyncXmppClient.fs
index 09d6db74..f031f8e9 100644
--- a/Emulsion/Xmpp/AsyncXmppClient.fs
+++ b/Emulsion/Xmpp/AsyncXmppClient.fs
@@ -1,4 +1,5 @@
 module Emulsion.Xmpp.AsyncXmppClient
+
 open System.Security
 open System.Threading
 
@@ -12,8 +13,10 @@ type SignInInfo = {
     Password: SecureString
 }
 
+type Jid = string
+
 type RoomInfo = {
-    RoomJid: string
+    RoomJid: Jid
     Nickname: string
 }
 
@@ -21,12 +24,26 @@ type MessageInfo = {
     RecipientJid: string
     Text: string
 }
+type MessageDeliveryInfo = Async<unit> // Resolves after the message is guaranteed to be delivered to the recipient.
 
 type Lifetime = CancellationToken // TODO[F]: Determine a proper lifetime?
 
 type IAsyncXmppClient =
-    abstract member Connect : ServerInfo -> Async<unit>
-    abstract member SignIn : SignInInfo -> Async<unit>
+    /// Establish a connection to the server. Returns a connection lifetime that will terminate if the connection
+    /// terminates.
+    abstract member Connect : ServerInfo -> Async<Lifetime>
+
+    /// Sign in with the provided credentials. Returns a session lifetime that will terminate if the session terminates.
+    abstract member SignIn : SignInInfo -> Async<Lifetime>
+
+    /// Enter the room, returning the in-room lifetime. Will terminate if kicked or left the room.
     abstract member EnterRoom : RoomInfo -> Async<Lifetime>
-    abstract member SendMessage : Lifetime -> MessageInfo -> Async<unit>
+
+    /// Sends the message to the room.
+    abstract member SendMessage : MessageInfo -> Async<MessageDeliveryInfo>
+
+    /// Waits for the message to be delivered.
+    abstract member AwaitMessageDelivery : MessageDeliveryInfo -> Async<unit>
+
+    /// Disconnects from the server (if connected) and frees all the resources associated with the client.
     abstract member DisposeAsync : unit -> Async<unit>