unitpost 0.3.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.
@@ -0,0 +1,353 @@
1
+ # Code generated by @unitpost/sdk-codegen from the public OpenAPI spec.
2
+ # DO NOT EDIT BY HAND. Run `npm run sdk:generate` to regenerate.
3
+ # Source of truth: apps/web/docs/openapi.json (itself derived from the API's
4
+ # Zod schemas and CI-gated for drift).
5
+
6
+ # frozen_string_literal: true
7
+
8
+ module Unitpost
9
+ module Generated
10
+ # Why a message was skipped before reaching the carrier. `out_of_reach`: no
11
+ # sender covers the recipient's country; `unsupported_country`: no
12
+ # compliance rule for the country yet, or SMS to that country is paused for
13
+ # now (every message, transactional included, until it resumes); `no_phone`:
14
+ # the contact has no SMS handle; `opted_out`: STOP / suppression /
15
+ # unreachable; `no_marketing_consent`: marketing without express consent;
16
+ # `quiet_hours_deferred`: delayed to the recipient's local window;
17
+ # `sender_not_active`: the sender lost approval.
18
+ module SmsSkipReason
19
+ OUT_OF_REACH = "out_of_reach"
20
+ UNSUPPORTED_COUNTRY = "unsupported_country"
21
+ NO_PHONE = "no_phone"
22
+ OPTED_OUT = "opted_out"
23
+ NO_MARKETING_CONSENT = "no_marketing_consent"
24
+ QUIET_HOURS_DEFERRED = "quiet_hours_deferred"
25
+ SENDER_NOT_ACTIVE = "sender_not_active"
26
+ ALL = [OUT_OF_REACH, UNSUPPORTED_COUNTRY, NO_PHONE, OPTED_OUT, NO_MARKETING_CONSENT, QUIET_HOURS_DEFERRED, SENDER_NOT_ACTIVE].freeze
27
+ end
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
+
50
+ # The `SmsError` object from the public API.
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.
52
+ # @!attribute message Human-readable sentence for `code`.
53
+ SmsError = Struct.new(:code, :message, keyword_init: true) do
54
+ # @param h [Hash, nil] the decoded API object (string keys)
55
+ # @return [SmsError, nil]
56
+ def self.from_hash(h)
57
+ return nil if h.nil?
58
+ h = h.transform_keys(&:to_s)
59
+ new(
60
+ code: h["code"],
61
+ message: h["message"]
62
+ )
63
+ end
64
+ end
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
+
124
+ # The `SmsNumberUseCase` object from the public API.
125
+ # @!attribute name
126
+ # @!attribute category
127
+ SmsNumberUseCase = Struct.new(:name, :category, keyword_init: true) do
128
+ # @param h [Hash, nil] the decoded API object (string keys)
129
+ # @return [SmsNumberUseCase, nil]
130
+ def self.from_hash(h)
131
+ return nil if h.nil?
132
+ h = h.transform_keys(&:to_s)
133
+ new(
134
+ name: h["name"],
135
+ category: h["category"]
136
+ )
137
+ end
138
+ end
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
+
158
+ # The `SmsNumberSenderIdGroupCountriesItem` object from the public API.
159
+ # @!attribute country ISO-3166 alpha-2.
160
+ # @!attribute status One of: pending, action_required, active, rejected, released.
161
+ SmsNumberSenderIdGroupCountriesItem = Struct.new(:country, :status, keyword_init: true) do
162
+ # @param h [Hash, nil] the decoded API object (string keys)
163
+ # @return [SmsNumberSenderIdGroupCountriesItem, nil]
164
+ def self.from_hash(h)
165
+ return nil if h.nil?
166
+ h = h.transform_keys(&:to_s)
167
+ new(
168
+ country: h["country"],
169
+ status: h["status"]
170
+ )
171
+ end
172
+ end
173
+
174
+ # The `SmsNumberSenderIdGroup` object from the public API.
175
+ # @!attribute name The Sender ID string recipients see.
176
+ # @!attribute brand_id The brand that owns this Sender ID.
177
+ # @!attribute countries Every country this Sender ID is enabled for, with each country's own status.
178
+ SmsNumberSenderIdGroup = Struct.new(:name, :brand_id, :countries, keyword_init: true) do
179
+ # @param h [Hash, nil] the decoded API object (string keys)
180
+ # @return [SmsNumberSenderIdGroup, nil]
181
+ def self.from_hash(h)
182
+ return nil if h.nil?
183
+ h = h.transform_keys(&:to_s)
184
+ new(
185
+ name: h["name"],
186
+ brand_id: h["brand_id"],
187
+ countries: (h["countries"] || []).map { |x| SmsNumberSenderIdGroupCountriesItem.from_hash(x) }
188
+ )
189
+ end
190
+ end
191
+
192
+ # The `Sms` object from the public API.
193
+ # @!attribute object Always "sms".
194
+ # @!attribute id
195
+ # @!attribute to
196
+ # @!attribute from
197
+ # @!attribute direction One of: outbound, inbound.
198
+ # @!attribute status One of: queued, scheduled, sending, sent, delivered, failed, suppressed, canceled, received.
199
+ # @!attribute type One of: transactional, marketing.
200
+ # @!attribute body
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.
202
+ # @!attribute in_reply_to Inbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
203
+ # @!attribute received_at Inbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
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.
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.
206
+ # @!attribute scheduled_at
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.
208
+ # @!attribute error Set on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
209
+ # @!attribute created_at
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
215
+ # @param h [Hash, nil] the decoded API object (string keys)
216
+ # @return [Sms, nil]
217
+ def self.from_hash(h)
218
+ return nil if h.nil?
219
+ h = h.transform_keys(&:to_s)
220
+ new(
221
+ object: h["object"],
222
+ id: h["id"],
223
+ to: h["to"],
224
+ from: h["from"],
225
+ direction: h["direction"],
226
+ status: h["status"],
227
+ type: h["type"],
228
+ body: h["body"],
229
+ segments: h["segments"],
230
+ in_reply_to: h["in_reply_to"],
231
+ received_at: h["received_at"],
232
+ looks_like_opt_out: h["looks_like_opt_out"],
233
+ country: h["country"],
234
+ scheduled_at: h["scheduled_at"],
235
+ last_error: h["last_error"],
236
+ error: SmsError.from_hash(h["error"]),
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) }
242
+ )
243
+ end
244
+ end
245
+
246
+ # The `SmsBrand` object from the public API.
247
+ # @!attribute object Always "sms_brand".
248
+ # @!attribute id Prefixed brand id, e.g. `sbrand_…`.
249
+ # @!attribute name Public-facing brand name.
250
+ # @!attribute legal_name Registered legal entity name.
251
+ # @!attribute website Brand website URL.
252
+ # @!attribute domain Registrable domain derived from the website. The brand contact email must be on this domain.
253
+ # @!attribute contact_email
254
+ # @!attribute status `incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier. One of: incomplete, ready, pending, action_required, verified, rejected, archived.
255
+ # @!attribute missing Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing.
256
+ # @!attribute ten_dlc_verified True when the 10DLC brand registration is approved.
257
+ # @!attribute tax_id_on_file
258
+ # @!attribute number_count Non-released senders on this brand (phone numbers and Sender ID countries, any status).
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.
260
+ # @!attribute created_at
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
274
+ # @param h [Hash, nil] the decoded API object (string keys)
275
+ # @return [SmsBrand, nil]
276
+ def self.from_hash(h)
277
+ return nil if h.nil?
278
+ h = h.transform_keys(&:to_s)
279
+ new(
280
+ object: h["object"],
281
+ id: h["id"],
282
+ name: h["name"],
283
+ legal_name: h["legal_name"],
284
+ website: h["website"],
285
+ domain: h["domain"],
286
+ contact_email: h["contact_email"],
287
+ status: h["status"],
288
+ missing: h["missing"],
289
+ ten_dlc_verified: h["ten_dlc_verified"],
290
+ tax_id_on_file: h["tax_id_on_file"],
291
+ number_count: h["number_count"],
292
+ editable: h["editable"],
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"]
306
+ )
307
+ end
308
+ end
309
+
310
+ # The `SmsNumber` object from the public API.
311
+ # @!attribute object Always "sms_number".
312
+ # @!attribute id Prefixed number id, e.g. `snum_…`.
313
+ # @!attribute phone_number E.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval.
314
+ # @!attribute type `long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender. One of: toll_free, ten_dlc, long_code, sender_id, simulator.
315
+ # @!attribute status Only `active` numbers can send. One of: pending, action_required, active, rejected, released.
316
+ # @!attribute is_default Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
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.
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.
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.
320
+ # @!attribute brand_id The brand this number is registered under.
321
+ # @!attribute use_case What carriers approved this number to send. Required for approval; submitted with the number.
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`.
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.
324
+ # @!attribute created_at
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
327
+ # @param h [Hash, nil] the decoded API object (string keys)
328
+ # @return [SmsNumber, nil]
329
+ def self.from_hash(h)
330
+ return nil if h.nil?
331
+ h = h.transform_keys(&:to_s)
332
+ new(
333
+ object: h["object"],
334
+ id: h["id"],
335
+ phone_number: h["phone_number"],
336
+ type: h["type"],
337
+ status: h["status"],
338
+ is_default: h["is_default"],
339
+ country: h["country"],
340
+ two_way: h["two_way"],
341
+ reach: h["reach"],
342
+ brand_id: h["brand_id"],
343
+ use_case: SmsNumberUseCase.from_hash(h["use_case"]),
344
+ action_required_reason: h["action_required_reason"],
345
+ sender_id_group: SmsNumberSenderIdGroup.from_hash(h["sender_id_group"]),
346
+ created_at: h["created_at"],
347
+ feedback: (h["feedback"] || []).map { |x| SmsNumberFeedbackItem.from_hash(x) }
348
+ )
349
+ end
350
+ end
351
+
352
+ end
353
+ 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