slack-logs 3.0.3 → 3.0.5

package/README.md

@@ -78,6 +78,29 @@ slack.logBlockMessage("Validation Message!", payload);
 - if `slackLogConfig(...)` is used, env values are ignored for both fields
 - `slackLogConfig(...)` does not ask for values interactively
 
+### Required Slack webhook setup
+
+- credential required: `Incoming Webhook URL`
+- URL format: `https://hooks.slack.com/services/...`
+- where to find it: Slack App Settings -> `Incoming Webhooks` -> `Webhook URLs for Your Workspace`
+- enable `Incoming Webhooks` first in the app settings
+- each webhook URL is tied to one Slack channel
+- if you need different channels, create separate webhook URLs or use `slackbot`
+
+### Create the Slack app / webhook if you don't have one
+
+1. Go to `https://api.slack.com/apps`
+2. Click `Create New App`
+3. Select `From scratch`
+4. Enter the app name and choose the workspace
+5. Open `Incoming Webhooks`
+6. Turn on `Activate Incoming Webhooks`
+7. Click `Add New Webhook to Workspace`
+8. Select the Slack channel
+9. Click `Allow`
+10. Copy the webhook URL from `Webhook URLs for Your Workspace`
+11. Use it in `slackLogConfig({ webhookUrl: "..." })` or `SLACK_WEBHOOK_URL`
+
 #### Option 2: Use environment variables
 
 Use env values only when `slackLogConfig(...)` is not called.
