ask-slack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b550c9169e3b980cb31099c840db9da17a79d2b1164ef92ba3b6d85080a68f3f
+  data.tar.gz: 484183cfcf1a3b76e11f3c3b1d09382c2d4acc72e2d73c538c8b0448fd8c2d55
+SHA512:
+  metadata.gz: ddf878f447dfd83a0130daf887c4b629fbaa5af92513d4908fdaf9789b787505e2bde3f9cd334ce8b3890d427d2fea350b53d2eb7d9955f9edf8c878519f9283
+  data.tar.gz: 80b75a4d986f37c174b46435641f623b3ff46267b0cf9263cc95478c5081da37b19bcfac10108b83aef35d12365ddc19ac03ca7b6d8f01afc5f0638b5cda2078

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# ask-slack
+
+Slack service context for the ask-rb ecosystem.
+
+Provides:
+- `Ask::Slack.client` — authenticated Slack Web API client
+- `Ask::Slack::DESCRIPTION` — context metadata for the system prompt
+- `Ask::Slack::Errors` — structured error knowledge for agents
+
+## Installation
+
+```ruby
+gem "ask-slack"
+```
+
+## Usage
+
+```ruby
+require "ask-slack"
+
+client = Ask::Slack.client
+client.chat_postMessage(channel: "#general", text: "Hello from ask-rb!")
+client.conversations_list
+client.users_list
+```
+
+## Authentication
+
+Set your Slack Bot User OAuth Token:
+
+```bash
+export SLACK_TOKEN=xoxb-your-bot-token-here
+```
+
+Or add it to `~/.ask/credentials.yml`:
+
+```yaml
+slack_token: xoxb-your-bot-token-here
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/slack/client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "slack-ruby-client"
+require "ask/auth"
+
+module Ask
+  module Slack
+    # 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+.
+    #
+    # Configuration:
+    # - Uses the resolved token for authentication
+    # - Default user agent is set by slack-ruby-client
+    #
+    # @example
+    #   client = Ask::Slack.client
+    #   client.channels_list
+    #   client.chat_postMessage(channel: "#general", text: "Hello!")
+    #
+    # @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
+      token = Ask::Auth.resolve(:slack_token)
+
+      ClientProxy.new(::Slack::Web::Client.new(token: token))
+    end
+
+    # Proxies method calls to a +::Slack::Web::Client+, converting authentication
+    # errors into +Ask::Auth::InvalidCredential+.
+    class ClientProxy < ::BasicObject
+      def initialize(client)
+        @client = client
+      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
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/ask/slack/context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ask
+  module Slack
+    # Human-readable description of the Slack service context.
+    DESCRIPTION = "Slack — messaging, channels, files, search, workspace management"
+
+    # Base URL for Slack Web API methods.
+    DOCS_URL = "https://api.slack.com/methods"
+
+    # URL for the Slack OpenAPI specification.
+    OPENAPI_URL = "https://api.slack.com/specs/openapi"
+
+    # Credential name used with Ask::Auth.resolve.
+    AUTH_NAME = :slack_token
+
+    # Instructions for obtaining a Slack Bot User OAuth Token.
+    AUTH_HOW = "Create a Slack app at https://api.slack.com/apps — get a Bot User OAuth Token (xoxb-). Scopes: chat:write, channels:read, users:read, files:read"
+
+    # Gem name for the Slack API client.
+    GEM_NAME = "slack-ruby-client"
+
+    # Required gem version constraint.
+    GEM_VERSION = "~> 3.1"
+
+    # URL for slack-ruby-client library documentation.
+    GEM_DOCS = "https://rubydoc.info/gems/slack-ruby-client"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      client = Ask::Slack.client
+      client.channels_list
+      client.conversations_list
+      client.chat_postMessage(channel: "#general", text: "Hello from ask-rb!")
+      client.users_list
+      client.conversations_history(channel: "C123456")
+    RUBY
+  end
+end

data/lib/ask/slack/error_guide.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Ask
+  module Slack
+    # Structured error knowledge for AI agents working with the Slack Web API.
+    #
+    # Provides human-readable guidance for common HTTP status codes, rate
+    # limiting, pagination, and authentication errors encountered when
+    # using the slack-ruby-client.
+    module Errors
+      # Rate limit information.
+      #
+      # Slack rate limits are applied per-method, per-app. Limits vary
+      # by endpoint. When rate-limited, +Slack::Web::Api::Errors::TooManyRequestsError+
+      # is raised with a +Retry-After+ header.
+      RATE_LIMIT = {
+        typical_limit: "Varies per method (typically 1–50 requests per minute per app)",
+        error_class: "Slack::Web::Api::Errors::TooManyRequestsError",
+        retry_header: "Retry-After (seconds)",
+        action: "Wait for the Retry-After duration, then retry the request. Use the retry_after method on the error."
+      }.freeze
+
+      # Common error strings returned by the Slack Web API and how to handle them.
+      ERRORS = {
+        "not_authed" => {
+          message: "No authentication token provided.",
+          action: "Ensure Ask::Slack.client is called with a valid token. Check that SLACK_TOKEN is set."
+        },
+        "invalid_auth" => {
+          message: "The authentication token is invalid or malformed.",
+          action: "Verify your Slack token is correct. It should start with xoxb- (bot) or xoxp- (user)."
+        },
+        "account_inactive" => {
+          message: "The authentication token is for a deleted or disabled account.",
+          action: "Reactivate the Slack app or generate a new token at https://api.slack.com/apps."
+        },
+        "token_revoked" => {
+          message: "The authentication token has been revoked.",
+          action: "Generate a new token at https://api.slack.com/apps and update your credentials."
+        },
+        "token_expired" => {
+          message: "The authentication token has expired.",
+          action: "Refresh the token or generate a new one at https://api.slack.com/apps."
+        },
+        "token_not_found" => {
+          message: "The authentication token could not be found.",
+          action: "Check that the token has been properly set via Ask::Auth."
+        },
+        "rate_limited" => {
+          message: "Slack API rate limit exceeded.",
+          action: "Check the Retry-After header, wait the specified duration, then retry. Use Slack::Web::Api::Errors::TooManyRequestsError#retry_after."
+        },
+        "ratelimited" => {
+          message: "Slack API rate limit exceeded (alternative error string).",
+          action: "Same as 'rate_limited' — wait for the Retry-After duration, then retry."
+        },
+        "channel_not_found" => {
+          message: "The specified channel was not found.",
+          action: "Verify the channel ID (starts with C) or channel name. Fetch available channels with client.conversations_list."
+        },
+        "user_not_found" => {
+          message: "The specified user was not found.",
+          action: "Verify the user ID (starts with U) or email. Fetch available users with client.users_list."
+        },
+        "not_in_channel" => {
+          message: "The bot user is not a member of the specified channel.",
+          action: "Invite the bot to the channel or use client.conversations_join to join public channels."
+        },
+        "restricted_action" => {
+          message: "The token lacks the required scopes for this action.",
+          action: "Add the required OAuth scope to your Slack app at https://api.slack.com/apps and reinstall."
+        },
+        "missing_scope" => {
+          message: "The token is missing a required OAuth scope.",
+          action: "Add the required scope at https://api.slack.com/apps, then reinstall the app to your workspace."
+        },
+        "invalid_arguments" => {
+          message: "The request contained invalid arguments.",
+          action: "Check the required parameters and data types for the method. See https://api.slack.com/methods for details."
+        },
+        "internal_error" => {
+          message: "Slack encountered an internal server error.",
+          action: "Retry with exponential backoff. If the issue persists, check https://status.slack.com."
+        },
+        "service_unavailable" => {
+          message: "Slack service is temporarily unavailable.",
+          action: "Retry with backoff. Check https://status.slack.com for ongoing incidents."
+        },
+        "fatal_error" => {
+          message: "Slack encountered a fatal error.",
+          action: "Retry with exponential backoff. Contact Slack support if the issue persists."
+        },
+        "deprecated_endpoint" => {
+          message: "The API endpoint has been deprecated.",
+          action: "Check https://api.slack.com/changelog for the replacement endpoint."
+        }
+      }.freeze
+
+      # HTTP status codes commonly returned by the Slack API.
+      STATUS_CODES = {
+        200 => "OK — Request succeeded.",
+        201 => "Created — File or resource was created.",
+        204 => "No Content — Request succeeded, no response body.",
+        400 => "Bad Request — Invalid parameters. Check the error field in the response.",
+        401 => "Unauthorized — Token missing or invalid. Re-authenticate.",
+        403 => "Forbidden — Token lacks required scopes.",
+        404 => "Not Found — Resource does not exist.",
+        429 => "Too Many Requests — Rate limit exceeded. Use Retry-After header.",
+        500 => "Internal Server Error — Slack server issue. Retry with backoff.",
+        502 => "Bad Gateway — Slack upstream issue. Retry with backoff.",
+        503 => "Service Unavailable — Slack is down for maintenance. Retry later."
+      }.freeze
+
+      # Pagination guidance for large result sets.
+      PAGINATION = {
+        cursor_based: "Slack uses cursor-based pagination via the 'next_cursor' field in response_metadata.",
+        limit: "Use the 'limit' parameter to set page size (max 200 for most endpoints).",
+        pattern: "Set cursor parameter to response_metadata.next_cursor from the previous response.",
+        max_results: "For large result sets, iterate through all cursors."
+      }.freeze
+
+      # Map of Slack error strings to common exception classes.
+      EXCEPTION_CLASSES = {
+        "not_authed" => "Slack::Web::Api::Errors::NotAuthed",
+        "invalid_auth" => "Slack::Web::Api::Errors::InvalidAuth",
+        "account_inactive" => "Slack::Web::Api::Errors::AccountInactive",
+        "token_revoked" => "Slack::Web::Api::Errors::TokenRevoked",
+        "token_expired" => "Slack::Web::Api::Errors::TokenExpired",
+        "rate_limited" => "Slack::Web::Api::Errors::TooManyRequestsError",
+        "channel_not_found" => "Slack::Web::Api::Errors::ChannelNotFound",
+        "user_not_found" => "Slack::Web::Api::Errors::UserNotFound"
+      }.freeze
+
+      # Look up guidance for a Slack error string.
+      #
+      # @param error_string [String] The Slack API error string (e.g., "channel_not_found")
+      # @return [Hash, nil] A hash with +:message+ and +:action+ keys, or nil if unknown
+      def self.for(error_string)
+        ERRORS[error_string]
+      end
+
+      # Describe an HTTP status code.
+      #
+      # @param code [Integer] HTTP status code
+      # @return [String, nil] Description of the status code
+      def self.status_code_description(code)
+        STATUS_CODES[code]
+      end
+
+      # Look up the exception class name for a Slack error string.
+      #
+      # @param error_string [String] The Slack API error string
+      # @return [String, nil] The fully qualified exception class name
+      def self.exception_class(error_string)
+        EXCEPTION_CLASSES[error_string]
+      end
+    end
+  end
+end

data/lib/ask/slack/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Slack
+    VERSION = '0.1.0'
+  end
+end

data/lib/ask-slack.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ask/slack/version"
+require_relative "ask/slack/context"
+require_relative "ask/slack/client"
+require_relative "ask/slack/error_guide"

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: ask-slack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: slack-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides authenticated Slack client helper, context metadata, and error
+  guide for AI agents.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-slack.rb
+- lib/ask/slack/client.rb
+- lib/ask/slack/context.rb
+- lib/ask/slack/error_guide.rb
+- lib/ask/slack/version.rb
+homepage: https://github.com/ask-rb/ask-slack
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Slack service context for the ask-rb ecosystem
+test_files: []