@mirid-dev/sendkit-core 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ky-Ling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @mirid-dev/sendkit-core
+
+Telegram messaging operations and [zod](https://zod.dev) schemas shared by the SendKit CLI and MCP servers.
+
+Requires Node.js 20 or later. ESM only.
+
+## Install
+
+```sh
+npm install @mirid-dev/sendkit-core
+```
+
+## Usage
+
+```ts
+import { sendTelegramMessage } from '@mirid-dev/sendkit-core'
+
+const result = await sendTelegramMessage({
+  botToken: process.env.TELEGRAM_BOT_TOKEN!,
+  chatId: '123456789',
+  message: 'Hello from SendKit',
+})
+
+console.log(result.messageId, result.chatId, result.sentAt)
+```
+
+`sendTelegramMessage` validates its input, calls the Telegram Bot API `sendMessage` method with a 10-second timeout, and resolves to `{ messageId, chatId, sentAt }`. `chatId` comes back numeric even when you pass an `@channelusername`. Errors never include the bot token.
+
+## Exports
+
+- `sendTelegramMessage(options)`
+- Schemas: `telegramMessageInputSchema` (`chatId`, `message`), `telegramMessageOptionsSchema` (adds `botToken`), `telegramMessageOutputSchema`, `telegramSendMessageRequestSchema`, `telegramSendMessageResponseSchema`
+- Types: `TelegramMessageInput`, `TelegramMessageOptions`, `TelegramMessageOutput`
+
+## License
+
+MIT

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@mirid-dev/sendkit-core",
-  "version": "0.0.0",
+  "version": "0.0.1",
+  "description": "Core Telegram messaging operations and zod schemas for SendKit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ky-Ling/sendkit.git",
+    "directory": "packages/core"
+  },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -25,5 +33,8 @@
   },
   "dependencies": {
     "zod": "^4.6.7"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './operations'
+export * from './schemas'

package/src/operations.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+import {
+  telegramMessageOutputSchema,
+  telegramMessageOptionsSchema,
+  telegramSendMessageRequestSchema,
+  telegramSendMessageResponseSchema,
+  type TelegramMessageOutput,
+} from './schemas'
+
+const TELEGRAM_REQUEST_TIMEOUT_MS = 10_000
+
+export async function sendTelegramMessage(
+  input: z.input<typeof telegramMessageOptionsSchema>,
+): Promise<TelegramMessageOutput> {
+  const { chatId, message, botToken } = telegramMessageOptionsSchema.parse(input)
+
+  const requestBody = telegramSendMessageRequestSchema.parse({
+    chat_id: chatId,
+    text: message,
+  })
+
+  let response: Response
+
+  try {
+    response = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+      signal: AbortSignal.timeout(TELEGRAM_REQUEST_TIMEOUT_MS),
+    })
+  } catch (error) {
+    // Don't rethrow the original error: the request URL contains the bot token
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(`Could not reach Telegram: ${reason.replaceAll(botToken, '<redacted>')}`, {
+      cause: error,
+    })
+  }
+
+  // Telegram returns a JSON body even on 4xx errors, but a proxy or outage page may not
+  const parsedResponse = telegramSendMessageResponseSchema.safeParse(
+    await response.json().catch(() => null),
+  )
+
+  if (!parsedResponse.success) {
+    // A 2xx we can't read may still mean the message went out, so warn before the caller resends
+    const hint = response.ok ? '; the message may still have been sent' : ''
+    throw new Error(`Unexpected response from Telegram (HTTP ${response.status})${hint}`)
+  }
+
+  const data = parsedResponse.data
+
+  if (!data.ok) {
+    throw new Error(
+      `Telegram API error (${response.status}): ${data.description || response.statusText || 'Unknown error'}`,
+    )
+  }
+
+  return telegramMessageOutputSchema.parse({
+    messageId: data.result.message_id,
+    chatId: data.result.chat.id,
+    sentAt: new Date(data.result.date * 1000),
+  })
+}

package/src/schemas.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod'
+
+// Telegram rejects message text longer than this
+const TELEGRAM_MAX_MESSAGE_LENGTH = 4096
+
+// Numeric ID (negative for groups) or a public @channelusername
+const telegramChatIdSchema = z
+  .string()
+  .trim()
+  .refine(
+    (chatId) => /^-?\d+$/.test(chatId) || /^@\w{5,}$/.test(chatId),
+    'Use a numeric chat ID or @channelusername',
+  )
+
+export const telegramMessageInputSchema = z.object({
+  chatId: telegramChatIdSchema,
+  message: z
+    .string()
+    .refine((message) => message.trim().length > 0, 'Message cannot be empty')
+    .refine(
+      (message) => message.length <= TELEGRAM_MAX_MESSAGE_LENGTH,
+      `Telegram allows at most ${TELEGRAM_MAX_MESSAGE_LENGTH} characters`,
+    ),
+})
+
+export const telegramMessageOptionsSchema = telegramMessageInputSchema.extend({
+  botToken: z
+    .string()
+    .trim()
+    .min(1, 'Telegram bot token is required')
+    // Tokens look like 123456789:AAH...; a copied "bot" prefix would otherwise surface as a 404
+    .regex(/^\d+:[\w-]+$/, 'Expected a token like 123456789:ABC-DEF..., without the "bot" prefix'),
+})
+
+// Body of POST /bot<token>/sendMessage, in Telegram's snake_case
+export const telegramSendMessageRequestSchema = z.object({
+  chat_id: z.union([z.string(), z.number().int()]),
+  text: z.string().min(1).max(TELEGRAM_MAX_MESSAGE_LENGTH),
+  parse_mode: z.enum(['MarkdownV2', 'HTML', 'Markdown']).optional(),
+  disable_notification: z.boolean().optional(),
+  protect_content: z.boolean().optional(),
+})
+
+// Telegram returns a JSON body with `ok` and `description` even on 4xx errors
+export const telegramSendMessageResponseSchema = z.discriminatedUnion('ok', [
+  z.object({
+    ok: z.literal(true),
+    result: z.object({
+      message_id: z.number().int(),
+      date: z.number().int(),
+      chat: z.object({
+        id: z.number().int(),
+      }),
+    }),
+  }),
+  z.object({
+    ok: z.literal(false),
+    error_code: z.number().int().optional(),
+    description: z.string().optional(),
+  }),
+])
+
+export const telegramMessageOutputSchema = z.object({
+  messageId: z.number().int(),
+  // Always numeric: Telegram resolves @channelusername to the chat's ID
+  chatId: z.number().int(),
+  sentAt: z.date(),
+})
+
+export type TelegramMessageInput = z.infer<typeof telegramMessageInputSchema>
+export type TelegramMessageOptions = z.infer<typeof telegramMessageOptionsSchema>
+export type TelegramMessageOutput = z.infer<typeof telegramMessageOutputSchema>