@@ -267,3 +290,168 @@ slack.rawBody(payload);
 ```
 
 If payload is invalid or sending fails, it logs a console error.
+
+---
+
+## Slack Bot
+
+Use `slackbot` when you want the same logging helpers with bot-token based multi-channel support.
+
+### Configuration
+
+```
+import { slackbot, slackBotConfig } from "slack-logs";
+or
+const { slackbot, slackBotConfig } = require("slack-logs");
+
+slackBotConfig({
+  botToken: "xoxb-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX",
+  defaultChannelId: "C0123456789",
+  enableAlerts: true,
+});
+```
+
+`slackBotConfig(...)` rules:
+
+- `botToken` and `enableAlerts` are required
+- `defaultChannelId` is optional if you pass `channelId` in method calls
+- if `defaultChannelId` is not set in config, package falls back to `SLACK_BOT_DEFAULT_CHANNEL_ID`
+
+### Required Slack app setup
+
+- token required: `Bot User OAuth Access Token`
+- token format: `xoxb-...`
+- where to find it: Slack App Settings -> `OAuth & Permissions` -> `Bot User OAuth Access Token`
+- important: the token appears only after you click `Install to Workspace`
+- add scopes under `OAuth & Permissions` -> `Bot Token Scopes`
+- required scope: `chat:write`
+- optional scope: `chat:write.public` if you want to post in public channels without inviting the app first
+- do not use `User Token Scopes`
+- do not use app-level tokens (`xapp-...`) for this package
+- if the app is not in a channel, invite it first unless you added `chat:write.public`
+
+### Environment variables
+
+Use env values only when `slackBotConfig(...)` is not called.
+
+`.env` 🚨
+
+```
+...
+SLACK_BOT_TOKEN="xoxb-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX"
+SLACK_BOT_DEFAULT_CHANNEL_ID="C0123456789"
+
+# Optional field.
+# If not defined, logs are sent by default.
+# true / True / TRUE sends logs.
+# false / False / FALSE skips logs.
+ENABLE_SLACK_BOT_LOGS=true
+...
+```
+
+### Create the Slack app if you don't have one
+
+1. Go to `https://api.slack.com/apps`
+2. Click `Create New App`
+3. Select `From scratch`
+4. Enter the app name and choose the workspace
+5. Open `OAuth & Permissions`
+6. Under `Bot Token Scopes`, add `chat:write`
+7. Optional: add `chat:write.public`
+8. Click `Install to Workspace`
+9. Copy the `Bot User OAuth Access Token` (`xoxb-...`)
+10. Use it in `slackBotConfig({ botToken: "xoxb-..." })` or `SLACK_BOT_TOKEN`
+
+### Methods
+
+```
+slackbot.log(label, data, channelId?);
+slackbot.logBlockMessage(label, payload, errorType?, channelId?);
+slackbot.rawBody(payload, channelId?);
+```
+
+### `slackbot.log(...)`
+
+`slackbot.log(...)` uses the same payload format as `slack.log(...)`, so the output style is the same.
+
+```
+import { slackbot } from "slack-logs";
+
+slackbot.log("Data Log with bold", "Here is *BOLD* message", "C0123456789");
+slackbot.log("Highlight Log", "`Message`", "C0123456789");
+slackbot.log("Emoji :rocket: Log", "Yeah :female-technologist::skin-tone-2:");
+slackbot.log("Object Log", {id:"123", value:"Lorem Impulse"});
+```
+
+![Sample Image](https://i.imgur.com/ucAnAiJ.png)
+
+### `slackbot.logBlockMessage(...)`
+
+`slackbot.logBlockMessage(...)` uses the same payload format as `slack.logBlockMessage(...)`, so the same output examples apply.
+
+```
+import { LogLevel, slackbot } from "slack-logs";
+
+const payload = [
+{ title: "Title 1", value: "1234" },
+{ title: "Title 2", value: 123 },
+{ title: "Title 3", value: { id: 12 } },
+{ title: "Title 4", value: [{ id: 12 }] },
+];
+
+slackbot.logBlockMessage("Custom Logs!", payload, LogLevel.DEFAULT, "C0123456789");
+slackbot.logBlockMessage("Some Information Logs!", payload, LogLevel.INFO);
+slackbot.logBlockMessage("Critical Alert!", payload, LogLevel.ERROR);
+```
+
+![Sample Image](https://i.imgur.com/Ohlktzr.png)
+
+### `slackbot.rawBody(...)`
+
+Use `slackbot.rawBody(...)` when you want to send a custom Slack payload with an optional `channelId`.
+
+```
+import { slackbot } from "slack-logs";
+
+const payload = {
+  blocks: [
+    {
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: "Hello from custom payload",
+      },
+    },
+    {
+      type: "divider",
+    },
+    {
+      type: "actions",
+      elements: [
+        {
+          type: "button",
+          text: {
+            type: "plain_text",
+            text: "Open",
+            emoji: true,
+          },
+          value: "click_me_123",
+          url: "https://google.com",
+        },
+      ],
+    },
+  ],
+};
+
+slackbot.rawBody(payload, "C0123456789");
+```
+
+`slackbot.rawBody(...)` expects a plain object payload like:
+
+```
+{
+  "blocks": [...]
+}
+```
+
+If payload is invalid or sending fails, it logs a console error.

package/dist/index.d.ts

@@ -1,30 +1,13 @@
+import type { BlocksInterface, LogLevel } from "./shared";
 interface Slack {
     log(label: string, data: any): Promise<null | undefined>;
-    logBlockMessage(label: string, objectData: BlocksInterface[], error_type?: LogLevel): Promise<null | undefined>;
+    logBlockMessage(label: string, objectData: BlocksInterface[], errorType?: LogLevel): Promise<null | undefined>;
     rawBody(payload: Record<string, any>): Promise<null | undefined>;
 }
-export interface SlackLogConfigOptions {
-    webhookUrl: string;
-    enableAlerts: boolean;
-}
-interface BlocksInterface {
-    title: string;
-    value: any;
-}
-export declare enum LogLevel {
-    DEFAULT = "DEFAULT",
-    SUCCESS = "SUCCESS",
-    INFO = "INFO",
-    WARN = "WARN",
-    ERROR = "ERROR"
-}
-export declare enum LogColor {
-    DEFAULT = "#B4B4B8",
-    SUCCESS = "#65B741",
-    INFO = "#40A2D8",
-    WARN = "#E3651D",
-    ERROR = "#FF0000"
-}
-export declare function slackLogConfig(config: SlackLogConfigOptions): void;
+export type { SlackBotConfigOptions } from "./slack-bot";
+export { slackBotConfig, slackbot } from "./slack-bot";
+export type { BlocksInterface } from "./shared";
+export { LogColor, LogLevel } from "./shared";
+export type { SlackLogConfigOptions } from "./webhook";
+export { slackLogConfig } from "./webhook";
 export declare const slack: Slack;
-export {};

package/dist/index.js

@@ -1 +1 @@
-"use strict";function e(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}Object.defineProperty(exports,"__esModule",{value:!0});var o,t,r=e(require("axios"));exports.LogLevel=void 0,(o=exports.LogLevel||(exports.LogLevel={})).DEFAULT="DEFAULT",o.SUCCESS="SUCCESS",o.INFO="INFO",o.WARN="WARN",o.ERROR="ERROR",exports.LogColor=void 0,(t=exports.LogColor||(exports.LogColor={})).DEFAULT="#B4B4B8",t.SUCCESS="#65B741",t.INFO="#40A2D8",t.WARN="#E3651D",t.ERROR="#FF0000";const n={};const s={async log(e,o){const t=JSON.stringify(o);if(!l())return console.error("🚨 Invalid Slack webhook URL. Kindly check slackLogConfig(...) or 'SLACK_WEBHOOK_URL' in your .env file! 🚨"),null;let r={text:`*${e}:* ${t}`};await c(r)},async logBlockMessage(e,o,t=exports.LogLevel.DEFAULT){if(!l())return console.error("🚨 Invalid Slack webhook URL. Kindly check slackLogConfig(...) or 'SLACK_WEBHOOK_URL' in your .env file! 🚨"),null;const r=exports.LogColor[t],n=[],s=[],a=[];n.push({type:"divider"}),n.push({type:"header",text:{type:"plain_text",text:e,emoji:!0}}),n.push({type:"divider"}),o?.length&&o.forEach((e=>{let o=JSON.stringify(e.value);a.push({type:"section",text:{type:"mrkdwn",text:`*${e.title}:* ${o}`}})})),s.push({color:r,blocks:a});let i={text:e,blocks:n,attachments:s};await c(i)},rawBody:async e=>l()?function(e){return!!e&&"object"==typeof e&&!Array.isArray(e)}(e)?void await c(e):(console.error('🚨 Invalid Slack payload for rawBody(...). Expected an object like { "blocks": [...] } 🚨'),null):(console.error("🚨 Invalid Slack webhook URL. Kindly check slackLogConfig(...) or 'SLACK_WEBHOOK_URL' in your .env file! 🚨"),null)};function l(){const e=a();if(!e)return!1;return!!/^https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9]+\/[A-Za-z0-9]+\/[A-Za-z0-9]+$/.test(e)||(console.error(`🚨 Slack webhook URL does not look in correct format. Current value is "${e}", expected format is "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX". 🚨`),!1)}function a(){return n.webhookUrl??process.env.SLACK_WEBHOOK_URL}async function c(e){if(!function(){if("boolean"==typeof n.enableAlerts)return n.enableAlerts;const e=(process?.env?.ENABLE_SLACK_LOGS??"").toString().trim();return!e||"true"===e.toLowerCase()||(e.toLowerCase(),!1)}())return null;const o=a();return await r.default.post(o,JSON.stringify(e),{headers:{"Content-Type":"application/json"}}).catch((e=>{const o=e?.response?.data?.error||e?.response?.statusText||e?.message||"Unknown error";console.error(`🚨 Error sending log message to Slack: ${o}`)}))}exports.slack=s,exports.slackLogConfig=function(e){n.webhookUrl=e.webhookUrl,n.enableAlerts=e.enableAlerts};
+"use strict";function e(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}Object.defineProperty(exports,"__esModule",{value:!0});var o,t,n=e(require("axios"));exports.LogLevel=void 0,(o=exports.LogLevel||(exports.LogLevel={})).DEFAULT="DEFAULT",o.SUCCESS="SUCCESS",o.INFO="INFO",o.WARN="WARN",o.ERROR="ERROR",exports.LogColor=void 0,(t=exports.LogColor||(exports.LogColor={})).DEFAULT="#B4B4B8",t.SUCCESS="#65B741",t.INFO="#40A2D8",t.WARN="#E3651D",t.ERROR="#FF0000";const r={};function s(){const e=l();if(!e)return!1;return!!/^https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9]+\/[A-Za-z0-9]+\/[A-Za-z0-9]+$/.test(e)||(console.error(`🚨 Slack webhook URL does not look in correct format. Current value is "${e}", expected format is "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX". 🚨`),!1)}function l(){return r.webhookUrl??process.env.SLACK_WEBHOOK_URL}async function a(e){if(!function(){if("boolean"==typeof r.enableAlerts)return r.enableAlerts;const e=(process?.env?.ENABLE_SLACK_LOGS??"").toString().trim();return!e||"true"===e.toLowerCase()||(e.toLowerCase(),!1)}())return null;const o=l();await n.default.post(o,JSON.stringify(e),{headers:{"Content-Type":"application/json"}}).catch((e=>{const o=e?.response?.data?.error||e?.response?.statusText||e?.message||"Unknown error";console.error(`🚨 Error sending log message to Slack: ${o}`)}))}const c={};const i={log:async(e,o,t)=>(await p(function(e,o){return{text:`*${e}:* ${JSON.stringify(o)}`}}(e,o),t),null),logBlockMessage:async(e,o,t=exports.LogLevel.DEFAULT,n)=>(await p(function(e,o,t=exports.LogLevel.DEFAULT){const n=[];return o?.length&&o.forEach((e=>{n.push({type:"section",text:{type:"mrkdwn",text:`*${e.title}:* ${JSON.stringify(e.value)}`}})})),{text:e,blocks:[{type:"divider"},{type:"header",text:{type:"plain_text",text:e,emoji:!0}},{type:"divider"}],attachments:[{color:exports.LogColor[t],blocks:n}]}}(e,o,t),n),null),rawBody:async(e,o)=>function(e){return!!e&&"object"==typeof e&&!Array.isArray(e)}(e)?(await p(e,o),null):(console.error('🚨 Invalid Slack payload for slackbot.rawBody(...). Expected an object like { "blocks": [...] } 🚨'),null)};function u(e,o){const t=("string"==typeof e.channel?e.channel:void 0)??o??c.defaultChannelId??process.env.SLACK_BOT_DEFAULT_CHANNEL_ID;return function(e){return!!e&&/^[CGD][A-Z0-9]+$/.test(e)}(t)?t:(console.error("🚨 Invalid Slack channel ID. Kindly pass a valid channelId or set 'defaultChannelId' in slackBotConfig(...) / 'SLACK_BOT_DEFAULT_CHANNEL_ID' in your .env file! 🚨"),null)}async function p(e,o){if(!function(){if("boolean"==typeof c.enableAlerts)return c.enableAlerts;const e=(process?.env?.ENABLE_SLACK_BOT_LOGS??process?.env?.ENABLE_SLACK_LOGS??"").toString().trim();return!e||"true"===e.toLowerCase()||(e.toLowerCase(),!1)}())return null;const t=c.botToken??process.env.SLACK_BOT_TOKEN;if(!function(e){return!!e&&/^xoxb-[A-Za-z0-9-]+$/.test(e)}(t))return console.error("🚨 Invalid Slack bot token. Kindly check slackBotConfig(...) or 'SLACK_BOT_TOKEN' in your .env file! 🚨"),null;const r=u(e,o);return r?await n.default.post("https://slack.com/api/chat.postMessage",{...e,channel:r},{headers:{Authorization:`Bearer ${t}`,"Content-Type":"application/json; charset=utf-8"}}).then((e=>{e?.data?.ok||console.error(`🚨 Error sending bot message to Slack: ${e?.data?.error||"Unknown error"}`)})).catch((e=>{const o=e?.response?.data?.error||e?.response?.statusText||e?.message||"Unknown error";console.error(`🚨 Error sending bot message to Slack: ${o}`)})):null}const d={...{async log(e,o){const t=JSON.stringify(o);if(!s())return console.error("🚨 Invalid Slack webhook URL. Kindly check slackLogConfig(...) or 'SLACK_WEBHOOK_URL' in your .env file! 🚨"),null;const n={text:`*${e}:* ${t}`};await a(n)},async logBlockMessage(e,o,t=exports.LogLevel.DEFAULT){if(!s())return console.error("🚨 Invalid Slack webhook URL. Kindly check slackLogConfig(...) or 'SLACK_WEBHOOK_URL' in your .env file! 🚨"),null;const n=exports.LogColor[t],r=[],l=[],c=[];r.push({type:"divider"}),r.push({type:"header",text:{type:"plain_text",text:e,emoji:!0}}),r.push({type:"divider"}),o?.length&&o.forEach((e=>{const o=JSON.stringify(e.value);c.push({type:"section",text:{type:"mrkdwn",text:`*${e.title}:* ${o}`}})})),l.push({color:n,blocks:c});const i={text:e,blocks:r,attachments:l};await a(i)},rawBody:async e=>s()?function(e){return!!e&&"object"==typeof e&&!Array.isArray(e)}(e)?void await a(e):(console.error('🚨 Invalid Slack payload for rawBody(...). Expected an object like { "blocks": [...] } 🚨'),null):(console.error("🚨 Invalid Slack webhook URL. Kindly check slackLogConfig(...) or 'SLACK_WEBHOOK_URL' in your .env file! 🚨"),null)}};exports.slack=d,exports.slackBotConfig=function(e){c.botToken=e.botToken,c.defaultChannelId=e.defaultChannelId,c.enableAlerts=e.enableAlerts},exports.slackLogConfig=function(e){r.webhookUrl=e.webhookUrl,r.enableAlerts=e.enableAlerts},exports.slackbot=i;

