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.
@@ -35,18 +35,11 @@ module GeneratorLabs
35
35
  @handler = handler
36
36
  end
37
37
 
38
- # Get contacts (all, by ID, or by array of IDs)
39
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
38
+ # Get contacts (all, or one by ID)
39
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
40
40
  # @return [Hash] Contact data
41
- def get(*ids)
42
- return @handler.get('contact/contacts') if ids.empty?
43
-
44
- # Check if first argument is a hash (parameters)
45
- return @handler.get('contact/contacts', ids.first) if ids.first.is_a?(Hash)
46
-
47
- return @handler.get("contact/contacts/#{ids.first}") if ids.length == 1
48
-
49
- @handler.get('contact/contacts', { ids: ids.join(',') })
41
+ def get(*args)
42
+ @handler.get(*GeneratorLabs.get_args('contact/contacts', args))
50
43
  end
51
44
 
52
45
  # Get all contacts with automatic pagination
@@ -60,7 +53,7 @@ module GeneratorLabs
60
53
  loop do
61
54
  params[:page] = page
62
55
  response = get(params)
63
- contacts = response['contacts'] || []
56
+ contacts = response['data'] || []
64
57
 
65
58
  all_items.concat(contacts)
66
59
 
@@ -74,53 +67,60 @@ module GeneratorLabs
74
67
 
75
68
  # Create a new contact
76
69
  # @param params [Hash] Contact parameters
70
+ # @param options [RequestOptions, nil] Request options
77
71
  # @return [Hash] Created contact data
78
- def create(params)
79
- @handler.post('contact/contacts', params)
72
+ def create(params, options = nil)
73
+ @handler.post('contact/contacts', params, options, idempotent: true)
80
74
  end
81
75
 
82
76
  # Update a contact
83
77
  # @param id [String, Integer] Contact ID
84
78
  # @param params [Hash] Updated parameters
79
+ # @param options [RequestOptions, nil] Request options
85
80
  # @return [Hash] Updated contact data
86
- def update(id, params)
87
- @handler.put("contact/contacts/#{id}", params)
81
+ def update(id, params, options = nil)
82
+ @handler.put("contact/contacts/#{id}", params, options)
88
83
  end
89
84
 
90
85
  # Delete a contact
91
86
  # @param id [String, Integer] Contact ID
87
+ # @param options [RequestOptions, nil] Request options
92
88
  # @return [Hash] Deletion confirmation
93
- def delete(id)
94
- @handler.delete("contact/contacts/#{id}")
89
+ def delete(id, options = nil)
90
+ @handler.delete("contact/contacts/#{id}", options)
95
91
  end
96
92
 
97
93
  # Pause a contact
98
94
  # @param id [String, Integer] Contact ID
95
+ # @param options [RequestOptions, nil] Request options
99
96
  # @return [Hash] Response
100
- def pause(id)
101
- @handler.post("contact/contacts/#{id}/pause")
97
+ def pause(id, options = nil)
98
+ @handler.post("contact/contacts/#{id}/pause", nil, options)
102
99
  end
103
100
 
104
101
  # Resume a contact
105
102
  # @param id [String, Integer] Contact ID
103
+ # @param options [RequestOptions, nil] Request options
106
104
  # @return [Hash] Response
107
- def resume(id)
108
- @handler.post("contact/contacts/#{id}/resume")
105
+ def resume(id, options = nil)
106
+ @handler.post("contact/contacts/#{id}/resume", nil, options)
109
107
  end
110
108
 
111
109
  # Confirm a contact with an auth code
112
110
  # @param id [String, Integer] Contact ID
113
111
  # @param params [Hash] Confirmation parameters (authcode)
112
+ # @param options [RequestOptions, nil] Request options
114
113
  # @return [Hash] Response
115
- def confirm(id, params)
116
- @handler.post("contact/contacts/#{id}/confirm", params)
114
+ def confirm(id, params, options = nil)
115
+ @handler.post("contact/contacts/#{id}/confirm", params, options, idempotent: true)
117
116
  end
118
117
 
119
118
  # Resend confirmation to a contact
120
119
  # @param id [String, Integer] Contact ID
120
+ # @param options [RequestOptions, nil] Request options
121
121
  # @return [Hash] Response
