turbodocx-sdk 0.9.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.
@@ -0,0 +1,470 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "http_client"
4
+
5
+ module TurboDocxSdk
6
+ # TurboPartner module -- partner portal management operations.
7
+ #
8
+ # All methods are class-level (static pattern). Call +configure+ once,
9
+ # then invoke any method directly on the class.
10
+ #
11
+ # TurboDocxSdk::TurboPartner.configure(partner_api_key: "TDXP-...", partner_id: "...")
12
+ # orgs = TurboDocxSdk::TurboPartner.list_organizations
13
+ #
14
+ class TurboPartner
15
+ class << self
16
+ # Configure the TurboPartner module with partner API credentials.
17
+ #
18
+ # @param partner_api_key [String] Partner API key (TDXP- prefix)
19
+ # @param partner_id [String] Partner UUID
20
+ # @param base_url [String, nil]
21
+ # @raise [AuthenticationError] if the partner API key is invalid
22
+ def configure(partner_api_key:, partner_id:, base_url: nil)
23
+ @client = HttpClient.new(
24
+ api_key: partner_api_key,
25
+ base_url: base_url,
26
+ skip_sender_validation: true
27
+ )
28
+ @partner_id = partner_id
29
+ end
30
+
31
+ # ============================================
32
+ # ORGANIZATION MANAGEMENT
33
+ # ============================================
34
+
35
+ # Create a new organization.
36
+ #
37
+ # @param request [Hash] organization data (:name, :metadata, :features)
38
+ # @return [Hash] the created organization
39
+ # @raise [ValidationError] on invalid request data or if not configured
40
+ # @raise [AuthenticationError] on invalid credentials
41
+ # @raise [NetworkError] on connection failure
42
+ def create_organization(request)
43
+ client = get_client
44
+ client.post("/partner/#{partner_id}/organization", request)
45
+ end
46
+
47
+ # List organizations with optional pagination and search.
48
+ #
49
+ # @param request [Hash, nil] :limit, :offset, :search
50
+ # @return [Hash] paginated list of organizations
51
+ # @raise [ValidationError] if not configured and no env vars
52
+ # @raise [AuthenticationError] on invalid credentials
53
+ # @raise [NetworkError] on connection failure
54
+ def list_organizations(request = nil)
55
+ client = get_client
56
+ client.get("/partner/#{partner_id}/organizations", to_query_params(request))
57
+ end
58
+
59
+ # Get detailed information about an organization.
60
+ #
61
+ # @param organization_id [String]
62
+ # @return [Hash] organization details with features and tracking
63
+ # @raise [NotFoundError] if the organization does not exist
64
+ # @raise [AuthenticationError] on invalid credentials
65
+ # @raise [NetworkError] on connection failure
66
+ def get_organization_details(organization_id)
67
+ client = get_client
68
+ client.get("/partner/#{partner_id}/organizations/#{organization_id}")
69
+ end
70
+
71
+ # Update an organization's info.
72
+ #
73
+ # @param organization_id [String]
74
+ # @param request [Hash] fields to update
75
+ # @return [Hash] the updated organization
76
+ # @raise [NotFoundError] if the organization does not exist
77
+ # @raise [ValidationError] on invalid request data
78
+ # @raise [AuthenticationError] on invalid credentials
79
+ # @raise [NetworkError] on connection failure
80
+ def update_organization_info(organization_id, request)
81
+ client = get_client
82
+ client.patch("/partner/#{partner_id}/organizations/#{organization_id}", request)
83
+ end
84
+
85
+ # Delete an organization.
86
+ #
87
+ # @param organization_id [String]
88
+ # @return [Hash] deletion confirmation
89
+ # @raise [NotFoundError] if the organization does not exist
90
+ # @raise [AuthenticationError] on invalid credentials
91
+ # @raise [NetworkError] on connection failure
92
+ def delete_organization(organization_id)
93
+ client = get_client
94
+ client.delete("/partner/#{partner_id}/organizations/#{organization_id}")
95
+ end
96
+
97
+ # Update an organization's entitlements (features and tracking).
98
+ #
99
+ # @param organization_id [String]
100
+ # @param request [Hash] :features, :tracking
101
+ # @return [Hash] updated entitlements
102
+ # @raise [NotFoundError] if the organization does not exist
103
+ # @raise [ValidationError] on invalid request data
104
+ # @raise [AuthenticationError] on invalid credentials
105
+ # @raise [NetworkError] on connection failure
106
+ def update_organization_entitlements(organization_id, request)
107
+ client = get_client
108
+ client.patch("/partner/#{partner_id}/organizations/#{organization_id}/entitlements", request)
109
+ end
110
+
111
+ # Read the TurboSign display preferences for one of the partner's organizations.
112
+ #
113
+ # Returns only the partner-settable preference keys, each with its effective
114
+ # value (defaults applied for keys the org never set).
115
+ #
116
+ # @param organization_id [String]
117
+ # @return [Hash] the organization's partner-settable preferences under +data.preferences+
118
+ # (+hideSignatureOutline+, +hideSignatureHash+, +lockedFieldsBackground+,
119
+ # +allowDownloadBeforeSigning+ booleans)
120
+ # @raise [NotFoundError] if the organization does not exist
121
+ # @raise [AuthenticationError] on invalid credentials
122
+ # @raise [NetworkError] on connection failure
123
+ def get_organization_preferences(organization_id)
124
+ client = get_client
125
+ client.get("/partner/#{partner_id}/organizations/#{organization_id}/preferences")
126
+ end
127
+
128
+ # Set TurboSign display preferences for one of the partner's organizations.
129
+ #
130
+ # Pass only the keys you want to change; each must be a boolean. The keys stay
131
+ # camelCase verbatim (+hideSignatureOutline+, +hideSignatureHash+,
132
+ # +lockedFieldsBackground+, +allowDownloadBeforeSigning+) -- they are the API
133
+ # contract, not Ruby names.
134
+ #
135
+ # @param organization_id [String]
136
+ # @param preferences [Hash] the preference keys to change (only these are sent)
137
+ # @return [Hash] the organization's updated partner-settable preferences under +data.preferences+
138
+ # @raise [NotFoundError] if the organization does not exist
139
+ # @raise [ValidationError] on invalid request data
140
+ # @raise [AuthenticationError] on invalid credentials
141
+ # @raise [NetworkError] on connection failure
142
+ def update_organization_preferences(organization_id, preferences)
143
+ client = get_client
144
+ # Wrap under :preferences without mutating the caller's hash.
145
+ client.patch(
146
+ "/partner/#{partner_id}/organizations/#{organization_id}/preferences",
147
+ { "preferences" => preferences.dup }
148
+ )
149
+ end
150
+
151
+ # ============================================
152
+ # ORGANIZATION USER MANAGEMENT
153
+ # ============================================
154
+
155
+ # List users in an organization.
156
+ #
157
+ # @param organization_id [String]
158
+ # @param request [Hash, nil] :limit, :offset, :search
159
+ # @return [Hash] paginated list of users
160
+ # @raise [NotFoundError] if the organization does not exist
161
+ # @raise [AuthenticationError] on invalid credentials
162
+ # @raise [NetworkError] on connection failure
163
+ def list_organization_users(organization_id, request = nil)
164
+ client = get_client
165
+ client.get("/partner/#{partner_id}/organizations/#{organization_id}/users", to_query_params(request))
166
+ end
167
+
168
+ # Add a user to an organization.
169
+ #
170
+ # @param organization_id [String]
171
+ # @param request [Hash] :email, :role (+"admin"+, +"contributor"+, +"user"+ or +"viewer"+ --
172
+ # the org role enum; the partner role +"member"+ is NOT valid here)
173
+ # @return [Hash] the added user
174
+ # @raise [ValidationError] on invalid request data
175
+ # @raise [NotFoundError] if the organization does not exist
176
+ # @raise [AuthenticationError] on invalid credentials
177
+ # @raise [NetworkError] on connection failure
178
+ def add_user_to_organization(organization_id, request)
179
+ client = get_client
180
+ client.post("/partner/#{partner_id}/organizations/#{organization_id}/users", request)
181
+ end
182
+
183
+ # Update a user's role in an organization.
184
+ #
185
+ # @param organization_id [String]
186
+ # @param user_id [String]
187
+ # @param request [Hash] :role (+"admin"+, +"contributor"+, +"user"+ or +"viewer"+)
188
+ # @return [Hash] the updated user
189
+ # @raise [NotFoundError] if the organization or user does not exist
190
+ # @raise [AuthenticationError] on invalid credentials
191
+ # @raise [NetworkError] on connection failure
192
+ def update_organization_user_role(organization_id, user_id, request)
193
+ client = get_client
194
+ client.patch("/partner/#{partner_id}/organizations/#{organization_id}/users/#{user_id}", request)
195
+ end
196
+
197
+ # Remove a user from an organization.
198
+ #
199
+ # @param organization_id [String]
200
+ # @param user_id [String]
201
+ # @return [Hash] removal confirmation
202
+ # @raise [NotFoundError] if the organization or user does not exist
203
+ # @raise [AuthenticationError] on invalid credentials
204
+ # @raise [NetworkError] on connection failure
205
+ def remove_user_from_organization(organization_id, user_id)
206
+ client = get_client
207
+ client.delete("/partner/#{partner_id}/organizations/#{organization_id}/users/#{user_id}")
208
+ end
209
+
210
+ # Resend an organization invitation to a user.
211
+ #
212
+ # @param organization_id [String]
213
+ # @param user_id [String]
214
+ # @return [Hash] resend confirmation
215
+ # @raise [NotFoundError] if the organization or user does not exist
216
+ # @raise [AuthenticationError] on invalid credentials
217
+ # @raise [NetworkError] on connection failure
218
+ def resend_organization_invitation_to_user(organization_id, user_id)
219
+ client = get_client
220
+ client.post("/partner/#{partner_id}/organizations/#{organization_id}/users/#{user_id}/resend-invitation")
221
+ end
222
+
223
+ # ============================================
224
+ # ORGANIZATION API KEY MANAGEMENT
225
+ # ============================================
226
+
227
+ # List API keys for an organization.
228
+ #
229
+ # @param organization_id [String]
230
+ # @param request [Hash, nil] :limit, :offset, :search
231
+ # @return [Hash] paginated list of API keys
232
+ # @raise [NotFoundError] if the organization does not exist
233
+ # @raise [AuthenticationError] on invalid credentials
234
+ # @raise [NetworkError] on connection failure
235
+ def list_organization_api_keys(organization_id, request = nil)
236
+ client = get_client
237
+ client.get("/partner/#{partner_id}/organizations/#{organization_id}/apikeys", to_query_params(request))
238
+ end
239
+
240
+ # Create an API key for an organization.
241
+ #
242
+ # @param organization_id [String]
243
+ # @param request [Hash] :name, :role (org role enum:
244
+ # +"admin"+, +"contributor"+, +"user"+ or +"viewer"+)
245
+ # @return [Hash] the created API key (includes full key value)
246
+ # @raise [ValidationError] on invalid request data
247
+ # @raise [NotFoundError] if the organization does not exist
248
+ # @raise [AuthenticationError] on invalid credentials
249
+ # @raise [NetworkError] on connection failure
250
+ def create_organization_api_key(organization_id, request)
251
+ client = get_client
252
+ client.post("/partner/#{partner_id}/organizations/#{organization_id}/apikeys", request)
253
+ end
254
+
255
+ # Update an organization API key.
256
+ #
257
+ # @param organization_id [String]
258
+ # @param api_key_id [String]
259
+ # @param request [Hash] fields to update
260
+ # @return [Hash] the updated API key
261
+ # @raise [NotFoundError] if the organization or API key does not exist
262
+ # @raise [AuthenticationError] on invalid credentials
263
+ # @raise [NetworkError] on connection failure
264
+ def update_organization_api_key(organization_id, api_key_id, request)
265
+ client = get_client
266
+ client.patch("/partner/#{partner_id}/organizations/#{organization_id}/apikeys/#{api_key_id}", request)
267
+ end
268
+
269
+ # Revoke an organization API key.
270
+ #
271
+ # @param organization_id [String]
272
+ # @param api_key_id [String]
273
+ # @return [Hash] revocation confirmation
274
+ # @raise [NotFoundError] if the organization or API key does not exist
275
+ # @raise [AuthenticationError] on invalid credentials
276
+ # @raise [NetworkError] on connection failure
277
+ def revoke_organization_api_key(organization_id, api_key_id)
278
+ client = get_client
279
+ client.delete("/partner/#{partner_id}/organizations/#{organization_id}/apikeys/#{api_key_id}")
280
+ end
281
+
282
+ # ============================================
283
+ # PARTNER API KEY MANAGEMENT
284
+ # ============================================
285
+
286
+ # List partner API keys.
287
+ #
288
+ # @param request [Hash, nil] :limit, :offset
289
+ # @return [Hash] paginated list of partner API keys
290
+ # @raise [AuthenticationError] on invalid credentials
291
+ # @raise [NetworkError] on connection failure
292
+ def list_partner_api_keys(request = nil)
293
+ client = get_client
294
+ client.get("/partner/#{partner_id}/api-keys", to_query_params(request))
295
+ end
296
+
297
+ # Create a partner API key.
298
+ #
299
+ # @param request [Hash] :name, :scopes, :description
300
+ # @return [Hash] the created partner API key (includes full key value)
301
+ # @raise [ValidationError] on invalid request data
302
+ # @raise [AuthenticationError] on invalid credentials
303
+ # @raise [NetworkError] on connection failure
304
+ def create_partner_api_key(request)
305
+ client = get_client
306
+ client.post("/partner/#{partner_id}/api-keys", request)
307
+ end
308
+
309
+ # Update a partner API key.
310
+ #
311
+ # @param key_id [String]
312
+ # @param request [Hash] fields to update
313
+ # @return [Hash] the updated partner API key
314
+ # @raise [NotFoundError] if the API key does not exist
315
+ # @raise [AuthenticationError] on invalid credentials
316
+ # @raise [NetworkError] on connection failure
317
+ def update_partner_api_key(key_id, request)
318
+ client = get_client
319
+ client.patch("/partner/#{partner_id}/api-keys/#{key_id}", request)
320
+ end
321
+
322
+ # Revoke a partner API key.
323
+ #
324
+ # @param key_id [String]
325
+ # @return [Hash] revocation confirmation
326
+ # @raise [NotFoundError] if the API key does not exist
327
+ # @raise [AuthenticationError] on invalid credentials
328
+ # @raise [NetworkError] on connection failure
329
+ def revoke_partner_api_key(key_id)
330
+ client = get_client
331
+ client.delete("/partner/#{partner_id}/api-keys/#{key_id}")
332
+ end
333
+
334
+ # ============================================
335
+ # PARTNER USER MANAGEMENT
336
+ # ============================================
337
+
338
+ # List partner portal users.
339
+ #
340
+ # @param request [Hash, nil] :limit, :offset, :search
341
+ # @return [Hash] paginated list of partner users
342
+ # @raise [AuthenticationError] on invalid credentials
343
+ # @raise [NetworkError] on connection failure
344
+ def list_partner_portal_users(request = nil)
345
+ client = get_client
346
+ client.get("/partner/#{partner_id}/users", to_query_params(request))
347
+ end
348
+
349
+ # Add a user to the partner portal.
350
+ #
351
+ # @param request [Hash] :email, :role (partner role enum: +"admin"+, +"member"+ or
352
+ # +"viewer"+ -- the org roles +"contributor"+/+"user"+ are NOT valid here),
353
+ # :permissions. When :permissions is supplied it must carry ALL SEVEN keys --
354
+ # +canManageOrgs+, +canManageOrgUsers+, +canManagePartnerUsers+,
355
+ # +canManageOrgAPIKeys+, +canManagePartnerAPIKeys+, +canUpdateEntitlements+,
356
+ # +canViewAuditLogs+ (booleans). A partial permissions object is a 400.
357
+ # @return [Hash] the added user
358
+ # @raise [ValidationError] on invalid request data
359
+ # @raise [AuthenticationError] on invalid credentials
360
+ # @raise [NetworkError] on connection failure
361
+ def add_user_to_partner_portal(request)
362
+ client = get_client
363
+ client.post("/partner/#{partner_id}/users", request)
364
+ end
365
+
366
+ # Update a partner user's permissions.
367
+ #
368
+ # The :permissions object itself is optional, but there is no partial update:
369
+ # if you send it, send all seven keys or the backend returns a 400.
370
+ #
371
+ # @param user_id [String]
372
+ # @param request [Hash] :role (+"admin"+, +"member"+ or +"viewer"+), :permissions
373
+ # (ALL SEVEN of +canManageOrgs+, +canManageOrgUsers+, +canManagePartnerUsers+,
374
+ # +canManageOrgAPIKeys+, +canManagePartnerAPIKeys+, +canUpdateEntitlements+,
375
+ # +canViewAuditLogs+)
376
+ # @return [Hash] the updated user
377
+ # @raise [NotFoundError] if the user does not exist
378
+ # @raise [AuthenticationError] on invalid credentials
379
+ # @raise [NetworkError] on connection failure
380
+ def update_partner_user_permissions(user_id, request)
381
+ client = get_client
382
+ client.patch("/partner/#{partner_id}/users/#{user_id}", request)
383
+ end
384
+
385
+ # Remove a user from the partner portal.
386
+ #
387
+ # @param user_id [String]
388
+ # @return [Hash] removal confirmation
389
+ # @raise [NotFoundError] if the user does not exist
390
+ # @raise [AuthenticationError] on invalid credentials
391
+ # @raise [NetworkError] on connection failure
392
+ def remove_user_from_partner_portal(user_id)
393
+ client = get_client
394
+ client.delete("/partner/#{partner_id}/users/#{user_id}")
395
+ end
396
+
397
+ # Resend a partner portal invitation to a user.
398
+ #
399
+ # @param user_id [String]
400
+ # @return [Hash] resend confirmation
401
+ # @raise [NotFoundError] if the user does not exist
402
+ # @raise [AuthenticationError] on invalid credentials
403
+ # @raise [NetworkError] on connection failure
404
+ def resend_partner_portal_invitation_to_user(user_id)
405
+ client = get_client
406
+ client.post("/partner/#{partner_id}/users/#{user_id}/resend-invitation")
407
+ end
408
+
409
+ # ============================================
410
+ # AUDIT LOGS
411
+ # ============================================
412
+
413
+ # Get partner audit logs with optional filters.
414
+ #
415
+ # @param request [Hash, nil] :limit, :offset, :action, :resourceType, :success, :startDate, :endDate
416
+ # @return [Hash] paginated list of audit log entries
417
+ # @raise [AuthenticationError] on invalid credentials
418
+ # @raise [NetworkError] on connection failure
419
+ def get_partner_audit_logs(request = nil)
420
+ client = get_client
421
+ client.get("/partner/#{partner_id}/audit-logs", to_query_params(request))
422
+ end
423
+
424
+ private
425
+
426
+ def get_client
427
+ @client ||= begin
428
+ partner_api_key = ENV["TURBODOCX_PARTNER_API_KEY"]
429
+ pid = ENV["TURBODOCX_PARTNER_ID"]
430
+ unless partner_api_key && pid
431
+ raise ValidationError, "TurboPartner must be configured before use. Call TurboPartner.configure() " \
432
+ "or set TURBODOCX_PARTNER_API_KEY and TURBODOCX_PARTNER_ID environment variables."
433
+ end
434
+ configure(partner_api_key: partner_api_key, partner_id: pid)
435
+ @client
436
+ end
437
+ end
438
+
439
+ def partner_id
440
+ @partner_id || begin
441
+ get_client # triggers auto-init
442
+ @partner_id
443
+ end
444
+ end
445
+
446
+ def to_query_params(request)
447
+ return nil if request.nil? || request.empty?
448
+
449
+ params = {}
450
+ request.each do |key, value|
451
+ str_key = key.to_s
452
+ next if value.nil?
453
+
454
+ case value
455
+ when true, false
456
+ params[str_key] = value ? "true" : "false"
457
+ when Array
458
+ # Preserve as a string array so HttpClient#build_url emits repeated
459
+ # keys (?k=a&k=b) rather than a JSON-stringified blob. Mirrors
460
+ # TurboQuote#to_query_params.
461
+ params[str_key] = value.map(&:to_s)
462
+ else
463
+ params[str_key] = value.to_s
464
+ end
465
+ end
466
+ params.empty? ? nil : params
467
+ end
468
+ end
469
+ end
470
+ end