### Setting up a Pumble App with Setup Function

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/getting-started.md

Utilize the `setup` function to instantiate a Pumble addon within your Node.js project. Provide your app's manifest details, including secrets obtained from Pumble, and configure server port and OAuth2 options. The addon can then be started using `addon.start()`.

```typescript
const addon = setup(
    {
        id: "<<Your app's ID>>",
        clientSecret: "<<You app's client secret>>",
        appKey: "<<Your app's app key>>",
        signingSecret: "<<Your app's signing secret>>",
        name: 'my-first-app',
        displayName: 'My first app',
        bot: true,
        botTitle: 'My first app',
        scopes: {
            botScopes: ['messages:read', 'messages:write'],
            userScopes: ['messages:read', 'messages:write'],
        },
        shortcuts: [
            // ...
        ],
        slashCommands: [
            // ...
        ],
        redirectUrls: ["..."],
        eventSubscriptions: {
            url: "...",
            events: ['APP_UNINSTALLED'],
        },
        dynamicMenus: [],
        // ...
    }, 
    {
        serverPort: 9898,
        oauth2Config: {
            redirect: {
                enable: true,
                onSuccess: async (result, req, res) => { 
                    res.send("Success!"); 
                },
                onError: async (err, req, res) => { 
                    res.send("Something went wrong!"); 
                },
            },
        }
    }
);

addon.start();
```

--------------------------------

### View Action Handler Setup

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Example of how to define onSubmit and onClose handlers for view actions within your App object.

```APIDOC
## View Action

To create view action handlers in your `main.ts` App object, insert the property `viewAction`, with `onSubmit` and `onClose` handlers:

```typescript

// main.ts
const app: App = {
    viewAction: {
        onSubmit: {
            modal_callback_id: async (ctx) => {
                await ctx.ack();
                console.log(`Modal submitted with state ${JSON.stringify(ctx.payload.view.state)}.`);
            }
        },
        onClose: {
            modal_callback_id: async (ctx) => {
                await cts.ack();
                console.log('Modal closed.');
            }
        }
    }
}
```

>[!NOTE]
>If you created an App object using `setup` function, insert the `viewAction` property within the `AddonManifest` object,
>with the view action handler, and make sure to specify the full `url` for block interactions.

### View Action context

| name              | type                                                                                                                                                      | description                                                                                                                                                                                                   |
|:------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| payload           | [ViewActionPayload](#view-action-payload)                                                                                                                 | The payload for the block interacion.                                                                                                                                                                         |
| ack               | () => Promise<Void>                                                                                                                                    | Callback to acknowledge the trigger. This should be invoked within 3 seconds upon receiving the request. It's recommended for this to be the first call in the trigger handler.                               |
| nack              | (message?: String) => Promise<Void>                                                                                                                    | Callback to reject the trigger. If provided with an argument the message will be sent to the user as an ephemeral message.                                                                                    |
| getBotClient      | () => Promise<ApiClient | undefined>                                                                                                                                                 | Returns the bot ApiClient for the workspace where the trigger was invoked. If you have set `{bot: false}` in the [manifest](/manifest#manifest-payload), this will return undefined.                          |
| getUserClient     | (userId?: String) => Promise<ApiClient | undefined>                                                                                                                                                 | Returns the user client given a user ID. If userId is not fed in this method it will try to find a the ApiClient of the triggering user. If the user has not authorized your app, this will return undefined. |
| getManifest       | () => [Manifest](/manifest#manifest-payload)                                                                                                             | Returns the manifest of your app. This can be used if you need to access some manifest configuration or secret                                                                                                |
| getBotUserId      | () => Promise<String | undefined>                                                                                                                                                 | Returns the bot user ID for the workspace where the trigger was invoked. If you set `{bot: false}` in the [manifest](/manifest#manifest-payload), this will return undefined.                                 |
| getAuthUrl        | ()=>> String                                                                                                                                              | Generate an auth URL that when opened it will show the Pumble Consent screen to authorize your app.                                                                                                           |
```

--------------------------------

### Navigate and Start Pumble App

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/README.md

Changes the directory to the newly created app and starts the development server using npm.

```sh
cd my_app
npm run dev
```

--------------------------------

### Date Range Picker Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

This example shows how to configure a basic date range picker with an initial date range and an action identifier.

```json
{
    "type": "date_range_picker",
    "onAction": "on_date_range_picked",
    "initial_date_range": {
        "start": "2026-01-01",
        "end": "2026-01-20"
    }
}
```

--------------------------------

### Pumble CLI Info Output Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Example output format for the `pumble-cli info` command, displaying workspace and user details.

