unitpost 0.4.0 → 0.5.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.
@@ -26,6 +26,27 @@ module Unitpost
26
26
  ALL = [OUT_OF_REACH, UNSUPPORTED_COUNTRY, NO_PHONE, OPTED_OUT, NO_MARKETING_CONSENT, QUIET_HOURS_DEFERRED, SENDER_NOT_ACTIVE].freeze
27
27
  end
28
28
 
29
+ module SmsFailureCode
30
+ QUOTA_EXCEEDED = "quota_exceeded"
31
+ OVERAGE_CAP_EXCEEDED = "overage_cap_exceeded"
32
+ SUBSCRIPTION_INACTIVE = "subscription_inactive"
33
+ SMS_NOT_IN_PLAN = "sms_not_in_plan"
34
+ UNSUPPORTED_COUNTRY = "unsupported_country"
35
+ WORKSPACE_SUSPENDED = "workspace_suspended"
36
+ SMS_BRAND_BLOCKED = "sms_brand_blocked"
37
+ SENDER_NOT_ACTIVE = "sender_not_active"
38
+ SENDER_REGISTRATION_INCOMPLETE = "sender_registration_incomplete"
39
+ SENDER_ACTION_REQUIRED = "sender_action_required"
40
+ SENDER_USE_CASE_MISMATCH = "sender_use_case_mismatch"
41
+ QUIET_HOURS_UNSATISFIABLE = "quiet_hours_unsatisfiable"
42
+ CHANNEL_UNAVAILABLE = "channel_unavailable"
43
+ DELIVERY_EXHAUSTED = "delivery_exhausted"
44
+ PROVIDER_REJECTED = "provider_rejected"
45
+ CARRIER_UNDELIVERED = "carrier_undelivered"
46
+ SUSPECTED_PUMPING = "suspected_pumping"
47
+ ALL = [QUOTA_EXCEEDED, OVERAGE_CAP_EXCEEDED, SUBSCRIPTION_INACTIVE, SMS_NOT_IN_PLAN, UNSUPPORTED_COUNTRY, WORKSPACE_SUSPENDED, SMS_BRAND_BLOCKED, SENDER_NOT_ACTIVE, SENDER_REGISTRATION_INCOMPLETE, SENDER_ACTION_REQUIRED, SENDER_USE_CASE_MISMATCH, QUIET_HOURS_UNSATISFIABLE, CHANNEL_UNAVAILABLE, DELIVERY_EXHAUSTED, PROVIDER_REJECTED, CARRIER_UNDELIVERED, SUSPECTED_PUMPING].freeze
48
+ end
49
+
29
50
  # The `SmsError` object from the public API.
30
51
  # @!attribute code Why a message was skipped before reaching the carrier. `out_of_reach`: no sender covers the recipient's country; `unsupported_country`: no compliance rule for the country yet, or SMS to that country is paused for now (every message, transactional included, until it resumes); `no_phone`: the contact has no SMS handle; `opted_out`: STOP / suppression / unreachable; `no_marketing_consent`: marketing without express consent; `quiet_hours_deferred`: delayed to the recipient's local window; `sender_not_active`: the sender lost approval.
31
52
  # @!attribute message Human-readable sentence for `code`.
@@ -42,6 +63,64 @@ module Unitpost
42
63
  end
43
64
  end
44
65
 
