atl-fetch 1.0.0

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

@@ -0,0 +1,354 @@
+import { err, ok } from 'neverthrow';
+import { z } from 'zod';
+import { httpDownload, httpRequest } from '../../ports/http/http-port.js';
+import { getAuthHeader } from '../auth/auth-service.js';
+/**
+ * Jira Cloud API のベース URL を構築する
+ *
+ * @param organization - 組織名（.atlassian.net のサブドメイン）
+ * @returns Jira Cloud API のベース URL
+ */
+function getJiraApiBaseUrl(organization) {
+    return `https://${organization}.atlassian.net/rest/api/3`;
+}
+/**
+ * ADF (Atlassian Document Format) からプレーンテキストを抽出する
+ *
+ * Jira Cloud API v3 は説明やコメントを ADF 形式で返す。
+ * この関数は ADF ドキュメントからテキストコンテンツを抽出する。
+ *
+ * @param adf - ADF ドキュメント
+ * @returns プレーンテキスト
+ *
+ * @internal テスト用に export
+ */
+export function extractTextFromAdf(adf) {
+    if (!adf || typeof adf !== 'object') {
+        return '';
+    }
+    const doc = adf;
+    if (doc.type === 'text' && typeof doc.text === 'string') {
+        return doc.text;
+    }
+    if (Array.isArray(doc.content)) {
+        return doc.content.map((child) => extractTextFromAdf(child)).join('');
+    }
+    return '';
+}
+/**
+ * Jira API レスポンスのコメントスキーマ
+ */
+const jiraApiCommentSchema = z.object({
+    author: z.object({
+        displayName: z.string(),
+    }),
+    body: z.unknown(),
+    created: z.string(),
+    id: z.string(),
+    updated: z.string(),
+});
+/**
+ * Jira API レスポンスの添付ファイルスキーマ
+ */
+const jiraApiAttachmentSchema = z.object({
+    content: z.string(),
+    filename: z.string(),
+    id: z.string(),
+    mimeType: z.string(),
+    size: z.number(),
+});
+/**
+ * Jira API レスポンスの変更履歴アイテムスキーマ
+ */
+const jiraApiChangelogItemSchema = z.object({
+    field: z.string(),
+    fromString: z.string().nullable(),
+    toString: z.string().nullable(),
+});
+/**
+ * Jira API レスポンスの変更履歴エントリスキーマ
+ */
+const jiraApiChangelogEntrySchema = z.object({
+    author: z.object({
+        displayName: z.string(),
+    }),
+    created: z.string(),
+    id: z.string(),
+    items: z.array(jiraApiChangelogItemSchema),
+});
+/**
+ * Jira API レスポンスのスキーマ
+ */
+const jiraApiResponseSchema = z.object({
+    changelog: z
+        .object({
+        histories: z.array(jiraApiChangelogEntrySchema),
+    })
+        .optional(),
+    fields: z.object({
+        attachment: z.array(jiraApiAttachmentSchema).optional(),
+        comment: z
+            .object({
+            comments: z.array(jiraApiCommentSchema),
+            total: z.number(),
+        })
+            .optional(),
+        description: z.unknown().nullable(),
+        summary: z.string(),
+    }),
+    key: z.string(),
+});
+/**
+ * API レスポンスを JiraComment に変換する
+ *
+ * @param apiComment - API レスポンスのコメント
+ * @returns JiraComment
+ */
+function mapApiCommentToJiraComment(apiComment) {
+    return {
+        author: apiComment.author.displayName,
+        body: extractTextFromAdf(apiComment.body),
+        created: apiComment.created,
+        id: apiComment.id,
+        updated: apiComment.updated,
+    };
+}
+/**
+ * API レスポンスを JiraAttachment に変換する
+ *
+ * @param apiAttachment - API レスポンスの添付ファイル
+ * @returns JiraAttachment
+ */
+function mapApiAttachmentToJiraAttachment(apiAttachment) {
+    return {
+        contentUrl: apiAttachment.content,
+        filename: apiAttachment.filename,
+        id: apiAttachment.id,
+        mimeType: apiAttachment.mimeType,
+        size: apiAttachment.size,
+    };
+}
+/**
+ * API レスポンスを JiraChangelogEntry に変換する
+ *
+ * @param apiEntry - API レスポンスの変更履歴エントリ
+ * @returns JiraChangelogEntry
+ */
+function mapApiChangelogEntryToJiraChangelogEntry(apiEntry) {
+    return {
+        author: apiEntry.author.displayName,
+        created: apiEntry.created,
+        id: apiEntry.id,
+        items: apiEntry.items.map((item) => ({
+            field: item.field,
+            fromString: item.fromString,
+            toString: item.toString,
+        })),
+    };
+}
+/**
+ * HTTP エラーを JiraError に変換する
+ *
+ * @param status - HTTP ステータスコード
+ * @param message - エラーメッセージ
+ * @returns JiraError
+ *
+ * @internal テスト用に export
+ */
+export function mapHttpStatusToJiraError(status, message) {
+    switch (status) {
+        case 401:
+            return {
+                kind: 'AUTH_FAILED',
+                message: '認証に失敗しました。API トークンとメールアドレスを確認してください。',
+            };
+        case 403:
+            return {
+                kind: 'FORBIDDEN',
+                message: 'この Issue へのアクセス権限がありません。権限を確認してください。',
+            };
+        case 404:
+            return {
+                kind: 'NOT_FOUND',
+                message: '指定された Issue が見つかりません。Issue キーを確認してください。',
+            };
+        default:
+            return {
+                kind: 'NETWORK_ERROR',
+                message: `API リクエストに失敗しました: ${message}`,
+            };
+    }
+}
+/**
+ * Jira Issue を取得する
+ *
+ * Jira Cloud API を使用して Issue の基本情報（タイトル、説明、コメント、
+ * 変更履歴、添付ファイル）を取得する。
+ *
+ * @param organization - 組織名（.atlassian.net のサブドメイン）
+ * @param issueKey - Issue キー（例: PROJECT-123）
+ * @returns 成功時は {@link JiraIssue} を含む Ok、失敗時は {@link JiraError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 基本的な使用例
+ * const result = await fetchJiraIssue('my-company', 'PROJECT-123');
+ * if (result.isOk()) {
+ *   console.log(result.value.summary);
+ *   console.log(result.value.description);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // エラーハンドリング
+ * const result = await fetchJiraIssue('my-company', 'NOTEXIST-999');
+ * if (result.isErr()) {
+ *   if (result.error.kind === 'NOT_FOUND') {
+ *     console.log('Issue が見つかりません');
+ *   }
+ * }
+ * ```
+ */
+export async function fetchJiraIssue(organization, issueKey) {
+    // 認証ヘッダーを取得
+    const authHeaderResult = getAuthHeader();
+    if (authHeaderResult.isErr()) {
+        return err({
+            kind: 'AUTH_FAILED',
+            message: authHeaderResult.error.message,
+        });
+    }
+    const authHeader = authHeaderResult.value;
+    const baseUrl = getJiraApiBaseUrl(organization);
+    const url = `${baseUrl}/issue/${issueKey}?expand=changelog`;
+    // API リクエストを実行
+    const response = await httpRequest(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: authHeader,
+        },
+    });
+    if (response.isErr()) {
+        const error = response.error;
+        if (error.kind === 'HTTP_ERROR') {
+            return err(mapHttpStatusToJiraError(error.status, error.message));
+        }
+        return err({
+            kind: 'NETWORK_ERROR',
+            message: error.message,
+        });
+    }
+    // レスポンスをパース
+    const parseResult = jiraApiResponseSchema.safeParse(response.value.data);
+    if (!parseResult.success) {
+        return err({
+            kind: 'PARSE_ERROR',
+            message: `API レスポンスのパースに失敗しました: ${parseResult.error.message}`,
+        });
+    }
+    const apiResponse = parseResult.data;
+    // JiraIssue に変換
+    const issue = {
+        attachments: (apiResponse.fields.attachment ?? []).map(mapApiAttachmentToJiraAttachment),
+        changelog: (apiResponse.changelog?.histories ?? []).map(mapApiChangelogEntryToJiraChangelogEntry),
+        comments: (apiResponse.fields.comment?.comments ?? []).map(mapApiCommentToJiraComment),
+        description: apiResponse.fields.description ? extractTextFromAdf(apiResponse.fields.description) : null,
+        key: apiResponse.key,
+        summary: apiResponse.fields.summary,
+    };
+    return ok(issue);
+}
+/**
+ * HTTP エラーステータスをダウンロード用の JiraError に変換する
+ *
+ * @param status - HTTP ステータスコード
+ * @returns JiraError
+ *
+ * @internal テスト用に export
+ */
+export function mapHttpStatusToDownloadError(status) {
+    switch (status) {
+        case 401:
+            return {
+                kind: 'AUTH_FAILED',
+                message: '認証に失敗しました。API トークンとメールアドレスを確認してください。',
+            };
+        case 403:
+            return {
+                kind: 'FORBIDDEN',
+                message: 'この添付ファイルへのアクセス権限がありません。権限を確認してください。',
+            };
+        case 404:
+            return {
+                kind: 'NOT_FOUND',
+                message: '指定された添付ファイルが見つかりません。',
+            };
+        default:
+            return {
+                kind: 'NETWORK_ERROR',
+                message: `添付ファイルのダウンロードに失敗しました（HTTP ${status}）`,
+            };
+    }
+}
+/**
+ * Jira 添付ファイルをダウンロードする
+ *
+ * Jira Cloud API を使用して添付ファイルを指定パスにダウンロードする。
+ *
+ * @param attachment - ダウンロード対象の添付ファイル情報
+ * @param destPath - 保存先ファイルパス
+ * @param onProgress - 進捗コールバック関数（オプション）
+ * @returns 成功時は void を含む Ok、失敗時は {@link JiraError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 基本的な使用例
+ * const attachment = issue.attachments[0];
+ * const result = await downloadJiraAttachment(attachment, '/path/to/save/file.png');
+ * if (result.isOk()) {
+ *   console.log('ダウンロード完了');
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 進捗表示付き
+ * const result = await downloadJiraAttachment(
+ *   attachment,
+ *   '/path/to/save/file.png',
+ *   (transferred, total) => {
+ *     if (total) {
+ *       console.log(`Progress: ${(transferred / total * 100).toFixed(1)}%`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function downloadJiraAttachment(attachment, destPath, onProgress) {
+    // 認証ヘッダーを取得
+    const authHeaderResult = getAuthHeader();
+    if (authHeaderResult.isErr()) {
+        return err({
+            kind: 'AUTH_FAILED',
+            message: authHeaderResult.error.message,
+        });
+    }
+    const authHeader = authHeaderResult.value;
+    // ファイルをダウンロード
+    const downloadResult = await httpDownload(attachment.contentUrl, destPath, {
+        Accept: '*/*',
+        Authorization: authHeader,
+    }, onProgress);
+    if (downloadResult.isErr()) {
+        const error = downloadResult.error;
+        if (error.kind === 'HTTP_ERROR') {
+            return err(mapHttpStatusToDownloadError(error.status));
+        }
+        return err({
+            kind: 'NETWORK_ERROR',
+            message: error.message,
+        });
+    }
+    return ok(undefined);
+}

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