```text
╔════════════════╤══════════════════════════╗
║ Workspace Id   │ 651122b0456aa466bf81c6b2 ║
╟────────────────┼──────────────────────────╢
║ Workspace Name │ my_workspace             ║
╟────────────────┼──────────────────────────╢
║ User Id        │ 651122b0456aa466bf81c6b3 ║
╟────────────────┼──────────────────────────╢
║ User Name      │ Your Name                ║
╟────────────────┼──────────────────────────╢
║ User Email     │ your.email@email.com     ║
╚════════════════╧══════════════════════════╝
```

--------------------------------

### Home View JSON Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/modals-views-reference.md

A complete JSON example of a Pumble home view. It includes a rich text element for content and an actions block with a button.

```json
{
    "title": {
        "type": "plain_text",
        "text": "My Home View"
    },
    "blocks": [
        {
            "type": "rich_text",
            "elements": [
                {
                    "type": "rich_text_section",
                    "elements": [
                        {
                            "type": "text",
                            "text": "Hello there "
                        },
                        {
                            "type": "emoji",
                            "name": "wave",
                            "skin_tone": 1
                        }
                    ]
                }
            ]
        },
        {
            "type": "actions",
            "elements": [
                {
                    "type": "button",
                    "onAction": "on_button_clicked",
                    "value": "test metadata",
                    "text": {
                        "type": "plain_text",
                        "text": "Click here!"
                    },
                    "style": "secondary"
                }
            ]
        }
    ]
}

```

--------------------------------

### Static Select Menu with Options

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Example of a static select menu with individual options. Use this when you have a flat list of choices.

```json
{
    "type": "static_select_menu",
    "placeholder": {
        "type": "plain_text",
        "text": "Choose an option"
    },
    "onAction": "on_static_select_menu",
    "options": [
        {
            "text": {
                "type": "plain_text", 
                "text": "Option 1"
            }, 
            "value": "1"
        },
        {
            "text": {
                "type": "plain_text",
                "text": "Option 2"
            },
            "value": "2"
        }
    ],
    "initial_option": {
        "text": {
            "type": "plain_text",
            "text": "Option 1"
        },
        "value": "1"
    }
}
```

--------------------------------

### Install Pumble CLI

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/README.md

Installs the Pumble CLI globally using npm. This tool is used for generating and running Pumble apps.

```sh
npm i -g pumble-cli
```

--------------------------------

### Initialize Pumble App Project

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/pumble-sdk/README.md

Commands to create a new Pumble app project directory, initialize npm, and install necessary packages.

```sh
mkdir my-pumble-app
cd my-pumble-app
npm init -y
npm install pumble-sdk
npm install -D pumble-cli typescript
```

--------------------------------

### Pumble CLI package.json Script

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Example of how to configure a `dev` script in `package.json` to run the Pumble CLI.

```json
// package.json
{
	"scripts": {
		"dev": "pumble-cli"
	}
}
```

--------------------------------

### Define a Global Shortcut

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/basic-concepts.md

Set up a global shortcut that can be invoked from anywhere in Pumble. This example shows how to acknowledge the shortcut and send a message back to the user.

```typescript
globalShortcuts: [
	{
		name: 'My Global Shortcut',
		handler: async (ctx) => {
			await ctx.ack();
			await ctx.say(`Received global shortcut by <<@${ctx.payload.userId}>>`);
		},
	},
]
```

--------------------------------

### Run Pumble CLI in Project Root

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Start your Pumble app by running the `pumble-cli` command in your project's root directory.

```sh
pumble-cli
```

--------------------------------

### Text Block with Bold Style

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

An example of a text block with bold styling applied. This demonstrates how to use the 'style' property to format text.

```json
{
    "type": "text",
    "text": "Hello World!",
    "style": {
        "bold": "true"
    }
}
```

--------------------------------

### Date Picker Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Use this JSON to render a date picker element. It includes a placeholder, an action identifier, an initial date, and a loading timeout.

```json
{
    "type": "date_picker",
    "placeholder": {
        "type": "plain_text",
        "text": "Enter a date"
    },
    "onAction": "on_date_picked",
    "initial_date": "2026-01-01",
    "loadingTimeout": 5
}
```

--------------------------------

### Create Channel and Post Message using Bot and User Clients

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/basic-concepts.md

Example of using both `botClient` to create a channel and `userClient` to post a message within a slash command handler. Ensure the appropriate client is used based on the required action.

```typescript
const app: App = {
	//...
	slashCommands: [
		{
            command: '/my_slash_command',
            handler: async (ctx) => {
                await ctx.ack();
                const botClient = await ctx.getBotClient();
                if (!botClient) return;
                const channel = await botClient.v1.channels.createChannel({
                    name: 'ChannelFromBot',
                    type: 'PUBLIC',
                });
                const userClient = await ctx.getUserClient();
                if (!userClient) return;
                await userClient.v1.messages
					.postMessageToChannel(channel.channel.id, 'First channel message');
            },
        }
	]
};
```

