@www.hyperlinks.space/program-kit 1.2.3

package/README.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/api/ai.ts

@@ -0,0 +1,111 @@
+/**
+ * AI gateway.
+ * - GET /api/ai  → health check ({ ok: true, ai: true }).
+ * - POST /api/ai → AI response from providers (currently OpenAI).
+ *
+ * Supports both:
+ * - Web API style (Request → Response)
+ * - Legacy Node style (req, res)
+ */
+
+import { transmit, type AiRequest } from "../ai/transmitter.js";
+
+type NodeRes = {
+  setHeader(name: string, value: string): void;
+  status(code: number): void;
+  end(body?: string): void;
+};
+
+function jsonResponse(body: object, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+async function handler(
+  request: Request,
+  res?: NodeRes,
+): Promise<Response | void> {
+  const method = (request as any)?.method ?? "GET";
+
+  if (method === "GET") {
+    const body = { ok: true, ai: true };
+
+    if (res) {
+      res.setHeader("Content-Type", "application/json");
+      res.status(200);
+      res.end(JSON.stringify(body));
+      return;
+    }
+
+    return jsonResponse(body, 200);
+  }
+
+  if (method !== "POST") {
+    const body = { ok: false, error: "Method not allowed" };
+
+    if (res) {
+      res.setHeader("Content-Type", "application/json");
+      res.status(405);
+      res.end(JSON.stringify(body));
+      return;
+    }
+
+    return jsonResponse(body, 405);
+  }
+
+  let payload: unknown;
+  try {
+    payload = await request.json();
+  } catch {
+    const body = { ok: false, error: "Invalid JSON body" };
+
+    if (res) {
+      res.setHeader("Content-Type", "application/json");
+      res.status(400);
+      res.end(JSON.stringify(body));
+      return;
+    }
+
+    return jsonResponse(body, 400);
+  }
+
+  const { input, mode, userId, context } = (payload || {}) as Partial<AiRequest>;
+
+  if (typeof input !== "string" || input.trim().length === 0) {
+    const body = { ok: false, error: "Field 'input' (string) is required." };
+
+    if (res) {
+      res.setHeader("Content-Type", "application/json");
+      res.status(400);
+      res.end(JSON.stringify(body));
+      return;
+    }
+
+    return jsonResponse(body, 400);
+  }
+
+  const result = await transmit({
+    input,
+    mode,
+    userId,
+    context,
+  });
+
+  const status = result.ok ? 200 : 500;
+
+  if (res) {
+    res.setHeader("Content-Type", "application/json");
+    res.status(status);
+    res.end(JSON.stringify(result));
+    return;
+  }
+
+  return jsonResponse(result, status);
+}
+
+export default handler;
+export const GET = handler;
+export const POST = handler;
+

package/api/base.ts

@@ -0,0 +1,117 @@
+/**
+ * API base URL helper used by frontend and bot.
+ *
+ * Priority:
+ * - EXPO_PUBLIC_API_BASE_URL (explicit override for any environment)
+ * - React Native / Expo Go dev: derive from dev server host (port 3000)
+ * - Browser:
+ *   - In dev: map localhost/LAN + dev port (8081/19000/19006) → port 3000
+ *   - In prod: window.location.origin (e.g. https://hsbexpo.vercel.app)
+ * - Node (no window): Vercel host if available, otherwise http://localhost:3000
+ */
+
+function normalizeBase(base: string): string {
+  return base.replace(/\/$/, "");
+}
+
+function isPrivateOrLocalHost(hostname: string): boolean {
+  if (hostname === "localhost" || hostname === "127.0.0.1") return true;
+  if (hostname.startsWith("10.")) return true;
+  if (hostname.startsWith("192.168.")) return true;
+  if (/^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname)) return true;
+  return false;
+}
+
+function getExpoNativeDevBaseUrl(): string | null {
+  // Only attempt this in React Native / Expo Go.
+  if (typeof navigator === "undefined" || navigator.product !== "ReactNative") {
+    return null;
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Constants = require("expo-constants").default as any;
+    const hostUri: string | undefined =
+      Constants?.expoConfig?.hostUri ??
+      Constants?.manifest2?.extra?.expoGo?.developer?.hostUri;
+
+    if (!hostUri || typeof hostUri !== "string") {
+      return null;
+    }
+
+    const [hostname] = hostUri.split(":");
+    if (!hostname) return null;
+
+    return `http://${hostname}:3000`;
+  } catch {
+    return null;
+  }
+}
+
+function getBrowserBaseUrl(): string | null {
+  if (typeof window === "undefined" || !window.location?.href) {
+    return null;
+  }
+
+  try {
+    const url = new URL(window.location.href);
+    const { protocol, hostname, port } = url;
+
+    // In dev, Expo often runs on 8081/19000/19006; map to 3000 for APIs.
+    if (
+      isPrivateOrLocalHost(hostname) &&
+      (port === "8081" || port === "19000" || port === "19006")
+    ) {
+      return normalizeBase(`${protocol}//${hostname}:3000`);
+    }
+
+    // In production (no explicit dev port), use origin as-is.
+    return normalizeBase(url.origin);
+  } catch {
+    return null;
+  }
+}
+
+function getNodeBaseUrl(): string {
+  const vercelProjectProd = process.env.VERCEL_PROJECT_PRODUCTION_URL?.trim();
+  if (vercelProjectProd) {
+    return normalizeBase(`https://${vercelProjectProd}`);
+  }
+
+  const vercelUrl = process.env.VERCEL_URL?.trim();
+  if (vercelUrl) {
+    return normalizeBase(
+      vercelUrl.startsWith("http") ? vercelUrl : `https://${vercelUrl}`,
+    );
+  }
+
+  // Local dev fallback (vercel dev on 3000).
+  return "http://localhost:3000";
+}
+
+export function getApiBaseUrl(): string {
+  const envBase = process.env.EXPO_PUBLIC_API_BASE_URL?.trim();
+  if (envBase) {
+    return normalizeBase(envBase);
+  }
+
+  const expoDev = getExpoNativeDevBaseUrl();
+  if (expoDev) {
+    return normalizeBase(expoDev);
+  }
+
+  const browserBase = getBrowserBaseUrl();
+  if (browserBase) {
+    return browserBase;
+  }
+
+  return getNodeBaseUrl();
+}
+
+export function buildApiUrl(path: string): string {
+  const base = getApiBaseUrl();
+  if (!base) {
+    return path;
+  }
+  return `${base}${path}`;
+}

