@www.hyperlinks.space/program-kit 1.2.3

package/blockchain/coffee.ts

@@ -0,0 +1,217 @@
+import { Configuration, RoutingApi } from "@swap-coffee/sdk";
+
+// Aggregator / routing API (swaps, routes, etc.)
+const COFFEE_BASE_URL =
+  process.env.COFFEE_BASE_URL?.trim() || "https://api.swap.coffee";
+
+// Tokens API (jettons, metadata). Default per Swap.Coffee docs.
+const COFFEE_TOKENS_BASE_URL =
+  process.env.COFFEE_TOKENS_BASE_URL?.trim() || "https://tokens.swap.coffee";
+
+const COFFEE = process.env.COFFEE?.trim() || "";
+
+export type SwapCoffeeStatus = {
+  provider: "swap.coffee";
+  enabled: boolean;
+};
+
+export function getSwapCoffeeStatus(): SwapCoffeeStatus {
+  return {
+    provider: "swap.coffee",
+    enabled: Boolean(COFFEE),
+  };
+}
+
+// Prepared Routing API client for future swap / routing features.
+const swapCoffeeConfig =
+  COFFEE &&
+  new Configuration({
+    basePath: COFFEE_BASE_URL,
+    apiKey: (name: string) => (name === "X-Api-Key" ? COFFEE : ""),
+  });
+
+export const swapCoffeeRoutingApi = swapCoffeeConfig
+  ? new RoutingApi(swapCoffeeConfig)
+  : null;
+
+export function normalizeSymbol(symbol: string | null | undefined): string {
+  if (!symbol) return "";
+  const cleaned = symbol.replace(/\$/g, "").replace(/\s+/g, "").trim();
+  const upper = cleaned.toUpperCase();
+  if (upper.length < 2 || upper.length > 10) return "";
+  return upper;
+}
+
+type TokenSearchOk = {
+  ok: true;
+  data: any;
+  elapsed_ms: number;
+  source: "swap.coffee";
+};
+
+type TokenSearchError = {
+  ok: false;
+  error: string;
+  reason?: string;
+  status_code?: number;
+  response_snippet?: string;
+  elapsed_ms: number;
+  symbol: string;
+  source: "swap.coffee";
+};
+
+export type TokenSearchResult = TokenSearchOk | TokenSearchError;
+
+export async function getTokenBySymbol(symbol: string): Promise<TokenSearchResult> {
+  const normalized = normalizeSymbol(symbol);
+  const started = Date.now();
+
+  if (!normalized) {
+    return {
+      ok: false,
+      error: "invalid_symbol",
+      reason: "Symbol must be 2-10 alphanumeric characters.",
+      elapsed_ms: Date.now() - started,
+      symbol: symbol ?? "",
+      source: "swap.coffee",
+    };
+  }
+
+  // Native TON special case.
+  if (normalized === "TON") {
+    return {
+      ok: true,
+      data: {
+        id: "TON",
+        type: "native",
+        symbol: "TON",
+        name: "Toncoin",
+        decimals: 9,
+      },
+      elapsed_ms: Date.now() - started,
+      source: "swap.coffee",
+    };
+  }
+
+  // Tokens API can be used with or without COFFEE key; send key only when set.
+  const url = new URL(
+    "/api/v3/jettons",
+    COFFEE_TOKENS_BASE_URL.endsWith("/")
+      ? COFFEE_TOKENS_BASE_URL
+      : `${COFFEE_TOKENS_BASE_URL}/`,
+  );
+  url.searchParams.set("search", normalized);
+  // API expects multiple verification params, not a single comma-separated value
+  const verificationList = (
+    process.env.TOKENS_VERIFICATION ?? "WHITELISTED,COMMUNITY,UNKNOWN"
+  )
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  for (const v of verificationList.length ? verificationList : ["WHITELISTED"]) {
+    url.searchParams.append("verification", v);
+  }
+  url.searchParams.set("size", "10");
+
+  try {
+    const headers: Record<string, string> = {};
+    if (COFFEE) headers["X-Api-Key"] = COFFEE;
+    const res = await fetch(url.toString(), { headers });
+    const elapsed_ms = Date.now() - started;
+
+    const text = await res.text();
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: "unavailable",
+        reason: "non_200",
+        status_code: res.status,
+        response_snippet: text.slice(0, 200),
+        elapsed_ms,
+        symbol: normalized,
+        source: "swap.coffee",
+      };
+    }
+
+    let data: unknown;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      return {
+        ok: false,
+        error: "unavailable",
+        reason: "json_parse",
+        status_code: res.status,
+        response_snippet: text.slice(0, 200),
+        elapsed_ms,
+        symbol: normalized,
+        source: "swap.coffee",
+      };
+    }
+
+    if (!Array.isArray(data)) {
+      return {
+        ok: false,
+        error: "unavailable",
+        reason: "unexpected_payload",
+        status_code: res.status,
+        response_snippet: text.slice(0, 200),
+        elapsed_ms,
+        symbol: normalized,
+        source: "swap.coffee",
+      };
+    }
+
+    if (data.length === 0) {
+      return {
+        ok: false,
+        error: "not_found",
+        elapsed_ms,
+        symbol: normalized,
+        source: "swap.coffee",
+      };
+    }
+
+    const exact = data.find(
+      (item: any) =>
+        typeof item?.symbol === "string" &&
+        normalizeSymbol(item.symbol) === normalized,
+    );
+
+    return {
+      ok: true,
+      data: exact ?? data[0],
+      elapsed_ms,
+      source: "swap.coffee",
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: "unavailable",
+      reason: "connection",
+      elapsed_ms: Date.now() - started,
+      symbol: normalized,
+      source: "swap.coffee",
+    };
+  }
+}
+
+export async function getJettonByAddress(
+  address: string,
+): Promise<unknown> {
+  const base =
+    COFFEE_TOKENS_BASE_URL.endsWith("/")
+      ? COFFEE_TOKENS_BASE_URL
+      : `${COFFEE_TOKENS_BASE_URL}/`;
+  const url = `${base}api/v3/jettons/${encodeURIComponent(address)}`;
+
+  const headers: Record<string, string> = {};
+  if (COFFEE) headers["X-Api-Key"] = COFFEE;
+  const res = await fetch(url, { headers });
+
+  if (!res.ok) {
+    throw new Error(`Swap.Coffee error: ${res.status} ${res.statusText}`);
+  }
+
+  return res.json();
+}