122
- def resend(id)
123
- @handler.post("contact/contacts/#{id}/resend")
122
+ def resend(id, options = nil)
123
+ @handler.post("contact/contacts/#{id}/resend", nil, options, idempotent: true)
124
124
  end
125
125
  end
126
126
 
@@ -130,18 +130,11 @@ module GeneratorLabs
130
130
  @handler = handler
131
131
  end
132
132
 
133
- # Get groups (all, by ID, or by array of IDs)
134
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
133
+ # Get groups (all, or one by ID)
134
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
135
135
  # @return [Hash] Group data
136
- def get(*ids)
137
- return @handler.get('contact/groups') if ids.empty?
138
-
139
- # Check if first argument is a hash (parameters)
140
- return @handler.get('contact/groups', ids.first) if ids.first.is_a?(Hash)
141
-
142
- return @handler.get("contact/groups/#{ids.first}") if ids.length == 1
143
-
144
- @handler.get('contact/groups', { ids: ids.join(',') })
136
+ def get(*args)
137
+ @handler.get(*GeneratorLabs.get_args('contact/groups', args))
145
138
  end
146
139
 
147
140
  # Get all groups with automatic pagination
@@ -155,7 +148,7 @@ module GeneratorLabs
155
148
  loop do
156
149
  params[:page] = page
157
150
  response = get(params)
158
- groups = response['groups'] || []
151
+ groups = response['data'] || []
159
152
 
160
153
  all_items.concat(groups)
161
154
 
@@ -169,24 +162,27 @@ module GeneratorLabs
169
162
 
170
163
  # Create a new contact group
171
164
  # @param params [Hash] Group parameters
165
+ # @param options [RequestOptions, nil] Request options
172
166
  # @return [Hash] Created group data
173
- def create(params)
174
- @handler.post('contact/groups', params)
167
+ def create(params, options = nil)
168
+ @handler.post('contact/groups', params, options, idempotent: true)
175
169
  end
176
170
 
177
171
  # Update a contact group
178
172
  # @param id [String, Integer] Group ID
179
173
  # @param params [Hash] Updated parameters
174
+ # @param options [RequestOptions, nil] Request options
180
175
  # @return [Hash] Updated group data
181
- def update(id, params)
182
- @handler.put("contact/groups/#{id}", params)
176
+ def update(id, params, options = nil)
177
+ @handler.put("contact/groups/#{id}", params, options)
183
178
  end
184
179
 
185
180
  # Delete a contact group
186
181
  # @param id [String, Integer] Group ID
182
+ # @param options [RequestOptions, nil] Request options
187
183
  # @return [Hash] Deletion confirmation
188
- def delete(id)
189
- @handler.delete("contact/groups/#{id}")
184
+ def delete(id, options = nil)
185
+ @handler.delete("contact/groups/#{id}", options)
190
186
  end
191
187
  end
192
188
  end
@@ -41,9 +41,11 @@ module GeneratorLabs
41
41
  end
42
42
 
43
43
  # Get current RBL listings for monitored hosts
44
+ # @param params [Hash, nil] Optional parameters (page, page_size)
45
+ # @param options [RequestOptions, nil] Request options
44
46
  # @return [Hash] Listing information
45
- def listings
46
- @handler.get('rbl/listings')
47
+ def listings(params = nil, options = nil)
48
+ @handler.get('rbl/listings', params, options)
47
49
  end
48
50
  end
49
51
 
@@ -55,17 +57,19 @@ module GeneratorLabs
55
57
 
56
58
  # Start a manual RBL check
57
59
  # @param params [Hash] Check parameters (host, callback, details)
60
+ # @param options [RequestOptions, nil] Request options
58
61
  # @return [Hash] Check result with check ID
59
- def start(params)
60
- @handler.post('rbl/check/start', params)
62
+ def start(params, options = nil)
63
+ @handler.post('rbl/check/start', params, options, idempotent: true)
61
64
  end
62
65
 
63
66
  # Get the status of a manual RBL check
64
67
  # @param id [String] Check ID
65
68
  # @param params [Hash] Optional parameters (details)
69
+ # @param options [RequestOptions, nil] Request options
66
70
  # @return [Hash] Check status
67
- def status(id, params = {})
68
- @handler.get("rbl/check/status/#{id}", params)
71
+ def status(id, params = {}, options = nil)
72
+ @handler.get("rbl/check/status/#{id}", params, options)
69
73
  end
