ask-slack 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b550c9169e3b980cb31099c840db9da17a79d2b1164ef92ba3b6d85080a68f3f
-  data.tar.gz: 484183cfcf1a3b76e11f3c3b1d09382c2d4acc72e2d73c538c8b0448fd8c2d55
+  metadata.gz: 01d86ade7e8ae10d0ea5370bf29ad2d5817dab29d6fed2d210bdf6a900498206
+  data.tar.gz: ba00d9649330d05b973d12a7d173c28337b8c5d0a54236b6c0c40d45902181d5
 SHA512:
-  metadata.gz: ddf878f447dfd83a0130daf887c4b629fbaa5af92513d4908fdaf9789b787505e2bde3f9cd334ce8b3890d427d2fea350b53d2eb7d9955f9edf8c878519f9283
-  data.tar.gz: 80b75a4d986f37c174b46435641f623b3ff46267b0cf9263cc95478c5081da37b19bcfac10108b83aef35d12365ddc19ac03ca7b6d8f01afc5f0638b5cda2078
+  metadata.gz: 53cc6ece6ba677124a33a25cff481df7e3dafcd1bff49186211e46ba30f6f64089263d9585eda6a1041191e7288659234d3f2d41c1730d04376a216a023f7822
+  data.tar.gz: 15db0b3dfcb89f293ceda3dbb18c9623ceaa8f5344c6664a88ca32e4df6fe7952eb23862863a761e004faeade2223b557f618134cbe5a90cea88a7ab83e8fea6

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

@@ -0,0 +1,168 @@
+---
+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:` | 🚀 |

data/lib/ask/slack/client.rb

@@ -8,12 +8,19 @@ module Ask
     # Returns an authenticated Slack Web API client configured for an AI agent.
     #
     # Resolves the Slack token via +Ask::Auth.resolve(:slack_token)+ and
-    # wraps the client in a proxy that converts +::Slack::Web::Api::Errors::SlackError+
-    # authentication errors into +Ask::Auth::InvalidCredential+.
+    # configures the client with sensible defaults:
     #
-    # Configuration:
-    # - Uses the resolved token for authentication
-    # - Default user agent is set by slack-ruby-client
+    # - +timeout+: 30 seconds for HTTP requests
+    # - +open_timeout+: 10 seconds for TCP connection
+    #
+    # Retry behaviour: +ClientProxy+ retries transient Faraday and network
+    # errors up to 3 times with exponential backoff before raising
+    # +Ask::Auth::InvalidCredential+.
+    #
+    # The client is wrapped in a +ClientProxy+ that:
+    # 1. Converts auth errors (+NotAuthed+, +InvalidAuth+, etc.) into
+    #    +Ask::Auth::InvalidCredential+
+    # 2. Retries transient network failures with exponential backoff
     #
     # @example
     #   client = Ask::Slack.client
@@ -23,27 +30,54 @@ module Ask
     # @return [::Slack::Web::Client] an authenticated client
     # @raise [Ask::Auth::MissingCredential] if no Slack token is configured
     # @raise [Ask::Auth::InvalidCredential] if the token is rejected
-    def self.client
+    def self.client(base_delay: nil)
       token = Ask::Auth.resolve(:slack_token)
 
-      ClientProxy.new(::Slack::Web::Client.new(token: token))
+      ClientProxy.new(::Slack::Web::Client.new(
+        token: token,
+        timeout: 30,
+        open_timeout: 10
+      ), base_delay: base_delay)
     end
 
-    # Proxies method calls to a +::Slack::Web::Client+, converting authentication
-    # errors into +Ask::Auth::InvalidCredential+.
+    # Proxies method calls to a +::Slack::Web::Client+, converting auth errors
+    # and retrying transient network failures with exponential backoff.
     class ClientProxy < ::BasicObject
-      def initialize(client)
+      MAX_RETRIES = 3
+      RETRYABLE_ERRORS = [
+        ::Faraday::TimeoutError,
+        ::Faraday::ConnectionFailed,
+        ::Faraday::ServerError,
+        ::Errno::ECONNREFUSED,
+        ::Errno::ECONNRESET,
+        ::Timeout::Error
+      ].freeze
+
+      attr_reader :client
+
+      def initialize(client, base_delay: nil)
         @client = client
+        @_base_delay = base_delay || 1
       end
 
       def method_missing(name, ...)
-        @client.public_send(name, ...)
-      rescue ::Slack::Web::Api::Errors::NotAuthed,
-             ::Slack::Web::Api::Errors::InvalidAuth,
-             ::Slack::Web::Api::Errors::AccountInactive,
-             ::Slack::Web::Api::Errors::TokenRevoked,
-             ::Slack::Web::Api::Errors::TokenExpired
-        ::Kernel.raise ::Ask::Auth::InvalidCredential, :slack_token
+        retry_count = 0
+        begin
+          @client.public_send(name, ...)
+        rescue ::Slack::Web::Api::Errors::NotAuthed,
+               ::Slack::Web::Api::Errors::InvalidAuth,
+               ::Slack::Web::Api::Errors::AccountInactive,
+               ::Slack::Web::Api::Errors::TokenRevoked,
+               ::Slack::Web::Api::Errors::TokenExpired
+          ::Kernel.raise ::Ask::Auth::InvalidCredential, :slack_token
+        rescue *RETRYABLE_ERRORS => e
+          retry_count += 1
+          if retry_count <= MAX_RETRIES
+            ::Kernel.sleep(@_base_delay * (2 ** (retry_count - 1)))
+            retry
+          end
+          ::Kernel.raise ::Ask::Auth::InvalidCredential.new(:slack_token, e.message)
+        end
       end
 
       def respond_to_missing?(name, include_private = false)

data/lib/ask/slack/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-slack
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +93,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 description: Provides authenticated Slack client helper, context metadata, and error
   guide for AI agents.
 email:
@@ -90,6 +146,7 @@ files:
 - LICENSE
 - README.md
 - lib/ask-slack.rb
+- lib/ask/skills/slack.compose/SKILL.md
 - lib/ask/slack/client.rb
 - lib/ask/slack/context.rb
 - lib/ask/slack/error_guide.rb