trigv 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db623af95b6d63ba76f6aadc73ad1fe6783aae9d60a7af01e15be026aa7840a3
+  data.tar.gz: 72082f5c52bf1e92d207932e646e7478cbc69ff9db4dd62fa348518debdc6e3c
+SHA512:
+  metadata.gz: bd42a53191af4b90172976e1c0adbb1c0b8a0499f4eae0781676df2793bab349b837efe189fa2d35773893dac7516658c725076ceec27ee56e2c7acfc99e992f
+  data.tar.gz: 942bb3b48a9f4ddd77b6544f0a7d50a442a19c06135da3ff5e4a87178f88014b5c1bc3989444f2dca8d3161cb5d72e431447eedaca0141e47c2e0ef9effa2b7a

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-07-07
+
+### Added
+
+- Initial stable release of the `trigv` gem
+- `Trigv::Client` with `#send_event` and `#verify_connection`
+- Net::HTTP client, strict field validation, WebMock tests

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trigv
+
+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,168 @@
+# trigv
+
+Official Trigv SDK for Ruby. Send notification events from scripts, servers, and CI pipelines.
+
+## What Trigv is
+
+Trigv delivers developer notifications to your team's devices. Your backend sends lightweight JSON events; Trigv queues push delivery. Notification title and body are not stored on Trigv servers — metadata only.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'trigv', '~> 0.1'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick start
+
+```ruby
+require 'trigv'
+
+client = Trigv::Client.new(api_key: ENV['TRIGV_API_KEY'])
+
+client.send_event(
+  channel: 'general',
+  title: 'Deploy finished',
+  description: 'Build #42 succeeded in 38s'
+)
+```
+
+## Authentication
+
+Create a workspace API key at [app.trigv.com](https://app.trigv.com). Keys look like `trgv_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
+
+```ruby
+client = Trigv::Client.new(api_key: 'trgv_your_api_key')
+# or set TRIGV_API_KEY in the environment
+```
+
+**Do not** send the API key in the JSON body — use the `Authorization: Bearer` header (handled automatically).
+
+## Sending an event
+
+```ruby
+result = client.send_event(
+  channel: 'general',
+  title: 'Cron job failed',
+  description: 'Nightly backup did not complete',
+  level: 'error',
+  event_type: 'cron.failed'
+)
+
+puts result.event.public_id
+```
+
+## Event options
+
+| Field | Required | Description |
+|-------|:--------:|-------------|
+| `channel` | Yes | Channel slug (e.g. `general`) |
+| `title` | Yes | Notification title |
+| `description` | No | Body text |
+| `image_url` | No | HTTPS image URL (not stored server-side) |
+| `url` | No | Destination URL for the notification (max 2048 characters; not stored server-side) |
+| `level` | No | `info`, `success`, `warning`, `error` (default: `info`) |
+| `delivery_urgency` | No | `standard` or `time_sensitive` (default: `standard`) |
+| `event_type` | No | Free-form label (e.g. `deploy.completed`) |
+| `idempotency_key` | No | Dedup key per workspace |
+
+## Levels
+
+- `info` — general information (default)
+- `success` — completed successfully
+- `warning` — attention needed
+- `error` — failure or alert
+
+## Delivery urgency
+
+- `standard` — normal notifications (default)
+- `time_sensitive` — iOS Time Sensitive delivery (requires user permission)
+
+## Idempotency
+
+When you set `idempotency_key`, retries with the same key return the existing event (`duplicate: true`, HTTP 200) without billing again.
+
+```ruby
+result = client.send_event(
+  channel: 'deploys',
+  title: 'Production deploy complete',
+  idempotency_key: 'deploy-prod-42'
+)
+
+puts result.duplicate ? 'duplicate' : 'new'
+```
+
+## Error handling
+
+```ruby
+begin
+  client.send_event(channel: 'general', title: 'Hello')
+rescue Trigv::ValidationError => e
+  puts e.errors
+rescue Trigv::NotFoundError
+  puts 'Channel not found'
+rescue Trigv::RateLimitError => e
+  puts e.retryable ? 'Retry later' : 'Monthly limit reached'
+end
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | `TRIGV_API_KEY` env | Workspace API key |
+| `base_url` | `https://api.trigv.com/api` | API base URL |
+| `timeout` | `30` | Request timeout (seconds) |
+| `max_retries` | `2` | Retries for retryable errors |
+
+### Verify connection
+
+```ruby
+connection = client.verify_connection
+puts connection.workspace.name
+```
+
+## Examples
+
+See the [`examples/`](./examples/) directory:
+
+- Basic event
+- Success event
+- Warning event
+- Full event with all optional fields
+- Idempotency example
+- Deploy completed (canonical example)
+- Cron job failed
+- WooCommerce order notification
+- AI agent task completed
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+Tests use WebMock — no live API key required.
+
+## Contributing
+
+Contributions welcome. Please open an issue before large changes.
+
+## Licence
+
+MIT

data/lib/trigv/client.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'retry'
+
+module Trigv
+  Event = Struct.new(
+    :public_id, :event_uuid, :status, :level, :event_type, :target_device_count, :received_at,
+    keyword_init: true
+  )
+
+  SendEventResult = Struct.new(:event, :duplicate, keyword_init: true)
+
+  ConnectionWorkspace = Struct.new(:public_id, :name, keyword_init: true)
+  ConnectionApiKey = Struct.new(:public_id, :name, :prefix, keyword_init: true)
+  ConnectionResult = Struct.new(:workspace, :api_key, keyword_init: true)
+
+  class Client
+    attr_reader :api_key, :base_url, :timeout, :max_retries
+
+    def initialize(
+      api_key: nil,
+      base_url: Validation::DEFAULT_BASE_URL,
+      timeout: Validation::DEFAULT_TIMEOUT,
+      max_retries: Validation::MAX_RETRIES
+    )
+      api_key ||= ENV.fetch('TRIGV_API_KEY', nil)
+      api_key = api_key&.strip
+      raise ValidationError, 'api_key is required (or set TRIGV_API_KEY)' if api_key.nil? || api_key.empty?
+      raise ValidationError, 'max_retries must be zero or greater' if max_retries.negative?
+      raise ValidationError, 'timeout must be greater than zero' if timeout <= 0
+
+      @api_key = api_key
+      @base_url = base_url.to_s.chomp('/')
+      @timeout = timeout
+      @max_retries = max_retries
+    end
+
+    def user_agent
+      "trigv-ruby/#{VERSION}"
+    end
+
+    def send_event(**params)
+      body = Validation.validate_send_event_params(params)
+      has_idempotency = body.key?('idempotency_key')
+
+      request_with_retry(:post, '/v1/events', body, allow_retry: has_idempotency) do |status, parsed, headers|
+        if [200, 202].include?(status) && parsed&.dig('event')
+          event = parse_event(parsed['event'])
+          SendEventResult.new(event: event, duplicate: status == 200)
+        else
+          error_from_response(status, parsed, headers)
+        end
+      end
+    end
+
+    def verify_connection
+      request_with_retry(:get, '/v1/connection', nil, allow_retry: true) do |status, parsed, headers|
+        if status == 200 && parsed&.dig('workspace') && parsed['api_key']
+          parse_connection_result(parsed)
+        else
+          error_from_response(status, parsed, headers)
+        end
+      end
+    end
+
+    private
+
+    def request_with_retry(method, path, body, allow_retry:)
+      last_error = nil
+
+      (0..max_retries).each do |attempt|
+        status, parsed, headers = request_once(method, path, body)
+        return yield(status, parsed, headers)
+      rescue StandardError => e
+        last_error = e
+        raise e unless allow_retry && attempt < max_retries
+        raise e unless retryable_error?(e)
+
+        wait = retry_wait_seconds(e, attempt)
+        sleep([wait, timeout].min)
+      end
+
+      raise last_error
+    end
+
+    def retry_wait_seconds(error, attempt)
+      return error.retry_after_seconds if error.is_a?(RateLimitError) && error.retry_after_seconds
+
+      (0.5 * (2**attempt)) + (rand * 0.25)
+    end
+
+    def retryable_error?(error)
+      case error
+      when ValidationError, AuthenticationError, AuthorizationError, NotFoundError
+        false
+      when RateLimitError
+        error.retryable
+      when ApiError
+        retryable_status?(error.status_code)
+      when NetworkError, TimeoutError
+        true
+      else
+        false
+      end
+    end
+
+    def retryable_status?(status)
+      [429, 502, 503, 504].include?(status)
+    end
+
+    def request_once(method, path, body)
+      uri = build_uri(path)
+      http = build_http(uri)
+      request = build_request(method, uri, body)
+      response = http.request(request)
+      parsed = parse_json(response.body)
+      response_headers = response.each_header.to_h.transform_keys(&:downcase)
+
+      [response.code.to_i, parsed, response_headers]
+    rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error
+      raise TimeoutError
+    rescue ValidationError, AuthenticationError, AuthorizationError, NotFoundError,
+           RateLimitError, ApiError, TimeoutError
+      raise
+    rescue StandardError => e
+      raise NetworkError.new(e.message, e)
+    end
+
+    def build_uri(path)
+      URI("#{@base_url}#{path}")
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http
+    end
+
+    def build_request(method, uri, body)
+      request =
+        case method
+        when :get then Net::HTTP::Get.new(uri)
+        when :post then Net::HTTP::Post.new(uri)
+        else
+          raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+      request['Accept'] = 'application/json'
+      request['Authorization'] = "Bearer #{@api_key}"
+      request['User-Agent'] = user_agent
+
+      if body
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def parse_json(text)
+      return nil if text.nil? || text.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def parse_event(data)
+      Event.new(
+        public_id: data['public_id'],
+        event_uuid: data['event_uuid'],
+        status: data['status'],
+        level: data['level'],
+        event_type: data['event_type'],
+        target_device_count: data['target_device_count'],
+        received_at: data['received_at']
+      )
+    end
+
+    def parse_connection_result(parsed)
+      workspace_data = parsed['workspace']
+      api_key_data = parsed['api_key']
+
+      unless workspace_data.is_a?(Hash) && api_key_data.is_a?(Hash)
+        raise ValidationError.new('Invalid connection response payload', {})
+      end
+
+      required_workspace = %w[public_id name]
+      required_api_key = %w[public_id name prefix]
+      missing_workspace = required_workspace.reject { |key| workspace_data[key].is_a?(String) && !workspace_data[key].empty? }
+      missing_api_key = required_api_key.reject { |key| api_key_data[key].is_a?(String) && !api_key_data[key].empty? }
+
+      unless missing_workspace.empty? && missing_api_key.empty?
+        raise ValidationError.new('Invalid connection response payload', {})
+      end
+
+      ConnectionResult.new(
+        workspace: ConnectionWorkspace.new(**symbolize_keys(workspace_data)),
+        api_key: ConnectionApiKey.new(**symbolize_keys(api_key_data))
+      )
+    rescue ArgumentError, KeyError, TypeError
+      raise ValidationError.new('Invalid connection response payload', {})
+    end
+
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
+    end
+
+    def error_from_response(status, body, headers = {})
+      message = body&.fetch('message', nil) || "Trigv API returned HTTP #{status}"
+
+      case status
+      when 401
+        raise AuthenticationError, message
+      when 403
+        raise AuthorizationError, message
+      when 404
+        raise NotFoundError, message
+      when 422
+        raise ValidationError.new(message, body&.fetch('errors', {}) || {})
+      when 429
+        retry_after = Retry.parse_retry_after(headers['retry-after'])
+        raise RateLimitError.new(
+          message,
+          retryable: !Errors.monthly_limit_message?(message),
+          retry_after_seconds: retry_after
+        )
+      else
+        raise ApiError.new(message, status, body)
+      end
+    end
+  end
+end

data/lib/trigv/errors.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Trigv
+  class Error < StandardError
+    def initialize(message = nil)
+      super
+    end
+  end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message, errors = {})
+      super(message)
+      @errors = errors
+    end
+  end
+
+  class AuthenticationError < Error
+    attr_reader :status_code
+
+    def initialize(message)
+      super
+      @status_code = 401
+    end
+  end
+
+  class AuthorizationError < Error
+    attr_reader :status_code
+
+    def initialize(message)
+      super
+      @status_code = 403
+    end
+  end
+
+  class NotFoundError < Error
+    attr_reader :status_code
+
+    def initialize(message)
+      super
+      @status_code = 404
+    end
+  end
+
+  class RateLimitError < Error
+    attr_reader :status_code, :retryable, :retry_after_seconds
+
+    def initialize(message, retryable: true, retry_after_seconds: nil)
+      super(message)
+      @status_code = 429
+      @retryable = retryable
+      @retry_after_seconds = retry_after_seconds
+    end
+  end
+
+  class ApiError < Error
+    attr_reader :status_code, :body
+
+    def initialize(message, status_code, body = nil)
+      super(message)
+      @status_code = status_code
+      @body = body
+    end
+  end
+
+  class NetworkError < Error
+    attr_reader :cause
+
+    def initialize(message, cause = nil)
+      super
+      @cause = cause
+    end
+  end
+
+  class TimeoutError < Error
+    def initialize(message = 'Request timed out')
+      super
+    end
+  end
+
+  module Errors
+    module_function
+
+    def monthly_limit_message?(message)
+      message.include?('Monthly event limit')
+    end
+  end
+end