66
+ # The `SmsTagsItem` object from the public API.
67
+ # @!attribute name
68
+ # @!attribute value
69
+ SmsTagsItem = Struct.new(:name, :value, keyword_init: true) do
70
+ # @param h [Hash, nil] the decoded API object (string keys)
71
+ # @return [SmsTagsItem, nil]
72
+ def self.from_hash(h)
73
+ return nil if h.nil?
74
+ h = h.transform_keys(&:to_s)
75
+ new(
76
+ name: h["name"],
77
+ value: h["value"]
78
+ )
79
+ end
80
+ end
81
+
82
+ # Who carriers reach about the brand (the email is `contact_email`).
83
+ # @!attribute first_name
84
+ # @!attribute last_name
85
+ # @!attribute phone
86
+ SmsBrandContact = Struct.new(:first_name, :last_name, :phone, keyword_init: true) do
87
+ # @param h [Hash, nil] the decoded API object (string keys)
88
+ # @return [SmsBrandContact, nil]
89
+ def self.from_hash(h)
90
+ return nil if h.nil?
91
+ h = h.transform_keys(&:to_s)
92
+ new(
93
+ first_name: h["first_name"],
94
+ last_name: h["last_name"],
95
+ phone: h["phone"]
96
+ )
97
+ end
98
+ end
99
+
100
+ # The registered business address.
101
+ # @!attribute address1
102
+ # @!attribute address2
103
+ # @!attribute city
104
+ # @!attribute state
105
+ # @!attribute zip_code
106
+ # @!attribute iso_country_code
107
+ SmsBrandAddress = Struct.new(:address1, :address2, :city, :state, :zip_code, :iso_country_code, keyword_init: true) do
108
+ # @param h [Hash, nil] the decoded API object (string keys)
109
+ # @return [SmsBrandAddress, nil]
110
+ def self.from_hash(h)
111
+ return nil if h.nil?
112
+ h = h.transform_keys(&:to_s)
113
+ new(
114
+ address1: h["address1"],
115
+ address2: h["address2"],
116
+ city: h["city"],
117
+ state: h["state"],
118
+ zip_code: h["zip_code"],
119
+ iso_country_code: h["iso_country_code"]
120
+ )
121
+ end
122
+ end
123
+
45
124
  # The `SmsNumberUseCase` object from the public API.
46
125
  # @!attribute name
47
126
  # @!attribute category
@@ -58,6 +137,24 @@ module Unitpost
58
137
  end
59
138
  end
60
139
 
140
+ # The `SmsNumberFeedbackItem` object from the public API.
141
+ # @!attribute reason The carrier's reason code.
142
+ # @!attribute description What to fix, in the carrier's words (redacted).
143
+ # @!attribute link A carrier help page about it, when they gave one.
144
+ SmsNumberFeedbackItem = Struct.new(:reason, :description, :link, keyword_init: true) do
145
+ # @param h [Hash, nil] the decoded API object (string keys)
146
+ # @return [SmsNumberFeedbackItem, nil]
147
+ def self.from_hash(h)
148
+ return nil if h.nil?
149
+ h = h.transform_keys(&:to_s)
150
+ new(
151
+ reason: h["reason"],
152
+ description: h["description"],
153
+ link: h["link"]
154
+ )
155
+ end
156
+ end
157
+
61
158
  # The `SmsNumberSenderIdGroupCountriesItem` object from the public API.
62
159
  # @!attribute country ISO-3166 alpha-2.
63
160
  # @!attribute status One of: pending, action_required, active, rejected, released.
@@ -101,16 +198,20 @@ module Unitpost
101
198
  # @!attribute status One of: queued, scheduled, sending, sent, delivered, failed, suppressed, canceled, received.
102
199
  # @!attribute type One of: transactional, marketing.
103
200
  # @!attribute body
104
- # @!attribute segments Billed units. Outbound: segments. Inbound: 1 when the received text was charged (1¢ in the US and Canada), else 0.
201
+ # @!attribute segments Billed units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0.
105
202
  # @!attribute in_reply_to Inbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
106
203
  # @!attribute received_at Inbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
107
204
  # @!attribute looks_like_opt_out Inbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound.
108
- # @!attribute country
205
+ # @!attribute country The other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known.
109
206
  # @!attribute scheduled_at
110
- # @!attribute last_error Legacy free-text error. Prefer `error.code`.
207
+ # @!attribute last_error The sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text.
111
208
  # @!attribute error Set on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
112
209
  # @!attribute created_at
113
- Sms = Struct.new(:object, :id, :to, :from, :direction, :status, :type, :body, :segments, :in_reply_to, :received_at, :looks_like_opt_out, :country, :scheduled_at, :last_error, :error, :created_at, keyword_init: true) do
210
+ # @!attribute failure_code Set on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook.
211
+ # @!attribute contact_id The contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact.
212
+ # @!attribute participant_opted_out The other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read.
213
+ # @!attribute tags The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts.
214
+ Sms = Struct.new(:object, :id, :to, :from, :direction, :status, :type, :body, :segments, :in_reply_to, :received_at, :looks_like_opt_out, :country, :scheduled_at, :last_error, :error, :created_at, :failure_code, :contact_id, :participant_opted_out, :tags, keyword_init: true) do
114
215
  # @param h [Hash, nil] the decoded API object (string keys)
