generatorlabs 2.0.0 → 2.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8e830c5a4cd5b0df22bf19efaf939efe353e910cd65498a986f9e066f4d1faa3
4
- data.tar.gz: 5038ebd57fea4966821b853c9930fb70046283051a51c5fc18821246bc8e126f
3
+ metadata.gz: b56287766310bf553d8a755f9cc91fd9470684f9d1a28e1e9ce095562c79e00a
4
+ data.tar.gz: a7a6441ed417f75c02acbdbdaa1fb500d5323b9b1560da729c4dd73c528eab89
5
5
  SHA512:
6
- metadata.gz: 8229f18ff07f6e03e72ebd130f3432222a38db4afa3badc5f31ced4bf8e943044f4064a355ec275b14377d80cf2aac75c18f1be25969b6048acf353b51ab7448
7
- data.tar.gz: 86e8aeda04eab53cf2898431f61093deb99e0005cf1eb8f3a8baac516f48219032d7fe9aa879d0c532dcb1b393b5c9d8f270245a548ec6cfba2751f22f557091
6
+ metadata.gz: d179bd66d1e6890c89966b4001b38ab4c20af77b35fd78358967e73a8b64d5d713062f493ebd87814cede86cc1126717a789bfaf0ca418557dfbc1b19803f124
7
+ data.tar.gz: 857ef149b49bc901b4412cdb0a5bbdf9403e6c69f71814bf51f49a6511f8d9df28d6309067912ca6b04574ec4fdaef7042dc9233435fa6b8169f62ef9080e51a
data/README.md CHANGED
@@ -16,8 +16,10 @@ Official Ruby SDK for the [Generator Labs API](https://generatorlabs.com). This
16
16
  - [Client Initialization](#client-initialization)
17
17
  - [Configuration Options](#configuration-options)
18
18
  - [Pagination](#pagination)
19
+ - [Request Options](#request-options)
20
+ - [Account](#account)
19
21
  - [RBL Monitoring](#rbl-monitoring) - [Hosts](#hosts) | [Profiles](#profiles) | [Sources](#sources) | [Check & Listings](#check--listings)
20
- - [Certificate Monitoring](#certificate-monitoring) - [Errors](#errors) | [Monitors](#monitors) | [Profiles](#profiles-1)
22
+ - [Certificate Monitoring](#certificate-monitoring) - [Errors](#errors) | [Monitors](#monitors) | [Findings](#findings) | [Profiles](#profiles-1)
21
23
  - [Contact Management](#contact-management) - [Contacts](#contacts) | [Groups](#groups)
22
24
  - [Error Handling](#error-handling)
23
25
  - [Retry Logic](#retry-logic)
@@ -177,6 +179,68 @@ all_contacts = client.contact.contacts.get_all
177
179
  all_groups = client.contact.groups.get_all
178
180
  ```
179
181
 
182
+ ### Request Options
183
+
184
+ Every resource method takes a `GeneratorLabs::RequestOptions` as its last argument: `idempotency_key`, `request_id`, `if_none_match` and `fields`.
185
+
186
+ **Idempotency keys.** Requests that create something (`create`), a contact `resend` or `confirm`, the certificate monitor `delete`, and the two check requests (`rbl.check.start`, `cert.monitors.check`) are sent with an `Idempotency-Key` header. The SDK generates one key per call and sends the same key on every automatic retry of that call, so a retry after a timeout never creates, sends, bills or deletes anything twice. Pass your own key to make a repeat of the call from your code safe as well:
187
+
188
+ ```ruby
189
+ options = GeneratorLabs::RequestOptions.new(idempotency_key: 'b0e1f6a2-4d7c-4b43-9d3c-3f1c5a9f2e11')
190
+ host = client.rbl.hosts.create({ name: 'My Mail Server', host: '192.168.1.100' }, options)
191
+
192
+ # true when the API answered with the result of an earlier request with the same key
193
+ puts host.replayed
194
+ ```
195
+
196
+ The same key with a different request is refused with a 422.
197
+
198
+ **Request IDs.** Every response carries an `X-Request-Id`, available as `request_id` on the response and on `GeneratorLabs::Error`. Quote it when you contact support about a request. You can also send your own (1 to 64 letters, digits, `-`, `_`, `.` or `:`):
199
+
200
+ ```ruby
201
+ begin
202
+ hosts = client.rbl.hosts.get(GeneratorLabs::RequestOptions.new(request_id: 'my-request-1'))
203
+ puts hosts.request_id
204
+ rescue GeneratorLabs::Error => e
205
+ puts "#{e.status_code} #{e.request_id}"
206
+ end
207
+ ```
208
+
209
+ **Conditional requests.** Every `GET` response carries an `ETag`. Send it back as `if_none_match`: when nothing has changed the API answers `304 Not Modified`, and the response has `not_modified` set and no data.
210
+
211
+ ```ruby
212
+ hosts = client.rbl.hosts.get
213
+
214
+ later = client.rbl.hosts.get(GeneratorLabs::RequestOptions.new(if_none_match: hosts.etag))
215
+ hosts = later unless later.not_modified
216
+ ```
217
+
218
+ **Field selection.** Any `GET` takes `fields` (an Array, or a comma-separated String) to keep only those keys in each object of `data`. A nested key is written with a dot. A field no object has is refused with a 422.
219
+
220
+ ```ruby
221
+ options = GeneratorLabs::RequestOptions.new(fields: %w[id host listed])
222
+
223
+ host = client.rbl.hosts.get('HT1a2b3c4d5e6f7890abcdef1234567890', options)
224
+ hosts = client.rbl.hosts.get({ page_size: 50 }, options)
225
+ ```
226
+
227
+ ### Account
228
+
229
+ ```ruby
230
+ # The account: balance, whether scheduled checks are running, and plan usage
231
+ account = client.account.get
232
+
233
+ # The account balance, as a Float
234
+ balance = client.account.balance
235
+
236
+ # Usage by month, for the last 3 months
237
+ usage = client.account.usage(months: 3)
238
+
239
+ # Pause and resume the account's scheduled checks
240
+ client.account.pause_checks
241
+ client.account.resume_checks
242
+ ```
243
+
180
244
  ### RBL Monitoring
181
245
 
182
246
  #### Hosts
@@ -188,9 +252,6 @@ hosts = client.rbl.hosts.get
188
252
  # Get a specific host
189
253
  host = client.rbl.hosts.get('HT1a2b3c4d5e6f7890abcdef1234567890')
190
254
 
191
- # Get multiple hosts
192
- hosts = client.rbl.hosts.get('HT1a2b3c4d5e6f7890abcdef1234567890', 'HT2b3c4d5e6f7890abcdef12345678901a')
193
-
194
255
  # Create a host
195
256
  host = client.rbl.hosts.create(
196
257
  host: '8.8.8.8',
@@ -281,6 +342,9 @@ status = client.rbl.check.status('check_id')
281
342
 
282
343
  # Get current listings
283
344
  listings = client.rbl.listings
345
+
346
+ # Get the second page of listings
347
+ listings = client.rbl.listings(page: 2)
284
348
  ```
285
349
 
286
350
  ### Certificate Monitoring
@@ -294,6 +358,11 @@ Certificate monitoring allows you to monitor SSL/TLS certificates for expiration
294
358
  errors = client.cert.errors.get
295
359
  ```
296
360
 
361
+ ```ruby
362
+ # The number of current certificate warnings and errors
363
+ count = client.cert.errors.count
364
+ ```
365
+
297
366
  #### Monitors
298
367
 
299
368
  ```ruby
@@ -330,6 +399,30 @@ result = client.cert.monitors.pause('CM62944aeeee2b46d7a28221164f38976a')
330
399
 
331
400
  # Resume monitoring
332
401
  result = client.cert.monitors.resume('CM62944aeeee2b46d7a28221164f38976a')
402
+
403
+ # Queue a check now, instead of waiting for the next scheduled check
404
+ result = client.cert.monitors.check('CM62944aeeee2b46d7a28221164f38976a')
405
+ ```
406
+
407
+ #### Findings
408
+
409
+ Findings are everything the last check of each active monitor found: errors, warnings and notices, whatever the profile's alert settings. Some findings can be dismissed, and restored later.
410
+
411
+ ```ruby
412
+ # List the current findings, one entry per monitor
413
+ findings = client.cert.findings.get
414
+
415
+ # Include the findings dismissed from each monitor
416
+ findings = client.cert.findings.get(dismissed: 1)
417
+
418
+ # Dismiss findings on named monitors (leave monitors out for every monitor that has them)
419
+ result = client.cert.findings.dismiss(
420
+ finding_id: %w[CERT_CAA01 CERT_CAA02],
421
+ monitors: ['CM62944aeeee2b46d7a28221164f38976a']
422
+ )
423
+
424
+ # Restore dismissed findings
425
+ result = client.cert.findings.restore(finding_id: 'CERT_CAA01')
333
426
  ```
334
427
 
335
428
  #### Profiles
@@ -373,9 +466,6 @@ contacts = client.contact.contacts.get
373
466
  # Get a specific contact
374
467
  contact = client.contact.contacts.get('COabcdef1234567890abcdef1234567890')
375
468
 
376
- # Get multiple contacts
377
- contacts = client.contact.contacts.get('COabcdef1234567890abcdef1234567890', 'CO1234567890abcdef1234567890abcdef')
378
-
379
469
  # Create a contact
380
470
  contact = client.contact.contacts.create(
381
471
  contact: 'user@example.com',
@@ -441,6 +531,7 @@ The SDK automatically retries failed requests with exponential backoff:
441
531
  - Configurable maximum retry attempts (default: 3)
442
532
  - Retries on connection errors, 5xx server errors, and 429 rate limits
443
533
  - Respects `Retry-After` header on 429 responses before falling back to exponential backoff
534
+ - A `Retry-After` longer than 60 seconds is not waited out: the 429 is raised as the error instead
444
535
  - Configurable exponential backoff multiplier (default: 1.0 for 1s, 2s, 4s delays)
445
536
  - Configurable connection timeout (default: 5 seconds)
446
537
  - Configurable request timeout (default: 30 seconds)
@@ -520,6 +611,20 @@ For security best practices and vulnerability reporting, see [SECURITY.md](SECUR
520
611
 
521
612
  ## Release History
522
613
 
614
+ ### v2.1.0 (2026-11-19)
615
+ * Added `client.account` (account, balance, usage, pause and resume scheduled checks)
616
+ * Added `client.cert.findings` (list, dismiss, restore), `client.cert.monitors.check` and `client.cert.errors.count`
617
+ * Added request options (`GeneratorLabs::RequestOptions`): `idempotency_key`, `request_id`, `if_none_match` and `fields`
618
+ * Automatic `Idempotency-Key` on requests that create something or start a check, reused on every retry
619
+ * `Response` exposes `request_id`, `etag`, `replayed` and `not_modified`; `Error` carries the `request_id`
620
+ * A `Retry-After` longer than 60 seconds is raised as the error, not waited out
621
+ * Fixed `get_all` returning an empty list, and retries waiting for the `RateLimit-Reset` time
622
+ * `get` takes a single ID; the form with several IDs is removed
623
+
624
+ ### v2.0.1 (2026-06-19)
625
+ * Error detection now reads the API `status_code` and `status_message`; any `status_code` (or HTTP status) of 400 or greater raises `Error` with the API message
626
+ * `Error` now exposes a `status_code` reader
627
+
523
628
  ### v2.0.0 (2026-01-31)
524
629
  * Complete rewrite for Generator Labs API v4.0
525
630
  * RESTful endpoint design with proper HTTP verbs
@@ -0,0 +1,55 @@
1
+ # frozen_string_literal: true
2
+
3
+ #
4
+ # This file is part of the Generator Labs Ruby SDK package.
5
+ #
6
+ # (c) Generator Labs <support@generatorlabs.com>
7
+ #
8
+ # For the full copyright and license information, please view the LICENSE
9
+ # file that was distributed with this source code.
10
+ #
11
+
12
+ module GeneratorLabs
13
+ # Account namespace: the account, its balance, its usage and its scheduled checks
14
+ class Account
15
+ def initialize(handler)
16
+ @handler = handler
17
+ end
18
+
19
+ # Get the account: its balance, whether its checks are running, and plan usage
20
+ # @param options [RequestOptions, nil] Request options
21
+ # @return [Hash] Account data
22
+ def get(options = nil)
23
+ @handler.get('account', nil, options)
24
+ end
25
+
26
+ # Get the account balance
27
+ # @param options [RequestOptions, nil] Request options
28
+ # @return [Float] Account balance
29
+ def balance(options = nil)
30
+ Float(@handler.get_plain('account/balance', options))
31
+ end
32
+
33
+ # Get the account's usage by month
34
+ # @param params [Hash] Optional parameters (months)
35
+ # @param options [RequestOptions, nil] Request options
36
+ # @return [Hash] Usage of each month
37
+ def usage(params = {}, options = nil)
38
+ @handler.get('account/usage', params, options)
39
+ end
40
+
41
+ # Pause the account's scheduled checks
42
+ # @param options [RequestOptions, nil] Request options
43
+ # @return [Hash] Result
44
+ def pause_checks(options = nil)
45
+ @handler.post('account/checks/pause', nil, options)
46
+ end
47
+
48
+ # Resume the account's scheduled checks
49
+ # @param options [RequestOptions, nil] Request options
50
+ # @return [Hash] Result
51
+ def resume_checks(options = nil)
52
+ @handler.post('account/checks/resume', nil, options)
53
+ end
54
+ end
55
+ end
@@ -22,6 +22,12 @@ module GeneratorLabs
22
22
  @errors ||= CertErrors.new(@handler)
23
23
  end
24
24
 
25
+ # Access certificate finding operations
26
+ # @return [CertFindings]
27
+ def findings
28
+ @findings ||= CertFindings.new(@handler)
29
+ end
30
+
25
31
  # Access certificate monitor management operations
26
32
  # @return [CertMonitors]
27
33
  def monitors
@@ -43,9 +49,17 @@ module GeneratorLabs
43
49
 
44
50
  # Get certificate errors
45
51
  # @param params [nil, Hash] Optional parameters
52
+ # @param options [RequestOptions, nil] Request options
46
53
  # @return [Hash] Error data
47
- def get(params = {})
48
- @handler.get('cert/errors', params)
54
+ def get(params = {}, options = nil)
55
+ @handler.get('cert/errors', params, options)
56
+ end
57
+
58
+ # Get the number of current certificate warnings and errors
59
+ # @param options [RequestOptions, nil] Request options
60
+ # @return [Integer] Number of warnings and errors
61
+ def count(options = nil)
62
+ Integer(@handler.get_plain('cert/errors/count', options))
49
63
  end
50
64
 
51
65
  # Get all errors with automatic pagination
@@ -59,7 +73,7 @@ module GeneratorLabs
59
73
  loop do
60
74
  params[:page] = page
61
75
  response = get(params)
62
- errors = response['errors'] || []
76
+ errors = response['data'] || []
63
77
 
64
78
  all_items.concat(errors)
65
79
 
@@ -72,24 +86,73 @@ module GeneratorLabs
72
86
  end
73
87
  end
74
88
 
75
- # Certificate monitor management
76
- class CertMonitors
89
+ # Certificate findings: list, dismiss and restore
90
+ class CertFindings
77
91
  def initialize(handler)
78
92
  @handler = handler
79
93
  end
80
94
 
81
- # Get monitors (all, by ID, or by array of IDs)
82
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
83
- # @return [Hash] Monitor data
84
- def get(*ids)
85
- return @handler.get('cert/monitors') if ids.empty?
95
+ # Get the current findings on the active certificate monitors
96
+ # @param params [Hash] Optional parameters (page, page_size, dismissed)
97
+ # @param options [RequestOptions, nil] Request options
98
+ # @return [Hash] One entry per monitor, each with its findings
99
+ def get(params = {}, options = nil)
100
+ @handler.get('cert/findings', params, options)
101
+ end
102
+
103
+ # Get the findings of every monitor with automatic pagination
104
+ # @param params [Hash] Optional parameters (e.g., page_size, dismissed)
105
+ # @return [Array] All monitors with findings across all pages
106
+ def get_all(params = {})
107
+ all_items = []
108
+ page = 1
109
+ params = params.dup
110
+
111
+ loop do
112
+ params[:page] = page
113
+ response = get(params)
114
+ monitors = response['data'] || []
115
+
116
+ all_items.concat(monitors)
117
+
118
+ break unless page < (response['total_pages'] || 1) && !monitors.empty?
86
119
 
87
- # Check if first argument is a hash (parameters)
88
- return @handler.get('cert/monitors', ids.first) if ids.first.is_a?(Hash)
120
+ page += 1
121
+ end
89
122
 
90
- return @handler.get("cert/monitors/#{ids.first}") if ids.length == 1
123
+ all_items
124
+ end
91
125
 
92
- @handler.get('cert/monitors', { ids: ids.join(',') })
126
+ # Dismiss findings
127
+ # @param params [Hash] Findings to dismiss (finding_id, monitors); without monitors,
128
+ # from every active monitor that has the finding
129
+ # @param options [RequestOptions, nil] Request options
130
+ # @return [Hash] Monitors changed
131
+ def dismiss(params, options = nil)
132
+ @handler.post('cert/findings/dismiss', params, options)
133
+ end
134
+
135
+ # Restore dismissed findings
136
+ # @param params [Hash] Findings to restore (finding_id, monitors); without monitors,
137
+ # on every monitor the finding is dismissed from
138
+ # @param options [RequestOptions, nil] Request options
139
+ # @return [Hash] Monitors changed
140
+ def restore(params, options = nil)
141
+ @handler.post('cert/findings/restore', params, options)
142
+ end
143
+ end
144
+
145
+ # Certificate monitor management
146
+ class CertMonitors
147
+ def initialize(handler)
148
+ @handler = handler
149
+ end
150
+
151
+ # Get monitors (all, or one by ID)
152
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
153
+ # @return [Hash] Monitor data
154
+ def get(*args)
155
+ @handler.get(*GeneratorLabs.get_args('cert/monitors', args))
93
156
  end
94
157
 
95
158
  # Get all monitors with automatic pagination
@@ -103,7 +166,7 @@ module GeneratorLabs
103
166
  loop do
104
167
  params[:page] = page
105
168
  response = get(params)
106
- monitors = response['monitors'] || []
169
+ monitors = response['data'] || []
107
170
 
108
171
  all_items.concat(monitors)
109
172
 
@@ -117,38 +180,51 @@ module GeneratorLabs
117
180
 
118
181
  # Create a new certificate monitor
119
182
  # @param params [Hash] Monitor parameters
183
+ # @param options [RequestOptions, nil] Request options
120
184
  # @return [Hash] Created monitor data
121
- def create(params)
122
- @handler.post('cert/monitors', params)
185
+ def create(params, options = nil)
186
+ @handler.post('cert/monitors', params, options, idempotent: true)
123
187
  end
124
188
 
125
189
  # Update a certificate monitor
126
190
  # @param id [String, Integer] Monitor ID
127
191
  # @param params [Hash] Updated parameters
192
+ # @param options [RequestOptions, nil] Request options
128
193
  # @return [Hash] Updated monitor data
129
- def update(id, params)
130
- @handler.put("cert/monitors/#{id}", params)
194
+ def update(id, params, options = nil)
195
+ @handler.put("cert/monitors/#{id}", params, options)
131
196
  end
132
197
 
133
198
  # Delete a certificate monitor
134
199
  # @param id [String, Integer] Monitor ID
200
+ # @param options [RequestOptions, nil] Request options
135
201
  # @return [Hash] Deletion confirmation
136
- def delete(id)
137
- @handler.delete("cert/monitors/#{id}")
202
+ def delete(id, options = nil)
203
+ @handler.delete("cert/monitors/#{id}", options, idempotent: true)
138
204
  end
139
205
 
140
206
  # Pause monitoring for a certificate
141
207
  # @param id [String, Integer] Monitor ID
208
+ # @param options [RequestOptions, nil] Request options
142
209
  # @return [Hash] Response
143
- def pause(id)
144
- @handler.post("cert/monitors/#{id}/pause")
210
+ def pause(id, options = nil)
211
+ @handler.post("cert/monitors/#{id}/pause", nil, options)
145
212
  end
146
213
 
147
214
  # Resume monitoring for a certificate
148
215
  # @param id [String, Integer] Monitor ID
216
+ # @param options [RequestOptions, nil] Request options
149
217
  # @return [Hash] Response
150
- def resume(id)
151
- @handler.post("cert/monitors/#{id}/resume")
218
+ def resume(id, options = nil)
219
+ @handler.post("cert/monitors/#{id}/resume", nil, options)
220
+ end
221
+
222
+ # Queue a check of a monitor now
223
+ # @param id [String] Monitor ID
224
+ # @param options [RequestOptions, nil] Request options
225
+ # @return [Hash] Queued check
226
+ def check(id, options = nil)
227
+ @handler.post("cert/monitors/#{id}/check", nil, options, idempotent: true)
152
228
  end
153
229
  end
154
230
 
@@ -158,18 +234,11 @@ module GeneratorLabs
158
234
  @handler = handler
159
235
  end
160
236
 
161
- # Get profiles (all, by ID, or by array of IDs)
162
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
237
+ # Get profiles (all, or one by ID)
238
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
163
239
  # @return [Hash] Profile data
164
- def get(*ids)
165
- return @handler.get('cert/profiles') if ids.empty?
166
-
167
- # Check if first argument is a hash (parameters)
168
- return @handler.get('cert/profiles', ids.first) if ids.first.is_a?(Hash)
169
-
170
- return @handler.get("cert/profiles/#{ids.first}") if ids.length == 1
171
-
172
- @handler.get('cert/profiles', { ids: ids.join(',') })
240
+ def get(*args)
241
+ @handler.get(*GeneratorLabs.get_args('cert/profiles', args))
173
242
  end
174
243
 
175
244
  # Get all profiles with automatic pagination
@@ -183,7 +252,7 @@ module GeneratorLabs
183
252
  loop do
184
253
  params[:page] = page
185
254
  response = get(params)
186
- profiles = response['profiles'] || []
255
+ profiles = response['data'] || []
187
256
 
188
257
  all_items.concat(profiles)
189
258
 
@@ -197,24 +266,27 @@ module GeneratorLabs
197
266
 
198
267
  # Create a new certificate monitoring profile
199
268
  # @param params [Hash] Profile parameters
269
+ # @param options [RequestOptions, nil] Request options
200
270
  # @return [Hash] Created profile data
201
- def create(params)
202
- @handler.post('cert/profiles', params)
271
+ def create(params, options = nil)
272
+ @handler.post('cert/profiles', params, options, idempotent: true)
203
273
  end
204
274
 
205
275
  # Update a certificate monitoring profile
206
276
  # @param id [String, Integer] Profile ID
207
277
  # @param params [Hash] Updated parameters
278
+ # @param options [RequestOptions, nil] Request options
208
279
  # @return [Hash] Updated profile data
209
- def update(id, params)
210
- @handler.put("cert/profiles/#{id}", params)
280
+ def update(id, params, options = nil)
281
+ @handler.put("cert/profiles/#{id}", params, options)
211
282
  end
212
283
 
213
284
  # Delete a certificate monitoring profile
214
285
  # @param id [String, Integer] Profile ID
286
+ # @param options [RequestOptions, nil] Request options
215
287
  # @return [Hash] Deletion confirmation
216
- def delete(id)
217
- @handler.delete("cert/profiles/#{id}")
288
+ def delete(id, options = nil)
289
+ @handler.delete("cert/profiles/#{id}", options)
218
290
  end
219
291
  end
220
292
  end
@@ -76,6 +76,12 @@ module GeneratorLabs
76
76
  @handler = RequestHandler.new(account_sid, auth_token, @config)
77
77
  end
78
78
 
79
+ # Access the account, its balance, its usage and its scheduled checks
80
+ # @return [Account]
81
+ def account
82
+ @account ||= Account.new(@handler)
83
+ end
84
+
79
85
  # Get the RBL monitoring API namespace.
80
86
  #
81
87
  # The RBL namespace provides access to: