openclacky 0.9.7 → 0.9.9

data/lib/clacky/server/channel/adapters/feishu/adapter.rb

@@ -73,6 +73,7 @@ module Clacky
             )
             @ws_client = nil
             @running = false
+            @doc_retry_cache = {} # { chat_id => { doc_urls: [...], attempts: N } }
           end
 
           # Start listening for messages via WebSocket
@@ -109,6 +110,15 @@ module Clacky
             @bot.send_text(chat_id, text, reply_to: reply_to)
           end
 
+          # Send a file (or image) to a chat.
+          # @param chat_id [String] Chat ID
+          # @param path [String] Local file path
+          # @param name [String, nil] Display filename
+          # @param reply_to [String, nil] Message ID to reply to
+          def send_file(chat_id, path, name: nil, reply_to: nil)
+            @bot.send_file(chat_id, path, name: name, reply_to: reply_to)
+          end
+
           # Update existing message
           # @param chat_id [String] Chat ID (unused for Feishu)
           # @param message_id [String] Message ID to update
@@ -149,8 +159,8 @@ module Clacky
               # Challenge is handled by MessageParser
             end
           rescue => e
-            warn "Error handling event: #{e.message}"
-            warn e.backtrace.join("\n")
+            Clacky::Logger.warn("[feishu] Error handling event: #{e.message}")
+            Clacky::Logger.warn(e.backtrace.first(5).join("\n"))
           end
 
           # Handle message event
@@ -181,9 +191,70 @@ module Clacky
             all_files = image_files + disk_files
             event = event.merge(files: all_files) unless all_files.empty?
 
+            # Merge cached doc_urls (from previous failed attempts) into current event
+            cached = @doc_retry_cache[event[:chat_id]]
+            if cached
+              merged_urls = ((event[:doc_urls] || []) + cached[:doc_urls]).uniq
+              event = event.merge(doc_urls: merged_urls)
+            end
+
+            # Fetch Feishu document content for any doc URLs in the message
+            if event[:doc_urls] && !event[:doc_urls].empty?
+              event = enrich_with_doc_content(event)
+              return if event.nil?
+            end
+
             @on_message&.call(event)
           end
 
+          # Fetch Feishu document content and append to event[:text].
+          # If the app lacks permission (91403), sends a guidance message and returns nil
+          # so the caller can skip forwarding the event to the agent.
+          # @param event [Hash]
+          # @return [Hash, nil] enriched event or nil if permission error
+          DOC_RETRY_MAX = 3
+
+          def enrich_with_doc_content(event)
+            doc_sections = []
+            failed_urls = []
+
+            event[:doc_urls].each do |url|
+              content = @bot.fetch_doc_content(url)
+              doc_sections << "📄 [Doc content from #{url}]\n#{content}" unless content.empty?
+            rescue Feishu::FeishuDocPermissionError
+              failed_urls << url
+              doc_sections << "#{url}\n[System Notice] Cannot read the above Feishu doc: the app has no access (error 91403). Tell user to: open the doc → top-right \"...\" → \"Add Document App\" → add this bot → just send any message to retry."
+            rescue Feishu::FeishuDocScopeError => e
+              failed_urls << url
+              scope_hint = e.auth_url ? "Admin can approve with one click: [点击授权](#{e.auth_url})" : "Admin needs to enable 'docx:document:readonly' scope in Feishu Open Platform."
+              doc_sections << "#{url}\n[System Notice] Cannot read the above Feishu doc: app is missing docx API scope (error 99991672). #{scope_hint} Tell user to just send any message to retry after approval."
+            rescue => e
+              failed_urls << url
+              Clacky::Logger.warn("[feishu] Failed to fetch doc #{url}: #{e.message}")
+              doc_sections << "#{url}\n[System Notice] Cannot read the above Feishu doc: #{e.message}. Tell user to just send any message to retry."
+            end
+
+            # Update retry cache
+            chat_id = event[:chat_id]
+            if failed_urls.any?
+              existing = @doc_retry_cache[chat_id]
+              attempts = (existing&.dig(:attempts) || 0) + 1
+              if attempts >= DOC_RETRY_MAX
+                @doc_retry_cache.delete(chat_id)
+              else
+                @doc_retry_cache[chat_id] = { doc_urls: failed_urls, attempts: attempts }
+              end
+            else
+              # All docs fetched successfully, clear cache
+              @doc_retry_cache.delete(chat_id)
+            end
+
+            return event if doc_sections.empty?
+
+            enriched_text = [event[:text], *doc_sections].reject(&:empty?).join("\n\n")
+            event.merge(text: enriched_text)
+          end
+
           MAX_IMAGE_BYTES = Clacky::Utils::FileProcessor::MAX_IMAGE_BYTES
 
           # Download images from Feishu and return as file hashes.
