Merge pull request #1 from slack-samples/init-improvements

feat: improve the sample to follow patterns from other templates

Author: WilliamBergamin

.github/workflows/lint.yml

@@ -22,7 +22,7 @@ jobs:
             - name: Install dependencies
               run: |
                   pip install -U pip
-                  pip install -r requirements.txt
+                  pip install ".[dev]"
             - name: Lint with ruff
               run: |
                   ruff check

.github/workflows/tests.yml

@@ -22,7 +22,7 @@ jobs:
             - name: Install dependencies
               run: |
                   pip install -U pip
-                  pip install -r requirements.txt
+                  pip install ".[dev]"
             - name: Run all tests
               run: |
                   pytest .

.slack/apps.json

@@ -1,2 +1,130 @@
-# bolt-python-search-template
-A template for implementing enterprise search in Bolt for Python
+# Bolt for Python Search Template
+
+> ⚠️ **Beta Notice**: This template demonstrates search functionality that is currently in beta and not yet widely available to all developers. The features shown here are being tested and may change before general availability.
+
+This is a Slack app template for building search functionality using Bolt for Python. It demonstrates how to create custom functions for search and filtering capabilities.
+
+It's recommended to use a [Slack sandbox](https://docs.slack.dev/tools/developer-sandboxes/) for development and testing. Other workspaces may not have access to all these features. To get started:
+
+1. Join the [Slack Developer Program](https://api.slack.com/developer-program) if you haven't already
+2. [Provision a sandbox workspace](https://docs.slack.dev/tools/developer-sandboxes/#provision)
+
+## Installation
+
+### Using Slack CLI
+
+Install the latest version of the Slack CLI for your operating system:
+
+- [Slack CLI for macOS & Linux](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux/)
+- [Slack CLI for Windows](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-windows/)
+
+You'll also need to log in if this is your first time using the Slack CLI.
+
+```sh
+slack login
+```
+
+#### Initializing the project
+
+```sh
+slack create bolt-python-search --template slack-samples/bolt-python-search-template -branch init
+cd bolt-python-search
+
+# Setup your python virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install the dependencies
+pip install .
+```
+
+#### Creating the Slack app
+
+```sh
+slack install
+```
+
+#### Running the app
+
+```sh
+slack run
+```
+
+<details>
+<summary><h3>Using Terminal</h3></summary>
+
+1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and choose "From an app manifest"
+2. Choose the workspace you want to install the application to
+3. Copy the contents of [manifest.json](./manifest.json) into the text box that says `*Paste your manifest code here*` (within the JSON tab) and click _Next_
+4. Review the configuration and click _Create_
+5. Click _Install to Workspace_ and _Allow_ on the screen that follows. You'll then be redirected to the App Configuration dashboard.
+
+#### Environment Variables
+
+Before you can run the app, you'll need to store some environment variables.
+
+1. Open your apps configuration page from this list, click **OAuth & Permissions** in the left hand menu, then copy the Bot User OAuth Token. You will store this in your environment as `SLACK_BOT_TOKEN`.
+2. Click ***Basic Information** from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the `connections:write` scope. Copy this token. You will store this in your environment as `SLACK_APP_TOKEN`.
+
+```zsh
+# Replace with your app token and bot token
+export SLACK_BOT_TOKEN=<your-bot-token>
+export SLACK_APP_TOKEN=<your-app-token>
+```
+
+### Setup Your Local Project
+
+```sh
+# Clone this project onto your machine
+git clone https://github.com/slack-samples/bolt-python-search-template.git
+
+# Change into this project directory
+cd bolt-python-search-template
+
+# Setup your python virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install all the dependencies
+pip install -e ".[dev]" 
+
+# Start your local server
+python3 app.py
+```
+
+</details>
+
+## Linting
+
+```sh
+# Run ruff from root directory for linting
+ruff check
+
+# Run ruff from root directory for formatting
+ruff format && ruff check --fix
+```
+
+## Testing
+
+```sh
+# Run pytest from root directory for unit testing
+pytest .
+```
+
+## Project Structure
+
+### `manifest.json`
+
+`manifest.json` is a configuration for Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.
+
+### `app.py`
+
+`app.py` is the entry point for the application and is the file you'll run to start the server. This project aims to keep this file as thin as possible, primarily using it as a way to route inbound requests.
+
+### `/listeners`
+
+Every incoming request is routed to a "listener". Inside this directory, we group each listener based on the Slack Platform feature used, so `/listeners/events` handles incoming [Events](https://docs.slack.dev/reference/events) requests, `/listeners/functions` handles [custom steps](https://docs.slack.dev/tools/bolt-js/concepts/custom-steps) and so on.
+
+### `/test`
+
+The `/test` directory contains the test suite for this project. It mirrors the structure of the source code, with test files corresponding to their implementation counterparts. For example, tests for files in `/listeners/functions` are located in `/test/listeners/functions`.

README.md

@@ -1,214 +1,16 @@
-import json
 import logging
 import os
-from enum import Enum
-from typing import TypedDict, List, Optional, NotRequired
 
-from slack_bolt import Ack, App, Complete, Fail
+from slack_bolt import App
 from slack_bolt.adapter.socket_mode import SocketModeHandler
-from slack_sdk import WebClient
 
-logging.basicConfig(level=logging.INFO)
-
-#----------------------
-# MODELS
-#----------------------
-
-class FilterType(Enum):
-    MULTI_SELECT = "multi_select"
-    TOGGLE = "toggle"
-
-class EntityReference(TypedDict):
-    id: str
-    type: Optional[str]
-
-class SearchResult(TypedDict):
-    title: str
-    description: str
-    link: str
-    date_updated: str
-    external_ref: EntityReference
-    content: NotRequired[str]
-
-
-class FilterOptions(TypedDict):
-    name: str
-    value: str
-
-
-class SearchFilter(TypedDict):
-    name: str
-    display_name: str
-    filter_type: FilterType
-    options: Optional[List[FilterOptions]]
-
-
-client = WebClient(token=os.environ.get("SLACK_BOT_TOKEN"), base_url="https://slack.com/api/")
-app = App(client=client)
-
-
-@app.function("search", auto_acknowledge=False)
-def handle_search_step_event(
-    ack: Ack, inputs: dict, body: dict, fail: Fail, complete: Complete, logger: logging.Logger
-):
-
-    try:
-        query = inputs.get("query")
-        languages_filter = inputs.get("filters", {}).get("languages", [])
-        type_filter = inputs.get("filters", {}).get("type", [])
-
-        filters_payload = {}
-        if languages_filter:
-            filters_payload["languages"] = languages_filter
-        if type_filter:
-            if len(type_filter) == 1:
-                filters_payload["type"] = type_filter[0]
-
-        params = {
-            "filters": json.dumps(filters_payload)
-        }
-        if query:
-            params["query"] = query
-
-        logger.info(f"Calling developer.sampleData.get with filters: {filters_payload}")
-
-        response = client.api_call(
-            api_method="developer.sampleData.get",
-            params=params
-        )
+from listeners import register_listeners
 
-        if not response.get("ok"):
-            logger.error(f"API error: {response}")
-            fail(error="Failed to fetch sample data")
-            return
-
-        samples = response.get("samples", [])
-
-        results: List[SearchResult] = [
-            {
-                "title": sample["title"],
-                "description": sample["description"],
-                "link": sample["link"],
-                "date_updated": sample["date_updated"],
-                "external_ref": sample["external_ref"],
-                **({"content": sample["content"]} if "content" in sample else {}),
-            }
-            for sample in samples
-        ]
-
-        complete(outputs={"search_result": results})
-
-    except Exception as e:
-        logger.error(f"Error in search step: {str(e)}")
-        fail(error=str(e))
-    finally:
-        ack()
-
-
-@app.function("filters", auto_acknowledge=False)
-def handle_filters_step_event(
-    ack: Ack, inputs: dict, fail: Fail, complete: Complete, logger: logging.Logger
-):
-    try:
-        filters: List[SearchFilter] = [
-            {
-                "name": "languages",
-                "display_name": "Languages",
-                "type": FilterType.MULTI_SELECT.value,
-                "options": [
-                    {"name": "Python", "value": "python"},
-                    {"name": "Java", "value": "java"},
-                    {"name": "JavaScript", "value": "javascript"},
-                    {"name": "TypeScript", "value": "typescript"},
-                ],
-            },
-            {
-                "name": "type",
-                "display_name": "Type",
-                "type": FilterType.MULTI_SELECT.value,
-                "options": [
-                    {"name": "Template", "value": "template"},
-                    {"name": "Sample", "value": "sample"},
-                ],
-            },
-        ]
-
-        complete(outputs={"filters": filters})
-    finally:
-        ack()
-
-@app.event("entity_details_requested")
-def handle_flexpane_event(event, body, client, logger):
-    sample_id = event["external_ref"]["id"]
-
-    response = client.api_call(api_method="developer.sampleData.get")
-
-    if not response.get("ok"):
-        logger.error(f"Failed to fetch samples: {response}")
-        return
-
-    samples = response.get("samples", [])
-
-    sample = next((s for s in samples if s["external_ref"]["id"] == sample_id), None)
-
-    if not sample:
-        logger.warning(f"No matching sample found for id={sample_id}")
-        return
-
-
-    custom_fields = [
-        {
-            "key": "description",
-            "label": "Description of sample",
-            "type": "string",
-            "value": sample["description"],
-        },
-        {
-            "key": "date_updated",
-            "label": "Last updated",
-            "type": "string",
-            "value": sample["date_updated"],
-        },
-    ]
-
-    if "content" in sample:
-        custom_fields.append({
-            "key": "content",
-            "label": "Details of sample",
-            "type": "string",
-            "value": sample["content"],
-        })
+logging.basicConfig(level=logging.INFO)
 
-    payload = {
-        "trigger_id": event["trigger_id"],
-        "metadata": {
-            "entity_type": "slack#/entities/item",
-            "url": event["link"]["url"],
-            "external_ref": {"id": sample_id},
-            "entity_payload": {
-                "attributes": {
-                    "title": {
-                        "text": sample["title"],
-                        "edit": {
-                            "enabled": False,
-                            "text": {
-                                "max_length": 50
-                            }
-                        }
-                    },
-                },
-                "custom_fields": custom_fields,
-            },
-        },
-    }
+app = App(token=os.environ.get("SLACK_BOT_TOKEN"))
 
-    try:
-        client.api_call(
-            api_method="entity.presentDetails",
-            json=payload,
-        )
-    except Exception as e:
-        logger.error(f"Error calling entity.presentDetails: {str(e)}")
+register_listeners(app)
 
 if __name__ == "__main__":
     SocketModeHandler(app, os.environ.get("SLACK_APP_TOKEN")).start()

app.py

@@ -1,8 +1,6 @@
-from slack_bolt import App
+from listeners import events, functions
 
-from .functions import handle_search_event, handle_filters_event
 
-
-def register_listeners(app: App):
-    app.function("search", auto_acknowledge=False, ack_timeout=10)(handle_search_event)
-    app.function("filters", auto_acknowledge=False)(handle_filters_event)
+def register_listeners(app):
+    functions.register(app)
+    events.register(app)

listeners/__init__.py

@@ -0,0 +1,7 @@
+from slack_bolt import App
+
+from .entity_details_requested import entity_details_requested_callback
+
+
+def register(app: App):
+    app.event("entity_details_requested")(entity_details_requested_callback)