@www.hyperlinks.space/program-kit 1.2.3

package/fullREADME.md

@@ -0,0 +1,159 @@
+# Welcome to your Expo app 👋
+This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
+
+## Get started
+
+To start the app (and the Telegram bot in polling mode), run:
+
+```bash
+npm run start
+```
+
+This runs both the Expo dev server and the bot. For Expo only (no bot), use `npm run start:expo`.
+
+## Milestone snapshot package (npm)
+
+This repository includes a publishable snapshot package for fast developer bootstrap:
+
+- package source: `app/` (published directly, no duplicate snapshot folder)
+- **npmjs (public):** `@www.hyperlinks.space/program-kit` — manage org and tokens: [www.hyperlinks.space on npm](https://www.npmjs.com/settings/www.hyperlinks.space/packages)
+- **GitHub Packages:** `@hyperlinksspace/program-kit` (same version; GitHub requires the package scope to match this repo’s owner)
+
+**npm ownership:** your token must be allowed to publish under scope `@www.hyperlinks.space` (org members or automation token with access to that org).
+
+### Verify publish payload locally
+
+The npm package page uses `README.md` from the published tarball, not `npmReadMe.md`. The published package also includes **`fullREADME.md`**, a copy of this developer readme (saved before the npm readme replaces `README.md`). Match CI before `npm pack`, then restore:
+
+```bash
+cp README.md fullREADME.md
+cp npmReadMe.md README.md
+npm pack --dry-run
+git checkout -- README.md
+rm -f fullREADME.md
+```
+
+### Install snapshot as a developer
+
+```bash
+npx @www.hyperlinks.space/program-kit ./my-hsp-app
+```
+
+The CLI materializes the bundled package payload into your target folder, then you run:
+
+```bash
+cd my-hsp-app
+npm install
+```
+
+### Release channels
+
+- `latest`: immutable stable snapshots (tag workflow `snapshot-vX.Y.Z`)
+- `next`: rolling snapshots from manual workflow dispatch
+
+In the output, you'll find options to open the app in:
+
+- [a development build](https://docs.expo.dev/develop/development-builds/introduction/)
+- [an Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
+- [an iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
+- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
+
+You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
+
+### Local env setup
+
+1. **Copy the example file** (from the `app/` directory):
+   ```bash
+   cp .env.example .env
+   ```
+2. **Edit `.env`** and set at least:
+   - **`BOT_TOKEN`** – if you run the Telegram bot locally (`npm run bot:local`).
+3. **Expo app** – `npx expo start` reads env from the environment; for app-only env vars you can also put them in `.env` and use an Expo-compatible loader if you add one, or set them in the shell before running:
+   ```bash
+   export BOT_TOKEN=your_token
+   npx expo start
+   ```
+4. **Bot local** – `npm run bot:local` loads `.env` from the project root (optional; you can also set `BOT_TOKEN` in the shell).
+
+The `.env` file is gitignored; do not commit it.
+
+## Workflows
+
+This project is configured to use [EAS Workflows](https://docs.expo.dev/eas/workflows/get-started/) to automate some development and release processes. These commands are set up in [`package.json`](./package.json) and can be run using NPM scripts in your terminal.
+
+### Previews
+
+Run `npm run draft` to [publish a preview update](https://docs.expo.dev/eas/workflows/examples/publish-preview-update/) of your project, which can be viewed in Expo Go or in a development build.
+
+### Development Builds
+
+Run `npm run development-builds` to [create a development build](https://docs.expo.dev/eas/workflows/examples/create-development-builds/). Note - you'll need to follow the [Prerequisites](https://docs.expo.dev/eas/workflows/examples/create-development-builds/#prerequisites) to ensure you have the correct emulator setup on your machine.
+
+### Production Deployments
+
+Run `npm run deploy` to [deploy to production](https://docs.expo.dev/eas/workflows/examples/deploy-to-production/). Note - you'll need to follow the [Prerequisites](https://docs.expo.dev/eas/workflows/examples/deploy-to-production/#prerequisites) to ensure you're set up to submit to the Apple and Google stores.
+
+## Hosting
+
+Expo offers hosting for websites and API functions via EAS Hosting. See the [Getting Started](https://docs.expo.dev/eas/hosting/get-started/) guide to learn more.
+
+### Deploy web build to Vercel
+
+From this directory (`app/`), deploy the static web build to Vercel production:
+
+```bash
+vercel --prod
+```
+
+Deploying from `app/` makes this folder the project root, so `api/bot` is deployed and no Root Directory setting is needed. The project is configured so Vercel runs `npx expo export -p web` and serves the `dist/` output. Link the project first with `vercel` if needed.
+
+### Telegram bot (Grammy)
+
+A minimal bot that replies "Hello" is included. It is deployable on Vercel via webhook and runnable locally with getUpdates.
+
+**Vercel (webhook)**  
+- **Env for deploy:** In Vercel → **Settings → Environment Variables** add **`BOT_TOKEN`** (or `TELEGRAM_BOT_TOKEN`). Assign to **Production** (and to **Build** if your dashboard has that option) so the deploy-step webhook script can run. The webhook URL is built from Vercel’s `VERCEL_PROJECT_PRODUCTION_URL` or `VERCEL_URL`.
+- **Webhook on deploy:** Each build runs `scripts/set-webhook.ts` and calls Telegram `setWebhook` with the base URL + `/api/bot`. If the script fails (e.g. missing URL or Telegram error), the build fails so you see the error in the deploy log.
+- Telegram sends updates to **POST** `/api/bot`; the bot replies "Hello".
+
+**Bot works locally but not on Vercel**  
+1. Open **GET** `https://<your-app>.vercel.app/api/bot` in a browser. The JSON shows:
+   - `bot: true` → BOT_TOKEN is set; `bot: false` → add BOT_TOKEN in Vercel → Settings → Environment Variables (Production), then redeploy.
+   - `expected_url` → URL we use for the webhook (from VERCEL_PROJECT_PRODUCTION_URL or VERCEL_URL).
+   - `telegram_has` → URL Telegram actually has. It must match your production URL (e.g. `https://hsbexpo.vercel.app/api/bot`). If it’s `(none)` or different, ensure the project’s production domain is set in Vercel and redeploy so set-webhook.ts runs with the correct URL.
+   - `webhook_set: true` → last setWebhook call succeeded.
+2. **Root directory:** Only needed if you deploy via Git (auto-deploy from the repo). Then set **Root Directory** to **`app`** in Vercel → Project Settings → General. If you always run `vercel --prod` from inside `app/`, the CLI uses this folder as the project root and you don’t need to set it.
+3. **Logs:** After sending /start, check **Logs** for `[webhook] POST update` and any `[bot]` errors (e.g. handler_error, timeout).
+4. Don’t run the same bot in polling locally while testing the webhook (or Telegram may deliver updates to the wrong place).
+
+**Local (getUpdates, no webhook)**  
+- Only `BOT_TOKEN` is required (in env or `.env`).
+- Run the bot in polling mode (do not use the same token with webhook set elsewhere):
+  ```bash
+  npx tsx scripts/run-bot-local.ts
+  ```
+- `npm run start` runs both Expo and the bot; or run the bot alone with `npm run bot:local`.
+
+## Get a fresh project
+
+When you're ready, run:
+
+```bash
+npm run reset-project
+```
+
+This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing.
+
+## Learn more
+
+To learn more about developing your project with Expo, look at the following resources:
+
+- [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides).
+- [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.
+
+## Join the community
+
+Join our community of developers creating universal apps.
+
+- [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute.
+- [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions.

package/global.css

@@ -0,0 +1,67 @@
+/* Global web-only overrides */
+
+/* Lock the app column to the viewport so the whole block is not scrollable (avoids logo bar jump in TMA when keyboard opens). */
+html {
+  height: 100%;
+  overflow: hidden;
+  overscroll-behavior: none;
+  background-color: var(--tg-theme-bg-color, transparent);
+}
+body {
+  height: var(--tg-viewport-height, 100%);
+  min-height: var(--tg-viewport-height, 100%);
+  overflow: hidden;
+  overscroll-behavior: none;
+  /* TMA: Telegram sets --tg-theme-bg-color early; fills gap before React shows the app (no dark flash). */
+  background-color: var(--tg-theme-bg-color, transparent);
+}
+
+/* TMA: --tg-viewport-height is set and updated by TMA SDK viewport.bindCssVars() on viewport_changed only. */
+#root,
+[data-expo-root] {
+  height: var(--tg-viewport-height, 100%);
+  min-height: var(--tg-viewport-height, 100%);
+  overflow: hidden;
+  background-color: var(--tg-theme-bg-color, transparent);
+}
+
+/* Hide native textarea scrollbars (React Native Web TextInput) while keeping scroll behaviour. */
+textarea {
+  -ms-overflow-style: none; /* IE and Edge */
+  scrollbar-width: none; /* Firefox */
+}
+
+textarea::-webkit-scrollbar {
+  display: none; /* Chrome, Safari, Opera */
+}
+
+/* Make the AI & Search textarea truly 20px tall for one line */
+textarea[data-ai-input="true"] {
+  min-height: 20px !important;
+  height: 20px !important;
+  line-height: 20px !important;
+  padding-top: 0 !important;
+  padding-bottom: 0 !important;
+  border: none !important;
+  box-sizing: content-box;
+}
+
+/* GlobalBottomBarWeb: placeholder + same font stack as inline (see app/fonts.ts). */
+[data-global-bottom-bar-web] {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  background-color: transparent !important;
+  font-family: Aeroport, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
+    Roboto, "Helvetica Neue", Arial, sans-serif !important;
+}
+
+[data-global-bottom-bar-web]::-webkit-scrollbar {
+  width: 0;
+  height: 0;
+}
+
+[data-global-bottom-bar-web]::placeholder {
+  color: var(--ai-placeholder-color, #fafafa);
+  opacity: 1;
+}
+

package/npmReadMe.md

@@ -0,0 +1,53 @@
+# Program Kit
+
+Program Kit is a production-ready cross-platform starter published from `app/`.
+It is built around React Native + Expo and is designed to be quickly tested, scaled,
+and deployed across popular platforms.
+
+## What You Get
+
+- Expo + React Native app foundation
+- Telegram bot support (webhook + local bot scripts)
+- Telegram Mini App-ready client structure
+- Android and iOS workflow scripts
+- Windows desktop packaging (`.exe`) with Electron Builder
+- CI-oriented release workflow and deployment helpers
+
+## Install
+
+### npmjs (public)
+
+```bash
+npx @www.hyperlinks.space/program-kit ./my-new-program
+```
+
+### GitHub Packages
+
+```bash
+npx @hyperlinksspace/program-kit ./my-new-program
+```
+
+If you install from GitHub Packages, configure `.npmrc` with the `@hyperlinksspace`
+registry and token.
+
+## After Scaffold
+
+```bash
+cd my-new-program
+npm install
+npm run start
+```
+
+Then open the project `README.md` for full setup details (env vars, bot setup, build
+and release commands).
+
+## Release Channels
+
+- `latest` for stable milestone snapshots
+- `next` for rolling preview snapshots
+
+## Notes
+
+- Published directly from the `app/` folder.
+- Package tarball is filtered to include only required project files.
+- **`fullREADME.md`** in the package is the full in-repo developer guide (Expo setup, scripts, and the rest of the project readme).

package/package.json

@@ -0,0 +1,214 @@
+{
+  "name": "@www.hyperlinks.space/program-kit",
+  "productName": "Hyperlinks Space Program",
+  "description": "Hyperlinks Space Program",
+  "author": "sraibaby",
+  "license": "0BSD",
+  "private": false,
+  "bin": {
+    "program-kit": "scripts/program-kit-init.cjs"
+  },
+  "files": [
+    "README.md",
+    "fullREADME.md",
+    "npmReadMe.md",
+    "app",
+    "api",
+    "app.json",
+    "assets",
+    "blockchain",
+    "bot",
+    "database",
+    "docs",
+    "!docs/debug.log",
+    "!docs/issue.md",
+    "eas.json",
+    "eslint.config.js",
+    "global.css",
+    "package-lock.json",
+    "scripts",
+    "telegram",
+    "tsconfig.json",
+    "vercel.json",
+    "windows"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HyperlinksSpace/HyperlinksSpaceBot.git"
+  },
+  "main": "expo-router/entry",
+  "version": "1.2.3",
+  "type": "module",
+  "engines": {
+    "node": ">=18 <=22"
+  },
+  "config": {
+    "forge": "./windows/forge/forge.config.js"
+  },
+  "scripts": {
+    "prestart": "npm run db:migrate",
+    "build": "expo export -p web",
+    "start": "npx concurrently -n expo,bot,vercel \"expo start\" \"npx tsx scripts/run-bot-local.ts\" \"npm run dev:vercel\"",
+    "start:expo": "expo start",
+    "reset-project": "node ./scripts/reset-project.js",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "dev:vercel": "cross-env TS_NODE_PROJECT=api/tsconfig.json npx vercel dev",
+    "lint": "expo lint",
+    "draft": "npx eas-cli@latest workflow:run create-draft.yml",
+    "development-builds": "npx eas-cli@latest workflow:run create-development-builds.yml",
+    "deploy": "npx eas-cli@latest workflow:run deploy-to-production.yml",
+    "deploy:vercel": "npx vercel --prod",
+    "bot:local": "npx tsx scripts/run-bot-local.ts",
+    "set-webhook": "npx tsx scripts/set-webhook.ts",
+    "db:migrate": "npx tsx scripts/migrate-db.ts",
+    "build:win": "node windows/build-with-progress.cjs",
+    "build:win:raw": "npm run build && node windows/run-win-electron-builder.cjs",
+    "pack:win": "node windows/build-with-progress.cjs --pack",
+    "pack:win:raw": "node windows/run-win-electron-builder.cjs",
+    "build:win:dir": "npm run build && electron-builder --win --publish never --config.win.target=dir",
+    "build:win:verbose": "node windows/build-with-progress.cjs --verbose",
+    "make:win:forge": "npm run build && node windows/forge/make-with-stamp.cjs",
+    "make:win:forge:verbose": "npm run build && node windows/forge/make-with-stamp.cjs --verbose",
+    "run:win:installed-icon-debug": "windows/run-installed-with-icon-debug.cmd",
+    "version:bump": "npm version patch --no-git-tag-version",
+    "version:bump-minor": "npm version minor --no-git-tag-version",
+    "version:bump-major": "npm version major --no-git-tag-version"
+  },
+  "build": {
+    "appId": "com.sraibaby.app",
+    "productName": "Hyperlinks Space Program",
+    "icon": "assets/icon.ico",
+    "asar": {
+      "smartUnpack": true
+    },
+    "asarUnpack": [
+      "**/*.node",
+      "**/*.dll",
+      "**/*.exe",
+      "assets/icon.ico"
+    ],
+    "extraResources": [
+      {
+        "from": "assets/icon.ico",
+        "to": "."
+      }
+    ],
+    "extraMetadata": {
+      "main": "windows/build.cjs"
+    },
+    "files": [
+      "dist/**/*",
+      "windows/**",
+      "assets/icon.ico"
+    ],
+    "afterSign": "windows/after-sign-windows-icon.cjs",
+    "win": {
+      "icon": "assets/icon.ico",
+      "signAndEditExecutable": true,
+      "artifactName": "HyperlinksSpaceProgram_${version}.${ext}",
+      "target": [
+        {
+          "target": "nsis",
+          "arch": [
+            "x64"
+          ]
+        },
+        {
+          "target": "zip",
+          "arch": [
+            "x64"
+          ]
+        }
+      ]
+    },
+    "nsis": {
+      "artifactName": "HyperlinksSpaceProgramInstaller_${env.BUILD_STAMP}.${ext}",
+      "include": "installer-hooks.nsi",
+      "installerIcon": "assets/icon.ico",
+      "uninstallerIcon": "assets/icon.ico",
+      "installerHeaderIcon": "assets/icon.ico",
+      "guid": "5e1f4a8d-9c64-4e6a-a7d1-2a2fd2f01b0f",
+      "oneClick": false,
+      "runAfterFinish": true,
+      "perMachine": true,
+      "allowElevation": true,
+      "allowToChangeInstallationDirectory": false,
+      "warningsAsErrors": false,
+      "deleteAppDataOnUninstall": true
+    },
+    "directories": {
+      "output": "releases/artifacts",
+      "buildResources": "windows"
+    },
+    "publish": {
+      "provider": "github",
+      "owner": "HyperlinksSpace",
+      "repo": "HyperlinksSpaceProgram"
+    }
+  },
+  "dependencies": {
+    "@expo/metro-runtime": "~6.1.2",
+    "@expo/vector-icons": "^15.0.2",
+    "@neondatabase/api-client": "^2.7.0",
+    "@neondatabase/serverless": "^1.0.2",
+    "@react-navigation/bottom-tabs": "^7.3.10",
+    "@react-navigation/elements": "^2.3.8",
+    "@react-navigation/native": "^7.1.6",
+    "@swap-coffee/sdk": "^1.5.4",
+    "@tma.js/sdk-react": "^3.0.16",
+    "electron-updater": "^6.8.3",
+    "expo": "~54.0.0",
+    "expo-blur": "~15.0.8",
+    "expo-constants": "~18.0.13",
+    "expo-font": "~14.0.11",
+    "expo-haptics": "~15.0.8",
+    "expo-image": "~3.0.11",
+    "expo-linking": "~8.0.11",
+    "expo-router": "~6.0.23",
+    "expo-splash-screen": "~31.0.13",
+    "expo-status-bar": "~3.0.9",
+    "expo-symbols": "~1.0.8",
+    "expo-system-ui": "~6.0.9",
+    "expo-updates": "~29.0.16",
+    "expo-web-browser": "~15.0.10",
+    "extract-zip": "^2.0.1",
+    "grammy": "^1.34.0",
+    "openai": "^6.25.0",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-reanimated": "~4.1.1",
+    "react-native-safe-area-context": "~5.6.2",
+    "react-native-screens": "~4.16.0",
+    "react-native-svg": "^15.15.3",
+    "react-native-web": "^0.21.0",
+    "react-native-webview": "13.15.0",
+    "react-native-worklets": "0.5.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.2",
+    "@electron-forge/cli": "^7.11.1",
+    "@electron-forge/maker-zip": "^7.11.1",
+    "@felixrieseberg/electron-forge-maker-nsis": "^7.2.0",
+    "@types/react": "~19.1.0",
+    "@vercel/functions": "^3.4.3",
+    "concurrently": "^9.1.0",
+    "cross-env": "^7.0.3",
+    "dotenv": "^16.4.5",
+    "electron": "^41.0.4",
+    "electron-builder": "^26.8.1",
+    "electron-forge": "^5.2.4",
+    "electron-prebuilt-compile": "8.2.0",
+    "eslint": "^9.25.0",
+    "eslint-config-expo": "~10.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "~5.9.2",
+    "vercel": "^38.0.0"
+  }
+}

package/scripts/load-env.ts

@@ -0,0 +1,17 @@
+import dotenv from "dotenv";
+import path from "path";
+
+/**
+ * Unified env loader for local Node contexts.
+ *
+ * Loads .env and .env.local from repo root and app/.
+ * On Vercel, these files normally aren't present, so this is effectively a no-op.
+ */
+export function loadEnv() {
+  const cwd = process.cwd();
+  dotenv.config({ path: path.join(cwd, ".env") });
+  dotenv.config({ path: path.join(cwd, "app", ".env") });
+  dotenv.config({ path: path.join(cwd, ".env.local") });
+  dotenv.config({ path: path.join(cwd, "app", ".env.local") });
+}
+

package/scripts/migrate-db.ts

@@ -0,0 +1,16 @@
+import { ensureSchema } from '../database/start.js';
+
+async function main() {
+  try {
+    console.log('[db] Running schema migrations against DATABASE_URL...');
+    await ensureSchema();
+    console.log('[db] Schema is up to date.');
+  } catch (err) {
+    console.error('[db] Migration failed', err);
+    process.exitCode = 1;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+main();
+

package/scripts/program-kit-init.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const SKIP = new Set(["node_modules", ".git", ".DS_Store"]);
+
+function copyRecursive(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyRecursive(from, to);
+    } else if (entry.isSymbolicLink()) {
+      const real = fs.realpathSync(from);
+      const st = fs.statSync(real);
+      if (st.isDirectory()) {
+        copyRecursive(real, to);
+      } else {
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.copyFileSync(real, to);
+      }
+    } else {
+      fs.mkdirSync(path.dirname(to), { recursive: true });
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function isEmptyDir(dir) {
+  try {
+    return fs.readdirSync(dir).length === 0;
+  } catch (_) {
+    return true;
+  }
+}
+
+const args = process.argv.slice(2);
+const force = args.includes("--force");
+const targetArg = args.find((a) => !a.startsWith("-")) || ".";
+const target = path.resolve(process.cwd(), targetArg);
+const packageRoot = path.resolve(__dirname, "..");
+
+if (fs.existsSync(target) && !isEmptyDir(target) && !force) {
+  console.error(`Target is not empty: ${target}`);
+  console.error("Re-run with --force to overwrite.");
+  process.exit(1);
+}
+
+fs.mkdirSync(target, { recursive: true });
+copyRecursive(packageRoot, target);
+
+console.log(`Program kit scaffold created at ${target}`);
+console.log("Next steps:");
+console.log(`  cd ${targetArg}`);
+console.log("  npm install");

package/scripts/run-bot-local.ts

@@ -0,0 +1,30 @@
+/**
+ * Local run: polling (getUpdates). Only BOT_TOKEN needed.
+ * Run: npx tsx scripts/run-bot-local.ts  (or npm run bot:local)
+ * Do not run with the same token while webhook is set in production.
+ */
+import { createBot } from '../bot/grammy';
+import { loadEnv } from './load-env';
+
+loadEnv();
+
+const token = (process.env.BOT_TOKEN || process.env.TELEGRAM_BOT_TOKEN || '').trim();
+if (!token) {
+  console.error('Missing BOT_TOKEN (or TELEGRAM_BOT_TOKEN)');
+  process.exit(1);
+}
+
+async function main() {
+  const bot = createBot(token);
+  await bot.api.deleteWebhook();
+  await bot.start();
+  console.log('Bot running locally (getUpdates). Press Ctrl+C to stop.');
+}
+
+main().catch((err) => {
+  console.error(err);
+  if (err?.error_code === 401) {
+    console.error('[bot] 401 Unauthorized: check BOT_TOKEN in .env (valid token from @BotFather, no extra spaces).');
+  }
+  process.exit(1);
+});

package/scripts/set-webhook.ts

@@ -0,0 +1,67 @@
+/**
+ * Set Telegram webhook on deploy. Run during Vercel build.
+ * Requires BOT_TOKEN and a base URL. Base URL is VERCEL_PROJECT_PRODUCTION_URL
+ * (Vercel's production alias, e.g. hsbexpo.vercel.app) or VERCEL_URL (deployment-specific).
+ */
+
+const BOT_TOKEN = process.env.BOT_TOKEN || process.env.TELEGRAM_BOT_TOKEN;
+const VERCEL_PROJECT_PRODUCTION_URL = process.env.VERCEL_PROJECT_PRODUCTION_URL;
+const VERCEL_URL = process.env.VERCEL_URL;
+const baseUrl =
+  VERCEL_PROJECT_PRODUCTION_URL
+    ? `https://${VERCEL_PROJECT_PRODUCTION_URL}`
+    : VERCEL_URL
+      ? `https://${VERCEL_URL}`
+      : '';
+
+const WEBHOOK_PATH = '/api/bot';
+const FETCH_TIMEOUT_MS = 15_000;
+
+async function setWebhook(): Promise<void> {
+  console.log(
+    '[set-webhook] env: VERCEL_ENV=%s VERCEL_URL=%s VERCEL_PROJECT_PRODUCTION_URL=%s',
+    process.env.VERCEL_ENV ?? '',
+    VERCEL_URL ?? '(none)',
+    VERCEL_PROJECT_PRODUCTION_URL ?? '(none)',
+  );
+
+  if (!BOT_TOKEN) {
+    console.log('[set-webhook] Skip: BOT_TOKEN not set. Add BOT_TOKEN in Vercel → Settings → Environment Variables (Production, include in Build).');
+    return;
+  }
+
+  if (!baseUrl) {
+    console.log('[set-webhook] Skip: no webhook URL (VERCEL_URL / VERCEL_PROJECT_PRODUCTION_URL).');
+    return;
+  }
+
+  const url = `${baseUrl}${WEBHOOK_PATH}`;
+  console.log('[set-webhook] Setting webhook to:', url);
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  const res = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/setWebhook`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ url }),
+    signal: controller.signal,
+  });
+  clearTimeout(timeout);
+
+  const data = (await res.json()) as { ok?: boolean; description?: string };
+  if (data.ok) {
+    console.log('[set-webhook] OK:', url);
+    return;
+  }
+
+  console.error('[set-webhook] Telegram setWebhook failed:', data.description ?? data);
+  process.exit(1);
+}
+
+setWebhook()
+  .then(() => process.exit(0))
+  .catch((err: Error) => {
+    console.error('[set-webhook] Error:', err.message);
+    process.exit(1);
+  });