calamity: A library for writing discord bots in haskell

[ library, mit, network, web ] [ Propose Tags ] [ Report a vulnerability ]

Please see the README on GitHub at https://github.com/simmsb/calamity#readme


[Skip to Readme]

Modules

[Last Documentation]

  • Calamity
    • Cache
      • Calamity.Cache.Eff
      • Calamity.Cache.InMemory
    • Calamity.Client
      • Calamity.Client.Client
      • Calamity.Client.ShardManager
      • Calamity.Client.Types
    • Calamity.Commands
      • Calamity.Commands.CalamityParsers
      • Calamity.Commands.Context
      • Calamity.Commands.Dsl
      • Calamity.Commands.Help
      • Calamity.Commands.Types
      • Calamity.Commands.Utils
    • Calamity.Gateway
      • Calamity.Gateway.DispatchEvents
      • Calamity.Gateway.Intents
      • Calamity.Gateway.Shard
      • Calamity.Gateway.Types
    • Calamity.HTTP
      • Calamity.HTTP.AuditLog
      • Calamity.HTTP.Channel
      • Calamity.HTTP.Emoji
      • Calamity.HTTP.Guild
      • Calamity.HTTP.Interaction
      • Internal
        • Calamity.HTTP.Internal.Ratelimit
        • Calamity.HTTP.Internal.Request
        • Calamity.HTTP.Internal.Route
        • Calamity.HTTP.Internal.Types
      • Calamity.HTTP.Invite
      • Calamity.HTTP.MiscRoutes
      • Calamity.HTTP.Reason
      • Calamity.HTTP.User
      • Calamity.HTTP.Webhook
    • Calamity.Interactions
      • Calamity.Interactions.Eff
      • Calamity.Interactions.Utils
      • Calamity.Interactions.View
    • Internal
      • Calamity.Internal.BoundedStore
      • Calamity.Internal.ConstructorName
      • Calamity.Internal.IntColour
      • Calamity.Internal.LocalWriter
      • Calamity.Internal.RunIntoIO
      • Calamity.Internal.SnowflakeMap
      • Calamity.Internal.UnixTimestamp
      • Calamity.Internal.Updateable
      • Calamity.Internal.Utils
    • Metrics
      • Calamity.Metrics.Eff
      • Calamity.Metrics.Internal
      • Calamity.Metrics.Noop
    • Calamity.Types
      • Calamity.Types.CDNAsset
      • Calamity.Types.LogEff
      • Calamity.Types.Model
        • Calamity.Types.Model.Avatar
        • Calamity.Types.Model.Channel
          • Calamity.Types.Model.Channel.Attachment
          • Calamity.Types.Model.Channel.ChannelType
          • Calamity.Types.Model.Channel.Component
          • Calamity.Types.Model.Channel.DM
          • Calamity.Types.Model.Channel.Embed
          • Calamity.Types.Model.Channel.Group
          • Calamity.Types.Model.Channel.Guild
            • Calamity.Types.Model.Channel.Guild.Category
            • Calamity.Types.Model.Channel.Guild.Text
            • Calamity.Types.Model.Channel.Guild.Voice
          • Calamity.Types.Model.Channel.Message
          • Calamity.Types.Model.Channel.Reaction
          • Calamity.Types.Model.Channel.UpdatedMessage
          • Calamity.Types.Model.Channel.Webhook
        • Calamity.Types.Model.Guild
          • Calamity.Types.Model.Guild.AuditLog
          • Calamity.Types.Model.Guild.Ban
          • Calamity.Types.Model.Guild.Emoji
          • Calamity.Types.Model.Guild.Guild
          • Calamity.Types.Model.Guild.Invite
          • Calamity.Types.Model.Guild.Member
          • Calamity.Types.Model.Guild.Overwrite
          • Calamity.Types.Model.Guild.Permissions
          • Calamity.Types.Model.Guild.Role
          • Calamity.Types.Model.Guild.UnavailableGuild
        • Calamity.Types.Model.Interaction
        • Calamity.Types.Model.Presence
          • Calamity.Types.Model.Presence.Activity
          • Calamity.Types.Model.Presence.Presence
        • Calamity.Types.Model.User
        • Calamity.Types.Model.Voice
          • Calamity.Types.Model.Voice.VoiceRegion
          • Calamity.Types.Model.Voice.VoiceState
      • Calamity.Types.Partial
      • Calamity.Types.Snowflake
      • Calamity.Types.Tellable
      • Calamity.Types.Token
      • Calamity.Types.TokenEff
      • Calamity.Types.Upgradeable
    • Calamity.Utils
      • Calamity.Utils.CDNUrl
      • Calamity.Utils.Colour
      • Calamity.Utils.Message
      • Calamity.Utils.Permissions

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.1.0.0, 0.1.2.0, 0.1.3.0, 0.1.3.1, 0.1.4.0, 0.1.4.1, 0.1.4.2, 0.1.4.3, 0.1.4.4, 0.1.5.0, 0.1.5.1, 0.1.6.0, 0.1.6.1, 0.1.6.2, 0.1.7.0, 0.1.8.0, 0.1.8.1, 0.1.9.0, 0.1.9.1, 0.1.9.2, 0.1.9.3, 0.1.9.4, 0.1.10, 0.1.10.1, 0.1.11.0, 0.1.11.1, 0.1.11.2, 0.1.12.0, 0.1.13.0, 0.1.14.0, 0.1.14.1, 0.1.14.2, 0.1.14.3, 0.1.14.4, 0.1.14.5, 0.1.14.6, 0.1.14.7, 0.1.14.8, 0.1.14.9, 0.1.15.0, 0.1.16.0, 0.1.17.0, 0.1.17.1, 0.1.18.0, 0.1.18.1, 0.1.19.0, 0.1.19.1, 0.1.19.2, 0.1.20.0, 0.1.20.1, 0.1.21.0, 0.1.22.0, 0.1.22.1, 0.1.23.0, 0.1.23.1, 0.1.24.0, 0.1.24.1, 0.1.24.2, 0.1.25.0, 0.1.25.1, 0.1.26.0, 0.1.26.1, 0.1.27.0, 0.1.28.0, 0.1.28.1, 0.1.28.2, 0.1.28.3, 0.1.28.4, 0.1.28.5, 0.1.29.0, 0.1.30.0, 0.1.30.1, 0.1.30.2, 0.1.30.3, 0.1.30.4, 0.1.31.0, 0.2.0.0, 0.2.0.2, 0.3.0.0, 0.4.0.0, 0.5.0.0, 0.6.0.0, 0.7.0.0, 0.7.0.1, 0.7.1.0, 0.8.0.0, 0.9.0.0, 0.10.0.0, 0.11.0.0, 0.12.0.0, 0.12.1.0
Change log ChangeLog.md
Dependencies aeson (>=2.1 && <2.3), aeson-optics (>=1.2 && <2), async (>=2.2 && <3), base (>=4.13 && <5), bytestring (>=0.10 && <0.13), calamity-commands (>=0.4 && <0.5), colour (>=2.3.5 && <2.4), concurrent-extra (>=0.7 && <0.8), containers (>=0.6 && <0.8), crypton-connection (>=0.2.6 && <0.5), crypton-x509-system (>=1.6.6 && <1.7), data-default-class (>=0.1 && <0.2), data-flags (>=0.0.3 && <0.1), deepseq (>=1.4.4.0 && <2), deque (>=0.4 && <0.5), df1 (>=0.4 && <0.5), di-core (>=1.0.4 && <1.1), di-polysemy (>=0.2 && <0.3), exceptions (>=0.10 && <0.11), focus (>=1.0 && <2), hashable (>=1.2 && <2), http-api-data (>=0.4.3 && <0.7), http-client (>=0.5 && <0.8), http-date (>=0.0.8 && <0.1), http-types (>=0.12 && <0.13), megaparsec (>=8 && <10), mime-types (>=0.1 && <0.2), mtl (>=2.2 && <3), optics (>=0.4.1 && <0.5), polysemy (>=1.5 && <2), polysemy-plugin (>=0.3 && <0.5), random (>=1.2 && <1.3), reflection (>=2.1 && <3), req (>=3.9.2 && <3.14), safe-exceptions (>=0.1 && <2), scientific (>=0.3 && <0.4), stm (>=2.5 && <3), stm-chans (>=3.0 && <4), stm-containers (>=1.1 && <2), text (>=1.2 && <2.2), text-show (>=3.8 && <4), time (>=1.8 && <1.15), tls (>=1.7 && <3), typerep-map (>=0.5 && <0.7), unagi-chan (>=0.4 && <0.5), unboxing-vector (>=0.2 && <0.3), unordered-containers (>=0.2 && <0.3), vector (>=0.12 && <0.14), websockets (>=0.13 && <0.14) [details]
Tested with ghc ==9.6.6
License MIT
Copyright 2020 Ben Simms
Author Ben Simms
Maintainer ben@bensimms.moe
Category Network, Web
Home page https://github.com/simmsb/calamity
Bug tracker https://github.com/simmsb/calamity/issues
Source repo head: git clone https://github.com/simmsb/calamity
Uploaded by nitros12 at 2024-10-14T22:10:06Z
Distributions
Reverse Dependencies 2 direct, 0 indirect [details]
Downloads 41246 total (224 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2024-10-20 [all 2 reports]

Readme for calamity-0.12.1.0

[back to package description]

Calamity

Hackage Build Status License Hackage-Deps Discord Invite

Calamity is a Haskell library for writing discord bots, it uses Polysemy as the core library for handling effects, allowing you to pick and choose how to handle certain features of the library.

If you're looking for something with a less complicated interface, you might want to take a look at discord-haskell.

The current customisable effects are:

  • Cache: The default cache handler keeps the cache in memory, however you could write a cache handler that stores cache in a database for example.

  • Metrics: The library has counters, gauges, and histograms installed to measure useful things, by default these are not used (and cost nothing), but could be combined with Prometheus. An example of using prometheus as the metrics handler can be found here.

  • Logging: The di-polysemy library is used to allow the logging effect to be customized, or disabled.

Docs

You can find documentation on hackage at: https://hackage.haskell.org/package/calamity

There's also a good blog post that covers the fundamentals of writing a bot with the library, you can read it here: https://morrowm.github.io/posts/2021-04-29-calamity.html

Examples

Here's a list of projects that use calamity:

(Feel free to contact me via the discord server, or email me via ben@bensimms.moe if you've written a bot using calamity, or don't want your project listed here)

#!/usr/bin/env cabal
{- cabal:
  build-depends:
     base >= 4.13 && < 5
     , calamity >= 0.10.0.0
     , optics >= 0.4.1 && < 0.5
     , di-polysemy ^>= 0.2
     , di >= 1.3 && < 2
     , df1 >= 0.3 && < 0.5
     , di-core ^>= 1.0.4
     , polysemy >= 1.5 && <2
     , polysemy-plugin >= 0.3 && <0.5
     , stm >= 2.5 && <3
     , text-show >= 3.8 && <4
     , http-client ^>= 0.7
-}

{-# OPTIONS_GHC -fplugin=Polysemy.Plugin #-}

{-# LANGUAGE ApplicativeDo #-}
{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE GADTs #-}
{-# LANGUAGE ImportQualifiedPost #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE OverloadedLabels #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE PolyKinds #-}
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE TypeApplications #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE UndecidableInstances #-}
{-# OPTIONS_GHC -fplugin=Polysemy.Plugin #-}

module Main (main) where

import Calamity
import Calamity.Cache.InMemory
import Calamity.Commands
import Calamity.Commands.Context (FullContext, useFullContext)
import Calamity.Interactions qualified as I
import Calamity.Metrics.Noop
import Calamity.Utils.CDNUrl (assetHashFile)
import Control.Concurrent
import Control.Monad
import Data.Foldable (for_)
import Data.Text qualified as T
import Di qualified
import DiPolysemy qualified as DiP
import Optics
import Polysemy qualified as P
import Polysemy.Async qualified as P
import Polysemy.State qualified as P
import System.Environment (getEnv)
import TextShow
import Network.HTTP.Client (RequestBody(RequestBodyLBS))

data MyViewState = MyViewState
  { numOptions :: Int
  , selected :: Maybe T.Text
  }

$(makeFieldLabelsNoPrefix ''MyViewState)

main :: IO ()
main = do
  token <- T.pack <$> getEnv "BOT_TOKEN"
  Di.new $ \di ->
    void
      . P.runFinal
      . P.embedToFinal
      . DiP.runDiToIO di
      . runCacheInMemory
      . runMetricsNoop
      . useConstantPrefix "!"
      . useFullContext
      $ runBotIO (BotToken token) defaultIntents
      $ do
        void . addCommands $ do
          helpCommand
          -- just some examples

          command @'[User] "pfp" \ctx u -> do
            Right pfp <- fetchAsset (u ^. #avatar)
            let name = maybe "default.png" assetHashFile (u ^. #avatar % #hash)
                file = CreateMessageAttachment name (Just "Your avatar") (Network.HTTP.Client.RequestBodyLBS pfp)
            void $ tell ctx file
          command @'[User] "utest" \ctx u -> do
            void . tell @T.Text ctx $ "got user: " <> showt u
          command @'[Named "u" User, Named "u1" User] "utest2" \ctx u u1 -> do
            void . tell @T.Text ctx $ "got user: " <> showt u <> "\nand: " <> showt u1
          command @'[T.Text, Snowflake User] "test" \_ctx something aUser -> do
            DiP.info $ "something = " <> showt something <> ", aUser = " <> showt aUser
          group "testgroup" $ do
            void $ command @'[[T.Text]] "test" \ctx l -> do
              void . tell @T.Text ctx $ "you sent: " <> showt l
            group "say" do
              command @'[KleenePlusConcat T.Text] "this" \ctx msg -> do
                void $ tell @T.Text ctx msg
          command @'[] "explode" \_ctx -> do
            Just _ <- pure Nothing
            DiP.debug @T.Text "unreachable!"
          command @'[] "bye" \ctx -> do
            void $ tell @T.Text ctx "bye!"
            stopBot

          -- views!

          command @'[] "components" \ctx -> do
            let view options = do
                  ~(add, done) <- I.row do
                    add <- I.button ButtonPrimary "add"
                    done <- I.button ButtonPrimary "done"
                    pure (add, done)
                  s <- I.select options
                  pure (add, done, s)
            let initialState = MyViewState 1 Nothing
            s <- P.evalState initialState $
              I.runView (view ["0"]) (tell ctx) \(add, done, s) -> do
                when add do
                  n <- P.gets (^. #numOptions)
                  let n' = n + 1
                  P.modify' (#numOptions .~ n')
                  let options = map (T.pack . show) [0 .. n]
                  I.replaceView (view options) (void . I.edit)

                when done do
                  finalSelected <- P.gets (^. #selected)
                  I.endView finalSelected
                  I.deleteInitialMsg
                  void . I.respond $ case finalSelected of
                    Just x -> "Thanks: " <> x
                    Nothing -> "Oopsie"

                case s of
                  Just s' -> do
                    P.modify' (#selected ?~ s')
                    void I.deferComponent
                  Nothing -> pure ()
            P.embed $ print s

          -- more views!

          command @'[] "cresponses" \ctx -> do
            let view = I.row do
                  a <- I.button ButtonPrimary "defer"
                  b <- I.button ButtonPrimary "deferEph"
                  c <- I.button ButtonPrimary "deferComp"
                  d <- I.button ButtonPrimary "modal"
                  pure (a, b, c, d)

                modalView = do
                  a <- I.textInput TextInputShort "a"
                  b <- I.textInput TextInputParagraph "b"
                  pure (a, b)

            I.runView view (tell ctx) $ \(a, b, c, d) -> do
              when a do
                void I.defer
                P.embed $ threadDelay 1000000
                void $ I.followUp @T.Text "lol"

              when b do
                void I.deferEphemeral
                P.embed $ threadDelay 1000000
                void $ I.followUpEphemeral @T.Text "lol"

              when c do
                void I.deferComponent
                P.embed $ threadDelay 1000000
                void $ I.followUp @T.Text "lol"

              when d do
                void . P.async $ do
                  I.runView modalView (void . I.pushModal "lol") $ \(a, b) -> do
                    P.embed $ print (a, b)
                    void $ I.respond ("Thanks: " <> a <> " " <> b)
                    I.endView ()

        react @('CustomEvt (CtxCommandError FullContext)) \(CtxCommandError ctx e) -> do
          DiP.info $ "Command failed with reason: " <> showt e
          case e of
            ParseError n r ->
              void . tell ctx $
                "Failed to parse parameter: "
                  <> codeline n
                  <> ", with reason: "
                  <> codeblock' Nothing r
            CheckError n r ->
              void . tell ctx $
                "The following check failed: "
                  <> codeline n
                  <> ", with reason: "
                  <> codeblock' Nothing r
            InvokeError n r ->
              void . tell ctx $
                "The command: "
                  <> codeline n
                  <> ", failed with reason: "
                  <> codeblock' Nothing r

Disabling library logging

The library logs on debug levels by default, if you wish to disable logging you can do something along the lines of:

import qualified Di
import qualified Df1
import qualified Di.Core
import qualified DiPolysemy

filterDi :: Di.Core.Di l Di.Path m -> Di.Core.Di l Di.Path m
filterDi = Di.Core.filter (\_ p _ -> Df1.Push "calamity" `notElem` p)

Di.new $ \di ->
-- ...
  . runDiToIO di
  -- disable logs emitted by calamity
  . DiPolysemy.local filterDi
  . runBotIO
  -- ...

Nix

If you trust me, I have a cachix cache setup at simmsb-calamity.

With cachix installed, you should be able to run cachix use simmsb-calamity to add my cache to your list of caches.

You can also just manually add the substituter and public key:

substituters = https://simmsb-calamity.cachix.org
trusted-public-keys = simmsb-calamity.cachix.org-1:CQsXXpwKsjSVu0BJFT/JSvy1j6R7rMSW2r3cRQdcuQM= 

After this nix builds should just use the cache (I hope?)

For an example of a bot built using nix, take a look at: simmsb/calamity-bot