@tma.sh/sdk 0.1.0

package/dist/bot/index.js

@@ -0,0 +1,185 @@
+// src/bot/context.ts
+var TELEGRAM_API_BASE = "https://api.telegram.org/bot";
+var createTelegramCaller = (botToken) => {
+  const callTelegram = async (method, body) => {
+    let response;
+    try {
+      response = await fetch(`${TELEGRAM_API_BASE}${botToken}/${method}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+    } catch {
+      throw new Error(`Telegram API request failed for method "${method}"`);
+    }
+    const data = await response.json();
+    if (!data.ok) {
+      throw new Error(`Telegram API error: ${data.description ?? "unknown"}`);
+    }
+    return data.result;
+  };
+  return callTelegram;
+};
+var createKV = (binding) => ({
+  get: async (key) => {
+    const value = await binding.get(key);
+    if (value === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  },
+  set: async (key, value, ttl) => {
+    const serialized = typeof value === "string" ? value : JSON.stringify(value);
+    await binding.put(
+      key,
+      serialized,
+      ttl ? { expirationTtl: ttl } : void 0
+    );
+  },
+  delete: async (key) => {
+    await binding.delete(key);
+  },
+  list: async (prefix) => {
+    const result = await binding.list(prefix ? { prefix } : void 0);
+    return result.keys.map((k) => k.name);
+  }
+});
+var resolveChatId = (update) => update.message?.chat.id ?? update.callback_query?.message?.chat.id ?? update.inline_query?.from.id;
+var resolveFrom = (update) => update.message?.from ?? update.callback_query?.from ?? update.inline_query?.from ?? update.pre_checkout_query?.from;
+var createBotContext = (update, env) => {
+  const callTelegram = createTelegramCaller(env.BOT_TOKEN);
+  const chatId = resolveChatId(update);
+  const from = resolveFrom(update);
+  const kv = createKV(env.KV);
+  const api = {
+    call: (method, body) => callTelegram(method, body ?? {})
+  };
+  const requireChatId = () => {
+    if (chatId === void 0) {
+      throw new Error(
+        "reply() requires a chat context (message or callback_query update)"
+      );
+    }
+    return chatId;
+  };
+  const reply = (text, options) => callTelegram("sendMessage", {
+    chat_id: requireChatId(),
+    text,
+    ...options
+  });
+  const replyPhoto = (photo, options) => callTelegram("sendPhoto", {
+    chat_id: requireChatId(),
+    photo,
+    ...options
+  });
+  const answerCallbackQuery = (text, options) => callTelegram("answerCallbackQuery", {
+    callback_query_id: update.callback_query?.id,
+    ...text !== void 0 ? { text } : {},
+    ...options
+  });
+  const answerInlineQuery = (results, options) => callTelegram("answerInlineQuery", {
+    inline_query_id: update.inline_query?.id,
+    results,
+    ...options
+  });
+  const answerPreCheckoutQuery = (ok, errorMessage) => callTelegram("answerPreCheckoutQuery", {
+    pre_checkout_query_id: update.pre_checkout_query?.id,
+    ok,
+    ...errorMessage !== void 0 ? { error_message: errorMessage } : {}
+  });
+  return {
+    update,
+    message: update.message,
+    callbackQuery: update.callback_query,
+    inlineQuery: update.inline_query,
+    preCheckoutQuery: update.pre_checkout_query,
+    chatId,
+    from,
+    env,
+    kv,
+    api,
+    reply,
+    replyPhoto,
+    answerCallbackQuery,
+    answerInlineQuery,
+    answerPreCheckoutQuery
+  };
+};
+
+// src/bot/runtime.ts
+var composeMiddleware = (middlewares, handler) => {
+  return async (ctx) => {
+    let index = -1;
+    const dispatch = async (i) => {
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+      const middleware = middlewares[i];
+      if (middleware) {
+        await middleware(ctx, () => dispatch(i + 1));
+      } else {
+        await handler(ctx);
+      }
+    };
+    await dispatch(0);
+  };
+};
+var routeUpdate = async (config, ctx) => {
+  if (ctx.message && config.onMessage) {
+    await config.onMessage(ctx);
+  } else if (ctx.callbackQuery && config.onCallbackQuery) {
+    await config.onCallbackQuery(ctx);
+  } else if (ctx.inlineQuery && config.onInlineQuery) {
+    await config.onInlineQuery(ctx);
+  } else if (ctx.preCheckoutQuery && config.onPreCheckoutQuery) {
+    await config.onPreCheckoutQuery(ctx);
+  } else if (config.onUpdate) {
+    await config.onUpdate(ctx);
+  }
+};
+var createBotWorker = (config) => {
+  const fetch2 = async (request, env, _ctx) => {
+    if (request.method !== "POST") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+    let update;
+    try {
+      update = await request.json();
+    } catch {
+      return new Response("Invalid request body", { status: 400 });
+    }
+    if (!update || typeof update.update_id !== "number") {
+      return new Response("Invalid Telegram update", { status: 400 });
+    }
+    try {
+      const botCtx = createBotContext(update, env);
+      const middlewares = config.middleware ?? [];
+      const handler = composeMiddleware(
+        middlewares,
+        (ctx) => routeUpdate(config, ctx)
+      );
+      await handler(botCtx);
+      return new Response("OK", { status: 200 });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      console.error(`Bot worker error: ${message}`);
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  };
+  return { fetch: fetch2 };
+};
+
+// src/bot/define-bot.ts
+var defineBot = (config) => {
+  const worker = createBotWorker(config);
+  return { ...config, ...worker };
+};
+export {
+  createKV,
+  defineBot
+};

package/dist/chunk-CDN4MZRW.js

@@ -0,0 +1,120 @@
+// src/client/http.ts
+var TMAError = class extends Error {
+  code;
+  constructor(message, code = "SDK_ERROR") {
+    super(message);
+    this.name = "TMAError";
+    this.code = code;
+  }
+};
+var DEFAULT_API_URL = "https://api.tma.sh";
+var TRAILING_SLASHES = /\/+$/;
+var resolveApiUrl = (apiUrl) => (apiUrl ?? DEFAULT_API_URL).replace(TRAILING_SLASHES, "");
+var makeRequest = async (baseUrl, path, options = {}) => {
+  const { method = "GET", body, jwt } = options;
+  const url = `${baseUrl}${path}`;
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (jwt) {
+    headers.Authorization = `Bearer ${jwt}`;
+  }
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  const json = await response.json();
+  if (!json.success) {
+    throw new TMAError(json.error, `HTTP_${response.status}`);
+  }
+  return json.data;
+};
+
+// src/client/auth.ts
+var storedJwt = null;
+var setStoredJwt = (jwt) => {
+  storedJwt = jwt;
+};
+var getStoredJwt = () => storedJwt;
+var createAuthClient = (config) => {
+  const baseUrl = resolveApiUrl(config?.apiUrl);
+  return {
+    validate: async (initData, projectId) => {
+      const result = await makeRequest(
+        baseUrl,
+        "/sdk/v1/auth/validate",
+        {
+          method: "POST",
+          body: { initData, projectId }
+        }
+      );
+      setStoredJwt(result.jwt);
+      return result;
+    },
+    getJwt: () => storedJwt
+  };
+};
+
+// src/client/kv.ts
+var requireJwt = () => {
+  const jwt = getStoredJwt();
+  if (!jwt) {
+    throw new TMAError(
+      "Authentication required. Call auth.validate() before using KV storage.",
+      "AUTH_REQUIRED"
+    );
+  }
+  return jwt;
+};
+var encodeKey = (key) => encodeURIComponent(key);
+var createKVClient = (config) => {
+  const baseUrl = resolveApiUrl(config?.apiUrl);
+  return {
+    set: async (key, value) => {
+      const jwt = requireJwt();
+      await makeRequest(baseUrl, `/sdk/v1/kv/${encodeKey(key)}`, {
+        method: "PUT",
+        body: value,
+        jwt
+      });
+    },
+    get: async (key) => {
+      const jwt = requireJwt();
+      try {
+        return await makeRequest(baseUrl, `/sdk/v1/kv/${encodeKey(key)}`, {
+          jwt
+        });
+      } catch (error) {
+        if (error instanceof TMAError && error.code === "HTTP_404") {
+          return null;
+        }
+        throw error;
+      }
+    },
+    remove: async (key) => {
+      const jwt = requireJwt();
+      await makeRequest(baseUrl, `/sdk/v1/kv/${encodeKey(key)}`, {
+        method: "DELETE",
+        jwt
+      });
+    },
+    list: (prefix) => {
+      const jwt = requireJwt();
+      const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
+      return makeRequest(baseUrl, `/sdk/v1/kv${query}`, { jwt });
+    }
+  };
+};
+
+// src/client/index.ts
+var createTMA = (config) => ({
+  auth: createAuthClient(config),
+  kv: createKVClient(config)
+});
+
+export {
+  TMAError,
+  createAuthClient,
+  createTMA
+};

package/dist/client/index.js

@@ -0,0 +1,8 @@
+import {
+  TMAError,
+  createTMA
+} from "../chunk-CDN4MZRW.js";
+export {
+  TMAError,
+  createTMA
+};

package/dist/react/index.js

@@ -0,0 +1,66 @@
+import {
+  createAuthClient,
+  createTMA
+} from "../chunk-CDN4MZRW.js";
+
+// src/react/index.ts
+import { useEffect, useState } from "react";
+var getInitData = () => window.Telegram?.WebApp?.initData;
+var LOADING_STATE = {
+  user: null,
+  jwt: null,
+  isLoading: true,
+  error: null
+};
+var NO_TELEGRAM_STATE = {
+  user: null,
+  jwt: null,
+  isLoading: false,
+  error: null
+};
+var makeErrorState = (err) => ({
+  user: null,
+  jwt: null,
+  isLoading: false,
+  error: err instanceof Error ? err : new Error(String(err))
+});
+var resolveAuthState = async (config) => {
+  const initData = getInitData();
+  if (!initData) {
+    return NO_TELEGRAM_STATE;
+  }
+  if (!config?.projectId) {
+    return makeErrorState("projectId is required in config");
+  }
+  const authClient = createAuthClient(config);
+  const result = await authClient.validate(initData, config.projectId);
+  return {
+    user: result.user,
+    jwt: result.jwt,
+    isLoading: false,
+    error: null
+  };
+};
+var useTelegramAuth = (config) => {
+  const [state, setState] = useState(LOADING_STATE);
+  useEffect(() => {
+    let cancelled = false;
+    resolveAuthState(config).then((resolved) => {
+      if (!cancelled) {
+        setState(resolved);
+      }
+    }).catch((err) => {
+      if (!cancelled) {
+        setState(makeErrorState(err));
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [config]);
+  return state;
+};
+export {
+  createTMA,
+  useTelegramAuth
+};

package/dist/server/index.js

@@ -0,0 +1,144 @@
+// src/server/auth.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { createMiddleware } from "hono/factory";
+var DEFAULT_JWKS_URL = "https://api.tma.sh/.well-known/jwks.json";
+var requireUser = (options) => {
+  const jwks = options?.jwks ?? createRemoteJWKSet(new URL(options?.jwksUrl ?? DEFAULT_JWKS_URL));
+  return createMiddleware(async (c, next) => {
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader?.startsWith("Bearer ")) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    const token = authHeader.slice(7);
+    if (token.length === 0) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    try {
+      const { payload } = await jwtVerify(token, jwks);
+      const user = {
+        telegramId: payload.telegramId,
+        firstName: payload.firstName,
+        lastName: payload.lastName,
+        username: payload.username,
+        projectId: payload.projectId
+      };
+      c.set("user", user);
+      await next();
+    } catch {
+      return c.json({ error: "Invalid or expired token" }, 401);
+    }
+  });
+};
+
+// src/server/kv.ts
+var createKV = (binding) => ({
+  get: async (key) => {
+    const value = await binding.get(key, "json");
+    return value;
+  },
+  set: async (key, value, ttl) => {
+    await binding.put(
+      key,
+      JSON.stringify(value),
+      ttl ? { expirationTtl: ttl } : void 0
+    );
+  },
+  delete: async (key) => {
+    await binding.delete(key);
+  },
+  list: async (prefix) => {
+    const result = await binding.list({ prefix });
+    return result.keys.map((k) => k.name);
+  }
+});
+
+// src/server/index.ts
+var validateInitData = async (initData, botToken) => {
+  const params = new URLSearchParams(initData);
+  const hash = params.get("hash");
+  if (!hash) {
+    return null;
+  }
+  params.delete("hash");
+  const sortedKeys = [];
+  params.forEach((_value, key) => {
+    sortedKeys.push(key);
+  });
+  sortedKeys.sort();
+  const dataCheckString = sortedKeys.map((key) => `${key}=${params.get(key)}`).join("\n");
+  const authDateStr = params.get("auth_date");
+  if (!authDateStr) {
+    return null;
+  }
+  const authDate = Number.parseInt(authDateStr, 10);
+  const now = Math.floor(Date.now() / 1e3);
+  if (Number.isNaN(authDate) || now - authDate > MAX_AUTH_AGE_SECONDS) {
+    return null;
+  }
+  const secretKey = await hmacSha256(
+    new TextEncoder().encode("WebAppData"),
+    botToken
+  );
+  const isValid = await verifyHmac(
+    new Uint8Array(secretKey),
+    dataCheckString,
+    hash
+  );
+  if (!isValid) {
+    return null;
+  }
+  const userJson = params.get("user");
+  if (!userJson) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(userJson);
+    if (!(raw.id && raw.first_name)) {
+      return null;
+    }
+    return {
+      telegramId: raw.id,
+      firstName: raw.first_name,
+      lastName: raw.last_name,
+      username: raw.username,
+      authDate
+    };
+  } catch {
+    return null;
+  }
+};
+var MAX_AUTH_AGE_SECONDS = 300;
+var hmacSha256 = async (key, data) => {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(data));
+};
+var verifyHmac = async (key, data, expectedHex) => {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  const expectedBytes = Uint8Array.from(
+    expectedHex.match(/.{2}/g) ?? [],
+    (h) => Number.parseInt(h, 16)
+  );
+  return crypto.subtle.verify(
+    "HMAC",
+    cryptoKey,
+    expectedBytes,
+    new TextEncoder().encode(data)
+  );
+};
+export {
+  createKV,
+  requireUser,
+  validateInitData
+};

package/dist/svelte/index.js

@@ -0,0 +1,61 @@
+import {
+  createAuthClient,
+  createTMA
+} from "../chunk-CDN4MZRW.js";
+
+// src/svelte/index.ts
+import { writable } from "svelte/store";
+var createTelegramAuth = (config) => {
+  const store = writable({
+    user: null,
+    jwt: null,
+    isLoading: true,
+    error: null
+  });
+  const authenticate = async () => {
+    const initData = typeof window !== "undefined" ? window.Telegram?.WebApp?.initData : void 0;
+    if (!initData) {
+      store.set({
+        user: null,
+        jwt: null,
+        isLoading: false,
+        error: null
+      });
+      return;
+    }
+    const projectId = config?.projectId;
+    if (!projectId) {
+      store.set({
+        user: null,
+        jwt: null,
+        isLoading: false,
+        error: new Error("projectId is required in config")
+      });
+      return;
+    }
+    try {
+      const authClient = createAuthClient(config);
+      const result = await authClient.validate(initData, projectId);
+      store.set({
+        user: result.user,
+        jwt: result.jwt,
+        isLoading: false,
+        error: null
+      });
+    } catch (err) {
+      store.set({
+        user: null,
+        jwt: null,
+        isLoading: false,
+        error: err instanceof Error ? err : new Error(String(err))
+      });
+    }
+  };
+  authenticate().catch(() => {
+  });
+  return store;
+};
+export {
+  createTMA,
+  createTelegramAuth
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@tma.sh/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "SDK for Telegram Mini Apps on TMA -- auth, KV storage, and framework bindings",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": "./dist/client/index.js",
+      "types": "./dist/client/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    },
+    "./svelte": {
+      "import": "./dist/svelte/index.js",
+      "types": "./dist/svelte/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server/index.js",
+      "types": "./dist/server/index.d.ts"
+    },
+    "./bot": {
+      "import": "./dist/bot/index.js",
+      "types": "./dist/bot/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "jose": "^6.0.11"
+  },
+  "peerDependencies": {
+    "hono": ">=4.0.0",
+    "react": ">=18.0.0",
+    "svelte": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250214.0",
+    "@types/react": "^19.2.14",
+    "hono": "^4.7.10",
+    "react": "^19.0.0",
+    "svelte": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "catalog:"
+  }
+}