senddart 1.0.0 → 1.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.
@@ -16,17 +16,18 @@ module SendDart
16
16
  Client.request(:post, "/campaigns", body: params)
17
17
  end
18
18
 
19
- # GET /campaigns/:id
19
+ # GET /campaigns/:id (carries "updated_at")
20
20
  def get(campaign_id)
21
21
  Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}")
22
22
  end
23
23
 
24
- # GET /campaigns
24
+ # GET /campaigns (rows carry "updated_at")
25
25
  def list(params = {})
26
26
  Client.request(:get, "/campaigns", query: Client.pagination(params))
27
27
  end
28
28
 
29
- # PATCH /campaigns/:id (draft campaigns only). Accepts the create-side
29
+ # PATCH /campaigns/:id. A `{ name: }`-only rename is accepted in any
30
+ # status; every other change is draft-only. Accepts the create-side
30
31
  # fields plus `followups` (replace pending follow-ups, [] clears),
31
32
  # `list_to` (true/false), `unsubscribe_policy` ("account" | "domain" |
32
33
  # "ignore"), `schedule_timezone` (IANA zone; nil clears), and
@@ -76,6 +77,125 @@ module SendDart
76
77
  def delete(campaign_id)
77
78
  Client.request(:delete, "/campaigns/#{Client.path_escape(campaign_id)}")
78
79
  end
