telnyx 6.83.0 → 7.2.0

package/src/resources/enterprises/reputation/remediation.ts

@@ -0,0 +1,273 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as RemediationAPI from './remediation';
+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-number reputation monitoring (spam-score lookup and tracking).
+ */
+export class Remediation extends APIResource {
+  /**
+   * Submit a batch of phone numbers belonging to this enterprise for reputation
+   * remediation. The request is accepted asynchronously: this endpoint returns `202`
+   * with the persisted request id, then the request transitions through processing
+   * states until completion. Use the GET endpoints to poll status and per-number
+   * results.
+   *
+   * Each phone number must be in E.164 format and belong to this enterprise. A
+   * number that already has an in-flight remediation request is rejected.
+   *
+   * @example
+   * ```ts
+   * const remediationRequestWrapped =
+   *   await client.enterprises.reputation.remediation.create(
+   *     '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *     {
+   *       call_purpose:
+   *         'Appointment reminders for our dental clinic.',
+   *       phone_numbers: ['+19493253498', '+12134445566'],
+   *       contact_email: 'ops@example.com',
+   *       webhook_url:
+   *         'https://example.com/webhooks/remediation',
+   *     },
+   *   );
+   * ```
+   */
+  create(
+    enterpriseID: string,
+    body: RemediationCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<RemediationRequestWrapped> {
+    return this._client.post(path`/enterprises/${enterpriseID}/reputation/remediation`, { body, ...options });
+  }
+
+  /**
+   * Retrieve the full detail of a remediation request, including current status,
+   * per-number results (once available), and submission metadata.
+   *
+   * @example
+   * ```ts
+   * const remediationRequestWrapped =
+   *   await client.enterprises.reputation.remediation.retrieve(
+   *     'b7c1f1c0-7a9d-4f0a-9d3e-2f6a1c4b8e21',
+   *     {
+   *       enterprise_id: '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *     },
+   *   );
+   * ```
+   */
+  retrieve(
+    remediationID: string,
+    params: RemediationRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<RemediationRequestWrapped> {
+    const { enterprise_id } = params;
+    return this._client.get(
+      path`/enterprises/${enterprise_id}/reputation/remediation/${remediationID}`,
+      options,
+    );
+  }
+
+  /**
+   * Paginated list of remediation requests for this enterprise. List items omit
+   * per-number results and webhook URLs to keep the response small; call GET by id
+   * for full detail. Supports JSON:API pagination and optional filters on status and
+   * created-at range.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const remediationListResponse of client.enterprises.reputation.remediation.list(
+   *   '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    enterpriseID: string,
+    query: RemediationListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<RemediationListResponsesDefaultFlatPagination, RemediationListResponse> {
+    return this._client.getAPIList(
+      path`/enterprises/${enterpriseID}/reputation/remediation`,
+      DefaultFlatPagination<RemediationListResponse>,
+      { query, ...options },
+    );
+  }
+}
+
+export type RemediationListResponsesDefaultFlatPagination = DefaultFlatPagination<RemediationListResponse>;
+
+export interface RemediationRequestWrapped {
+  /**
+   * Full detail of a remediation request, returned on submit and GET by id.
+   */
+  data: RemediationRequestWrapped.Data;
+}
+
+export namespace RemediationRequestWrapped {
+  /**
+   * Full detail of a remediation request, returned on submit and GET by id.
+   */
+  export interface Data {
+    id: string;
+
+    call_purpose: string;
+
+    created_at: string;
+
+    /**
+     * Total phone numbers in this batch, including any later cancelled. May exceed the
+     * sum of the per-category result buckets, which omit cancelled numbers.
+     */
+    phone_numbers_count: number;
+
+    /**
+     * Numbers rejected before submission (e.g. cooldown).
+     */
+    phone_numbers_ineligible: number;
+
+    /**
+     * Numbers accepted for remediation, i.e. not rejected as ineligible. Counts
+     * numbers still queued (pending) as well as processed ones.
+     */
+    phone_numbers_submitted: number;
+
+    /**
+     * Customer-facing status of a remediation request.
+     */
+    status: RemediationAPI.RemediationStatus;
+
+    updated_at: string;
+
+    contact_email?: string | null;
+
+    /**
+     * Per-category buckets. Populated once results are available. Null while the
+     * request is still pending.
+     */
+    results?: Data.Results | null;
+
+    tier1_completed_at?: string | null;
+
+    tier2_completed_at?: string | null;
+
+    webhook_url?: string | null;
+  }
+
+  export namespace Data {
+    /**
+     * Per-category buckets. Populated once results are available. Null while the
+     * request is still pending.
+     */
+    export interface Results {
+      ineligible?: Array<string>;
+
+      not_flagged?: Array<string>;
+
+      refused?: Array<string>;
+
+      remediated?: Array<string>;
+
+      requires_review?: Array<string>;
+    }
+  }
+}
+
+/**
+ * Customer-facing status of a remediation request.
+ */
+export type RemediationStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * Slim list-endpoint shape. Omits per-number results and webhook URLs to keep
+ * responses small.
+ */
+export interface RemediationListResponse {
+  id: string;
+
+  call_purpose: string;
+
+  created_at: string;
+
+  phone_numbers_count: number;
+
+  /**
+   * Customer-facing status of a remediation request.
+   */
+  status: RemediationStatus;
+
+  updated_at: string;
+
+  tier1_completed_at?: string | null;
+
+  tier2_completed_at?: string | null;
+}
+
+export interface RemediationCreateParams {
+  /**
+   * How the numbers are used (free text).
+   */
+  call_purpose: string;
+
+  /**
+   * Phone numbers in E.164 format. Each must belong to this enterprise. Maximum
+   * 2,000 per request.
+   */
+  phone_numbers: Array<string>;
+
+  /**
+   * Optional contact email for this remediation request.
+   */
+  contact_email?: string;
+
+  /**
+   * Optional https:// URL for status notifications.
+   */
+  webhook_url?: string;
+}
+
+export interface RemediationRetrieveParams {
+  /**
+   * The enterprise id. Lowercase UUID.
+   */
+  enterprise_id: string;
+}
+
+export interface RemediationListParams extends DefaultFlatPaginationParams {
+  /**
+   * Only requests created on or after this timestamp (ISO 8601).
+   */
+  'filter[created_at][gte]'?: string;
+
+  /**
+   * Only requests created on or before this timestamp (ISO 8601).
+   */
+  'filter[created_at][lte]'?: string;
+
+  /**
+   * Filter by customer-facing status.
+   */
+  'filter[status]'?: RemediationStatus;
+}
+
+export declare namespace Remediation {
+  export {
+    type RemediationRequestWrapped as RemediationRequestWrapped,
+    type RemediationStatus as RemediationStatus,
+    type RemediationListResponse as RemediationListResponse,
+    type RemediationListResponsesDefaultFlatPagination as RemediationListResponsesDefaultFlatPagination,
+    type RemediationCreateParams as RemediationCreateParams,
+    type RemediationRetrieveParams as RemediationRetrieveParams,
+    type RemediationListParams as RemediationListParams,
+  };
+}

package/src/resources/enterprises/reputation/reputation.ts

@@ -1,62 +1,76 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
+import * as LoaAPI from './loa';
+import { AgentInput, Loa, LoaRenderParams, LoaUpdateParams } from './loa';
 import * as NumbersAPI from './numbers';
 import {
   NumberAssociateParams,
-  NumberAssociateResponse,
   NumberDisassociateParams,
   NumberListParams,
+  NumberRefreshParams,
+  NumberRefreshResponse,
   NumberRetrieveParams,
-  NumberRetrieveResponse,
   Numbers,
+  ReputationPhoneNumber,
+  ReputationPhoneNumberList,
+  ReputationPhoneNumberListWithReputation,
+  ReputationPhoneNumberWithReputation,
+  ReputationPhoneNumbersDefaultFlatPagination,
 } from './numbers';
+import * as RemediationAPI from './remediation';
+import {
+  Remediation,
+  RemediationCreateParams,
+  RemediationListParams,
+  RemediationListResponse,
+  RemediationListResponsesDefaultFlatPagination,
+  RemediationRequestWrapped,
+  RemediationRetrieveParams,
+  RemediationStatus,
+} from './remediation';
 import { APIPromise } from '../../../core/api-promise';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
 /**
- * Manage Number Reputation enrollment and check frequency settings for an enterprise
+ * Phone-number reputation monitoring (spam-score lookup and tracking).
  */
 export class Reputation extends APIResource {
   numbers: NumbersAPI.Numbers = new NumbersAPI.Numbers(this._client);
+  loa: LoaAPI.Loa = new LoaAPI.Loa(this._client);
+  remediation: RemediationAPI.Remediation = new RemediationAPI.Remediation(this._client);
 
   /**
-   * Retrieve the current Number Reputation settings for an enterprise.
-   *
-   * Returns the enrollment status (`pending`, `approved`, `rejected`, `deleted`),
-   * check frequency, and any rejection reasons.
+   * Phone Number Reputation tracks how your outbound caller-IDs are perceived (spam
+   * risk, engagement, etc.) across the call-screening ecosystem. This endpoint reads
+   * the enterprise-level settings: whether the product is enabled, the refresh
+   * cadence, and the stored Letter of Authorization document id.
    *
-   * Returns `404` if reputation has not been enabled for this enterprise.
+   * Returns `404` if reputation has never been enabled for this enterprise.
    *
    * @example
    * ```ts
-   * const reputation =
+   * const enterpriseReputationPublicWrapped =
    *   await client.enterprises.reputation.retrieve(
-   *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
+   *     '4a6192a4-573d-446d-b3ce-aff9117272a6',
    *   );
    * ```
    */
-  retrieve(enterpriseID: string, options?: RequestOptions): APIPromise<ReputationRetrieveResponse> {
+  retrieve(enterpriseID: string, options?: RequestOptions): APIPromise<EnterpriseReputationPublicWrapped> {
     return this._client.get(path`/enterprises/${enterpriseID}/reputation`, options);
   }
 
   /**
-   * Disable Number Reputation for an enterprise.
-   *
-   * This will:
-   *
-   * - Delete the reputation settings record
-   * - Log the deletion for audit purposes
-   * - Stop all future automated reputation checks
-   *
-   * **Note:** Can only be performed on `approved` reputation settings.
+   * Disable Phone Number Reputation. All registered numbers are de-registered as a
+   * cascade. The enterprise itself is unaffected. Returns `204` on success, `404` if
+   * reputation is not enabled for this enterprise.
    *
    * @example
    * ```ts
    * await client.enterprises.reputation.disable(
-   *   '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
+   *   '4a6192a4-573d-446d-b3ce-aff9117272a6',
    * );
    * ```
    */
@@ -68,69 +82,59 @@ export class Reputation extends APIResource {
   }
 
   /**
-   * Enable Number Reputation service for an enterprise.
-   *
-   * **Requirements:**
-   *
-   * - Signed LOA (Letter of Authorization) document ID
-   * - Reputation check frequency (defaults to `business_daily`)
-   * - Number Reputation Terms of Service must be accepted
-   *
-   * **Flow:**
+   * Activate Phone Number Reputation for the given enterprise. Requires an uploaded
+   * Letter of Authorization document (the `loa_document_id` references the Telnyx
+   * Documents API) and a refresh-frequency selection. After activation, individual
+   * phone numbers can be registered via `POST .../reputation/numbers`.
    *
-   * 1. Registers the enterprise for reputation monitoring
-   * 2. Creates reputation settings with `pending` status
-   * 3. Awaits admin approval before monitoring begins
+   * **Prerequisite**: the calling user must have agreed to the Phone Number
+   * Reputation Terms of Service (`POST /terms_of_service/number_reputation/agree`).
    *
-   * **Resubmission After Rejection:** If a previously rejected record exists, this
-   * endpoint will delete it and create a new `pending` record.
+   * Failure modes:
    *
-   * **Available Frequencies:**
+   * - `403` - Phone Number Reputation Terms of Service not accepted.
+   * - `404` - enterprise does not exist or does not belong to your account.
+   * - `400` - reputation already enabled for this enterprise.
+   * - `422` - `loa_document_id` missing or `check_frequency` invalid.
    *
-   * - `business_daily` — Monday–Friday
-   * - `daily` — Every day
-   * - `weekly` — Once per week
-   * - `biweekly` — Once every two weeks
-   * - `monthly` — Once per month
-   * - `never` — Manual refresh only
+   * **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
+   * for current pricing.
    *
    * @example
    * ```ts
-   * const response = await client.enterprises.reputation.enable(
-   *   '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
-   *   { loa_document_id: 'doc_01HXYZ1234ABCDEF' },
-   * );
+   * const enterpriseReputationPublicWrapped =
+   *   await client.enterprises.reputation.enable(
+   *     '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *     {
+   *       loa_document_id:
+   *         '2a7e8337-e803-4057-a4ae-26c40eb0bc6c',
+   *       check_frequency: 'business_daily',
+   *     },
+   *   );
    * ```
    */
   enable(
     enterpriseID: string,
     body: ReputationEnableParams,
     options?: RequestOptions,
-  ): APIPromise<ReputationEnableResponse> {
+  ): APIPromise<EnterpriseReputationPublicWrapped> {
     return this._client.post(path`/enterprises/${enterpriseID}/reputation`, { body, ...options });
   }
 
   /**
-   * Update how often reputation data is automatically refreshed.
-   *
-   * **Note:** The enterprise must have `approved` reputation settings. Updating
-   * frequency on `pending` or `rejected` settings will return an error.
-   *
-   * **Available Frequencies:**
+   * Update how often Telnyx refreshes the reputation data for this enterprise's
+   * registered numbers. The new frequency takes effect on the next scheduled
+   * refresh.
    *
-   * - `business_daily` — Monday–Friday
-   * - `daily` — Every day including weekends
-   * - `weekly` — Once per week
-   * - `biweekly` — Once every two weeks
-   * - `monthly` — Once per month
-   * - `never` — Manual refresh only (no automatic checks)
+   * The enterprise's reputation must be in `approved` status. A request made while
+   * the status is `pending` is rejected with `400 Bad Request`.
    *
    * @example
    * ```ts
-   * const response =
+   * const enterpriseReputationPublicWrapped =
    *   await client.enterprises.reputation.updateFrequency(
-   *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
-   *     { check_frequency: 'business_daily' },
+   *     '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *     { check_frequency: 'weekly' },
    *   );
    * ```
    */
@@ -138,99 +142,128 @@ export class Reputation extends APIResource {
     enterpriseID: string,
     body: ReputationUpdateFrequencyParams,
     options?: RequestOptions,
-  ): APIPromise<ReputationUpdateFrequencyResponse> {
+  ): APIPromise<EnterpriseReputationPublicWrapped> {
     return this._client.patch(path`/enterprises/${enterpriseID}/reputation/frequency`, { body, ...options });
   }
 }
 
 export interface EnterpriseReputationPublic {
   /**
-   * Frequency for refreshing reputation data
+   * How often Telnyx refreshes the stored reputation data for this enterprise's
+   * registered numbers.
    */
-  check_frequency?: 'business_daily' | 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'never';
+  check_frequency?: ReputationCheckFrequency;
 
-  /**
-   * When the reputation settings were created
-   */
   created_at?: string;
 
-  /**
-   * ID of the associated enterprise
-   */
   enterprise_id?: string;
 
   /**
-   * ID of the signed LOA document
+   * Id of the signed LOA document.
    */
   loa_document_id?: string | null;
 
   /**
-   * Reasons for rejection (present when status is rejected)
+   * Customer-facing Letter-of-Authorization verification state. `approved` is
+   * required (alongside reputation status) before phone numbers can be added.
    */
-  rejection_reasons?: Array<string> | null;
+  loa_status?: 'pending' | 'approved' | 'rejected';
 
   /**
-   * Current enrollment status
+   * Populated when `status` is `rejected`.
    */
-  status?: 'pending' | 'approved' | 'rejected' | 'deleted';
+  rejection_reasons?: Array<string> | null;
 
   /**
-   * When the reputation settings were last updated
+   * Lifecycle status of the enterprise's Phone Number Reputation activation.
    */
-  updated_at?: string;
-}
+  status?: 'pending' | 'approved' | 'deleted' | 'rejected';
 
-export interface ReputationRetrieveResponse {
-  data?: EnterpriseReputationPublic;
+  updated_at?: string;
 }
 
-export interface ReputationEnableResponse {
-  data?: EnterpriseReputationPublic;
+export interface EnterpriseReputationPublicWrapped {
+  data: EnterpriseReputationPublic;
 }
 
-export interface ReputationUpdateFrequencyResponse {
-  data?: EnterpriseReputationPublic;
-}
+/**
+ * How often Telnyx refreshes the stored reputation data for this enterprise's
+ * registered numbers.
+ */
+export type ReputationCheckFrequency =
+  | 'business_daily'
+  | 'daily'
+  | 'weekly'
+  | 'biweekly'
+  | 'monthly'
+  | 'never';
 
 export interface ReputationEnableParams {
   /**
-   * ID of the signed Letter of Authorization (LOA) document uploaded to the document
-   * service
+   * Id of the signed Letter of Authorization document, returned by the Telnyx
+   * Documents API after upload (upload via `POST /v2/documents`; see
+   * https://developers.telnyx.com/api/documents).
    */
   loa_document_id: string;
 
   /**
-   * Frequency for automatically refreshing reputation data
+   * How often Telnyx refreshes the stored reputation data for this enterprise's
+   * registered numbers.
    */
-  check_frequency?: 'business_daily' | 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'never';
+  check_frequency?: ReputationCheckFrequency;
 }
 
 export interface ReputationUpdateFrequencyParams {
   /**
-   * New frequency for refreshing reputation data
+   * How often Telnyx refreshes the stored reputation data for this enterprise's
+   * registered numbers.
    */
-  check_frequency: 'business_daily' | 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'never';
+  check_frequency: ReputationCheckFrequency;
 }
 
 Reputation.Numbers = Numbers;
+Reputation.Loa = Loa;
+Reputation.Remediation = Remediation;
 
 export declare namespace Reputation {
   export {
     type EnterpriseReputationPublic as EnterpriseReputationPublic,
-    type ReputationRetrieveResponse as ReputationRetrieveResponse,
-    type ReputationEnableResponse as ReputationEnableResponse,
-    type ReputationUpdateFrequencyResponse as ReputationUpdateFrequencyResponse,
+    type EnterpriseReputationPublicWrapped as EnterpriseReputationPublicWrapped,
+    type ReputationCheckFrequency as ReputationCheckFrequency,
     type ReputationEnableParams as ReputationEnableParams,
     type ReputationUpdateFrequencyParams as ReputationUpdateFrequencyParams,
   };
 
   export {
     Numbers as Numbers,
-    type NumberRetrieveResponse as NumberRetrieveResponse,
-    type NumberAssociateResponse as NumberAssociateResponse,
+    type ReputationPhoneNumber as ReputationPhoneNumber,
+    type ReputationPhoneNumberList as ReputationPhoneNumberList,
+    type ReputationPhoneNumberListWithReputation as ReputationPhoneNumberListWithReputation,
+    type ReputationPhoneNumberWithReputation as ReputationPhoneNumberWithReputation,
+    type NumberRefreshResponse as NumberRefreshResponse,
+    type ReputationPhoneNumbersDefaultFlatPagination as ReputationPhoneNumbersDefaultFlatPagination,
     type NumberRetrieveParams as NumberRetrieveParams,
     type NumberListParams as NumberListParams,
     type NumberAssociateParams as NumberAssociateParams,
     type NumberDisassociateParams as NumberDisassociateParams,
+    type NumberRefreshParams as NumberRefreshParams,
+  };
+
+  export {
+    Loa as Loa,
+    type AgentInput as AgentInput,
+    type LoaUpdateParams as LoaUpdateParams,
+    type LoaRenderParams as LoaRenderParams,
+  };
+
+  export {
+    Remediation as Remediation,
+    type RemediationRequestWrapped as RemediationRequestWrapped,
+    type RemediationStatus as RemediationStatus,
+    type RemediationListResponse as RemediationListResponse,
+    type RemediationListResponsesDefaultFlatPagination as RemediationListResponsesDefaultFlatPagination,
+    type RemediationCreateParams as RemediationCreateParams,
+    type RemediationRetrieveParams as RemediationRetrieveParams,
+    type RemediationListParams as RemediationListParams,
   };
 }

package/src/resources/external-connections/external-connections.ts

@@ -13,12 +13,12 @@ import {
 } from './civic-addresses';
 import * as LogMessagesAPI from './log-messages';
 import {
+  LogMessage,
   LogMessageDismissResponse,
   LogMessageListParams,
-  LogMessageListResponse,
-  LogMessageListResponsesDefaultPaginationForLogMessages,
   LogMessageRetrieveResponse,
   LogMessages,
+  LogMessagesDefaultPaginationForLogMessages,
 } from './log-messages';
 import * as PhoneNumbersAPI from './phone-numbers';
 import {
@@ -33,12 +33,12 @@ import {
 } from './phone-numbers';
 import * as ReleasesAPI from './releases';
 import {
+  Release,
   ReleaseListParams,
-  ReleaseListResponse,
-  ReleaseListResponsesDefaultFlatPagination,
   ReleaseRetrieveParams,
   ReleaseRetrieveResponse,
   Releases,
+  ReleasesDefaultFlatPagination,
   TnReleaseEntry,
 } from './releases';
 import * as UploadsAPI from './uploads';
@@ -562,10 +562,10 @@ export declare namespace ExternalConnections {
 
   export {
     LogMessages as LogMessages,
+    type LogMessage as LogMessage,
     type LogMessageRetrieveResponse as LogMessageRetrieveResponse,
-    type LogMessageListResponse as LogMessageListResponse,
     type LogMessageDismissResponse as LogMessageDismissResponse,
-    type LogMessageListResponsesDefaultPaginationForLogMessages as LogMessageListResponsesDefaultPaginationForLogMessages,
+    type LogMessagesDefaultPaginationForLogMessages as LogMessagesDefaultPaginationForLogMessages,
     type LogMessageListParams as LogMessageListParams,
   };
 
@@ -592,10 +592,10 @@ export declare namespace ExternalConnections {
 
   export {
     Releases as Releases,
+    type Release as Release,
     type TnReleaseEntry as TnReleaseEntry,
     type ReleaseRetrieveResponse as ReleaseRetrieveResponse,
-    type ReleaseListResponse as ReleaseListResponse,
-    type ReleaseListResponsesDefaultFlatPagination as ReleaseListResponsesDefaultFlatPagination,
+    type ReleasesDefaultFlatPagination as ReleasesDefaultFlatPagination,
     type ReleaseRetrieveParams as ReleaseRetrieveParams,
     type ReleaseListParams as ReleaseListParams,
   };