115
216
  # @return [Sms, nil]
116
217
  def self.from_hash(h)
@@ -133,7 +234,11 @@ module Unitpost
133
234
  scheduled_at: h["scheduled_at"],
134
235
  last_error: h["last_error"],
135
236
  error: SmsError.from_hash(h["error"]),
136
- created_at: h["created_at"]
237
+ created_at: h["created_at"],
238
+ failure_code: h["failure_code"],
239
+ contact_id: h["contact_id"],
240
+ participant_opted_out: h["participant_opted_out"],
241
+ tags: (h["tags"] || []).map { |x| SmsTagsItem.from_hash(x) }
137
242
  )
138
243
  end
139
244
  end
@@ -153,7 +258,19 @@ module Unitpost
153
258
  # @!attribute number_count Non-released senders on this brand (phone numbers and Sender ID countries, any status).
154
259
  # @!attribute editable False once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask.
155
260
  # @!attribute created_at
156
- SmsBrand = Struct.new(:object, :id, :name, :legal_name, :website, :domain, :contact_email, :status, :missing, :ten_dlc_verified, :tax_id_on_file, :number_count, :editable, :created_at, keyword_init: true) do
261
+ # @!attribute dba_name The name the business trades under, when it isn't the legal name.
262
+ # @!attribute sender_id_name The one Sender ID the brand sends under abroad (1–11 characters).
263
+ # @!attribute vertical The brand's industry, in the carriers' words (e.g. `RETAIL`).
264
+ # @!attribute legal_organization_type `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
265
+ # @!attribute registration_number_type
266
+ # @!attribute tax_country
267
+ # @!attribute stock_symbol
268
+ # @!attribute stock_exchange
269
+ # @!attribute contact Who carriers reach about the brand (the email is `contact_email`).
270
+ # @!attribute address The registered business address.
271
+ # @!attribute revision Moves on every material change; a registration keeps the revision it was submitted with.
272
+ # @!attribute archived_at
273
+ SmsBrand = Struct.new(:object, :id, :name, :legal_name, :website, :domain, :contact_email, :status, :missing, :ten_dlc_verified, :tax_id_on_file, :number_count, :editable, :created_at, :dba_name, :sender_id_name, :vertical, :legal_organization_type, :registration_number_type, :tax_country, :stock_symbol, :stock_exchange, :contact, :address, :revision, :archived_at, keyword_init: true) do
157
274
  # @param h [Hash, nil] the decoded API object (string keys)
158
275
  # @return [SmsBrand, nil]
159
276
  def self.from_hash(h)
@@ -173,7 +290,19 @@ module Unitpost
173
290
  tax_id_on_file: h["tax_id_on_file"],
174
291
  number_count: h["number_count"],
175
292
  editable: h["editable"],
176
- created_at: h["created_at"]
293
+ created_at: h["created_at"],
294
+ dba_name: h["dba_name"],
295
+ sender_id_name: h["sender_id_name"],
296
+ vertical: h["vertical"],
297
+ legal_organization_type: h["legal_organization_type"],
298
+ registration_number_type: h["registration_number_type"],
299
+ tax_country: h["tax_country"],
300
+ stock_symbol: h["stock_symbol"],
301
+ stock_exchange: h["stock_exchange"],
302
+ contact: SmsBrandContact.from_hash(h["contact"]),
303
+ address: SmsBrandAddress.from_hash(h["address"]),
304
+ revision: h["revision"],
305
+ archived_at: h["archived_at"]
177
306
  )
178
307
  end
179
308
  end
@@ -186,14 +315,15 @@ module Unitpost
186
315
  # @!attribute status Only `active` numbers can send. One of: pending, action_required, active, rejected, released.
187
316
  # @!attribute is_default Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
188
317
  # @!attribute country ISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded.
189
- # @!attribute two_way Whether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs 1¢. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator.
318
+ # @!attribute two_way Whether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs $0.008 a segment in the US and $0.004 in Canada. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator.
190
319
  # @!attribute reach ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown.
191
320
  # @!attribute brand_id The brand this number is registered under.
