letterapp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f34428952a2c04f306b6202d26e5fed5537a347aef6b5682d893eacd2b5d148c
+  data.tar.gz: f21c70172c12e83daf530971113ae379c385b18a2101189546c97cd1c978d70e
+SHA512:
+  metadata.gz: 04155060eef72dc6631a404abf9ea37327a7584642d576f52e43245c1d95729c31a60728589fd750839ddd8c5279b5d8e3bc7bfafc8316042f33fbde0ff0021b
+  data.tar.gz: a91ef9c7620135df31e75a05b4164b78e17feae3630f89b14f17a92e36e87a0d0dde7fd9ceb57abf5b38ae3746f28f9dd1f7b0f34111399531121d7c4a60ccd0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 letter.app
+
+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,93 @@
+# letterapp (Ruby)
+
+[![Gem Version](https://img.shields.io/gem/v/letterapp)](https://rubygems.org/gems/letterapp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
+
+Official Ruby client for **[letter.app](https://letter.app)** - onboarding
+email drip campaigns for product teams.
+
+```bash
+bundle add letterapp
+# or: gem install letterapp
+```
+
+Requires Ruby **3.0+**. Zero runtime dependencies (standard library only).
+
+## Quick start
+
+```ruby
+require "letterapp"
+
+letter = Letterapp::Client.new(api_key: ENV["LETTER_API_KEY"]) # Dashboard -> Settings -> API keys
+
+# Tell Letter who your user is (call where users sign up or log in).
+letter.identify(
+  user_id: "user_123",
+  email: "alice@example.com",
+  traits: { name: "Alice", plan: "free" }
+)
+
+# Report something they did.
+letter.track(user_id: "user_123", event: "Signed Up", properties: { source: "web" })
+
+# Required before the process exits so no events are lost.
+letter.close
+```
+
+## Serverless (Lambda, Cloud Functions)
+
+There is no background time to flush in a serverless handler, so set
+`flush_at: 1` and `flush` at the end of each invocation:
+
+```ruby
+letter = Letterapp::Client.new(api_key: ENV["LETTER_API_KEY"], flush_at: 1)
+
+def handler(event:, context:)
+  letter.track(user_id: "user_123", event: "Checkout Started")
+  letter.flush
+end
+```
+
+## What it does
+
+- **Auto-batching** - calls are queued and flushed every 100ms or 50 events by
+  a background thread.
+- **Retries** - `429` waits `Retry-After`; `5xx` and network errors back off
+  exponentially with jitter, up to `max_retries` (default 3).
+- **Idempotent** - every call gets a UUID `message_id` so retries are
+  deduplicated server-side.
+- **No dependencies** - HTTP over the standard library `net/http`.
+
+## API
+
+```ruby
+Letterapp::Client.new(
+  api_key:,
+  base_url: "https://api.letter.app", # only set for self-hosted / local
+  flush_at: 50,                        # 1 for serverless
+  flush_interval: 0.1,                 # seconds
+  max_retries: 3,
+  open_timeout: 10,
+  read_timeout: 10,
+  on_error: nil                        # ->(error) for background errors
+)
+
+letter.identify(user_id:, email: nil, traits: nil, timezone: nil, timestamp: nil, message_id: nil)
+letter.group(user_id:, account_id:, name: nil, traits: nil, timestamp: nil, message_id: nil)
+letter.track(user_id:, event:, properties: nil, timestamp: nil, message_id: nil)
+letter.flush # send queued calls now, block until done
+letter.close # flush + stop the background thread (also runs at exit)
+```
+
+Configuration errors and non-retryable API responses raise `Letterapp::Error`
+(with `#status` and `#body`). Background transport errors are passed to
+`on_error` instead, since they cannot be raised to the caller.
+
+## Full documentation
+
+- **SDK reference:** <https://letter.app/docs/ruby-sdk>
+- **Ingestion API:** <https://letter.app/docs/api>
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

data/lib/letterapp/client.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "time"
+require "uri"
+
+require_relative "version"
+
+module Letterapp
+  DEFAULT_BASE_URL = "https://api.letter.app"
+
+  # Raised for client misconfiguration and non-retryable API errors.
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  # A Letter ingestion client.
+  #
+  # Long-running server (default): identify / group / track enqueue calls that a
+  # background thread auto-batches and flushes every 100ms or 50 events. Call
+  # +close+ before the process exits.
+  #
+  # Serverless: pass flush_at: 1 and call +flush+ at the end of each invocation.
+  class Client
+    # @param api_key   [String] API key (Dashboard -> Settings -> API keys).
+    # @param base_url  [String] API origin. Defaults to https://api.letter.app.
+    # @param flush_at  [Integer] Flush after this many queued events (1 = serverless).
+    # @param flush_interval [Float] Seconds between background flushes.
+    # @param max_retries [Integer] Max retry attempts per request.
+    # @param on_error   [#call] Callback for background transport errors.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, flush_at: 50,
+                   flush_interval: 0.1, max_retries: 3, open_timeout: 10,
+                   read_timeout: 10, on_error: nil)
+      raise Error, "api_key is required" if api_key.nil? || api_key.to_s.empty?
+
+      @api_key = api_key
+      @base_url = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @flush_at = [1, flush_at.to_i].max
+      @flush_interval = flush_interval.to_f
+      @max_retries = max_retries.to_i
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @on_error = on_error || ->(err) { warn("[letter] #{err.message}") }
+
+      @uri = URI.parse(@base_url)
+      @queue = []
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @send_mutex = Mutex.new
+      @closed = false
+
+      @thread = Thread.new { loop_run }
+      at_exit { close }
+    end
+
+    # Queue an identify call (creates or updates a contact).
+    def identify(user_id:, email: nil, traits: nil, timezone: nil,
+                 timestamp: nil, message_id: nil)
+      enqueue(serialize_identify(user_id, email, traits, timezone, timestamp, message_id))
+    end
+
+    # Queue a group call (associates a contact with an account).
+    def group(user_id:, account_id:, name: nil, traits: nil,
+              timestamp: nil, message_id: nil)
+      enqueue(serialize_group(user_id, account_id, name, traits, timestamp, message_id))
+    end
+
+    # Queue a track call (records an event).
+    def track(user_id:, event:, properties: nil, timestamp: nil, message_id: nil)
+      enqueue(serialize_track(user_id, event, properties, timestamp, message_id))
+    end
+
+    # Send everything currently queued and block until it completes.
+    def flush
+      loop do
+        batch = take_batch
+        break if batch.nil?
+
+        @send_mutex.synchronize { send_batch(batch) }
+      end
+    end
+
+    # Flush, stop the background thread, and block until drained.
+    def close
+      @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        @cond.broadcast
+      end
+      @thread&.join(@read_timeout * (@max_retries + 2))
+      flush
+    end
+
+    private
+
+    def enqueue(item)
+      @mutex.synchronize do
+        if @closed
+          @on_error.call(Error.new("Letter client is closed."))
+          return
+        end
+        @queue << item
+        @cond.signal
+      end
+    end
+
+    def take_batch
+      @mutex.synchronize do
+        return nil if @queue.empty?
+
+        @queue.shift([@queue.length, 100].min)
+      end
+    end
+
+    def loop_run
+      loop do
+        @mutex.synchronize do
+          @cond.wait(@mutex) while @queue.empty? && !@closed
+          return if @closed && @queue.empty?
+
+          # Below the size threshold: wait briefly to batch more before sending.
+          @cond.wait(@mutex, @flush_interval) if @queue.length < @flush_at && !@closed
+        end
+        flush
+      end
+    end
+
+    def send_batch(batch)
+      request("/v1/batch", { "batch" => batch })
+    rescue StandardError => e
+      @on_error.call(e.is_a?(Error) ? e : Error.new(e.message))
+    end
+
+    def request(path, body)
+      data = JSON.generate(body)
+      last_err = nil
+
+      (0..@max_retries).each do |attempt|
+        begin
+          res = post(path, data)
+          code = res.code.to_i
+          return if code >= 200 && code < 300
+
+          if code == 429 && attempt < @max_retries
+            sleep(retry_after(res))
+            next
+          end
+          if code >= 500 && attempt < @max_retries
+            sleep(backoff(attempt))
+            next
+          end
+          raise Error.new(
+            "Request failed with #{code}: #{res.body}", status: code, body: res.body
+          )
+        rescue Timeout::Error, IOError, SystemCallError, SocketError => e
+          last_err = Error.new("Network error: #{e.message}")
+          raise last_err if attempt >= @max_retries
+
+          sleep(backoff(attempt))
+        end
+      end
+
+      raise(last_err || Error.new("Request failed for unknown reason"))
+    end
+
+    def post(path, data)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = (@uri.scheme == "https")
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      req = Net::HTTP::Post.new(path)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["User-Agent"] = "letterapp-ruby/#{Letterapp::VERSION}"
+      req.body = data
+      http.request(req)
+    end
+
+    def serialize_identify(user_id, email, traits, timezone, timestamp, message_id)
+      raise Error, "identify: user_id is required" if blank?(user_id)
+
+      item = {
+        "type" => "identify",
+        "userId" => user_id,
+        "traits" => traits || {},
+        "messageId" => message_id || SecureRandom.uuid
+      }
+      item["email"] = email unless email.nil?
+      item["timezone"] = timezone unless timezone.nil?
+      iso = to_iso(timestamp)
+      item["timestamp"] = iso unless iso.nil?
+      item
+    end
+
+    def serialize_group(user_id, account_id, name, traits, timestamp, message_id)
+      raise Error, "group: user_id is required" if blank?(user_id)
+      raise Error, "group: account_id is required" if blank?(account_id)
+
+      item = {
+        "type" => "group",
+        "userId" => user_id,
+        "accountId" => account_id,
+        "traits" => traits || {},
+        "messageId" => message_id || SecureRandom.uuid
+      }
+      item["name"] = name unless name.nil?
+      iso = to_iso(timestamp)
+      item["timestamp"] = iso unless iso.nil?
+      item
+    end
+
+    def serialize_track(user_id, event, properties, timestamp, message_id)
+      raise Error, "track: user_id is required" if blank?(user_id)
+      raise Error, "track: event is required" if blank?(event)
+
+      item = {
+        "type" => "track",
+        "userId" => user_id,
+        "event" => event,
+        "properties" => properties || {},
+        "messageId" => message_id || SecureRandom.uuid
+      }
+      iso = to_iso(timestamp)
+      item["timestamp"] = iso unless iso.nil?
+      item
+    end
+
+    def to_iso(value)
+      return nil if value.nil?
+      return value.iso8601 if value.respond_to?(:iso8601)
+
+      value.to_s
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.empty?
+    end
+
+    def retry_after(res)
+      raw = res["retry-after"]
+      Float(raw)
+    rescue ArgumentError, TypeError
+      1.0
+    end
+
+    def backoff(attempt)
+      (0.25 * (2**attempt)) + (rand * 0.1)
+    end
+  end
+end

data/lib/letterapp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Letterapp
+  VERSION = "0.1.0"
+end

data/lib/letterapp.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "letterapp/version"
+require_relative "letterapp/client"
+
+# Official Ruby client for letter.app.
+#
+#   require "letterapp"
+#
+#   letter = Letterapp::Client.new(api_key: ENV["LETTER_API_KEY"])
+#   letter.identify(user_id: "user_123", email: "alice@example.com")
+#   letter.track(user_id: "user_123", event: "Signed Up")
+#   letter.close
+module Letterapp
+  # Convenience: Letterapp.new(...) == Letterapp::Client.new(...)
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: letterapp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- letter.app
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Auto-batching Ruby client for letter.app: identify users, track events,
+  and group accounts over the ingestion API. Retries, idempotency, zero runtime dependencies.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/letterapp.rb
+- lib/letterapp/client.rb
+- lib/letterapp/version.rb
+homepage: https://letter.app/docs/ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://letter.app/docs/ruby-sdk
+  source_code_uri: https://github.com/vincenzor/letter-ruby
+  bug_tracker_uri: https://github.com/vincenzor/letter-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Official Ruby client for letter.app - onboarding email drip campaigns.
+test_files: []