pumble-sdk v0.0.27

Pumble SDK

A javascript framework to quickly build Pumble Apps. Visit the documentation to explore the full guide on creating Pumble Apps

Setup

Create a new project in an empty directory

mkdir my-pumble-app
cd my-pumble-app
npm init -y

Install the packages

npm install pumble-sdk
npm install -D pumble-cli typescript

Create tsconfig.json file in the root directory with the content below:

{
    "compilerOptions": {
        "target": "es2016",
        "module": "commonjs",
        "rootDir": "./src",
        "outDir": "./dist",
        "esModuleInterop": true
    }
}

Create a manifest.json file with the content below:

{
    "name": "my-pumble-app",
    "displayName": "My Pumble App",
    "botTitle": "My Pumble App Bot",
    "bot": true,
    "scopes": {
        "botScopes": [
            "messages:read",
            "messages:write"
        ],
        "userScopes": [
            "messages:read"
        ]
    }
}

Create src/main.ts file with the content below

mkdir src
touch src/main.ts

import { App, JsonFileTokenStore, start } from "pumble-sdk";

const addon: App = {
  slashCommands: [
    {
      command: "/my_slash_command",
      handler: async (ctx) => {
        await ctx.ack();
        await ctx.say("Received slash command!");
      },
    },
  ],
  redirect: { enable: true },
  tokenStore: new JsonFileTokenStore("tokens.json"),
};

start(addon);

Folder structure

.
├── manifest.json
├── package.json
├── src
│   └── main.ts
└── tsconfig.json

Run the project. When prompted provide your credentials to log in.

npx pumble-cli

After everything is set up open Pumble and type /my_slash_command

Triggers

Pumble Apps can be triggered by App custom triggers or Pumble Events

App Triggers

Slash Commands

  slashCommands: [
	//.....
    {
      command: "/my_slash_command",
      handler: async (ctx) => {
        await ctx.ack();
        await ctx.say("Received slash command!");
      },
    },
	//.....
  ],

Global Shortcuts

    globalShortcuts: [
		//...
        {
            name: 'My App Global Shortcut',
            handler: async (ctx) => {
                await ctx.ack();
				await ctx.say("Received global shortcut")
            },
        },
		//...
    ],

Message Shortcuts

    messageShortcuts: [
        {
            name: 'My App message shortcut',
            handler: async (ctx) => {
                await ctx.ack();
				await ctx.say("Received message shortcut")
            },
        },
	]

Pumble Events

    events: [
        {
            name: 'APP_UNAUTHORIZED',
            handler: (ctx) => {
                console.log('User unauthorized app');
            },
        },
        {
            name: 'REACTION_ADDED',
            options: { match: ':robot_face:' },
            handler: async (ctx) => {
				await ctx.say('BLEEP BLOOP')
            },
        },
        {
            name: 'NEW_MESSAGE',
            options: { includeBotMessages: false, match: /^greet/ },
            handler: async (ctx) => {
                await ctx.say('hello');
            },
        },
	]

Triggers context

Each trigger callback has a context argument where you can find information information and helper methods to interact with Pumble.

  slashCommands: [
	//.....
    {
      command: "/my_slash_command",
      handler: async (ctx) => {
        await ctx.ack();
		const userId = ctx.payload.userId;
		const workspaceId = ctx.payload.userId.
        await ctx.say("Received slash command!");
		await ctx.getUserClient();
      },
    },
	//.....
  ],

The properties below are available on every context: | key | type | description | | :----------- | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | | payload | object | The payload of the trigger. It contains all the relevant information of the trigger, such as workspace where it as triggered, triggering user etc. | | getBotClient | () => Promise<ApiClient \| undefined> | A method to get an instance of Pumble ApiClient in order to make requests in Pumble on behalf of your app's bot in the workspace where trigger was initiated | | getBotUserId | () => Promise<string \| undefined> | A method to get your App's bot id in the workspace where the trigger was initiated | | getManifest | () => AddonManifest | A method to get the manifest of your App, in this manifest you can find all of your app's secrets and configurations | | getAuthUrl | () => string | A method to generate a URL that would open Pumble's OAuth2 screen with your client_id and scopes |

Every trigger also has its own methods in the context, For example messageShortcuts, NEW_MESSAGE, UPDATED_MESSAGE and REACTION_ADDED have fetchMessage() method For more information about triggers and their contexts click here. TBD

Responding to triggers

Slash commands, Global shortcuts, Message shortcuts, NEW_MESSAGE and REACTION_ADDED events have say() method in their context say() will send a message or ephemeral message as your App's bot

Responding with an ephemeral message

  slashCommands: [
	//.....
    {
      command: "/my_slash_command",
      handler: async (ctx) => {
        await ctx.ack();
        await ctx.say("Received slash command!");
      },
    },
	//.....
  ],

Responding with a normal message

  slashCommands: [
	//.....
    {
      command: "/my_slash_command",
      handler: async (ctx) => {
        await ctx.ack();
        await ctx.say("Received slash command!", 'in_channel');
      },
    },
	//.....
  ],

Working with the Pumble API

All Trigger contexts have access to two methods getUserClient() and getBotClient() In all App trigger contexts (commands and shortcuts) a user id is not required for getUserClient() since it will try to automatically try to use the authorization of the user that triggered the request. For events such as NEW_MESSAGE, REACTION_ADDED, UPDATED_MESSAGE the default user id if not provided in getUserClient(user_id) is the event author.

  slashCommands: [
	//.....
    {
      command: "/my_slash_command",
      handler: async (ctx) => {
        await ctx.ack();
		const userClient = await ctx.getUserClient();
		if (userClient) {
			await userClient.v1.messages.postMessageToChannel(ctx.payload.channelId, "Message from user")
		}
		const botClient = await ctx.getBotClient();
		if (botClient) {
			await botClient.v1.messages.postMessageToChannel(ctx.payload.channelId, "Message from bot")
		}
      },
    },
	//.....
  ],