70
74
  end
71
75
 
@@ -75,18 +79,11 @@ module GeneratorLabs
75
79
  @handler = handler
76
80
  end
77
81
 
78
- # Get hosts (all, by ID, or by array of IDs)
79
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
82
+ # Get hosts (all, or one by ID)
83
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
80
84
  # @return [Hash] Host data
81
- def get(*ids)
82
- return @handler.get('rbl/hosts') if ids.empty?
83
-
84
- # Check if first argument is a hash (parameters)
85
- return @handler.get('rbl/hosts', ids.first) if ids.first.is_a?(Hash)
86
-
87
- return @handler.get("rbl/hosts/#{ids.first}") if ids.length == 1
88
-
89
- @handler.get('rbl/hosts', { ids: ids.join(',') })
85
+ def get(*args)
86
+ @handler.get(*GeneratorLabs.get_args('rbl/hosts', args))
90
87
  end
91
88
 
92
89
  # Get all hosts with automatic pagination
@@ -100,7 +97,7 @@ module GeneratorLabs
100
97
  loop do
101
98
  params[:page] = page
102
99
  response = get(params)
103
- hosts = response['hosts'] || []
100
+ hosts = response['data'] || []
104
101
 
105
102
  all_items.concat(hosts)
106
103
 
@@ -114,38 +111,43 @@ module GeneratorLabs
114
111
 
115
112
  # Create a new monitored host
116
113
  # @param params [Hash] Host parameters
114
+ # @param options [RequestOptions, nil] Request options
117
115
  # @return [Hash] Created host data
118
- def create(params)
119
- @handler.post('rbl/hosts', params)
116
+ def create(params, options = nil)
117
+ @handler.post('rbl/hosts', params, options, idempotent: true)
120
118
  end
121
119
 
122
120
  # Update a monitored host
123
121
  # @param id [String, Integer] Host ID
124
122
  # @param params [Hash] Updated parameters
123
+ # @param options [RequestOptions, nil] Request options
125
124
  # @return [Hash] Updated host data
126
- def update(id, params)
127
- @handler.put("rbl/hosts/#{id}", params)
125
+ def update(id, params, options = nil)
126
+ @handler.put("rbl/hosts/#{id}", params, options)
128
127
  end
129
128
 
130
129
  # Delete a monitored host
131
130
  # @param id [String, Integer] Host ID
131
+ # @param options [RequestOptions, nil] Request options
132
132
  # @return [Hash] Deletion confirmation
133
- def delete(id)
134
- @handler.delete("rbl/hosts/#{id}")
133
+ def delete(id, options = nil)
134
+ @handler.delete("rbl/hosts/#{id}", options)
135
135
  end
136
136
 
137
137
  # Pause monitoring for a host
138
138
  # @param id [String, Integer] Host ID
139
+ # @param options [RequestOptions, nil] Request options
139
140
  # @return [Hash] Response
140
- def pause(id)
141
- @handler.post("rbl/hosts/#{id}/pause")
141
+ def pause(id, options = nil)
142
+ @handler.post("rbl/hosts/#{id}/pause", nil, options)
142
143
  end
143
144
 
144
145
  # Resume monitoring for a host
145
146
  # @param id [String, Integer] Host ID
147
+ # @param options [RequestOptions, nil] Request options
146
148
  # @return [Hash] Response
147
- def resume(id)
148
- @handler.post("rbl/hosts/#{id}/resume")
149
+ def resume(id, options = nil)
150
+ @handler.post("rbl/hosts/#{id}/resume", nil, options)
149
151
  end
150
152
  end
151
153
 
@@ -155,18 +157,11 @@ module GeneratorLabs
155
157
  @handler = handler
156
158
  end
157
159
 
158
- # Get profiles (all, by ID, or by array of IDs)
159
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
160
+ # Get profiles (all, or one by ID)
161
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
160
162
  # @return [Hash] Profile data
