@amirhosseinnouri/send 1.0.0-2

package/README.md

@@ -0,0 +1,181 @@
+# @amirhosseinnouri/send
+
+Send a **structured message** to a chat provider — from code or the command line.
+
+Supported providers: **Slack**, **Microsoft Teams**, **Telegram**, **Element/Matrix**, **Mattermost**.
+
+A message is provider-agnostic:
+
+```ts
+interface Message {
+  title?: string;
+  body: string;
+  markdown?: boolean; // render the body as markdown in the provider's native format
+}
+```
+
+Each provider renders it into its own native format (Slack blocks, Teams MessageCard,
+Telegram/Element markdown, Mattermost attachment). With `markdown: true` the body is
+rendered as rich markdown; otherwise it is sent as plain text.
+
+## Install
+
+```sh
+npm i @amirhosseinnouri/send
+# or run directly, no install:
+npx @amirhosseinnouri/send --help
+```
+
+## Programmatic API
+
+```ts
+import { send, createSender } from "@amirhosseinnouri/send";
+
+// one-shot — flat config + message
+await send({
+  provider: "slack",
+  webhookUrl: "https://hooks.slack.com/services/...",
+  title: "Release 1.2.0",
+  body: "## Changes\n- Fixed a bug",
+  markdown: true,
+});
+
+// reusable sender bound to one provider
+const sender = createSender({ provider: "telegram", botToken: "T", chatId: "42" });
+await sender.send({ body: "hello" });
+```
+
+Exports also include the zod schemas (`senderConfigSchema`, `messageSchema`,
+`providerConfigSchemas`, ...) and the `PROVIDERS` list for consumers that want to
+validate input or reuse the per-provider config shapes.
+
+### Provider config
+
+| provider     | config keys                                    |
+| ------------ | ---------------------------------------------- |
+| `slack`      | `webhookUrl`                                   |
+| `teams`      | `webhookUrl`                                   |
+| `mattermost` | `webhookUrl`                                   |
+| `telegram`   | `botToken`, `chatId`                           |
+| `element`    | `homeserverUrl`, `accessToken`, `roomId`       |
+
+## CLI
+
+```sh
+send --provider slack --webhook-url <url> \
+  --title "Release 1.2" --body "Bug **fixes**" --markdown
+```
+
+- Provider config flags: `--webhook-url` (slack/teams/mattermost);
+  `--bot-token --chat-id` (telegram);
+  `--homeserver-url --access-token --room-id` (element).
+- Body: `--body <text>` (required).
+- `--title` optional. `--markdown` renders the body as markdown (off by default).
+
+```sh
+send --provider telegram --bot-token T --chat-id 42 --title Hi --body "the body"
+```
+
+## Examples by provider
+
+Each block shows the CLI invocation and the equivalent programmatic call.
+
+### Slack
+
+```sh
+send --provider slack \
+  --webhook-url https://hooks.slack.com/services/T000/B000/XXXX \
+  --title "Release 1.2.0" --body "Bug **fixes** and improvements" --markdown
+```
+
+```ts
+await send({
+  provider: "slack",
+  webhookUrl: "https://hooks.slack.com/services/T000/B000/XXXX",
+  title: "Release 1.2.0",
+  body: "Bug **fixes** and improvements",
+  markdown: true,
+});
+```
+
+### Microsoft Teams
+
+```sh
+send --provider teams \
+  --webhook-url https://outlook.office.com/webhook/XXXX/IncomingWebhook/YYYY \
+  --title "Deploy complete" --body "Shipped to **production**" --markdown
+```
+
+```ts
+await send({
+  provider: "teams",
+  webhookUrl: "https://outlook.office.com/webhook/XXXX/IncomingWebhook/YYYY",
+  title: "Deploy complete",
+  body: "Shipped to **production**",
+  markdown: true,
+});
+```
+
+### Telegram
+
+```sh
+send --provider telegram \
+  --bot-token 123456:ABC-DEF1234ghIkl \
+  --chat-id -1001234567890 \
+  --title "Alert" --body "Disk usage at *90%*" --markdown
+```
+
+```ts
+await send({
+  provider: "telegram",
+  botToken: "123456:ABC-DEF1234ghIkl",
+  chatId: "-1001234567890",
+  title: "Alert",
+  body: "Disk usage at *90%*",
+  markdown: true,
+});
+```
+
+### Element / Matrix
+
+```sh
+send --provider element \
+  --homeserver-url https://matrix.org \
+  --access-token syt_XXXX \
+  --room-id '!abc123:matrix.org' \
+  --title "CI" --body "Build **passed**" --markdown
+```
+
+```ts
+await send({
+  provider: "element",
+  homeserverUrl: "https://matrix.org",
+  accessToken: "syt_XXXX",
+  roomId: "!abc123:matrix.org",
+  title: "CI",
+  body: "Build **passed**",
+  markdown: true,
+});
+```
+
+### Mattermost
+
+```sh
+send --provider mattermost \
+  --webhook-url https://chat.example.com/hooks/xxxxxxxxxxxxxxxxx \
+  --title "Backup" --body "Nightly backup `OK`" --markdown
+```
+
+```ts
+await send({
+  provider: "mattermost",
+  webhookUrl: "https://chat.example.com/hooks/xxxxxxxxxxxxxxxxx",
+  title: "Backup",
+  body: "Nightly backup `OK`",
+  markdown: true,
+});
+```
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_command_line_args = __toESM(require("command-line-args"), 1);
+var import_zod7 = require("zod");
+
+// src/schema/sender.ts
+var import_zod6 = require("zod");
+
+// src/schema/element.ts
+var import_zod = require("zod");
+var elementConfigSchema = import_zod.z.object({
+  provider: import_zod.z.literal("element"),
+  homeserverUrl: import_zod.z.url(),
+  accessToken: import_zod.z.string(),
+  roomId: import_zod.z.string()
+});
+
+// src/schema/mattermost.ts
+var import_zod2 = require("zod");
+var mattermostConfigSchema = import_zod2.z.object({
+  provider: import_zod2.z.literal("mattermost"),
+  webhookUrl: import_zod2.z.url()
+});
+
+// src/schema/slack.ts
+var import_zod3 = require("zod");
+var slackConfigSchema = import_zod3.z.object({
+  provider: import_zod3.z.literal("slack"),
+  webhookUrl: import_zod3.z.url()
+});
+
+// src/schema/teams.ts
+var import_zod4 = require("zod");
+var teamsConfigSchema = import_zod4.z.object({
+  provider: import_zod4.z.literal("teams"),
+  webhookUrl: import_zod4.z.url()
+});
+
+// src/schema/telegram.ts
+var import_zod5 = require("zod");
+var telegramConfigSchema = import_zod5.z.object({
+  provider: import_zod5.z.literal("telegram"),
+  botToken: import_zod5.z.string(),
+  chatId: import_zod5.z.string()
+});
+
+// src/schema/sender.ts
+var messageSchema = import_zod6.z.object({
+  title: import_zod6.z.string().optional(),
+  body: import_zod6.z.string(),
+  /** Render the body as markdown in the provider's native format. */
+  markdown: import_zod6.z.boolean().optional()
+});
+var senderConfigSchema = import_zod6.z.discriminatedUnion("provider", [
+  slackConfigSchema,
+  teamsConfigSchema,
+  mattermostConfigSchema,
+  telegramConfigSchema,
+  elementConfigSchema
+]);
+var sendInputSchema = import_zod6.z.intersection(
+  senderConfigSchema,
+  messageSchema
+);
+
+// src/lib/flags.ts
+var toKebab = (key) => key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+var flagFor = (key) => `--${toKebab(key)}`;
+var configKeys = [
+  ...new Set(
+    senderConfigSchema.options.flatMap((option) => Object.keys(option.shape))
+  )
+];
+var configOptionDefinitions = configKeys.map((key) => ({
+  name: toKebab(key),
+  type: String
+}));
+var optionDefinitions = [
+  ...configOptionDefinitions,
+  { name: "title", type: String },
+  { name: "body", type: String },
+  { name: "markdown", type: Boolean },
+  { name: "help", alias: "h", type: Boolean }
+];
+
+// src/lib/config.ts
+function formatConfigError(error) {
+  const lines = error.issues.map((issue) => {
+    const key = issue.path[0];
+    const where = typeof key === "string" ? flagFor(key) : "config";
+    return `  \u2192 ${where}: ${issue.message}`;
+  });
+  return `Invalid provider config:
+${lines.join("\n")}`;
+}
+function parseConfig(values) {
+  const result = senderConfigSchema.safeParse(values);
+  if (!result.success) {
+    throw new Error(formatConfigError(result.error));
+  }
+  return result.data;
+}
+
+// src/providers/element.ts
+var import_marked = require("marked");
+var ElementSender = class {
+  name = "Element";
+  homeserverUrl;
+  accessToken;
+  roomId;
+  constructor(config) {
+    this.homeserverUrl = config.homeserverUrl;
+    this.accessToken = config.accessToken;
+    this.roomId = config.roomId;
+  }
+  async send(message) {
+    const lines = [];
+    if (message.title) {
+      lines.push(message.markdown ? `**${message.title}**` : message.title, "");
+    }
+    lines.push(message.body);
+    const body = lines.join("\n");
+    const formatted = message.markdown ? {
+      format: "org.matrix.custom.html",
+      formatted_body: await import_marked.marked.parse(body, { async: true })
+    } : {};
+    const txnId = `send-${Date.now()}`;
+    const encodedRoomId = encodeURIComponent(this.roomId);
+    const url = `${this.homeserverUrl}/_matrix/client/v3/rooms/${encodedRoomId}/send/m.room.message/${txnId}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.accessToken}`
+        },
+        body: JSON.stringify({
+          msgtype: "m.text",
+          body,
+          ...formatted
+        })
+      });
+    } catch (error) {
+      const cause = error instanceof Error ? error.cause ?? error.message : error;
+      throw new Error(`Element fetch failed: ${JSON.stringify(cause)}`);
+    }
+    if (!response.ok) {
+      const responseBody = await response.text();
+      throw new Error(
+        `Element API returned status ${response.status}: ${responseBody}`
+      );
+    }
+  }
+};
+
+// src/providers/mattermost.ts
+var MattermostSender = class {
+  name = "Mattermost";
+  webhookUrl;
+  constructor(config) {
+    this.webhookUrl = config.webhookUrl;
+  }
+  /** Mattermost always renders markdown; escape special chars for plain bodies. */
+  escapeMarkdown(text) {
+    return text.replace(/([\\`*_{}[\]()#+\-.!|>~])/g, "\\$1");
+  }
+  async send(message) {
+    const summary = message.title ?? message.body;
+    const body = message.markdown ? message.body : this.escapeMarkdown(message.body);
+    const payload = {
+      text: message.title ? `#### ${message.title}` : "",
+      attachments: [
+        {
+          fallback: summary,
+          color: "#2eb886",
+          text: body
+        }
+      ]
+    };
+    const response = await fetch(this.webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const body2 = await response.text();
+      throw new Error(
+        `Mattermost webhook returned status ${response.status}: ${body2}`
+      );
+    }
+  }
+};
+
+// src/providers/slack.ts
+var SlackSender = class {
+  name = "Slack";
+  webhookUrl;
+  constructor(config) {
+    this.webhookUrl = config.webhookUrl;
+  }
+  async send(message) {
+    const summary = message.title ?? message.body;
+    const blocks = [];
+    if (message.title) {
+      blocks.push({
+        type: "header",
+        text: { type: "plain_text", text: message.title }
+      });
+    }
+    blocks.push({ type: "divider" });
+    blocks.push({
+      type: "section",
+      text: {
+        type: message.markdown ? "mrkdwn" : "plain_text",
+        text: message.body
+      }
+    });
+    const payload = { text: summary, blocks };
+    const response = await fetch(this.webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(
+        `Slack webhook returned status ${response.status}: ${body}`
+      );
+    }
+  }
+};
+
+// src/providers/teams.ts
+var TeamsSender = class {
+  name = "Microsoft Teams";
+  webhookUrl;
+  constructor(config) {
+    this.webhookUrl = config.webhookUrl;
+  }
+  async send(message) {
+    const summary = message.title ?? message.body;
+    const messageCard = {
+      "@type": "MessageCard",
+      "@context": "https://schema.org/extensions",
+      themeColor: "0078D7",
+      summary,
+      sections: [
+        {
+          activityTitle: message.title,
+          text: message.body,
+          markdown: message.markdown ?? false
+        }
+      ]
+    };
+    const response = await fetch(this.webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(messageCard)
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Teams webhook returned status ${response.status}: ${response.statusText}`
+      );
+    }
+  }
+};
+
+// src/providers/telegram.ts
+var TelegramSender = class {
+  name = "Telegram";
+  botToken;
+  chatId;
+  constructor(config) {
+    this.botToken = config.botToken;
+    this.chatId = config.chatId;
+  }
+  escapeMarkdown(text) {
+    return text.replace(/([*_`[])/g, "\\$1");
+  }
+  async send(message) {
+    const lines = [];
+    if (message.markdown) {
+      if (message.title) {
+        lines.push(`*${this.escapeMarkdown(message.title)}*`, "");
+      }
+      lines.push(message.body);
+    } else {
+      if (message.title) lines.push(message.title, "");
+      lines.push(message.body);
+    }
+    const text = lines.join("\n");
+    const url = `https://api.telegram.org/bot${this.botToken}/sendMessage`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        chat_id: this.chatId,
+        text,
+        ...message.markdown ? { parse_mode: "Markdown" } : {}
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(
+        `Telegram API returned status ${response.status}: ${body}`
+      );
+    }
+  }
+};
+
+// src/providers/index.ts
+function createSender(config) {
+  switch (config.provider) {
+    case "slack":
+      return new SlackSender(config);
+    case "teams":
+      return new TeamsSender(config);
+    case "mattermost":
+      return new MattermostSender(config);
+    case "telegram":
+      return new TelegramSender(config);
+    case "element":
+      return new ElementSender(config);
+  }
+}
+
+// src/cli.ts
+var USAGE = `send \u2014 post a structured message to a chat provider
+
+Usage:
+  send --provider <slack|teams|telegram|element|mattermost> [config] --body <text> [options]
+
+Provider config:
+  slack | teams | mattermost   --webhook-url <url>
+  telegram                     --bot-token <token> --chat-id <id>
+  element                      --homeserver-url <url> --access-token <token> --room-id <id>
+
+Message:
+  --title <text>               Optional heading
+  --body <text>                Message body
+  --markdown                   Render the body as markdown
+
+Examples:
+  send --provider slack --webhook-url https://hooks.slack.com/... \\
+    --title "Release 1.2" --body "Bug **fixes**" --markdown
+
+  send --provider telegram --bot-token T --chat-id 42 --title Hi --body "the body"
+`;
+function fail(message) {
+  process.stderr.write(`${message}
+`);
+  process.exit(1);
+}
+async function main() {
+  const values = (0, import_command_line_args.default)(optionDefinitions, {
+    camelCase: true
+  });
+  if (values.help || !values.provider) {
+    process.stdout.write(USAGE);
+    process.exit(values.help ? 0 : 1);
+  }
+  const config = parseConfig(values);
+  const messageResult = messageSchema.safeParse({
+    title: values.title,
+    body: values.body,
+    markdown: values.markdown
+  });
+  if (!messageResult.success) {
+    fail(
+      `Invalid message (a body is required):
+${import_zod7.z.prettifyError(messageResult.error)}`
+    );
+  }
+  const sender = createSender(config);
+  try {
+    await sender.send(messageResult.data);
+    process.stdout.write(`Sent to ${sender.name}.
+`);
+  } catch (error) {
+    fail(`Failed to send to ${sender.name}: ${error.message}`);
+  }
+}
+main().catch((error) => fail(error.message));