--------------------------------

### Input Block with Static Select Menu

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

This example shows how to create an Input Block that wraps a Static Select Menu. It is used in modals to capture user selections and can be part of the modal's state.

```json
{
    "type": "input",
    "blockId": "input_1",
    "label": {
        "text": "Input field",
        "type": "plain_text"
    },
    "element": {
        "type": "static_select_menu",
        "placeholder": {
            "text": "Select an option", 
            "type": "plain_text"
        },
        "onAction": "on_static_select_menu",
        "options": [
            {
                "text": {
                    "type": "plain_text", 
                    "text": "Option 1"
                }, 
                "value": "1"
            },
            {
                "text": {
                    "type": "plain_text", 
                    "text": "Option 2"
                }, 
                "value": "2"
            }
        ]
    },
    "dispatchAction": true
}
```

--------------------------------

### Create Pumble App with npx

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/README.md

Alternative method to create a Pumble app without globally installing the Pumble CLI, using npx.

```sh
npx pumble-cli create
```

--------------------------------

### Run Pumble CLI with npx

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Execute Pumble CLI commands without global installation using npx.

```sh
npx pumble-cli <command>
```

--------------------------------

### Get Pumble CLI Login Info

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Display information about the currently logged-in workspace and user.

```sh
pumble-cli info
```

--------------------------------

### Start Pumble App Development

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Run your Pumble app in development mode. Changes to your project will automatically update the app.

```sh
npm run dev
```

--------------------------------

### Link Block - Hyperlink Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Create a clickable hyperlink by providing both 'url' and 'text'. The 'style' property can be used to further customize the appearance, such as making it bold or code-formatted.

```json
{
    "type": "link",
    "url": "https://github.com/CAKE-com/pumble-node-sdk",
    "text": "Pumble Node SDK",
    "style": {
        "bold": true,
        "code": true
    }
}
```

--------------------------------

### Link Block - Email Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Format an email address as a clickable link by prefixing the 'url' with 'mailto:'. This allows users to initiate an email to the specified address.

```json
{
    "type": "link",
    "url": "mailto:support@pumble.com"
}
```

--------------------------------

### Plain Text Input Block Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

This JSON object demonstrates the structure of a Plain Text Input block. It includes placeholder text, an action identifier, multiline support, maximum length, and interaction triggers.

```json
{
    "type": "plain_text_input",
    "placeholder": {
        "type": "plain_text",
        "text": "Enter something here"
    },
    "onAction": "on_plain_text_input",
    "line_mode": "multiline",
    "max_length": 15,
    "interaction_triggers": ["on_input"]
}
```

--------------------------------

### App Specific Triggers Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Illustrates the structure of app-specific triggers within an event handler context, including slash commands.

```typescript
slashCommands: [
    {
        command: '/my_slash_command',
        handler: async (ctx) => {
            await ctx.ack();
            const payload = ctx.payload;
        },
    },
]
```

--------------------------------

### Link Block - Raw Link Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Use this to display a link as plain text without making it a clickable hyperlink. Ensure the 'type' is set to 'link' and provide the 'url'.

```json
{
    "type": "link",
    "url": "https://github.com/CAKE-com/pumble-node-sdk",
    "style": {
        "italic": true
    }
}
```

--------------------------------

### Button Element Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

This JSON object demonstrates the structure of a button element within an Action Block. It includes text, an action identifier, a value, a confirmation dialog, and a loading timeout.

```json
{
    "type": "button",
    "text": {
        "type": "plain_text",
        "text": "Click here!"
    },
    "onAction": "on_button_clicked",
    "value": "1",
    "confirm": {
        "title": {
            "type": "plain_text",
            "text": "Confirmation needed"
        },
        "text": {
            "type": "plain_text",
            "text": "Are you sure you want to perform this action?"
        },
        "confirm": {
            "type": "plain_text",
            "text": "Yes"
        },
        "deny": {
            "type": "plain_text",
            "text": "No"
        }
    },
    "loadingTimeout": 5
}
```

--------------------------------

### Manual Request Signature Verification Logic

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/advanced-concepts.md

Understand the manual process of verifying request signatures using the `signingSecret`. This example demonstrates how to extract timestamp and signature headers, construct the signing payload, and compare it with the received signature.

```typescript
function verifySignature(signingSecret: string) {
    const TIMESTAMP_HEADER = 'x-pumble-request-timestamp';
    const SIGNATURE_HEADER = 'x-pumble-request-signature';
    return (request: Request, res: Response, next: NextFunction) => {
        const timestamp = request.headers[TIMESTAMP_HEADER];
        const signature = request.headers[SIGNATURE_HEADER];
        if (!timestamp || !signature) {
            res.status(403).send('Invalid signature!');
            return;
        }
        const rawBody = request.rawBody; 
        // The string to be signed is timestamp:rawBody
        const signingPayload = `${timestamp}:${rawBody}`;
        const hmac = crypto.createHmac('sha256', signingSecret);
        const testSignature = hmac
            .update(signingPayload)
            .digest()
            .toString('hex');
        if (testSignature !== signature) {
            res.status(403).send('Invalid signature!');
            return;
        }
        next();
    };
}
```

