maple/README.md

## [MAPLE|G1MP]+[ML^N]+[NETSPANNING[i]]
---
```
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMh+MMMMMMMMMMMMMMhsMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMm/ oMMMMMMMMMMMMMMm +NMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMy`  yMMMMMMMMMMMMMMM- -mMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMs+dMMMMMMMMMM+    sMMMMMMMMMMMMMMM-  `dMMMMMMMMMMms/NMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMM+ .omMMMMMM:     -MMMMMMMMMMMMMMo    `yMMMMMMMy: `dMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMM-   /dMMM+       sMMMMMMMMMMMMh      `hMMMNo`   sMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMd     :dm        `mMMMMMMMMMMN.       .NNo`    .MMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMM:      -         :MMMMMMMMMMs         :`      sMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMs                 ymNMMMMMNm.                 NMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMy                    `-/-`                   .MMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMo                                            .NMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMNh+.                                               :sdMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMhso+:.                                                      `-/+syMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMM-                                                                 dMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMM`   `.:+/.                                              `/s+:.    sMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMNo   -oms.             .//-`               `:/:`            `+md+`  .hMMMMMMMMMMMMMMM
MMMMMMMMMMMMMNs`                        .odNdo.       .ohmd+`                        :dMMMMMMMMMMMMM
MMMMMMMMMMMNo`                             ..           .-                             :hMMMMMMMMMMM
MMMMMMMMMd+`                                                                             -sNMMMMMMMM
MMMMMMNs-                         `..                          `/-.                        `+dMMMMMM
MMMNy:                       ./sdNMMMh:                      `sNMMMNds/.                      .odMMM
MM+                       :ymMMMMMMMMMMh.                   +NMMMMMMMMMMmo-                      /NM
MMMh:                  .sNMMMMMMMMMMMMMMN-                `hMMMMMMMMMMMMMMMm+`                 :hMMM
MMMMMd:`       ``-:+shmMMMMMMMMMMMMMMMMMMN.               hMMMMMMMMMMMMMMMMMMMmhs+/-..``````./dMMMMM
MMMMMMMMMNNNNNNMMMMMMMMMMMMMMMMMMMMMMMMMMMo              .MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMy              .MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMN.             /MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMN+`         `+NMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNs.    -hMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMdyymMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
```
---
## Summary

```
this project is the ( m4plmp - https://git.tcp.direct/decoded/m4pl1mp )
except that this one also uses the matrix protocol and talks to
matrix and irc servers both. so it's essentialy two clients wrapped
in one and not only bridging information between the two networks
but unifying maple's services between them as well.
```
---
## TODO
- plugin wrapper to reduce rewrite the same plugins properties per spanned network
- intuitive bridge system
- raw tcp socket for external service interfacing
- logical color formatting of strings
- plugin to monitor version control
- plugin to monitor music releases
  
---
## Changelog - v2.4
- telegram netspanned
- experimenting with color coding
---
## Changelog - v2.3
- discord netspanned
---
## Changelog - v2.2
- matrix netspanned
---
## Changelog - v2.1
- tried pyenv+pipenv, ended up up reverting back to pure virtualenv for consistency.
---
## Screenshots

![screenshots](screenshots/ss1.png)

---
## References

###### [ Netspanning network protocols ]
- [online] - irc - https://www.rfc-editor.org/rfc/rfc2812.html
- [online] - matrix - https://spec.matrix.org/latest
- [online] - discord - https://discord.com/developers/docs/reference
- [online] - telegram - https://core.telegram.org/bots/api

###### [ The actual base hybrid - Machine Learning Irc3 ]
- m4plmp - https://git.tcp.direct/decoded/m4pl1mp

###### [ g1mp was the first service bot, maple named herself ]
- Maple - https://git.tcp.direct/decoded/Maple
- g1mp - https://git.tcp.direct/decoded/g1mp
---
## Prerequisites

###### [ substitute apt for the package manager of your choice ]

- `apt install python3` - `*note: python3.9 is ideal`
- `apt install python3-pip`
- `python3 -m pip install virtualenv`
---
## Instructions

