-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Bindings for signal-cli's DBus interface
--   
--   This library aims provides a way to interact programmatically with the
--   private messenger signal <a>https://signal.org/</a>. To use this, you
--   need an instance of <a>signal-cli</a> running in daemon mode, with the
--   DBus interface enabled. Support exists for almost the whole api, which
--   should be sufficient for your bot-writing needs.
@package signal-messaging-dbus
@version 1.0.1.0


-- | This module contains types used by this package. Please import
--   SignalDBus instead.
module SignalDBus.Types

-- | Opaque connection object, aquired by <a>withConn</a> or
--   <a>withConnNum</a>
data SignalConn
SignalConn :: !ObjectPath -> !Client -> SignalConn

-- | Timestamp, represented as an ms-precision unix timestamp
data Timestamp

-- | Opaque object representing a linked device
newtype Device
Device :: Int64 -> Device

-- | Opaque Group object, aquired by <a>listGroups</a> or <a>getGroup</a>
newtype Group
Group :: ObjectPath -> Group

-- | Received message
data ReceivedMessage

-- | Message sent by a linked device to someone else
SyncMessage :: Timestamp -> String -> Maybe Group -> String -> [String] -> ReceivedMessage

-- | Read receipt sent by someone else in response to one of your messages
Receipt :: Timestamp -> String -> ReceivedMessage

-- | Message sent to you by someone else
Message :: Timestamp -> String -> Maybe Group -> String -> [String] -> ReceivedMessage

-- | Conversion to <a>UTCTime</a>. This retains precision, so converting
--   back-and-forth is unproblematic.
toUTCTime :: Timestamp -> UTCTime

-- | Conversion from <a>UTCTime</a>. This retains precision, so converting
--   back-and-forth is unproblematic.
fromUTCTime :: UTCTime -> Timestamp
instance DBus.Internal.Types.IsValue SignalDBus.Types.Timestamp
instance DBus.Internal.Types.IsVariant SignalDBus.Types.Timestamp
instance GHC.Classes.Ord SignalDBus.Types.Timestamp
instance GHC.Classes.Eq SignalDBus.Types.Timestamp
instance GHC.Read.Read SignalDBus.Types.Timestamp
instance GHC.Show.Show SignalDBus.Types.Timestamp
instance DBus.Internal.Types.IsValue SignalDBus.Types.Device
instance DBus.Internal.Types.IsVariant SignalDBus.Types.Device
instance GHC.Classes.Eq SignalDBus.Types.Device
instance GHC.Read.Read SignalDBus.Types.Device
instance GHC.Show.Show SignalDBus.Types.Device
instance DBus.Internal.Types.IsValue SignalDBus.Types.Group
instance DBus.Internal.Types.IsVariant SignalDBus.Types.Group
instance GHC.Classes.Ord SignalDBus.Types.Group
instance GHC.Classes.Eq SignalDBus.Types.Group
instance GHC.Read.Read SignalDBus.Types.Group
instance GHC.Show.Show SignalDBus.Types.Group
instance GHC.Classes.Ord SignalDBus.Types.ReceivedMessage
instance GHC.Classes.Eq SignalDBus.Types.ReceivedMessage
instance GHC.Read.Read SignalDBus.Types.ReceivedMessage
instance GHC.Show.Show SignalDBus.Types.ReceivedMessage
instance GHC.Read.Read DBus.Internal.Types.ObjectPath


-- | Except for things reexported elsewhere, this module is mainly meant
--   for internal usage. However, if you require APIs not implemented by
--   the main module, you may use these functions to implement them.
module SignalDBus.Interface

-- | Run an action that requires a signal connection, and return its result
withConn :: MonadUnliftIO m => (SignalConn -> m a) -> m a

-- | Like <a>withConn</a>, but you have to manually specify a phone number
--   to use, which is useful if the signal daemon doesn't have a default
--   number. This may not be used with a signal-cli daemon that has a
--   default number configured.
withConnNum :: MonadUnliftIO m => String -> (SignalConn -> m a) -> m a

-- | Run an action that receives a callback to receive new messages, and
--   return its result. This will <i>not</i> yield messages that were
--   received prior to calling this.
withReceiveMessages :: MonadUnliftIO m => SignalConn -> (m ReceivedMessage -> m a) -> m a