--------------------------------

### Code Block Section Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Shows a basic Code Block Section with plain text content. This section is used for displaying code without any additional formatting.

```json
{
    "type": "rich_text_preformatted",
    "elements": [
        {
            "type": "text",
            "text": "Code Block content, no formatting"
        }
    ]
}
```

--------------------------------

### Basic Rich Text Block

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

A simple example demonstrating the structure of a basic rich text block. This block contains a single rich text section with plain text.

```json
[
    {
        "type": "rich_text",
        "elements": [
            {
                "type": "rich_text_section",
                "elements": [
                    {
                        "type": "text",
                        "text": "Simple text"
                    }
                ]
            }
        ]
    }
]
```

--------------------------------

### Date Range Picker State Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/modals-views-reference.md

Illustrates the state structure for a date range picker input within a modal. The 'values' field contains an array of selected date strings.

```json
{
    "type": "date_range_picker",
    "onAction": "on_date_range_picked"
}
}
}
            }
        }
    ]
}

```

--------------------------------

### Prepare App for Release

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/examples/interactivity/README.md

Run this command to prepare your Pumble App for publishing. It performs necessary checks and configurations before release.

```sh
pumble-cli pre-publish
```

--------------------------------

### Broadcast Mention Block Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Represents a broadcast mention like '@here' or '@channel'. Requires a range value.

```json
{
    "type": "broadcast",
    "range": "here"
}
```

--------------------------------

### Channel Mention Block Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Represents a mention of a specific channel. Requires the channel's ID.

```json
{
    "type": "channel",
    "user_id": "6965ed9a6790becb7e38675c"
}
```

--------------------------------

### User Mention Block Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Represents a mention of a specific user. Requires the user's ID.

```json
{
    "type": "user",
    "user_id": "6965ed9a6790becb7e38675b"
}
```

--------------------------------

### Get App Manifest and Secrets

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/manifest.md

Fetch the complete app manifest, including its secrets, for a specific app.

```APIDOC
## GET /workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps/mine/{app_id}

### Description
Retrieves the full manifest of a specific app, including its associated secrets.

### Method
GET

### Endpoint
`/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps/mine/{app_id}`

### Parameters
#### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace.
- **workspace_user_id** (string) - Required - The ID of the workspace user.
- **app_id** (string) - Required - The ID of the app to retrieve the manifest for.
```

--------------------------------

### Display Pumble CLI Help

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

View available commands and their usage for the Pumble CLI.

```sh
pumble-cli --help
```

```sh
pumble-cli-command --help
```

--------------------------------

### getBotClient

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Get the bot ApiClient for the workspace where the trigger was invoked. If you have set `{bot: false}` in the manifest, this will return undefined.

```APIDOC
## getBotClient

### Description
Retrieves the bot's ApiClient for the current workspace. Returns undefined if the bot integration is disabled in the manifest.

### Method
() => Promise<ApiClient | undefined>

### Returns
A Promise that resolves to the bot's ApiClient or undefined.
```

--------------------------------

### Pumble SDK App Initialization

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/pumble-sdk/README.md

Initializes a Pumble app with a slash command handler and a JSON file token store. Ensure the token store path is correctly configured.

```typescript
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);
```

--------------------------------

### Create Main TypeScript File

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/pumble-sdk/README.md

Commands to create the source directory and the main TypeScript file for the Pumble app.

```sh
mkdir src
touch src/main.ts
```

--------------------------------

### User Group Mention Block Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Represents a mention of a user group. Requires the user group's ID.

```json
{
    "type": "usergroup",
    "usergroup_id": "6965ed9a6790becb7e38675e"
}
```

--------------------------------

### getChannelDetails

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Get channel information for the channel where the interaction was triggered, given the `channels:read` scope is granted for the user or bot.

```APIDOC
## getChannelDetails

### Description
Retrieves detailed information about the channel where the interaction occurred. Requires the `channels:read` scope for the user or bot.

### Method
() => Promise<ChannelInfo>

### Returns
A Promise that resolves to the ChannelInfo object.
```

--------------------------------

### Publish Home View After Authorization

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/modals-views.md

This snippet shows how to publish the Home view after a user authorizes the app. It uses a setTimeout to delay the publishing by 3 seconds. Ensure you have the addonManifest and botClient initialized.

