Add usage docs

docs/development/bridges.md

@@ -8,6 +8,7 @@ interface, but rather create a separate component using the same database.
 ::: suppgram.frontends.telegram.TelegramStorage
     handler: python
     options:
+      show_bases: false
       show_root_heading: true
       show_source: false
       heading_level: 2

docs/development/customer_frontends.md

@@ -4,6 +4,7 @@
     handler: python
     options:
       show_root_heading: true
+      show_bases: false
       show_source: false
 
 <hr/>

docs/development/storages.md

@@ -5,6 +5,7 @@
     options:
       show_root_heading: true
       show_source: false
+      show_bases: false
       show_if_no_docstring: true
       heading_level: 3
 

docs/usage/customizing_texts.md → docs/features/customizing_texts.md

@@ -12,20 +12,23 @@ Suppgram encapsulates all text generation in [TextProvider][suppgram.texts.TextP
 It has a lot of members, see [source code](https://github.com/Saluev/suppgram/blob/master/suppgram/texts/interface.py)
 for details.
 
-Suppgram also provides out-of-the-box text pack for English and Russian languages.
+Suppgram provides out-of-the-box text packs for English and Russian languages. These texts are intentionally
+bland to fit all more or less, so you should probably consider tailoring them to your needs.
 
 ::: suppgram.texts.en.EnglishTextProvider
     handler: python
     options:
       show_root_heading: true
       show_source: false
+      show_bases: false
       heading_level: 2
 
 ::: suppgram.texts.ru.RussianTextProvider
     handler: python
     options:
       show_root_heading: true
       show_source: false
+      show_bases: false
       heading_level: 2
 
 If you want to customize your texts, you can either implement your own `TextProvider` or tweak an
@@ -44,10 +47,9 @@ class MyTextProvider(EnglishTextProvider):
 
 Then we can customize texts provider in all-in-one CLI:
 ```shell
-$ python -m suppgram.cli.all_in_one \
-         --sqlalchemy-uri sqlite+aiosqlite:///test.db \
-         --telegram-owner-id <your Telegram user ID> \
-         --texts mytexts.MyTextProvider
+python -m suppgram.cli.all_in_one \
+    --texts mytexts.MyTextProvider \
+    ...
 ```
 or via builder:
 ```python

docs/features/mongodb_integration.md

@@ -10,8 +10,8 @@ Then you can configure the integration by database URI. Examples:
 ```shell
 # All-in-one CLI + MongoDB (insecure)
 python -m suppgram.cli.all_in_one \
-  --mongodb-uri mongodb://user:password@host:27017/database \
-  ...
+    --mongodb-uri mongodb://user:password@host:27017/database \
+    ...
 
 # All-in-one CLI + MongoDB (secret in environment variable)
 export MONGODB_URI=mongodb://user:password@host:27017/database
@@ -20,8 +20,8 @@ python -m suppgram.cli.all_in_one ...
 # All-in-one CLI + MongoDB (secret in file)
 echo "mongodb://user:password@host:27017/database" > /secrets/mongodb_uri
 python -m suppgram.cli.all_in_one \
-  --mongodb-uri-file /secrets/mongodb_uri \
-  ...
+    --mongodb-uri-file /secrets/mongodb_uri \
+    ...
 ```
 
 Suppgram will create collections with names starting with `suppgram_`, so you may use 

docs/features/pubnub_integration.md

@@ -0,0 +1,64 @@
+# PubNub integrations
+
+[PubNub](https://pubnub.com/) operates channels and users within channels. It also allows 
+gathering chats into [channel groups](https://www.pubnub.com/docs/sdks/python/api-reference/channel-groups).
+
+Suppgram integration presumes there is a single channel group all support channels belong to.
+All messages from support agents will be authored by a single PubNub user.
+All messages written to these channels by users other than the support user are considered
+messages from customers and will be forwarded to agents.
+
+To configure PubNub, you will need to specify a number of environment variables and flags:
+```shell
+export PUBNUB_PUBLISH_KEY="publish_key"
+export PUBNUB_SUBSCRIBE_KEY="subscribe_key"
+export PUBNUB_SECRET_KEY="secret_key"
+python -m suppgram.cli.all_in_one \
+    --pubnub-user-id "support_user_id" \
+    --pubnub-channel-group "support_channel_group" \
+    ...
+```
+Secret key is optional; if not specified, it is your responsibility to ensure that 
+support user has all necessary permissions to read and write to channels.
+
+Since there is no strict structure of messages within PubNub, but rather they are
+arbitrary JSONs, you might need to implement a custom encoder/decoder for them:
+
+::: suppgram.frontends.pubnub.MessageConverter
+    handler: python
+    options:
+      show_root_heading: true
+      show_source: false
+      show_bases: false
+      heading_level: 2
+
+Default implementation is `suppgram.frontends.pubnub.DefaultMessageConverter`. It may be used with
+sandbox credentials to test how it works. To override it, use `--pubnub-message-converter` flag:
+```shell
+python -m suppgram.cli.all_in_one \
+  --pubnub-message-converter mymodule.MyConverter \
+  ...
+```
+
+For testing purposes you can also use `suppgram.cli.pubnub_customer_client` tool, accepting basically
+the same list of environment variables and command line arguments:
+```shell
+$ python -m suppgram.cli.pubnub_customer_client --help
+Usage: python -m suppgram.cli.pubnub_customer_client [OPTIONS]
+
+Options:
+  --pubnub-user-id TEXT           PubNub user ID [default: random UUID]
+  --pubnub-channel TEXT           PubNub channel for communication with
+                                  support [default: UUID-support]
+  --pubnub-channel-group TEXT     PubNub channel group to add channel to
+                                  [default: support]
+  --pubnub-message-converter TEXT
+                                  Class converting messages between PubNub
+                                  JSONs and suppgram Message objects
+                                  [default: suppgram.frontends.pubnub.DefaultM
+                                  essageConverter]
+  --help                          Show this message and exit.
+```
+**Note** that user ID here is **not** support user ID as before, but rather customer user ID. 
+It can be omitted; then it will be generated randomly. It will probably not work without secret 
+key though, since now we'll have to get some permissions dynamically.

docs/features/sql_integration.md

@@ -16,13 +16,13 @@ by database URI. Examples:
 ```shell
 # All-in-one CLI + SQLite
 python -m suppgram.cli.all_in_one \
-  --sqlalchemy-uri sqlite+aiosqlite:///path/to/file.db \
-  ...
+    --sqlalchemy-uri sqlite+aiosqlite:///path/to/file.db \
+    ...
 
 # All-in-one CLI + PostgreSQL (insecure)
 python -m suppgram.cli.all_in_one \
-  --sqlalchemy-uri postgresql+asyncpg://user:password@host:5432/database \
-  ...
+    --sqlalchemy-uri postgresql+asyncpg://user:password@host:5432/database \
+    ...
 
 # All-in-one CLI + PostgreSQL (secret in environment variable)
 export SQLALCHEMY_URI=postgresql+asyncpg://user:password@host:5432/database
@@ -31,8 +31,8 @@ python -m suppgram.cli.all_in_one ...
 # All-in-one CLI + PostgreSQL (secret in file)
 echo "postgresql+asyncpg://user:password@host:5432/database" > /secrets/postgres_uri
 python -m suppgram.cli.all_in_one \
-  --sqlalchemy-uri-file /secrets/postgres_uri \
-  ...
+    --sqlalchemy-uri-file /secrets/postgres_uri \
+    ...
 ```
 
 Suppgram will create tables with names starting with `suppgram_`, so you may use 

docs/features/telegram_integration.md

@@ -0,0 +1,41 @@
+# Telegram integraton
+
+Configuring Telegram bots is pretty much covered in [Quickstart](../usage/quickstart.md)
+section. Examples:
+
+```shell
+# Secrets in environment variables
+export TELEGRAM_MANAGER_BOT_TOKEN="token"
+export TELEGRAM_CUSTOMER_BOT_TOKEN="token"
+export TELEGRAM_AGENT_BOT_TOKENS="token1 token2 ..."
+python -m suppgram.cli.all_in_one ...
+
+# Secrets in files
+echo "token" > /secrets/manager_bot_token
+echo "token" > /secrets/customer_bot_token
+echo "token1 token2 ..." > /secrets/agent_bot_tokens
+python -m suppgram.cli.all_in_one \
+    --telegram-manager-bot-token-file /secrets/manager_bot_token \
+    --telegram-customer-bot-token-file /secrets/customer_bot_token \
+    --telegram-agent-bot-tokens-file /secrets/agent_bot_tokens \
+    ...
+```
+
+## Bot commands
+
+All bots update their command list on startup, so hints should be accessible
+via Telegram interface (upon typing `/`).
+
+Manager bot commands: 
+
+* `/create_tag` — create new tag to label conversations with. Works in private chat with the bot.
+* `/agents` — make all members of a group support agents **and** send notifications about new conversations to the 
+  group. Works in group chats.
+* `/send_new_conversations` — only send notifications about new conversations to a group. Works in group chats. May be
+  useful to create a separate group without agents to overview all conversations.
+
+Agent bot commands:
+
+* `/postpone` — stop messaging with the customer currently assigned to this bot and return the conversation to NEW 
+  status. 
+* `/resolve` — stop messaging with the customer currently assigned to this bot and mark conversation resolved.

mkdocs.yml

@@ -9,10 +9,12 @@ nav:
       - Quickstart: usage/quickstart.md
       - 'All-in-one CLI': usage/all_in_one_cli.md
       - Builder: usage/builder.md
-      - 'Customizing texts': usage/customizing_texts.md
   - Features:
       - 'PostgreSQL/SQLite integration': features/sql_integration.md
       - 'MongoDB integration': features/mongodb_integration.md
+      - 'Telegram integration': features/telegram_integration.md
+      - 'PubNub integration': features/pubnub_integration.md
+      - 'Customizing texts': features/customizing_texts.md
   - Development:
       - 'Contribution guide': development/contribution_guide.md
       - 'Architecture overview': development/architecture_overview.md

suppgram/frontends/pubnub/__init__.py

@@ -1,2 +1,3 @@
 from .converter import DefaultMessageConverter  # noqa
+from .converter import MessageConverter  # noqa
 from .customer_frontend import PubNubCustomerFrontend  # noqa

suppgram/frontends/pubnub/converter.py

@@ -13,13 +13,17 @@ def make_pubnub_message_converter(converter_class_path: str) -> "MessageConverte
         converter_module_name,
         converter_class_name,
     ) = converter_class_path.rsplit(".", 1)
-    converter_class = getattr(
-        import_module(converter_module_name), converter_class_name
-    )
+    converter_class = getattr(import_module(converter_module_name), converter_class_name)
     return converter_class()
 
 
 class MessageConverter(abc.ABC):
+    """Converts messages from project-specific JSON to Suppgram dataclass and vice-versa.
+
+    Methods:
+        convert_from_pubnub: convert from project-specific JSON received from PubNub
+        convert_to_pubnub: convert to project-specific JSON to be sent to PubNub"""
+
     @abc.abstractmethod
     def convert_from_pubnub(self, message: PNMessageResult) -> Message:
         pass
@@ -35,9 +39,9 @@ class DefaultMessageConverter(MessageConverter):
     def convert_from_pubnub(self, message: PNMessageResult) -> Message:
         return Message(
             kind=MessageKind(message.message["kind"]),
-            time_utc=datetime.strptime(
-                message.message["time"], self._ISO_8601_FORMAT
-            ).astimezone(timezone.utc),
+            time_utc=datetime.strptime(message.message["time"], self._ISO_8601_FORMAT).astimezone(
+                timezone.utc
+            ),
             text=message.message.get("text"),
         )