@mirid-dev/sendkit-core 0.0.0-stage → 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

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @mirid-dev/sendkit-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const telegramMessageInputSchema: z.ZodObject<{
+  chatId: z.ZodString;
+  message: z.ZodString;
+}, z.core.$strip>;
+export declare const telegramMessageOptionsSchema: z.ZodObject<{
+  chatId: z.ZodString;
+  message: z.ZodString;
+  botToken: z.ZodString;
+}, z.core.$strip>;
+export declare const telegramSendMessageRequestSchema: z.ZodObject<{
+  chat_id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+  text: z.ZodString;
+  parse_mode: z.ZodOptional<z.ZodEnum<{
+    HTML: "HTML";
+    Markdown: "Markdown";
+    MarkdownV2: "MarkdownV2";
+  }>>;
+  disable_notification: z.ZodOptional<z.ZodBoolean>;
+  protect_content: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const telegramSendMessageResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  ok: z.ZodLiteral<true>;
+  result: z.ZodObject<{
+    message_id: z.ZodNumber;
+    date: z.ZodNumber;
+    chat: z.ZodObject<{
+      id: z.ZodNumber;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+  ok: z.ZodLiteral<false>;
+  error_code: z.ZodOptional<z.ZodNumber>;
+  description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "ok">;
+export declare const telegramMessageOutputSchema: z.ZodObject<{
+  messageId: z.ZodNumber;
+  chatId: z.ZodNumber;
+  sentAt: z.ZodDate;
+}, z.core.$strip>;
+export type TelegramMessageInput = z.infer<typeof telegramMessageInputSchema>;
+export type TelegramMessageOptions = z.infer<typeof telegramMessageOptionsSchema>;
+export type TelegramMessageOutput = z.infer<typeof telegramMessageOutputSchema>;
+export declare function sendTelegramMessage(input: z.input<typeof telegramMessageOptionsSchema>): Promise<TelegramMessageOutput>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/schemas.ts","../src/operations.ts"],"mappings":";qBAca,4BAA0B,EAAA;;;GASrC,EAAA,KAAA;qBAEW,8BAA4B,EAAA;;;;GAOvC,EAAA,KAAA;qBAGW,kCAAgC,EAAA;;;;;;;;;;GAM3C,EAAA,KAAA;qBAGW,mCAAiC,EAAA,uBAAA,EAAA;;;;;;;;;;;;;GAgB5C,EAAA,KAAA;qBAEW,6BAA2B,EAAA;;;;GAKtC,EAAA,KAAA;YAEU,uBAAuB,EAAE,aAAa;YACtC,yBAAyB,EAAE,aAAa;YACxC,wBAAwB,EAAE,aAAa;wBC5D7B,oBACpB,OAAO,EAAE,aAAa,gCACrB,QAAQ"}

package/dist/index.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+// src/schemas.ts
+const TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
+const telegramChatIdSchema = z.string().trim().refine((chatId) => /^-?\d+$/.test(chatId) || /^@\w{5,}$/.test(chatId), "Use a numeric chat ID or @channelusername");
+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`)
+});
+const telegramMessageOptionsSchema = telegramMessageInputSchema.extend({ botToken: z.string().trim().min(1, "Telegram bot token is required").regex(/^\d+:[\w-]+$/, "Expected a token like 123456789:ABC-DEF..., without the \"bot\" prefix") });
+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()
+});
+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()
+})]);
+const telegramMessageOutputSchema = z.object({
+	messageId: z.number().int(),
+	chatId: z.number().int(),
+	sentAt: z.date()
+});
+// src/operations.ts
+const TELEGRAM_REQUEST_TIMEOUT_MS = 1e4;
+async function sendTelegramMessage(input) {
+	const { chatId, message, botToken } = telegramMessageOptionsSchema.parse(input);
+	const requestBody = telegramSendMessageRequestSchema.parse({
+		chat_id: chatId,
+		text: message
+	});
+	let 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) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not reach Telegram: ${reason.replaceAll(botToken, "<redacted>")}`, { cause: error });
+	}
+	const parsedResponse = telegramSendMessageResponseSchema.safeParse(await response.json().catch(() => null));
+	if (!parsedResponse.success) {
+		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: /* @__PURE__ */ new Date(data.result.date * 1e3)
+	});
+}
+export { sendTelegramMessage, telegramMessageInputSchema, telegramMessageOptionsSchema, telegramMessageOutputSchema, telegramSendMessageRequestSchema, telegramSendMessageResponseSchema };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/schemas.ts","../src/operations.ts"],"sourcesContent":["import { z } from 'zod'\n\n// Telegram rejects message text longer than this\nconst TELEGRAM_MAX_MESSAGE_LENGTH = 4096\n\n// Numeric ID (negative for groups) or a public @channelusername\nconst telegramChatIdSchema = z\n  .string()\n  .trim()\n  .refine(\n    (chatId) => /^-?\\d+$/.test(chatId) || /^@\\w{5,}$/.test(chatId),\n    'Use a numeric chat ID or @channelusername',\n  )\n\nexport const telegramMessageInputSchema = z.object({\n  chatId: telegramChatIdSchema,\n  message: z\n    .string()\n    .refine((message) => message.trim().length > 0, 'Message cannot be empty')\n    .refine(\n      (message) => message.length <= TELEGRAM_MAX_MESSAGE_LENGTH,\n      `Telegram allows at most ${TELEGRAM_MAX_MESSAGE_LENGTH} characters`,\n    ),\n})\n\nexport const telegramMessageOptionsSchema = telegramMessageInputSchema.extend({\n  botToken: z\n    .string()\n    .trim()\n    .min(1, 'Telegram bot token is required')\n    // Tokens look like 123456789:AAH...; a copied \"bot\" prefix would otherwise surface as a 404\n    .regex(/^\\d+:[\\w-]+$/, 'Expected a token like 123456789:ABC-DEF..., without the \"bot\" prefix'),\n})\n\n// Body of POST /bot<token>/sendMessage, in Telegram's snake_case\nexport const telegramSendMessageRequestSchema = z.object({\n  chat_id: z.union([z.string(), z.number().int()]),\n  text: z.string().min(1).max(TELEGRAM_MAX_MESSAGE_LENGTH),\n  parse_mode: z.enum(['MarkdownV2', 'HTML', 'Markdown']).optional(),\n  disable_notification: z.boolean().optional(),\n  protect_content: z.boolean().optional(),\n})\n\n// Telegram returns a JSON body with `ok` and `description` even on 4xx errors\nexport const telegramSendMessageResponseSchema = z.discriminatedUnion('ok', [\n  z.object({\n    ok: z.literal(true),\n    result: z.object({\n      message_id: z.number().int(),\n      date: z.number().int(),\n      chat: z.object({\n        id: z.number().int(),\n      }),\n    }),\n  }),\n  z.object({\n    ok: z.literal(false),\n    error_code: z.number().int().optional(),\n    description: z.string().optional(),\n  }),\n])\n\nexport const telegramMessageOutputSchema = z.object({\n  messageId: z.number().int(),\n  // Always numeric: Telegram resolves @channelusername to the chat's ID\n  chatId: z.number().int(),\n  sentAt: z.date(),\n})\n\nexport type TelegramMessageInput = z.infer<typeof telegramMessageInputSchema>\nexport type TelegramMessageOptions = z.infer<typeof telegramMessageOptionsSchema>\nexport type TelegramMessageOutput = z.infer<typeof telegramMessageOutputSchema>\n","import { z } from 'zod'\nimport {\n  telegramMessageOutputSchema,\n  telegramMessageOptionsSchema,\n  telegramSendMessageRequestSchema,\n  telegramSendMessageResponseSchema,\n  type TelegramMessageOutput,\n} from './schemas'\n\nconst TELEGRAM_REQUEST_TIMEOUT_MS = 10_000\n\nexport async function sendTelegramMessage(\n  input: z.input<typeof telegramMessageOptionsSchema>,\n): Promise<TelegramMessageOutput> {\n  const { chatId, message, botToken } = telegramMessageOptionsSchema.parse(input)\n\n  const requestBody = telegramSendMessageRequestSchema.parse({\n    chat_id: chatId,\n    text: message,\n  })\n\n  let response: Response\n\n  try {\n    response = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify(requestBody),\n      signal: AbortSignal.timeout(TELEGRAM_REQUEST_TIMEOUT_MS),\n    })\n  } catch (error) {\n    // Don't rethrow the original error: the request URL contains the bot token\n    const reason = error instanceof Error ? error.message : String(error)\n    throw new Error(`Could not reach Telegram: ${reason.replaceAll(botToken, '<redacted>')}`, {\n      cause: error,\n    })\n  }\n\n  // Telegram returns a JSON body even on 4xx errors, but a proxy or outage page may not\n  const parsedResponse = telegramSendMessageResponseSchema.safeParse(\n    await response.json().catch(() => null),\n  )\n\n  if (!parsedResponse.success) {\n    // A 2xx we can't read may still mean the message went out, so warn before the caller resends\n    const hint = response.ok ? '; the message may still have been sent' : ''\n    throw new Error(`Unexpected response from Telegram (HTTP ${response.status})${hint}`)\n  }\n\n  const data = parsedResponse.data\n\n  if (!data.ok) {\n    throw new Error(\n      `Telegram API error (${response.status}): ${data.description || response.statusText || 'Unknown error'}`,\n    )\n  }\n\n  return telegramMessageOutputSchema.parse({\n    messageId: data.result.message_id,\n    chatId: data.result.chat.id,\n    sentAt: new Date(data.result.date * 1000),\n  })\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@mirid-dev/sendkit-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "pack:dry": "bun run build && bun pm pack --dry-run",
+    "prepublishOnly": "bun run build"
+  },
+  "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>