-- | INTERNAL. Call method from the main Signal interface, and return its
--   result.
callSC :: (MonadIO m, IsVariant a) => MemberName -> [Variant] -> SignalConn -> m a

-- | INTERNAL. Call method from the main Signal interface, expecting no
--   return value.
callSC_ :: MonadIO m => MemberName -> [Variant] -> SignalConn -> m ()

-- | INTERNAL. Call method from the Signal.Control interface, and return
--   its result.
callControl :: (MonadIO m, IsVariant a) => MemberName -> [Variant] -> SignalConn -> m a

-- | INTERNAL. Call method from the Signal.Control interface, expecting no
--   return value.
callControl_ :: MonadIO m => MemberName -> [Variant] -> SignalConn -> m ()

-- | INTERNAL. Get group proptery
getGroupProp :: (MonadIO m, IsValue a) => MemberName -> Group -> SignalConn -> m a

-- | INTERNAL. Set group proptery
setGroupProp :: (MonadIO m, IsValue a) => MemberName -> a -> Group -> SignalConn -> m ()

-- | INTERNAL. Call method from the Signal.Group interface, expecting no
--   return value.
callGroup_ :: MonadIO m => MemberName -> [Variant] -> Group -> SignalConn -> m ()


-- | This module is the main entry point for this library.
--   
--   To get started, install and set up <a>signal-cli</a>, and make sure
--   it's running in daemon mode, with the dbus interface enabled. Then, as
--   an example, you could use the following code to react with "💀" to
--   every message received from a specific user either via PM or in groups
--   you're a member of:
--   
--   <pre>
--   import Control.Monad (forever, when)
--   import SignalDBus
--   
--   reactWithSkull :: Timestamp -&gt; String -&gt; Maybe Group -&gt; SignalConn -&gt; IO Timestamp
--   reactWithSkull ts n mayG sc =
--       case mayG of
--           Nothing -&gt; sendMessageReaction "💀" False n ts n sc
--           Just g -&gt; sendGroupMessageReaction "💀" False n ts g sc
--   
--   -- react with 💀 to every message received by a specific user
--   main :: IO ()
--   main = do
--       let num = "[insert phone number with country code]"
--       withConn $ \sc -&gt; do
--           n &lt;- getSelfNumber sc
--           putStrLn $ "Running on: " ++ show n
--           withReceiveMessages sc $ \getMsg -&gt; forever $ do
--               getMsg &gt;&gt;= \case
--                   Receipt _ _ -&gt; return ()
--                   SyncMessage _ _ _ _ _ -&gt; return ()
--                   Message ts n g _ _ -&gt; when (n == num) $ do
--                       reactWithSkull ts num g sc
--                       return ()
--   
--       return ()
--   </pre>
--   
--   All of the functions exported may fail with a <a>ClientError</a> if
--   something goes wrong. None of the functions should throw any other
--   exception.
--   
--   Quite a few of these functions have a scary-looking "UNTESTED" in
--   their documentation. If you end up using any of those, and they work,
--   please tell me so I can remove that disclaimer.
--   
--   This package aims to provide somewhat direct bindings for all methods
--   described by
--   <a>https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc</a>.
--   In cases where methods are overloaded, this library almost always
--   chooses to implement the more general ones. Some functionality of the
--   dbus interface of signal-cli isn't implemented, as it's either not
--   documented or not often useful; if you require any of that, I'd
--   recommend looking at SignalDBus.Interface.
module SignalDBus

-- | Run an action that requires a signal connection, and return its result
withConn :: MonadUnliftIO m => (SignalConn -> m a) -> m a

-- | Like <a>withConn</a>, but you have to manually specify a phone number
--   to use, which is useful if the signal daemon doesn't have a default
--   number. This may not be used with a signal-cli daemon that has a
--   default number configured.
withConnNum :: MonadUnliftIO m => String -> (SignalConn -> m a) -> m a

-- | Run an action that receives a callback to receive new messages, and
--   return its result. This will <i>not</i> yield messages that were
--   received prior to calling this.
withReceiveMessages :: MonadUnliftIO m => SignalConn -> (m ReceivedMessage -> m a) -> m a

-- | Utility function for reacting to a received message
reactTo :: MonadIO m => ReceivedMessage -> String -> Bool -> SignalConn -> m Timestamp

-- | Utility function for sending a message in the same chat as you
--   received a message from
replyTo :: MonadIO m => ReceivedMessage -> String -> [String] -> SignalConn -> m Timestamp

