atl-fetch 1.0.0

package/dist/ports/http/http-port.d.ts

@@ -0,0 +1,107 @@
+import { type Result } from 'neverthrow';
+import type { HttpError, HttpRequestOptions, HttpResponse, ProgressCallback } from '../../types/http.js';
+/**
+ * HTTP リクエストを実行する
+ *
+ * got ライブラリを使用して HTTP リクエストを実行し、Result 型で結果を返す。
+ * 認証ヘッダーの付与、リトライ、タイムアウト処理をサポート。
+ *
+ * @typeParam T - レスポンスデータの型
+ * @param url - リクエスト先の URL
+ * @param options - リクエストオプション（メソッド、ヘッダー、ボディ、タイムアウト）
+ * @returns 成功時は {@link HttpResponse} を含む Ok、失敗時は {@link HttpError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // GET リクエスト
+ * const result = await httpRequest<{ id: string }>('https://api.example.com/data');
+ * if (result.isOk()) {
+ *   console.log(result.value.data.id);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 認証付き GET リクエスト
+ * const result = await httpRequest<{ user: string }>('https://api.example.com/me', {
+ *   headers: { Authorization: 'Basic xxx' }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // POST リクエスト
+ * const result = await httpRequest<{ id: string }>('https://api.example.com/create', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ name: 'test' }),
+ * });
+ * ```
+ */
+export declare function httpRequest<T>(url: string, options?: HttpRequestOptions): Promise<Result<HttpResponse<T>, HttpError>>;
+/**
+ * エラーを HttpError にマッピングする
+ *
+ * @param error - キャッチしたエラー
+ * @returns 対応する HttpError
+ *
+ * @internal テスト用に export
+ */
+export declare function mapErrorToHttpError(error: unknown): HttpError;
+/**
+ * HTTP ステータスコードに対応するテキストを取得する
+ *
+ * @param status - HTTP ステータスコード
+ * @returns ステータステキスト
+ *
+ * @internal テスト用に export
+ */
+export declare function getStatusText(status: number): string;
+/**
+ * ファイルをダウンロードして指定パスに保存する
+ *
+ * got ライブラリを使用してストリームでファイルをダウンロードし、
+ * 指定したパスに保存する。大きなファイルでもメモリを節約できる。
+ *
+ * @param url - ダウンロード対象の URL
+ * @param destPath - 保存先ファイルパス
+ * @param headers - リクエストヘッダー（認証ヘッダー等）
+ * @param onProgress - 進捗コールバック関数
+ * @param timeout - タイムアウト（ミリ秒）
+ * @returns 成功時は void を含む Ok、失敗時は {@link HttpError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 基本的なダウンロード
+ * const result = await httpDownload(
+ *   'https://example.com/file.pdf',
+ *   '/path/to/save/file.pdf'
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 認証付きダウンロード
+ * const result = await httpDownload(
+ *   'https://api.example.com/attachments/123',
+ *   '/path/to/save/attachment.pdf',
+ *   { Authorization: 'Basic xxx' }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 進捗コールバック付きダウンロード
+ * const result = await httpDownload(
+ *   'https://example.com/large-file.zip',
+ *   '/path/to/save/large-file.zip',
+ *   undefined,
+ *   (transferred, total) => {
+ *     if (total) {
+ *       console.log(`Progress: ${(transferred / total * 100).toFixed(1)}%`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function httpDownload(url: string, destPath: string, headers?: Record<string, string>, onProgress?: ProgressCallback, timeout?: number): Promise<Result<void, HttpError>>;

package/dist/ports/http/http-port.js

@@ -0,0 +1,238 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import got, { HTTPError, RequestError, TimeoutError } from 'got';
+import { err, ok } from 'neverthrow';
+/**
+ * デフォルトのタイムアウト（ミリ秒）
+ */
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * リトライ対象のステータスコード
+ */
+const RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+/**
+ * リトライ回数
+ */
+const DEFAULT_RETRY_LIMIT = 2;
+/**
+ * HTTP リクエストを実行する
+ *
+ * got ライブラリを使用して HTTP リクエストを実行し、Result 型で結果を返す。
+ * 認証ヘッダーの付与、リトライ、タイムアウト処理をサポート。
+ *
+ * @typeParam T - レスポンスデータの型
+ * @param url - リクエスト先の URL
+ * @param options - リクエストオプション（メソッド、ヘッダー、ボディ、タイムアウト）
+ * @returns 成功時は {@link HttpResponse} を含む Ok、失敗時は {@link HttpError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // GET リクエスト
+ * const result = await httpRequest<{ id: string }>('https://api.example.com/data');
+ * if (result.isOk()) {
+ *   console.log(result.value.data.id);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 認証付き GET リクエスト
+ * const result = await httpRequest<{ user: string }>('https://api.example.com/me', {
+ *   headers: { Authorization: 'Basic xxx' }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // POST リクエスト
+ * const result = await httpRequest<{ id: string }>('https://api.example.com/create', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ name: 'test' }),
+ * });
+ * ```
+ */
+export async function httpRequest(url, options = {}) {
+    const { method = 'GET', headers = {}, body, timeout = DEFAULT_TIMEOUT } = options;
+    try {
+        const response = await got(url, {
+            body,
+            headers,
+            method,
+            responseType: 'json',
+            retry: {
+                limit: DEFAULT_RETRY_LIMIT,
+                statusCodes: RETRY_STATUS_CODES,
+            },
+            timeout: {
+                request: timeout,
+            },
+        });
+        // ヘッダーを Record<string, string> に変換
+        const responseHeaders = {};
+        for (const [key, value] of Object.entries(response.headers)) {
+            if (typeof value === 'string') {
+                responseHeaders[key] = value;
+            }
+            else if (Array.isArray(value)) {
+                responseHeaders[key] = value.join(', ');
+            }
+        }
+        return ok({
+            data: response.body,
+            headers: responseHeaders,
+            status: response.statusCode,
+        });
+    }
+    catch (error) {
+        return err(mapErrorToHttpError(error));
+    }
+}
+/**
+ * エラーを HttpError にマッピングする
+ *
+ * @param error - キャッチしたエラー
+ * @returns 対応する HttpError
+ *
+ * @internal テスト用に export
+ */
+export function mapErrorToHttpError(error) {
+    // タイムアウトエラー
+    if (error instanceof TimeoutError) {
+        return {
+            kind: 'TIMEOUT',
+            message: `リクエストがタイムアウトしました: ${error.message}`,
+        };
+    }
+    // HTTP エラー（4xx, 5xx）
+    if (error instanceof HTTPError) {
+        const status = error.response.statusCode;
+        const statusText = getStatusText(status);
+        return {
+            kind: 'HTTP_ERROR',
+            message: `HTTP ${status} ${statusText}: ${error.message}`,
+            status,
+        };
+    }
+    // その他の got エラー（ネットワークエラー等）
+    if (error instanceof RequestError) {
+        return {
+            kind: 'NETWORK_ERROR',
+            message: `ネットワークエラーが発生しました: ${error.message}`,
+        };
+    }
+    // 不明なエラー
+    const message = error instanceof Error ? error.message : '不明なエラーが発生しました';
+    return {
+        kind: 'NETWORK_ERROR',
+        message: `リクエストエラー: ${message}`,
+    };
+}
+/**
+ * HTTP ステータスコードに対応するテキストを取得する
+ *
+ * @param status - HTTP ステータスコード
+ * @returns ステータステキスト
+ *
+ * @internal テスト用に export
+ */
+export function getStatusText(status) {
+    const statusTexts = {
+        400: 'Bad Request',
+        401: 'Unauthorized',
+        403: 'Forbidden',
+        404: 'Not Found',
+        405: 'Method Not Allowed',
+        408: 'Request Timeout',
+        429: 'Too Many Requests',
+        500: 'Internal Server Error',
+        502: 'Bad Gateway',
+        503: 'Service Unavailable',
+        504: 'Gateway Timeout',
+    };
+    return statusTexts[status] ?? 'Error';
+}
+/**
+ * ファイルをダウンロードして指定パスに保存する
+ *
+ * got ライブラリを使用してストリームでファイルをダウンロードし、
+ * 指定したパスに保存する。大きなファイルでもメモリを節約できる。
+ *
+ * @param url - ダウンロード対象の URL
+ * @param destPath - 保存先ファイルパス
+ * @param headers - リクエストヘッダー（認証ヘッダー等）
+ * @param onProgress - 進捗コールバック関数
+ * @param timeout - タイムアウト（ミリ秒）
+ * @returns 成功時は void を含む Ok、失敗時は {@link HttpError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 基本的なダウンロード
+ * const result = await httpDownload(
+ *   'https://example.com/file.pdf',
+ *   '/path/to/save/file.pdf'
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 認証付きダウンロード
+ * const result = await httpDownload(
+ *   'https://api.example.com/attachments/123',
+ *   '/path/to/save/attachment.pdf',
+ *   { Authorization: 'Basic xxx' }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 進捗コールバック付きダウンロード
+ * const result = await httpDownload(
+ *   'https://example.com/large-file.zip',
+ *   '/path/to/save/large-file.zip',
+ *   undefined,
+ *   (transferred, total) => {
+ *     if (total) {
+ *       console.log(`Progress: ${(transferred / total * 100).toFixed(1)}%`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function httpDownload(url, destPath, headers, onProgress, timeout = DEFAULT_TIMEOUT) {
+    try {
+        // 保存先ディレクトリを作成
+        await mkdir(dirname(destPath), { recursive: true });
+        // ダウンロードストリームを作成
+        const downloadStream = got.stream(url, {
+            ...(headers && { headers }),
+            retry: {
+                limit: DEFAULT_RETRY_LIMIT,
+                statusCodes: RETRY_STATUS_CODES,
+            },
+            timeout: {
+                request: timeout,
+            },
+        });
+        // 進捗追跡
+        let transferred = 0;
+        let total;
+        downloadStream.on('downloadProgress', (progress) => {
+            transferred = progress.transferred;
+            total = progress.total;
+            if (onProgress) {
+                onProgress(transferred, total);
+            }
+        });
+        // ファイル書き込みストリームを作成
+        const writeStream = createWriteStream(destPath);
+        // ストリームをパイプラインで接続
+        await pipeline(downloadStream, writeStream);
+        return ok(undefined);
+    }
+    catch (error) {
+        return err(mapErrorToHttpError(error));
+    }
+}

package/dist/ports/http/index.d.ts

@@ -0,0 +1 @@
+export { httpDownload, httpRequest } from './http-port.js';

package/dist/ports/http/index.js

@@ -0,0 +1 @@
+export { httpDownload, httpRequest } from './http-port.js';

package/dist/services/auth/auth-service.d.ts

@@ -0,0 +1,79 @@
+import { type Result } from 'neverthrow';
+import { type ZodIssue } from 'zod';
+import type { AuthError, Credentials } from '../../types/auth.js';
+/**
+ * Zod の issues 配列からエラーの種別を判定し、AuthError を生成する
+ *
+ * @t3-oss/env-core は onValidationError で ZodError ではなく issues 配列を渡す
+ *
+ * @param issues - Zod バリデーションエラーの issues 配列
+ * @returns 適切な AuthError
+ *
+ * @internal テスト用に export
+ */
+export declare function mapZodIssuesToAuthError(issues: ZodIssue[]): AuthError;
+/**
+ * 環境変数から Atlassian Cloud の認証情報を取得する
+ *
+ * @t3-oss/env-core と zod を使用して環境変数をバリデーションし、
+ * 型安全な認証情報を返す。
+ *
+ * 必要な環境変数:
+ * - `ATLASSIAN_EMAIL`: Atlassian アカウントのメールアドレス（有効なメール形式）
+ * - `ATLASSIAN_API_TOKEN`: Atlassian API トークン（空でない文字列）
+ *
+ * @returns 成功時は {@link Credentials} を含む Ok、失敗時は {@link AuthError} を含す Err
+ *
+ * @example
+ * ```typescript
+ * // 成功例
+ * process.env.ATLASSIAN_EMAIL = 'user@example.com';
+ * process.env.ATLASSIAN_API_TOKEN = 'your-api-token';
+ * const result = getCredentials();
+ * if (result.isOk()) {
+ *   console.log(result.value.email); // 'user@example.com'
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 失敗例: 環境変数未設定
+ * delete process.env.ATLASSIAN_EMAIL;
+ * const result = getCredentials();
+ * if (result.isErr()) {
+ *   console.log(result.error.kind); // 'MISSING_EMAIL'
+ * }
+ * ```
+ */
+export declare function getCredentials(): Result<Credentials, AuthError>;
+/**
+ * Basic Auth ヘッダーを生成する
+ *
+ * 環境変数から認証情報を取得し、`Authorization: Basic <base64>` 形式の
+ * ヘッダー値を生成する。email:token を base64 エンコードする。
+ *
+ * @returns 成功時は `Basic <base64>` 形式の文字列を含む Ok、失敗時は {@link AuthError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 成功例
+ * process.env.ATLASSIAN_EMAIL = 'user@example.com';
+ * process.env.ATLASSIAN_API_TOKEN = 'your-api-token';
+ * const result = getAuthHeader();
+ * if (result.isOk()) {
+ *   // result.value は 'Basic dXNlckBleGFtcGxlLmNvbTp5b3VyLWFwaS10b2tlbg=='
+ *   fetch(url, { headers: { Authorization: result.value } });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 失敗例: 環境変数未設定
+ * delete process.env.ATLASSIAN_EMAIL;
+ * const result = getAuthHeader();
+ * if (result.isErr()) {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export declare function getAuthHeader(): Result<string, AuthError>;

package/dist/services/auth/auth-service.js

@@ -0,0 +1,158 @@
+import { createEnv } from '@t3-oss/env-core';
+import { err, ok } from 'neverthrow';
+import { z } from 'zod';
+/**
+ * 環境変数スキーマの定義
+ *
+ * @t3-oss/env-core と zod を使用して環境変数をバリデーション
+ */
+const envSchema = {
+    ATLASSIAN_API_TOKEN: z.string().min(1, 'API トークンは必須です'),
+    ATLASSIAN_EMAIL: z.string().min(1, 'メールアドレスは必須です').email('有効なメールアドレスを指定してください'),
+};
+/**
+ * Zod の issues 配列からエラーの種別を判定し、AuthError を生成する
+ *
+ * @t3-oss/env-core は onValidationError で ZodError ではなく issues 配列を渡す
+ *
+ * @param issues - Zod バリデーションエラーの issues 配列
+ * @returns 適切な AuthError
+ *
+ * @internal テスト用に export
+ */
+export function mapZodIssuesToAuthError(issues) {
+    // 最初のエラーを取得
+    const firstIssue = issues[0];
+    if (!firstIssue) {
+        return {
+            kind: 'INVALID_CREDENTIALS',
+            message: '認証情報のバリデーションに失敗しました。',
+        };
+    }
+    const path = firstIssue.path[0];
+    const code = firstIssue.code;
+    // ATLASSIAN_EMAIL のエラー
+    if (path === 'ATLASSIAN_EMAIL') {
+        // 未設定または空の場合
+        if (code === 'invalid_type' || code === 'too_small') {
+            return {
+                kind: 'MISSING_EMAIL',
+                message: '環境変数 ATLASSIAN_EMAIL が設定されていません。Atlassian アカウントのメールアドレスを設定してください。',
+            };
+        }
+        // メール形式が無効
+        return {
+            kind: 'INVALID_EMAIL',
+            message: `無効なメールアドレス形式です。有効なメールアドレスを ATLASSIAN_EMAIL に設定してください。`,
+        };
+    }
+    // ATLASSIAN_API_TOKEN のエラー
+    if (path === 'ATLASSIAN_API_TOKEN') {
+        return {
+            kind: 'MISSING_TOKEN',
+            message: '環境変数 ATLASSIAN_API_TOKEN が設定されていません。Atlassian API トークンを設定してください。トークンは https://id.atlassian.com/manage-profile/security/api-tokens で作成できます。',
+        };
+    }
+    return {
+        kind: 'INVALID_CREDENTIALS',
+        message: `認証情報のバリデーションに失敗しました: ${firstIssue.message}`,
+    };
+}
+/**
+ * 環境変数から Atlassian Cloud の認証情報を取得する
+ *
+ * @t3-oss/env-core と zod を使用して環境変数をバリデーションし、
+ * 型安全な認証情報を返す。
+ *
+ * 必要な環境変数:
+ * - `ATLASSIAN_EMAIL`: Atlassian アカウントのメールアドレス（有効なメール形式）
+ * - `ATLASSIAN_API_TOKEN`: Atlassian API トークン（空でない文字列）
+ *
+ * @returns 成功時は {@link Credentials} を含む Ok、失敗時は {@link AuthError} を含す Err
+ *
+ * @example
+ * ```typescript
+ * // 成功例
+ * process.env.ATLASSIAN_EMAIL = 'user@example.com';
+ * process.env.ATLASSIAN_API_TOKEN = 'your-api-token';
+ * const result = getCredentials();
+ * if (result.isOk()) {
+ *   console.log(result.value.email); // 'user@example.com'
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 失敗例: 環境変数未設定
+ * delete process.env.ATLASSIAN_EMAIL;
+ * const result = getCredentials();
+ * if (result.isErr()) {
+ *   console.log(result.error.kind); // 'MISSING_EMAIL'
+ * }
+ * ```
+ */
+export function getCredentials() {
+    let validationError = null;
+    try {
+        const env = createEnv({
+            onValidationError: (issues) => {
+                // @t3-oss/env-core は issues 配列を渡す
+                validationError = mapZodIssuesToAuthError(issues);
+                throw new Error('Validation failed');
+            },
+            runtimeEnv: process.env,
+            server: envSchema,
+        });
+        return ok({
+            apiToken: env.ATLASSIAN_API_TOKEN,
+            email: env.ATLASSIAN_EMAIL,
+        });
+    }
+    catch {
+        if (validationError) {
+            return err(validationError);
+        }
+        // 予期しないエラー
+        return err({
+            kind: 'INVALID_CREDENTIALS',
+            message: '認証情報の取得中に予期しないエラーが発生しました。',
+        });
+    }
+}
+/**
+ * Basic Auth ヘッダーを生成する
+ *
+ * 環境変数から認証情報を取得し、`Authorization: Basic <base64>` 形式の
+ * ヘッダー値を生成する。email:token を base64 エンコードする。
+ *
+ * @returns 成功時は `Basic <base64>` 形式の文字列を含む Ok、失敗時は {@link AuthError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 成功例
+ * process.env.ATLASSIAN_EMAIL = 'user@example.com';
+ * process.env.ATLASSIAN_API_TOKEN = 'your-api-token';
+ * const result = getAuthHeader();
+ * if (result.isOk()) {
+ *   // result.value は 'Basic dXNlckBleGFtcGxlLmNvbTp5b3VyLWFwaS10b2tlbg=='
+ *   fetch(url, { headers: { Authorization: result.value } });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 失敗例: 環境変数未設定
+ * delete process.env.ATLASSIAN_EMAIL;
+ * const result = getAuthHeader();
+ * if (result.isErr()) {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export function getAuthHeader() {
+    return getCredentials().map((credentials) => {
+        const rawCredentials = `${credentials.email}:${credentials.apiToken}`;
+        const base64Encoded = Buffer.from(rawCredentials).toString('base64');
+        return `Basic ${base64Encoded}`;
+    });
+}

package/dist/services/auth/index.d.ts

@@ -0,0 +1 @@
+export { getAuthHeader, getCredentials } from './auth-service.js';

package/dist/services/auth/index.js

@@ -0,0 +1 @@
+export { getAuthHeader, getCredentials } from './auth-service.js';