ask-slack 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01d86ade7e8ae10d0ea5370bf29ad2d5817dab29d6fed2d210bdf6a900498206
-  data.tar.gz: ba00d9649330d05b973d12a7d173c28337b8c5d0a54236b6c0c40d45902181d5
+  metadata.gz: 8328e80c2b6386b33282dd95c8af3eceab18182e53547d5fe6b849a9bcbe874d
+  data.tar.gz: c73406fd2a39f3d8dca19f856226373cc30c090023a2f73d2f1b342081a2c3bd
 SHA512:
-  metadata.gz: 53cc6ece6ba677124a33a25cff481df7e3dafcd1bff49186211e46ba30f6f64089263d9585eda6a1041191e7288659234d3f2d41c1730d04376a216a023f7822
-  data.tar.gz: 15db0b3dfcb89f293ceda3dbb18c9623ceaa8f5344c6664a88ca32e4df6fe7952eb23862863a761e004faeade2223b557f618134cbe5a90cea88a7ab83e8fea6
+  metadata.gz: b46af6dc89a858df607c4e0b57a32873463ab80883757e0bcbba57e1297882a23e2d23fbe916d9e7fa31912caace997be3166b170537af293bff1ae07fb48452
+  data.tar.gz: 32d1694ed20b65b4595a7b24a70aad1f255745d33208b6844b73ce7099154bcea8761f0520826a72f260eb448f067a7d5ed7635980c4a2bcd7aa46e8b769e35e

data/lib/ask/skills/slack.use_slack/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: slack.use_slack
+description: How to navigate the Slack API with slack-ruby-client — discover methods, handle auth, pagination, and errors
+---
+
+Use this skill when you need to interact with Slack — posting messages, reading
+channels, managing users, uploading files, or searching conversations.
+
+## Step 1: Get the Client
+
+```ruby
+client = Ask::Slack.client
+```
+
+This returns an authenticated `Slack::Web::Client`. It expects a valid Slack Bot
+User OAuth Token resolved via `Ask::Auth.resolve(:slack_token)`.
+
+If you get an auth error, read `Ask::Slack::Context::AUTH_HOW` for token setup.
+
+## Step 2: Explore the Context
+
+The gem ships with structured context you should reference:
+
+```ruby
+Ask::Slack::Context::DOCS_URL    # Slack Web API methods docs
+Ask::Slack::Context::GEM_DOCS    # slack-ruby-client Ruby docs
+Ask::Slack::Context::QUICK_START # Copy-paste examples
+Ask::Slack::Context::GEM_NAME    # "slack-ruby-client"
+```
+
+The `QUICK_START` constant has basic examples for channels, messaging, and users.
+
+## Step 3: Discover Available Methods
+
+Use code tools to explore the underlying SDK client:
+
+```ruby
+Code.new.call(code: "
+  client = Ask::Slack.client.client  # unwrap proxy to get raw client
+  puts client.methods(false).sort.join(\"\\n\")
+")
+```
+
+Common Slack API methods:
+- `client.chat_postMessage(channel:, text:, blocks:)` — send a message
+- `client.conversations_list` — list public channels
+- `client.conversations_history(channel:)` — read channel history
+- `client.conversations_replies(channel:, ts:)` — get thread replies
+- `client.users_list` — list workspace users
+- `client.files_upload_v2(channels:, content:, file:)` — upload files
+
+For method details, read the slack-ruby-client source:
+```ruby
+# Discover the underlying WebClient methods
+Read.new.call(path: "$GEM_PATH/slack-ruby-client-*/lib/slack/web/client.rb")
+```
+
+## Step 4: Authentication & Common Errors
+
+Auth failures are converted to `Ask::Auth::InvalidCredential`. For detailed
+error guidance, use:
+
+```ruby
+Ask::Slack::Errors.for("channel_not_found")
+Ask::Slack::Errors.status_code_description(429)
+Ask::Slack::Errors::RATE_LIMIT
+Ask::Slack::Errors::PAGINATION
+```
+
+Common scenarios:
+- **not_in_channel**: Bot isn't in that channel → invite or use `conversations_join`
+- **missing_scope**: Token lacks required OAuth scope → add at api.slack.com/apps
+- **rate_limited**: Exceeded per-method limit → check Retry-After header
+- **invalid_blocks**: Block Kit JSON has validation errors
+
+## Step 5: Pagination
+
+Slack uses cursor-based pagination. The pattern is:
+
+```ruby
+response = client.conversations_list(limit: 200)
+cursor = response.response_metadata.next_cursor
+# Pass cursor in next request:
+client.conversations_list(limit: 200, cursor: cursor) unless cursor.empty?
+```
+
+Most list methods accept `limit` (max 200) and `cursor` parameters.
+
+## Step 6: Message Formatting
+
+For rich messages, use Block Kit (JSON blocks). The `QUICK_START` constant
+has examples for header, section, context, divider, and actions blocks. For
+detailed Block Kit reference, see the Slack API docs.
+
+## Step 7: Fallback Strategy
+
+If the SDK doesn't have a method for what you need:
+1. Check `Ask::Slack::Context::DOCS_URL` for the API method
+2. Use `client.post("method.name", params)` for custom API calls
+3. Use `client.get("conversations.list")` style for raw endpoint access

data/lib/ask/slack/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Slack
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-slack
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Kaka Ruto
@@ -146,7 +146,7 @@ files:
 - LICENSE
 - README.md
 - lib/ask-slack.rb
-- lib/ask/skills/slack.compose/SKILL.md
+- lib/ask/skills/slack.use_slack/SKILL.md
 - lib/ask/slack/client.rb
 - lib/ask/slack/context.rb
 - lib/ask/slack/error_guide.rb

