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