apialerts 1.0.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca74872675531d5f22e9ae62c2298a760e7c2ada9c33f8f00b9de4109dd7c0f7
+  data.tar.gz: 7bd96af6093b6b5f2e74bba74f1e887cec60a9c728edfcdf46751e7d24a0e811
+SHA512:
+  metadata.gz: 1957c3f75ac52982b322501b35082783c5be24046d336f68724a99d269e9cba1a66ced602927c180642303632a32cc99d79d9ca9e03025fa4c5ee2a29f9ff10d
+  data.tar.gz: 0ab4395dd514436e03c6e9c35bdbcfb4e8f77a636b6449974617df69b106c905d45434d5f2dc1ee3da517dee0553b966255e6c6a5d3768d0dca22731e8102385

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 API Alerts
+
+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,106 @@
+# API Alerts • Ruby Client
+
+[![Gem](https://img.shields.io/gem/v/apialerts)](https://rubygems.org/gems/apialerts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[RubyGems](https://rubygems.org/gems/apialerts) • [GitHub](https://github.com/apialerts/apialerts-ruby) • [API Alerts](https://apialerts.com)
+
+Effortless project notifications. Send once, deliver everywhere.
+
+## Installation
+
+```ruby
+gem 'apialerts'
+```
+
+Or install directly:
+
+```bash
+gem install apialerts
+```
+
+## Quick Start
+
+```ruby
+require 'apialerts'
+
+ApiAlerts.configure('your-api-key')
+ApiAlerts.send(ApiAlerts::Event.new(message: 'Deploy complete'))
+```
+
+## Usage
+
+### Global singleton (recommended)
+
+Call `configure` once at startup, then use `send` / `send_async` anywhere.
+
+```ruby
+require 'apialerts'
+
+ApiAlerts.configure('your-api-key')
+
+# Fire-and-forget - never raises
+ApiAlerts.send(ApiAlerts::Event.new(message: 'Deploy complete'))
+
+# Or get the result back
+result = ApiAlerts.send_async(ApiAlerts::Event.new(message: 'Deploy complete'))
+if result.success?
+  puts "Sent to #{result.workspace} (#{result.channel})"
+else
+  puts "Error: #{result.error}"
+end
+```
+
+### Event fields
+
+Only `message` is required. All other fields are optional.
+
+| Field     | Type     | Required | Description                      |
+|-----------|----------|----------|----------------------------------|
+| `message` | `String` | Yes      | Main notification message        |
+| `channel` | `String` | No       | Target channel name              |
+| `event`   | `String` | No       | Event key for routing            |
+| `title`   | `String` | No       | Short title                      |
+| `tags`    | `Array`  | No       | Categorisation tags              |
+| `link`    | `String` | No       | URL associated with the event (deeplink + CTA) |
+| `data`    | `Hash`   | No       | Arbitrary key-value metadata     |
+
+```ruby
+event = ApiAlerts::Event.new(
+  message: 'Deploy complete',
+  channel: 'releases',
+  event:   'ci.deploy',
+  title:   'Deployed',
+  tags:    ['CI/CD', 'Ruby'],
+  link:    'https://github.com/apialerts/apialerts-ruby/actions',
+  data:    { version: '2.0.0' }
+)
+```
+
+### Send to a different workspace
+
+Pass an optional `api_key:` to override the configured key for a single call.
+
+```ruby
+ApiAlerts.send(event, api_key: 'other-workspace-key')
+
+result = ApiAlerts.send_async(event, api_key: 'other-workspace-key')
+```
+
+### SendResult fields
+
+`send_async` always returns a `SendResult` - it never raises.
+
+| Field       | Type      | Description                                    |
+|-------------|-----------|------------------------------------------------|
+| `success?`  | `Boolean` | Whether the event was delivered successfully   |
+| `workspace` | `String`  | Workspace the event was delivered to           |
+| `channel`   | `String`  | Channel the event was delivered to             |
+| `warnings`  | `Array`   | Non-fatal warnings returned by the API         |
+| `error`     | `String`  | Error message when `success?` is false         |
+
+## Links
+
+- [Documentation](https://apialerts.com/docs)
+- [Sign up](https://apialerts.com)
+- [GitHub Issues](https://github.com/apialerts/apialerts-ruby/issues)

data/lib/apialerts/client.rb

@@ -0,0 +1,111 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'event'
+require_relative 'result'
+require_relative 'version'
+
+module ApiAlerts
+  # Instance-based API Alerts client.
+  #
+  # Use the module-level methods (ApiAlerts.configure / ApiAlerts.send_async)
+  # for a convenient global singleton, or construct this class directly when
+  # you need multiple clients or full lifecycle control.
+  class Client
+    def initialize(api_key, debug: false)
+      @api_key             = api_key
+      @debug               = debug
+      @integration         = INTEGRATION_NAME
+      @integration_version = VERSION
+      @base_url            = API_URL
+    end
+
+    # Override the integration name, version, and base URL.
+    #
+    # Used by official integrations and in tests to redirect requests to a
+    # mock server.
+    def set_overrides(integration, version, base_url)
+      @integration         = integration
+      @integration_version = version
+      @base_url            = base_url
+      self
+    end
+
+    # Send an event - fire-and-forget. Never raises.
+    # Critical errors (not configured, missing key, empty message) are always
+    # logged to stderr. HTTP errors and success are only logged when debug is
+    # enabled.
+    def send(event, api_key: nil)
+      key = api_key.nil? || api_key.empty? ? @api_key : api_key
+      if key.nil? || key.empty?
+        warn 'x (apialerts.com) Error: api key is missing'
+        return
+      end
+      if event.message.nil? || event.message.empty?
+        warn 'x (apialerts.com) Error: message is required'
+        return
+      end
+
+      result = post(event, api_key: key)
+      return unless @debug
+
+      if result.success?
+        warn "✓ (apialerts.com) Alert sent to #{result.workspace} (#{result.channel})"
+        result.warnings.each { |w| warn "! (apialerts.com) Warning: #{w}" }
+      else
+        warn "x (apialerts.com) Error: #{result.error}"
+      end
+    end
+
+    # Send an event and return a SendResult. Never raises.
+    # Check result.success? to determine whether delivery succeeded.
+    def send_async(event, api_key: nil)
+      key = api_key.nil? || api_key.empty? ? @api_key : api_key
+      return SendResult.new(success: false, error: 'api key is missing') if key.nil? || key.empty?
+      return SendResult.new(success: false, error: 'message is required') if event.message.nil? || event.message.empty?
+
+      post(event, api_key: key)
+    end
+
+    private
+
+    def post(event, api_key: @api_key)
+      uri  = URI.parse(@base_url)
+      http = Net::HTTP.new(uri.host, uri.port).tap do |h|
+        h.use_ssl      = uri.scheme == 'https'
+        h.open_timeout = TIMEOUT_SECONDS
+        h.read_timeout = TIMEOUT_SECONDS
+      end
+      request = Net::HTTP::Post.new(uri.path.empty? ? '/' : uri.path)
+
+      request['Authorization'] = "Bearer #{api_key}"
+      request['Content-Type']  = 'application/json'
+      request['X-Integration'] = @integration
+      request['X-Version']     = @integration_version
+      request.body             = JSON.generate(event.to_h)
+
+      response = http.request(request)
+
+      case response.code.to_i
+      when 200
+        body = JSON.parse(response.body)
+        workspace = body['workspace']
+        channel   = body['channel']
+        return SendResult.new(success: false, error: 'invalid response from server') unless workspace && channel
+
+        warnings = body['warnings'] || []
+        SendResult.new(success: true, workspace: workspace, channel: channel, warnings: warnings)
+      when 400 then SendResult.new(success: false, error: 'bad request')
+      when 401 then SendResult.new(success: false, error: 'unauthorized, check your api key')
+      when 403 then SendResult.new(success: false, error: 'forbidden')
+      when 429 then SendResult.new(success: false, error: 'rate limit exceeded')
+      else          SendResult.new(success: false, error: "unexpected status: #{response.code.to_i}")
+      end
+    rescue JSON::ParserError
+      SendResult.new(success: false, error: 'invalid response from server')
+    rescue StandardError => e
+      SendResult.new(success: false, error: e.message)
+    end
+  end
+end

data/lib/apialerts/event.rb

@@ -0,0 +1,59 @@
+module ApiAlerts
+  # An event to send to the API Alerts platform.
+  #
+  # Only +message+ is required. All other fields are optional and omitted
+  # from the JSON payload when nil.
+  #
+  #   # Minimal
+  #   event = ApiAlerts::Event.new(message: 'Deploy complete')
+  #
+  #   # Full
+  #   event = ApiAlerts::Event.new(
+  #     message: 'Deploy complete',
+  #     channel: 'releases',
+  #     event:   'ci.deploy.success',
+  #     title:   'Deployed',
+  #     tags:    ['CI/CD', 'Ruby'],
+  #     link:    'https://github.com/apialerts/apialerts-ruby/actions',
+  #     data:    { commit: 'a1b2c3d' }
+  #   )
+  class Event
+    # Human-readable notification text. Required. Appears on the push lock screen.
+    attr_reader :message
+    # Workspace channel the push fires on. Defaults to the workspace default when omitted.
+    attr_reader :channel
+    # What kind of thing happened. Optional but recommended. Dotted notation
+    # ("ci.deploy.success", "payment.failed") so routing rules can match with
+    # wildcards ("ci.*", "*.failed").
+    attr_reader :event
+    # Short headline some destinations render separately from the body.
+    attr_reader :title
+    # Categorisation tags for filtering and search.
+    attr_reader :tags
+    # URL attached to the notification. Tapping the push opens it.
+    attr_reader :link
+    # Arbitrary key-value metadata. Available to non-push destinations for templating.
+    attr_reader :data
+
+    def initialize(message:, channel: nil, event: nil, title: nil, tags: nil, link: nil, data: nil)
+      @message = message
+      @channel = channel
+      @event   = event
+      @title   = title
+      @tags    = tags
+      @link    = link
+      @data    = data
+    end
+
+    def to_h
+      h = { message: message }
+      h[:channel] = channel unless channel.nil?
+      h[:event]   = event   unless event.nil?
+      h[:title]   = title   unless title.nil?
+      h[:tags]    = tags    unless tags.nil?
+      h[:link]    = link    unless link.nil?
+      h[:data]    = data    unless data.nil?
+      h
+    end
+  end
+end

data/lib/apialerts/result.rb

@@ -0,0 +1,18 @@
+module ApiAlerts
+  # The result of an event delivery attempt.
+  class SendResult
+    attr_reader :success, :workspace, :channel, :warnings, :error
+
+    def initialize(success:, workspace: nil, channel: nil, warnings: [], error: nil)
+      @success   = success
+      @workspace = workspace
+      @channel   = channel
+      @warnings  = warnings
+      @error     = error
+    end
+
+    def success?
+      @success
+    end
+  end
+end

data/lib/apialerts/version.rb

@@ -0,0 +1,6 @@
+module ApiAlerts
+  VERSION = '1.0.0.alpha.1'.freeze
+  INTEGRATION_NAME = 'ruby'.freeze
+  API_URL = 'https://api.apialerts.com/event'.freeze
+  TIMEOUT_SECONDS = 30
+end

data/lib/apialerts.rb

@@ -0,0 +1,46 @@
+require_relative 'apialerts/version'
+require_relative 'apialerts/event'
+require_relative 'apialerts/result'
+require_relative 'apialerts/client'
+
+# Global singleton facade for the API Alerts client.
+#
+#   ApiAlerts.configure('your-api-key')
+#   ApiAlerts.send(ApiAlerts::Event.new(message: 'Deploy complete'))
+module ApiAlerts
+  class << self
+    # Initialise the global client. Subsequent calls are no-ops.
+    def configure(api_key, debug: false)
+      @client ||= Client.new(api_key, debug: debug)
+    end
+
+    # Override the integration name, version, and base URL on the global client.
+    # No-op if configure has not been called yet.
+    def set_overrides(integration, version, base_url)
+      @client&.set_overrides(integration, version, base_url)
+    end
+
+    # Send an event - fire-and-forget. Never raises.
+    # Silently does nothing if the global client has not been initialised.
+    def send(event, api_key: nil)
+      unless @client
+        warn 'x (apialerts.com) Error: client not configured'
+        return
+      end
+      @client.send(event, api_key: api_key)
+    end
+
+    # Send an event and return a SendResult. Never raises.
+    # Returns SendResult with success: false if not configured.
+    def send_async(event, api_key: nil)
+      return SendResult.new(success: false, error: 'client not configured') unless @client
+
+      @client.send_async(event, api_key: api_key)
+    end
+
+    # @private - for use in tests only
+    def reset!
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: apialerts
+version: !ruby/object:Gem::Version
+  version: 1.0.0.alpha.1
+platform: ruby
+authors:
+- API Alerts
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !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'
+description: Effortless project notifications. Send once, deliver everywhere.
+email:
+- support@apialerts.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/apialerts.rb
+- lib/apialerts/client.rb
+- lib/apialerts/event.rb
+- lib/apialerts/result.rb
+- lib/apialerts/version.rb
+homepage: https://apialerts.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/apialerts/apialerts-ruby
+  bug_tracker_uri: https://github.com/apialerts/apialerts-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the API Alerts notification platform
+test_files: []