telnyx 6.83.0 → 7.1.0

package/src/resources/dir/index.ts

@@ -0,0 +1,46 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Comments,
+  type CommentType,
+  type DirComment,
+  type CommentCreateResponse,
+  type CommentCreateParams,
+  type CommentListParams,
+  type DirCommentsDefaultFlatPagination,
+} from './comments';
+export {
+  DirResource,
+  type Dir,
+  type DirList,
+  type DirStatus,
+  type DirWrapped,
+  type Document,
+  type DirListDocumentTypesResponse,
+  type DirUpdateParams,
+  type DirListParams,
+  type DirListInfringementClaimsParams,
+  type DirNewLoaParams,
+  type DirUpdateInfringementParams,
+  type DirsDefaultFlatPagination,
+} from './dir';
+export {
+  PhoneNumberBatches,
+  type DirPhoneNumberStatus,
+  type PhoneNumberBatch,
+  type PhoneNumberBatchRetrieveResponse,
+  type PhoneNumberBatchRetrieveParams,
+  type PhoneNumberBatchListParams,
+  type PhoneNumberBatchesDefaultFlatPagination,
+} from './phone-number-batches';
+export {
+  PhoneNumbers,
+  type DirPhoneNumber,
+  type RejectionReason,
+  type PhoneNumberAddResponse,
+  type PhoneNumberRemoveResponse,
+  type PhoneNumberListParams,
+  type PhoneNumberAddParams,
+  type PhoneNumberRemoveParams,
+  type DirPhoneNumbersDefaultFlatPagination,
+} from './phone-numbers';

package/src/resources/dir/phone-number-batches.ts

@@ -0,0 +1,170 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as DirAPI from './dir';
+import * as PhoneNumbersAPI from './phone-numbers';
+import { APIPromise } from '../../core/api-promise';
+import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Phone numbers are submitted to Telnyx for vetting in batches. Batches group all numbers added in a single request under the same Letter of Authorization.
+ */
+export class PhoneNumberBatches extends APIResource {
+  /**
+   * Get a single phone-number batch by id. The enterprise is resolved server-side
+   * from the DIR id.
+   *
+   * @example
+   * ```ts
+   * const phoneNumberBatch =
+   *   await client.dir.phoneNumberBatches.retrieve(
+   *     '0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62',
+   *     { dir_id: '16635d38-75a6-4481-82e8-69af60e05011' },
+   *   );
+   * ```
+   */
+  retrieve(
+    batchID: string,
+    params: PhoneNumberBatchRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<PhoneNumberBatchRetrieveResponse> {
+    const { dir_id } = params;
+    return this._client.get(path`/dir/${dir_id}/phone_number_batches/${batchID}`, options);
+  }
+
+  /**
+   * List the phone-number batches submitted under a DIR. The enterprise is resolved
+   * server-side from the DIR id.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const phoneNumberBatch of client.dir.phoneNumberBatches.list(
+   *   '16635d38-75a6-4481-82e8-69af60e05011',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    dirID: string,
+    query: PhoneNumberBatchListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PhoneNumberBatchesDefaultFlatPagination, PhoneNumberBatch> {
+    return this._client.getAPIList(
+      path`/dir/${dirID}/phone_number_batches`,
+      DefaultFlatPagination<PhoneNumberBatch>,
+      { query, ...options },
+    );
+  }
+}
+
+export type PhoneNumberBatchesDefaultFlatPagination = DefaultFlatPagination<PhoneNumberBatch>;
+
+/**
+ * Phone-number lifecycle status.
+ *
+ * - `submitted` / `in_review` - Telnyx is reviewing the batch this number belongs
+ *   to.
+ * - `verified` - approved; the DIR's display identity will be shown on outbound
+ *   calls from this number.
+ * - `unsuccessful` - Telnyx rejected this submission; the customer may re-add to
+ *   retry.
+ * - `suspended` - temporarily disabled (e.g. by an active infringement claim on
+ *   the DIR).
+ * - `expired` - verification expired; re-add to renew.
+ * - `permanently_rejected` - terminal; cannot be re-added on this or any other DIR
+ *   you own.
+ */
+export type DirPhoneNumberStatus =
+  | 'submitted'
+  | 'in_review'
+  | 'verified'
+  | 'unsuccessful'
+  | 'suspended'
+  | 'expired'
+  | 'permanently_rejected';
+
+/**
+ * A phone-number batch groups all numbers added in a single bulk-add request.
+ * Telnyx vets the batch as a unit. The response embeds the full `phone_numbers`
+ * array so you can read per-number status without a separate call, plus a
+ * batch-level `status` summarising the unit's progress.
+ */
+export interface PhoneNumberBatch {
+  batch_id?: string;
+
+  /**
+   * The DIR's display name at the time the batch was read.
+   */
+  dir_display_name?: string;
+
+  dir_id?: string;
+
+  /**
+   * Documents attached to this batch (e.g. a Letter of Authorization). Empty when
+   * none were supplied at add time.
+   */
+  documents?: Array<DirAPI.Document>;
+
+  enterprise_id?: string;
+
+  /**
+   * All phone numbers in this batch, with per-number status.
+   */
+  phone_numbers?: Array<PhoneNumbersAPI.DirPhoneNumber>;
+
+  /**
+   * Aggregate batch status. Mirrors the values used on individual phone numbers
+   * (`submitted`, `in_review`, `verified`, `unsuccessful`, `permanently_rejected`,
+   * etc.).
+   */
+  status?: DirPhoneNumberStatus;
+
+  /**
+   * When the batch was created (and implicitly submitted for vetting).
+   */
+  submitted_at?: string;
+
+  /**
+   * Number of phone numbers in this batch (length of `phone_numbers`).
+   */
+  total_count?: number;
+}
+
+export interface PhoneNumberBatchRetrieveResponse {
+  /**
+   * A phone-number batch groups all numbers added in a single bulk-add request.
+   * Telnyx vets the batch as a unit. The response embeds the full `phone_numbers`
+   * array so you can read per-number status without a separate call, plus a
+   * batch-level `status` summarising the unit's progress.
+   */
+  data: PhoneNumberBatch;
+}
+
+export interface PhoneNumberBatchRetrieveParams {
+  /**
+   * The DIR id. Lowercase UUID.
+   */
+  dir_id: string;
+}
+
+export interface PhoneNumberBatchListParams extends DefaultFlatPaginationParams {
+  /**
+   * Restrict to batches whose aggregate status equals this value.
+   */
+  'filter[status]'?: DirPhoneNumberStatus;
+}
+
+export declare namespace PhoneNumberBatches {
+  export {
+    type DirPhoneNumberStatus as DirPhoneNumberStatus,
+    type PhoneNumberBatch as PhoneNumberBatch,
+    type PhoneNumberBatchRetrieveResponse as PhoneNumberBatchRetrieveResponse,
+    type PhoneNumberBatchesDefaultFlatPagination as PhoneNumberBatchesDefaultFlatPagination,
+    type PhoneNumberBatchRetrieveParams as PhoneNumberBatchRetrieveParams,
+    type PhoneNumberBatchListParams as PhoneNumberBatchListParams,
+  };
+}

package/src/resources/dir/phone-numbers.ts

@@ -0,0 +1,266 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as DirAPI from './dir';
+import * as PhoneNumberBatchesAPI from './phone-number-batches';
+import { APIPromise } from '../../core/api-promise';
+import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Associate phone numbers with a verified DIR so calls from those numbers carry the DIR's display identity.
+ */
+export class PhoneNumbers extends APIResource {
+  /**
+   * List the phone numbers registered under a DIR. The enterprise is resolved
+   * server-side from the DIR id.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const dirPhoneNumber of client.dir.phoneNumbers.list(
+   *   '16635d38-75a6-4481-82e8-69af60e05011',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    dirID: string,
+    query: PhoneNumberListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<DirPhoneNumbersDefaultFlatPagination, DirPhoneNumber> {
+    return this._client.getAPIList(path`/dir/${dirID}/phone_numbers`, DefaultFlatPagination<DirPhoneNumber>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Register phone numbers under a DIR. The enterprise is resolved server-side from
+   * the DIR id. Same body, failure modes, and batch semantics whichever path form
+   * you use.
+   *
+   * **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
+   * for current pricing.
+   *
+   * @example
+   * ```ts
+   * const response = await client.dir.phoneNumbers.add(
+   *   '16635d38-75a6-4481-82e8-69af60e05011',
+   *   {
+   *     documents: [
+   *       {
+   *         document_id: '2a7e8337-e803-4057-a4ae-26c40eb0bc6c',
+   *         document_type: 'letter_of_authorization',
+   *         description:
+   *           'LOA authorising Telnyx to register these numbers under the DIR.',
+   *       },
+   *     ],
+   *     phone_numbers: ['+19493253498', '+12134445566'],
+   *   },
+   * );
+   * ```
+   */
+  add(
+    dirID: string,
+    body: PhoneNumberAddParams,
+    options?: RequestOptions,
+  ): APIPromise<PhoneNumberAddResponse> {
+    return this._client.post(path`/dir/${dirID}/phone_numbers`, { body, ...options });
+  }
+
+  /**
+   * Deregister phone numbers from a DIR. The enterprise is resolved server-side from
+   * the DIR id. Returns a partial-success envelope.
+   *
+   * @example
+   * ```ts
+   * const phoneNumber = await client.dir.phoneNumbers.remove(
+   *   '16635d38-75a6-4481-82e8-69af60e05011',
+   *   { phone_numbers: ['+19493253498'] },
+   * );
+   * ```
+   */
+  remove(
+    dirID: string,
+    body: PhoneNumberRemoveParams,
+    options?: RequestOptions,
+  ): APIPromise<PhoneNumberRemoveResponse> {
+    return this._client.delete(path`/dir/${dirID}/phone_numbers`, { body, ...options });
+  }
+}
+
+export type DirPhoneNumbersDefaultFlatPagination = DefaultFlatPagination<DirPhoneNumber>;
+
+export interface DirPhoneNumber {
+  id?: string;
+
+  /**
+   * Id of the batch this number was vetted as part of.
+   */
+  batch_id?: string | null;
+
+  created_at?: string;
+
+  dir_id?: string;
+
+  enterprise_id?: string;
+
+  /**
+   * Id of the Letter of Authorization document attached to this number's batch.
+   */
+  loa_document_id?: string | null;
+
+  /**
+   * E.164 with leading `+`.
+   */
+  phone_number?: string;
+
+  /**
+   * Populated when `status` is `unsuccessful` or `permanently_rejected`.
+   */
+  rejection_reason?: RejectionReason | null;
+
+  /**
+   * Phone-number lifecycle status.
+   *
+   * - `submitted` / `in_review` - Telnyx is reviewing the batch this number belongs
+   *   to.
+   * - `verified` - approved; the DIR's display identity will be shown on outbound
+   *   calls from this number.
+   * - `unsuccessful` - Telnyx rejected this submission; the customer may re-add to
+   *   retry.
+   * - `suspended` - temporarily disabled (e.g. by an active infringement claim on
+   *   the DIR).
+   * - `expired` - verification expired; re-add to renew.
+   * - `permanently_rejected` - terminal; cannot be re-added on this or any other DIR
+   *   you own.
+   */
+  status?: PhoneNumberBatchesAPI.DirPhoneNumberStatus;
+
+  updated_at?: string;
+
+  verified_at?: string | null;
+}
+
+export interface RejectionReason {
+  code?: string;
+
+  detail?: string;
+
+  /**
+   * Customer-visible free-text comment from the Telnyx vetting team. Only the first
+   * entry of `rejection_reasons` carries this; the rest are `null`.
+   */
+  message?: string | null;
+
+  title?: string;
+}
+
+/**
+ * Bulk-add success response (HTTP 201). All numbers in the request were accepted
+ * into a single new batch. Every entry in `data` shares the same `batch_id` - read
+ * it from any element to obtain the batch id for subsequent
+ * `GET .../phone_number_batches/{batch_id}` calls. If any number in the request
+ * fails (schema-invalid, not in inventory, already attached to another DIR, etc.)
+ * the entire request is rejected with HTTP 400 and the canonical Telnyx error
+ * envelope; the success body described here is therefore an all-or-nothing
+ * payload.
+ */
+export interface PhoneNumberAddResponse {
+  /**
+   * Phone numbers accepted into the new batch. List order mirrors the request order.
+   * Each element shares the same `batch_id`.
+   */
+  data: Array<DirPhoneNumber>;
+}
+
+/**
+ * Bulk-delete partial-success response. `data` is the list of phone numbers that
+ * were soft-deleted. `meta.errors` holds per-number failures (e.g. number not
+ * associated with this DIR). When EVERY number in the request fails, the endpoint
+ * instead returns 400 with the canonical Telnyx error envelope and `data`/`meta`
+ * are absent.
+ */
+export interface PhoneNumberRemoveResponse {
+  /**
+   * Phone numbers that were successfully soft-deleted. Bare E.164 strings.
+   */
+  data: Array<string>;
+
+  meta: PhoneNumberRemoveResponse.Meta;
+}
+
+export namespace PhoneNumberRemoveResponse {
+  export interface Meta {
+    /**
+     * Per-number failures that did not block the call. Each entry has `phone_number`,
+     * `code`, `title`, `detail`.
+     */
+    errors: Array<Meta.Error>;
+  }
+
+  export namespace Meta {
+    /**
+     * Per-number error returned by the bulk-delete endpoint. Bulk-add does not use
+     * this shape - it returns a 400 with the canonical envelope grouping numbers by
+     * failure category.
+     */
+    export interface Error {
+      /**
+       * Stable per-number error code. Currently only `not_associated` is emitted, when
+       * the number is not attached to this DIR.
+       */
+      code: 'not_associated';
+
+      detail: string;
+
+      phone_number: string;
+
+      title: string;
+    }
+  }
+}
+
+export interface PhoneNumberListParams extends DefaultFlatPaginationParams {
+  /**
+   * Filter by phone-number status.
+   */
+  status?: PhoneNumberBatchesAPI.DirPhoneNumberStatus;
+}
+
+export interface PhoneNumberAddParams {
+  /**
+   * Supporting documents covering this batch. At least one entry with
+   * `document_type: letter_of_authorization` is required - the LOA authorises Telnyx
+   * to register these numbers under the DIR. Each `document_id` must come from the
+   * Telnyx Documents API. Additional document types (e.g. business registration) may
+   * be included alongside the LOA.
+   */
+  documents: Array<DirAPI.Document>;
+
+  /**
+   * 1–15 phone numbers in E.164 format. 10-digit US numbers are auto-prefixed with
+   * `1`.
+   */
+  phone_numbers: Array<string>;
+}
+
+export interface PhoneNumberRemoveParams {
+  phone_numbers: Array<string>;
+}
+
+export declare namespace PhoneNumbers {
+  export {
+    type DirPhoneNumber as DirPhoneNumber,
+    type RejectionReason as RejectionReason,
+    type PhoneNumberAddResponse as PhoneNumberAddResponse,
+    type PhoneNumberRemoveResponse as PhoneNumberRemoveResponse,
+    type DirPhoneNumbersDefaultFlatPagination as DirPhoneNumbersDefaultFlatPagination,
+    type PhoneNumberListParams as PhoneNumberListParams,
+    type PhoneNumberAddParams as PhoneNumberAddParams,
+    type PhoneNumberRemoveParams as PhoneNumberRemoveParams,
+  };
+}

package/src/resources/dir.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './dir/index';

package/src/resources/document-links.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
+import * as DocumentsAPI from './documents';
 import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 
@@ -24,17 +25,7 @@ export class DocumentLinks extends APIResource {
 
 export type DocumentLinkListResponsesDefaultFlatPagination = DefaultFlatPagination<DocumentLinkListResponse>;
 
-export interface DocumentLinkListResponse {
-  /**
-   * Identifies the resource.
-   */
-  id?: string;
-
-  /**
-   * ISO 8601 formatted date-time indicating when the resource was created.
-   */
-  created_at?: string;
-
+export interface DocumentLinkListResponse extends DocumentsAPI.DocServiceRecord {
   /**
    * Identifies the associated document.
    */
@@ -54,11 +45,6 @@ export interface DocumentLinkListResponse {
    * Identifies the type of the resource.
    */
   record_type?: string;
-
-  /**
-   * ISO 8601 formatted date-time indicating when the resource was updated.
-   */
-  updated_at?: string;
 }
 
 export interface DocumentLinkListParams extends DefaultFlatPaginationParams {

package/src/resources/documents.ts

@@ -96,7 +96,7 @@ export class Documents extends APIResource {
   download(id: string, options?: RequestOptions): APIPromise<Response> {
     return this._client.get(path`/documents/${id}/download`, {
       ...options,
-      headers: buildHeaders([{ Accept: 'application/octet-stream' }, options?.headers]),
+      headers: buildHeaders([{ Accept: '*' }, options?.headers]),
       __binaryResponse: true,
     });
   }
@@ -158,12 +158,7 @@ export class Documents extends APIResource {
 
 export type DocServiceDocumentsDefaultFlatPagination = DefaultFlatPagination<DocServiceDocument>;
 
-export interface DocServiceDocument {
-  /**
-   * Identifies the resource.
-   */
-  id?: string;
-
+export interface DocServiceDocument extends DocServiceRecord {
   /**
    * The antivirus scan status of the document.
    */
@@ -174,11 +169,6 @@ export interface DocServiceDocument {
    */
   content_type?: string;
 
-  /**
-   * ISO 8601 formatted date-time indicating when the resource was created.
-   */
-  created_at?: string;
-
   /**
    * Optional reference string for customer tracking.
    */
@@ -208,11 +198,6 @@ export interface DocServiceDocument {
    * Indicates the current document reviewing status
    */
   status?: 'pending' | 'verified' | 'denied';
-
-  /**
-   * ISO 8601 formatted date-time indicating when the resource was updated.
-   */
-  updated_at?: string;
 }
 
 export namespace DocServiceDocument {
@@ -232,6 +217,28 @@ export namespace DocServiceDocument {
   }
 }
 
+export interface DocServiceRecord {
+  /**
+   * Identifies the resource.
+   */
+  id?: string;
+
+  /**
+   * ISO 8601 formatted date-time indicating when the resource was created.
+   */
+  created_at?: string;
+
+  /**
+   * Identifies the type of the resource.
+   */
+  record_type?: string;
+
+  /**
+   * ISO 8601 formatted date-time indicating when the resource was updated.
+   */
+  updated_at?: string;
+}
+
 export interface DocumentRetrieveResponse {
   data?: DocServiceDocument;
 }
@@ -402,6 +409,7 @@ export namespace DocumentUploadJsonParams {
 export declare namespace Documents {
   export {
     type DocServiceDocument as DocServiceDocument,
+    type DocServiceRecord as DocServiceRecord,
     type DocumentRetrieveResponse as DocumentRetrieveResponse,
     type DocumentUpdateResponse as DocumentUpdateResponse,
     type DocumentDeleteResponse as DocumentDeleteResponse,