@xpr/nestjs-slack 0.0.0

package/decorators.d.ts

@@ -0,0 +1,72 @@
+import { ActionConstraints, OptionsConstraints, ShortcutConstraints, ViewConstraints } from "@slack/bolt";
+import { type Pattern } from "./utils";
+export { Pattern };
+/**
+ * @see https://tools.slack.dev/bolt-js/reference/
+ */
+export declare const EventTypes: {
+    Event: string;
+    Shortcut: string;
+    Command: string;
+    Action: string;
+    View: string;
+    Option: string;
+};
+/**
+ * Decorator for event events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/event-listening
+ * @see api https://api.slack.com/apis/events-api
+ * @param event
+ * @constructor
+ */
+export declare function SlackEvent(event: string): MethodDecorator;
+export type ShortCutId = Pattern | ShortcutConstraints;
+/**
+ * Decorator for shortcut events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/shortcuts
+ * @see api https://api.slack.com/interactivity/shortcuts
+ * @param shortcutId
+ * @constructor
+ */
+export declare function SlackShortcut(shortcutId: ShortCutId): MethodDecorator;
+/**
+ * Decorator for command events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/commands
+ * @see api https://api.slack.com/interactivity/slash-commands
+ * @param commandId
+ * @constructor
+ */
+export declare function SlackCommand(commandId: Pattern): MethodDecorator;
+export type ActionId = Pattern | ActionConstraints;
+/**
+ * Decorator for action events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/actions
+ * @param actionId
+ * @constructor
+ */
+export declare function SlackAction(actionId: ActionId): MethodDecorator;
+export type ViewId = Pattern | ViewConstraints;
+/**
+ * Decorator for view events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/view-submissions
+ * @param viewId
+ * @constructor
+ */
+export declare function SlackView(viewId: ViewId): MethodDecorator;
+export type OptionId = OptionsConstraints;
+/**
+ * Decorator for options events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/options
+ * @param optionId
+ * @constructor
+ */
+export declare function SlackOption(optionId: OptionId): MethodDecorator;
+/**
+ * Decorator for message events
+ *
+ * @see guide https://tools.slack.dev/bolt-js/concepts/message-listening
+ * @see reference https://api.slack.com/events/message
+ * @param pattern
+ * @constructor
+ */
+export declare function SlackMessage(pattern?: Pattern): MethodDecorator;

