ask-slack 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b550c9169e3b980cb31099c840db9da17a79d2b1164ef92ba3b6d85080a68f3f
-  data.tar.gz: 484183cfcf1a3b76e11f3c3b1d09382c2d4acc72e2d73c538c8b0448fd8c2d55
+  metadata.gz: 8328e80c2b6386b33282dd95c8af3eceab18182e53547d5fe6b849a9bcbe874d
+  data.tar.gz: c73406fd2a39f3d8dca19f856226373cc30c090023a2f73d2f1b342081a2c3bd
 SHA512:
-  metadata.gz: ddf878f447dfd83a0130daf887c4b629fbaa5af92513d4908fdaf9789b787505e2bde3f9cd334ce8b3890d427d2fea350b53d2eb7d9955f9edf8c878519f9283
-  data.tar.gz: 80b75a4d986f37c174b46435641f623b3ff46267b0cf9263cc95478c5081da37b19bcfac10108b83aef35d12365ddc19ac03ca7b6d8f01afc5f0638b5cda2078
+  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/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.2'
   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.2
 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.use_slack/SKILL.md
 - lib/ask/slack/client.rb
 - lib/ask/slack/context.rb
 - lib/ask/slack/error_guide.rb