<commit_before># IMPORTANT

This is a fork of https://github.com/xmikos/hangupsbot

* The build script is out-of-date and will be removed in the future.
  DO NOT TRUST IT ;)
* To execute: `python3 hangupsbot.py`
  * If the script cannot find `config.json`, execute 
    `<path of hangupsbot.py>/python3 hangupsbot.py --config ../config.json`
* Any current tests will be in `<path of hangupsbot.py>/tests/`
* PushBullet integration is **experimental** - it also has a security risk: 
  since the only way to send pushes is via API key, the key has to be stored - 
  and is visible - inside `config.json`
  * To set your pushbullet key, open a 1-on-1 HO with the bot and issue:
    `/bot pushbulletapi [<api key>|false, 0, -1]`
    to set your api key or clear it, respectively.
* please also see the original documentation which is reproduced below
  (after the TODO section)

Additional requirements:
* https://pypi.python.org/pypi/jsonrpclib-pelix `pip3 install jsonrpclib-pelix`
* https://pypi.python.org/pypi/pushbullet.py/0.5.0 `pip3 install pushbullet.py`

# Users: Quickstart

1. You need to open a 1-on-1 conversation with the bot first and say "hello" 
   (or anything!)
2. Then give yourself a @mention in another HO where the bot is participating 
   as a group member

This procedure is necessary to let the bot know you're alive ;P 
No seriously, the above steps are **required** to authorise two-way 
communication between the bot and your own account.

# Admins: Installation & Configuration

* `config.json` is found in two places:
  * one folder below `hangupsbot.py`;and later,
  * ...in `/root/.local/share/hangupsbot/` after first successful run
* add (or replace) your *user id* into the `admins` array in config.json

```
{
  "admins": [
    "104821221116551390464"
  ],
  "autoreplies": [
  ...
```
To find out how to get your user id, read on!

## Getting Your User ID

### first time admins with no existing bot

1. start the bot with a valid gmail account (not your actual account!)
2. open a hangout with the bot (using your actual account), say anything to it
3. login into the bot's gmail account and ensure chat is activated
4. open up invites, and accept your incoming invite (from your actual account)
5. restart the bot and it will dump out a conversation and users list
6. find your actual account user name, the chat_id will be listed next to it

### with an existing bot

join a group with an existing bot and issue this command `/bot whoami`, your
chat_id will be displayed

# Admins: Useful Commands
```
# add user 104...64 to the admins list...
/bot config append admins "104...64"  
/bot reload

# remove user 104...64 from the admins list...
/bot config remove admins "104...64"
/bot reload
```

# GitLab Users: Web hooks sink/receiver

Partial support as a "sink" (receiver) for gitlab project webhooks is available. These
are preliminary instructions how to setup a webhook sink:

1. Determine which group hangout you want to receive GitLab events. In that 
   hangout, execute `/bot whereami` - the bot will message the id for that 
   specific hangout. Record the conversation id.
2. In your GitLab instance, access Project Settings > Web Hooks
3. Select which project events you want to be notified of and specify this URL:
   ```
   https://<your bot ip/domain name>:8000/<conversation id>/
   ```
   
4. After entering the above, **Add Web Hook**, test the hook.

# Developers: TODO

