pauth-js

Official JavaScript/TypeScript SDK for pauth.me

Installation

npm install github:pauth-me/pauth-js

Quick Start

import { PauthClient } from 'pauth-js';

const client = new PauthClient({ apiKey: 'test_your-api-key' });
const result = await client.verify('+819012345678');
console.log(result.pin); // "1234"（サンドボックスでは約2秒後に返る）

Sandbox Mode

• APIキーが test_ で始まる場合、サンドボックスモードで動作
• 実際に着信はせず、約2秒後に自動でPIN=1234が返る
• pauth.me でサインアップすれば無料枠（100回/月）で利用可能

API Reference

new PauthClient(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your API key (test_ prefix for sandbox) | | baseUrl | string | No | Base URL (default: https://pauth.me) |

client.authenticate(): Promise<string>

APIキーでBearer トークンを取得します。トークンはクライアント内部でキャッシュされるため、通常は直接呼び出す必要はありません。

client.entry(callerNumber, signal?): Promise<EntryEvent>

SSEストリームで着信PINを待ち受けます。

| Parameter | Type | Description | |-----------|------|-------------| | callerNumber | string | 電話番号（国際形式: +819012345678） | | signal | AbortSignal | (optional) キャンセル用シグナル |

Returns: EntryEvent — { expires_in: number, callerd_number: string, pin: string | null }

client.apply(callerNumber, pin): Promise<boolean>

PINを照合します。

| Parameter | Type | Description | |-----------|------|-------------| | callerNumber | string | 電話番号（国際形式） | | pin | string | PIN コード |

Returns: true (認証成功) / false (PIN不一致)

client.verify(callerNumber, options?): Promise<VerifyResult>

電話番号認証を一括実行します（authenticate → entry → apply）。

| Parameter | Type | Description | |-----------|------|-------------| | callerNumber | string | 電話番号（国際形式） | | options.onStep | function | ステップ進捗コールバック | | options.signal | AbortSignal | キャンセル用シグナル |

const result = await client.verify('+819012345678', {
  onStep: (step) => console.log('Step:', step),
  // step: 'authenticating' | 'waiting_for_call' | 'verifying_pin'
});
// result: { callerNumber: string, pin: string }

Error Handling

import {
  PauthError, AuthenticationError, ConflictError,
  RateLimitError, StreamError, TimeoutError, PauthAPIError
} from 'pauth-js';

try {
  const result = await client.verify('+819012345678');
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log('Rate limited. Retry after:', err.retryAfter);
  } else if (err instanceof ConflictError) {
    console.log('Duplicate request detected');
  } else if (err instanceof TimeoutError) {
    console.log('Timed out waiting for call');
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid or expired API key');
  } else if (err instanceof PauthAPIError) {
    console.log('API error:', err.status, err.message);
  }
}

| Error Class | Trigger | |-------------|---------| | AuthenticationError | 無効または期限切れのAPIキー/トークン (401) | | ConflictError | 同一番号で認証が既に進行中 (409) | | RateLimitError | レート制限超過 (429)。err.retryAfter (秒) を参照 | | StreamError | SSEストリームエラー | | TimeoutError | PIN待機タイムアウト | | PauthAPIError | その他のAPIエラー。err.status でHTTPステータスを取得 |

Examples

• examples/node-basic — Node.js での基本的な使い方
• examples/nextjs-form — Next.js (App Router) フォームサンプル

License

MIT