data/lib/trigv/retry.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Trigv
+  module Retry
+    module_function
+
+    def parse_retry_after(value, now = Time.now)
+      return nil if value.nil? || value.strip.empty?
+
+      trimmed = value.strip
+
+      if trimmed.match?(/\A\d+\z/)
+        seconds = trimmed.to_i
+        return nil if seconds.negative?
+
+        return seconds.to_f
+      end
+
+      retry_at = Time.httpdate(trimmed)
+      wait = retry_at - now
+      wait.negative? ? nil : wait
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/trigv/validation.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Trigv
+  module Validation
+    DEFAULT_BASE_URL = 'https://api.trigv.com/api'
+    DEFAULT_TIMEOUT = 30
+    MAX_RETRIES = 2
+
+    LEVELS = %w[info success warning error].freeze
+    DELIVERY_URGENCIES = %w[standard time_sensitive].freeze
+
+    FIELD_MAX_LENGTHS = {
+      channel: 120,
+      title: 255,
+      description: 1000,
+      image_url: 2048,
+      url: 2048,
+      event_type: 120,
+      idempotency_key: 190
+    }.freeze
+
+    PROHIBITED_FIELDS = %w[api_key icon].freeze
+
+    ALLOWED_EVENT_KEYS = %i[
+      channel title description image_url url level delivery_urgency event_type idempotency_key
+    ].freeze
+
+    module_function
+
+    def validate_send_event_params(params)
+      params = params.transform_keys(&:to_sym)
+
+      unknown = params.keys - ALLOWED_EVENT_KEYS
+      unless unknown.empty?
+        field = unknown.first.to_s
+        raise ValidationError.new("Unknown field \"#{field}\"", { field => ["Unknown field \"#{field}\""] })
+      end
+
+      PROHIBITED_FIELDS.each do |prohibited|
+        next unless params.key?(prohibited.to_sym)
+
+        raise ValidationError.new(
+          "Field \"#{prohibited}\" is not allowed",
+          { prohibited => ["The #{prohibited} field is prohibited"] }
+        )
+      end
+
+      channel = trim(params[:channel])
+      title = trim(params[:title])
+
+      raise ValidationError.new('channel is required', { channel: ['channel is required'] }) if channel.nil?
+      raise ValidationError.new('title is required', { title: ['title is required'] }) if title.nil?
+
+      assert_max_length('channel', channel, FIELD_MAX_LENGTHS[:channel])
+      assert_max_length('title', title, FIELD_MAX_LENGTHS[:title])
+
+      body = { 'channel' => channel, 'title' => title }
+
+      description = trim(params[:description])
+      if description
+        assert_max_length('description', description, FIELD_MAX_LENGTHS[:description])
+        body['description'] = description
+      end
+
+      image_url = trim(params[:image_url])
+      if image_url
+        assert_max_length('image_url', image_url, FIELD_MAX_LENGTHS[:image_url])
+        body['image_url'] = image_url
+      end
+
+      url = trim(params[:url])
+      if url
+        assert_max_length('url', url, FIELD_MAX_LENGTHS[:url])
+        body['url'] = url
+      end
+
+      level = trim(params[:level])
+      if level
+        assert_enum('level', level, LEVELS)
+        body['level'] = level
+      end
+
+      delivery_urgency = trim(params[:delivery_urgency])
+      if delivery_urgency
+        assert_enum('delivery_urgency', delivery_urgency, DELIVERY_URGENCIES)
+        body['delivery_urgency'] = delivery_urgency
+      end
+
+      event_type = trim(params[:event_type])
+      if event_type
+        assert_max_length('event_type', event_type, FIELD_MAX_LENGTHS[:event_type])
+        body['event_type'] = event_type
+      end
+
+      idempotency_key = trim(params[:idempotency_key])
+      if idempotency_key
+        assert_max_length('idempotency_key', idempotency_key, FIELD_MAX_LENGTHS[:idempotency_key])
+        body['idempotency_key'] = idempotency_key
+      end
+
+      body
+    end
+
+    def trim(value)
+      return nil if value.nil?
+
+      trimmed = value.to_s.strip
+      trimmed.empty? ? nil : trimmed
+    end
+
+    def assert_max_length(field, value, max)
+      return if value.length <= max
+
+      message = "#{field} must be at most #{max} characters"
+      raise ValidationError.new(message, { field => [message] })
+    end
+
+    def assert_enum(field, value, allowed)
+      return if allowed.include?(value)
+
+      message = "#{field} must be one of: #{allowed.join(', ')}"
+      raise ValidationError.new(message, { field => [message] })
+    end
+  end
+end

data/lib/trigv/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Trigv
+  VERSION = '1.0.0'
+end

data/lib/trigv.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'trigv/version'
+require 'trigv/errors'
+require 'trigv/validation'
+require 'trigv/client'
+
+module Trigv
+  DEFAULT_BASE_URL = Validation::DEFAULT_BASE_URL
+  MAX_RETRIES = Validation::MAX_RETRIES
+  LEVELS = Validation::LEVELS
+  DELIVERY_URGENCIES = Validation::DELIVERY_URGENCIES
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: trigv
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Trigv
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Thin HTTP client for the Trigv workspace ingest API (events and connection
+  verification).
+email:
+- hello@trigv.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/trigv.rb
+- lib/trigv/client.rb
+- lib/trigv/errors.rb
+- lib/trigv/retry.rb
+- lib/trigv/validation.rb
+- lib/trigv/version.rb
+homepage: https://github.com/Trigv/trigv-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Trigv/trigv-ruby
+  source_code_uri: https://github.com/Trigv/trigv-ruby
+  rubygems_mfa_required: 'true'
+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.11
+specification_version: 4
+summary: Official Trigv SDK for Ruby — send notification events to your workspace
+test_files: []