Metadata-Version: 2.1
Name: afk_slack_agent
Version: 0.1.0
Summary: Signal your A.F.K. status on Slack automatically
Home-page: https://github.com/keul/afk_slack_agent
Author: Luca Fabbri
Author-email: lucafbb@gmail.com
License: Apache Software License 2.0
Keywords: afk_slack_agent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
License-File: LICENSE
License-File: AUTHORS.rst

===============
AFK Slack Agent
===============


.. image:: https://img.shields.io/pypi/v/afk_slack_agent.svg
        :target: https://pypi.python.org/pypi/afk_slack_agent

Signal you A.F.K. (Away From Keyboard) status on Slack, automatically.

.. contents:: Table of Contents

.. warning::
    This software is for MacOS only!

Installation
============

.. code-block:: bash
   
   pip install afk_slack_agent

What it does?
=============

This software is distributed with an agent (``afk_agent``) and a client (``afk``, optional).

The agent is designed to be run in the background and stay active until you terminate it.

Features implemented by the agent

- waits for lock screen and unlock screen events
- connects to a Slack workspace, and change user status on lock (clean it on unlock)
- optionally: write a message on a channel on lock/unlock

Prerequisites
=============

- you have to `create a Slack application <https://api.slack.com/apps?new_app=1>`_, and install it into your workspace
  - the application should have at least the following `scope <https://api.slack.com/scopes>`_: ``users.profile:write``.
    
    optionally, you could also enable ``chat:write`` and ``reactions:write``
- to run custom AFK commands from the client, you'll need to enable the agent to control your Mac (from "Privacy and Security" system settings)

Configuration
=============

The first time the agent is run, a ``~/.afk.json`` file is created.

This is the default file created:

.. code-block:: json
   
   {
     "version": 1,
     "token": "",
     "status_text": "I need a break",
     "status_emoji": ":coffee:",
     "channel": null,
     "away_message": "I'm going to take a coffee break",
     "back_message": "I'm back",
     "delay_for_reaction_emoji": 60,
     "back_emoji": "back",
     "agent_emoji": "robot_face",
     "actions": [
       {
         "action": "lunch",
         "status_text": "Lunch break",
         "status_emoji": ":spaghetti:",
         "away_message": "I'm going to take the lunch break",
         "back_message": "I'm back and stuffed!",
         "command": "lock"
       }
     ]
   }

The most important key is ``token``, which must contain the Slack User OAuth Token.

.. image:: https://raw.githubusercontent.com/keul/afk_slack_agent/main/docs/slack-key.png
        :alt: Slack configuration, where to grab your token

Other settings
--------------

``status_text``
  Status to be set when locking the screen

``status_emoji``
  emoji to be set when locking the screen

``channel``
  use this only if you want to write messages on a channel when going AFK and be back.
  
  Put the channel id there. You can find it by right-clicking on the channel and clicking "View channel details".
  It will be at the very bottom of the popup.

``away_message``
  message to send when going  AFK

``back_message``
  message to send when back to keyboard

``delay_for_reaction_emoji``
  in case you will be back before this amount of seconds, do not send a back message, but just react to your away message using a reaction emoji.
  This will reduce noise in case of quick lock/unlock screen

``back_emoji``
  emoji to be used for quick back reaction

``agent_emoji``
  automatically adds this emoji at the end of every message sent or slack status set.
  This helps others to know there's a bot that is acting for you.

``delay_after_screen_lock``
  before starting interacting with Slack, wait this amount of seconds.

  This will delay reactions to your lock screen status a while, so no Slack commands will be run if you unlock the screen before this time.
  As example: you are reading a document and the screen locks for inactivity, but you are not AFK.

Custom actions
~~~~~~~~~~~~~~

The JSON configuration can contain an ``actions`` key, with an array of custom actions.

Custom actions can be sent to the agent using the client component:

.. code-block:: bash
   
   afk lunch

A custom action is a way to perform something more than the standard lock/unlock monitor.

See the ``afk`` command line help for more.

An action interact with Slack in the same way the agent does, and inherit the same configuration, but it can override some of them like: ``status_text``, ``status_emoji``, ``away_message`` and ``back_message``.
Every of these settings can be ``null`` to explicitly inherit from the global settings.
``back_message`` can also be ``false``: this disables the back message for the action even if the global setting has a value.

Finally, a custom action can perform one of the following commands:

``lock``
  Lock the screen manually

``sleep``
  Put you computer to sleep

Why?
====

To understand motivation about this tool, read `why I needed to join my lock screen activities with Slack <https://blog.keul.it/automate-slack-afk-status/>`_.