161
- def get(*ids)
162
- return @handler.get('rbl/profiles') if ids.empty?
163
-
164
- # Check if first argument is a hash (parameters)
165
- return @handler.get('rbl/profiles', ids.first) if ids.first.is_a?(Hash)
166
-
167
- return @handler.get("rbl/profiles/#{ids.first}") if ids.length == 1
168
-
169
- @handler.get('rbl/profiles', { ids: ids.join(',') })
163
+ def get(*args)
164
+ @handler.get(*GeneratorLabs.get_args('rbl/profiles', args))
170
165
  end
171
166
 
172
167
  # Get all profiles with automatic pagination
@@ -180,7 +175,7 @@ module GeneratorLabs
180
175
  loop do
181
176
  params[:page] = page
182
177
  response = get(params)
183
- profiles = response['profiles'] || []
178
+ profiles = response['data'] || []
184
179
 
185
180
  all_items.concat(profiles)
186
181
 
@@ -194,24 +189,27 @@ module GeneratorLabs
194
189
 
195
190
  # Create a new monitoring profile
196
191
  # @param params [Hash] Profile parameters
192
+ # @param options [RequestOptions, nil] Request options
197
193
  # @return [Hash] Created profile data
198
- def create(params)
199
- @handler.post('rbl/profiles', params)
194
+ def create(params, options = nil)
195
+ @handler.post('rbl/profiles', params, options, idempotent: true)
200
196
  end
201
197
 
202
198
  # Update a monitoring profile
203
199
  # @param id [String, Integer] Profile ID
204
200
  # @param params [Hash] Updated parameters
201
+ # @param options [RequestOptions, nil] Request options
205
202
  # @return [Hash] Updated profile data
206
- def update(id, params)
207
- @handler.put("rbl/profiles/#{id}", params)
203
+ def update(id, params, options = nil)
204
+ @handler.put("rbl/profiles/#{id}", params, options)
208
205
  end
209
206
 
210
207
  # Delete a monitoring profile
211
208
  # @param id [String, Integer] Profile ID
209
+ # @param options [RequestOptions, nil] Request options
212
210
  # @return [Hash] Deletion confirmation
213
- def delete(id)
214
- @handler.delete("rbl/profiles/#{id}")
211
+ def delete(id, options = nil)
212
+ @handler.delete("rbl/profiles/#{id}", options)
215
213
  end
216
214
  end
217
215
 
@@ -221,18 +219,11 @@ module GeneratorLabs
221
219
  @handler = handler
222
220
  end
223
221
 
224
- # Get sources (all, by ID, or by array of IDs)
225
- # @param ids [nil, String, Integer, Hash, Array] Optional ID(s) or parameters
222
+ # Get sources (all, or one by ID)
223
+ # @param args [String, Hash, RequestOptions] Optional ID or parameters, then request options
226
224
  # @return [Hash] Source data
227
- def get(*ids)
228
- return @handler.get('rbl/sources') if ids.empty?
229
-
230
- # Check if first argument is a hash (parameters)
231
- return @handler.get('rbl/sources', ids.first) if ids.first.is_a?(Hash)
232
-
233
- return @handler.get("rbl/sources/#{ids.first}") if ids.length == 1
234
-
235
- @handler.get('rbl/sources', { ids: ids.join(',') })
225
+ def get(*args)
226
+ @handler.get(*GeneratorLabs.get_args('rbl/sources', args))
236
227
  end
237
228
 
238
229
  # Get all sources with automatic pagination
@@ -246,7 +237,7 @@ module GeneratorLabs
246
237
  loop do
247
238
  params[:page] = page
248
239
  response = get(params)
249
- sources = response['sources'] || []
240
+ sources = response['data'] || []
250
241
 
251
242
  all_items.concat(sources)
252
243
 
@@ -260,38 +251,43 @@ module GeneratorLabs
260
251
 
261
252
  # Create a new RBL source
262
253
  # @param params [Hash] Source parameters
254
+ # @param options [RequestOptions, nil] Request options
263
255
  # @return [Hash] Created source data
264
- def create(params)
265
- @handler.post('rbl/sources', params)
256
+ def create(params, options = nil)
257
+ @handler.post('rbl/sources', params, options, idempotent: true)
266
258
  end
267
259
 
268
260
  # Update an RBL source
269
261
  # @param id [String, Integer] Source ID
270
262
  # @param params [Hash] Updated parameters
263
+ # @param options [RequestOptions, nil] Request options
271
264
  # @return [Hash] Updated source data