###### - [ virtualenv could be substituted for pyenv/pipenv or no virtualenv et al ]
###### - [ environmental credentials of env/bin/activate could alternatively be hardcoded ]
- `git clone --recursive https://git.tcp.direct/decoded/maple_netspan.git`
- `cd maple_netspan`
- `virtualenv -p python3.9 env`
- `source env/bin/activate`
- `pip install -r requirements.txt`
---
###### [ Relevant urls pertaining to the developer api keys and server credentials ]
---
- **openai** - https://beta.openai.com/signup
- **nickserv** - https://wiki.anope.org/index.php/2.0/Modules#NickServ - `/msg nickserv help register`
- **matrix** - https://app.element.io/
- **discord** - https://discord.com/developers/applications
- **telegram** - https://tinyurl.com/bdececee - https://docs.python-telegram-bot.org/en/v20.0a2/examples.html
- **twitter** - https://developer.twitter.com/en/portal/petition/essential/basic-info
- **youtube** - https://console.cloud.google.com/apis/credentials
---
###### [ Append your *developer* / *service* api keys credentials to `env/bin/activate` ]
---
```
cat env/bin/activate
..
export NICKSERV_USERNAME=your_nickserv_username                                  # <- IRCD NICKSERV USER
export NICKSERV_PASSWORD=your_nickserv_password                                  # <- IRCD NICKSERV PASS
export BOT_SASL_USERNAME=$NICKSERV_USERNAME                                      # <- IRCD NICKSERV USER
export BOT_SASL_PASSWORD=$NICKSERV_PASSWORD                                      # <- IRCD NICKSERV PASS
export MATRIX_HOMESERVER=https://matrix.org                                      # <- MATRIX HOMESERVER
export MATRIX___USERNAME=your_matrix_username                                    # <- MATRIX USERNAME
export MATRIX___PASSWORD=your_matrix_password                                    # <- MATRIX PASSWORD
export DEVELOPER_KEY=1394823190182390182382383215382158321                       # <- YOUTUBE API KEY
export CONSUMER_KEY=2151235132512351235123512351325231                           # <- TWITTER API KEY
export CONSUMER_SECRET=514512521345234523452345234523452345234523452             # <- TWITTER API KEY
export ACCESS_TOKEN_KEY=24513429875209348502934850294898348034850293485203948592 # <- TWITTER API KEY
export ACCESS_TOKEN_SECRET=523490582034985203948520394804884820934850923485      # <- TWITTER API KEY
export OPENAPI_KEY=AeJWbyak16wjHZ8L4TAbGIlVk31YwwAyz-GsezWCJ7Wkh7BIFTO           # <- OPENAI API KEY
export DISCORD__MAPLE=295326962352954038                                         # <- DISCORD API KEY
export DISCORD__SCHAN=295326962352954038                                         # <- DISCORD API KEY
export DISCORD__TOKEN=AT2Sh4g.G1M9vNTOXmIaQzdvn5b6QzQMTyTBX6COJONUIRjLWi5UX0j294 # <- DISCORD API KEY
export TELEGRAM_TOKEN=AHh4DA9FgE3vs1SfAnx8975t85J30mU925GhJWcoUBBo7              # <- TELEGRAM API KEY
```
---
# Usage
## 1 - `cd maple_netspan`
## 2 - `source env/bin/activate`
## 3 - `python3.9 bot_maple.py`
---
**plugins/net_irc_plugin.py** - main bot config
- `here plugins can be diabled/enabled. e.g. disabling plugins without api keys`

**plugins.net_matrix_plugin.py** - the file to edit for this change
- `@maple:pcriot.org` change this credential to your matrix username:homeserver
- `add_credentials("@maple:pcriot.org")` - what the code looks like to change

---
#### 1 `env/bin/activate` - the actual credentials to be exported into the local environment
#### 2 `relevant plugin` - reads these particular environmental variable exports
#### 3 `the source code` - where the credentials are read back to as runtime only variables
###### [ this method can be hardened with a cipher, but at some point a key is required ]
---
       1         export NICKSERV_USERNAME=your_nickserv_username
       1         export NICKSERV_PASSWORD=your_nickserv_password
       2 plugins.auth_custom_plugin
       3         NICKSERV_USERNAME=os.environ['NICKSERV_USERNAME']
       3         NICKSERV_PASSWORD=os.environ['NICKSERV_PASSWORD']
---
       1         export BOT_SASL_USERNAME=also_your_nickserv_username
       1         export BOT_SASL_PASSWORD=also_your_nickserv_password
       2 plugins.sasl_custom_plugin
       3         BOT_SASL_USERNAME=os.environ['BOT_SASL_USERNAME']
       3         BOT_SASL_PASSWORD=os.environ['BOT_SASL_PASSWORD']
---
       1        export MATRIX_HOMESERVER=https://matrix.org
       1        export MATRIX___USERNAME=your_matrix_username
       1        export MATRIX___PASSWORD=your_matrix_password
       2 plugins.net_matrix_plugin
       3        MATRIX_HOMESERVER=os.environ['MATRIX_HOMESERVER']
       3        MATRIX___USERNAME=os.environ['MATRIX___USERNAME']
       3        MATRIX___PASSWORD=os.environ['MATRIX___PASSWORD']
---
       1        export OPENAPI_KEY=AeJWbyak16wjHZ8L4TAbGIlVk31YwwAyz-GsezWCJ7Wkh7BIFTO
       2 plugins.openai_plugin
       3        OPENAPI_KEY = os.environ['OPENAPI_KEY']
---
       1        export DISCORD__MAPLE=295326962352954038
       1        export DISCORD__SCHAN=295326962352954038
       1        export DISCORD__TOKEN=AT2Sh4g.G1M9vNTOXmIaQzdvn5b6QzQMTyTBX6COJONUIRjLWi5UX0j294
       2 plugins.net_discord_plugin
       3        DISCORD__SCHAN=int(os.environ['DISCORD__SCHAN'])
       3        DISCORD__MAPLE=int(os.environ['DISCORD__MAPLE'])
       3        DISCORD__TOKEN=str(os.environ['DISCORD__TOKEN'])
---
       1        export TELEGRAM_TOKEN=AHh4DA9FgE3vs1SfAnx8975t85J30mU925GhJWcoUBBo7
       2 plugins.net_telegram_plugin
       3        TELEGRAM_TOKEN=os.environ['TELEGRAM_TOKEN']
---
       1        export DEVELOPER_KEY=1394823190182390182382383215382158321
       2 plugins.youtube_plugin
       3        DEVELOPER_KEY = os.environ['DEVELOPER_KEY']
---
       1        export CONSUMER_KEY=2151235132512351235123512351325231
       1        export CONSUMER_SECRET=514512521345234523452345234523452345234523452
       1        export ACCESS_TOKEN_KEY=24513429875209348502934850294898348034850293485203948592
       1        export ACCESS_TOKEN_SECRET=523490582034985203948520394804884820934850923485
       2 plugins.twitter_plugin
       3        CONSUMER_KEY = os.environ['CONSUMER_KEY']
       3        CONSUMER_SECRET = os.environ['CONSUMER_SECRET']
       3        ACCESS_TOKEN_KEY = os.environ['ACCESS_TOKEN_KEY']
       3        ACCESS_TOKEN_SECRET = os.environ['ACCESS_TOKEN_SECRET']
---

## 1 `edit` - plugins/net_irc_plugin.py to configure your bot settings
---