package/blockchain/router.ts

@@ -0,0 +1,44 @@
+import { getSwapCoffeeStatus } from "./coffee.js";
+
+export type BlockchainMode = "ping";
+
+export type BlockchainRequest = {
+  mode?: BlockchainMode;
+};
+
+export type BlockchainResponse = {
+  ok: boolean;
+  mode: BlockchainMode;
+  provider: "swap.coffee";
+  status: {
+    swapCoffee: ReturnType<typeof getSwapCoffeeStatus>;
+  };
+  error?: string;
+};
+
+export async function handleBlockchainRequest(
+  request: BlockchainRequest = {},
+): Promise<BlockchainResponse> {
+  const mode: BlockchainMode = request.mode ?? "ping";
+
+  if (mode === "ping") {
+    return {
+      ok: true,
+      mode,
+      provider: "swap.coffee",
+      status: {
+        swapCoffee: getSwapCoffeeStatus(),
+      },
+    };
+  }
+
+  return {
+    ok: false,
+    mode,
+    provider: "swap.coffee",
+    status: {
+      swapCoffee: getSwapCoffeeStatus(),
+    },
+    error: `Unsupported blockchain mode: ${mode}`,
+  };
+}

package/bot/format.ts

@@ -0,0 +1,143 @@
+/**
+ * Converts Markdown (as typically produced by the AI) to Telegram HTML.
+ * Telegram supports: <b>, <i>, <code>, <pre>, <a href="...">.
+ * We escape & < > in text; lists stay as newlines (no list tags in Telegram).
+ */
+
+/** Escape for Telegram HTML: only &lt; &gt; &amp; &quot; are supported. Unescaped " breaks attribute values (e.g. href). */
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Convert Markdown to Telegram HTML. Safe for AI output (handles **bold**,
+ * *italic*, `code`, ```blocks```, [text](url)).
+ */
+export function mdToTelegramHtml(md: string): string {
+  if (typeof md !== "string" || md.length === 0) return md;
+
+  let out = md;
+
+  // 1) Escape HTML so we can safely wrap segments in tags
+  out = escapeHtml(out);
+
+  // 2) Code blocks (must be before inline code so we don't touch content)
+  out = out.replace(/```\n?([\s\S]*?)```/g, (_m, code) => `<pre>${code.trimEnd()}</pre>`);
+
+  // 3) Inline code
+  out = out.replace(/`([^`]*)`/g, "<code>$1</code>");
+
+  // 4) Bold (** or __)
+  out = out.replace(/\*\*([^*]+)\*\*/g, "<b>$1</b>");
+  out = out.replace(/__([^_]+)__/g, "<b>$1</b>");
+
+  // 5) Italic (* or _); bold already replaced so **/__ are gone
+  out = out.replace(/\*([^*]+)\*/g, "<i>$1</i>");
+  out = out.replace(/_([^_]+)_/g, "<i>$1</i>");
+
+  // 6) Links [text](url) - href and text are already escaped
+  out = out.replace(/\[([^\]]*)\]\(([^)]*)\)/g, '<a href="$2">$1</a>');
+
+  return out;
+}
+
+/**
+ * Remove unpaired **, __, and ` from HTML (output of mdToTelegramHtml). Use for partial
+ * content so the bot never shows raw delimiters. Skips content inside <pre> and <code>
+ * so we don't strip asterisks/backticks that are part of code.
+ */
+export function stripUnpairedMarkdownDelimiters(html: string): string {
+  if (typeof html !== "string" || html.length === 0) return html;
+  const blocks: string[] = [];
+  const placeholder = (i: number) => `\x00B${i}\x00`;
+  let out = html.replace(/<pre>[\s\S]*?<\/pre>/gi, (m) => {
+    const i = blocks.length;
+    blocks.push(m);
+    return placeholder(i);
+  });
+  out = out.replace(/<code>[\s\S]*?<\/code>/gi, (m) => {
+    const i = blocks.length;
+    blocks.push(m);
+    return placeholder(i);
+  });
+  out = out.replace(/\*\*/g, "").replace(/__/g, "").replace(/`/g, "");
+  for (let i = 0; i < blocks.length; i++) {
+    out = out.split(placeholder(i)).join(blocks[i]);
+  }
+  return out;
+}
+
+const TELEGRAM_HTML_TAG_RE = /<(?:(\/(?:code|pre|a|b|i))>|((?:code|pre|a|b|i)(?:\s[^>]*)?)>)/gi;
+
+/**
+ * Make HTML valid for Telegram: remove unexpected (orphan) closing tags, then
+ * append closing tags for any unclosed opens. Fixes "Unexpected end tag" errors
+ * from overlapping markdown (e.g. *a **b* c**).
+ */
+export function sanitizeTelegramHtml(html: string): string {
+  if (typeof html !== "string" || html.length === 0) return html;
+  const tags: { start: number; end: number; type: "open" | "close"; name: string }[] = [];
+  let m: RegExpExecArray | null;
+  TELEGRAM_HTML_TAG_RE.lastIndex = 0;
+  while ((m = TELEGRAM_HTML_TAG_RE.exec(html)) !== null) {
+    if (m[1] !== undefined) {
+      const name = m[1].replace(/^\//, "").toLowerCase();
+      tags.push({ start: m.index, end: m.index + m[0].length, type: "close", name });
+    } else if (m[2] !== undefined) {
+      const name = m[2].replace(/\s.*$/, "").toLowerCase();
+      tags.push({ start: m.index, end: m.index + m[0].length, type: "open", name });
+    }
+  }
+  const stack: string[] = [];
+  const orphanCloseIndices = new Set<number>();
+  for (let i = 0; i < tags.length; i++) {
+    const t = tags[i];
+    if (t.type === "open") {
+      stack.push(t.name);
+    } else {
+      if (stack.length > 0 && stack[stack.length - 1] === t.name) {
+        stack.pop();
+      } else {
+        orphanCloseIndices.add(i);
+      }
+    }
+  }
+  let out = "";
+  let pos = 0;
+  for (let i = 0; i < tags.length; i++) {
+    const t = tags[i];
+    out += html.slice(pos, t.start);
+    if (!orphanCloseIndices.has(i)) out += html.slice(t.start, t.end);
+    pos = t.end;
+  }
+  out += html.slice(pos);
+  if (stack.length > 0) {
+    out += stack.reverse().map((tag) => `</${tag}>`).join("");
+  }
+  return out;
+}
+
+/**
+ * Append closing tags for any unclosed Telegram HTML tags. Use after mdToTelegramHtml
+ * on partial content so we never send invalid HTML (avoids reject + flicker).
+ */
+export function closeOpenTelegramHtml(html: string): string {
+  return sanitizeTelegramHtml(html);
+}
+
+/**
+ * Truncate HTML to at most maxLen without cutting through a tag, then close any unclosed tags.
+ * Use before sending/edit with parse_mode: "HTML" so Telegram never receives invalid HTML
+ * (avoids reject and fallback to plain text).
+ */
+export function truncateTelegramHtmlSafe(html: string, maxLen: number): string {
+  if (typeof html !== "string" || html.length <= maxLen) return html;
+  const cut = html.slice(0, maxLen);
+  const lastTagEnd = cut.lastIndexOf(">");
+  const safe = lastTagEnd >= 0 ? cut.slice(0, lastTagEnd + 1) : cut;
+  return closeOpenTelegramHtml(safe);
+}

package/bot/grammy.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared Grammy bot.
+ * Used by app/bot/webhook (Vercel) and scripts/run-bot-local.ts (polling).
+ */
+import { Bot, type Context } from 'grammy';
+import {
+  normalizeUsername,
+  upsertUserFromBot,
+} from '../database/users.js';
+import { handleBotAiResponse } from './responder.js';
+
+export function createBot(token: string): Bot {
+  const bot = new Bot(token);
+
+  async function handleUserUpsert(ctx: Context): Promise<void> {
+    try {
+      const from = ctx.from;
+      if (!from) return;
+
+      const telegramUsername = normalizeUsername(from.username);
+      if (!telegramUsername) return;
+
+      const locale =
+        typeof from.language_code === 'string' ? from.language_code : null;
+
+      await upsertUserFromBot({ telegramUsername, locale });
+    } catch (err) {
+      console.error('[bot] upsert user failed', err);
+    }
+  }
+
+  bot.command('start', async (ctx: Context) => {
+    await handleUserUpsert(ctx);
+    await ctx.reply("That's @HyperlinksSpaceBot, you can use AI in bot and explore the app for more features");
+  });
+
+  bot.on('message:text', async (ctx: Context) => {
+    await handleUserUpsert(ctx);
+    await handleBotAiResponse(ctx);
+  });
+
+  bot.on('message:caption', async (ctx: Context) => {
+    await handleUserUpsert(ctx);
+    await handleBotAiResponse(ctx);
+  });
+
+  bot.catch((err) => {
+    console.error('[bot]', err);
+  });
+
+  return bot;
+}