272
- def update(id, params)
273
- @handler.put("rbl/sources/#{id}", params)
265
+ def update(id, params, options = nil)
266
+ @handler.put("rbl/sources/#{id}", params, options)
274
267
  end
275
268
 
276
269
  # Delete an RBL source
277
270
  # @param id [String, Integer] Source ID
271
+ # @param options [RequestOptions, nil] Request options
278
272
  # @return [Hash] Deletion confirmation
279
- def delete(id)
280
- @handler.delete("rbl/sources/#{id}")
273
+ def delete(id, options = nil)
274
+ @handler.delete("rbl/sources/#{id}", options)
281
275
  end
282
276
 
283
277
  # Pause an RBL source
284
278
  # @param id [String, Integer] Source ID
279
+ # @param options [RequestOptions, nil] Request options
285
280
  # @return [Hash] Response
286
- def pause(id)
287
- @handler.post("rbl/sources/#{id}/pause")
281
+ def pause(id, options = nil)
282
+ @handler.post("rbl/sources/#{id}/pause", nil, options)
288
283
  end
289
284
 
290
285
  # Resume an RBL source
291
286
  # @param id [String, Integer] Source ID
287
+ # @param options [RequestOptions, nil] Request options
292
288
  # @return [Hash] Response
293
- def resume(id)
294
- @handler.post("rbl/sources/#{id}/resume")
289
+ def resume(id, options = nil)
290
+ @handler.post("rbl/sources/#{id}/resume", nil, options)
295
291
  end
296
292
  end
297
293
  end
@@ -12,6 +12,7 @@
12
12
  require 'faraday'
13
13
  require 'faraday/retry'
14
14
  require 'json'
15
+ require 'securerandom'
15
16
 
16
17
  module GeneratorLabs
17
18
  # Handles HTTP requests to the Generator Labs API.
@@ -42,11 +43,16 @@ module GeneratorLabs
42
43
  faraday_config.request :url_encoded
43
44
  faraday_config.request :authorization, :basic, account_sid, auth_token
44
45
  # Retry with exponential backoff; faraday-retry respects Retry-After
45
- # headers automatically on rate limit (429) responses
46
+ # headers automatically on rate limit (429) responses. A Retry-After longer
47
+ # than max_interval is not waited out: the response is raised as the error.
48
+ # RateLimit-Reset is on every response and is not a time to wait before a
49
+ # retry, so the reset header is pointed at Retry-After as well.
46
50
  faraday_config.request :retry,
47
51
  max: config.max_retries,
48
52
  interval: 1.0,
49
53
  backoff_factor: config.retry_backoff,
54
+ max_interval: MAX_RETRY_AFTER,
55
+ rate_limit_reset_header: 'Retry-After',
50
56
  retry_statuses: [429, 500, 502, 503, 504],
51
57
  methods: %i[get post put delete]
52
58
 
@@ -63,13 +69,28 @@ module GeneratorLabs
63
69
  #
64
70
  # @param path [String] API endpoint path (e.g., 'rbl/hosts')
65
71
  # @param params [Hash, nil] Query parameters (e.g., {status: 'active'})
72
+ # @param options [RequestOptions, nil] Request options
66
73
  # @return [Response] Response wrapper with parsed data and rate limit info
67
74
  # @raise [Error] if request fails after all retries
68
75
  #
69
76
  # @example
70
77
  # handler.get('rbl/hosts', { status: 'active' })
71
- def get(path, params = nil)
72
- make_request(:get, path, params)
78
+ def get(path, params = nil, options = nil)
79
+ make_request(:get, path, params, options)
80
+ end
81
+
82
+ # Make a GET request to an endpoint that answers in plain text.
83
+ #
84
+ # @param path [String] API endpoint path (e.g., 'account/balance')
85
+ # @param options [RequestOptions, nil] Request options
86
+ # @return [String] The response body
87
+ # @raise [Error] if request fails or the HTTP status code is >= 400
88
+ def get_plain(path, options = nil)
89
+ response = send_request(:get, path, nil, options, false)
90
+ return response.body.to_s.strip if response.status < 400
91
+
92
+ raise Error.new("API error: HTTP #{response.status} error",
93
+ status_code: response.status, request_id: response.headers['x-request-id'])
73
94
  end
74
95
 
75
96
  # Make a POST request to the API.