```typescript
redirect: {
    enable: true, path: "/redirect",
    onSuccess: async (result, req, res) => {
        if (result.botToken && result.botId && result.userId) {
            setTimeout(async () => {
                try {
                    const addonManifest = await addonManifestPromise;
                    const botClient = await addonManifest.getBotClient(result.workspaceId);
                    // publish addon home view when user authorizes
                    botClient?.v1.app.publishHomeView(result.userId, {callbackId: '', title: {...}, ...});
                } catch (err) {
                    console.error(err);
                }
            }, 3000);
        }
    }
}
```

--------------------------------

### getBotUserId

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Get the bot user ID for the workspace where the trigger was invoked. If you have set `{bot: false}` in the manifest, this will return undefined.

```APIDOC
## getBotUserId

### Description
Retrieves the bot user ID for the current workspace. Returns undefined if the bot integration is disabled in the manifest.

### Method
() => Promise<String | undefined>

### Returns
A Promise that resolves to the bot user ID or undefined.
```

--------------------------------

### getBotUserId

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Get the bot user ID for the workspace where the trigger was invoked. If you have set `{bot: false}` in the manifest, this will return undefined.

```APIDOC
## getBotUserId

### Description
Fetches the unique identifier for the bot user within the current workspace. This is only available if the bot is enabled in the application's manifest.

### Method
N/A (SDK Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const botUserId = await pumble.getBotUserId();
```

### Response
#### Success Response
- **String** - The bot user ID.
- **undefined** - If the bot is disabled in the manifest (`{bot: false}`).

#### Response Example
```json
{
  "//": "Example of a bot user ID"
}
```
```

--------------------------------

### Run Pumble CLI pre-publish with hostname

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/production-deployment.md

This command skips the hostname prompt by providing it directly. Ensure the URL is valid.

```sh
npx pumble-cli pre-publish --host https://yourhost.com
```

--------------------------------

### Global Shortcut Context Methods

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

The global shortcut context provides several utility functions for handling triggers, including acknowledging or rejecting events, interacting with the bot and user clients, and managing modal views.

```APIDOC
## Global Shortcut Context

### Description

The global shortcut context provides access to various utilities for handling trigger events within the Pumble Node.js SDK.

### Methods