@@ -207,29 +278,23 @@ module Clacky
               data_url = "data:#{mime};base64,#{Base64.strict_encode64(result[:body])}"
               file_hashes << { name: "image.jpg", mime_type: mime, data_url: data_url }
             rescue => e
-              warn "[Feishu] Failed to download image #{image_key}: #{e.message}"
+              Clacky::Logger.warn("[feishu] Failed to download image #{image_key}: #{e.message}")
               errors << "Image download failed: #{e.message}"
             end
             [file_hashes, errors]
           end
 
-          # Download and process file attachments, returning file hashes for agent.
+          # Download and save file attachments, returning file hashes for agent.
+          # Parsing happens inside agent.run, not here.
           # @param attachments [Array<Hash>] [{key:, name:}]
           # @param message_id [String]
-          # @return [Array<Hash>] file hashes with path/preview_path/name/type/mime_type
+          # @return [Array<Hash>] { name:, path: }
           def process_files(attachments, message_id)
             attachments.filter_map do |attachment|
-              result   = @bot.download_message_resource(message_id, attachment[:key], type: "file")
-              file_ref = Clacky::Utils::FileProcessor.process(body: result[:body], filename: attachment[:name])
-              {
-                name:         file_ref.name,
-                path:         file_ref.original_path,
-                preview_path: file_ref.preview_path,
-                type:         file_ref.type.to_s,
-                mime_type:    "application/octet-stream"
-              }
+              result = @bot.download_message_resource(message_id, attachment[:key], type: "file")
+              Clacky::Utils::FileProcessor.save(body: result[:body], filename: attachment[:name])
             rescue => e
-              warn "[Feishu] Failed to download file #{attachment[:name]}: #{e.message}"
+              Clacky::Logger.warn("[feishu] Failed to download file #{attachment[:name]}: #{e.message}")
               nil
             end.compact
           end

data/lib/clacky/server/channel/adapters/feishu/bot.rb

@@ -1,12 +1,35 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/multipart"
 require "json"
 
 module Clacky
   module Channel
     module Adapters
       module Feishu
+        # Raised when the app lacks read permission for a specific Feishu document (error code 91403).
+        # The user needs to add the app as a collaborator on the document.
+        class FeishuDocPermissionError < StandardError
+          attr_reader :doc_token
+
+          def initialize(doc_token)
+            @doc_token = doc_token
+            super("App has no permission to access document: #{doc_token}")
+          end
+        end
+
+        # Raised when the app hasn't been granted the API scope for documents (error code 99991672).
+        # The admin needs to approve the scope via the returned auth_url.
+        class FeishuDocScopeError < StandardError
+          attr_reader :auth_url
+
+          def initialize(auth_url)
+            @auth_url = auth_url
+            super("App is missing docx API scope")
+          end
+        end
+
         # Feishu Bot API client.
         # Handles authentication, message sending, and API calls.
         class Bot
@@ -53,10 +76,42 @@ module Clacky
             response = patch("/open-apis/im/v1/messages/#{message_id}", payload)
             response["code"] == 0
           rescue => e
-            warn "Failed to update message: #{e.message}"
+            Clacky::Logger.warn("[feishu] Failed to update message: #{e.message}")
             false
           end
 
+          # Upload a local file to Feishu and send it to a chat.
+          # Images use /im/v1/images + msg_type "image".
+          # All other files use /im/v1/files + msg_type "file".
+          # @param chat_id [String] Chat ID
+          # @param path [String] Local file path
+          # @param name [String, nil] Display filename
+          # @param reply_to [String, nil] Message ID to reply to
+          # @return [Hash] Response with :message_id
+          def send_file(chat_id, path, name: nil, reply_to: nil)
+            raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+
+            filename  = name || File.basename(path)
+            file_data = File.binread(path)
+            ext       = File.extname(filename).downcase
+
+            if %w[.jpg .jpeg .png .gif .webp].include?(ext)
+              image_key = upload_image(file_data, filename)
+              content   = JSON.generate({ image_key: image_key })
+              msg_type  = "image"
+            else
+              file_key = upload_file(file_data, filename)
+              content  = JSON.generate({ file_key: file_key })
+              msg_type = "file"
+            end
+
+            payload = { receive_id: chat_id, msg_type: msg_type, content: content }
+            payload[:reply_to_message_id] = reply_to if reply_to
+
+            response = post("/open-apis/im/v1/messages", payload, params: { receive_id_type: "chat_id" })
+            { message_id: response.dig("data", "message_id") }
+          end
+
           # Download a message resource (image or file) from Feishu.
           # For message attachments, must use messageResource API — not im/v1/images.
           # @param message_id [String] Message ID containing the resource
