trigv 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db623af95b6d63ba76f6aadc73ad1fe6783aae9d60a7af01e15be026aa7840a3
-  data.tar.gz: 72082f5c52bf1e92d207932e646e7478cbc69ff9db4dd62fa348518debdc6e3c
+  metadata.gz: bec937b624e4c89520252f25849322469e32f51a74dadb4fe98d5aff5bce3756
+  data.tar.gz: 0cd521c1fffedd723fc607e23a865749a41e9c167f4e7804e867b48fb0d52427
 SHA512:
-  metadata.gz: bd42a53191af4b90172976e1c0adbb1c0b8a0499f4eae0781676df2793bab349b837efe189fa2d35773893dac7516658c725076ceec27ee56e2c7acfc99e992f
-  data.tar.gz: 942bb3b48a9f4ddd77b6544f0a7d50a442a19c06135da3ff5e4a87178f88014b5c1bc3989444f2dca8d3161cb5d72e431447eedaca0141e47c2e0ef9effa2b7a
+  metadata.gz: 5c48be29cd4ca018bc3a475ddd7113fc43558e0629dbd1a3088898f54f737c61a356eff543654ad9917e4b9376cf35bedf2c2d9e95f3018172a752a8a72505b0
+  data.tar.gz: 1853fdeac0f0b339133f666db263af0abc40e6a60a8e665526646cd5ea09e5ebf312b27e1ebee17ceccf5c74dc789d15e5c6b856b40a99196ec2e6c21ab9a732

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.1.1] - 2026-11-01
+
+### Changed
+
+- Changed: README and package metadata link to trigv.com docs
+
+## [1.1.0] - 2026-11-01
+
+### Changed
+
+- Default `base_url` is now `https://api.trigv.com`; paths are `/v1/events` and `/v1/connection`. A base URL ending in `/api` keeps working.
+- `public_id` values are 26 character ULIDs (no `evt_` prefix).
+- Rate limit is 60 requests per minute per workspace.
+- Invalid JSON bodies return 422 and map to `Trigv::ValidationError`.
+- A `Retry-After` longer than the client `timeout` is not waited for: the 409, 429 or 503 error is raised at once.
+
+### Added
+
+- `Trigv::ConflictError` (409) and `Trigv::ServiceUnavailableError` (503), retried with `Retry-After` when an `idempotency_key` is set.
+- `request_id` on every API error (from the `X-Request-ID` header).
+- `request_id` on `Trigv::SendEventResult` and `Trigv::ConnectionResult` (`nil` if the header is missing).
+
+### Deprecated
+
+- `Trigv::RateLimitError#retryable` (always `true`), the `retryable:` argument (ignored) and `Trigv::Errors.monthly_limit_message?` (always `false`) are kept for compatibility.
+
+### Removed
+
+- Monthly event cap handling.
+
 ## [1.0.0] - 2026-07-07
 
 ### Added

data/README.md

@@ -1,5 +1,7 @@
 # trigv
 
