telnyx-account-javascript

用途

Telnyx Account - JavaScript 是一个用于管理 Telnyx 账户相关功能的 JavaScript SDK 技能。它通过 telnyx@6.74.2 包提供对账户余额、支付、发票、Webhook 投递记录、审计日志和明细记录的访问能力，帮助开发者在 JavaScript/Node.js 应用中集成 Telnyx 账户管理功能。

主要能力

该技能涵盖以下 API 操作：

审计日志：通过 client.auditEvents.list() 获取审计日志条目列表，返回字段包括 alternate_resource_id、change_made_by、change_type、changes、created_at、id、organization_id、record_type、resource_id、user_id。审计日志为尽力而为、最终一致的记录。
账户余额：通过 client.balance.retrieve() 获取余额详情，返回 available_credit、balance、credit_limit、currency、pending、record_type。
月度费用明细：通过 client.chargesBreakdown.retrieve({ start_date }) 获取指定日期范围内电话号码的月度费用明细，日期范围不能超过 31 天。
月度费用汇总：通过 client.chargesSummary.retrieve({ end_date, start_date }) 获取指定日期范围的月度费用汇总，日期范围不能超过 31 天。
明细记录搜索：通过 client.detailRecords.list() 搜索 Telnyx 平台上的任意明细记录，返回字段包括 carrier、carrier_fee、cld、cli、completed_at、cost、country_code、created_at、currency、delivery_status、direction、errors、fteu、mcc、message_type、mnc、on_net、parts、profile_id、profile_name、rate、record_type、sent_at、source_country_code、status、tags、updated_at、user_id、uuid。
发票列表：通过 client.invoices.list() 获取分页发票列表，返回 file_id、invoice_id、paid、period_end、period_start、url。
发票详情：通过 client.invoices.retrieve('id') 根据唯一标识符获取单张发票，返回 download_url、file_id、invoice_id、paid、period_end、period_start、url。
自动充值偏好：通过 client.payment.autoRechargePrefs.list() 获取支付自动充值偏好，返回 enabled、id、invoice_enabled、preference、recharge_amount、record_type、threshold_amount。
更新自动充值偏好：通过 client.payment.autoRechargePrefs.update() 更新支付自动充值偏好，可选参数包括 enabled、invoice_enabled、preference、recharge_amount、threshold_amount。
用户标签：通过 client.userTags.list() 列出所有用户标签，返回 number_tags、outbound_profile_tags。
创建存储支付交易：通过 client.payment.createStoredPaymentTransaction({ amount }) 创建存储支付交易，amount 为必填项，返回 amount_cents、amount_currency、auto_recharge、created_at、id、processor_status、record_type、transaction_processing_type。
Webhook 投递列表：通过 client.webhookDeliveries.list() 列出当前认证用户的 webhook_deliveries，返回 attempts、finished_at、id、record_type、started_at、status、user_id、webhook。
Webhook 投递详情：通过 client.webhookDeliveries.retrieve('id') 根据 ID 获取 webhook_delivery 调试数据，如时间戳、投递状态和尝试记录。

使用方式

安装：

npm install telnyx@6.74.2

初始化：

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

所有示例均假设 client 已按上述方式初始化。

错误处理：所有 API 调用都可能因网络错误、限流（429）、验证错误（422）或认证错误（401）而失败。生产代码中应始终处理错误：

try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}

常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 限流（使用指数退避重试）。

分页：列表方法返回自动分页迭代器。使用 for await (const item of result) { ... } 自动遍历所有页面。

适用场景

适用于需要在 JavaScript/Node.js 项目中集成 Telnyx 账户财务与审计功能的开发者，例如查询账户余额、查看月度费用、管理发票、配置自动充值、创建支付交易、监控 Webhook 投递状态以及检索审计日志和明细记录。

限制

月度费用明细和汇总的日期范围不能超过 31 天。
审计日志为尽力而为、最终一致的记录。
其他限制暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制