@@ -79,13 +100,15 @@ module GeneratorLabs
79
100
  #
80
101
  # @param path [String] API endpoint path (e.g., 'rbl/hosts')
81
102
  # @param params [Hash, nil] Request parameters (e.g., {name: 'My Host', host: '1.2.3.4'})
103
+ # @param options [RequestOptions, nil] Request options
104
+ # @param idempotent [Boolean] Whether the endpoint accepts an Idempotency-Key
82
105
  # @return [Response] Response wrapper with parsed data and rate limit info
83
106
  # @raise [Error] if request fails after all retries
84
107
  #
85
108
  # @example
86
109
  # handler.post('rbl/hosts', { name: 'My Host', host: '1.2.3.4', type: 'rbl' })
87
- def post(path, params = nil)
88
- make_request(:post, path, params)
110
+ def post(path, params = nil, options = nil, idempotent: false)
111
+ make_request(:post, path, params, options, idempotent)
89
112
  end
90
113
 
91
114
  # Make a PUT request to the API.
@@ -95,13 +118,14 @@ module GeneratorLabs
95
118
  #
96
119
  # @param path [String] API endpoint path (e.g., 'rbl/hosts/HTxxxxxxxx')
97
120
  # @param params [Hash, nil] Request parameters (e.g., {name: 'Updated Name'})
121
+ # @param options [RequestOptions, nil] Request options
98
122
  # @return [Response] Response wrapper with parsed data and rate limit info
99
123
  # @raise [Error] if request fails after all retries
100
124
  #
101
125
  # @example
102
126
  # handler.put('rbl/hosts/HT1a2b3c4d5e6f7890abcdef1234567890', { name: 'Updated Name' })
103
- def put(path, params = nil)
104
- make_request(:put, path, params)
127
+ def put(path, params = nil, options = nil)
128
+ make_request(:put, path, params, options)
105
129
  end
106
130
 
107
131
  # Make a DELETE request to the API.
@@ -110,51 +134,79 @@ module GeneratorLabs
110
134
  # automatic retry logic for failures.
111
135
  #
112
136
  # @param path [String] API endpoint path (e.g., 'rbl/hosts/HTxxxxxxxx')
137
+ # @param options [RequestOptions, nil] Request options
138
+ # @param idempotent [Boolean] Whether the endpoint accepts an Idempotency-Key
113
139
  # @return [Response] Response wrapper with parsed data and rate limit info
114
140
  # @raise [Error] if request fails after all retries
115
141
  #
116
142
  # @example
117
143
  # handler.delete('rbl/hosts/HT1a2b3c4d5e6f7890abcdef1234567890')
118
- def delete(path)
119
- make_request(:delete, path, nil)
144
+ def delete(path, options = nil, idempotent: false)
145
+ make_request(:delete, path, nil, options, idempotent)
120
146
  end
121
147
 
122
148
  private
123
149
 
124
- # Make HTTP request to API with automatic retries.
150
+ # Send HTTP request to API with automatic retries.
125
151
  #
126
152
  # This method handles:
127
153
  # - Building the request URL with .json extension
128
154
  # - Adding query parameters for GET requests
129
155
  # - Adding form data for POST/PUT/DELETE requests
130
- # - Setting authentication headers
156
+ # - Setting authentication and request option headers
131
157
  # - Executing the request with retry logic
132
- # - Parsing JSON responses
133
- # - Checking for API errors in the response
158
+ #
159
+ # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
160
+ # @param path [String] API endpoint path
161
+ # @param params [Hash, nil] Request parameters
162
+ # @param options [RequestOptions, nil] Request options
163
+ # @param idempotent [Boolean] Whether the endpoint accepts an Idempotency-Key; one is
164
+ # generated when the caller gave none
165
+ # @return [Faraday::Response] The HTTP response
166
+ # @raise [Error] if all retry attempts fail
167
+ def send_request(method, path, params, options, idempotent)
168
+ options ||= RequestOptions.new
169
+
170
+ # Field selection applies to GET requests
171
+ params = (params || {}).merge(fields: options.fields) if method == :get && options.fields
172
+ params = convert_params(params)
173
+
174
+ # The headers are set once per call, so every retry of the call sends the same
175
+ # Idempotency-Key and the API answers a repeat with the first result
176
+ headers = {
177
+ 'User-Agent' => "GeneratorLabs-Ruby/#{VERSION}",
178
+ 'Accept' => 'application/json',
179
+ 'Idempotency-Key' => options.idempotency_key || (SecureRandom.uuid if idempotent),
180
+ 'X-Request-Id' => options.request_id,
181
+ 'If-None-Match' => options.if_none_match
182
+ }.compact
183
+
184
+ @connection.send(method) do |req|
185
+ req.url "#{path}.json"
186
+ req.headers.update(headers)
187
+ apply_params(req, method, params)
188
+ end
189
+ rescue Faraday::Error => e
190
+ raise Error, "API request failed: #{e.message}"
191
+ end
192
+
193
+ # Make HTTP request to API and parse the JSON response.
134
194
  #