+[Docs](https://trigv.com/docs/sdks/ruby/) | [API reference](https://trigv.com/docs/api/) | [Free tools](https://trigv.com/tools/) | [Get an API key](https://app.trigv.com/register)
+
 Official Trigv SDK for Ruby. Send notification events from scripts, servers, and CI pipelines.
 
 ## What Trigv is
@@ -11,7 +13,7 @@ Trigv delivers developer notifications to your team's devices. Your backend send
 Add to your Gemfile:
 
 ```ruby
-gem 'trigv', '~> 0.1'
+gem 'trigv', '~> 1.1'
 ```
 
 Then run:
@@ -57,21 +59,22 @@ result = client.send_event(
 )
 
 puts result.event.public_id
+puts result.request_id # X-Request-ID header, or nil if missing
 ```
 
 ## 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) |
+| `channel` | Yes | Channel slug (e.g. `general`, max 120 characters) |
+| `title` | Yes | Notification title (max 255 characters) |
+| `description` | No | Body text (max 1000 characters) |
+| `image_url` | No | Image URL (max 2048 characters; 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 |
+| `event_type` | No | Free-form label (e.g. `deploy.completed`, max 120 characters) |
+| `idempotency_key` | No | Dedup key per workspace (max 190 characters) |
 
 ## Levels
 
@@ -87,7 +90,7 @@ puts result.event.public_id
 
 ## Idempotency
 
-When you set `idempotency_key`, retries with the same key return the existing event (`duplicate: true`, HTTP 200) without billing again.
+When you set `idempotency_key`, retries with the same key return the existing event (`duplicate: true`, HTTP 200, message `already stored`) without billing again. A 409 or 503 is retried with the same key, honouring `Retry-After`.
 
 ```ruby
 result = client.send_event(
@@ -108,17 +111,29 @@ 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'
+rescue Trigv::RateLimitError, Trigv::ConflictError, Trigv::ServiceUnavailableError => e
+  puts "Retry in #{e.retry_after_seconds}s (request id #{e.request_id})"
 end
 ```
 
+| Error | HTTP | Retried (with `idempotency_key`) |
+|-------|------|:---:|
+| `Trigv::AuthenticationError` | 401 | No |
+| `Trigv::AuthorizationError` | 403 | No |
+| `Trigv::NotFoundError` | 404 | No |
+| `Trigv::ConflictError` | 409, same key being delivered | Yes |
+| `Trigv::ValidationError` | 422 | No |
+| `Trigv::RateLimitError` | 429, 60 requests per minute per workspace | Yes |
+| `Trigv::ServiceUnavailableError` | 503, push unavailable | Yes |
+
+Retries wait for `Retry-After`. If `Retry-After` is longer than the client `timeout`, the error is raised at once. 502 and 504 responses, network errors and timeouts are also retried (with an `idempotency_key`), and so is `verify_connection`. Every error has `request_id`, the `X-Request-ID` header. Successful results have `request_id` too (`nil` if missing). Quote it to support.
+
 ## Configuration
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `api_key` | `TRIGV_API_KEY` env | Workspace API key |
-| `base_url` | `https://api.trigv.com/api` | API base URL |
+| `base_url` | `https://api.trigv.com` | API base URL. A URL ending in `/api` still works |
 | `timeout` | `30` | Request timeout (seconds) |
 | `max_retries` | `2` | Retries for retryable errors |
 
@@ -127,6 +142,7 @@ end
 ```ruby
 connection = client.verify_connection
 puts connection.workspace.name
+puts connection.request_id # X-Request-ID header, or nil if missing
 ```
 
 ## Examples

data/lib/trigv/client.rb

@@ -12,11 +12,11 @@ module Trigv
     keyword_init: true
   )
 
-  SendEventResult = Struct.new(:event, :duplicate, keyword_init: true)
+  SendEventResult = Struct.new(:event, :duplicate, :request_id, 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)
+  ConnectionResult = Struct.new(:workspace, :api_key, :request_id, keyword_init: true)
 
   class Client
     attr_reader :api_key, :base_url, :timeout, :max_retries
@@ -43,6 +43,11 @@ module Trigv
       "trigv-ruby/#{VERSION}"
     end
 
+    # Keep the API key out of logs, consoles and exception reports that call inspect.
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect} timeout=#{timeout} max_retries=#{max_retries}>"
+    end
+
     def send_event(**params)
       body = Validation.validate_send_event_params(params)
       has_idempotency = body.key?('idempotency_key')
@@ -50,7 +55,7 @@ module Trigv
       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)
+          SendEventResult.new(event: event, duplicate: status == 200, request_id: headers['x-request-id'])
         else
           error_from_response(status, parsed, headers)
         end
@@ -60,7 +65,7 @@ module Trigv
     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)
+          parse_connection_result(parsed, headers['x-request-id'])
         else
           error_from_response(status, parsed, headers)
         end
@@ -81,6 +86,9 @@ module Trigv
         raise e unless retryable_error?(e)
 
         wait = retry_wait_seconds(e, attempt)
+        # A wait longer than the timeout is not worth sleeping for: raise the real error.
+        raise e if wait > timeout && e.respond_to?(:retry_after_seconds) && e.retry_after_seconds
+
         sleep([wait, timeout].min)
       end
 
@@ -88,7 +96,7 @@ module Trigv
     end
 
     def retry_wait_seconds(error, attempt)
-      return error.retry_after_seconds if error.is_a?(RateLimitError) && error.retry_after_seconds
+      return error.retry_after_seconds if error.respond_to?(:retry_after_seconds) && error.retry_after_seconds
 
       (0.5 * (2**attempt)) + (rand * 0.25)
     end
@@ -97,8 +105,8 @@ module Trigv
       case error
       when ValidationError, AuthenticationError, AuthorizationError, NotFoundError
         false
-      when RateLimitError
-        error.retryable
+      when RateLimitError, ConflictError, ServiceUnavailableError
+        true
       when ApiError
         retryable_status?(error.status_code)
       when NetworkError, TimeoutError
@@ -109,7 +117,7 @@ module Trigv
     end
 
     def retryable_status?(status)
-      [429, 502, 503, 504].include?(status)
+      [502, 504].include?(status)
     end
 
     def request_once(method, path, body)
@@ -123,8 +131,7 @@ module Trigv
       [response.code.to_i, parsed, response_headers]
     rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error
       raise TimeoutError
-    rescue ValidationError, AuthenticationError, AuthorizationError, NotFoundError,
-           RateLimitError, ApiError, TimeoutError
+    rescue Error
       raise
     rescue StandardError => e
       raise NetworkError.new(e.message, e)
@@ -166,7 +173,8 @@ module Trigv
     def parse_json(text)
       return nil if text.nil? || text.empty?
 
-      JSON.parse(text)
+      parsed = JSON.parse(text)
+      parsed.is_a?(Hash) ? parsed : nil
     rescue JSON::ParserError
       nil
     end
