Zendesk API Client for TypeScript

TypeScript用のZendesk API クライアントライブラリです。型安全で使いやすいインターフェースを提供し、自動的なRate Limit管理機能を搭載しています。

インストール

npm install zendesk-api-client-typescript

🚀 クイックスタート

import { ZendeskClient } from 'zendesk-api-client-typescript';

const client = new ZendeskClient({
  subdomain: 'your-subdomain',
  email: '[email protected]',
  token: 'your-api-token'
});

// チケット一覧を取得
const tickets = await client.tickets.list();

// ユーザーを作成
const user = await client.users.create({
  name: 'John Doe',
  email: '[email protected]'
});

使用方法

基本的な設定

import { ZendeskClient } from 'zendesk-api-client-typescript';

const client = new ZendeskClient({
  subdomain: 'your-subdomain',
  email: '[email protected]',
  token: 'your-api-token',
  // Rate limit対応のオプション設定
  httpOptions: {
    maxRetries: 3,        // 429エラー時の最大リトライ回数
    retryDelay: 1000,     // リトライ間隔（ミリ秒）
    rateLimitBuffer: 10   // 残りリクエスト数がこの値以下で自動待機
  }
});

チケット操作

// チケット一覧取得
const tickets = await client.tickets.list({
  per_page: 50,
  sort_by: 'created_at',
  sort_order: 'desc'
});

// チケット詳細取得
const ticket = await client.tickets.show(12345);

// チケット作成
const newTicket = await client.tickets.create({
  subject: 'サポートが必要です',
  comment: {
    body: 'この問題について助けが必要です。',
    public: true
  },
  type: 'question',
  priority: 'normal'
});

// チケット更新
const updatedTicket = await client.tickets.update(12345, {
  status: 'solved',
  comment: {
    body: '問題が解決しました。',
    public: true
  }
});

開発

# 依存関係のインストール
npm install

# ビルド
npm run build

# テスト実行
npm test

# リント
npm run lint

# フォーマット
npm run format

Rate Limit管理

クライアントは自動的にZendeskのRate Limitに対応します：

// Rate limit情報の取得
const rateLimitInfo = client.getRateLimitInfo();
if (rateLimitInfo) {
  console.log(`残りリクエスト数: ${rateLimitInfo.remaining}/${rateLimitInfo.limit}`);
  console.log(`リセット時刻: ${rateLimitInfo.resetTime}`);
}

// 手動でRate limitを回避したい場合
await client.users.list();
const info = client.getRateLimitInfo();
if (info && info.remaining < 5) {
  console.log('Rate limit近づいています。少し待機...');
  await new Promise(resolve => setTimeout(resolve, 60000));
}

Rate Limit機能

• ✅ 自動リトライ: 429エラー時の指数バックオフリトライ
• ✅ プロアクティブ待機: 残りリクエスト数が少なくなったら自動待機
• ✅ ヘッダー監視: Zendeskのrate limitヘッダーを自動解析
• ✅ 柔軟な設定: リトライ回数、遅延時間、バッファサイズを調整可能

📖 API ドキュメント

ZendeskClient

const client = new ZendeskClient(config: ZendeskClientConfig)

ZendeskClientConfig

| プロパティ | 型 | 必須 | 説明 | |------------|----|----|-----| | subdomain | string | ✅ | Zendeskサブドメイン | | email | string | ✅ | Zendeskアカウントのメールアドレス | | token | string | ✅ | API トークン | | apiVersion | string | ❌ | APIバージョン (デフォルト: 'v2') | | httpOptions | HttpClientOptions | ❌ | HTTP設定オプション |

HttpClientOptions

| プロパティ | 型 | デフォルト | 説明 | |------------|----|-----------|----| | maxRetries | number | 3 | 最大リトライ回数 | | retryDelay | number | 1000 | ベースリトライ間隔（ミリ秒） | | rateLimitBuffer | number | 10 | プロアクティブ待機のしきい値 |

対応API

• Users API: ユーザーの作成、取得、更新、削除、検索
• Organizations API: 組織の作成、取得、更新、削除、検索
• Tickets API: チケットの作成、取得、更新、削除、検索

詳細なAPIリファレンスはZendesk公式ドキュメントを参照してください。

📚 使用例

ユーザー管理

// ユーザーの作成
const newUser = await client.users.create({
  name: '田中太郎',
  email: '[email protected]',
  role: 'end-user',
  verified: true,
  tags: ['vip', 'japanese']
});

// ユーザーの検索
const users = await client.users.search('[email protected]');

// ユーザーの更新
const updatedUser = await client.users.update(userId, {
  name: '田中次郎',
  phone: '+81-90-1234-5678'
});

組織管理

// 組織の作成
const organization = await client.organizations.create({
  name: '株式会社サンプル',
  domain_names: ['sample.co.jp'],
  details: '東京都に本社を置くIT企業'
});

// 組織メンバーの管理
const memberships = await client.organizations.listMemberships(organizationId);

チケット管理

// チケットの作成
const ticket = await client.tickets.create({
  subject: 'ログインできません',
  comment: {
    body: 'パスワードを忘れてしまい、ログインできない状況です。',
    public: true
  },
  type: 'incident',
  priority: 'high',
  tags: ['login', 'password']
});

// チケットの更新
const updatedTicket = await client.tickets.update(ticketId, {
  status: 'open',
  assignee_id: agentId,
  comment: {
    body: '調査を開始いたします。',
    public: true
  }
});

// チケットの検索
const urgentTickets = await client.tickets.search(
  'type:incident priority:high status<solved'
);

エラーハンドリング

import {
  ZendeskError,
  ZendeskRateLimitError,
  ZendeskAuthenticationError
} from 'zendesk-api-client-typescript';

try {
  const user = await client.users.create(userData);
} catch (error) {
  if (error instanceof ZendeskRateLimitError) {
    console.log(`Rate limit発生。${error.retryAfter}秒後に再試行してください`);
  } else if (error instanceof ZendeskAuthenticationError) {
    console.log('認証エラー: APIトークンを確認してください');
  } else if (error instanceof ZendeskError) {
    console.log(`Zendesk API エラー: ${error.message}`);
  }
}

ライセンス

MIT