@xpr/nestjs-slack 0.6.0 → 0.9.3

package/decorators.d.ts

@@ -1,5 +1,6 @@
-import { ActionConstraints, OptionsConstraints, ShortcutConstraints, ViewConstraints } from "@slack/bolt";
-import { type Pattern } from "./utils";
+import { ActionConstraints, OptionsConstraints, ShortcutConstraints, ViewConstraints } from '@slack/bolt';
+import { type Pattern } from './utils';
+export type { SlackActionMiddlewareArgs, SlackCommandMiddlewareArgs, SlackShortcutMiddlewareArgs, SlackEventMiddlewareArgs, SlackViewMiddlewareArgs, SlackOptionsMiddlewareArgs, AllMiddlewareArgs, } from '@slack/bolt/dist/types';
 export { Pattern };
 /**
  * @see https://tools.slack.dev/bolt-js/reference/
@@ -12,12 +13,15 @@ export declare const EventTypes: {
     View: string;
     Option: string;
 };
+/**
+ * Decorator for Slack controller
+ */
+export declare function SlackController(): ClassDecorator;
 /**
  * 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;
@@ -26,7 +30,6 @@ export type ShortCutId = Pattern | ShortcutConstraints;
  * @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;
 /**
@@ -34,7 +37,6 @@ export declare function SlackShortcut(shortcutId: ShortCutId): MethodDecorator;
  * @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;
@@ -42,7 +44,6 @@ 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;
@@ -50,7 +51,6 @@ 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;
@@ -58,7 +58,6 @@ 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;
 /**
@@ -67,6 +66,5 @@ export declare function SlackOption(optionId: OptionId): MethodDecorator;
  * @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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventTypes = void 0;
+exports.SlackController = SlackController;
 exports.SlackEvent = SlackEvent;
 exports.SlackShortcut = SlackShortcut;
 exports.SlackCommand = SlackCommand;
@@ -8,24 +9,30 @@ exports.SlackAction = SlackAction;
 exports.SlackView = SlackView;
 exports.SlackOption = SlackOption;
 exports.SlackMessage = SlackMessage;
+const common_1 = require("@nestjs/common");
 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",
+    Event: 'event',
+    Shortcut: 'shortcut',
+    Command: 'command',
+    Action: 'action',
+    View: 'view',
+    Option: 'option',
 };
+/**
+ * Decorator for Slack controller
+ */
+function SlackController() {
+    return (target) => (0, common_1.Controller)()(target);
+}
 /**
  * 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)
@@ -36,7 +43,6 @@ function SlackEvent(event) {
  * @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);
@@ -46,7 +52,6 @@ function SlackShortcut(shortcutId) {
  * @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.
@@ -56,7 +61,6 @@ function SlackCommand(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);
@@ -65,7 +69,6 @@ function SlackAction(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);
@@ -74,7 +77,6 @@ function SlackView(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);
@@ -85,8 +87,7 @@ function SlackOption(optionId) {
  * @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);
+function SlackMessage(pattern = '*') {
+    return (0, utils_1.messageDecorator)('message', pattern);
 }

package/package.json

@@ -1,35 +1 @@
-{
-  "name": "@xpr/nestjs-slack",
-  "version": "0.6.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"
-  }
-}
+{"name":"@xpr/nestjs-slack","version":"0.9.3","description":"NestJS server implementation of the Slack Assistant","main":"index.js","scripts":{"build":"tsc -p tsconfig-lib.json","release":"npm run build && npm publish --access public"},"author":"Ziv Perry","license":"MIT","keywords":["slack","nestjs","assistant","ai"],"engines":{"node":">=20.0.0","npm":">=10.0.0"},"repository":{"type":"git","url":"git+https://github.com/ziv/nestjs-slack.git","directory":"packages/nestjs-slack-assistant"},"bugs":{"url":"https://github.com/ziv/nestjs-slack/issues"},"homepage":"https://github.com/ziv/nestjs-slack#readme","devDependencies":{"@tsconfig/node20":"^20.1.4","@types/node":"^22.10.6"},"peerDependencies":{"@nestjs/common":"^11.0.1","@nestjs/microservices":">=11.0.13","@slack/bolt":">=4.2.1","reflect-metadata":">=0.2.2"},"files":["*.js","*.d.ts","readme.md"]}

package/readme.md

@@ -1 +1,66 @@
 # @xpr/nestjs-slack
+
+A NestJS microservice transport and decorators for [Slack Bolt Apps](https://github.com/slackapi/bolt-js).
+
+### Usage
+
+Make sure to install peer dependencies if not already installed (`@slack/bolt`).
+
+```shell
+npm i @xpr/nestjs-slack
+```
+
+### Initialize Slack/Bolt application with the `Slack` transport:
+
+```ts
+const app = await NestFactory.createMicroservice(MyModule, {
+  strategy: new Slack({
+    slack: {
+      token: env.SLACK_BOT_TOKEN,
+      appToken: env.SLACK_APP_TOKEN,
+    },
+  }),
+});
+await app.listen();
+```
+
+📃 https://tools.slack.dev/bolt-js/getting-started
+
+### Slack Application Controller
+
+Example of a Slack controller with listener for action and a command.
+
+```ts
+import {
+  SlackAction,
+  SlackCommand,
+  SlackController,
+} from '@xpr/nestjs-slack';
+
+@SlackController()
+export class MyController {
+
+  @SlackAction('button-action')
+  async onAction({ ack, respond, payload }: SlackActionMiddlewareArgs) {
+    await ack();
+    await respond(`Button clicked! with payload ${JSON.stringify(payload)}`);
+  }
+
+  @SlackCommand('/ping')
+  async onPing({ ack, respond }: SlackCommandMiddlewareArgs) {
+    await ack();
+    await respond({
+      text: 'pong!',
+      response_type: 'in_channel',
+    });
+  }
+}
+```
+
+📃 https://tools.slack.dev/bolt-js/concepts/event-listening
+
+📃 https://tools.slack.dev/bolt-js/concepts/commands
+
+## Decorators
+
+See [source file](./decorators.ts).

package/slack.js

@@ -34,20 +34,27 @@ class Slack extends microservices_1.Server {
      */
     register(handler) {
         const { type, event } = handler.extras;
-        this.logger.log(`Registering handler of type [${type}] with (${event})`);
         switch (type) {
             case decorators_1.EventTypes.Shortcut:
-                return this.app().shortcut(event, handler);
+                this.app().shortcut(event, handler);
+                break;
             case decorators_1.EventTypes.Action:
-                return this.app().action(event, handler);
+                this.app().action(event, handler);
+                break;
             case decorators_1.EventTypes.Event:
-                return this.app().event(event, // todo improve by providing types
-                handler);
+                // todo improve by providing types for events names
+                this.app().event(event, handler);
+                break;
             case decorators_1.EventTypes.Command:
-                return this.app().command(event, handler);
+                this.app().command(event, handler);
+                break;
             case decorators_1.EventTypes.Option:
-                return this.app().options(event, handler);
+                this.app().options(event, handler);
+                break;
+            default:
+                throw new Error(`Unknown event type ${type}`);
         }
+        this.logger.log(`Handler of type [${type}] registered with id(${event})`);
     }
     /**
      * Get/Create Bolt app instance

package/utils.d.ts

@@ -1,4 +1,4 @@
-import { type Logger } from "@slack/bolt";
+import { type Logger } from '@slack/bolt';
 export type Pattern = string | RegExp;
 /**
  * Create method decorator

package/utils.js

@@ -6,7 +6,7 @@ exports.adjustLogger = adjustLogger;
 const microservices_1 = require("@nestjs/microservices");
 const bolt_1 = require("@slack/bolt");
 const normalizePattern = (pattern) => {
-    if (typeof pattern === "string") {
+    if (typeof pattern === 'string') {
         return pattern;
     }
     if (pattern instanceof RegExp) {
@@ -39,27 +39,33 @@ function messageDecorator(type, pattern) {
 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);
+    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") {
+    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(_) {
+    // add compatibility with @slack/bolt library
+    if (!logger['setLevel']) {
+        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() {
+        };
+    }
+    if (!logger['getLevel']) {
+        logger.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;
-        },
-    });
+        };
+    }
+    if (!logger['setName']) {
+        logger.setName = (name) => {
+            // search for all possible setName/setContext methods, use "noop" if none
+            (logger.setName ?? logger.setContext ?? ((i) => i))(name);
+        };
+    }
+    return logger;
 }