align

README

Align

Easily schedule nights to meet with friends!

Table of Contents

1. About
   • Built With
2. Getting Started
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About

Align is a scheduling tool that allows users to schedule events with other users. It is designed to be modular, so that users can easily receive schedule reminders and updates through different platforms. Align's uses a configuration file combined with user-controlled sessions to seamlessly integrate with your own custom tools.

Currently, align allows you to contact users through Discord or Telegram. More outreach methods are planned in the future!

Check out align's example usages here.

(back to top)

Built With

• Golang
• Cron
• Discord Go
• Telegram-Bot-API

(back to top)

Getting Started

To get started with align, you can follow one of the ready-made examples here.

The general gist of align is as follows:

• You have a project that utilizes a session (Discord, Telegram, etc)
• You have an align configuration file
• You initialize an align manager using your provided config file that attaches itself to the running session

In doing this, you can attach align ontop of other programs, such as a ready-made Discord/Telegram bot.

(back to top)

Usage

Examples can be found here. Existing examples include:

• Discord Implementation.
• Telegram Implementation.
• Multi-Module Implementation.

These examples show how align can be attached to already-running sessions with an example configuration file.

For more details, please refer to the documentation.

(back to top)

Roadmap

• Allow for different request/response methods
• Add SMS outreach method

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

For issues and suggestions, please include as much useful information as possible. Review the documentation and make sure the issue is actually present or the suggestion is not included. Please share issues/suggestions on the issue tracker.

For patches and feature additions, please submit them as pull requests. Please adhere to the conventional commits. standard for commit messaging. In addition, please try to name your git branch according to your new patch. These standards are a great guide you can follow.

You can follow these steps below to create a pull request:

1. Fork the Project
2. Create your Feature Branch (git checkout -b branch_name)
3. Commit your Changes (git commit -m "commit_message")
4. Push to the Branch (git push origin branch_name)
5. Open a Pull Request

(back to top)

License

This project uses the Apache 2.0 License. You can find more information in the LICENSE file.

(back to top)

Contact

Ethan Baker - contact@ethanbaker.dev - LinkedIn

Project Link: https://github.com/ethanbaker/align

(back to top)

Acknowledgments

• All the friendgroups out there who struggle to connect regularly!

(back to top)

Documentation

Overview

Align is a scheduling tool that allows users to schedule events with other users. It is designed to be modular, so that users can easily receive schedule reminders and updates through different platforms. Align's configuration file has settings described below:

```yaml settings:

title: "Group Meetup"        # Title of the event
interval: 7                  # How many days to ask for availability
offset: 2                    # How many days past the contact time to ask for availability
timezone: "America/New_York" # Timezone that cron strings are based on
contact_time: "0 10 * * 0"   # Contact time cron string (Sunday at 10:00 AM)
deadline_time: "0 10 * * 1"  # Deadline time cron string (Monday at 10:00 AM)

persons:

• name: "Person 1" # Name of the person request_method: "discord" # Method to request information from response_method: "discord" # Method to respond with information id: "PERSONS_ID" # Identifiying string for the person (Discord ID, Telegram ID, etc.)

• name: "Person 2" ...

```

Currently, the `request_method` and `response_methods` must be the same value, but this will be changed in future updates.

Examples for each module can be found in the 'examples/' directory. These directories contain the most barebones setup align needs to function. If you are using align in a more complicated package, you can provide the same types in the examples to get align working.

## SQL

Align has an option to use SQL to store availability data. This is useful if align ever stops running (server resetting, power outages, etc). If align is restarted without persisting data, the availability data may be lost, and the subsequent schedule alignment may be incorrect (align tries to mitigate this fact as much as possible, but some necessary data cannot be recovered in this case, such as discord message IDs).

You can provide SQL credentials to the align configuration file to use SQL. The yaml format is as follows:

```yaml sql:

user: SQL_USER
passwd: SQL_PASSWD
net: SQL_NET
addr: SQL_ADDR
dbname: SQL_DBNAME

```

## Discord

Discord is easy to set up with align. Simply providing a Discord session to align will allow it to send and receive messages. Keep in mind that, in order for a Discord bot to send a message to a user, it must be in a mutual server with said user. This is a limitation of the Discord API, and align cannot bypass this.

To collect Discord IDs, you can right click on a profile you want to contact and click 'Copy User ID.' You can provide this information to align's configuration file.

## Telegram

