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.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/README.md +43 -0
- data/lib/sooner_email.rb +203 -0
- 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.
|
data/lib/sooner_email.rb
ADDED
|
@@ -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: []
|