80
+
81
+ # Copy any campaign (whatever its status) into a new DRAFT, follow-up
82
+ # rules included. POST /campaigns/:id/duplicate
83
+ # Returns { "object" => "campaign", "id", "name" }.
84
+ def duplicate(campaign_id)
85
+ Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/duplicate")
86
+ end
87
+
88
+ # Send the campaign to 1-5 addresses to check it in a real inbox.
89
+ # POST /campaigns/:id/test (send scope) — params: { to: } (an Array, or
90
+ # one String; a comma-separated String is accepted). The subject gets a
91
+ # "[Test] " prefix, merge tags render sample/fallback values, and the
92
+ # campaign's status is unchanged. Pass { idempotency_key: "..." } as the
93
+ # third argument so a double submit cannot send twice.
94
+ # Returns { "object" => "email", "id", "to" => [...] }.
95
+ def test(campaign_id, params, options = {})
96
+ Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/test", body: params, options: options)
97
+ end
98
+
99
+ # Save the campaign's content as a new DRAFT template (422
100
+ # validation_error when the campaign has no content).
101
+ # POST /campaigns/:id/template — returns { "object" => "template", "id", "name" }.
102
+ def save_as_template(campaign_id)
103
+ Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/template")
104
+ end
105
+
106
+ # Resume a campaign the server `paused` (reputation or limit pause) once
107
+ # its checks pass. POST /campaigns/:id/continue (send scope)
108
+ # Returns { "id", "status" => "queued", "remaining" => Integer }. A 409
109
+ # validation_error means it is not paused, changed, or has nothing left;
110
+ # a 429 carries daily_quota_exceeded / plan-limit / reputation names.
111
+ # (`continue` is a Ruby keyword, hence the name.)
112
+ def continue_sending(campaign_id)
113
+ Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/continue")
114
+ end
115
+
116
+ # Recipients of this campaign that are now bounced.
117
+ # GET /campaigns/:id/bounced-contacts — { "count", "sample" (up to 25
118
+ # emails), "version" (64-hex) }. Pass `version` to remove_bounced_contacts.
119
+ def bounced_contacts(campaign_id)
120
+ Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/bounced-contacts")
121
+ end
122
+
123
+ # Remove the bounced contacts counted by bounced_contacts.
124
+ # POST /campaigns/:id/bounced-contacts — params: { version: } (from
125
+ # bounced_contacts). Returns { "removed" => Integer }. A 409
126
+ # validation_error means the list changed since — fetch it again.
127
+ def remove_bounced_contacts(campaign_id, params)
128
+ Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/bounced-contacts", body: params)
129
+ end
130
+
131
+ # Batch-by-batch send history. GET /campaigns/:id/batches
132
+ # Returns { "remaining_count", "current_batch_id", "can_send",
133
+ # "history_complete", "in_progress", "data" => [{ "id",
134
+ # "requested_count", "selected_count", "created_at", "attempted_count",
135
+ # "sent_count", "failed_count" }] } — newest first, at most 100, and NOT
136
+ # a paginated list (no "object"/"has_more").
137
+ def batches(campaign_id)
138
+ Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/batches")
139
+ end
140
+
141
+ # Add a follow-up to a `sending`/`sent` campaign (at most 5 active).
142
+ # POST /campaigns/:id/followups (write + send scope) — params:
143
+ # { condition: "delivered" | "opened" | "clicked" | "replied",
144
+ # delay_days: 0-7, delay_hours: 0-23, html: "...",
145
+ # subject: "..." (omit or "" to reuse the campaign's),
146
+ # auto_followup: true | false }
147
+ # Returns { "object" => "campaign_followup", "id", "recipients" }.
148
+ def create_followup(campaign_id, params)
149
+ Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/followups", body: params)
150
+ end
151
+
152
+ # GET /campaigns/:id/followups/:followup_id — the follow-up with its
153
+ # "condition", "delay_days", "delay_hours", "subject", "html", "status",
154
+ # "mode" ("manual" | "auto"), "run_at", "sent_count", "active" and
155
+ # "delivery_counts" ({ "pending", "sending", "sent", "failed", "canceled" }).
156
+ def get_followup(campaign_id, followup_id)
157
+ Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/followups/#{Client.path_escape(followup_id)}")
158
+ end
159
+
160
+ # Replace a follow-up. PATCH /campaigns/:id/followups/:followup_id
161
+ # Takes the FULL create_followup params again (validated the same way)
162
+ # plus optional `resend_previously_sent: true`.
163
+ # Returns { "object" => "campaign_followup", "id", "recipients" }.
164
+ def update_followup(campaign_id, followup_id, params)
165
+ Client.request(
166
+ :patch,
167
+ "/campaigns/#{Client.path_escape(campaign_id)}/followups/#{Client.path_escape(followup_id)}",
168
+ body: params
169
+ )
170
+ end
171
+
172
+ # One page of the people the campaign went to, optionally only one
173
+ # outcome. GET /campaigns/:id/recipients — params: { type: ("delivered",
174
+ # "opened", "clicked", "bounced", "complained", "failed", "suppressed"),
175
+ # limit: (1-100, 20), after: (the last row's "id") }. Rows: { "object" =>
176
+ # "campaign_recipient", "id", "email", "contact_id", "status",
177
+ # "sent_at", "opened_at", "clicked_at", "open_count", "click_count" }.
178
+ # Marketing analytics: paid marketing plans only.
179
+ def recipients(campaign_id, params = {})
180
+ query = Client.filters(params, :type, :limit, :after)
181
+ Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/recipients", query: query)
182
+ end
183
+
184
+ # Every tracked link with its click total, most-clicked first:
185
+ # { "object" => "list", "data" => [{ "object" => "campaign_link", "url",
186
+ # "clicks" }] }. GET /campaigns/:id/clicked-links — params: { limit:
187
+ # (1-100, 50) }. Marketing analytics: paid marketing plans only.
188
+ def clicked_links(campaign_id, params = {})
189
+ query = Client.filters(params, :limit)
190
+ Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/clicked-links", query: query)
191
+ end
192
+
193
+ # Cancel a follow-up (it is not hard-deleted).
194
+ # DELETE /campaigns/:id/followups/:followup_id
195
+ # Returns { "object" => "campaign_followup", "id", "canceled" => true }.
196
+ def delete_followup(campaign_id, followup_id)
197
+ Client.request(:delete, "/campaigns/#{Client.path_escape(campaign_id)}/followups/#{Client.path_escape(followup_id)}")
198
+ end
79
199
  end
80
200
  end
81
201
  end
@@ -16,6 +16,7 @@ module SendDart
16
16
  get: Net::HTTP::Get,
17
17
  post: Net::HTTP::Post,
18
18
  patch: Net::HTTP::Patch,
19
+ put: Net::HTTP::Put,
19
20
  delete: Net::HTTP::Delete
20
21
  }.freeze
21
22
 
@@ -36,10 +37,17 @@ module SendDart
36
37
  # the server be the authority.
37
38
  IDEMPOTENCY_KEY_MAX_LENGTH = 255
38
39
 
40
+ # Thread.current key behind SendDart.last_response. Thread.current[] is
41
+ # fiber-local, so concurrent threads (and fibers) never see each other's.
42
+ LAST_RESPONSE_KEY = :senddart_last_response
43
+
39
44
  # Perform an API request and return the parsed JSON body (a Hash/Array),