-- | UNTESTED. Link this as a new device, identified by the given string.
link :: MonadIO m => String -> SignalConn -> m String

-- | List accounts attached to this signal-cli instance
listAccounts :: MonadIO m => SignalConn -> m [String]

-- | UNTESTED. Register this as the primary device for the given number.
--   Set the second argument to <a>True</a> to request voice verification
--   instead of SMS verification.
register :: MonadIO m => String -> Bool -> SignalConn -> m ()

-- | UNTESTED. Same as <a>register</a>, but include a Captcha string.
registerWithCaptcha :: MonadIO m => String -> Bool -> String -> SignalConn -> m ()

-- | UNTESTED. Verify your phone number after requesting registration via
--   <a>register</a> or <a>registerWithCaptcha</a>
verify :: MonadIO m => String -> String -> SignalConn -> m ()

-- | UNTESTED. Same as <a>verify</a>, but include a registration pin for
--   protected accounts
verifyWithPin :: MonadIO m => String -> String -> String -> SignalConn -> m ()

-- | Takes a number, and returns the name of the contact, empty if unknown
getContactName :: MonadIO m => String -> SignalConn -> m String

-- | Takes a contact name, and returns known numbers, both as strings
getContactNumber :: MonadIO m => String -> SignalConn -> m [String]

-- | Returns your own number
getSelfNumber :: MonadIO m => SignalConn -> m String

-- | Returns true if you blocked this number
isContactBlocked :: MonadIO m => String -> SignalConn -> m Bool

-- | For each given number, returns whether that user is registered on
--   Signal
isRegistered :: MonadIO m => [String] -> SignalConn -> m [Bool]

-- | List all known numbers (e.g. group members and senders of received
--   messages)
listNumbers :: MonadIO m => SignalConn -> m [String]

-- | UNTESTED. Removes registration pin protection.
removePin :: MonadIO m => SignalConn -> m ()

-- | UNTESTED. No idea what this accomplishes, so hmu if you know. It's
--   implemented though
sendEndSessionMessage :: MonadIO m => SignalConn -> m ()

-- | Sends a message, possibly with attachments, to a number of recipients
sendMessage :: MonadIO m => String -> [String] -> [String] -> SignalConn -> m Timestamp

-- | Reacts to a message
sendMessageReaction :: MonadIO m => String -> Bool -> String -> Timestamp -> String -> SignalConn -> m Timestamp

-- | Sends a message to yourself
sendNoteToSelfMessage :: MonadIO m => String -> [String] -> SignalConn -> m Timestamp

-- | Sends read receipts for the messages with the specified timestamps to
--   the given phone number. These timestamps must belong to messages you
--   received from that number.
sendReadReceipt :: MonadIO m => String -> [Timestamp] -> SignalConn -> m ()

-- | Sends viewed receipts for the messages with the specified timestamps
--   to the given phone number. This is probably not what you want;
--   <a>sendReadReceipt</a> seems to be the way to go.
sendViewedReceipt :: MonadIO m => String -> [Timestamp] -> SignalConn -> m ()

-- | Delete one of you own private messages; also deletes them remotely on
--   supported clients (Signal-desktop, Android/IOS apps, ...)
sendRemoteDeleteMessage :: MonadIO m => Timestamp -> [String] -> SignalConn -> m Timestamp

-- | Send updates about whether you're typing to the given number. NOTE:
--   the boolean argument should be False to indicate you're typing, and
--   True to clear the typing state
sendTyping :: MonadIO m => String -> Bool -> SignalConn -> m ()

-- | UNTESTED. Sets whether a contact is blocked. This is only done
--   locally, so this just disabled messages from that number from being
--   forwarded via DBus.
setContactBlocked :: MonadIO m => String -> Bool -> SignalConn -> m ()

-- | Not implemented, as the documentation doesn't state the type of the
--   name (probably a String, but I dont feel like testing stuff rn)
setContactName :: a

-- | UNTESTED. Probably deletes a contact, given by a phone number, or
--   something.
deleteContact :: MonadIO m => String -> SignalConn -> m ()

-- | UNTESTED. Idk what this does, but tell me if you know/have used this.
deleteRecipient :: MonadIO m => String -> SignalConn -> m ()

-- | Set seconds until messages to this recipient dissapear (on supported
--   clients). Set to 0 to disable.
setExpirationTimer :: (MonadIO m, Integral i) => String -> i -> SignalConn -> m ()