package/api/blockchain.ts

@@ -0,0 +1,58 @@
+/**
+ * Minimal blockchain gateway.
+ * GET /api/blockchain → status of blockchain integrations (swap.coffee, etc.).
+ *
+ * Supports both:
+ * - Web API style (Request → Response)
+ * - Legacy Node style (req, res)
+ */
+
+import { handleBlockchainRequest } from "../blockchain/router.js";
+
+type NodeRes = {
+  setHeader(name: string, value: string): void;
+  status(code: number): void;
+  end(body?: string): void;
+};
+
+function jsonResponse(body: object, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+async function handler(
+  request: Request,
+  res?: NodeRes,
+): Promise<Response | void> {
+  const method = (request as any)?.method ?? "GET";
+
+  if (method !== "GET") {
+    const body = { ok: false, error: "Method not allowed" };
+
+    if (res) {
+      res.setHeader("Content-Type", "application/json");
+      res.status(405);
+      res.end(JSON.stringify(body));
+      return;
+    }
+
+    return jsonResponse(body, 405);
+  }
+
+  const result = await handleBlockchainRequest({ mode: "ping" });
+
+  if (res) {
+    res.setHeader("Content-Type", "application/json");
+    res.status(200);
+    res.end(JSON.stringify(result));
+    return;
+  }
+
+  return jsonResponse(result, 200);
+}
+
+export default handler;
+export const GET = handler;
+

package/api/bot.ts

@@ -0,0 +1,19 @@
+/**
+ * Vercel API route: named GET/POST so Telegram webhook POST is handled.
+ * Forwards to app/bot/webhook so only this file is a route (avoids 12-function limit).
+ */
+import webhookHandler, {
+  type NodeReq,
+  type NodeRes,
+} from '../bot/webhook.js';
+
+async function handler(
+  request: Request | NodeReq,
+  context?: NodeRes,
+): Promise<Response | void> {
+  return webhookHandler(request, context);
+}
+
+export default handler;
+export const GET = handler;
+export const POST = handler;

package/api/ping.ts

@@ -0,0 +1,41 @@
+/**
+ * Zero-dependency health check.
+ * GET /api/ping → { ok: true, ping: true }
+ *
+ * Supports both:
+ * - Web API style (Request → Response)
+ * - Legacy Node style (req, res)
+ */
+
+type NodeRes = {
+  setHeader(name: string, value: string): void;
+  status(code: number): void;
+  end(body?: string): void;
+};
+
+function jsonResponse(body: object, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+async function handler(
+  request: Request,
+  res?: NodeRes,
+): Promise<Response | void> {
+  const body = { ok: true, ping: true };
+
+  if (res) {
+    res.setHeader('Content-Type', 'application/json');
+    res.status(200);
+    res.end(JSON.stringify(body));
+    return;
+  }
+
+  return jsonResponse(body, 200);
+}
+
+export default handler;
+export const GET = handler;
+

package/api/releases.ts

@@ -0,0 +1,162 @@
+/**
+ * Release webhook endpoint.
+ * - GET /api/releases  -> health check
+ * - POST /api/releases -> accepts release publish events from CI
+ */
+
+type NodeRes = {
+  setHeader(name: string, value: string): void;
+  status(code: number): void;
+  end(body?: string): void;
+};
+
+type Asset = {
+  name: string;
+  url: string;
+  sha256?: string;
+};
+
+type ReleasePayload = {
+  release_id: string;
+  version?: string;
+  published_at: string;
+  platform?: string;
+  assets: Asset[];
+  github_release_url?: string;
+};
+
+const processedReleaseIds = new Set<string>();
+const MAX_REMEMBERED_RELEASE_IDS = 500;
+
+function jsonResponse(body: object, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      "Access-Control-Allow-Origin": "*",
+    },
+  });
+}
+
+function setNodeCors(res: NodeRes): void {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, x-release-token");
+  res.setHeader("Content-Type", "application/json");
+}
+
+function isValidPayload(payload: unknown): payload is ReleasePayload {
+  if (!payload || typeof payload !== "object") return false;
+  const candidate = payload as Partial<ReleasePayload>;
+  if (typeof candidate.release_id !== "string" || candidate.release_id.trim() === "") return false;
+  if (typeof candidate.published_at !== "string" || candidate.published_at.trim() === "") return false;
+  if (!Array.isArray(candidate.assets)) return false;
+  return candidate.assets.every(
+    (asset) =>
+      asset &&
+      typeof asset === "object" &&
+      typeof (asset as Asset).name === "string" &&
+      typeof (asset as Asset).url === "string",
+  );
+}
+
+function rememberReleaseId(releaseId: string): void {
+  processedReleaseIds.add(releaseId);
+  if (processedReleaseIds.size <= MAX_REMEMBERED_RELEASE_IDS) return;
+
+  // Best-effort bounded memory for warm server instances.
+  const oldest = processedReleaseIds.values().next().value as string | undefined;
+  if (oldest) processedReleaseIds.delete(oldest);
+}
+
+async function notifyReleaseSignal(payload: ReleasePayload): Promise<void> {
+  const notifyUrl = process.env.RELEASES_NOTIFY_URL?.trim();
+  if (!notifyUrl) return;
+
+  const token = process.env.RELEASES_NOTIFY_TOKEN?.trim();
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (token) headers["x-release-token"] = token;
+
+  const response = await fetch(notifyUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`notify_failed:${response.status}`);
+  }
+}
+
+async function readPayload(request: Request): Promise<unknown> {
+  try {
+    return await request.json();
+  } catch {
+    return null;
+  }
+}
+
+async function handleWebRequest(request: Request): Promise<Response> {
+  const method = request.method;
+  if (method === "OPTIONS") return jsonResponse({}, 200);
+
+  if (method === "GET") {
+    const tokenConfigured = !!process.env.RELEASE_WEBHOOK_TOKEN?.trim();
+    return jsonResponse(
+      {
+        ok: true,
+        service: "releases-webhook",
+        token_configured: tokenConfigured,
+        auth_mode: tokenConfigured ? "token_required" : "open",
+      },
+      200,
+    );
+  }
+
+  if (method !== "POST") {
+    return jsonResponse({ ok: false, error: "Method not allowed" }, 405);
+  }
+
+  const requiredToken = process.env.RELEASE_WEBHOOK_TOKEN?.trim();
+  if (requiredToken) {
+    const providedToken = request.headers.get("x-release-token")?.trim();
+    if (providedToken !== requiredToken) {
+      return jsonResponse({ ok: false, error: "Unauthorized" }, 401);
+    }
+  } else {
+    console.warn("[releases] RELEASE_WEBHOOK_TOKEN is not set; endpoint is open");
+  }
+
+  const payload = await readPayload(request);
+  if (!isValidPayload(payload)) {
+    return jsonResponse({ ok: false, error: "Invalid payload" }, 400);
+  }
+
+  if (processedReleaseIds.has(payload.release_id)) {
+    return jsonResponse({ ok: true, duplicate: true }, 200);
+  }
+
+  rememberReleaseId(payload.release_id);
+  try {
+    await notifyReleaseSignal(payload);
+  } catch (error) {
+    console.error("[releases] notify error", error);
+    return jsonResponse({ ok: false, error: "Failed to notify downstream service" }, 502);
+  }
+
+  return jsonResponse({ ok: true }, 200);
+}
+
+export default async function handler(request: Request, res?: NodeRes): Promise<Response | void> {
+  if (!res) {
+    return handleWebRequest(request);
+  }
+
+  setNodeCors(res);
+  const webResponse = await handleWebRequest(request);
+  res.status(webResponse.status);
+  res.end(await webResponse.text());
+}
+
+export const GET = handler;
+export const POST = handler;