@@ -0,0 +1,4 @@
+/**
+ * 出力サービスのエントリーポイント
+ */
+export { formatConfluencePage, formatJiraIssue, showProgress, writeToFile } from './output-service.js';

package/dist/services/output/index.js

@@ -0,0 +1,4 @@
+/**
+ * 出力サービスのエントリーポイント
+ */
+export { formatConfluencePage, formatJiraIssue, showProgress, writeToFile } from './output-service.js';

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

@@ -0,0 +1,67 @@
+/**
+ * 出力サービス
+ *
+ * 取得したデータを指定形式（JSON/Markdown/YAML）で出力する。
+ */
+import { type Result } from 'neverthrow';
+import type { ConfluencePage } from '../../types/confluence.js';
+import type { JiraIssue } from '../../types/jira.js';
+import type { OutputError, OutputFormat } from '../../types/output.js';
+/**
+ * Jira Issue を指定形式でフォーマットする
+ *
+ * @param issue Jira Issue
+ * @param options 出力オプション
+ * @returns フォーマット済み文字列
+ */
+export declare const formatJiraIssue: (issue: JiraIssue, options: {
+    format: OutputFormat;
+}) => Result<string, OutputError>;
+/**
+ * Confluence ページを指定形式でフォーマットする
+ *
+ * @param page Confluence ページ
+ * @param options 出力オプション
+ * @returns フォーマット済み文字列
+ */
+export declare const formatConfluencePage: (page: ConfluencePage, options: {
+    format: OutputFormat;
+}) => Result<string, OutputError>;
+/**
+ * ダウンロード進捗を標準エラー出力に表示する
+ *
+ * 添付ファイルダウンロード時に進捗を表示する。
+ * 同じ行で更新するためにキャリッジリターン（\r）を使用し、
+ * 完了時（current === total）には改行を追加する。
+ *
+ * @param message 進捗メッセージ
+ * @param current 現在の進捗位置
+ * @param total 合計数
+ *
+ * @example
+ * ```typescript
+ * // ダウンロード進捗を表示
+ * showProgress('Downloading', 1, 3);  // "\rDownloading: 1/3 (33%)"
+ * showProgress('Downloading', 2, 3);  // "\rDownloading: 2/3 (67%)"
+ * showProgress('Downloading', 3, 3);  // "\rDownloading: 3/3 (100%)\n"
+ * ```
+ */
+export declare const showProgress: (message: string, current: number, total: number) => void;
+/**
+ * コンテンツをファイルに書き込む
+ *
+ * 親ディレクトリを作成してから、指定されたパスにコンテンツを書き込む。
+ *
+ * @param content 書き込むコンテンツ
+ * @param outputPath 出力先ファイルパス
+ * @returns 成功時は Ok(void)、失敗時は Err(OutputError)
+ *
+ * @example
+ * ```typescript
+ * const result = await writeToFile('{"key": "value"}', '/path/to/output.json');
+ * if (result.isOk()) {
+ *   console.log('ファイルを書き込みました');
+ * }
+ * ```
+ */
+export declare const writeToFile: (content: string, outputPath: string) => Promise<Result<void, OutputError>>;

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