* easier setup/configuration
* run as service ([cron](http://www.raspberrypi-spy.co.uk/2013/07/running-a-python-script-at-boot-using-cron/) works too!)
* integration with gitlab (in progress)
* secure json-rpc
* better debug output<commit_msg>quick start guide for ssl configuration and starting the gitlab sink<commit_after># IMPORTANT

This is a fork of https://github.com/xmikos/hangupsbot

* The build script is out-of-date and will be removed in the future.
  DO NOT TRUST IT ;)
* To execute: `python3 hangupsbot.py`
  * If the script cannot find `config.json`, execute 
    `<path of hangupsbot.py>/python3 hangupsbot.py --config ../config.json`
* Any current tests will be in `<path of hangupsbot.py>/tests/`
* PushBullet integration is **experimental** - it also has a security risk: 
  since the only way to send pushes is via API key, the key has to be stored - 
  and is visible - inside `config.json`
  * To set your pushbullet key, open a 1-on-1 HO with the bot and issue:
    `/bot pushbulletapi [<api key>|false, 0, -1]`
    to set your api key or clear it, respectively.
* please also see the original documentation which is reproduced below
  (after the TODO section)

Additional requirements:
* https://pypi.python.org/pypi/jsonrpclib-pelix `pip3 install jsonrpclib-pelix`
* https://pypi.python.org/pypi/pushbullet.py/0.5.0 `pip3 install pushbullet.py`

# Users: Quickstart

1. You need to open a 1-on-1 conversation with the bot first and say "hello" 
   (or anything!)
2. Then give yourself a @mention in another HO where the bot is participating 
   as a group member

This procedure is necessary to let the bot know you're alive ;P 
No seriously, the above steps are **required** to authorise two-way 
communication between the bot and your own account.

# Admins: Installation & Configuration

* `config.json` is found in two places:
  * one folder below `hangupsbot.py`;and later,
  * ...in `/root/.local/share/hangupsbot/` after first successful run
* add (or replace) your *user id* into the `admins` array in config.json

```
{
  "admins": [
    "104821221116551390464"
  ],
  "autoreplies": [
  ...
```
To find out how to get your user id, read on!

## Getting Your User ID

### first time admins with no existing bot

1. start the bot with a valid gmail account (not your actual account!)
2. open a hangout with the bot (using your actual account), say anything to it
3. login into the bot's gmail account and ensure chat is activated
4. open up invites, and accept your incoming invite (from your actual account)
5. restart the bot and it will dump out a conversation and users list
6. find your actual account user name, the chat_id will be listed next to it

### with an existing bot

join a group with an existing bot and issue this command `/bot whoami`, your
chat_id will be displayed

# Admins: Useful Commands
```
# add user 104...64 to the admins list...
/bot config append admins "104...64"  
/bot reload

# remove user 104...64 from the admins list...
/bot config remove admins "104...64"
/bot reload
```

# GitLab Users: Web hooks Sink/Receiver

Partial support as a "sink" (receiver) for gitlab project webhooks is available. These
are preliminary instructions how to setup a webhook sink:

## configuring and starting the sink

Note: Still under development, subject to change

1. Generate a .pem file to enable SSL/TLS. It can be generated anywhere
   accessible to the script. A self-signed certificate will do:
   ```
   openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
   ```

2. If necessary, modify the location of the certificate file in the sink 
   [here](https://gitlab.sabah.io/eol/mogunsamang/blob/gitlab-integration/hangupsbot/sinks/gitlab/gitlab_translator.py#L88)
3. Start the sink **independently of the bot**, by running 
   ```python3 gitlab_translator.py```

## configuring gitlab

1. Determine which group hangout you want to receive GitLab events. In that 
   hangout, execute `/bot whereami` - the bot will message the id for that 
   specific hangout. Record the conversation id.
2. In your GitLab instance, access Project Settings > Web Hooks
3. Select which project events you want to be notified of and specify this URL:
   ```
   https://<your bot ip/domain name>:8000/<conversation id>/
   ```
   
4. After entering the above, **Add Web Hook**, test the hook.

# Developers: TODO

* easier setup/configuration
* run as service ([cron](http://www.raspberrypi-spy.co.uk/2013/07/running-a-python-script-at-boot-using-cron/) works too!)
* integration with gitlab (in progress)
* secure json-rpc
* better debug output
{'fraction_non_alphanumeric': 0.09154228855721393, 'fraction_numerical': 0.020398009950248756, 'mean_word_length': 3.6587485515643103, 'pattern_counts': {'":': 4, '<': 13, '<?xml version=': 0, '>': 15, 'https://': 9, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '691686', 'n_tokens_mistral': 2545, 'n_tokens_neox': 2368, 'n_words': 1110}