-- | UNTESTED. Set registration pin to prevent others from registering your
--   number.
setPin :: MonadIO m => String -> SignalConn -> m ()

-- | UNTESTED. Idk but seems to be useful for lifting rate limits
submitRateLimitChallenge :: MonadIO m => String -> String -> SignalConn -> m ()

-- | Update parts of your profile. You can leave any string field empty to
--   keep the old value.
updateProfile :: MonadIO m => String -> String -> String -> String -> String -> Bool -> SignalConn -> m ()

-- | UNTESTED. Uploads a sticker pack, given by the path to a manifest.json
--   or zip file, and return the URL of the pack.
uploadStickerPack :: MonadIO m => String -> SignalConn -> m String

-- | Return version string of signal-cli. This also works for multi-account
--   connections.
version :: MonadIO m => SignalConn -> m String

-- | Create a group
createGroup :: MonadIO m => String -> [String] -> String -> SignalConn -> m Group

-- | Get DBus object path for a group, given by its signal-internal binary
--   identifier.
getGroup :: MonadIO m => ByteString -> SignalConn -> m Group

-- | UNTESTED. Join a group given by an invite link. Behaviour of this
--   depends on properties of the group; see "joinGroup" on
--   <a>https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc</a>
--   (latest commit while writing this:
--   34cc64f8ce97a63c859bd95faf6783422f14df61)
joinGroup :: MonadIO m => String -> SignalConn -> m ()

-- | List known groups, represented as (group object, internal identifier,
--   group name)
listGroups :: MonadIO m => SignalConn -> m [(Group, ByteString, String)]

-- | Sends a message, possibly with attachments, to a group
sendGroupMessage :: MonadIO m => String -> [String] -> Group -> SignalConn -> m Timestamp

-- | Send updates about whether you're typing to the given group. NOTE: the
--   boolean argument should be False to indicate you're typing, and True
--   to clear the typing state
sendGroupTyping :: MonadIO m => Group -> Bool -> SignalConn -> m ()

-- | Reacts to a message
sendGroupMessageReaction :: MonadIO m => String -> Bool -> String -> Timestamp -> Group -> SignalConn -> m Timestamp

-- | Delete one of you own group messages; also deletes them remotely on
--   supported clients (Signal-desktop, Android/IOS apps, ...)
sendGroupRemoteDeleteMessage :: MonadIO m => Timestamp -> Group -> SignalConn -> m Timestamp

-- | UNTESTED. Add a device that wants to link to this account using a link
addDevice :: MonadIO m => String -> SignalConn -> m ()

-- | Get DBus object path for a device given by a device ID
getDevice :: MonadIO m => Int64 -> SignalConn -> m ObjectPath

-- | List devices linked with this account, represented as (object path,
--   device id, device name)
listDevices :: MonadIO m => SignalConn -> m [(ObjectPath, Int64, String)]

-- | Byte array representing the internal group identifier
getGroupId :: MonadIO m => Group -> SignalConn -> m ByteString

-- | Display name
getGroupName :: MonadIO m => Group -> SignalConn -> m String

-- | Description
getGroupDescription :: MonadIO m => Group -> SignalConn -> m String

-- | UNTESTED. If true, messages won't be forwarded via DBus
getGroupIsBlocked :: MonadIO m => Group -> SignalConn -> m Bool

-- | Whether this account is a group admin
getGroupIsAdmin :: MonadIO m => Group -> SignalConn -> m Bool

-- | Message expiration timer. 0 if disabled
getGroupMessageExpirationTimer :: MonadIO m => Group -> SignalConn -> m Int

-- | List of group members' phone numbers
getGroupMembers :: MonadIO m => Group -> SignalConn -> m [String]

-- | UNTESTED. List of pending group members; I don't know what this does,
--   but I imagine you're probably looking for
--   <a>getGroupRequestingMembers</a>
getGroupPendingMembers :: MonadIO m => Group -> SignalConn -> m [String]

-- | List of phone numbers requesting to join the group, if theres an
--   invite link set to require admin approval
getGroupRequestingMembers :: MonadIO m => Group -> SignalConn -> m [String]

-- | List of group admins' phone numbers
getGroupAdmins :: MonadIO m => Group -> SignalConn -> m [String]