@@ -85,6 +140,26 @@ module Clacky
             }
           end
 
+          # Fetch the plain-text content of a Feishu document (docx / docs / wiki).
+          # Raises FeishuDocPermissionError (code 91403) when the app has no access.
+          # @param url [String] Feishu document URL
+          # @return [String] Document plain text
+          def fetch_doc_content(url)
+            doc_token, doc_type = parse_doc_url(url)
+            raise ArgumentError, "Unsupported Feishu doc URL: #{url}" unless doc_token
+
+            if doc_type == :wiki
+              # Wiki: first resolve the real docToken via get_node
+              node = fetch_wiki_node(doc_token)
+              actual_token = node["obj_token"]
+              actual_type  = node["obj_type"]   # "docx" / "doc" / etc.
+              raise "Unsupported wiki node type: #{actual_type}" unless %w[docx doc].include?(actual_type)
+              fetch_docx_raw_content(actual_token)
+            else
+              fetch_docx_raw_content(doc_token)
+            end
+          end
+
           private
 
           # Build message content and type based on text content.
@@ -190,6 +265,140 @@ module Clacky
             parse_response(response)
           end
 
+          # Upload an image to Feishu and return image_key.
+          # @param data [String] Binary file content
+          # @param filename [String] Display filename
+          # @return [String] image_key
+          def upload_image(data, filename)
+            conn = Faraday.new(url: @domain) do |f|
+              f.options.timeout = DOWNLOAD_TIMEOUT
+              f.options.open_timeout = API_TIMEOUT
+              f.ssl.verify = false
+              f.request :multipart
+              f.adapter Faraday.default_adapter
+            end
+
+            response = conn.post("/open-apis/im/v1/images") do |req|
+              req.headers["Authorization"] = "Bearer #{tenant_access_token}"
+              req.body = {
+                image_type: "message",
+                image: Faraday::Multipart::FilePart.new(
+                  StringIO.new(data), detect_mime(filename), filename
+                )
+              }
+            end
+
+            result = JSON.parse(response.body)
+            raise "Failed to upload image: code=#{result["code"]} msg=#{result["msg"]}" if result["code"] != 0
+
+            result.dig("data", "image_key") or raise "No image_key returned"
+          end
+
+          # Upload a file to Feishu and return file_key.
+          # @param data [String] Binary file content
+          # @param filename [String] Display filename
+          # @return [String] file_key
+          def upload_file(data, filename)
+            conn = Faraday.new(url: @domain) do |f|
+              f.options.timeout = DOWNLOAD_TIMEOUT
+              f.options.open_timeout = API_TIMEOUT
+              f.ssl.verify = false
+              f.request :multipart
+              f.adapter Faraday.default_adapter
+            end
+
+            response = conn.post("/open-apis/im/v1/files") do |req|
+              req.headers["Authorization"] = "Bearer #{tenant_access_token}"
+              req.body = {
+                file_type: feishu_file_type(filename),
+                file_name: filename,
+                file: Faraday::Multipart::FilePart.new(
+                  StringIO.new(data), detect_mime(filename), filename
+                )
+              }
+            end
+
+            result = JSON.parse(response.body)
+            raise "Failed to upload file: code=#{result["code"]} msg=#{result["msg"]}" if result["code"] != 0
+
+            result.dig("data", "file_key") or raise "No file_key returned"
+          end
+
+          # Map file extension to Feishu file_type enum.
+          # Feishu accepts: opus, mp4, pdf, doc, xls, ppt, stream (others)
+          def feishu_file_type(filename)
+            case File.extname(filename).downcase
+            when ".pdf"             then "pdf"
+            when ".doc", ".docx"   then "doc"
+            when ".xls", ".xlsx"   then "xls"
+            when ".ppt", ".pptx"   then "ppt"
+            when ".mp4"            then "mp4"
+            when ".opus"           then "opus"
+            else                        "stream"
+            end
+          end
+
+          # Detect MIME type from filename extension.
+          def detect_mime(filename)
+            case File.extname(filename).downcase
+            when ".jpg", ".jpeg" then "image/jpeg"
+            when ".png"          then "image/png"
+            when ".gif"          then "image/gif"
+            when ".webp"         then "image/webp"
+            when ".pdf"          then "application/pdf"
+            when ".mp4"          then "video/mp4"
+            else                      "application/octet-stream"
+            end
+          end
+
+          # Parse Feishu doc URL and return [doc_token, type]
+          # type is :docx, :docs, or :wiki
+          # @param url [String]
+          # @return [Array<String, Symbol>, nil]
+          def parse_doc_url(url)
+            if (m = url.match(%r{/(?:docx|docs)/([A-Za-z0-9_-]+)}))
+              [m[1], :docx]
+            elsif (m = url.match(%r{/wiki/([A-Za-z0-9_-]+)}))
+              [m[1], :wiki]
+            end
+          end
+
+          # Fetch raw text content of a docx document.
+          # Raises FeishuDocPermissionError on 91403.
+          # @param doc_token [String]
+          # @return [String]
+          def fetch_docx_raw_content(doc_token)
+            response = get("/open-apis/docx/v1/documents/#{doc_token}/raw_content")
+            check_doc_error!(response, doc_token)
+            response.dig("data", "content").to_s.strip
+          end
+
+          # Resolve wiki node to get real obj_token and obj_type.
+          # @param wiki_token [String]
+          # @return [Hash] node data with "obj_token" and "obj_type"
+          def fetch_wiki_node(wiki_token)
+            response = get("/open-apis/wiki/v2/spaces/get_node", params: { token: wiki_token, obj_type: "wiki" })
+            check_doc_error!(response, wiki_token)
+            response.dig("data", "node") or raise "No node in wiki response"
+          end
+
+          # Check doc API response for known permission errors and raise accordingly.
+          def check_doc_error!(response, token)
+            code = response["code"].to_i
+            return if code == 0
+
+            if code == 91403
+              raise FeishuDocPermissionError, token
+            elsif code == 99991672
+              # Extract auth URL from the error message if present
+              auth_url = response.dig("error", "permission_violations", 0, "attach_url") ||
+                         response["msg"].to_s[/https:\/\/open\.feishu\.cn\/app\/[^\s"]+/]
+              raise FeishuDocScopeError.new(auth_url)
+            else
+              raise "Failed to fetch doc: code=#{code} msg=#{response["msg"]}"
+            end
+          end
+
           # Build Faraday connection
           # @return [Faraday::Connection]
           def build_connection
@@ -205,13 +414,13 @@ module Clacky
           # @param response [Faraday::Response]
           # @return [Hash] Parsed JSON
           def parse_response(response)
-            unless response.success?
-              raise "API request failed: HTTP #{response.status}"
-            end
+            # Feishu returns JSON even on 4xx — parse it so callers can inspect error codes
+            parsed = JSON.parse(response.body)
+            return parsed if response.success? || parsed.key?("code")
 
-            JSON.parse(response.body)
-          rescue JSON::ParserError => e
-            raise "Failed to parse API response: #{e.message}"
+            raise "API request failed: HTTP #{response.status} body=#{response.body.to_s[0..300]}"
+          rescue JSON::ParserError
+            raise "API request failed: HTTP #{response.status} body=#{response.body.to_s[0..300]}"
           end
         end
       end

data/lib/clacky/server/channel/adapters/feishu/message_parser.rb

@@ -55,6 +55,7 @@ module Clacky
             return nil unless message && sender
 
             msg_type = message["message_type"]
+            Clacky::Logger.info("[feishu] msg_type=#{msg_type} content=#{message["content"].to_s[0..300]}")
             return nil unless %w[text image file].include?(msg_type)
 
             content_raw = message["content"]
@@ -94,6 +95,7 @@ module Clacky
               text: text,
               image_keys: image_keys,
               file_attachments: file_attachments,
+              doc_urls: extract_doc_urls(text),
               message_id: message_id,
               timestamp: timestamp,
               chat_type: chat_type,
@@ -103,6 +105,16 @@ module Clacky
             nil
           end
 
+          # Extract Feishu document URLs from text.
+          # Matches: /docx/TOKEN, /docs/TOKEN, /wiki/TOKEN
+          # @param text [String]
+          # @return [Array<String>] matched URLs
+          def extract_doc_urls(text)
+            return [] if text.nil? || text.empty?
+
+            text.scan(%r{https?://[a-zA-Z0-9._-]+\.(?:feishu\.cn|larksuite\.com)/(?:docx|docs|wiki)/[A-Za-z0-9_-]+(?:\?[^\s]*)?})
+          end
+
           # Strip bot @mentions from message text
           # @param text [String]
           # @return [String]

data/lib/clacky/server/channel/adapters/wecom/adapter.rb

@@ -112,14 +112,8 @@ module Clacky
               filename = raw.dig("file", "name") || raw.dig("file", "filename") || "attachment"
               result   = MediaDownloader.download(url, aeskey)
               filename = result[:filename] || filename
-              file_ref = Clacky::Utils::FileProcessor.process(body: result[:body], filename: filename)
-              files = [{
-                name:         file_ref.name,
-                path:         file_ref.original_path,
-                preview_path: file_ref.preview_path,
-                type:         file_ref.type.to_s,
-                mime_type:    "application/octet-stream"
-              }]
+              saved = Clacky::Utils::FileProcessor.save(body: result[:body], filename: filename)
+              files = [saved]
             end
 
             event = {