package/decorators.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventTypes = void 0;
+exports.SlackEvent = SlackEvent;
+exports.SlackShortcut = SlackShortcut;
+exports.SlackCommand = SlackCommand;
+exports.SlackAction = SlackAction;
+exports.SlackView = SlackView;
+exports.SlackOption = SlackOption;
+exports.SlackMessage = SlackMessage;
+const utils_1 = require("./utils");
+/**
+ * @see https://tools.slack.dev/bolt-js/reference/
+ */
+exports.EventTypes = {
+    Event: "event",
+    Shortcut: "shortcut",
+    Command: "command",
+    Action: "action",
+    View: "view",
+    Option: "option",
+};
+/**
+ * Decorator for event events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/event-listening
+ * @see api https://api.slack.com/apis/events-api
+ * @param event
+ * @constructor
+ */
+function SlackEvent(event) {
+    // todo input validation (types for event)
+    return (0, utils_1.eventDecorator)(exports.EventTypes.Event, event);
+}
+/**
+ * Decorator for shortcut events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/shortcuts
+ * @see api https://api.slack.com/interactivity/shortcuts
+ * @param shortcutId
+ * @constructor
+ */
+function SlackShortcut(shortcutId) {
+    return (0, utils_1.eventDecorator)(exports.EventTypes.Shortcut, shortcutId);
+}
+/**
+ * Decorator for command events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/commands
+ * @see api https://api.slack.com/interactivity/slash-commands
+ * @param commandId
+ * @constructor
+ */
+function SlackCommand(commandId) {
+    // todo input validation command must start with / etc.
+    return (0, utils_1.eventDecorator)(exports.EventTypes.Command, commandId);
+}
+/**
+ * Decorator for action events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/actions
+ * @param actionId
+ * @constructor
+ */
+function SlackAction(actionId) {
+    return (0, utils_1.eventDecorator)(exports.EventTypes.Action, actionId);
+}
+/**
+ * Decorator for view events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/view-submissions
+ * @param viewId
+ * @constructor
+ */
+function SlackView(viewId) {
+    return (0, utils_1.eventDecorator)(exports.EventTypes.View, viewId);
+}
+/**
+ * Decorator for options events
+ * @see guide https://tools.slack.dev/bolt-js/concepts/options
+ * @param optionId
+ * @constructor
+ */
+function SlackOption(optionId) {
+    return (0, utils_1.eventDecorator)(exports.EventTypes.Option, optionId);
+}
+/**
+ * Decorator for message events
+ *
+ * @see guide https://tools.slack.dev/bolt-js/concepts/message-listening
+ * @see reference https://api.slack.com/events/message
+ * @param pattern
+ * @constructor
+ */
+function SlackMessage(pattern = "*") {
+    return (0, utils_1.messageDecorator)("message", pattern);
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+import Slack from "./slack";
+export * from "./decorators";
+export { Slack };

package/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Slack = void 0;
+const slack_1 = __importDefault(require("./slack"));
+exports.Slack = slack_1.default;
+__exportStar(require("./decorators"), exports);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@xpr/nestjs-slack",
+  "version": "0.0.0",
+  "description": "NestJS server implementation of the Slack Assistant",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig-lib.json",
+    "postbuild": "cp package.json ../../dist/nestjs-slack/. && cp readme.md ../../dist/nestjs-slack/."
+  },
+  "author": "Ziv Perry",
+  "license": "MIT",
+  "keywords": [],
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ziv/nestjs-slack-assistant.git",
+    "directory": "libs/slack-assistant"
+  },
+  "bugs": {
+    "url": "https://github.com/ziv/nestjs-slack-assistant/issues"
+  },
+  "homepage": "https://github.com/ziv/nestjs-slack-assistant#readme",
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.4",
+    "@types/node": "^22.10.6"
+  },
+  "peerDependencies": {
+    "@nestjs/microservices": ">=11.0.13",
+    "@slack/bolt": ">=4.2.1",
+    "reflect-metadata": ">=0.2.2"
+  }
+}

package/readme.md

@@ -0,0 +1 @@
+# @xpr/nestjs-slack

package/slack.d.ts

@@ -0,0 +1,29 @@
+import { type CustomTransportStrategy, type MessageHandler, Server } from "@nestjs/microservices";
+import { App, type AppOptions } from "@slack/bolt";
+export type SlackOptions = {
+    /**
+     * Slack application options with required types
+     * @see https://github.com/slackapi/bolt-js
+     */
+    slack: AppOptions;
+};
+export default class Slack extends Server implements CustomTransportStrategy {
+    #private;
+    readonly options: SlackOptions;
+    constructor(options: SlackOptions);
+    listen(callback: () => void): Promise<void>;
+    close(): Promise<void>;
+    on(): void;
+    unwrap<T>(): T;
+    /**
+     * Register the handler for the event
+     * @param handler
+     * @protected
+     */
+    protected register(handler: MessageHandler): void;
+    /**
+     * Get/Create Bolt app instance
+     * @protected
+     */
+    protected app(): App;
+}

