Filaxy Herald

Prerequisites

Before you begin, make sure you have the following installed and ready:

• Node.js 18+ (Vercel's serverless runtime requires at least Node 18; run node -v to check)
• npm (bundled with Node.js) or yarn
• A Vercel account — vercel.com (free tier is sufficient)
• The Vercel CLI installed globally:

  npm install -g vercel
  

• Accounts on the five external services listed below — all have free tiers, though two require a small prepaid credit balance:

| Service | Purpose | Cost | |---------|---------|------| | GitHub | Source of your public activity feed | Free | | Telegram | Approval inbox (receives drafts, sends ✅/❌) | Free | | Anthropic | Claude writes the posts | ~$5 prepaid (lasts months) | | X / Twitter Developer | Publishes approved posts | ~$0.02 per post | | Upstash | Redis — stores pending drafts between draft and approval | Free tier |

---

Get Your API Keys

Work through each service in order. You will collect these values for the configuration step.

1. Telegram Bot (~2 min)

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. BotFather will reply with a token like 110201543:AAHdqTcvCH1vGWJxfSeofSs4tHmC9Ok2piP. Save this as TELEGRAM_BOT_TOKEN.
4. Start a conversation with your new bot (search for it and press Start).
5. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser, send any message to the bot, then refresh. Find the "id" field inside "chat" — this is your personal chat ID. Save this as TELEGRAM_CHAT_ID.

2. Anthropic (Claude) API Key (~5 min)

1. Log in at console.anthropic.com.
2. Add ~$5 of prepaid credit under Billing (one-time; it lasts months at this usage level).
3. Go to API Keys → Create Key.
4. Save the key as ANTHROPIC_API_KEY. You will not be able to view it again.

3. X / Twitter Developer App (~15 min)

1. Go to developer.x.com and apply for a developer account if you haven't already.
2. Create a new Project and an App inside it.
3. Under App Settings → User authentication settings, enable OAuth 1.0a with Read and Write permissions.
4. From Keys and Tokens, generate all four credentials and save them:
   • API Key → TWITTER_API_KEY
   • API Key Secret → TWITTER_API_SECRET
   • Access Token → TWITTER_ACCESS_TOKEN
   • Access Token Secret → TWITTER_ACCESS_SECRET

4. Upstash Redis (~3 min)

1. Log in at upstash.com and create a new Redis database (select the region closest to your Vercel deployment).
2. On the database detail page, find the REST API section.
3. Save the two values:
   • REST URL → UPSTASH_REDIS_REST_URL
   • REST Token → UPSTASH_REDIS_REST_TOKEN

5. GitHub Username

No token is required. Herald reads the public events feed at https://api.github.com/users/<username>/events/public. Just note your exact GitHub username — you will set it as GITHUB_USERNAME.

---

Installation

# Clone the repository
git clone https://github.com/othmarodev/filaxy-herald.git
cd filaxy-herald

# Install dependencies
npm install

Run the TypeScript type-checker to confirm the project is intact:

npm run typecheck

No errors means you are ready to configure and deploy.

---

Configuration

Filaxy Herald is deployed as a Vercel project. Environment variables are set in Vercel's dashboard (or via the CLI), not in a local .env file that gets committed.

Create a .env file locally for development (it is already in .gitignore):

cp .env.example .env   # if the file exists, otherwise create it manually

Populate every variable listed below:

| Variable | Description | Where to get it | |----------|-------------|-----------------| | TELEGRAM_BOT_TOKEN | Secret token for your Telegram bot | BotFather (step 1) | | TELEGRAM_CHAT_ID | Your personal Telegram chat ID (numeric) | getUpdates API call (step 1) | | ANTHROPIC_API_KEY | Anthropic API key for Claude | Anthropic console (step 2) | | TWITTER_API_KEY | X app consumer key | X Developer Portal (step 3) | | TWITTER_API_SECRET | X app consumer secret | X Developer Portal (step 3) | | TWITTER_ACCESS_TOKEN | OAuth 1.0a access token (your account) | X Developer Portal (step 3) | | TWITTER_ACCESS_SECRET | OAuth 1.0a access token secret | X Developer Portal (step 3) | | UPSTASH_REDIS_REST_URL | HTTPS endpoint for your Upstash Redis database | Upstash dashboard (step 4) | | UPSTASH_REDIS_REST_TOKEN | Bearer token for Upstash REST API | Upstash dashboard (step 4) | | GITHUB_USERNAME | Your GitHub username (no @) | Your GitHub profile | | CRON_SECRET | A random secret that protects the /api/digest cron endpoint from unauthorized triggers | Generate with openssl rand -hex 32 |

---

Running the Bot

Deploy to Vercel (production)

# Log in to Vercel
vercel login

# Link this directory to a new Vercel project
vercel link

# Push all environment variables to Vercel
# Repeat this command for each variable (or set them in the Vercel dashboard under Settings → Environment Variables)
vercel env add TELEGRAM_BOT_TOKEN
vercel env add TELEGRAM_CHAT_ID
# ... repeat for every variable in the table above

# Deploy
vercel --prod

After deployment, Vercel will print your production URL, e.g. https://filaxy-herald-xyz.vercel.app. Save this URL.

Connect the Telegram Webhook (1 min)

Tell Telegram where to send button taps and commands. Run this once, replacing the placeholders:

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=https://<YOUR_VERCEL_URL>/api/telegram-webhook"

A successful response looks like:

{"ok":true,"result":true,"description":"Webhook was set"}

Local dry-run (development)

Before deploying, you can preview what Herald would post without actually publishing anything:

npm run dry-run

This runs scripts/dry-run.ts via tsx and prints the drafted post to your terminal. No Telegram message is sent and nothing is posted to X.

---

Testing

1. Verify the webhook is registered

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo"

Check that "url" matches your Vercel URL and "last_error_message" is absent.

2. Trigger a manual post with /announce

Open Telegram, find your bot, and send:

/announce filaxy-herald: just shipped the install guide for my build-in-public bot

Within a few seconds you should receive a Telegram message containing a draft post and ✅/❌ buttons. This confirms Claude, Redis, and the Telegram webhook are all wired up correctly.

Tap ✅ to confirm the full pipeline works — the post will be published to X.

3. Trigger the daily digest manually

curl -X POST "https://<YOUR_VERCEL_URL>/api/digest" \
  -H "Authorization: Bearer <CRON_SECRET>"

If your GitHub account has recent public activity, you will receive a Telegram approval request within seconds.

---

Troubleshooting

| Problem | Likely cause | Fix | |---------|-------------|-----| | Telegram bot sends nothing after /announce | Webhook URL is wrong or not set | Re-run the setWebhook curl command with your exact Vercel production URL and confirm getWebhookInfo returns it correctly | | 401 Unauthorized when calling /api/digest | CRON_SECRET in the request header doesn't match the environment variable | Verify the value set in Vercel matches what you're sending in the Authorization: Bearer header | | Claude returns an error / post is never drafted | ANTHROPIC_API_KEY is invalid or the account has no credit | Log in to console.anthropic.com, confirm the key is active, and check that your prepaid balance is above $0 | | Post draft appears in Telegram but X publish fails after tapping ✅ | X OAuth credentials are wrong or app lacks Write permission | Double-check all four TWITTER_* values in Vercel; confirm the X app's User authentication settings show Read and Write access | | getUpdates returns no messages when finding TELEGRAM_CHAT_ID | You haven't started a conversation with the bot