40
45
  # or the raw body String when `raw: true` (binary download endpoints).
41
46
  # Raises SendDart::Error on any non-2xx response.
42
47
  def request(verb, path, body: nil, query: nil, options: {}, raw: false)
48
+ # Cleared first, so a call that fails without a response (missing key,
49
+ # network error) never leaves an older call's headers behind.
50
+ Thread.current[LAST_RESPONSE_KEY] = nil
43
51
  key = SendDart.api_key
44
52
  if key.nil? || key.to_s.strip.empty?
45
53
  raise SendDart::Error.new(
@@ -54,7 +62,16 @@ module SendDart
54
62
  end
55
63
 
56
64
  req = build_request(verb, uri, body, options, key)
57
- handle_response(deliver_with_retries(req, uri), raw: raw)
65
+ resp = deliver_with_retries(req, uri)
66
+ handle_response(resp, raw: raw, response: record_response(resp))
67
+ end
68
+
69
+ # Snapshot the final attempt's status + headers as a SendDart::Response
70
+ # and publish it as SendDart.last_response for the current thread.
71
+ def record_response(resp)
72
+ response = Response.from_http(resp)
73
+ Thread.current[LAST_RESPONSE_KEY] = response
74
+ response
58
75
  end
59
76
 
60
77
  # The single request chokepoint: both the JSON and raw/binary paths funnel
@@ -166,7 +183,7 @@ module SendDart
166
183
  end
167
184
  end
168
185
 
169
- def handle_response(resp, raw: false)
186
+ def handle_response(resp, raw: false, response: nil)
170
187
  code = resp.code.to_i
171
188
  body = resp.body
172
189
 
@@ -193,7 +210,8 @@ module SendDart
193
210
  parsed["message"] || "Request failed with status #{code}",
194
211
  status_code: code,
195
212
  error_name: parsed["name"] || "application_error",
196
- body: parsed
213
+ body: parsed,
214
+ response: response
197
215
  )
198
216
  end
199
217
  end
@@ -251,6 +269,13 @@ module SendDart
251
269
  end
252
270
  end
253
271
 
272
+ # Like `filters`, for list endpoints that take comma lists: an Array value
273
+ # is sent comma-separated (`statuses`, `dimensions`, `from`...) instead
274
+ # of as a repeated key.
275
+ def list_filters(params, *keys)
276
+ filters(params, *keys).transform_values { |v| v.is_a?(Array) ? v.join(",") : v }
277
+ end
278
+
254
279
  # Domain-first guard: several resources require the sending domain.
255
280
  def require_domain!(params, context)
256
281
  v = opt(params, :domain)
@@ -122,11 +122,15 @@ module SendDart
122
122
  # Or a file already uploaded via create_import_upload (no row cap — the
123
123
  # overflow past your contact limit comes back as `limit_skipped`):
124
124
  # Contacts.import({ audience_id: "aud_1", storage_key: key })
125
+ # `mapping` maps CSV headers to fields: { "E-mail" => "email", "Notes" =>
126
+ # "ignore", "Company" => "company" } — "email", "first_name",
127
+ # "last_name", "unsubscribed", "ignore" or a property key; one column
128
+ # must be email and a field is used once.
125
129
  def import(params)
126
130
  audience_id = Client.opt(params, :audience_id)
127
131
  query = Client.filters(params, :on_conflict, :segment_id)
128
132
  query[:create_properties] = "false" if Client.opt(params, :create_properties) == false
129
- body = Client.filters(params, :csv, :file_name, :storage_key)
133
+ body = Client.filters(params, :csv, :file_name, :storage_key, :mapping)
130
134
  Client.request(
131
135
  :post,
132
136
  "/audiences/#{Client.path_escape(audience_id)}/contacts/import",
@@ -149,6 +153,25 @@ module SendDart
149
153
  )
150
154
  end
151
155
 