192
321
  # @!attribute use_case What carriers approved this number to send. Required for approval; submitted with the number.
193
322
  # @!attribute action_required_reason Set when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`.
194
323
  # @!attribute sender_id_group Present on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set.
195
324
  # @!attribute created_at
196
- SmsNumber = Struct.new(:object, :id, :phone_number, :type, :status, :is_default, :country, :two_way, :reach, :brand_id, :use_case, :action_required_reason, :sender_id_group, :created_at, keyword_init: true) do
325
+ # @!attribute feedback What carriers sent back, item by item, when a toll-free verification needs changes (`action_required`); null otherwise. Fix it on the brand or the messaging program, then POST /sms/numbers/{id}/resubmit (ADR-0159).
326
+ SmsNumber = Struct.new(:object, :id, :phone_number, :type, :status, :is_default, :country, :two_way, :reach, :brand_id, :use_case, :action_required_reason, :sender_id_group, :created_at, :feedback, keyword_init: true) do
197
327
  # @param h [Hash, nil] the decoded API object (string keys)
198
328
  # @return [SmsNumber, nil]
199
329
  def self.from_hash(h)
@@ -213,7 +343,8 @@ module Unitpost
213
343
  use_case: SmsNumberUseCase.from_hash(h["use_case"]),
214
344
  action_required_reason: h["action_required_reason"],
215
345
  sender_id_group: SmsNumberSenderIdGroup.from_hash(h["sender_id_group"]),
216
- created_at: h["created_at"]
346
+ created_at: h["created_at"],
347
+ feedback: (h["feedback"] || []).map { |x| SmsNumberFeedbackItem.from_hash(x) }
217
348
  )
218
349
  end
219
350
  end
