Ruby SDK

The norq gem provides a client for sending and linting notification templates from Ruby applications.

Install

# Gemfile
gem "norq"
bundle install

Requires the norq binary to be installed and available in $PATH.

Quick start

require "norq"
 
notif = Norq::Client.new
 
# Send
result = notif.send("transactional/order-shipped",
  to: { email: "gaurav@example.com" },
  data: { user: { first_name: "Gaurav" }, order: { id: "ORD-123" } })
 
result.results.each do |r|
  puts "#{r.channel}: #{r.success ? 'OK' : r.error}"
end

Constructor

notif = Norq::Client.new(
  binary_path: "/usr/local/bin/norq",
  cwd: "/path/to/project",
  recipient_resolver: MyResolver.new,
)

API

send(notification, to:, data: nil, sample: nil, channels: nil, dry_run: false)

result = notif.send("transactional/welcome",
  to: { email: "user@example.com" },
  data: { user: { first_name: "Gaurav" } },
  channels: ["email"],
  dry_run: false)
 
result.results.each { |r| puts "#{r.channel}: #{r.success}" }
result.skipped.each { |s| puts "Skipped #{s.channel}: #{s.reason}" }

lint(notification = nil)

results = notif.lint              # all
results = notif.lint("transactional/welcome")   # one
 
results.each do |result|
  result.diagnostics.each do |d|
    puts "#{d.severity}: #{d.message} [#{d.rule}]"
  end
end

RecipientResolver

class MyResolver
  def initialize(db)
    @db = db
  end
 
  def resolve(user_id)
    user = @db.find_user(user_id)
    Norq::Recipient.new(
      email: user.email,
      phone: user.phone
    )
  end
end
 
notif = Norq::Client.new(recipient_resolver: MyResolver.new(db))
notif.send("transactional/welcome", to: "user-123", data: { ... })

Error handling

begin
  notif.send("transactional/welcome", to: "user-123", data: { ... })
rescue Norq::NorqError => e
  puts "Norq error: #{e.message}"
end

Codegen

norq codegen --lang ruby --out lib/generated/norq_types.rb

Generates typed Ruby classes for each notification's data shape.