diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index 04b60b4..0000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,26 +0,0 @@ -# Summary - - -## Principle - -- [Architecture](./overivew.md#architecture) -- [Account](./overview.md#account-setup) - -## Development - -- [Modules](./development/modules.md) -- [Database](./development/database.md) - - -## Usages - -- [Messaging API](./usage/messaging.md) -- [Community Monitoring](./usage/monitoring.md) -- [Receiver](/usage/receiver.md) - -## Deployement - -- [Docker Deployement](./deployement/docker.md) -- [Configuration](./deployement/configuration.md) -- [Metrics](./deployement/metrics.md) - diff --git a/docs/deployment/configuration.md b/docs/deployment/configuration.md index bf79781..a732908 100644 --- a/docs/deployment/configuration.md +++ b/docs/deployment/configuration.md @@ -1,13 +1,14 @@ # Configuration -The bot is configured through a YAML file (`config.yaml`) and environment variables. -Environment variables override values from the YAML file. +The bot is configured through a YAML file (`config.yaml`), environment variables, and an optional `.env` file. ## Loading order -1. `config.yaml` — base configuration -2. Shell environment variables — override YAML values -3. `.env` file — override YAML values (loaded from the same directory as `config.yaml`) +Sources are resolved in priority order (highest first). A value is taken from the first source that defines it; later sources only fill in settings not set by a higher-priority source: + +1. `config.yaml` — highest priority; overrides environment variables and the `.env` file +2. Shell environment variables — override the `.env` file +3. `.env` file — lowest priority, used as fallback (loaded from the current working directory) ## Usage @@ -42,12 +43,6 @@ logging: ## Reference -### `sleep` - -| Type | Default | Description | -|------|---------|-------------| -| `int` | `10` | Sleep interval in minutes between monitoring cycles | - ### `files` | Field | Type | Default | Description | @@ -66,7 +61,7 @@ files: | Field | Type | Default | Env var | Description | |-------|------|---------|---------|-------------| | `name` | `str` | `""` | `BOT__NAME` | Status display name used to log in | -| `public_key` | `str` | `"BOT__PUBLIC_KEY"` | — | Expected public key for verification | +| `public_key` | `str` | `""` | `BOT__PUBLIC_KEY` | Expected public key for verification | | `password` | `str` | `""` | `BOT__PASSWORD` | Status account password | | `mnemonic_phrase` | `str` | `""` | `BOT__MNEMONIC_PHRASE` | 12-word recovery phrase (used when `init_account: true`) | | `init_account` | `bool` | `false` | `BOT__INIT_ACCOUNT` | If `false`, the account must already exist. If `true`, creates or restores the account using `mnemonic_phrase` | @@ -78,7 +73,7 @@ files: ```yaml bot: - display_name: 'my-bot' + name: 'my-bot' public_key: '0x...' password: 'ChangeMe' mnemonic_phrase: 'word1 word2 ... word12' @@ -93,7 +88,7 @@ Parameter to connect to the Status Backend instance. | Field | Type | Default | Env var | Description | |-------|------|---------|---------|-------------| | `domain` | `str` | `"localhost"` | `BACKEND__DOMAIN` | Status Backend hostname (`localhost` for local, `status-backend` for Docker) | -| `port` | `int` | `8080` | `BACKEND__BACKEND_PORT` | Status Backend API port | +| `backend_port` | `int` | `8080` | `BACKEND__BACKEND_PORT` | Status Backend API port | | `is_secure` | `bool` | `false` | `BACKEND__IS_SECURE` | Use HTTPS instead of HTTP | ```yaml backend: @@ -191,7 +186,7 @@ Event payloads are kept in plaintext in-memory so they can be handled correctly; | Field | Type | Default | Description | |-------|------|---------|-------------| -| `directories` | `list[str]` | `["./modules"]` | Directories to scan for module `.py` files | +| `directories` | `list[str]` | `["./modules", "bot/modules"]` | Directories to scan for module `.py` files | | `enabled` | `list[str]` | `[]` | List of module names to enable | | `settings` | `dict` | `{}` | Per-module settings (each module defines its own schema) | diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index e69de29..4177612 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -0,0 +1,3 @@ +# Docker deployement + + diff --git a/docs/overview.md b/docs/index.md similarity index 92% rename from docs/overview.md rename to docs/index.md index 2b58ed5..d03af34 100644 --- a/docs/overview.md +++ b/docs/index.md @@ -24,6 +24,7 @@ graph TB The Status Bot use [status-python-sdk](https://github.com/status-im/status-python-sdk) for the interraction with Status Backend. The Status-Backend use external services: + * CoinGecko - Optional to get token price * EVM access - (Infura for example) required to interract with Token Gated community. @@ -51,4 +52,4 @@ It first need to export a backup, then import it in the docker container under ` > Note: the account backup need to also be imported in Status Backend -The full configuration explaination can be found at [./deployment/configuration.md] +The full configuration explaination can be found in the [configuration](deployment/configuration.md) page. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..e8aa77e --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,104 @@ +/* ========================================================================== + Status.app Theme Overrides for MkDocs Material + ========================================================================== */ + +:root, +[data-md-color-scheme="slate"] { + /* Status Palette */ + --status-bg: #090a10; /* Ultra-dark background */ + --status-card-bg: #12141d; /* Card/sidebar background */ + --status-accent-blue: #4360df; /* Primary brand blue */ + --status-accent-purple: #814bf6; /* Accent purple */ + --status-text: #eceef8; /* Primary text */ + --status-text-muted: #8b92b0; /* Muted secondary text */ + --status-border: #1e2235; /* Soft subtle border */ + + /* Material Theme Token Remapping */ + --md-default-bg-color: var(--status-bg); + --md-default-bg-color--light: var(--status-card-bg); + --md-default-bg-color--lighter: #1a1d2c; + --md-default-fg-color: var(--status-text); + --md-default-fg-color--light: var(--status-text-muted); + --md-default-fg-color--lighter: #687093; + + /* Primary Accent & Links */ + --md-primary-fg-color: var(--status-bg); + --md-accent-fg-color: var(--status-accent-blue); + + /* Code Syntax Highlighting Cards */ + --md-code-bg-color: #0d0f17; + --md-code-fg-color: #e2e8f0; +} + +/* Base Body & Layout */ +body { + background-color: var(--status-bg); + color: var(--status-text); +} + +/* Header Navbar */ +.md-header { + background-color: rgba(9, 10, 16, 0.85) !important; + backdrop-filter: blur(12px); + border-bottom: 1px solid var(--status-border); +} + +/* Navigation & Sidebar Cards */ +.md-sidebar__inner { + background-color: var(--status-card-bg); + border-radius: 12px; + border: 1px solid var(--status-border); + padding: 1rem; +} + +.md-nav__link { + color: var(--status-text-muted); + border-radius: 6px; + transition: color 0.2s ease, background-color 0.2s ease; +} + +.md-nav__link--active, +.md-nav__link:hover { + color: #ffffff !important; + background-color: rgba(67, 96, 223, 0.15); +} + +/* Content Area Styling */ +.md-content { + background-color: var(--status-bg); +} + +/* Code Blocks */ +.md-typeset pre > code { + border-radius: 10px; + border: 1px solid var(--status-border); + background-color: var(--status-card-bg); +} + +/* Admonitions / Callout Boxes */ +.md-typeset .admonition, +.md-typeset details { + border-radius: 10px; + border: 1px solid var(--status-border); + box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25); + background-color: var(--status-card-bg); +} + +.md-typeset .admonition.note { + border-left-color: var(--status-accent-blue); +} + +.md-typeset .admonition.tip { + border-left-color: var(--status-accent-purple); +} + +/* Links */ +.md-typeset a { + color: #6380ff; + text-decoration: none; +} + +.md-typeset a:hover { + color: #a3b5ff; + text-decoration: underline; +} diff --git a/docs/usage/monitoring.md b/docs/usage/monitoring.md index 6398f98..af10603 100644 --- a/docs/usage/monitoring.md +++ b/docs/usage/monitoring.md @@ -1,58 +1,109 @@ -# Community Monitoring +# Monitoring -The Status Bot can be used to monitore activity in community +The Status Bot can store the messages and Community information to allow some analytics. -## Fetch Data +## Received messages - **No personal data is collected from users.** +The messages received by the bot account can be store in the database with the module `receiver`. + +Data from `Messages` and `Chats` are hashed with sha256 and a pepper, to avoid storing information openly. + +### Messages + +| Field | Type | Hashed | Description | +|----|----|----|---| +| id | String | Hashed | Message Id | +| whisper_timestamp | - | DateTime | Timstamp of reception by the last network node | +| from_ | String | Hashed | Address of the sender | +| alias | String | Hashed | User Alias | +| seen | Boolean | - | Flag indicating if the message has been seen | +| rtl | Boolean | - | Flag indicating | +| line_count | Integer | - | | +| text | String | Hashed | Content of the messages | +| chat_id | String | Hashed | Id of the chat link to this message | +| local_chat_id | String | Hashed | Chat id for the local backend instance | +| clock | BigInteger | - | Unix timestamp of the message reception | +| replace | String | - | | +| response_to | String | Hashed | User Id to whom the message is responding | +| ens_name | String | Hashed | ENS name of the sender | +| display_name | String | Hashed | Display Name of the sender | +| timestamp | DateTime | - | timestamp of the message sent | +| content_type | Integer | - | Number indicating the type of message content | +| message_type | Integer | - | Type of message | +| contact_request_state | Integer | - | | +| compressed_key | String | - | Key used to compress the message | +| received_timestamp | DateTime | - | timestamp of the message reception | + +### Chats + +| Field | Type | Hashed | Description | +|----|----|----|----| +| id | String | | | +| type | String | | | +| name | String | | | +| received_timestamp | DateTime | | | +| description | String | | | +| color | String | | | +| emoji | String | | | +| active | Boolean | | | +| viewers_can_post_reactions | Boolean | | | +| chat_type | Integer | | | +| timestamp | DateTime | | | +| last_clock_value | BigInteger | | | +| deleted_at_clock_value | Integer | | | +| read_messages_at_clock_value | Integer | | | +| unviewed_messages_count | Integer | | | +| unviewed_mentions_count | Integer | | | +| membership_update_events | Integer | | | +| identicon | String | | | +| muted | Boolean | | | +| mute_till | DateTime | | | +| community_id | String | | | +| category_id | String | | | +| joined | String | | | -| Field | Hashed | Description | -|:----------------------|:---------|:------------------------------------------------------------| -| **id** | **Yes** | The message's ID | -| **whisper_timestamp** | No | The whisper timestamp of the message | -| **from** | **Yes** | The public key of the user | -| **message_type** | No | The message type | -| **seen** | No | True if the message has been seen otherwise False | -| **chat_id** | No | The chat ID is a combination of community ID and channel ID | -| **community_id** | No | The ID of the community | -| **response_to** | **Yes** | Ithe public key of the user who the response is for | -| **timestamp** | No | The timestamp of the message | -| **deleted** | No | True if the message was deleted otherwise False | +## Community Monitoring -Status Bot account information can be found in [`config.yaml`](./config.yaml). +The module `communities_monitoring` will allow to periodically fetch information of the community the bot account has access. -## How it works +The data by the Bot are the following. -```mermaid -graph LR - subgraph Communities[Status App] - subgraph Status[Status Community] - StatusMessages[Messages] - StatusInfo[Information] - end - subgraph Logos[Logos Community] - LogosMessages[Messages] - LogosInfo[Information] - end +### Community - end +| Field | Type | Description | +|----|----|----| +| id | String | Community Id | +| url | String | Url to join the community | +| name | String | Name of the community | +| verified | Boolean | Flag if the community is verified | +| tags | String | All the community tags separated by a `,` | +| is_member | Boolean | Flag indicating the community the bot has joined | +| joined_timestamp | DateTime | Timestamp when the account joined the community. `None` when the account has not joined. | +| requested_timestamp | DateTime | Timestamp when the join request was submitted. `None` when no request was made. | +| encrypted | String | Whether the community messaging is encrypted. | +| number_members | Integer | Total number of community members. | - subgraph Bot[Docker Container] - RawDataLocal[(Raw Data)] - Script[monitor.py] - end +### Channels - subgraph IFT[IFT Infrastructure] - RawDataIFT[(Raw Data)] - ProcessedDataIFT[(Processed Data)] - - end - - Communities <--> |class Account| Script - Script --> |SHA256| RawDataLocal - RawDataLocal --> |Airbyte| RawDataIFT - RawDataIFT --> |dbt| ProcessedDataIFT -``` +* `id`: Id of the channel. +* `chat_id`: Chat id of the channel. +* `community_id`: Id of the channel's community. +* `name`: Name of the channel. +* `description`: Description of the channel. +* `can_post`: Can the Bot Post into the channel. +* `can_view`: Can the Bot view the channel. +* `can_post_reaction`: Can the bot react to a Post. +* `token_gated`: Is the channel access limited with a token. +| Key | Type | Description | +|----|----|-------------| +| `id` | String | The channel's own id | | | +| `chat_id` | String | The community id and channel id joined together. Value to use to map a message to a channel. | +| `name` | String | The channel name | | | +| `description` | String | The channel description. | +| `can_post` | Boolean | Whether the account can send messages to the channel. [`chats`](./account.md#chats) only lists channels where this is `True`. | +| `can_view` | Boolean | Whether the account can read the channel. | +| `can_post_reaction` | Boolean | Whether the account can post emoji reactions. | +| `token_gated` | Boolean | Whether access to the channel is gated behind a token. | diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..ce4c723 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,40 @@ +site_name: Status Bot Documentation + +theme: + name: material + palette: + - scheme: slate + primary: custom + accent: custom + font: + text: Inter + code: JetBrains Mono + features: + - navigation.sections + - navigation.instant + - navigation.tracking + - content.code.copy + - content.code.annotate + +extra_css: + - stylesheets/extra.css + +nav: + - index.md + - Usage: + - Messaging: usage/messaging.md + - Monitoring: usage/monitoring.md + - Deployment: + - Configuration: deployment/configuration.md + - Docker: deployment/docker.md + - Metrics: deployment/metrics.md + - Development: + - Database: development/database.md + - Modules: development/modules.md + +markdown_extensions: + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format diff --git a/pyproject.toml b/pyproject.toml index be7356e..dddb0bc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,6 +21,10 @@ dependencies = [ [project.optional-dependencies] dev = ["pytest"] +docs = [ + "mkdocs>=1.5.3", + "mkdocs-material>=9.5.0", +] [project.scripts] status-bot = "main:main"