@unboundcx/sdk 4.13.145 → 4.13.146-security.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.
Files changed (45) hide show
  1. package/README.md +7 -0
  2. package/base.js +74 -3
  3. package/index.js +7 -31
  4. package/lib/refreshInterceptor.js +127 -0
  5. package/package.json +2 -5
  6. package/services/layouts.js +4 -13
  7. package/services/licenses.js +330 -0
  8. package/services/login.js +21 -0
  9. package/services/messageTemplates.js +2 -109
  10. package/services/messaging/EmailTemplatesService.js +2 -10
  11. package/services/messaging/SmsService.js +3 -0
  12. package/services/messaging/SmsTemplatesService.js +125 -0
  13. package/services/messaging.js +2 -0
  14. package/services/oauth.js +159 -0
  15. package/services/objects.js +39 -12
  16. package/services/permissions.js +0 -21
  17. package/services/phoneNumbers.js +1037 -2
  18. package/services/recents.js +0 -16
  19. package/services/taskRouter/MetricsService.js +0 -3
  20. package/services/taskRouter/TaskRouterService.js +0 -2
  21. package/services/taskRouter/TaskService.js +10 -70
  22. package/services/voice.js +25 -47
  23. package/lib/journeyLayout.js +0 -132
  24. package/services/journeys/JourneyDraftService.js +0 -92
  25. package/services/journeys/JourneyGoalsService.js +0 -57
  26. package/services/journeys/JourneyMembersService.js +0 -246
  27. package/services/journeys/JourneyTypesService.js +0 -59
  28. package/services/journeys/JourneyWorklistService.js +0 -74
  29. package/services/journeys/JourneysService.js +0 -392
  30. package/services/operatorPanels.js +0 -226
  31. package/services/parking.js +0 -121
  32. package/services/phoneNumbers/carrier.js +0 -60
  33. package/services/phoneNumbers/cnam.js +0 -42
  34. package/services/phoneNumbers/index.js +0 -27
  35. package/services/phoneNumbers/order.js +0 -88
  36. package/services/phoneNumbers/porting-activity.js +0 -289
  37. package/services/phoneNumbers/porting-orders.js +0 -318
  38. package/services/phoneNumbers/search.js +0 -181
  39. package/services/phoneNumbers/update.js +0 -94
  40. package/services/schedules/SchedulesService.js +0 -232
  41. package/services/schedules/TimeOffService.js +0 -131
  42. package/services/skills.js +0 -207
  43. package/services/taskRouter/QueueService.js +0 -343
  44. package/services/voicemailDrops.js +0 -268
  45. package/services/workflowTemplates/WorkflowTemplatesService.js +0 -68
@@ -1,2 +1,1037 @@
1
- // services/phoneNumbers.js :: back-compat re-export :: split into services/phoneNumbers/{search,order,update,cnam,porting,carrier}.js
2
- export { PhoneNumbersService, PhoneNumberCarrierService } from './phoneNumbers/index.js';
1
+ import { internalRequest } from '../base.js';
2
+ export class PhoneNumbersService {
3
+ constructor(sdk) {
4
+ this.sdk = sdk;
5
+ this.carrier = new PhoneNumberCarrierService(sdk);
6
+ }
7
+
8
+ async search({
9
+ type,
10
+ country,
11
+ state,
12
+ city,
13
+ startsWith,
14
+ endsWith,
15
+ contains,
16
+ limit,
17
+ minimumBlockSize,
18
+ sms,
19
+ mms,
20
+ voice,
21
+ }) {
22
+ // Validate optional parameters
23
+ const validationSchema = {};
24
+ if ('type' in arguments[0]) validationSchema.type = { type: 'string' };
25
+ if ('country' in arguments[0])
26
+ validationSchema.country = { type: 'string' };
27
+ if ('state' in arguments[0]) validationSchema.state = { type: 'string' };
28
+ if ('city' in arguments[0]) validationSchema.city = { type: 'string' };
29
+ if ('startsWith' in arguments[0])
30
+ validationSchema.startsWith = { type: 'string' };
31
+ if ('endsWith' in arguments[0])
32
+ validationSchema.endsWith = { type: 'string' };
33
+ if ('contains' in arguments[0])
34
+ validationSchema.contains = { type: 'string' };
35
+ if ('limit' in arguments[0]) validationSchema.limit = { type: 'number' };
36
+ if ('minimumBlockSize' in arguments[0])
37
+ validationSchema.minimumBlockSize = { type: 'number' };
38
+ if ('sms' in arguments[0]) validationSchema.sms = { type: 'boolean' };
39
+ if ('mms' in arguments[0]) validationSchema.mms = { type: 'boolean' };
40
+ if ('voice' in arguments[0]) validationSchema.voice = { type: 'boolean' };
41
+
42
+ if (Object.keys(validationSchema).length > 0) {
43
+ this.sdk.validateParams(arguments[0], validationSchema);
44
+ }
45
+
46
+ const params = {
47
+ query: {
48
+ type,
49
+ country,
50
+ state,
51
+ city,
52
+ startsWith,
53
+ endsWith,
54
+ contains,
55
+ limit,
56
+ minimumBlockSize,
57
+ sms,
58
+ mms,
59
+ voice,
60
+ },
61
+ };
62
+
63
+ const result = await internalRequest(this.sdk, '/phoneNumbers/search', 'GET', params);
64
+ return result;
65
+ }
66
+
67
+ async order({ phoneNumbers, name }) {
68
+ this.sdk.validateParams(
69
+ { phoneNumbers },
70
+ {
71
+ phoneNumbers: { type: 'array', required: true },
72
+ name: { type: 'string', required: false },
73
+ },
74
+ );
75
+
76
+ const orderData = { phoneNumbers };
77
+ if (name) orderData.name = name;
78
+
79
+ const params = {
80
+ body: orderData,
81
+ };
82
+
83
+ const result = await internalRequest(this.sdk, '/phoneNumbers/order', 'POST', params);
84
+ return result;
85
+ }
86
+
87
+ async remove(phoneNumber) {
88
+ this.sdk.validateParams(
89
+ { phoneNumber },
90
+ {
91
+ phoneNumber: { type: 'string', required: true },
92
+ },
93
+ );
94
+
95
+ const result = await internalRequest(this.sdk,
96
+ `/phoneNumbers/${phoneNumber}`,
97
+ 'DELETE',
98
+ );
99
+ return result;
100
+ }
101
+
102
+ async update(
103
+ id,
104
+ {
105
+ name,
106
+ messagingWebHookUrl,
107
+ voiceWebHookUrl,
108
+ voiceAppExternalUrl,
109
+ voiceAppExternalMethod,
110
+ voiceApp,
111
+ voiceAppMetaData,
112
+ voiceRecordTypeId,
113
+ messagingRecordTypeId,
114
+ recordCalls,
115
+ textApp,
116
+ textAppMetaData,
117
+ textChatVisibility,
118
+ shakenBlockUnsigned,
119
+ shakenMinAttestation,
120
+ },
121
+ ) {
122
+ this.sdk.validateParams(
123
+ {
124
+ id,
125
+ messagingWebHookUrl,
126
+ voiceWebHookUrl,
127
+ voiceAppExternalUrl,
128
+ voiceAppExternalMethod,
129
+ voiceApp,
130
+ voiceRecordTypeId,
131
+ messagingRecordTypeId,
132
+ recordCalls,
133
+ textApp,
134
+ textAppMetaData,
135
+ textChatVisibility,
136
+ shakenBlockUnsigned,
137
+ shakenMinAttestation,
138
+ },
139
+ {
140
+ id: { type: 'string', required: true },
141
+ name: { type: 'string', required: false },
142
+ messagingWebHookUrl: { type: 'string', required: false },
143
+ voiceWebHookUrl: { type: 'string', required: false },
144
+ voiceAppExternalUrl: { type: 'string', required: false },
145
+ voiceAppExternalMethod: { type: 'string', required: false },
146
+ voiceApp: { type: 'string', required: false },
147
+ voiceRecordTypeId: { type: 'string', required: false },
148
+ messagingRecordTypeId: { type: 'string', required: false },
149
+ recordCalls: { type: 'boolean', required: false },
150
+ textApp: { type: 'string', required: false },
151
+ textAppMetaData: { type: 'string', required: false },
152
+ textChatVisibility: { type: 'string', required: false },
153
+ shakenBlockUnsigned: { type: 'boolean', required: false },
154
+ shakenMinAttestation: { type: 'string', required: false },
155
+ },
156
+ );
157
+
158
+ const updateData = {};
159
+ if (name) updateData.name = name;
160
+ if (messagingWebHookUrl)
161
+ updateData.messagingWebHookUrl = messagingWebHookUrl;
162
+ if (voiceWebHookUrl) updateData.voiceWebHookUrl = voiceWebHookUrl;
163
+ if (voiceAppExternalUrl)
164
+ updateData.voiceAppExternalUrl = voiceAppExternalUrl;
165
+ if (voiceAppExternalMethod)
166
+ updateData.voiceAppExternalMethod = voiceAppExternalMethod;
167
+ if (voiceApp) updateData.voiceApp = voiceApp;
168
+ if (voiceAppMetaData) updateData.voiceAppMetaData = voiceAppMetaData;
169
+ if (voiceRecordTypeId) updateData.voiceRecordTypeId = voiceRecordTypeId;
170
+ if (messagingRecordTypeId)
171
+ updateData.messagingRecordTypeId = messagingRecordTypeId;
172
+ if (recordCalls !== undefined) updateData.recordCalls = recordCalls;
173
+ if (textApp !== undefined) updateData.textApp = textApp;
174
+ if (textAppMetaData !== undefined)
175
+ updateData.textAppMetaData = textAppMetaData;
176
+ if (textChatVisibility !== undefined)
177
+ updateData.textChatVisibility = textChatVisibility;
178
+ if (shakenBlockUnsigned !== undefined)
179
+ updateData.shakenBlockUnsigned = shakenBlockUnsigned;
180
+ // null clears the floor when the gate is turned off.
181
+ if (shakenMinAttestation !== undefined)
182
+ updateData.shakenMinAttestation = shakenMinAttestation;
183
+
184
+ const params = {
185
+ body: updateData,
186
+ };
187
+
188
+ const result = await internalRequest(this.sdk, `/phoneNumbers/${id}`, 'PUT', params);
189
+ return result;
190
+ }
191
+
192
+ async updateCnam(phoneNumber, { cnam }) {
193
+ this.sdk.validateParams(
194
+ { phoneNumber, cnam },
195
+ {
196
+ phoneNumber: { type: 'string', required: true },
197
+ cnam: { type: 'string', required: true },
198
+ },
199
+ );
200
+
201
+ const params = {
202
+ body: { cnam },
203
+ };
204
+
205
+ const result = await internalRequest(this.sdk,
206
+ `/phoneNumbers/cnam/${phoneNumber}`,
207
+ 'PUT',
208
+ params,
209
+ );
210
+ return result;
211
+ }
212
+
213
+ async format(number) {
214
+ this.sdk.validateParams(
215
+ { number },
216
+ {
217
+ number: { type: 'string', required: true },
218
+ },
219
+ );
220
+
221
+ const result = await internalRequest(this.sdk,
222
+ `/phoneNumbers/format/${number}`,
223
+ 'GET',
224
+ );
225
+ return result;
226
+ }
227
+
228
+ /**
229
+ * Get routing options for phone numbers or extensions
230
+ *
231
+ * Supports multiple query modes:
232
+ * 1. Get list of valid app types with metadata (appType: 'list')
233
+ * 2. Get all application types (default)
234
+ * 3. Get details for a specific application type
235
+ * 4. Get versions for a specific workflow
236
+ *
237
+ * @param {Object} [options] - Query options
238
+ * @param {string} [options.mode] - Context mode: 'phoneNumbers' (default) or 'extensions'
239
+ * @param {string} [options.type] - Filter by routing type: 'voice' or 'messaging'
240
+ * @param {string} [options.appType] - 'list' for metadata, or specific app type: 'workflows', 'extensions', 'voiceApps', 'users'
241
+ * @param {string} [options.workflowId] - Get versions for a specific workflow ID
242
+ * @param {string} [options.search] - Search/filter by name
243
+ * @returns {Promise<Object>} Routing options based on query parameters
244
+ * @example
245
+ * // Get metadata about available app types
246
+ * const metadata = await sdk.phoneNumbers.getRoutingOptions({ appType: 'list' });
247
+ * // Returns: { types: [{ key: 'voiceApps', label: 'Voice Applications', description: '...', ... }] }
248
+ *
249
+ * // Get all application types for phone numbers (default)
250
+ * const all = await sdk.phoneNumbers.getRoutingOptions();
251
+ * // Returns: { voiceApps: [...], workflows: [...], extensions: [...], webhooks: [...] }
252
+ *
253
+ * // Get routing options for extensions
254
+ * const extensionOptions = await sdk.phoneNumbers.getRoutingOptions({ mode: 'extensions' });
255
+ * // Returns: { voiceApps: [...], workflows: [...], users: [...] }
256
+ *
257
+ * // Get only voice routing options
258
+ * const voice = await sdk.phoneNumbers.getRoutingOptions({ type: 'voice' });
259
+ *
260
+ * // Get all workflows with their versions
261
+ * const workflows = await sdk.phoneNumbers.getRoutingOptions({ appType: 'workflows' });
262
+ *
263
+ * // Get all users (for extension routing)
264
+ * const users = await sdk.phoneNumbers.getRoutingOptions({ mode: 'extensions', appType: 'users' });
265
+ *
266
+ * // Get versions for a specific workflow
267
+ * const versions = await sdk.phoneNumbers.getRoutingOptions({ workflowId: 'wf_123' });
268
+ *
269
+ * // Search workflows by name
270
+ * const filtered = await sdk.phoneNumbers.getRoutingOptions({ appType: 'workflows', search: 'customer' });
271
+ *
272
+ * // Page through a large appType's destination list (default 50, max 200)
273
+ * const page = await sdk.phoneNumbers.getRoutingOptions({ appType: 'users', search: 'jo', limit: 50 });
274
+ * // Returns: { users: [...], hasMore: true }
275
+ */
276
+ async getRoutingOptions({
277
+ mode,
278
+ type,
279
+ appType,
280
+ workflowId,
281
+ search,
282
+ limit,
283
+ } = {}) {
284
+ const validationSchema = {};
285
+ const args = arguments[0] || {};
286
+
287
+ if ('mode' in args)
288
+ validationSchema.mode = { type: 'string', required: false };
289
+ if ('type' in args)
290
+ validationSchema.type = { type: 'string', required: false };
291
+ if ('appType' in args)
292
+ validationSchema.appType = { type: 'string', required: false };
293
+ if ('workflowId' in args)
294
+ validationSchema.workflowId = { type: 'string', required: false };
295
+ if ('search' in args)
296
+ validationSchema.search = { type: 'string', required: false };
297
+ if ('limit' in args)
298
+ validationSchema.limit = { type: 'number', required: false };
299
+
300
+ if (Object.keys(validationSchema).length > 0) {
301
+ this.sdk.validateParams(args, validationSchema);
302
+ }
303
+
304
+ const params = {
305
+ query: {
306
+ mode,
307
+ type,
308
+ appType,
309
+ workflowId,
310
+ search,
311
+ limit,
312
+ },
313
+ };
314
+
315
+ const result = await internalRequest(this.sdk,
316
+ '/phoneNumbers/routing-options',
317
+ 'GET',
318
+ params,
319
+ );
320
+ return result;
321
+ }
322
+
323
+ async getSupportedCountries() {
324
+ const result = await internalRequest(this.sdk,
325
+ '/phoneNumbers/supported-countries',
326
+ 'GET',
327
+ );
328
+ return result;
329
+ }
330
+
331
+ // Porting Methods
332
+
333
+ /**
334
+ * Check portability of phone numbers using two-phase validation
335
+ *
336
+ * Phase 1 (Default): Internal validation using LRN lookup
337
+ * - Validates ownership, duplicates, and carrier compatibility
338
+ * - Sets portabilityStatus to 'pending'
339
+ *
340
+ * Phase 2 (runPortabilityCheck: true): External validation
341
+ * - Runs full portability check with carrier
342
+ * - Updates portabilityStatus to 'portable', 'not-portable', or 'error'
343
+ *
344
+ * @param {Object} params
345
+ * @param {string[]} params.phoneNumbers - Array of +E.164 formatted phone numbers
346
+ * @param {string} [params.portingOrderId] - Optional porting order ID to save results to
347
+ * @param {boolean} [params.runPortabilityCheck=false] - Run external portability validation
348
+ * @returns {Promise<Object>} Portability check results
349
+ */
350
+ async checkPortability({
351
+ phoneNumbers,
352
+ portingOrderId,
353
+ runPortabilityCheck = false,
354
+ }) {
355
+ this.sdk.validateParams(
356
+ { phoneNumbers, runPortabilityCheck },
357
+ {
358
+ phoneNumbers: { type: 'array', required: true },
359
+ runPortabilityCheck: { type: 'boolean', required: false },
360
+ },
361
+ );
362
+
363
+ const body = { phoneNumbers, runPortabilityCheck };
364
+ if (portingOrderId) body.portingOrderId = portingOrderId;
365
+
366
+ const result = await internalRequest(this.sdk,
367
+ '/phoneNumbers/porting/portability-check',
368
+ 'POST',
369
+ {
370
+ body: body,
371
+ },
372
+ );
373
+ return result;
374
+ }
375
+
376
+ /**
377
+ * Create a draft porting order (no phone numbers - add them via checkPortability)
378
+ * @param {Object} params
379
+ * @param {string} [params.customerReference] - Customer-specified reference number
380
+ * @param {Object} [params.endUser] - End user information
381
+ * @param {Object} [params.endUser.admin] - Admin contact info
382
+ * @param {string} [params.endUser.admin.entityName] - Business/entity name
383
+ * @param {string} [params.endUser.admin.authPersonName] - Authorized person name
384
+ * @param {string} [params.endUser.admin.billingPhoneNumber] - Billing phone number
385
+ * @param {string} [params.endUser.admin.accountNumber] - Account number with current provider
386
+ * @param {string} [params.endUser.admin.taxIdentifier] - Tax identification number (EU)
387
+ * @param {string} [params.endUser.admin.pinPasscode] - PIN/passcode for account access
388
+ * @param {string} [params.endUser.admin.businessIdentifier] - Business identifier (EU)
389
+ * @param {Object} [params.endUser.location] - Location information
390
+ * @param {string} [params.endUser.location.streetAddress] - Street address
391
+ * @param {string} [params.endUser.location.extendedAddress] - Apt/suite/etc
392
+ * @param {string} [params.endUser.location.locality] - City
393
+ * @param {string} [params.endUser.location.administrativeArea] - State/province
394
+ * @param {string} [params.endUser.location.postalCode] - ZIP/postal code
395
+ * @param {string} [params.endUser.location.countryCode] - 2-letter country code
396
+ * @param {Object} [params.activationSettings] - Activation preferences
397
+ * @param {string} [params.activationSettings.focDatetimeRequested] - Requested FOC date/time (ISO 8601 UTC)
398
+ * @param {boolean} [params.activationSettings.fastPortEligible] - Request fast port if available
399
+ * @param {string} [params.portOrderType] - Port type: 'full' or 'partial' (defaults to 'full')
400
+ * @param {string[]} [params.tags] - Array of tags for organization
401
+ * @returns {Promise<Object>} Created draft porting order with ID and status 'draft'
402
+ * @example
403
+ * // Create empty draft order, then add numbers via checkPortability
404
+ * const order = await sdk.phoneNumbers.createPortingOrder({
405
+ * customerReference: "CUST-123",
406
+ * endUser: { admin: { entityName: "My Company" } }
407
+ * });
408
+ *
409
+ * // Phase 1: Add numbers with internal validation (pending status)
410
+ * await sdk.phoneNumbers.checkPortability({
411
+ * phoneNumbers: ["+15551234567"],
412
+ * portingOrderId: order.id
413
+ * });
414
+ *
415
+ * // Phase 2: Run external portability check when ready
416
+ * await sdk.phoneNumbers.checkPortability({
417
+ * phoneNumbers: ["+15551234567"],
418
+ * portingOrderId: order.id,
419
+ * runPortabilityCheck: true
420
+ * });
421
+ */
422
+ async createPortingOrder({
423
+ customerReference,
424
+ endUser,
425
+ activationSettings,
426
+ portOrderType,
427
+ tags,
428
+ } = {}) {
429
+ // Creates draft order without phone numbers - use checkPortability to add them
430
+ const body = {};
431
+ if (customerReference) body.customerReference = customerReference;
432
+ if (endUser) body.endUser = endUser;
433
+ if (activationSettings) body.activationSettings = activationSettings;
434
+ if (portOrderType) body.portOrderType = portOrderType;
435
+ if (tags) body.tags = tags;
436
+
437
+ const result = await internalRequest(this.sdk,
438
+ '/phoneNumbers/porting/orders',
439
+ 'POST',
440
+ {
441
+ body: body,
442
+ },
443
+ );
444
+ return result;
445
+ }
446
+
447
+ async getPortingOrders({
448
+ page,
449
+ status,
450
+ customerReference,
451
+ sort,
452
+ limit,
453
+ id,
454
+ operatorType = 'contains',
455
+ } = {}) {
456
+ const query = {
457
+ page,
458
+ status,
459
+ customerReference,
460
+ id,
461
+ operatorType,
462
+ sort,
463
+ limit,
464
+ };
465
+
466
+ const url = '/phoneNumbers/porting/orders';
467
+
468
+ const params = {
469
+ query,
470
+ };
471
+
472
+ const result = await internalRequest(this.sdk, url, 'GET', params);
473
+ return result;
474
+ }
475
+
476
+ /**
477
+ * Get a porting order with optional related data
478
+ * @param {string} id - Porting order ID
479
+ * @param {Object} [options]
480
+ * @param {boolean} [options.includePhoneNumbers=true] - Include phone numbers array
481
+ * @param {boolean} [options.includeExceptions=true] - Include exceptions array
482
+ * @param {boolean} [options.includeDocuments=true] - Include documents array with upload status
483
+ * @returns {Promise<Object>} Porting order with requested related data
484
+ */
485
+ async getPortingOrder(
486
+ id,
487
+ {
488
+ includePhoneNumbers = true,
489
+ includeExceptions = true,
490
+ includeDocuments = true,
491
+ } = {},
492
+ ) {
493
+ this.sdk.validateParams(
494
+ { id },
495
+ {
496
+ id: { type: 'string', required: true },
497
+ },
498
+ );
499
+
500
+ const params = new URLSearchParams();
501
+ if (includePhoneNumbers !== undefined)
502
+ params.append('includePhoneNumbers', includePhoneNumbers);
503
+ if (includeExceptions !== undefined)
504
+ params.append('includeExceptions', includeExceptions);
505
+ if (includeDocuments !== undefined)
506
+ params.append('includeDocuments', includeDocuments);
507
+
508
+ const queryString = params.toString();
509
+ const url = queryString
510
+ ? `/phoneNumbers/porting/orders/${id}?${queryString}`
511
+ : `/phoneNumbers/porting/orders/${id}`;
512
+
513
+ const result = await internalRequest(this.sdk, url, 'GET');
514
+ return result;
515
+ }
516
+
517
+ /**
518
+ * Update a draft porting order (order info only - manage numbers via checkPortability)
519
+ * @param {string} id - Porting order ID
520
+ * @param {Object} params - Order information to update
521
+ * @param {string} [params.customerReference] - Customer-specified reference number
522
+ * @param {Object} [params.endUser] - End user information
523
+ * @param {Object} [params.activationSettings] - Activation preferences
524
+ * @param {string} [params.portOrderType] - Port type: 'full' or 'partial'
525
+ * @param {string[]} [params.tags] - Array of tags for organization
526
+ * @returns {Promise<Object>} Updated porting order
527
+ */
528
+ async updatePortingOrder(
529
+ id,
530
+ {
531
+ customerReference,
532
+ endUser,
533
+ activationSettings,
534
+ portOrderType,
535
+ tags,
536
+ } = {},
537
+ ) {
538
+ this.sdk.validateParams(
539
+ { id },
540
+ {
541
+ id: { type: 'string', required: true },
542
+ },
543
+ );
544
+
545
+ const body = {};
546
+
547
+ if (customerReference) body.customerReference = customerReference;
548
+ if (endUser) body.endUser = endUser;
549
+ if (activationSettings) body.activationSettings = activationSettings;
550
+ if (portOrderType) body.portOrderType = portOrderType;
551
+ if (tags) body.tags = tags;
552
+
553
+ const result = await internalRequest(this.sdk,
554
+ `/phoneNumbers/porting/orders/${id}`,
555
+ 'PUT',
556
+ {
557
+ body: body,
558
+ },
559
+ );
560
+ return result;
561
+ }
562
+
563
+ /**
564
+ * Submit a draft porting order for processing (validates all required fields)
565
+ * @param {string} id - Porting order ID
566
+ * @returns {Promise<Object>} Submitted porting order with Telnyx status
567
+ */
568
+ async submitPortingOrder(id) {
569
+ this.sdk.validateParams(
570
+ { id },
571
+ {
572
+ id: { type: 'string', required: true },
573
+ },
574
+ );
575
+
576
+ // Submit the draft order (status is implied)
577
+ const body = {
578
+ status: 'submit',
579
+ };
580
+
581
+ const result = await internalRequest(this.sdk,
582
+ `/phoneNumbers/porting/orders/${id}`,
583
+ 'PUT',
584
+ {
585
+ body: body,
586
+ },
587
+ );
588
+ return result;
589
+ }
590
+
591
+ /**
592
+ * Delete/cancel a porting order (soft delete)
593
+ * - Draft orders: Immediately cancelled locally
594
+ * - Submitted orders: Cancelled via Telnyx, then status updated to cancel-pending
595
+ * - Cannot delete orders within 48 hours of FOC date
596
+ * - Cannot delete already completed or cancelled orders
597
+ * @param {string} id - Porting order ID
598
+ * @returns {Promise<Object>} Cancellation result with new status
599
+ */
600
+ async deletePortingOrder(id) {
601
+ this.sdk.validateParams(
602
+ { id },
603
+ {
604
+ id: { type: 'string', required: true },
605
+ },
606
+ );
607
+
608
+ const result = await internalRequest(this.sdk,
609
+ `/phoneNumbers/porting/orders/${id}`,
610
+ 'DELETE',
611
+ );
612
+ return result;
613
+ }
614
+
615
+ /**
616
+ * Remove a specific phone number from a porting order
617
+ * - Only works on draft orders (not submitted orders)
618
+ * - Cannot remove the last phone number (delete entire order instead)
619
+ * - Validates that phone number exists in the order
620
+ * @param {string} portingOrderId - Porting order ID
621
+ * @param {string} phoneNumber - Phone number to remove (+E.164 format)
622
+ * @returns {Promise<Object>} Removal confirmation with updated counts
623
+ * @example
624
+ * await sdk.phoneNumbers.removePhoneNumberFromOrder(
625
+ * "port_123...",
626
+ * "+15551234567"
627
+ * );
628
+ */
629
+ async removePhoneNumberFromOrder(portingOrderId, phoneNumber) {
630
+ this.sdk.validateParams(
631
+ { portingOrderId, phoneNumber },
632
+ {
633
+ portingOrderId: { type: 'string', required: true },
634
+ phoneNumber: { type: 'string', required: true },
635
+ },
636
+ );
637
+
638
+ const result = await internalRequest(this.sdk,
639
+ `/phoneNumbers/porting/orders/${encodeURIComponent(
640
+ portingOrderId,
641
+ )}/numbers/${encodeURIComponent(phoneNumber)}`,
642
+ 'DELETE',
643
+ );
644
+ return result;
645
+ }
646
+
647
+ /**
648
+ * Attach or update a document for a porting order
649
+ *
650
+ * @param {Object} params
651
+ * @param {string} params.portingOrderId - Porting order ID
652
+ * @param {string} [params.storageId] - Storage ID of uploaded file (null to clear)
653
+ * @param {string} [params.documentType='loa'] - Document type (loa, bill, csr, etc.)
654
+ * @param {boolean} [params.isRequired=false] - Whether document is required
655
+ * @param {string} [params.documentId] - Optional: Update existing document by ID
656
+ * @returns {Promise<Object>} Document attachment result with action (created/updated)
657
+ */
658
+ async attachPortingDocument({
659
+ portingOrderId,
660
+ storageId = null,
661
+ documentType = 'loa',
662
+ isRequired = false,
663
+ documentId = null,
664
+ }) {
665
+ this.sdk.validateParams(
666
+ { portingOrderId, documentType },
667
+ {
668
+ portingOrderId: { type: 'string', required: true },
669
+ documentType: { type: 'string', required: true },
670
+ },
671
+ );
672
+
673
+ const body = {
674
+ portingOrderId,
675
+ storageId,
676
+ documentType,
677
+ isRequired,
678
+ };
679
+
680
+ if (documentId) body.documentId = documentId;
681
+
682
+ const result = await internalRequest(this.sdk,
683
+ '/phoneNumbers/porting/documents',
684
+ 'POST',
685
+ {
686
+ body: body,
687
+ },
688
+ );
689
+ return result;
690
+ }
691
+
692
+ /**
693
+ * Start e-sign for a porting LOA (`send` emails the signer, `present` returns a URL).
694
+ *
695
+ * @param {Object} params
696
+ * @param {string} params.portingOrderId
697
+ * @param {string} params.signerName
698
+ * @param {string} params.mode - `send` or `present`
699
+ * @param {string} [params.signerTitle]
700
+ * @param {string} [params.signerEmail] - required when mode is send
701
+ * @returns {Promise<Object>} `{ packageId, status, signers, presentUrl?, presentExpiresAt? }`
702
+ */
703
+ async generateLoa({
704
+ portingOrderId,
705
+ signerName,
706
+ signerTitle,
707
+ signerEmail,
708
+ mode,
709
+ }) {
710
+ this.sdk.validateParams(
711
+ { portingOrderId, signerName, mode },
712
+ {
713
+ portingOrderId: { type: 'string', required: true },
714
+ signerName: { type: 'string', required: true },
715
+ mode: { type: 'string', required: true },
716
+ signerTitle: { type: 'string', required: false },
717
+ signerEmail: { type: 'string', required: false },
718
+ },
719
+ );
720
+
721
+ const body = { signerName, mode };
722
+ if (signerTitle !== undefined) body.signerTitle = signerTitle;
723
+ if (signerEmail !== undefined) body.signerEmail = signerEmail;
724
+
725
+ const result = await internalRequest(
726
+ this.sdk,
727
+ `/phoneNumbers/porting/orders/${encodeURIComponent(
728
+ portingOrderId,
729
+ )}/generate-loa`,
730
+ 'POST',
731
+ { body },
732
+ );
733
+ return result;
734
+ }
735
+
736
+ async getPortingEvents(id, { page, limit } = {}) {
737
+ this.sdk.validateParams(
738
+ { id },
739
+ {
740
+ id: { type: 'string', required: true },
741
+ },
742
+ );
743
+
744
+ const params = new URLSearchParams();
745
+ if (page) params.append('page', page);
746
+ if (limit) params.append('limit', limit);
747
+
748
+ const queryString = params.toString();
749
+ const url = queryString
750
+ ? `/phoneNumbers/porting/orders/${id}/events?${queryString}`
751
+ : `/phoneNumbers/porting/orders/${id}/events`;
752
+
753
+ const result = await internalRequest(this.sdk, url, 'GET');
754
+ return result;
755
+ }
756
+
757
+ /**
758
+ * Get available activation dates for a porting order
759
+ * - Creates the porting order in external system if not already created
760
+ * - Updates the order data to ensure it's current before fetching dates
761
+ * - Returns list of available activation dates for user selection
762
+ * - Validates that phone numbers and required order details are complete
763
+ * @param {string} id - Porting order ID
764
+ * @returns {Promise<Object>} Available activation dates and order status
765
+ * @example
766
+ * const dates = await sdk.phoneNumbers.getFocWindows("port_123...");
767
+ * // Returns:
768
+ * // {
769
+ * // id: "port_123...",
770
+ * // status: "draft",
771
+ * // availableDates: [
772
+ * // { date: "2025-08-30T00:00:00.000Z", type: "Standard", available: true },
773
+ * // { date: "2025-09-02T00:00:00.000Z", type: "Express", available: true }
774
+ * // ],
775
+ * // phoneNumbersCount: 1,
776
+ * // orderReady: true
777
+ * // }
778
+ */
779
+ async getFocWindows(id) {
780
+ this.sdk.validateParams(
781
+ { id },
782
+ {
783
+ id: { type: 'string', required: true },
784
+ },
785
+ );
786
+
787
+ const result = await internalRequest(this.sdk,
788
+ `/phoneNumbers/porting/orders/${id}/foc-windows`,
789
+ 'GET',
790
+ );
791
+ return result;
792
+ }
793
+
794
+ /**
795
+ * Sync a porting order with the carrier
796
+ * Fetches the latest order details and comments from the carrier and updates the local database
797
+ * @param {string} id - Porting order ID
798
+ * @returns {Promise<Object>} Sync results including updates made and comments added
799
+ * @example
800
+ * const syncResult = await sdk.phoneNumbers.syncPortingOrder("port_123...");
801
+ * // Returns:
802
+ * // {
803
+ * // id: "port_123...",
804
+ * // carrierOrderId: "carrier_abc123",
805
+ * // orderUpdated: true,
806
+ * // commentsAdded: 2,
807
+ * // errors: []
808
+ * // }
809
+ */
810
+ async syncPortingOrder(id) {
811
+ this.sdk.validateParams(
812
+ { id },
813
+ {
814
+ id: { type: 'string', required: true },
815
+ },
816
+ );
817
+
818
+ const result = await internalRequest(this.sdk,
819
+ `/phoneNumbers/porting/orders/${id}/sync`,
820
+ 'POST',
821
+ );
822
+ return result;
823
+ }
824
+
825
+ /**
826
+ * Mark a porting-order exception as resolved after the user has updated
827
+ * the order (documents, account number, etc.). Syncs with the carrier
828
+ * so local status picks up the next Telnyx state.
829
+ * @param {string} id - Porting order ID
830
+ * @param {string} exceptionId - Exception ID
831
+ * @param {Object} [options]
832
+ * @param {string} [options.resolution]
833
+ * @returns {Promise<Object>} Updated exception
834
+ */
835
+ async resolvePortingException(id, exceptionId, { resolution } = {}) {
836
+ this.sdk.validateParams(
837
+ { id, exceptionId },
838
+ {
839
+ id: { type: 'string', required: true },
840
+ exceptionId: { type: 'string', required: true },
841
+ },
842
+ );
843
+ const body = {};
844
+ if (resolution) body.resolution = resolution;
845
+ return internalRequest(
846
+ this.sdk,
847
+ `/phoneNumbers/porting/orders/${id}/exceptions/${exceptionId}/resolve`,
848
+ 'POST',
849
+ { body },
850
+ );
851
+ }
852
+
853
+ /**
854
+ * Get comments for a porting order
855
+ * @param {string} id - Porting order ID
856
+ * @param {Object} [options] - Query options
857
+ * @param {string} [options.includeInternal='true'] - Include internal comments ('true', 'false', 'only')
858
+ * @returns {Promise<Object>} Comments list with metadata
859
+ * @example
860
+ * // Get all comments
861
+ * const allComments = await sdk.phoneNumbers.getPortingComments("port_123...");
862
+ *
863
+ * // Get only public comments
864
+ * const publicComments = await sdk.phoneNumbers.getPortingComments("port_123...", { includeInternal: 'false' });
865
+ *
866
+ * // Get only internal comments
867
+ * const internalComments = await sdk.phoneNumbers.getPortingComments("port_123...", { includeInternal: 'only' });
868
+ */
869
+ async getPortingComments(id, { includeInternal = 'true' } = {}) {
870
+ this.sdk.validateParams(
871
+ { id },
872
+ {
873
+ id: { type: 'string', required: true },
874
+ },
875
+ );
876
+
877
+ const params = new URLSearchParams();
878
+ if (includeInternal !== 'true') {
879
+ params.append('includeInternal', includeInternal);
880
+ }
881
+
882
+ const queryString = params.toString();
883
+ const url = `/phoneNumbers/porting/orders/${id}/comments${
884
+ queryString ? '?' + queryString : ''
885
+ }`;
886
+
887
+ const result = await internalRequest(this.sdk, url, 'GET');
888
+ return result;
889
+ }
890
+
891
+ /**
892
+ * Post a comment on a porting order
893
+ * @param {string} id - Porting order ID
894
+ * @param {Object} params - Comment parameters
895
+ * @param {string} params.comment - Comment body text
896
+ * @param {boolean} [params.isInternal=false] - Whether this is an internal comment (not shared with carrier)
897
+ * @returns {Promise<Object>} Created comment details
898
+ * @example
899
+ * // Post a public comment (shared with carrier)
900
+ * const publicComment = await sdk.phoneNumbers.postPortingComment("port_123...", {
901
+ * comment: "Please expedite this port request",
902
+ * isInternal: false
903
+ * });
904
+ *
905
+ * // Post an internal comment (team use only)
906
+ * const internalComment = await sdk.phoneNumbers.postPortingComment("port_123...", {
907
+ * comment: "Customer called - they need this ASAP",
908
+ * isInternal: true
909
+ * });
910
+ */
911
+ async postPortingComment(id, { comment, isInternal = false }) {
912
+ this.sdk.validateParams(
913
+ { id, comment },
914
+ {
915
+ id: { type: 'string', required: true },
916
+ comment: { type: 'string', required: true },
917
+ isInternal: { type: 'boolean', required: false },
918
+ },
919
+ );
920
+
921
+ const result = await internalRequest(this.sdk,
922
+ `/phoneNumbers/porting/orders/${id}/comments`,
923
+ 'POST',
924
+ {
925
+ body: { comment, isInternal },
926
+ },
927
+ );
928
+ return result;
929
+ }
930
+
931
+ /**
932
+ * Auto-create porting orders by grouping phone numbers by carrier
933
+ *
934
+ * Analyzes phone numbers using internal LRN lookup, groups them by carrier,
935
+ * and either previews the groupings (dry run) or creates separate porting
936
+ * orders for each carrier group.
937
+ *
938
+ * @param {Object} params
939
+ * @param {string[]} params.phoneNumbers - Array of +E.164 formatted phone numbers (max 100)
940
+ * @param {string} params.name - Base name for orders (will be appended with carrier names)
941
+ * @param {boolean} [params.dryRun=false] - If true, returns preview without creating orders
942
+ * @returns {Promise<Object>} Carrier groups and creation results
943
+ * @example
944
+ * // Preview carrier groupings
945
+ * const preview = await sdk.phoneNumbers.autoCreateOrders({
946
+ * phoneNumbers: ['+15551234567', '+15551234568', '+15551234569'],
947
+ * name: 'Q1 2025 Port',
948
+ * dryRun: true
949
+ * });
950
+ * // Returns carrier groups with proposed order names
951
+ *
952
+ * // Create orders for each carrier
953
+ * const result = await sdk.phoneNumbers.autoCreateOrders({
954
+ * phoneNumbers: ['+15551234567', '+15551234568', '+15551234569'],
955
+ * name: 'Q1 2025 Port',
956
+ * dryRun: false
957
+ * });
958
+ * // Returns created orders and any errors
959
+ */
960
+ async autoCreateOrders({ phoneNumbers, name, dryRun = false }) {
961
+ this.sdk.validateParams(
962
+ { phoneNumbers, name },
963
+ {
964
+ phoneNumbers: { type: 'array', required: true },
965
+ name: { type: 'string', required: true },
966
+ dryRun: { type: 'boolean', required: false },
967
+ },
968
+ );
969
+
970
+ const result = await internalRequest(this.sdk,
971
+ '/phoneNumbers/porting/auto-create-orders',
972
+ 'POST',
973
+ {
974
+ body: { phoneNumbers, name, dryRun },
975
+ },
976
+ );
977
+ return result;
978
+ }
979
+ }
980
+
981
+ export class PhoneNumberCarrierService {
982
+ constructor(sdk) {
983
+ this.sdk = sdk;
984
+ }
985
+
986
+ async sync(carrier, { updateVoiceConnection, updateMessagingConnection }) {
987
+ this.sdk.validateParams(
988
+ { carrier },
989
+ {
990
+ carrier: { type: 'string', required: true },
991
+ updateVoiceConnection: { type: 'boolean', required: false },
992
+ updateMessagingConnection: { type: 'boolean', required: false },
993
+ },
994
+ );
995
+
996
+ const params = {
997
+ query: { updateVoiceConnection, updateMessagingConnection },
998
+ };
999
+
1000
+ const result = await internalRequest(this.sdk,
1001
+ `/phoneNumbers/carrier/syncPhoneNumbers/${carrier}`,
1002
+ 'POST',
1003
+ params,
1004
+ );
1005
+ return result;
1006
+ }
1007
+
1008
+ async getDetails(phoneNumber) {
1009
+ this.sdk.validateParams(
1010
+ { phoneNumber },
1011
+ {
1012
+ phoneNumber: { type: 'string', required: true },
1013
+ },
1014
+ );
1015
+
1016
+ const result = await internalRequest(this.sdk,
1017
+ `/phoneNumbers/carrier/${phoneNumber}`,
1018
+ 'GET',
1019
+ );
1020
+ return result;
1021
+ }
1022
+
1023
+ async delete(phoneNumber) {
1024
+ this.sdk.validateParams(
1025
+ { phoneNumber },
1026
+ {
1027
+ phoneNumber: { type: 'string', required: true },
1028
+ },
1029
+ );
1030
+
1031
+ const result = await internalRequest(this.sdk,
1032
+ `/phoneNumbers/carrier/${phoneNumber}`,
1033
+ 'DELETE',
1034
+ );
1035
+ return result;
1036
+ }
1037
+ }