======
README
======

Signald python bindings
=======================

Most of the content here is generated by the ``generate.py`` script
that uses `<https://signald.org/protocol.json>`_.

Install
-------

``pip install aiosignald``

Have signald running. See `their docs <https://signald.org/articles/install/>`_ about it.

Usage
-----

Example: echo bot
*****************

.. code:: python

    import asyncio

    from aiosignald import SignaldAPI
    import aiosignald.generated as api

    class EchoBot(SignaldAPI):
        async def handle_IncomingMessage(self, msg: api.IncomingMessagev1, _payload):
            # hook to the incoming event by naming you function handle_EventName
            # most stuff comes through an IncomingMessage anyway
            print("Received: ", msg)
            if (data_msg := msg.data_message) and (body := data_msg.body):
                await self.send(
                    username=PHONE_NUMBER,
                    recipientAddress=msg.source,
                    messageBody=body
                )

    async def main():
        loop = asyncio.get_running_loop()
        _, signald = await loop.create_unix_connection(
            EchoBot, path=SIGNALD_SOCKET_PATH)
        if ACCOUNT_TYPE == "primary":
            await signald.register(account=PHONE_NUMBER)
            # Some async code to get the SMS code
            code = await user_input("Enter your sms code?")
            await signald.verify(account=PHONE_NUMBER, code=code)
        else:
            # linking to an existing account is also possible
            resp = await signald.generate_linking_uri()
            print("Make this a QR code and scan it on your primary signal device:", resp.uri)
            await signald.finish_link(device_name="friendly-device-name", session_id=resp.session_id)
        await signald.on_con_lost

    # See https://signald.org/articles/protocol/ for more info about this
    SIGNALD_SOCKET_PATH = "/var/run/signald/signald.sock"
    PHONE_NUMBER = "+XXXXXX"
    ACCOUNT_TYPE = "primary"

    asyncio.run(main())