@@ -183,7 +191,7 @@ module Trigv
       )
     end
 
-    def parse_connection_result(parsed)
+    def parse_connection_result(parsed, request_id = nil)
       workspace_data = parsed['workspace']
       api_key_data = parsed['api_key']
 
@@ -202,7 +210,8 @@ module Trigv
 
       ConnectionResult.new(
         workspace: ConnectionWorkspace.new(**symbolize_keys(workspace_data)),
-        api_key: ConnectionApiKey.new(**symbolize_keys(api_key_data))
+        api_key: ConnectionApiKey.new(**symbolize_keys(api_key_data)),
+        request_id: request_id
       )
     rescue ArgumentError, KeyError, TypeError
       raise ValidationError.new('Invalid connection response payload', {})
@@ -214,26 +223,22 @@ module Trigv
 
     def error_from_response(status, body, headers = {})
       message = body&.fetch('message', nil) || "Trigv API returned HTTP #{status}"
+      retry_after = Retry.parse_retry_after(headers['retry-after'])
+
+      error =
+        case status
+        when 401 then AuthenticationError.new(message)
+        when 403 then AuthorizationError.new(message)
+        when 404 then NotFoundError.new(message)
+        when 409 then ConflictError.new(message, retry_after_seconds: retry_after)
+        when 422 then ValidationError.new(message, body&.fetch('errors', {}) || {})
+        when 429 then RateLimitError.new(message, retry_after_seconds: retry_after)
+        when 503 then ServiceUnavailableError.new(message, retry_after_seconds: retry_after)
+        else ApiError.new(message, status, body)
+        end
 
-      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
+      error.request_id = headers['x-request-id']
+      raise error
     end
   end
 end

data/lib/trigv/errors.rb

@@ -2,6 +2,9 @@
 
 module Trigv
   class Error < StandardError
+    # Value of the X-Request-ID response header, when the API answered.
+    attr_accessor :request_id
+
     def initialize(message = nil)
       super
     end
@@ -44,12 +47,42 @@ module Trigv
   end
 
   class RateLimitError < Error
-    attr_reader :status_code, :retryable, :retry_after_seconds
+    attr_reader :status_code, :retry_after_seconds
 
-    def initialize(message, retryable: true, retry_after_seconds: nil)
+    # +retryable:+ is accepted and ignored so code written for 1.0 keeps working.
+    def initialize(message, retry_after_seconds: nil, retryable: true) # rubocop:disable Lint/UnusedMethodArgument
       super(message)
       @status_code = 429
-      @retryable = retryable
+      @retry_after_seconds = retry_after_seconds
+    end
+
+    # Always true.
+    #
+    # @deprecated Kept so code written for 1.0 still works. Every 429 is a rate limit:
+    #   wait +retry_after_seconds+ and try again. There is no monthly cap any more.
+    def retryable # rubocop:disable Naming/PredicateMethod
+      true
+    end
+  end
+
+  # HTTP 409: another request is delivering the same idempotency_key.
+  class ConflictError < Error
+    attr_reader :status_code, :retry_after_seconds
+
+    def initialize(message, retry_after_seconds: nil)
+      super(message)
+      @status_code = 409
+      @retry_after_seconds = retry_after_seconds
+    end
+  end
+
+  # HTTP 503: push delivery is unavailable. Retry with the same idempotency_key.
+  class ServiceUnavailableError < Error
+    attr_reader :status_code, :retry_after_seconds
+
+    def initialize(message, retry_after_seconds: nil)
+      super(message)
+      @status_code = 503
       @retry_after_seconds = retry_after_seconds
     end
   end
@@ -82,8 +115,11 @@ module Trigv
   module Errors
     module_function
 
-    def monthly_limit_message?(message)
-      message.include?('Monthly event limit')
+    # Always false.
+    #
+    # @deprecated Kept so code written for 1.0 still works. The monthly event cap was removed.
+    def monthly_limit_message?(_message)
+      false
     end
   end
 end

data/lib/trigv/validation.rb

@@ -2,7 +2,7 @@
 
 module Trigv
   module Validation
-    DEFAULT_BASE_URL = 'https://api.trigv.com/api'
+    DEFAULT_BASE_URL = 'https://api.trigv.com'
     DEFAULT_TIMEOUT = 30
     MAX_RETRIES = 2
 

data/lib/trigv/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trigv
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Trigv
@@ -26,12 +26,15 @@ files:
 - lib/trigv/retry.rb
 - lib/trigv/validation.rb
 - lib/trigv/version.rb
-homepage: https://github.com/Trigv/trigv-ruby
+homepage: https://trigv.com
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/Trigv/trigv-ruby
+  homepage_uri: https://trigv.com
+  documentation_uri: https://trigv.com/docs/sdks/ruby/
   source_code_uri: https://github.com/Trigv/trigv-ruby
+  bug_tracker_uri: https://github.com/Trigv/trigv-ruby/issues
+  changelog_uri: https://github.com/Trigv/trigv-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: