@unboundcx/sdk 4.13.138 → 4.13.140

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,318 @@
1
+ import { internalRequest } from '../../base.js';
2
+
3
+ // phoneNumbers/porting-orders.js :: porting-order CRUD + portability checks
4
+ export const portingOrderMethods = {
5
+ /**
6
+ * Check portability of phone numbers using two-phase validation
7
+ *
8
+ * Phase 1 (Default): Internal validation using LRN lookup
9
+ * - Validates ownership, duplicates, and carrier compatibility
10
+ * - Sets portabilityStatus to 'pending'
11
+ *
12
+ * Phase 2 (runPortabilityCheck: true): External validation
13
+ * - Runs full portability check with carrier
14
+ * - Updates portabilityStatus to 'portable', 'not-portable', or 'error'
15
+ *
16
+ * @param {Object} params
17
+ * @param {string[]} params.phoneNumbers - Array of +E.164 formatted phone numbers
18
+ * @param {string} [params.portingOrderId] - Optional porting order ID to save results to
19
+ * @param {boolean} [params.runPortabilityCheck=false] - Run external portability validation
20
+ * @returns {Promise<Object>} Portability check results
21
+ */
22
+ async checkPortability({
23
+ phoneNumbers,
24
+ portingOrderId,
25
+ runPortabilityCheck = false,
26
+ }) {
27
+ this.sdk.validateParams(
28
+ { phoneNumbers, runPortabilityCheck },
29
+ {
30
+ phoneNumbers: { type: 'array', required: true },
31
+ runPortabilityCheck: { type: 'boolean', required: false },
32
+ },
33
+ );
34
+
35
+ const body = { phoneNumbers, runPortabilityCheck };
36
+ if (portingOrderId) body.portingOrderId = portingOrderId;
37
+
38
+ const result = await internalRequest(this.sdk,
39
+ '/phoneNumbers/porting/portability-check',
40
+ 'POST',
41
+ {
42
+ body: body,
43
+ },
44
+ );
45
+ return result;
46
+ },
47
+
48
+ /**
49
+ * Create a draft porting order (no phone numbers - add them via checkPortability)
50
+ * @param {Object} params
51
+ * @param {string} [params.customerReference] - Customer-specified reference number
52
+ * @param {Object} [params.endUser] - End user information
53
+ * @param {Object} [params.endUser.admin] - Admin contact info
54
+ * @param {string} [params.endUser.admin.entityName] - Business/entity name
55
+ * @param {string} [params.endUser.admin.authPersonName] - Authorized person name
56
+ * @param {string} [params.endUser.admin.billingPhoneNumber] - Billing phone number
57
+ * @param {string} [params.endUser.admin.accountNumber] - Account number with current provider
58
+ * @param {string} [params.endUser.admin.taxIdentifier] - Tax identification number (EU)
59
+ * @param {string} [params.endUser.admin.pinPasscode] - PIN/passcode for account access
60
+ * @param {string} [params.endUser.admin.businessIdentifier] - Business identifier (EU)
61
+ * @param {Object} [params.endUser.location] - Location information
62
+ * @param {string} [params.endUser.location.streetAddress] - Street address
63
+ * @param {string} [params.endUser.location.extendedAddress] - Apt/suite/etc
64
+ * @param {string} [params.endUser.location.locality] - City
65
+ * @param {string} [params.endUser.location.administrativeArea] - State/province
66
+ * @param {string} [params.endUser.location.postalCode] - ZIP/postal code
67
+ * @param {string} [params.endUser.location.countryCode] - 2-letter country code
68
+ * @param {Object} [params.activationSettings] - Activation preferences
69
+ * @param {string} [params.activationSettings.focDatetimeRequested] - Requested FOC date/time (ISO 8601 UTC)
70
+ * @param {boolean} [params.activationSettings.fastPortEligible] - Request fast port if available
71
+ * @param {string} [params.portOrderType] - Port type: 'full' or 'partial' (defaults to 'full')
72
+ * @param {string[]} [params.tags] - Array of tags for organization
73
+ * @returns {Promise<Object>} Created draft porting order with ID and status 'draft'
74
+ * @example
75
+ * // Create empty draft order, then add numbers via checkPortability
76
+ * const order = await sdk.phoneNumbers.createPortingOrder({
77
+ * customerReference: "CUST-123",
78
+ * endUser: { admin: { entityName: "My Company" } }
79
+ * });
80
+ *
81
+ * // Phase 1: Add numbers with internal validation (pending status)
82
+ * await sdk.phoneNumbers.checkPortability({
83
+ * phoneNumbers: ["+15551234567"],
84
+ * portingOrderId: order.id
85
+ * });
86
+ *
87
+ * // Phase 2: Run external portability check when ready
88
+ * await sdk.phoneNumbers.checkPortability({
89
+ * phoneNumbers: ["+15551234567"],
90
+ * portingOrderId: order.id,
91
+ * runPortabilityCheck: true
92
+ * });
93
+ */
94
+ async createPortingOrder({
95
+ customerReference,
96
+ endUser,
97
+ activationSettings,
98
+ portOrderType,
99
+ tags,
100
+ } = {}) {
101
+ // Creates draft order without phone numbers - use checkPortability to add them
102
+ const body = {};
103
+ if (customerReference) body.customerReference = customerReference;
104
+ if (endUser) body.endUser = endUser;
105
+ if (activationSettings) body.activationSettings = activationSettings;
106
+ if (portOrderType) body.portOrderType = portOrderType;
107
+ if (tags) body.tags = tags;
108
+
109
+ const result = await internalRequest(this.sdk,
110
+ '/phoneNumbers/porting/orders',
111
+ 'POST',
112
+ {
113
+ body: body,
114
+ },
115
+ );
116
+ return result;
117
+ },
118
+
119
+ async getPortingOrders({
120
+ page,
121
+ status,
122
+ customerReference,
123
+ sort,
124
+ limit,
125
+ id,
126
+ operatorType = 'contains',
127
+ } = {}) {
128
+ const query = {
129
+ page,
130
+ status,
131
+ customerReference,
132
+ id,
133
+ operatorType,
134
+ sort,
135
+ limit,
136
+ };
137
+
138
+ const url = '/phoneNumbers/porting/orders';
139
+
140
+ const params = {
141
+ query,
142
+ };
143
+
144
+ const result = await internalRequest(this.sdk, url, 'GET', params);
145
+ return result;
146
+ },
147
+
148
+ /**
149
+ * Get a porting order with optional related data
150
+ * @param {string} id - Porting order ID
151
+ * @param {Object} [options]
152
+ * @param {boolean} [options.includePhoneNumbers=true] - Include phone numbers array
153
+ * @param {boolean} [options.includeExceptions=true] - Include exceptions array
154
+ * @param {boolean} [options.includeDocuments=true] - Include documents array with upload status
155
+ * @returns {Promise<Object>} Porting order with requested related data
156
+ */
157
+ async getPortingOrder(
158
+ id,
159
+ {
160
+ includePhoneNumbers = true,
161
+ includeExceptions = true,
162
+ includeDocuments = true,
163
+ } = {},
164
+ ) {
165
+ this.sdk.validateParams(
166
+ { id },
167
+ {
168
+ id: { type: 'string', required: true },
169
+ },
170
+ );
171
+
172
+ const params = new URLSearchParams();
173
+ if (includePhoneNumbers !== undefined)
174
+ params.append('includePhoneNumbers', includePhoneNumbers);
175
+ if (includeExceptions !== undefined)
176
+ params.append('includeExceptions', includeExceptions);
177
+ if (includeDocuments !== undefined)
178
+ params.append('includeDocuments', includeDocuments);
179
+
180
+ const queryString = params.toString();
181
+ const url = queryString
182
+ ? `/phoneNumbers/porting/orders/${id}?${queryString}`
183
+ : `/phoneNumbers/porting/orders/${id}`;
184
+
185
+ const result = await internalRequest(this.sdk, url, 'GET');
186
+ return result;
187
+ },
188
+
189
+ /**
190
+ * Update a draft porting order (order info only - manage numbers via checkPortability)
191
+ * @param {string} id - Porting order ID
192
+ * @param {Object} params - Order information to update
193
+ * @param {string} [params.customerReference] - Customer-specified reference number
194
+ * @param {Object} [params.endUser] - End user information
195
+ * @param {Object} [params.activationSettings] - Activation preferences
196
+ * @param {string} [params.portOrderType] - Port type: 'full' or 'partial'
197
+ * @param {string[]} [params.tags] - Array of tags for organization
198
+ * @returns {Promise<Object>} Updated porting order
199
+ */
200
+ async updatePortingOrder(
201
+ id,
202
+ {
203
+ customerReference,
204
+ endUser,
205
+ activationSettings,
206
+ portOrderType,
207
+ tags,
208
+ } = {},
209
+ ) {
210
+ this.sdk.validateParams(
211
+ { id },
212
+ {
213
+ id: { type: 'string', required: true },
214
+ },
215
+ );
216
+
217
+ const body = {};
218
+
219
+ if (customerReference) body.customerReference = customerReference;
220
+ if (endUser) body.endUser = endUser;
221
+ if (activationSettings) body.activationSettings = activationSettings;
222
+ if (portOrderType) body.portOrderType = portOrderType;
223
+ if (tags) body.tags = tags;
224
+
225
+ const result = await internalRequest(this.sdk,
226
+ `/phoneNumbers/porting/orders/${id}`,
227
+ 'PUT',
228
+ {
229
+ body: body,
230
+ },
231
+ );
232
+ return result;
233
+ },
234
+
235
+ /**
236
+ * Submit a draft porting order for processing (validates all required fields)
237
+ * @param {string} id - Porting order ID
238
+ * @returns {Promise<Object>} Submitted porting order with Telnyx status
239
+ */
240
+ async submitPortingOrder(id) {
241
+ this.sdk.validateParams(
242
+ { id },
243
+ {
244
+ id: { type: 'string', required: true },
245
+ },
246
+ );
247
+
248
+ // Submit the draft order (status is implied)
249
+ const body = {
250
+ status: 'submit',
251
+ };
252
+
253
+ const result = await internalRequest(this.sdk,
254
+ `/phoneNumbers/porting/orders/${id}`,
255
+ 'PUT',
256
+ {
257
+ body: body,
258
+ },
259
+ );
260
+ return result;
261
+ },
262
+
263
+ /**
264
+ * Delete/cancel a porting order (soft delete)
265
+ * - Draft orders: Immediately cancelled locally
266
+ * - Submitted orders: Cancelled via Telnyx, then status updated to cancel-pending
267
+ * - Cannot delete orders within 48 hours of FOC date
268
+ * - Cannot delete already completed or cancelled orders
269
+ * @param {string} id - Porting order ID
270
+ * @returns {Promise<Object>} Cancellation result with new status
271
+ */
272
+ async deletePortingOrder(id) {
273
+ this.sdk.validateParams(
274
+ { id },
275
+ {
276
+ id: { type: 'string', required: true },
277
+ },
278
+ );
279
+
280
+ const result = await internalRequest(this.sdk,
281
+ `/phoneNumbers/porting/orders/${id}`,
282
+ 'DELETE',
283
+ );
284
+ return result;
285
+ },
286
+
287
+ /**
288
+ * Remove a specific phone number from a porting order
289
+ * - Only works on draft orders (not submitted orders)
290
+ * - Cannot remove the last phone number (delete entire order instead)
291
+ * - Validates that phone number exists in the order
292
+ * @param {string} portingOrderId - Porting order ID
293
+ * @param {string} phoneNumber - Phone number to remove (+E.164 format)
294
+ * @returns {Promise<Object>} Removal confirmation with updated counts
295
+ * @example
296
+ * await sdk.phoneNumbers.removePhoneNumberFromOrder(
297
+ * "port_123...",
298
+ * "+15551234567"
299
+ * );
300
+ */
301
+ async removePhoneNumberFromOrder(portingOrderId, phoneNumber) {
302
+ this.sdk.validateParams(
303
+ { portingOrderId, phoneNumber },
304
+ {
305
+ portingOrderId: { type: 'string', required: true },
306
+ phoneNumber: { type: 'string', required: true },
307
+ },
308
+ );
309
+
310
+ const result = await internalRequest(this.sdk,
311
+ `/phoneNumbers/porting/orders/${encodeURIComponent(
312
+ portingOrderId,
313
+ )}/numbers/${encodeURIComponent(phoneNumber)}`,
314
+ 'DELETE',
315
+ );
316
+ return result;
317
+ },
318
+ };
@@ -0,0 +1,181 @@
1
+ import { internalRequest } from '../../base.js';
2
+
3
+ // phoneNumbers/search.js :: search/lookup methods :: number search, routing options, countries, formatting
4
+ export const searchMethods = {
5
+ async search({
6
+ type,
7
+ country,
8
+ state,
9
+ city,
10
+ startsWith,
11
+ endsWith,
12
+ contains,
13
+ limit,
14
+ minimumBlockSize,
15
+ sms,
16
+ mms,
17
+ voice,
18
+ }) {
19
+ // Validate optional parameters
20
+ const validationSchema = {};
21
+ if ('type' in arguments[0]) validationSchema.type = { type: 'string' };
22
+ if ('country' in arguments[0])
23
+ validationSchema.country = { type: 'string' };
24
+ if ('state' in arguments[0]) validationSchema.state = { type: 'string' };
25
+ if ('city' in arguments[0]) validationSchema.city = { type: 'string' };
26
+ if ('startsWith' in arguments[0])
27
+ validationSchema.startsWith = { type: 'string' };
28
+ if ('endsWith' in arguments[0])
29
+ validationSchema.endsWith = { type: 'string' };
30
+ if ('contains' in arguments[0])
31
+ validationSchema.contains = { type: 'string' };
32
+ if ('limit' in arguments[0]) validationSchema.limit = { type: 'number' };
33
+ if ('minimumBlockSize' in arguments[0])
34
+ validationSchema.minimumBlockSize = { type: 'number' };
35
+ if ('sms' in arguments[0]) validationSchema.sms = { type: 'boolean' };
36
+ if ('mms' in arguments[0]) validationSchema.mms = { type: 'boolean' };
37
+ if ('voice' in arguments[0]) validationSchema.voice = { type: 'boolean' };
38
+
39
+ if (Object.keys(validationSchema).length > 0) {
40
+ this.sdk.validateParams(arguments[0], validationSchema);
41
+ }
42
+
43
+ const params = {
44
+ query: {
45
+ type,
46
+ country,
47
+ state,
48
+ city,
49
+ startsWith,
50
+ endsWith,
51
+ contains,
52
+ limit,
53
+ minimumBlockSize,
54
+ sms,
55
+ mms,
56
+ voice,
57
+ },
58
+ };
59
+
60
+ const result = await internalRequest(this.sdk, '/phoneNumbers/search', 'GET', params);
61
+ return result;
62
+ },
63
+
64
+ async format(number) {
65
+ this.sdk.validateParams(
66
+ { number },
67
+ {
68
+ number: { type: 'string', required: true },
69
+ },
70
+ );
71
+
72
+ const result = await internalRequest(this.sdk,
73
+ `/phoneNumbers/format/${number}`,
74
+ 'GET',
75
+ );
76
+ return result;
77
+ },
78
+
79
+ /**
80
+ * Get routing options for phone numbers or extensions
81
+ *
82
+ * Supports multiple query modes:
83
+ * 1. Get list of valid app types with metadata (appType: 'list')
84
+ * 2. Get all application types (default)
85
+ * 3. Get details for a specific application type
86
+ * 4. Get versions for a specific workflow
87
+ *
88
+ * @param {Object} [options] - Query options
89
+ * @param {string} [options.mode] - Context mode: 'phoneNumbers' (default) or 'extensions'
90
+ * @param {string} [options.type] - Filter by routing type: 'voice' or 'messaging'
91
+ * @param {string} [options.appType] - 'list' for metadata, or specific app type: 'workflows', 'extensions', 'voiceApps', 'users'
92
+ * @param {string} [options.workflowId] - Get versions for a specific workflow ID
93
+ * @param {string} [options.search] - Search/filter by name
94
+ * @returns {Promise<Object>} Routing options based on query parameters
95
+ * @example
96
+ * // Get metadata about available app types
97
+ * const metadata = await sdk.phoneNumbers.getRoutingOptions({ appType: 'list' });
98
+ * // Returns: { types: [{ key: 'voiceApps', label: 'Voice Applications', description: '...', ... }] }
99
+ *
100
+ * // Get all application types for phone numbers (default)
101
+ * const all = await sdk.phoneNumbers.getRoutingOptions();
102
+ * // Returns: { voiceApps: [...], workflows: [...], extensions: [...], webhooks: [...] }
103
+ *
104
+ * // Get routing options for extensions
105
+ * const extensionOptions = await sdk.phoneNumbers.getRoutingOptions({ mode: 'extensions' });
106
+ * // Returns: { voiceApps: [...], workflows: [...], users: [...] }
107
+ *
108
+ * // Get only voice routing options
109
+ * const voice = await sdk.phoneNumbers.getRoutingOptions({ type: 'voice' });
110
+ *
111
+ * // Get all workflows with their versions
112
+ * const workflows = await sdk.phoneNumbers.getRoutingOptions({ appType: 'workflows' });
113
+ *
114
+ * // Get all users (for extension routing)
115
+ * const users = await sdk.phoneNumbers.getRoutingOptions({ mode: 'extensions', appType: 'users' });
116
+ *
117
+ * // Get versions for a specific workflow
118
+ * const versions = await sdk.phoneNumbers.getRoutingOptions({ workflowId: 'wf_123' });
119
+ *
120
+ * // Search workflows by name
121
+ * const filtered = await sdk.phoneNumbers.getRoutingOptions({ appType: 'workflows', search: 'customer' });
122
+ *
123
+ * // Page through a large appType's destination list (default 50, max 200)
124
+ * const page = await sdk.phoneNumbers.getRoutingOptions({ appType: 'users', search: 'jo', limit: 50 });
125
+ * // Returns: { users: [...], hasMore: true }
126
+ */
127
+ async getRoutingOptions({
128
+ mode,
129
+ type,
130
+ appType,
131
+ workflowId,
132
+ search,
133
+ limit,
134
+ } = {}) {
135
+ const validationSchema = {};
136
+ const args = arguments[0] || {};
137
+
138
+ if ('mode' in args)
139
+ validationSchema.mode = { type: 'string', required: false };
140
+ if ('type' in args)
141
+ validationSchema.type = { type: 'string', required: false };
142
+ if ('appType' in args)
143
+ validationSchema.appType = { type: 'string', required: false };
144
+ if ('workflowId' in args)
145
+ validationSchema.workflowId = { type: 'string', required: false };
146
+ if ('search' in args)
147
+ validationSchema.search = { type: 'string', required: false };
148
+ if ('limit' in args)
149
+ validationSchema.limit = { type: 'number', required: false };
150
+
151
+ if (Object.keys(validationSchema).length > 0) {
152
+ this.sdk.validateParams(args, validationSchema);
153
+ }
154
+
155
+ const params = {
156
+ query: {
157
+ mode,
158
+ type,
159
+ appType,
160
+ workflowId,
161
+ search,
162
+ limit,
163
+ },
164
+ };
165
+
166
+ const result = await internalRequest(this.sdk,
167
+ '/phoneNumbers/routing-options',
168
+ 'GET',
169
+ params,
170
+ );
171
+ return result;
172
+ },
173
+
174
+ async getSupportedCountries() {
175
+ const result = await internalRequest(this.sdk,
176
+ '/phoneNumbers/supported-countries',
177
+ 'GET',
178
+ );
179
+ return result;
180
+ },
181
+ };
@@ -0,0 +1,94 @@
1
+ import { internalRequest } from '../../base.js';
2
+
3
+ // phoneNumbers/update.js :: update method :: webhook/app/record-type config for an owned number
4
+ export const updateMethods = {
5
+ async update(
6
+ id,
7
+ {
8
+ name,
9
+ messagingWebHookUrl,
10
+ voiceWebHookUrl,
11
+ voiceAppExternalUrl,
12
+ voiceAppExternalMethod,
13
+ voiceApp,
14
+ voiceAppMetaData,
15
+ voiceRecordTypeId,
16
+ messagingRecordTypeId,
17
+ recordCalls,
18
+ textApp,
19
+ textAppMetaData,
20
+ textChatVisibility,
21
+ shakenBlockUnsigned,
22
+ shakenMinAttestation,
23
+ },
24
+ ) {
25
+ this.sdk.validateParams(
26
+ {
27
+ id,
28
+ messagingWebHookUrl,
29
+ voiceWebHookUrl,
30
+ voiceAppExternalUrl,
31
+ voiceAppExternalMethod,
32
+ voiceApp,
33
+ voiceRecordTypeId,
34
+ messagingRecordTypeId,
35
+ recordCalls,
36
+ textApp,
37
+ textAppMetaData,
38
+ textChatVisibility,
39
+ shakenBlockUnsigned,
40
+ shakenMinAttestation,
41
+ },
42
+ {
43
+ id: { type: 'string', required: true },
44
+ name: { type: 'string', required: false },
45
+ messagingWebHookUrl: { type: 'string', required: false },
46
+ voiceWebHookUrl: { type: 'string', required: false },
47
+ voiceAppExternalUrl: { type: 'string', required: false },
48
+ voiceAppExternalMethod: { type: 'string', required: false },
49
+ voiceApp: { type: 'string', required: false },
50
+ voiceRecordTypeId: { type: 'string', required: false },
51
+ messagingRecordTypeId: { type: 'string', required: false },
52
+ recordCalls: { type: 'boolean', required: false },
53
+ textApp: { type: 'string', required: false },
54
+ textAppMetaData: { type: 'string', required: false },
55
+ textChatVisibility: { type: 'string', required: false },
56
+ shakenBlockUnsigned: { type: 'boolean', required: false },
57
+ shakenMinAttestation: { type: 'string', required: false },
58
+ },
59
+ );
60
+
61
+ const updateData = {};
62
+ if (name) updateData.name = name;
63
+ if (messagingWebHookUrl)
64
+ updateData.messagingWebHookUrl = messagingWebHookUrl;
65
+ if (voiceWebHookUrl) updateData.voiceWebHookUrl = voiceWebHookUrl;
66
+ if (voiceAppExternalUrl)
67
+ updateData.voiceAppExternalUrl = voiceAppExternalUrl;
68
+ if (voiceAppExternalMethod)
69
+ updateData.voiceAppExternalMethod = voiceAppExternalMethod;
70
+ if (voiceApp) updateData.voiceApp = voiceApp;
71
+ if (voiceAppMetaData) updateData.voiceAppMetaData = voiceAppMetaData;
72
+ if (voiceRecordTypeId) updateData.voiceRecordTypeId = voiceRecordTypeId;
73
+ if (messagingRecordTypeId)
74
+ updateData.messagingRecordTypeId = messagingRecordTypeId;
75
+ if (recordCalls !== undefined) updateData.recordCalls = recordCalls;
76
+ if (textApp !== undefined) updateData.textApp = textApp;
77
+ if (textAppMetaData !== undefined)
78
+ updateData.textAppMetaData = textAppMetaData;
79
+ if (textChatVisibility !== undefined)
80
+ updateData.textChatVisibility = textChatVisibility;
81
+ if (shakenBlockUnsigned !== undefined)
82
+ updateData.shakenBlockUnsigned = shakenBlockUnsigned;
83
+ // null clears the floor when the gate is turned off.
84
+ if (shakenMinAttestation !== undefined)
85
+ updateData.shakenMinAttestation = shakenMinAttestation;
86
+
87
+ const params = {
88
+ body: updateData,
89
+ };
90
+
91
+ const result = await internalRequest(this.sdk, `/phoneNumbers/${id}`, 'PUT', params);
92
+ return result;
93
+ },
94
+ };