feishu_notifier 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45fef57b6d5c69eed564a4625e58fa3a60c38808ec9de9526a5a0bc6e624ba1a
+  data.tar.gz: 2ed23eaceaf3595525b136070210c607e828ce1b6a2bbe6d74ba4fd17704672f
+SHA512:
+  metadata.gz: 80367f0000f9db8c102d07f7393b83e4b93a3b2176d1c545801c4c4bc291b1c158545fd16056b3e92eecb4a2fe2b0073e320aa56ed337008aa7c2261086e46bf
+  data.tar.gz: 6a0c3b51e0603ebff1c78c0e45f9dad169a12f0f669334ad46e4708860cca45ce04abbf8b1d70c651bf7932d2327432ceb12cee81873a59723831ab0673319d6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Yang
+
+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,178 @@
+# Feishu Notifier
+
+Ruby gem and CLI for sending Feishu app notifications. It supports plain text messages, custom interactive cards, existing CardKit card IDs, and existing card template IDs.
+
+Repository: https://github.com/Youngv/feishu-notifier-ruby
+
+## Features
+
+- Sends messages through Feishu `im/v1/messages`.
+- Uses `receive_id_type=user_id`.
+- Reads app credentials from `.env`, environment variables, or `--config`.
+- Provides built-in card levels: `info`, `debug`, and `error`.
+- Can be used as a CLI or as a Ruby library.
+
+## Requirements
+
+- Ruby 3.2 or newer.
+- This project is developed with Ruby 3.4.7.
+- A Feishu app with permission to send IM messages.
+- A reachable Feishu recipient `user_id`.
+
+## Configuration
+
+Create a `.env` file:
+
+```bash
+cp .env.example .env
+```
+
+Required variables:
+
+```bash
+FEISHU_APP_ID=cli_xxx
+FEISHU_APP_SECRET=your_app_secret
+FEISHU_USER_ID=your_user_id
+FEISHU_BASE_URL=https://open.feishu.cn
+```
+
+The local `.env` file is ignored by git. Do not commit real app secrets.
+
+## Development Setup
+
+```bash
+cd /root/feishu-notifier-ruby
+source /usr/local/rvm/scripts/rvm
+rvm use ruby-3.4.7
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rake test
+```
+
+## CLI Usage
+
+Run from this repository:
+
+```bash
+bin/feishu-notifier --level info --text "Hello from Ruby"
+```
+
+Run after installing the gem:
+
+```bash
+feishu-notifier --config /root/feishu-notifier-ruby/.env --level error --text "Something failed"
+```
+
+If the target project has its own `.env`, run `feishu-notifier` from that directory without `--config`.
+
+### Plain Text
+
+```bash
+bin/feishu-notifier --text "Hello from Ruby"
+```
+
+### Custom Cards
+
+The `--level` option sends a custom interactive card. Available levels:
+
+- `info`: blue header, default title `Info`
+- `debug`: grey header, default title `Debug`
+- `error`: red header, default title `Error`
+
+```bash
+bin/feishu-notifier --level info --text "Normal notification"
+bin/feishu-notifier --level debug --text "Debug details"
+bin/feishu-notifier --level error --text "Something failed"
+```
+
+Override the card title:
+
+```bash
+bin/feishu-notifier --level error --title "Deploy failed" --text "Rollback required"
+```
+
+### Existing Cards and Templates
+
+Send an existing CardKit card by card ID:
+
+```bash
+bin/feishu-notifier --card-id CARD_ID
+```
+
+Send an existing card template by template ID:
+
+```bash
+bin/feishu-notifier --template-id TEMPLATE_ID
+```
+
+### Recipient Override
+
+```bash
+bin/feishu-notifier --user-id your_user_id --level info --text "Hello"
+```
+
+### Dry Run
+
+Use `--dry-run` to print the request summary without calling Feishu:
+
+```bash
+bin/feishu-notifier --dry-run --level error --title "Gem check" --text "Installed executable works"
+```
+
+## Ruby Library Usage
+
+Add the gem to another Ruby project, or install the local gem first.
+
+```ruby
+require "feishu_notifier"
+
+FeishuNotifier::EnvFile.load("/root/feishu-notifier-ruby/.env")
+config = FeishuNotifier::Config.from_env
+client = FeishuNotifier::Client.new(config: config)
+
+card = FeishuNotifier::Card.custom(
+  level: "error",
+  title: "Task failed",
+  text: "Check logs"
+)
+
+client.send_card(card)
+```
+
+Send plain text:
+
+```ruby
+client.send_text("Hello from Ruby")
+```
+
+## Build and Install
+
+Build the gem:
+
+```bash
+gem build feishu_notifier.gemspec
+```
+
+Install the generated gem:
+
+```bash
+gem install ./feishu_notifier-0.1.1.gem
+```
+
+## Project Layout
+
+- `bin/feishu-notifier`: CLI executable.
+- `lib/feishu_notifier/client.rb`: Feishu API client.
+- `lib/feishu_notifier/card.rb`: Card content builders.
+- `lib/feishu_notifier/config.rb`: Environment-based configuration.
+- `lib/feishu_notifier/env_file.rb`: Minimal `.env` loader.
+- `lib/feishu_notifier/version.rb`: Gem version.
+- `test/`: Minitest coverage.
+
+## Permissions
+
+The Feishu app must be enabled in the target tenant and have permission to send IM messages. The recipient must be reachable by `user_id`.

