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:

gem 'trigv', '~> 0.1'

Then run:

bundle install

Quick start

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. Keys look like trgv_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

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

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.

result = client.send_event(
  channel: 'deploys',
  title: 'Production deploy complete',
  idempotency_key: 'deploy-prod-42'
)

puts result.duplicate ? 'duplicate' : 'new'

Error handling

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

connection = client.verify_connection
puts connection.workspace.name

Examples

See the 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

bundle install
bundle exec rspec
bundle exec rubocop

Testing

bundle exec rspec

Tests use WebMock — no live API key required.

Contributing

Contributions welcome. Please open an issue before large changes.

Licence

MIT