156
+ # Dry-run an uploaded CSV before importing it: nothing is written.
157
+ # POST /audiences/:id/contacts/import/preview — params:
158
+ # { audience_id:, storage_key:, mapping: } (the key from
159
+ # create_import_upload, after you PUT the file; `mapping` as in
160
+ # `import`). Returns { "object" => "contact_import_preview", "file_name",
161
+ # "size_bytes", "has_header", "header_row", "header_is_data", "mapping",
162
+ # "columns", "property_keys", "source_rows", "valid_rows",
163
+ # "unique_contacts", "duplicate_rows", "invalid_rows",
164
+ # "existing_contacts", "new_contacts", "sample" (up to 20 parsed
165
+ # contacts), "warnings" }.
166
+ def preview_import(params)
167
+ audience_id = Client.opt(params, :audience_id)
168
+ Client.request(
169
+ :post,
170
+ "/audiences/#{Client.path_escape(audience_id)}/contacts/import/preview",
171
+ body: Client.without(params, :audience_id)
172
+ )
173
+ end
174
+
152
175
  # Add a contact to a segment. POST /contacts/:id/segments/:segment_id
153
176
  def add_to_segment(contact_id, segment_id)
154
177
  Client.request(:post, "/contacts/#{Client.path_escape(contact_id)}/segments/#{Client.path_escape(segment_id)}")
@@ -2,6 +2,11 @@
2
2
 
3
3
  module SendDart
4
4
  module Domains
5
+ # The deprecation message every retired DNS auto-setup method prints.
6
+ DNS_SETUP_DEPRECATION = "Automatic DNS setup was retired on 2026-10-15; the API now answers 410 " \
7
+ "dns_setup_disabled. Add the records from Domains.get / Domains.records_csv at your " \
8
+ "DNS provider. This method will be removed in 2.0."
9
+
5
10
  class << self
6
11
  # HTTPS readiness; an unavailable host schedules server-side repair.
7
12
  def tracking_health(domain_id)
@@ -67,19 +72,34 @@ module SendDart
67
72
 
68
73
  # Detect the DNS provider and available one-click apply methods.
69
74
  # GET /domains/:id/dns/detect
75
+ #
76
+ # @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
77
+ # answers 410 dns_setup_disabled. Add the records from Domains.get /
78
+ # Domains.records_csv at your DNS provider. Removed in 2.0.
70
79
  def detect_dns(domain_id)
80
+ warn_dns_deprecated(:detect_dns)
71
81
  Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/dns/detect")
72
82
  end
73
83
 
74
84
  # Apply DNS records via the Cloudflare API, then auto-verify.
75
85
  # POST /domains/:id/dns/cloudflare — params: { token: "..." }
86
+ #
87
+ # @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
88
+ # answers 410 dns_setup_disabled. Add the records from Domains.get /
89
+ # Domains.records_csv at your DNS provider. Removed in 2.0.
76
90
  def apply_cloudflare_dns(domain_id, params)
91
+ warn_dns_deprecated(:apply_cloudflare_dns)
77
92
  Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/cloudflare", body: params)
78
93
  end
79
94
 
80
95
  # Apply DNS records via the GoDaddy API, then auto-verify.
81
96
  # POST /domains/:id/dns/godaddy — params: { key: "...", secret: "..." }
97
+ #
98
+ # @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
99
+ # answers 410 dns_setup_disabled. Add the records from Domains.get /
100
+ # Domains.records_csv at your DNS provider. Removed in 2.0.
82
101
  def apply_godaddy_dns(domain_id, params)
102
+ warn_dns_deprecated(:apply_godaddy_dns)
83
103
  Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/godaddy", body: params)
84
104
  end
85
105
 
@@ -90,7 +110,12 @@ module SendDart
90
110
  # are accepted aliases, and the optional username may also be spelled
91
111
  # `username`, but there is NO `user_name` alias: the API ignores that key,
92
112
  # so a username sent under it is silently dropped.
113
+ #
114
+ # @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
115
+ # answers 410 dns_setup_disabled. Add the records from Domains.get /
116
+ # Domains.records_csv at your DNS provider. Removed in 2.0.
93
117
  def apply_namecheap_dns(domain_id, params)
118
+ warn_dns_deprecated(:apply_namecheap_dns)
94
119
  Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/namecheap", body: params)
95
120
  end
96
121
 
@@ -98,6 +123,14 @@ module SendDart
98
123
  def delete(domain_id)
99
124
  Client.request(:delete, "/domains/#{Client.path_escape(domain_id)}")
100
125
  end
126
+
127
+ private
128
+
129
+ # Kernel#warn goes to $stderr and is silenced by `ruby -W0` ($VERBOSE nil).
130
+ # The request still goes out, so existing callers keep working until 2.0.
131
+ def warn_dns_deprecated(method_name)
132
+ warn "[DEPRECATION] SendDart::Domains.#{method_name} is deprecated. #{DNS_SETUP_DEPRECATION}"
133
+ end
101
134
  end
