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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +320 -0
- data/README.md +59 -11
- data/lib/unitpost/client.rb +14 -2
- data/lib/unitpost/errors.rb +5 -3
- data/lib/unitpost/generated/operations.rb +2432 -173
- data/lib/unitpost/generated/sms_models.rb +141 -10
- data/lib/unitpost/organization.rb +322 -0
- data/lib/unitpost/resources.rb +1125 -18
- data/lib/unitpost/version.rb +1 -1
- data/lib/unitpost.rb +1 -0
- metadata +4 -2
|
@@ -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:
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|