package/api/telegram.ts

@@ -0,0 +1,65 @@
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+
+function jsonResponse(body: object, status: number): Response {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+
+/** Node res: send body and end so the client gets the response (Vercel uses (req, res) in prod). */
+function sendViaRes(res: { status: (n: number) => void; setHeader: (k: string, v: string) => void; end: (s?: string) => void }, body: object, status: number): void {
+  res.status(status);
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * Thin router: GET returns immediately (no heavy deps). POST loads
+ * the heavy handler from ./telegram/post so initData verification and
+ * DB writes stay out of the fast path. When Vercel passes (req, res),
+ * we must send via res so the client gets the response.
+ */
+async function handler(
+  request: Request,
+  res?: { status: (n: number) => void; setHeader: (k: string, v: string) => void; end: (s?: string) => void }
+): Promise<Response | void> {
+  const method = (request as { method?: string }).method ?? request.method;
+  if (method === 'GET') {
+    const body = { ok: true, endpoint: 'telegram', use: 'POST with initData' };
+    if (res) {
+      sendViaRes(res, body, 200);
+      return;
+    }
+    return jsonResponse(body, 200);
+  }
+  if (method !== 'POST') {
+    if (res) {
+      res.status(405);
+      res.end('Method Not Allowed');
+      return;
+    }
+    return new Response('Method Not Allowed', { status: 405 });
+  }
+  try {
+    const { handlePost } = await import('../telegram/post.js');
+    const response = await handlePost(request);
+    if (res) {
+      res.status(response.status);
+      response.headers.forEach((v, k) => res.setHeader(k, v));
+      res.end(await response.text());
+      return;
+    }
+    return response;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error('[api/telegram] POST error:', message, err instanceof Error ? err.stack : '');
+    const body = { ok: false, error: message || 'internal_error' };
+    if (res) {
+      sendViaRes(res, body, 500);
+      return;
+    }
+    return jsonResponse(body, 500);
+  }
+}
+
+export default handler;
+export const GET = handler;
+export const POST = handler;

package/api/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "../bot/**/*.ts"
+  ]
+}