package/dist/shared.d.ts

@@ -0,0 +1,40 @@
+export interface BlocksInterface {
+    title: string;
+    value: any;
+}
+export declare enum LogLevel {
+    DEFAULT = "DEFAULT",
+    SUCCESS = "SUCCESS",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+export declare enum LogColor {
+    DEFAULT = "#B4B4B8",
+    SUCCESS = "#65B741",
+    INFO = "#40A2D8",
+    WARN = "#E3651D",
+    ERROR = "#FF0000"
+}
+export declare function buildLogPayload(label: string, data: any): {
+    text: string;
+};
+export declare function buildLogBlockPayload(label: string, objectData: BlocksInterface[], errorType?: LogLevel): {
+    text: string;
+    blocks: ({
+        type: string;
+        text?: undefined;
+    } | {
+        type: string;
+        text: {
+            type: string;
+            text: string;
+            emoji: boolean;
+        };
+    })[];
+    attachments: {
+        color: LogColor;
+        blocks: object[];
+    }[];
+};
+export declare function isValidRawPayload(payload: Record<string, any>): boolean;

package/dist/slack-bot.d.ts

@@ -0,0 +1,15 @@
+import type { BlocksInterface } from "./shared";
+import { LogLevel } from "./shared";
+export interface SlackBotConfigOptions {
+    botToken: string;
+    defaultChannelId?: string;
+    enableAlerts: boolean;
+}
+interface SlackBot {
+    log(label: string, data: any, channelId?: string): Promise<null | undefined>;
+    logBlockMessage(label: string, objectData: BlocksInterface[], errorType?: LogLevel, channelId?: string): Promise<null | undefined>;
+    rawBody(payload: Record<string, any>, channelId?: string): Promise<null | undefined>;
+}
+export declare function slackBotConfig(config: SlackBotConfigOptions): void;
+export declare const slackbot: SlackBot;
+export {};

package/dist/webhook.d.ts

@@ -0,0 +1,12 @@
+import { LogLevel } from "./shared";
+import type { BlocksInterface } from "./shared";
+export interface SlackLogConfigOptions {
+    webhookUrl: string;
+    enableAlerts: boolean;
+}
+export declare function slackLogConfig(config: SlackLogConfigOptions): void;
+export declare const slackWebhook: {
+    log(label: string, data: any): Promise<null | undefined>;
+    logBlockMessage(label: string, objectData: BlocksInterface[], errorType?: LogLevel): Promise<null | undefined>;
+    rawBody(payload: Record<string, any>): Promise<null | undefined>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-logs",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "slack-logs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",