@@ -0,0 +1,322 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "securerandom"
4
+ require_relative "http_client"
5
+ require_relative "resources"
6
+ require_relative "webhooks"
7
+
8
+ module Unitpost
9
+ # The organization client (ADR-0171): the second client, for an ORGANIZATION
10
+ # key (ok_live_...). A platform that gives each of its customers a Unitpost
11
+ # workspace uses it to create, close and restore those workspaces, mint their
12
+ # keys, manage the organization's webhook endpoints, read usage per workspace,
13
+ # change a workspace's plan and manage which workspaces share the
14
+ # organization's shared plan.
15
+ #
16
+ # require "unitpost"
17
+ # org = Unitpost::OrganizationClient.new # UNITPOST_ORG_KEY + UNITPOST_ORGANIZATION_ID
18
+ # result = org.workspaces.create({ name: "Acme", external_id: "cust_42" })
19
+ #
20
+ # One credential per client: the workspace client (Unitpost::Client) never
21
+ # calls an organization route, and this one never calls a workspace route. To
22
+ # work inside one of the workspaces, mint its key with workspace_keys.create
23
+ # and make a Unitpost::Client with it. Same transport, retries and errors as
24
+ # the workspace client; every method returns a Unitpost::Result.
25
+ #
26
+ # api_key defaults to ENV["UNITPOST_ORG_KEY"] and organization_id (org_...) to
27
+ # ENV["UNITPOST_ORGANIZATION_ID"]. The organization key is never read from
28
+ # UNITPOST_API_KEY.
29
+ class OrganizationClient
30
+ # The organization every call acts on (org_...).
31
+ attr_reader :organization_id
32
+ # The organization's workspaces: list, create, get, update, close, restore.
33
+ attr_reader :workspaces
34
+ # Keys for one of the organization's workspaces: create mints one (the
35
+ # secret is in that answer only).
36
+ attr_reader :workspace_keys
37
+ # The organization's webhook endpoints: events from every workspace it owns,
38
+ # each with workspace_id and external_id.
39
+ attr_reader :webhooks
40
+ # Usage per workspace for a billing period (list).
41
+ attr_reader :usage
42
+ # A plan change for one workspace the organization pays for: quote, read, confirm.
43
+ attr_reader :plan_quotes
44
+ # The organization's shared plan: read it, and add, cap or remove the
45
+ # workspaces on it.
46
+ attr_reader :shared_plan
47
+
48
+ def initialize(api_key: nil, organization_id: nil, base_url: nil, timeout: 30, headers: {}, adapter: nil,
49
+ stubs: nil, max_retries: 2, retry_base_delay: 0.5, max_retry_delay: 20.0, sleeper: nil)
50
+ key = api_key || ENV.fetch("UNITPOST_ORG_KEY", nil)
51
+ if key.nil? || key.empty?
52
+ raise Unitpost::Error.new(
53
+ code: "missing_api_key",
54
+ message: "No organization key provided. Pass Unitpost::OrganizationClient.new(api_key:) or set the UNITPOST_ORG_KEY environment variable. An Owner or Admin makes one in the dashboard under Organization → API.",
55
+ status: 0
56
+ )
57
+ end
58
+ org_id = organization_id || ENV.fetch("UNITPOST_ORGANIZATION_ID", nil)
59
+ if org_id.nil? || org_id.empty?
60
+ raise Unitpost::Error.new(
61
+ code: "missing_organization_id",
62
+ message: "No organization id provided. Pass Unitpost::OrganizationClient.new(organization_id:) (`org_…`) or set the UNITPOST_ORGANIZATION_ID environment variable.",
63
+ status: 0
64
+ )
65
+ end
66
+ http = HttpClient.new(
67
+ api_key: key,
68
+ base_url: base_url,
69
+ timeout: timeout,
70
+ headers: headers,
71
+ adapter: adapter,
72
+ stubs: stubs,
73
+ max_retries: max_retries,
74
+ retry_base_delay: retry_base_delay,
75
+ max_retry_delay: max_retry_delay,
76
+ sleeper: sleeper
77
+ )
78
+ @organization_id = org_id
79
+ @workspaces = OrganizationResources::Workspaces.new(http, org_id)
80
+ @workspace_keys = OrganizationResources::WorkspaceKeys.new(http, org_id)
81
+ @webhooks = OrganizationResources::Webhooks.new(http, org_id)
82
+ @usage = OrganizationResources::Usage.new(http, org_id)
83
+ @plan_quotes = OrganizationResources::PlanQuotes.new(http, org_id)
84
+ @shared_plan = OrganizationResources::SharedPlan.new(http, org_id)
85
+ end
86
+ end
87
+
88
+ module OrganizationResources
89
+ class Base < Resources::Base
90
+ def initialize(http, organization_id)
91
+ super(http)
92
+ @organization_id = organization_id
93
+ end
94
+ end
95
+
96
+ class Workspaces < Base
97
+ # The organization's workspaces, newest first (cursor-paginated).
98
+ # external_id keeps only the workspace you gave that id. Needs
99
+ # organizations:read.
100
+ def list(limit: nil, after: nil, before: nil, external_id: nil)
101
+ @http.request(
102
+ "GET", "/organizations/#{enc(@organization_id)}/workspaces",
103
+ query: list_params(limit: limit, after: after, before: before, external_id: external_id)
104
+ )
105
+ end
106
+
107
+ # Iterate every workspace of the organization (same filters as list).
108
+ def list_all(**params)
109
+ paginate("/organizations/#{enc(@organization_id)}/workspaces", params)
110
+ end
111
+
112
+ # Create a workspace (201). Its Owner is the key's creator. An
113
+ # Idempotency-Key is generated when you don't pass one, so a retry can't
114
+ # make two. Needs organizations:write.
115
+ def create(body, idempotency_key: nil)
116
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/workspaces", body: body, idempotency_key: idempotency_key || SecureRandom.uuid)
117
+ end
118
+
119
+ # One workspace (ws_...). Needs organizations:read.
120
+ def get(workspace_id)
121
+ @http.request("GET", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}")
122
+ end
123
+
124
+ # Rename it, set its external_id or its SMS purchases cap. Needs
125
+ # organizations:write.
126
+ def update(workspace_id, body)
127
+ @http.request("PATCH", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}", body: body)
128
+ end
129
+
130
+ # Close it: it stops sending at once. It can be restored for 30 days
131
+ # (restorable_until); unless restored, it is deleted once those 30 days
132
+ # are over and 7 days have passed since the end of the billing period it
133
+ # closed in, whichever is later (deletes_at). Closing twice changes
134
+ # nothing. Needs organizations:write.
135
+ def close(workspace_id)
136
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}/close")
137
+ end
138
+
139
+ # Restore a closed workspace within its 30 days. Needs organizations:write.
140
+ def restore(workspace_id)
141
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}/restore")
142
+ end
143
+ end
144
+
145
+ class WorkspaceKeys < Base
146
+ # Mint a workspace key (201) for one of the organization's workspaces. The
147
+ # answer holds the secret (key) once; use it with Unitpost::Client.new(api_key: key).
148
+ # Needs organizations:write.
149
+ def create(workspace_id, body)
150
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}/api-keys", body: body)
151
+ end
152
+ end
153
+
154
+ class Webhooks < Base
155
+ # The organization's webhook endpoints. Needs organizations:read.
156
+ def list(limit: nil, after: nil, before: nil)
157
+ @http.request(
158
+ "GET", "/organizations/#{enc(@organization_id)}/webhooks",
159
+ query: list_params(limit: limit, after: after, before: before)
160
+ )
161
+ end
162
+
163
+ # Iterate every webhook endpoint of the organization. Needs
164
+ # organizations:read.
165
+ def list_all(**params)
166
+ paginate("/organizations/#{enc(@organization_id)}/webhooks", params)
167
+ end
168
+
169
+ # Create an endpoint. The answer has signing_secret exactly once. Needs
170
+ # organizations:write.
171
+ def create(body)
172
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/webhooks", body: body)
173
+ end
174
+
175
+ # One endpoint (wh_...). Needs organizations:read.
176
+ def get(webhook_id)
177
+ @http.request("GET", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}")
178
+ end
179
+
180
+ # Change an endpoint. Needs organizations:write.
181
+ def update(webhook_id, body)
182
+ @http.request("PATCH", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}", body: body)
183
+ end
184
+
185
+ # Delete an endpoint. Needs organizations:write.
186
+ def delete(webhook_id)
187
+ @http.request("DELETE", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}")
188
+ end
189
+
190
+ # Mint a new signing secret; the answer carries it exactly once. Needs
191
+ # organizations:write.
192
+ def rotate_secret(webhook_id)
193
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}/rotate-secret")
194
+ end
195
+
196
+ # Fire a sample event at the endpoint. Needs organizations:write.
197
+ def test(webhook_id)
198
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}/test")
199
+ end
200
+
201
+ # The endpoint's delivery log, newest first; each row names its
202
+ # workspace_id and external_id. filters: status, event_type,
203
+ # workspace_id, external_id. Needs organizations:write (the rows carry
204
+ # each event's data, so organizations:read alone is a 403).
205
+ def list_deliveries(webhook_id, limit: nil, after: nil, before: nil, **filters)
206
+ @http.request(
207
+ "GET", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}/deliveries",
208
+ query: list_params(limit: limit, after: after, before: before, **filters)
209
+ )
210
+ end
211
+
212
+ # Iterate the endpoint's whole delivery log (same filters as
213
+ # list_deliveries). Needs organizations:write.
214
+ def list_all_deliveries(webhook_id, **params)
215
+ paginate("/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}/deliveries", params)
216
+ end
217
+
218
+ # Deliver one event to the endpoint again (202). Needs organizations:write.
219
+ def replay_delivery(webhook_id, delivery_id)
220
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}/deliveries/#{enc(delivery_id)}/replay")
221
+ end
222
+
223
+ # Deliver the backlog (202); { include_failed: true } adds the ones that
224
+ # failed for good. Needs organizations:write.
225
+ def flush(webhook_id, body = {})
226
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/webhooks/#{enc(webhook_id)}/flush", body: body)
227
+ end
228
+
229
+ # Verify a delivery's signature and return the parsed event (the same as
230
+ # Unitpost.verify_webhook).
231
+ def verify(payload:, secret:, headers:, tolerance_seconds: 300)
232
+ Unitpost::Webhooks.verify(
233
+ payload: payload,
234
+ secret: secret,
235
+ headers: headers,
236
+ tolerance_seconds: tolerance_seconds
237
+ )
238
+ end
239
+ end
240
+
241
+ class Usage < Base
242
+ # Usage per workspace (workspace_usage rows), each for that workspace's
243
+ # own billing period containing period ("current" by default, or an ISO
244
+ # 8601 instant). Paged by workspace. Needs organizations:read.
245
+ def list(period: nil, external_id: nil, limit: nil, after: nil, before: nil)
246
+ @http.request(
247
+ "GET", "/organizations/#{enc(@organization_id)}/usage",
248
+ query: list_params(limit: limit, after: after, before: before, period: period, external_id: external_id)
249
+ )
250
+ end
251
+
252
+ # Iterate the usage row of every workspace (same filters as list),
253
+ # paging by the last row's workspace_id. Needs organizations:read.
254
+ def list_all(**params)
255
+ paginate("/organizations/#{enc(@organization_id)}/usage", params, cursor: "workspace_id")
256
+ end
257
+ end
258
+
259
+ class PlanQuotes < Base
260
+ # Price a plan change for one workspace the organization pays for (201).
261
+ # Charges nothing; the quote lasts 10 minutes and holds a single-use
262
+ # confirm_token (only in this answer). Its "pending_change" is a
263
+ # downgrade already scheduled for the period end, or nil; with one, a
264
+ # quote for the current plan and tier is a "noop" whose confirm cancels
265
+ # it. Needs organizations:billing.
266
+ def create(workspace_id, body)
267
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}/plan-quotes", body: body)
268
+ end
269
+
270
+ # One quote (pq_...). Needs organizations:read.
271
+ def get(workspace_id, quote_id)
272
+ @http.request("GET", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}/plan-quotes/#{enc(quote_id)}")
273
+ end
274
+
275
+ # Apply the quoted change and charge it. An Idempotency-Key is generated
276
+ # when you don't pass one, so a retry can't charge twice. Needs
277
+ # organizations:billing.
278
+ def confirm(workspace_id, quote_id, body, idempotency_key: nil)
279
+ @http.request("POST", "/organizations/#{enc(@organization_id)}/workspaces/#{enc(workspace_id)}/plan-quotes/#{enc(quote_id)}/confirm", body: body, idempotency_key: idempotency_key || SecureRandom.uuid)
280
+ end
281
+ end
282
+
283
+ class SharedPlan < Base
284
+ # The organization's shared plan (one plan whose allowance its
285
+ # workspaces share): whether it's turned on (approved), its status
286
+ # ("none" until one is bought), plan, price and period, and this
287
+ # period's used_cents, overage_cents, paused. Buying, upgrading and
288
+ # ending it are done in the dashboard. Needs organizations:read.
289
+ def get
290
+ @http.request("GET", "/organizations/#{enc(@organization_id)}/shared-plan")
291
+ end
292
+
293
+ # Every workspace on the shared plan, with its cap and what it drew this
294
+ # period (one page). Needs organizations:read.
295
+ def list_workspaces
296
+ @http.request("GET", "/organizations/#{enc(@organization_id)}/shared-plan/workspaces")
297
+ end
298
+
299
+ # Put a workspace on the shared plan (it moves onto the organization's
300
+ # card), or set its cap when it's already on it. Refusals carry the
301
+ # reason in error details[0]["code"] (own_plan, limit_reached, ...). An
302
+ # Idempotency-Key is generated when you don't pass one, so a retry
303
+ # answers what the first call did. Needs organizations:billing.
304
+ def add_workspace(workspace_id, body = {}, idempotency_key: nil)
305
+ @http.request("PUT", "/organizations/#{enc(@organization_id)}/shared-plan/workspaces/#{enc(workspace_id)}", body: body, idempotency_key: idempotency_key || SecureRandom.uuid)
306
+ end
307
+
308
+ # Set a workspace's cap (cap_cents; nil removes it). Needs
309
+ # organizations:billing.
310
+ def update_workspace(workspace_id, body)
311
+ @http.request("PATCH", "/organizations/#{enc(@organization_id)}/shared-plan/workspaces/#{enc(workspace_id)}", body: body)
312
+ end
313
+
314
+ # Take a workspace off the shared plan: drops_to is "free" or
315
+ # "needs_plan"; one not on it answers left: false. An Idempotency-Key is
316
+ # generated when you don't pass one. Needs organizations:billing.
317
+ def remove_workspace(workspace_id, idempotency_key: nil)
318
+ @http.request("DELETE", "/organizations/#{enc(@organization_id)}/shared-plan/workspaces/#{enc(workspace_id)}", idempotency_key: idempotency_key || SecureRandom.uuid)
319
+ end
320
+ end
321
+ end
322
+ end