@@ -0,0 +1,228 @@
+/**
+ * 出力サービス
+ *
+ * 取得したデータを指定形式（JSON/Markdown/YAML）で出力する。
+ */
+import { dirname } from 'node:path';
+import { err, ok } from 'neverthrow';
+import { stringify as yamlStringify } from 'yaml';
+import { ensureDir, writeFileContent } from '../../ports/file/file-port.js';
+/**
+ * Jira Issue を Markdown 形式にフォーマットする
+ *
+ * @param issue Jira Issue
+ * @returns Markdown 文字列
+ */
+const formatJiraIssueAsMarkdown = (issue) => {
+    const lines = [];
+    // Title
+    lines.push(`# ${issue.key}: ${issue.summary}`);
+    lines.push('');
+    // Description
+    lines.push('## Description');
+    lines.push('');
+    lines.push(issue.description ?? 'N/A');
+    lines.push('');
+    // Comments
+    lines.push('## Comments');
+    lines.push('');
+    if (issue.comments.length === 0) {
+        lines.push('No comments');
+    }
+    else {
+        for (const comment of issue.comments) {
+            lines.push(`### ${comment.author} (${comment.created})`);
+            lines.push('');
+            lines.push(comment.body);
+            lines.push('');
+        }
+    }
+    // Changelog
+    lines.push('## Changelog');
+    lines.push('');
+    if (issue.changelog.length === 0) {
+        lines.push('No changes');
+    }
+    else {
+        for (const entry of issue.changelog) {
+            lines.push(`### ${entry.author} (${entry.created})`);
+            lines.push('');
+            for (const item of entry.items) {
+                const from = item.fromString ?? '(none)';
+                const to = item.toString ?? '(none)';
+                lines.push(`- **${item.field}**: ${from} → ${to}`);
+            }
+            lines.push('');
+        }
+    }
+    // Attachments
+    lines.push('## Attachments');
+    lines.push('');
+    if (issue.attachments.length === 0) {
+        lines.push('No attachments');
+    }
+    else {
+        for (const attachment of issue.attachments) {
+            const sizeKB = (attachment.size / 1024).toFixed(1);
+            lines.push(`- **${attachment.filename}** (${attachment.mimeType}, ${sizeKB} KB)`);
+        }
+    }
+    return lines.join('\n');
+};
+/**
+ * Jira Issue を指定形式でフォーマットする
+ *
+ * @param issue Jira Issue
+ * @param options 出力オプション
+ * @returns フォーマット済み文字列
+ */
+export const formatJiraIssue = (issue, options) => {
+    if (options.format === 'json') {
+        return ok(JSON.stringify(issue, null, 2));
+    }
+    if (options.format === 'markdown') {
+        return ok(formatJiraIssueAsMarkdown(issue));
+    }
+    // YAML 形式
+    return ok(yamlStringify(issue));
+};
+/**
+ * HTML タグを除去してプレーンテキストを抽出する
+ *
+ * @param html HTML 文字列
+ * @returns プレーンテキスト
+ */
+const stripHtmlTags = (html) => {
+    return html.replaceAll(/<[^>]*>/g, '');
+};
+/**
+ * Confluence ページを Markdown 形式にフォーマットする
+ *
+ * @param page Confluence ページ
+ * @returns Markdown 文字列
+ */
+const formatConfluencePageAsMarkdown = (page) => {
+    const lines = [];
+    // Title
+    lines.push(`# ${page.title}`);
+    lines.push('');
+    // Metadata
+    lines.push(`**Page ID**: ${page.id}`);
+    lines.push(`**Space**: ${page.spaceKey}`);
+    lines.push(`**Version**: ${String(page.currentVersion)}`);
+    lines.push('');
+    // Content
+    lines.push('## Content');
+    lines.push('');
+    lines.push(stripHtmlTags(page.body));
+    lines.push('');
+    // Version History
+    lines.push('## Version History');
+    lines.push('');
+    if (page.versions.length === 0) {
+        lines.push('No version history');
+    }
+    else {
+        for (const version of page.versions) {
+            const message = version.message !== null ? `: ${version.message}` : '';
+            lines.push(`### Version ${String(version.number)} by ${version.by} (${version.when})${message}`);
+            lines.push('');
+        }
+    }
+    // Attachments
+    lines.push('## Attachments');
+    lines.push('');
+    if (page.attachments.length === 0) {
+        lines.push('No attachments');
+    }
+    else {
+        for (const attachment of page.attachments) {
+            const sizeKB = (attachment.fileSize / 1024).toFixed(1);
+            lines.push(`- **${attachment.title}** (${attachment.mediaType}, ${sizeKB} KB)`);
+        }
+    }
+    return lines.join('\n');
+};
+/**
+ * Confluence ページを指定形式でフォーマットする
+ *
+ * @param page Confluence ページ
+ * @param options 出力オプション
+ * @returns フォーマット済み文字列
+ */
+export const formatConfluencePage = (page, options) => {
+    if (options.format === 'json') {
+        return ok(JSON.stringify(page, null, 2));
+    }
+    if (options.format === 'markdown') {
+        return ok(formatConfluencePageAsMarkdown(page));
+    }
+    // YAML 形式
+    return ok(yamlStringify(page));
+};
+/**
+ * ダウンロード進捗を標準エラー出力に表示する
+ *
+ * 添付ファイルダウンロード時に進捗を表示する。
+ * 同じ行で更新するためにキャリッジリターン（\r）を使用し、
+ * 完了時（current === total）には改行を追加する。
+ *
+ * @param message 進捗メッセージ
+ * @param current 現在の進捗位置
+ * @param total 合計数
+ *
+ * @example
+ * ```typescript
+ * // ダウンロード進捗を表示
+ * showProgress('Downloading', 1, 3);  // "\rDownloading: 1/3 (33%)"
+ * showProgress('Downloading', 2, 3);  // "\rDownloading: 2/3 (67%)"
+ * showProgress('Downloading', 3, 3);  // "\rDownloading: 3/3 (100%)\n"
+ * ```
+ */
+export const showProgress = (message, current, total) => {
+    // パーセンテージを計算（total が 0 の場合は 0%）
+    const percentage = total === 0 ? 0 : Math.min(100, Math.floor((current / total) * 100));
+    // 進捗メッセージを構築
+    const progressMessage = `\r${message}: ${String(current)}/${String(total)} (${String(percentage)}%)`;
+    // 完了時は改行を追加
+    const output = current >= total && total > 0 ? `${progressMessage}\n` : progressMessage;
+    // 標準エラー出力に書き込む
+    process.stderr.write(output);
+};
+/**
+ * コンテンツをファイルに書き込む
+ *
+ * 親ディレクトリを作成してから、指定されたパスにコンテンツを書き込む。
+ *
+ * @param content 書き込むコンテンツ
+ * @param outputPath 出力先ファイルパス
+ * @returns 成功時は Ok(void)、失敗時は Err(OutputError)
+ *
+ * @example
+ * ```typescript
+ * const result = await writeToFile('{"key": "value"}', '/path/to/output.json');
+ * if (result.isOk()) {
+ *   console.log('ファイルを書き込みました');
+ * }
+ * ```
+ */
+export const writeToFile = async (content, outputPath) => {
+    const parentDir = dirname(outputPath);
+    // 親ディレクトリを作成
+    const ensureDirResult = await ensureDir(parentDir);
+    if (ensureDirResult.isErr()) {
+        return err({
+            kind: 'WRITE_FAILED',
+            message: `ディレクトリの作成に失敗しました: ${parentDir} - ${ensureDirResult.error.message}`,
+        });
+    }
+    // ファイルに書き込む
+    const writeResult = await writeFileContent(outputPath, content);
+    if (writeResult.isErr()) {
+        return err({
+            kind: 'WRITE_FAILED',
+            message: `ファイルの書き込みに失敗しました: ${outputPath} - ${writeResult.error.message}`,
+        });
+    }
+    return ok(undefined);
+};

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

@@ -0,0 +1,6 @@
+/**
+ * ストレージサービス
+ *
+ * Jira Issue / Confluence ページをディレクトリ構造で保存する。
+ */
+export { saveConfluencePage, saveConfluenceVersions, saveJiraIssue } from './storage-service.js';

package/dist/services/storage/index.js

@@ -0,0 +1,6 @@
+/**
+ * ストレージサービス
+ *
+ * Jira Issue / Confluence ページをディレクトリ構造で保存する。
+ */
+export { saveConfluencePage, saveConfluenceVersions, saveJiraIssue } from './storage-service.js';