- **payload** ([GlobalShortcutPayload](#global-shortcut-payload)) - The payload containing information about the global shortcut trigger.
- **say** ([SayFunction](#say-function)) - A function to quickly reply to the trigger.
- **ack** (() => Promise<void>) - A callback to acknowledge the trigger. Should be invoked within 3 seconds.
- **nack** ((message?: String) => Promise<void>) - A callback to reject the trigger. Optionally sends an ephemeral message.
- **getBotClient** (() => Promise<ApiClient | undefined>) - Retrieves the bot's ApiClient for the workspace.
- **getUserClient** ((userId?: String) => Promise<ApiClient | undefined>) - Retrieves the user's ApiClient for the workspace, or the triggering user's if no userId is provided.
- **getManifest** (() => Manifest) - Returns the manifest of your app.
- **getBotUserId** (() => Promise<String | undefined>) - Retrieves the bot user ID for the workspace.
- **getAuthUrl** (() => String) - Generates an authorization URL for the Pumble Consent screen.
- **spawnModalView** (([View<"MODAL">](#modals-views-reference#modal)) | [StorageIntegrationModalCredentials](#modals-views-reference#storage-integration)) => Promise<void> - Triggers the creation of a modal (regular or storage integration).
```

--------------------------------

### Emoji Block Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Demonstrates how to use the emoji block type to display a specific emoji. This is useful for adding visual elements to messages.

```json
{
    "type": "emoji",
    "name": "rocket"
}
```

--------------------------------

### App Manifest URL

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/manifest.md

Your app's manifest will be served on this URL. Ensure {APP_HOST_URL} is correctly configured.

```http
https://{APP_HOST_URL}/manifest
```

--------------------------------

### Create a New Pumble App

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/README.md

Creates a new Pumble app project using the Pumble CLI. Prompts for app name and description.

```sh
pumble-cli create
```

--------------------------------

### Divider Block JSON Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

This JSON object represents a divider block. Use it to visually separate content in messages, modals, or home views.

```json
{
    "type": "divider"
}
```

--------------------------------

### Slash Command Context Methods

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Provides a reference for the methods available within the slash command context, allowing developers to acknowledge or reject triggers, interact with the bot or user clients, retrieve manifest information, and more.

```APIDOC
## Slash Command Context Reference

### Description
This object provides the context in which a slash command is executed, offering various utilities to interact with the Pumble platform.

### Methods

- **payload** (SlashCommandPayload): The payload containing details of the slash command invocation.
- **say** (SayFunction): A function to quickly reply to the trigger. See [SayFunction](#say-function) for more details.
- **ack** (): Acknowledges the trigger. This should be called within 3 seconds of receiving the request and is recommended as the first action.
- **nack** (message?: String): Rejects the trigger. An optional message can be provided to be sent to the user as an ephemeral message.
- **getBotClient** (): Returns a Promise resolving to the bot's ApiClient for the workspace, or undefined if `{bot: false}` is set in the manifest.
- **getUserClient** (userId?: String): Returns a Promise resolving to the ApiClient for a given user ID, or the triggering user's client if no ID is provided. Returns undefined if the user has not authorized the app.
- **getManifest** (): Returns the app's manifest object, useful for accessing configuration or secrets.
- **getBotUserId** (): Returns a Promise resolving to the bot user ID for the workspace, or undefined if `{bot: false}` is set in the manifest.
- **getAuthUrl** (): Generates an authorization URL for the Pumble Consent screen.
- **getChannelDetails** (): Returns a Promise resolving to the channel information for the command's invocation channel, requires the `channels:read` scope.
- **spawnModalView** (View<"MODAL"> | StorageIntegrationModalCredentials): Triggers the creation of a modal, either a regular modal or a storage integration modal.
```

--------------------------------

### File Methods

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/api-client.md

Methods for fetching files.

```APIDOC
## fetchFile

### Description
Fetch a file by URL.

### Method
client.v1.files.fetchFile

### Scopes
`messages:read`
```

--------------------------------

### Working with the Pumble API

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/pumble-sdk/README.md

How to use `getUserClient` and `getBotClient` to interact with the Pumble API from triggers.

```APIDOC
## Working with the Pumble API

All trigger contexts provide access to `getUserClient()` and `getBotClient()` methods for API interactions.

### User Client

In App trigger contexts (commands and shortcuts), `getUserClient()` can be called without a `user_id` as it attempts to use the authorization of the user who triggered the request.

For events like `NEW_MESSAGE`, `REACTION_ADDED`, and `UPDATED_MESSAGE`, if `user_id` is not provided to `getUserClient(user_id)`, it defaults to the event author's ID.

### Bot Client

`getBotClient()` provides an API client instance to make requests on behalf of your app's bot.

### Example Usage

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

--------------------------------

### POST /workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/manifest.md

Create a new app with a manifest by sending a POST request to this Pumble API endpoint.

```APIDOC
## POST /workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps

### Description

This endpoint allows you to manually create an app with a manifest.

### Method

POST

### Endpoint

`https://api-ga.pumble.com/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps`

### Parameters

#### Path Parameters

- **workspace_id** (string) - Required - The ID of the workspace.
- **workspace_user_id** (string) - Required - The ID of the workspace user.

#### Request Body

- **name** (string) - Required - The internal name of the app.
- **displayName** (string) - Required - The display name of the app.
- **bot** (boolean) - Optional - Whether the app is a bot.
- **botTitle** (string) - Optional - The title for the bot.
- **socketMode** (boolean) - Optional - Whether to use socket mode.
- **scopes** (object) - Optional - Defines the scopes for the bot and user.
  - **botScopes** (array of strings) - Optional - Scopes for the bot.
  - **userScopes** (array of strings) - Optional - Scopes for the user.
- **shortcuts** (array of objects) - Optional - Configuration for app shortcuts.
  - **shortcutType** (string) - Required - Type of shortcut (e.g., ON_MESSAGE, GLOBAL).
  - **url** (string) - Required - The URL to handle the shortcut.
  - **name** (string) - Required - The internal name of the shortcut.
  - **displayName** (string) - Required - The display name of the shortcut.
  - **description** (string) - Optional - Description of the shortcut.
- **slashCommands** (array of objects) - Optional - Configuration for slash commands.
  - **command** (string) - Required - The slash command string.
  - **url** (string) - Required - The URL to handle the slash command.
  - **description** (string) - Optional - Description of the slash command.
  - **usageHint** (string) - Optional - Hint on how to use the slash command.
- **eventSubscriptions** (object) - Optional - Configuration for event subscriptions.
  - **url** (string) - Required - The URL to receive events.
  - **events** (array of strings) - Required - List of events to subscribe to.
- **blockInteraction** (object) - Optional - Configuration for block interactions.
  - **url** (string) - Required - The URL to handle block interactions.
- **viewAction** (object) - Optional - Configuration for view actions.
  - **url** (string) - Required - The URL to handle view actions.
- **dynamicMenus** (array of objects) - Optional - Configuration for dynamic menus.
  - **url** (string) - Required - The URL to fetch dynamic menu items.
  - **onAction** (string) - Required - The action to perform when an item is selected.
- **defaultHomeView** (object) - Optional - Configuration for the default home view.
  - **enabled** (boolean) - Required - Whether the home view is enabled.
  - **blocks** (array of objects) - Required - The blocks that make up the home view.
- **redirectUrls** (array of strings) - Optional - URLs to redirect to after authorization.
- **helpUrl** (string) - Optional - URL for help documentation.
- **listingUrl** (string) - Optional - URL for installing the app on Pumble.
- **welcomeMessage** (string) - Optional - The welcome message for the app.
- **offlineMessage** (string) - Optional - The message to display when the app is offline.

### Request Example

```json
{
    "name": "my_app", 
    "displayName": "My App",
    "bot": true,
    "botTitle": "My App Bot Description",
    "socketMode": false,
    "scopes": {
        "botScopes": [
            "messages:read",
            "messages:write"
        ],
        "userScopes": [
            "messages:read",
            "messages:write"
        ]
    },
    "shortcuts": [
        {
            "shortcutType": "ON_MESSAGE",
            "url": "https://myapp.com/onmessage",
            "name": "message_shortcut",
            "displayName": "Message Shortcut",
            "description": "Message Shortcut Description"
        },
        {
            "shortcutType": "GLOBAL",
            "url": "https://myapp.com/global",
            "name": "global_shortcut",
            "displayName": "Global Shortcut",
            "description": "Global Shortcut Description"
        }
    ],
    "slashCommands": [
        {
            "command": "/my_slash_command",
            "url": "https://myapp.com/slash",
            "description": "Google Calendar commands",
            "usageHint": "/my_slash_command [first][second]"
        }
    ],
    "eventSubscriptions": {
        "url": "https://myapp.com/events",
        "events": [
            "APP_UNAUTHORIZED",
            "APP_UNINSTALLED",
            "NEW_MESSAGE"
        ]
    },
    "blockInteraction": {
        "url": "https://myapp.com/block_interaction"
    },
    "viewAction": {
        "url": "https://myapp.com/view_action"
    },
    "dynamicMenus": [
        {
            "url": "https://myapp.com/dynamic_menu",
            "onAction": "onDynamicItemSelect"
        }
    ],
    
    "defaultHomeView": {
        "enabled": true,
        "blocks":[
            {
                "type": "rich_text",
                "elements":[
                    {
                        "type": "rich_text_section",
                        "elements":[
                            {
                                "type": "text",
                                "text": "Welcome to My App!"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "redirectUrls": [
        "https://myapp.com/redirect"
    ],
    "helpUrl": "https://myapp.com/help",
    "listingUrl": "https://myapp.com/install-on-pumble",
    "welcomeMessage": "Hello :wave:",
    "offlineMessage": "We are experiencing some issues at the moment. Please try again later"
}
```

### Response

#### Success Response (200)

- **id** (string) - Your app's id. This will be used as the clientId in OAuth2 request.
- **clientSecret** (string) - Your app's clientSecret. This will be used to generate access tokens.
- **appKey** (string) - Your app's secret key. This should be sent on every Pumble request along with the access token.
- **signingSecret** (string) - Your app's signing key. Pumble will sign every request that will be sent to your endpoints with this key.

#### Response Example

```json
{
	//...your manifest
	"id": "...",
	"clientSecret": "...",
	"appKey": "...",
	"signingSecret": "..."
}
```

:::warning
Make sure not to share app secrets anywhere.
:::
```

--------------------------------

### Emoji Block within Rich Text Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Shows how to embed an emoji within a rich text block. This allows for combining text and emojis seamlessly in messages.

```json
{
    "type": "rich_text",
    "elements": [
        {
            "type": "rich_text_section",
            "elements": [
                {
                    "type": "emoji",
                    "name": "beers"
                }
            ]
        }
    ]
}
```

--------------------------------

### Quote Section Example

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/blocks.md

Demonstrates a Quote Section with bold and italic text, a broadcast mention, and an emoji. This section is used to display quoted content with rich text formatting.

```json
{
    "type": "rich_text_quote",
    "elements": [
        {
            "type": "text",
            "text": "Quote",
            "style": {
                "bold": true,
                "italic": true
            }
        },
        {
            "type": "text",
            "text": " with "
        },
        {
            "type": "broadcast",
            "range": "here"
        },
        {
            "type": "text",
            "text": " mention, and an emoji: "
        },
        {
            "type": "emoji",
            "name": "wave",
            "skin_tone": 1
        }
    ]
}
```

--------------------------------

### spawnModalView

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Triggers creation of a modal (regular modal or storage integration modal).

```APIDOC
## spawnModalView

### Description
Initiates the display of a modal view to the user. This can be a standard modal or a specialized modal for storage integration.

### Method
N/A (SDK Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **View<"MODAL"> | StorageIntegrationModalCredentials** - The definition of the modal view or storage integration credentials to be displayed.

### Request Example
```javascript
// For a regular modal:
await pumble.spawnModalView(modalViewDefinition);

// For a storage integration modal:
await pumble.spawnModalView(storageCredentials);
```

### Response
#### Success Response (void)
- This method does not return a value upon successful execution.

#### Response Example
```json
{
  "//": "No response body for this method"
}
```
```

--------------------------------

### spawnModalView

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/triggers-reference.md

Triggers creation of a modal (regular modal or storage integration modal).

```APIDOC
## spawnModalView

### Description
Initiates the display of a modal view, which can be a standard modal or a storage integration modal.

### Method
([View<"MODAL">](/modals-views-reference#modal) | [StorageIntegrationModalCredentials](/modals-views-reference#storage-integration)) => Promise<void>

### Parameters
#### Request Body
- **view** (View<"MODAL"> | StorageIntegrationModalCredentials) - Required - The modal view configuration or storage integration credentials.

### Returns
A Promise that resolves when the modal has been triggered.
```

--------------------------------

### Handle Slash Command with Text Input

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/basic-concepts.md

Process user input provided after a slash command. This example validates the input text and responds accordingly, demonstrating how to access `ctx.payload.text`.

```typescript
const app: App = {
	//...
	slashCommands: [
		{
            command: '/todo',
            handler: async (ctx) => {
                await ctx.ack();
                const text = ctx.payload.text;
				if(!["add", "remove", "list"].includes(text)){
					await ctx.say("Invalid command");
					return;
				}
				await ctx.say(`Triggered /todo ${text} from <<@${ctx.payload.userId}>>` )
            },
        }
	]
};
```

--------------------------------

### Run Pumble CLI Locally with Custom Host and Port

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/pumble-cli.md

Use this command to run your app locally, syncing your manifest and watching for changes. It creates a tunnel to expose your server port, allowing Pumble to reach your app. Specify `--host` and `--port` for custom configurations.

```sh
pumble-cli --host=https://myhostname.com --port=8080
```

--------------------------------

### Pumble App Main Entry Point

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/getting-started.md

The main.ts file is the core of your Pumble App. It defines handlers for various Pumble events, shortcuts, and commands. It also configures token storage and server settings.

```typescript
//main.ts
import { App, JsonFileTokenStore, start } from "pumble-sdk";

const addon: App = {
    globalShortcuts: [
        {
            name: "Global shortcut",
            handler: async (ctx) => {
                await ctx.ack();
                console.log("Received global shortcut!");
                await ctx.say("Received global shortcut!");
            },
        },
    ],
    messageShortcuts: [
        {
            name: "Message shortcut",
            handler: async (ctx) => {
                await ctx.ack();
                console.log("Received message shortcut!");
                await ctx.say("Ok", "in_channel", true);
            },
        },
    ],
    slashCommands: [
        {
            command: "/slash_first",
            handler: async (ctx) => {
                await ctx.ack();
                console.log("Received slash command!");
                await ctx.say("Received slash command!");
            },
        },
    ],
    events: [
        {
            name: "NEW_MESSAGE",
            handler: (ctx) => {
                console.log("Received new message!", ctx.payload.body);
            },
        },
    ],
    blockInteraction: {
        interactions: [
            {
                sourceType: "MESSAGE",
                handlers: {
                    "on_action_1": async (ctx: BlockInteractionContext<'MESSAGE'>) => {
                        await ctx.ack();
                        console.log("Action triggered!");
                    }
                }
            }
        ]    
    },
    viewAction: {
        onSubmit: {
            view_callback_1: async (ctx) => {
                await ctx.ack();
                console.log("View submitted.");
            }
        },
        onClose: {
            view_callback_1: async (ctx) => {
                await ctx.ack();
                console.log("View closed.");
            }
        }
    },
    eventsPath: "/hook",
    redirect: { enable: true, path: "/redirect" },
    tokenStore: new JsonFileTokenStore("tokens.json"),
    welcomeMessage: 'Welcome!',
    offlineMessage: 'App cannot respond at this moment. Please try again later.',
    onServerConfiguring: (e, addon) => { 
        // ... 
    }
};

start(addon);
```

--------------------------------

### Listen to NEW_MESSAGE Events in Pumble App

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/basic-concepts.md

Configure handlers for the NEW_MESSAGE event in your Pumble app. Ensure 'messages:read' scope is set in your manifest. This example shows basic message handling.

```typescript
const app: App = {
    //...
    events: [
        {
            name: 'NEW_MESSAGE', 
            handler: async (ctx) => {
                console.log("Received a message.")
            },
        }, 
        //...
    ]
    //...
}
```

--------------------------------

### Pumble App Manifest Configuration

Source: https://github.com/cake-com/pumble-node-sdk/blob/master/docs/getting-started.md

The manifest.json file defines your App's name, display name, bot title, and scopes. Ensure scopes are correctly set for desired permissions.

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