data/lib/ask/skills/slack.compose/SKILL.md

@@ -1,168 +0,0 @@
----
-name: slack.compose
-description: How to format and send effective Slack messages — blocks, attachments, markdown, and threading
----
-
-Use this skill when you need to communicate via Slack — sending messages,
-formatting rich content, or managing conversations with the Slack API.
-
-## Step 1: Establish the Channel and Context
-
-Before sending any message, confirm:
-
-- **Channel** — public channel name (e.g. `#general`) or user DM ID
-- **Intent** — are you informing, asking, alerting, or collaborating?
-- **Thread** — should this be a new message or reply in an existing thread?
-
-```ruby
-client = Ask::Slack.client
-```
-
-## Step 2: Choose the Message Format
-
-Slack supports three levels of message formatting:
-
-**Plain text** — Simple, fast, use for ephemeral or bot messages:
-```ruby
-client.chat_postMessage(channel: "#general", text: "Deploy finished successfully!")
-```
-
-**Markdown-ish text** — Use basic formatting in `text`:
-- `*bold*` for emphasis
-- `_italic_` for book titles or terms
-- `~strikethrough~` for obsolete info
-- `` `code` `` for inline code
-- ``````code block`````` for multi-line code
-- `>quote` for blockquotes
-
-**Blocks** — Rich interactive messages with structured layout:
-```ruby
-client.chat_postMessage(channel: "#deploy", blocks: [
-  {
-    type: "header",
-    text: { type: "plain_text", text: "🚀 Deploy Complete" }
-  },
-  {
-    type: "section",
-    text: { type: "mrkdwn", text: "Version *v2.3.1* deployed to *production*" }
-  },
-  {
-    type: "context",
-    elements: [
-      { type: "mrkdwn", text: "By: @kaka | Duration: 2m 34s" }
-    ]
-  }
-])
-```
-
-## Step 3: Use Block Kit for Rich Messages
-
-Block Kit is the recommended way to compose Slack messages. Key block types:
-
-**Header** — Bold, centered title (1 per message recommended):
-```ruby
-{ type: "header", text: { type: "plain_text", text: "📋 Report Title" } }
-```
-
-**Section** — Body content with optional accessory:
-```ruby
-{ type: "section",
-  text: { type: "mrkdwn", text: "Description here" },
-  accessory: { type: "button", text: { type: "plain_text", text: "View" }, value: "view", url: "..." } }
-```
-
-**Divider** — Visual separator:
-```ruby
-{ type: "divider" }
-```
-
-**Context** — Small text for metadata, timestamps, authorship:
-```ruby
-{ type: "context", elements: [{ type: "mrkdwn", text: "Posted 2h ago" }] }
-```
-
-**Fields** — Multi-column layout in a section:
-```ruby
-{ type: "section",
-  fields: [
-    { type: "mrkdwn", text: "*Status:*\n✅ Complete" },
-    { type: "mrkdwn", text: "*Duration:*\n45s" }
-  ] }
-```
-
-**Actions** — Interactive buttons (avoid more than 3):
-```ruby
-{ type: "actions", elements: [
-  { type: "button", text: { type: "plain_text", text: "Approve" }, style: "primary", value: "approve" },
-  { type: "button", text: { type: "plain_text", text: "Reject" }, style: "danger", value: "reject" }
-] }
-```
-
-## Step 4: Handle Threading
-
-Reply in a thread to keep conversations organized:
-
-```ruby
-# Reply to a specific message
-client.chat_postMessage(
-  channel: "#general",
-  thread_ts: "1234567890.123456",  # parent message timestamp
-  text: "I've looked into this — here's what I found..."
-)
-
-# Broadcast reply to channel as well (use sparingly)
-client.chat_postMessage(
-  channel: "#general",
-  thread_ts: "1234567890.123456",
-  text: "Update for everyone",
-  reply_broadcast: true
-)
-```
-
-## Step 5: Handle Errors
-
-Slack API errors are converted to `Ask::Auth::InvalidCredential` for auth failures.
-For other errors, check the error message:
-
-```ruby
-begin
-  client.chat_postMessage(channel: "#unknown", text: "test")
-rescue Slack::Web::Api::Errors::ChannelNotFound => e
-  # Channel doesn't exist or bot not invited
-end
-```
-
-Common errors:
-- `channel_not_found` — Bot not in channel or channel doesn't exist
-- `not_in_channel` — Bot needs to be invited: `/invite @botname`
-- `invalid_blocks` — Block Kit JSON validation error
-- `rate_limited` — Too many requests, retry with backoff
-- `msg_too_long` — Message exceeds 40,000 character limit
-
-## Step 6: Upload Files
-
-For longer content, upload as a file:
-
-```ruby
-client.files_upload_v2(
-  channels: "#general",
-  content: "Long content here...",
-  filename: "report.txt",
-  title: "Deploy Report"
-)
-```
-
-## Formatting Reference
-
-| Format | Markdown | Result |
-|--------|----------|--------|
-| Bold | `*text*` | **text** |
-| Italic | `_text_` | *text* |
-| Strikethrough | `~text~` | ~~text~~ |
-| Code | `` `code` `` | `code` |
-| Code block | ```` ```code``` ```` | ⬛ code |
-| Quote | `>text` | blockquote |
-| Link | `<https://...\|label>` | [label](...) |
-| User mention | `<@U12345>` | @username |
-| Channel | `<#C12345>` | #channel |
-| Emoji | `:rocket:` | 🚀 |