data/bin/feishu-notifier

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+
+require "json"
+require "optparse"
+
+begin
+  require "feishu_notifier"
+rescue LoadError
+  require_relative "../lib/feishu_notifier"
+end
+
+options = {
+  config: ENV.fetch("FEISHU_CONFIG", ".env"),
+  dry_run: false,
+  message_type: nil,
+  level: "info"
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: feishu-notifier --text MESSAGE | --card-id CARD_ID | --template-id TEMPLATE_ID [options]"
+
+  opts.on("-t", "--text MESSAGE", "Text message to send") { |value| options[:text] = value }
+  opts.on("--card", "Send an interactive card built from --text") { options[:message_type] = "interactive" }
+  opts.on("--level LEVEL", "Card level: info, debug, or error") do |value|
+    options[:level] = value
+    options[:message_type] = "interactive"
+  end
+  opts.on("--card-id CARD_ID", "Send an existing Feishu CardKit card") do |value|
+    options[:card_id] = value
+    options[:message_type] = "interactive"
+  end
+  opts.on("--template-id TEMPLATE_ID", "Send an existing Feishu card template") do |value|
+    options[:template_id] = value
+    options[:message_type] = "interactive"
+  end
+  opts.on("--title TITLE", "Card title when using --card") { |value| options[:title] = value }
+  opts.on("-u", "--user-id USER_ID", "Override FEISHU_USER_ID") { |value| options[:user_id] = value }
+  opts.on("-c", "--config PATH", "Load environment variables from PATH") { |value| options[:config] = value }
+  opts.on("--dry-run", "Print request summary without calling Feishu") { options[:dry_run] = true }
+  opts.on("-h", "--help", "Print help") do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+
+card_id = options[:card_id].to_s.strip
+template_id = options[:template_id].to_s.strip
+message = options[:text].to_s.strip
+options[:message_type] ||= "text"
+abort parser.to_s if card_id.empty? && template_id.empty? && message.empty?
+
+FeishuNotifier::EnvFile.load(options[:config])
+ENV["FEISHU_USER_ID"] = options[:user_id] if options[:user_id]
+
+config = FeishuNotifier::Config.from_env
+content = if !card_id.empty?
+            FeishuNotifier::Card.by_id(card_id)
+          elsif !template_id.empty?
+            FeishuNotifier::Card.template(template_id)
+          elsif options[:message_type] == "interactive"
+            FeishuNotifier::Card.custom(title: options[:title], text: message, level: options[:level])
+          else
+            { text: message }
+          end
+
+if options[:dry_run]
+  puts JSON.pretty_generate(
+    {
+      app_id: config.app_id,
+      user_id: config.user_id,
+      endpoint: "#{config.base_url}/open-apis/im/v1/messages?receive_id_type=user_id",
+      msg_type: options[:message_type],
+      content: content
+    }
+  )
+  exit
+end
+
+client = FeishuNotifier::Client.new(config: config)
+if options[:message_type] == "interactive"
+  client.send_card(content)
+else
+  client.send_text(message)
+end
+puts "#{options[:message_type]} message sent to #{config.user_id}"

data/lib/feishu_notifier/card.rb

@@ -0,0 +1,71 @@
+module FeishuNotifier
+  module Card
+    LEVELS = {
+      "info" => {
+        title: "Info",
+        template: "blue"
+      },
+      "debug" => {
+        title: "Debug",
+        template: "grey"
+      },
+      "error" => {
+        title: "Error",
+        template: "red"
+      }
+    }.freeze
+
+    module_function
+
+    def by_id(card_id)
+      {
+        type: "card",
+        data: {
+          card_id: card_id
+        }
+      }
+    end
+
+    def template(template_id, variables: {})
+      {
+        type: "template",
+        data: {
+          template_id: template_id,
+          template_variable: variables
+        }
+      }
+    end
+
+    def custom(title: nil, text:, level: "info")
+      style = LEVELS.fetch(level) do
+        raise ArgumentError, "Unsupported card level: #{level}. Expected one of: #{LEVELS.keys.join(", ")}"
+      end
+
+      {
+        config: {
+          wide_screen_mode: true
+        },
+        header: {
+          template: style.fetch(:template),
+          title: {
+            tag: "plain_text",
+            content: title.to_s.empty? ? style.fetch(:title) : title
+          }
+        },
+        elements: [
+          {
+            tag: "div",
+            text: {
+              tag: "lark_md",
+              content: text
+            }
+          }
+        ]
+      }
+    end
+
+    def simple(title:, text:)
+      custom(title: title, text: text, level: "info")
+    end
+  end
+end

data/lib/feishu_notifier/client.rb

@@ -0,0 +1,88 @@
+require "json"
+require "net/http"
+require "uri"
+
+module FeishuNotifier
+  class Client
+    TOKEN_PATH = "/open-apis/auth/v3/tenant_access_token/internal".freeze
+    MESSAGE_PATH = "/open-apis/im/v1/messages".freeze
+
+    def initialize(config:, http: Net::HTTP)
+      @config = config
+      @http = http
+    end
+
+    def send_text(text, user_id: @config.user_id)
+      send_message(
+        user_id: user_id,
+        msg_type: "text",
+        content: { text: text }
+      )
+    end
+
+    def send_card(card, user_id: @config.user_id)
+      send_message(
+        user_id: user_id,
+        msg_type: "interactive",
+        content: card
+      )
+    end
+
+    def tenant_access_token
+      response = post_json(
+        TOKEN_PATH,
+        {
+          app_id: @config.app_id,
+          app_secret: @config.app_secret
+        }
+      )
+
+      token = response["tenant_access_token"].to_s
+      raise ApiError, "Feishu token response did not include tenant_access_token" if token.empty?
+
+      token
+    end
+
+    private
+
+    def send_message(user_id:, msg_type:, content:)
+      token = tenant_access_token
+      post_json(
+        "#{MESSAGE_PATH}?receive_id_type=user_id",
+        {
+          receive_id: user_id,
+          msg_type: msg_type,
+          content: JSON.generate(content)
+        },
+        headers: { "Authorization" => "Bearer #{token}" }
+      )
+    end
+
+    def post_json(path, payload, headers: {})
+      uri = URI.join(@config.base_url, path)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json; charset=utf-8"
+      headers.each { |key, value| request[key] = value }
+      request.body = JSON.generate(payload)
+
+      response = @http.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |connection|
+        connection.request(request)
+      end
+
+      parse_response(response)
+    end
+
+    def parse_response(response)
+      body = JSON.parse(response.body)
+      code = body.fetch("code", 0)
+      return body if response.is_a?(Net::HTTPSuccess) && code.to_i.zero?
+
+      message = body["msg"] || body["message"] || response.message
+      raise ApiError, "Feishu API error: HTTP #{response.code}, code #{code}, #{message}"
+    rescue JSON::ParserError
+      raise ApiError, "Feishu API returned non-JSON response: HTTP #{response.code}"
+    end
+  end
+
+  class ApiError < StandardError; end
+end

data/lib/feishu_notifier/config.rb

@@ -0,0 +1,21 @@
+module FeishuNotifier
+  Config = Data.define(:app_id, :app_secret, :user_id, :base_url) do
+    DEFAULT_BASE_URL = "https://open.feishu.cn".freeze
+
+    def self.from_env(env = ENV)
+      new(
+        app_id: fetch_required(env, "FEISHU_APP_ID"),
+        app_secret: fetch_required(env, "FEISHU_APP_SECRET"),
+        user_id: fetch_required(env, "FEISHU_USER_ID"),
+        base_url: env.fetch("FEISHU_BASE_URL", DEFAULT_BASE_URL)
+      )
+    end
+
+    def self.fetch_required(env, key)
+      value = env[key].to_s.strip
+      raise ArgumentError, "Missing required environment variable: #{key}" if value.empty?
+
+      value
+    end
+  end
+end

data/lib/feishu_notifier/env_file.rb

@@ -0,0 +1,28 @@
+module FeishuNotifier
+  module EnvFile
+    module_function
+
+    def load(path)
+      return unless File.file?(path)
+
+      File.readlines(path, chomp: true).each do |line|
+        stripped = line.strip
+        next if stripped.empty? || stripped.start_with?("#")
+
+        key, value = stripped.split("=", 2)
+        next if key.nil? || value.nil? || key.empty?
+
+        ENV[key] = unquote(value.strip)
+      end
+    end
+
+    def unquote(value)
+      if (value.start_with?('"') && value.end_with?('"')) ||
+         (value.start_with?("'") && value.end_with?("'"))
+        value[1...-1]
+      else
+        value
+      end
+    end
+  end
+end

data/lib/feishu_notifier/version.rb

@@ -0,0 +1,3 @@
+module FeishuNotifier
+  VERSION = "0.1.1"
+end

data/lib/feishu_notifier.rb

@@ -0,0 +1,5 @@
+require_relative "feishu_notifier/version"
+require_relative "feishu_notifier/card"
+require_relative "feishu_notifier/client"
+require_relative "feishu_notifier/config"
+require_relative "feishu_notifier/env_file"

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: feishu_notifier
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Victor Yang
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: A small Ruby client and CLI for sending Feishu app notifications with
+  text and custom card levels.
+executables:
+- feishu-notifier
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/feishu-notifier
+- lib/feishu_notifier.rb
+- lib/feishu_notifier/card.rb
+- lib/feishu_notifier/client.rb
+- lib/feishu_notifier/config.rb
+- lib/feishu_notifier/env_file.rb
+- lib/feishu_notifier/version.rb
+homepage: https://github.com/Youngv/feishu-notifier-ruby
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Send Feishu text and card notifications from Ruby.
+test_files: []