Worklog Bot

This project collects activity from:

• Google Calendar
• Jira
• WakaTime
• GitHub

It builds a daily summary and sends it to Slack.

Requirements

• Node.js 20+
• npm
• A Slack incoming webhook
• At least one enabled integration with valid credentials

Install

npm install

Run

npm start

To validate the TypeScript project:

npm run typecheck

Enable Or Disable Integrations

Edit integrations.config.ts:

export const INTEGRATIONS = {
  googleCalendar: true,
  jira: true,
  wakatime: true,
  github: true,
};

Set any integration to false to skip it.

Environment Variables

Create a .env file in the project root. You can start from .env.example.

Example:

SLACK_WEBHOOK_URL=
GOOGLE_CALENDAR_ID=primary
JIRA_BASE_URL=
JIRA_EMAIL=
JIRA_API_TOKEN=
JIRA_ACCOUNT_ID=
JIRA_DISPLAY_NAME=
WAKATIME_API_KEY=
GITHUB_TOKEN=
GITHUB_USERNAME=
GITHUB_REPOS=

Step By Step: How To Get Each Value

1. SLACK_WEBHOOK_URL

Used to send the final summary message to Slack.

How to get it:

1. Go to https://api.slack.com/apps
2. Click Create New App
3. Choose From scratch
4. Give the app a name and select your Slack workspace
5. Open Incoming Webhooks
6. Enable Activate Incoming Webhooks
7. Click Add New Webhook to Workspace
8. Choose the channel where the summary should be posted
9. Authorize the app
10. Copy the webhook URL

How to set it:

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

2. GOOGLE_CALENDAR_ID

Used to choose which Google Calendar will be queried. This is optional. If omitted, the app uses primary.

How to get it:

1. Open Google Calendar
2. In the left sidebar, find the calendar you want to use
3. Click the ... next to that calendar
4. Open Settings and sharing
5. Scroll to Integrate calendar
6. Copy the Calendar ID

How to set it:

GOOGLE_CALENDAR_ID=primary

Or:

GOOGLE_CALENDAR_ID=your-calendar-id@group.calendar.google.com

3. JIRA_BASE_URL

Used as the base URL for all Jira API requests.

How to get it:

1. Open your Jira site in the browser
2. Copy the site root URL
3. Remove any page-specific path

Example:

• If your Jira page is https://your-company.atlassian.net/jira/software/projects/ABC/boards/1
• Then your base URL is https://your-company.atlassian.net

How to set it:

JIRA_BASE_URL=https://your-company.atlassian.net

4. JIRA_EMAIL

Used to authenticate Jira API requests and help identify your comments.

How to get it:

1. Use the email address of your Atlassian account
2. You can confirm it from your Atlassian profile if needed

How to set it:

JIRA_EMAIL=you@company.com

5. JIRA_API_TOKEN

Used together with JIRA_EMAIL for Jira API authentication.

How to get it:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Enter a label like worklog-bot
4. Create the token
5. Copy the token immediately

How to set it:

JIRA_API_TOKEN=your-jira-api-token

6. JIRA_ACCOUNT_ID

Optional, but recommended. Helps the bot detect which Jira comments are yours.

How to get it:

1. Open Jira
2. Open any issue where you have commented
3. Open the browser developer tools and inspect Jira API responses, or use the Atlassian profile APIs if your admin allows it
4. Look for your Atlassian accountId

Simpler alternative:

1. Leave this blank at first
2. Set JIRA_DISPLAY_NAME
3. Test the bot
4. Only add JIRA_ACCOUNT_ID later if comment detection is inconsistent

How to set it:

JIRA_ACCOUNT_ID=your-atlassian-account-id

7. JIRA_DISPLAY_NAME

Optional, but recommended. Also helps the bot match your Jira comments.

How to get it:

1. Open Jira
2. Click your avatar
3. Copy your display name exactly as shown

How to set it:

JIRA_DISPLAY_NAME=Your Name

8. WAKATIME_API_KEY

Used to read your coding activity from WakaTime.

How to get it:

1. Log in to https://wakatime.com
2. Open Settings
3. Open Account or API Key
4. Copy your API key

How to set it:

WAKATIME_API_KEY=waka_xxxxxxxxxxxxxxxxx

9. GITHUB_TOKEN

Used to query pull requests, comments, reviews, and commits.

How to get it:

1. Log in to GitHub
2. Go to Settings
3. Open Developer settings
4. Open Personal access tokens
5. Choose either Tokens (classic) or Fine-grained tokens
6. Create a token with read access to the repositories you want to inspect

Recommended access:

• Pull requests: read
• Issues: read
• Metadata: read
• Contents: read

How to set it:

GITHUB_TOKEN=github_token_here

10. GITHUB_USERNAME

Used to identify your own GitHub activity.

How to get it:

1. Open GitHub
2. Click your profile picture
3. Copy your username from your profile URL or profile header

How to set it:

GITHUB_USERNAME=your-github-username

11. GITHUB_REPOS

Comma-separated list of repositories the bot should inspect.

How to get it:

1. Open each repository in GitHub
2. Copy the owner/repo value from the URL
3. Join multiple repos with commas and no line breaks

Example:

GITHUB_REPOS=owner-one/repo-one,owner-two/repo-two

Google Calendar OAuth Files

Google Calendar does not use only .env. It also needs:

• credentials.json
• token.json

credentials.json

How to get it:

1. Open https://console.cloud.google.com/
2. Create or select a Google Cloud project
3. Enable the Google Calendar API for that project
4. Go to APIs & Services -> Credentials
5. Click Create Credentials
6. Choose OAuth client ID
7. If prompted, configure the consent screen first
8. Choose Desktop app
9. Create the credential
10. Download the JSON file
11. Save it in the project root as credentials.json

token.json

This file contains the OAuth access and refresh token after authorizing the app.

How to create it:

1. Use the credentials.json file above
2. Run an OAuth flow once using the same Google account that owns the calendar
3. Save the resulting token payload as token.json in the project root

Important:

• token.json is user-specific
• credentials.json and token.json should not be committed to a public repository

Which Variables Are Required?

Always required:

• SLACK_WEBHOOK_URL

Required only if that integration is enabled:

• Google Calendar: GOOGLE_CALENDAR_ID is optional, but credentials.json and token.json are required
• Jira: JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN
• WakaTime: WAKATIME_API_KEY
• GitHub: GITHUB_TOKEN, GITHUB_USERNAME

Recommended optional values:

• JIRA_ACCOUNT_ID
• JIRA_DISPLAY_NAME
• GITHUB_REPOS

Notes

• If GITHUB_REPOS is empty, GitHub integration will not return repository activity.
• If GOOGLE_CALENDAR_ID is not set, the bot uses primary.
• The app timezone and integration endpoints are defined in app.config.ts.
• The app currently reads meetings, Jira work and comments, WakaTime file activity, and GitHub pull request activity for the current day.

Security

• Do not commit .env, credentials.json, or token.json
• Rotate any token immediately if it has been exposed
• Prefer least-privilege GitHub and Jira tokens