-- | String representing who has permission to add members (one of
--   <a>ONLY_ADMINS</a>, <a>EVERY_MEMBER</a>)
getGroupPermissionAddMember :: MonadIO m => Group -> SignalConn -> m String

-- | String representing who has permission to edit group description (one
--   of <a>ONLY_ADMINS</a>, <a>EVERY_MEMBER</a>)
getGroupPermissionEditDetails :: MonadIO m => Group -> SignalConn -> m String

-- | String representing who has permission to send messages (one of
--   <a>ONLY_ADMINS</a>, <a>EVERY_MEMBER</a>)
getGroupPermissionSendMessage :: MonadIO m => Group -> SignalConn -> m String

-- | Group invitation link. Empty if disabled
getGroupInviteLink :: MonadIO m => Group -> SignalConn -> m String

-- | Display name
setGroupName :: MonadIO m => String -> Group -> SignalConn -> m ()

-- | Description
setGroupDescription :: MonadIO m => String -> Group -> SignalConn -> m ()

-- | Filename of group avatar. Resolves using the working dir of the
--   signal-cli daemon, not this process
setGroupAvatar :: MonadIO m => String -> Group -> SignalConn -> m ()

-- | UNTESTED. If true, messages won't be forwarded via DBus
setGroupIsBlocked :: MonadIO m => Bool -> Group -> SignalConn -> m ()

-- | Message expiration timer. 0 to disable
setGroupMessageExpirationTimer :: MonadIO m => Int -> Group -> SignalConn -> m ()

-- | String representing who has permission to add members (one of
--   <a>ONLY_ADMINS</a>, <a>EVERY_MEMBER</a>)
setGroupPermissionAddMember :: MonadIO m => String -> Group -> SignalConn -> m ()

-- | String representing who has permission to edit group description (one
--   of <a>ONLY_ADMINS</a>, <a>EVERY_MEMBER</a>)
setGroupPermissionEditDetails :: MonadIO m => String -> Group -> SignalConn -> m ()

-- | String representing who has permission to send messages (one of
--   <a>ONLY_ADMINS</a>, <a>EVERY_MEMBER</a>)
setGroupPermissionSendMessage :: MonadIO m => String -> Group -> SignalConn -> m ()

-- | Add admins
groupAddAdmins :: MonadIO m => [String] -> Group -> SignalConn -> m ()

-- | Add numbers who are pending members to the group, and other numbers to
--   requesting members list
groupAddMembers :: MonadIO m => [String] -> Group -> SignalConn -> m ()

-- | Disable group invitation link
groupDisableLink :: MonadIO m => Group -> SignalConn -> m ()

-- | Enable group invitation link. If the argument is true, users cannot
--   join directly, but are added to the requesting members list first.
groupEnableLink :: MonadIO m => Bool -> Group -> SignalConn -> m ()

-- | Quit the group
groupQuit :: MonadIO m => Group -> SignalConn -> m ()

-- | Remove admins
groupRemoveAdmins :: MonadIO m => [String] -> Group -> SignalConn -> m ()

-- | Remove numbers from the group
groupRemoveMembers :: MonadIO m => [String] -> Group -> SignalConn -> m ()

-- | Reset the group invitation link
groupResetLink :: MonadIO m => Group -> SignalConn -> m ()

-- | Opaque connection object, aquired by <a>withConn</a> or
--   <a>withConnNum</a>
data SignalConn

-- | Timestamp, represented as an ms-precision unix timestamp
data Timestamp

-- | Opaque object representing a linked device
data Device

-- | Opaque Group object, aquired by <a>listGroups</a> or <a>getGroup</a>
data Group

-- | Received message
data ReceivedMessage

-- | Message sent by a linked device to someone else
SyncMessage :: Timestamp -> String -> Maybe Group -> String -> [String] -> ReceivedMessage

-- | Read receipt sent by someone else in response to one of your messages
Receipt :: Timestamp -> String -> ReceivedMessage

-- | Message sent to you by someone else
Message :: Timestamp -> String -> Maybe Group -> String -> [String] -> ReceivedMessage

-- | Conversion from <a>UTCTime</a>. This retains precision, so converting
--   back-and-forth is unproblematic.
fromUTCTime :: UTCTime -> Timestamp

-- | Conversion to <a>UTCTime</a>. This retains precision, so converting
--   back-and-forth is unproblematic.
toUTCTime :: Timestamp -> UTCTime