To initialize telegram with align, you can start a telegram session using [telegram-bot-api](https://github.com/go-telegram-bot-api/telegram-bot-api). This package is used to interact with the Telegram Bot API. Once you have started this session, align can use it to send and receive messages for easy and convienient scheduling.

However, Telegram is more difficult to set up and maintain with align. These constraints originate from the [Telegram Bot API](https://core.telegram.org/bots/api) itself. These reasons are: * Telegram bots are not allowed to send messages to users who have not initiated some sort of conversation with the bot * Telegram servers only store updates for 24 hours, so if the bot is down for more than 24 hours, it may not receive poll updates

So, to use Telegram with align, you must: * Have users initiate a conversation with the bot using '/start', or clicking the bottom of the bar when messaging the bot. The bot does not have to be online, but it must be activated within 24 hours to receive the update * Keep the bot online at least once every 24 hours so it can receive updates from telegram. If the bot is down for more than 24 hours, it may not receive poll updates and return incorrect schedule times

The best way to do this in practice is to approach the user you want to contact using Telegram and have them start a conversation with the bot while the bot is online (or during the 24 hour update period). This way, the bot can send messages to the user without any issues. Secondly, you need to receive this user's Telegram User ID (not username). This can be done by having that user message '@userinfobot', clicking 'start', and recording the 'User Id Information' field.

Index

• Constants
• func DiscordGather(person Person, manager *Manager) error
• func DiscordRequest(person Person, manager *Manager) error
• func DiscordResponse(person Person, manager *Manager, days []day, unknowns []string, available int) error
• func InitDiscord(manager *Manager, s *discordgo.Session)
• func InitTelegram(manager *Manager, s *telegram.BotAPI)
• func TelegramGather(person Person, manager *Manager) error
• func TelegramRequest(person Person, manager *Manager) error
• func TelegramResponse(person Person, manager *Manager, days []day, unknowns []string, available int) error
• type AvailabilityMap
  • func (m *AvailabilityMap) Scan(value interface{}) error
  • func (m AvailabilityMap) Value() (driver.Value, error)
• type Config
• type DSN
• type DiscordConfig
• type Manager
  • func CreateManager(name string, path string, options Options) (*Manager, error)
  • func (m *Manager) OnCompletion()
  • func (m *Manager) OnContact()
• type Options
• type Person
• type Settings
• type TelegramConfig

Constants

const DAY_DURATION = int(time.Hour * 24)

Constant for a day's duration

const TIME_FORMAT = "Monday 01/02"

How the days will be formatted

Functions

func DiscordGather

func DiscordGather(person Person, manager *Manager) error

Read a response for availability using discord

func DiscordRequest

func DiscordRequest(person Person, manager *Manager) error

Request an availability schedule using discord

func DiscordResponse

func DiscordResponse(person Person, manager *Manager, days []day, unknowns []string, available int) error

Send a user a response summary on discord

func InitDiscord

func InitDiscord(manager *Manager, s *discordgo.Session)

Initialize a discord config

func InitTelegram

func InitTelegram(manager *Manager, s *telegram.BotAPI)

Initialize a telegram config

func TelegramGather

func TelegramGather(person Person, manager *Manager) error

Read a response for availability using telegram

func TelegramRequest

func TelegramRequest(person Person, manager *Manager) error

Request an availability schedule using telegram

func TelegramResponse

func TelegramResponse(person Person, manager *Manager, days []day, unknowns []string, available int) error

Send a user a response summary on telegram

Types

type AvailabilityMap

type AvailabilityMap map[string]bool

func (*AvailabilityMap) Scan

func (m *AvailabilityMap) Scan(value interface{}) error

func (AvailabilityMap) Value

func (m AvailabilityMap) Value() (driver.Value, error)

type Config

type Config struct {
	// Persons to run the application for
	Persons []Person `yaml:"persons"` // A list of persons to contact

	// SQL Credentials
	Dsn *DSN `yaml:"sql,omitempty"`

	// Application configuration settings
	Settings `yaml:"settings"`
}

Config represents the configuration align will run off of

type DSN

type DSN struct {
	User   string `yaml:"user"`
	Passwd string `yaml:"passwd"`
	Net    string `yaml:"tcp"`
	Addr   string `yaml:"addr"`
	DBName string `yaml:"dbname"`
}

DSN represents sql credentials for the service

type DiscordConfig

type DiscordConfig struct {
	Session *discordgo.Session
}

DiscordConfig holds all necessary fields for discord request/response functions to run successfully

type Manager

type Manager struct {
	gorm.Model
	Name       string       `gorm:"uniqueIndex,length:256"` // The name identifier for the manager
	ContactDay sql.NullTime // The day persons are contacted
	// contains filtered or unexported fields
}

Manager struct represents a top level manager class

func CreateManager

func CreateManager(name string, path string, options Options) (*Manager, error)

Create and initialize a new manager

func (*Manager) OnCompletion

func (m *Manager) OnCompletion()

OnCompletion runs when the person deciding time completes

func (*Manager) OnContact

func (m *Manager) OnContact()

OnContact contacts the persons listed in the config using their preferred method

type Options

type Options struct {
	// Whether or not align should use an SQL database to persist messages in case of power outages/etc
	UseSQL bool
}

Options struct is used to provide custom options when creating a manager

type Person

type Person struct {
	Name           string `yaml:"name"`            // The person's name
	RequestMethod  string `yaml:"request_method"`  // The person's ideal contact method for availability requests
	ResponseMethod string `yaml:"response_method"` // The person's ideal contact method for responses
	ID             string `yaml:"id"`              // The person's ID used to contact them with a given method
}

Person represents a contactable person who provides feedback on what days they are free

type Settings

type Settings struct {
	Title           string `yaml:"title"`         // The title of the group
	Interval        int    `yaml:"interval"`      // How many days to get availability for each cycle
	Offset          int    `yaml:"offset"`        // How many days after the contact date should availability gathering start
	ContactTimezone string `yaml:"timezone"`      // The timezone in which to contact persons
	ContactTime     string `yaml:"contact_time"`  // A cron string that shows when the persons should be contacted
	DeadlineTime    string `yaml:"deadline_time"` // A cron string that shows when the final decision should be made
}

Settings represent general configuration settings

type TelegramConfig

type TelegramConfig struct {
	Session *telegram.BotAPI
	Updates *telegram.UpdatesChannel
}

TelegramConfig holds all necessary fields for telegram request/response functions to run successfully