102
135
  end
103
136
  end
@@ -36,10 +36,23 @@ module SendDart
36
36
  # against the row's `last_event`), `folder` (one of "outbox", "sent",
37
37
  # "scheduled" or "failed" — any other value is rejected with a 422) and
38
38
  # `search` (recipients, subject and sender). `q` is the server's alias
39
- # for `search`, honoured only when `search` is absent. GET /emails
39
+ # for `search`, honoured only when `search` is absent.
40
+ # Also: `engagement` ("delivered", "opened", "clicked", "replied",
41
+ # "bounced" or "complained"), `campaign_scope` ("direct" — one-off sends
42
+ # only, no campaign mail), and `created_after` / `created_before` (ISO
43
+ # 8601 date-times such as "2026-01-31T00:00:00Z"; after must be earlier
44
+ # than before, and a malformed value is a 422). They are `created_*`
45
+ # because `after`/`before` are the pagination cursors.
46
+ # `statuses` (an Array or comma list of bounced, canceled, clicked,
47
+ # complained, delivered, delivery_delayed, failed, opened, queued,
48
+ # replied, scheduled, sent, suppressed — merged with `status`; an unknown
49
+ # one is a 422), `api_key_id` (the key that sent it) and `query` (alias
50
+ # of `search`) narrow it further. GET /emails
40
51
  def list(params = {})
41
52
  query = Client.pagination(params).merge(
42
- Client.filters(params, :campaign_id, :automation_id, :source, :domain_id, :status, :search, :q, :folder)
53
+ Client.list_filters(params, :campaign_id, :automation_id, :source, :domain_id, :status, :statuses,
54
+ :api_key_id, :search, :query, :q, :folder, :engagement, :campaign_scope,
55
+ :created_after, :created_before)
43
56
  )
44
57
  Client.request(:get, "/emails", query: query)
45
58
  end
@@ -53,6 +66,28 @@ module SendDart
53
66
  Client.request(:get, "/emails/sources")
54
67
  end
55
68
 
69
+ # What happened to the account's email over a window of UTC days.
70
+ # GET /emails/metrics — params: { start_date:, end_date: (YYYY-MM-DD;
71
+ # default the last 7 days, at most 92), dimensions: (Array or comma list
72
+ # of "period", "domain", "campaign"), domain_id:, campaign_id: (Array or
73
+ # comma list) }. Returns { "object" => "list", "start_date", "end_date",
74
+ # "dimensions", "data" => [{ "period"?, "domain_id"?, "campaign_id"?,
75
+ # "sent", "delivered", "delivery_delayed", "opened", "clicked",
76
+ # "bounced", "complained", "failed" }] }.
77
+ def metrics(params = {})
78
+ query = Client.list_filters(params, :start_date, :end_date, :dimensions, :domain_id, :campaign_id,
79
+ :broadcast_id)
80
+ Client.request(:get, "/emails/metrics", query: query)
81
+ end
82
+
83
+ # Create a public, read-only link to one sent email, valid 48 hours (a
84
+ # new link revokes the previous one; the URL is only in this answer).
85
+ # Needs write access. Returns { "object" => "email_share", "email_id",
86
+ # "url", "expires_at" }. POST /emails/:id/share
87
+ def share(email_id)
88
+ Client.request(:post, "/emails/#{Client.path_escape(email_id)}/share")
89
+ end
90
+
56
91
  # Retrieve a sent email and its events. GET /emails/:id
57
92
  def get(email_id)
58
93
  Client.request(:get, "/emails/#{Client.path_escape(email_id)}")
@@ -83,13 +118,17 @@ module SendDart
83
118
  # Inbound (received) email.
84
119
  module Receiving
85
120
  class << self
86
- # List received emails — cursor pagination plus an optional
87
- # `received_for` filter (only messages received for that address).
121
+ # List received emails — cursor pagination plus optional filters:
122
+ # `received_for` (only messages received for that address), `search`
123
+ # (or its alias `query`) and `created_after` / `created_before` (ISO
124
+ # 8601; a malformed date is a 422).
88
125
  # With no `limit` and no cursor the endpoint returns up to 1000 rows in
