sooner-email 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +21 -0
  3. data/README.md +43 -0
  4. data/lib/sooner_email.rb +203 -0
  5. metadata +44 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 33b24eb2e21737bf96e7815e4464c9da07322b1104bd6ce172aa575b5d24a332
4
+ data.tar.gz: d8d61bc124f2b45934c3bf0b2363e7488270e052f032614186e37cb876bffaf3
5
+ SHA512:
6
+ metadata.gz: 4d89b6769f42b9bad0b886aedff52d94837ea0db9cd8a846238be9f923af5b6725ea8f43c9b6acaaee1a03000dffb117818b3b551fdca29ec0256814377785a8
7
+ data.tar.gz: b0131de8865c1c9ee3b6d6220556170be5e8bc2f9e28b8525af1b60bf64043e3ea6b9a8e8ca6a8a1ae4afe8415d7cb3b2d3add01b100b43e6503e038f787dfa1
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sooner
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,43 @@
1
+ # Sooner Ruby SDK
2
+
3
+ Ruby 3.1 or later. Uses standard and bundled `net/http`, `json`, `uri`, `ipaddr` and `timeout`. Verified locally with Ruby 4.0.
4
+
5
+ Install the published gem:
6
+
7
+ ```sh
8
+ curl -fLO https://github.com/Quad-Labs-LLC/sooner-sdks/releases/download/v0.1.0/sooner-email-0.1.0.gem
9
+ gem install --local sooner-email-0.1.0.gem
10
+ ```
11
+
12
+ ```ruby
13
+ require "sooner_email"
14
+
15
+ client = SoonerEmail::Client.new(ENV.fetch("SOONER_API_KEY"))
16
+ email = client.emails.send({
17
+ from: "Acme <hello@mail.example.com>",
18
+ to: ["ada@example.com"],
19
+ subject: "Welcome",
20
+ text: "Welcome to Acme."
21
+ }, idempotency_key: "welcome-user-123")
22
+
23
+ puts email.fetch("id")
24
+ ```
25
+
26
+ The client supports these email methods.
27
+
28
+ - `emails.send(payload, idempotency_key: nil)`
29
+ - `emails.send_batch(payloads, idempotency_key: nil)`
30
+ - `emails.list(limit: nil, after: nil)`
31
+ - `emails.get(id)`
32
+ - `emails.reschedule(id, scheduled_at: "2026-12-01T09:00:00Z")`
33
+ - `emails.cancel(id)`
34
+
35
+ Payload hashes use the API's snake_case field names with symbol or string keys. Calls return parsed response hashes with string keys. Batch sends accept 1–100 messages and reject attachments or scheduling. Sending-only keys can send email. Reading, canceling and rescheduling require full access. The sending domain must be verified.
36
+
37
+ HTTP failures raise `SoonerEmail::APIError` with `status`, `code`, `message` and the raw `retry_after` header. Network failures and timeouts raise `SoonerEmail::TransportError` with a stable `code` of `network_error`, `timeout_error` or `invalid_response`. Transport exception text is redacted. Request failure can leave a send outcome unknown. Reuse the exact payload and original idempotency key when retrying that send.
38
+
39
+ The constructor accepts `base_url:` and `timeout:`. The default origin is `https://api.sooner.dev`. The default total request deadline is 30 seconds. Custom origins require HTTPS, except localhost or loopback HTTP origins for development. Redirects are rejected. Each call makes a single attempt.
40
+
41
+ Run offline tests with `ruby -Ilib test/client_test.rb`. Build from this directory using `gem build sooner-email.gemspec --output /tmp/sooner-email-0.1.0.gem`.
42
+
43
+ Source and releases are available at https://github.com/Quad-Labs-LLC/sooner-sdks/tree/main/ruby. Licensed under MIT.
@@ -0,0 +1,203 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ipaddr"
4
+ require "json"
5
+ require "net/http"
6
+ require "timeout"
7
+ require "uri"
8
+
9
+ module SoonerEmail
10
+ VERSION = "0.1.0"
11
+ DEFAULT_BASE_URL = "https://api.sooner.dev"
12
+ MAX_RESPONSE_BYTES = 4 * 1024 * 1024
13
+
14
+ class APIError < StandardError
15
+ attr_reader :status, :code, :retry_after
16
+
17
+ def initialize(status:, code:, message:, retry_after: nil)
18
+ @status = status
19
+ @code = code
20
+ @retry_after = retry_after
21
+ super(message)
22
+ end
23
+ end
24
+
25
+ # Request failures may leave a write outcome unknown. Reuse the original
26
+ # idempotency key and exact payload when retrying a send.
27
+ class TransportError < StandardError
28
+ attr_reader :code
29
+
30
+ def initialize(message, code: "invalid_response")
31
+ @code = code
32
+ super(message)
33
+ end
34
+ end
35
+
36
+ class Client
37
+ attr_reader :emails
38
+
39
+ def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30)
40
+ unless api_key.is_a?(String) && api_key.match?(/\Asn_[A-Za-z0-9_-]{16,200}\z/)
41
+ raise ArgumentError, "A native sn_ project API key is required"
42
+ end
43
+ @base = URI.parse(base_url)
44
+ unless valid_origin?(@base)
45
+ raise ArgumentError, "Base URL must be an HTTPS origin or a loopback HTTP origin"
46
+ end
47
+ unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
48
+ raise ArgumentError, "Timeout must be finite and positive"
49
+ end
50
+ @api_key = api_key.dup.freeze
51
+ @timeout = timeout
52
+ @emails = Emails.new(self)
53
+ rescue URI::InvalidURIError
54
+ raise ArgumentError, "Invalid API origin"
55
+ end
56
+
57
+ def inspect
58
+ "#<SoonerEmail::Client base_url=#{@base}>"
59
+ end
60
+
61
+ def request(method, path, body: nil, idempotency_key: nil)
62
+ if idempotency_key && (!idempotency_key.is_a?(String) ||
63
+ idempotency_key.empty? || idempotency_key.bytesize > 256 ||
64
+ idempotency_key.match?(/[\r\n]/))
65
+ raise ArgumentError, "Idempotency key must contain 1 to 256 bytes without newlines"
66
+ end
67
+ request = Net::HTTPGenericRequest.new(method, !body.nil?, true, path)
68
+ request["Authorization"] = "Bearer #{@api_key}"
69
+ request["Accept"] = "application/json"
70
+ request["User-Agent"] = "sooner-ruby/#{VERSION}"
71
+ request["Idempotency-Key"] = idempotency_key if idempotency_key
72
+ unless body.nil?
73
+ request["Content-Type"] = "application/json"
74
+ request.body = JSON.generate(body)
75
+ end
76
+ http = Net::HTTP.new(@base.hostname, @base.port, nil)
77
+ http.use_ssl = @base.scheme == "https"
78
+ http.open_timeout = @timeout
79
+ http.read_timeout = @timeout
80
+ http.write_timeout = @timeout
81
+ http.max_retries = 0
82
+ data = +""
83
+ response = nil
84
+
85
+ Timeout.timeout(@timeout) do
86
+ http.start do
87
+ http.request(request) do |received|
88
+ response = received
89
+ received.read_body do |chunk|
90
+ data << chunk
91
+ if data.bytesize > MAX_RESPONSE_BYTES
92
+ raise TransportError, "API response exceeded 4 MiB; a write outcome may be unknown"
93
+ end
94
+ end
95
+ end
96
+ end
97
+ end
98
+
99
+ status = response.code.to_i
100
+ unless (200...300).cover?(status)
101
+ failure = begin
102
+ JSON.parse(data)
103
+ rescue JSON::ParserError
104
+ {}
105
+ end
106
+ failure = {} unless failure.is_a?(Hash)
107
+ raise APIError.new(
108
+ status: status,
109
+ code: failure["name"].is_a?(String) ? failure["name"].gsub(@api_key, "[redacted]") : "http_error",
110
+ message: failure["message"].is_a?(String) ? failure["message"].gsub(@api_key, "[redacted]") : "Sooner returned HTTP #{status}",
111
+ retry_after: response["Retry-After"]&.gsub(@api_key, "[redacted]")
112
+ )
113
+ end
114
+ result = JSON.parse(data)
115
+ raise TransportError, "API response must be a JSON object" unless result.is_a?(Hash)
116
+ result
117
+ rescue JSON::ParserError
118
+ raise TransportError, "Invalid API response; a write outcome may be unknown", cause: nil
119
+ rescue Timeout::Error
120
+ raise TransportError.new("Request timed out; a write outcome may be unknown. Reuse its original idempotency key.", code: "timeout_error"), cause: nil
121
+ rescue IOError, SystemCallError, SocketError, EOFError, OpenSSL::SSL::SSLError
122
+ raise TransportError.new("Request failed; a write outcome may be unknown. Reuse its original idempotency key.", code: "network_error"), cause: nil
123
+ end
124
+
125
+ private
126
+
127
+ def valid_origin?(uri)
128
+ return false unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo &&
129
+ !uri.query && !uri.fragment && ["", "/"].include?(uri.path)
130
+ return true if uri.scheme == "https"
131
+ return true if uri.hostname == "localhost"
132
+ IPAddr.new(uri.hostname).loopback?
133
+ rescue IPAddr::InvalidAddressError
134
+ false
135
+ end
136
+ end
137
+
138
+ class Emails
139
+ def initialize(client)
140
+ @client = client
141
+ end
142
+
143
+ def send(payload, idempotency_key: nil)
144
+ require_payload(payload)
145
+ @client.request("POST", "/emails", body: payload, idempotency_key: idempotency_key)
146
+ end
147
+
148
+ def send_batch(payloads, idempotency_key: nil)
149
+ unless payloads.is_a?(Array) && (1..100).cover?(payloads.length)
150
+ raise ArgumentError, "Batch must contain 1 to 100 emails"
151
+ end
152
+ payloads.each do |payload|
153
+ require_payload(payload)
154
+ if ["attachments", "scheduled_at", "scheduledAt"].any? { |key| payload.key?(key) || payload.key?(key.to_sym) }
155
+ raise ArgumentError, "Batch emails cannot include attachments or scheduled_at"
156
+ end
157
+ end
158
+ @client.request("POST", "/emails/batch", body: payloads, idempotency_key: idempotency_key)
159
+ end
160
+
161
+ def list(limit: nil, after: nil)
162
+ query = {}
163
+ unless limit.nil?
164
+ raise ArgumentError, "Limit must be between 1 and 100" unless limit.is_a?(Integer) && (1..100).cover?(limit)
165
+ query["limit"] = limit
166
+ end
167
+ unless after.nil?
168
+ identifier(after)
169
+ query["after"] = after
170
+ end
171
+ suffix = query.empty? ? "" : "?#{URI.encode_www_form(query)}"
172
+ @client.request("GET", "/emails#{suffix}")
173
+ end
174
+
175
+ def get(id)
176
+ @client.request("GET", "/emails/#{identifier(id)}")
177
+ end
178
+
179
+ def reschedule(id, scheduled_at:)
180
+ unless scheduled_at.is_a?(String) && !scheduled_at.empty?
181
+ raise ArgumentError, "Scheduled time is required"
182
+ end
183
+ @client.request("PATCH", "/emails/#{identifier(id)}", body: {scheduled_at: scheduled_at})
184
+ end
185
+
186
+ def cancel(id)
187
+ @client.request("POST", "/emails/#{identifier(id)}/cancel")
188
+ end
189
+
190
+ private
191
+
192
+ def identifier(id)
193
+ unless id.is_a?(String) && id.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]{0,127}\z/)
194
+ raise ArgumentError, "Invalid email identifier"
195
+ end
196
+ id
197
+ end
198
+
199
+ def require_payload(payload)
200
+ raise ArgumentError, "Email payload must be a Hash" unless payload.is_a?(Hash)
201
+ end
202
+ end
203
+ end
metadata ADDED
@@ -0,0 +1,44 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: sooner-email
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Sooner
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies: []
12
+ description: Email sending, batch delivery, pagination, scheduling and cancellation
13
+ with explicit idempotency and request deadlines.
14
+ executables: []
15
+ extensions: []
16
+ extra_rdoc_files: []
17
+ files:
18
+ - LICENSE
19
+ - README.md
20
+ - lib/sooner_email.rb
21
+ homepage: https://sooner.dev
22
+ licenses:
23
+ - MIT
24
+ metadata:
25
+ source_code_uri: https://github.com/Quad-Labs-LLC/sooner-sdks/tree/main/ruby
26
+ documentation_uri: https://sooner.dev/docs
27
+ rdoc_options: []
28
+ require_paths:
29
+ - lib
30
+ required_ruby_version: !ruby/object:Gem::Requirement
31
+ requirements:
32
+ - - ">="
33
+ - !ruby/object:Gem::Version
34
+ version: '3.1'
35
+ required_rubygems_version: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ version: '0'
40
+ requirements: []
41
+ rubygems_version: 4.0.20
42
+ specification_version: 4
43
+ summary: First-party Ruby client for the Sooner email API
44
+ test_files: []