package/slack.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const microservices_1 = require("@nestjs/microservices");
+const bolt_1 = require("@slack/bolt");
+const decorators_1 = require("./decorators");
+const utils_1 = require("./utils");
+class Slack extends microservices_1.Server {
+    options;
+    #app;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    async listen(callback) {
+        for (const handler of this.getHandlers().values()) {
+            this.register(handler);
+            const { type, event } = handler.extras;
+            this.logger.log(`Handler [${type}] registered with (${event})`);
+        }
+        await this.app().start();
+        callback();
+    }
+    async close() {
+        this.#app && (await this.#app.stop());
+    }
+    on() {
+        throw new Error("Use SlackEvent decorator to register events");
+    }
+    unwrap() {
+        return this.#app;
+    }
+    /**
+     * Register the handler for the event
+     * @param handler
+     * @protected
+     */
+    register(handler) {
+        const { type, event } = handler.extras;
+        switch (type) {
+            case decorators_1.EventTypes.Shortcut:
+                return this.app().shortcut(event, handler);
+            case decorators_1.EventTypes.Action:
+                return this.app().action(event, handler);
+            case decorators_1.EventTypes.Event:
+                return this.app().event(event, // todo improve by providing types
+                handler);
+            case decorators_1.EventTypes.Command:
+                return this.app().command(event, handler);
+            case decorators_1.EventTypes.Option:
+                return this.app().options(event, handler);
+        }
+    }
+    /**
+     * Get/Create Bolt app instance
+     * @protected
+     */
+    app() {
+        if (!this.#app) {
+            // make sure to add logger if not provided
+            if (!this.options.slack.logger) {
+                this.options.slack.logger = (0, utils_1.adjustLogger)(this.logger);
+            }
+            this.#app = new bolt_1.App(this.options.slack);
+            this.logger.log("Bolt app created");
+        }
+        return this.#app;
+    }
+}
+exports.default = Slack;

package/utils.d.ts

@@ -0,0 +1,15 @@
+import { type Logger } from "@slack/bolt";
+export type Pattern = string | RegExp;
+/**
+ * Create method decorator
+ * @param type type of listener
+ * @param event how to identify the event
+ */
+export declare function eventDecorator<T>(type: string, event: T): MethodDecorator;
+/**
+ * Create method decorator
+ * @param type type of listener
+ * @param pattern how to identify the message
+ */
+export declare function messageDecorator(type: string, pattern: Pattern): MethodDecorator;
+export declare function adjustLogger(logger: any): Logger;

package/utils.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventDecorator = eventDecorator;
+exports.messageDecorator = messageDecorator;
+exports.adjustLogger = adjustLogger;
+const microservices_1 = require("@nestjs/microservices");
+const bolt_1 = require("@slack/bolt");
+const normalizePattern = (pattern) => {
+    if (typeof pattern === "string") {
+        return pattern;
+    }
+    if (pattern instanceof RegExp) {
+        return pattern.toString();
+    }
+    return JSON.stringify(pattern);
+};
+/**
+ * Create method decorator
+ * @param type type of listener
+ * @param event how to identify the event
+ */
+function eventDecorator(type, event) {
+    return (target, key, descriptor) => (0, microservices_1.EventPattern)(`${type}://${normalizePattern(event)}`, {
+        type,
+        event,
+    })(target, key, descriptor);
+}
+/**
+ * Create method decorator
+ * @param type type of listener
+ * @param pattern how to identify the message
+ */
+function messageDecorator(type, pattern) {
+    return (target, key, descriptor) => (0, microservices_1.MessagePattern)(`${type}://${normalizePattern(pattern)}`, {
+        type,
+        pattern,
+    })(target, key, descriptor);
+}
+function adjustLogger(logger) {
+    // this patch required to support NestJS logger that not use the standard "info"
+    // and use "log" instead
+    if (logger["log"] && !logger["info"]) {
+        logger["info"] = logger["log"].bind(logger);
+    }
+    // minimal logger interface required by @slack/bolt library
+    for (const method of ["debug", "info", "warn", "error"]) {
+        if (typeof logger[method] !== "function") {
+            throw new Error(`Logger must implement "${method}" method`);
+        }
+    }
+    return Object.assign(logger, {
+        setLevel(_) {
+            // don't allow library to set the level
+        },
+        setName(name) {
+            // search for all possible setName/setContext methods, use "noop" if none
+            (logger.setName ?? logger.setContext ?? ((i) => i))(name);
+        },
+        getLevel() {
+            // always return the lowest supported level (by library, not real logger)
+            // to avoid filtering log messages by library instead of real logger
+            return bolt_1.LogLevel.DEBUG;
+        },
+    });
+}