89
126
  # one response; pass `limit` to get normal 1-100 pages.
90
127
  # GET /emails/receiving
91
128
  def list(params = {})
92
- query = Client.pagination(params).merge(Client.filters(params, :received_for))
129
+ query = Client.pagination(params).merge(
130
+ Client.filters(params, :received_for, :search, :query, :created_after, :created_before)
131
+ )
93
132
  Client.request(:get, "/emails/receiving", query: query)
94
133
  end
95
134
 
@@ -104,6 +143,13 @@ module SendDart
104
143
  Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}")
105
144
  end
106
145
 
146
+ # Mark a received email read or unread (write scope).
147
+ # PATCH /emails/receiving/:id — params: { read: true | false }
148
+ # Returns the full received email, including "read" and "read_at".
149
+ def update(email_id, params)
150
+ Client.request(:patch, "/emails/receiving/#{Client.path_escape(email_id)}", body: params)
151
+ end
152
+
107
153
  # List a received email's attachments. With no `limit` and no `after`
108
154
  # one page carries up to 1,000 of them and `has_more` reports any
109
155
  # truncation; supplying either paginates normally.
@@ -30,6 +30,8 @@ module SendDart
30
30
  # e.reputation # reputation gates
31
31
  # e.sent # a batch that failed part way through
32
32
  # e.sent_count # — do NOT resend these
33
+ # e.waiting; e.oldest # 409 waiting_enrollments
34
+ # e.rate_limit&.retry_after # parsed response headers
33
35
  # end
34
36
  class Error < StandardError
35
37
  attr_reader :status_code, :error_name
@@ -38,11 +40,46 @@ module SendDart
38
40
  # Read it for any additive field newer than this SDK version.
39
41
  attr_reader :body
40
42
 
41
- def initialize(message = nil, status_code: nil, error_name: nil, body: nil)
43
+ # The SendDart::Response (status + headers) of the failed request, or nil
44
+ # for an error raised before any request went out (e.g. missing_api_key).
45
+ attr_reader :response
46
+
47
+ def initialize(message = nil, status_code: nil, error_name: nil, body: nil, response: nil)
42
48
  super(message)
43
49
  @status_code = status_code
44
50
  @error_name = error_name
45
51
  @body = body.is_a?(Hash) ? body : {}
52
+ @response = response
53
+ end
54
+
55
+ # The failed response's headers (lower-cased keys), {} when there was none.
56
+ def headers
57
+ @response ? @response.headers : {}
58
+ end
59
+
60
+ # The parsed RateLimit-* / Retry-After headers (a SendDart::RateLimit),
61
+ # or nil when there was no response. Most useful on a 429:
62
+ #
63
+ # rescue SendDart::Error => e
64
+ # sleep(e.rate_limit.retry_after || 1) if e.status_code == 429
65
+ def rate_limit
66
+ @response&.rate_limit
67
+ end
68
+
69
+ # How many contacts are waiting, on a 409 `waiting_enrollments` (enabling
70
+ # an automation whose contacts have waited over an hour), else nil.
71
+ # Repeat Automations.update with `on_waiting: "resume"` (run their next
72
+ # step now) or `"skip_waiting"` (skip them; enable for new contacts only).
73
+ def waiting
74
+ value = @body["waiting"]
75
+ value.is_a?(Integer) ? value : nil
76
+ end
77
+
78
+ # ISO 8601 time the longest-waiting contact started waiting, on a 409
79
+ # `waiting_enrollments`, else nil (also nil when the API sent null).
80
+ def oldest
81
+ value = @body["oldest"]
82
+ value.is_a?(String) ? value : nil
46
83
  end
47
84
 
48
85
  # The API error `name` (e.g. "validation_error", "not_found").
@@ -39,6 +39,13 @@ module SendDart
39
39
  Client.request(:patch, "/events/#{Client.path_escape(event_id)}", body: params)
40
40
  end
41
41
 
42
+ # One custom-event definition by its id OR its name: { "object" =>
43
+ # "event", "id", "name", "schema", "created_at", "updated_at" }.
44
+ # GET /events/:id
45
+ def get(event_id)
46
+ Client.request(:get, "/events/#{Client.path_escape(event_id)}")
47
+ end
48
+
42
49
  # List custom-event definitions. GET /events
43
50
  def list(params = {})
44
51
  Client.request(:get, "/events", query: Client.pagination(params))