135
195
  # Errors are raised if:
136
196
  # - All retry attempts fail
137
197
  # - The response body cannot be parsed
138
- # - The API returns success=false in the response
139
- # - The HTTP status code is >= 400
198
+ # - The HTTP status code or the API status_code is >= 400
140
199
  #
141
200
  # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
142
201
  # @param path [String] API endpoint path
143
202
  # @param params [Hash, nil] Request parameters
203
+ # @param options [RequestOptions, nil] Request options
204
+ # @param idempotent [Boolean] Whether the endpoint accepts an Idempotency-Key
144
205
  # @return [Response] Response wrapper with parsed data and rate limit info
145
206
  # @raise [Error] if request fails or response is invalid
146
- def make_request(method, path, params)
147
- url = "#{path}.json"
148
- params = convert_params(params)
149
-
150
- response = @connection.send(method) do |req|
151
- req.url url
152
- req.headers['User-Agent'] = "GeneratorLabs-Ruby/#{VERSION}"
153
- req.headers['Accept'] = 'application/json'
154
- apply_params(req, method, params)
155
- end
156
-
157
- data = parse_response(response)
207
+ def make_request(method, path, params, options = nil, idempotent = false) # rubocop:disable Style/OptionalBooleanParameter
208
+ response = send_request(method, path, params, options, idempotent)
209
+ metadata = { request_id: response.headers['x-request-id'], etag: response.headers['etag'] }
158
210
 
159
211
  #
160
212
  # parse rate limit headers
@@ -168,9 +220,11 @@ module GeneratorLabs
168
220
  )
169
221
  end
170
222
 
171
- Response.new(data, rate_limit_info)
172
- rescue Faraday::Error => e
173
- raise Error, "API request failed: #{e.message}"
223
+ # 304 Not Modified has no body: the copy the caller's ETag came from is still current
224
+ return Response.new({}, rate_limit_info, **metadata, not_modified: true) if response.status == 304
225
+
226
+ Response.new(parse_response(response), rate_limit_info, **metadata,
227
+ replayed: response.headers['idempotent-replayed'] == 'true')
174
228
  end
175
229
 
176
230
  # Convert array values to comma-separated strings for form encoding.
@@ -195,19 +249,17 @@ module GeneratorLabs
195
249
  def parse_response(response)
196
250
  data = JSON.parse(response.body)
197
251
 
198
- if data.is_a?(Hash) && data['success'] == false
199
- error_msg = data.dig('error', 'message') || data['message'] || 'Unknown error'
200
- raise Error, "API error: #{error_msg}"
201
- end
202
-
203
- if response.status >= 400
204
- error_msg = data.dig('error', 'message') || data['message'] || "HTTP #{response.status} error"
205
- raise Error, "API error: #{error_msg}"
252
+ code = (data.is_a?(Hash) && data['status_code']) || response.status
253
+ if code.to_i >= 400 || response.status >= 400
254
+ error_msg = (data.is_a?(Hash) && data['status_message']) || "HTTP #{response.status} error"
255
+ raise Error.new("API error: #{error_msg}", status_code: code.to_i,
256
+ request_id: response.headers['x-request-id'])
206
257
  end
207
258
 
208
259
  data
209
260
  rescue JSON::ParserError => e
210
- raise Error, "Failed to parse JSON response: #{e.message}"
261
+ raise Error.new("Failed to parse JSON response: #{e.message}",
262
+ request_id: response.headers['x-request-id'])
211
263
  end
212
264
  end
213
265
  end