@plolink/sdk 0.0.8 → 0.0.9

package/dist/modules/report-writer/index.cjs

@@ -0,0 +1,282 @@
+'use strict';
+
+var chunkY3UJVC2L_cjs = require('../../chunk-Y3UJVC2L.cjs');
+
+// src/modules/report-writer/index.ts
+var ReportWriter = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 创建报告
+   * 
+   * @description
+   * 创建一个新的报告任务，系统会自动加入队列进行处理。
+   * 报告生成过程是异步的，需要通过 getDetail() 方法轮询检查状态。
+   * 
+   * @param params - 创建报告参数
+   * @param params.name - 报告名称
+   * @param params.instruction - 写作指令，描述要生成的文章内容
+   * @param params.businessCode - 业务代号，用于后续处理策略分发
+   * @param params.externalId - 外部ID，关联外部业务系统
+   * @param params.materials - 参考材料数组（可选）
+   * @param params.articleLevel - 文章层级，1-3，默认 3（可选）
+   * 
+   * @returns 创建结果，包含报告ID
+   * 
+   * @throws {PlolinkError} 参数验证失败或 API 调用失败
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.reportWriter.create({
+   *   name: '2024年度总结报告',
+   *   instruction: '请根据提供的材料，撰写一份年度工作总结报告',
+   *   businessCode: 'annual-report',
+   *   externalId: '2024-001',
+   *   articleLevel: 3,
+   *   materials: [
+   *     {
+   *       type: 'text',
+   *       content: '2024年完成了10个项目，总营收增长30%...'
+   *     }
+   *   ]
+   * });
+   * console.log(`报告ID: ${result.id}`);
+   * ```
+   */
+  async create(params) {
+    this.client.logger.debug("Creating report", { params });
+    if (!params.name?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: name is required", "VALIDATION_ERROR");
+    }
+    if (!params.instruction?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: instruction is required", "VALIDATION_ERROR");
+    }
+    if (!params.businessCode?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: businessCode is required", "VALIDATION_ERROR");
+    }
+    if (!params.externalId?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: externalId is required", "VALIDATION_ERROR");
+    }
+    if (params.articleLevel !== void 0 && (params.articleLevel < 1 || params.articleLevel > 3)) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: articleLevel must be between 1 and 3", "VALIDATION_ERROR");
+    }
+    try {
+      const response = await this.client.axiosInstance.post(
+        "/api/v1/report-writer/reports",
+        params
+      );
+      this.client.logger.info("Report created successfully", { reportId: response.id });
+      return response;
+    } catch (error) {
+      this.client.logger.error("Failed to create report", { error, params });
+      throw error;
+    }
+  }
+  /**
+   * 获取报告列表
+   * 
+   * @description
+   * 分页获取报告列表，支持按状态、业务代号、关键词筛选。
+   * 
+   * @param params - 查询参数（可选）
+   * @param params.page - 页码，默认 1（可选）
+   * @param params.pageSize - 每页数量，默认 20（可选）
+   * @param params.keyword - 搜索关键词（报告名称、业务代号）（可选）
+   * @param params.status - 状态筛选（可选）
+   * @param params.businessCode - 业务代号筛选（可选）
+   * 
+   * @returns 分页列表结果
+   * 
+   * @throws {PlolinkError} API 调用失败
+   * 
+   * @example
+   * ```typescript
+   * // 获取所有报告
+   * const allReports = await client.reportWriter.list();
+   * 
+   * // 分页查询
+   * const page2 = await client.reportWriter.list({
+   *   page: 2,
+   *   pageSize: 10
+   * });
+   * 
+   * // 按状态筛选
+   * const completedReports = await client.reportWriter.list({
+   *   status: 'COMPLETED'
+   * });
+   * 
+   * // 按业务代号和关键词筛选
+   * const filtered = await client.reportWriter.list({
+   *   businessCode: 'annual-report',
+   *   keyword: '2024'
+   * });
+   * ```
+   */
+  async list(params) {
+    this.client.logger.debug("Listing reports", { params });
+    try {
+      const queryParams = {};
+      if (params?.page !== void 0) {
+        queryParams.page = params.page.toString();
+      }
+      if (params?.pageSize !== void 0) {
+        queryParams.pageSize = params.pageSize.toString();
+      }
+      if (params?.keyword) {
+        queryParams.keyword = params.keyword;
+      }
+      if (params?.status) {
+        queryParams.status = params.status;
+      }
+      if (params?.businessCode) {
+        queryParams.businessCode = params.businessCode;
+      }
+      const response = await this.client.axiosInstance.get(
+        "/api/v1/report-writer/reports",
+        { params: queryParams }
+      );
+      this.client.logger.info("Reports listed successfully", {
+        total: response.total,
+        page: response.page,
+        pageSize: response.pageSize
+      });
+      return response;
+    } catch (error) {
+      this.client.logger.error("Failed to list reports", { error, params });
+      throw error;
+    }
+  }
+  /**
+   * 获取报告详情
+   * 
+   * @description
+   * 获取单个报告的完整详情，包括文章风格、结构化内容和生成状态。
+   * 可用于轮询检查报告生成进度。
+   * 
+   * @param id - 报告ID
+   * 
+   * @returns 报告详情
+   * 
+   * @throws {PlolinkError} 报告不存在或 API 调用失败
+   * 
+   * @example
+   * ```typescript
+   * // 获取报告详情
+   * const detail = await client.reportWriter.getDetail('report-123');
+   * console.log(`状态: ${detail.status}`);
+   * 
+   * // 轮询检查状态
+   * let report = await client.reportWriter.getDetail('report-123');
+   * while (report.status !== 'COMPLETED' && report.status !== 'FAILED') {
+   *   await new Promise(resolve => setTimeout(resolve, 5000)); // 等待5秒
+   *   report = await client.reportWriter.getDetail('report-123');
+   *   console.log(`当前状态: ${report.status}`);
+   * }
+   * 
+   * if (report.status === 'COMPLETED') {
+   *   console.log('报告生成完成');
+   * } else {
+   *   console.error('报告生成失败:', report.errorMessage);
+   * }
+   * ```
+   */
+  async getDetail(id) {
+    this.client.logger.debug("Getting report detail", { id });
+    if (!id?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: id is required", "VALIDATION_ERROR");
+    }
+    try {
+      const response = await this.client.axiosInstance.get(
+        `/api/v1/report-writer/reports/${id}`
+      );
+      this.client.logger.info("Report detail retrieved", {
+        id: response.id,
+        status: response.status
+      });
+      return response;
+    } catch (error) {
+      this.client.logger.error("Failed to get report detail", { error, id });
+      throw error;
+    }
+  }
+  /**
+   * 删除报告
+   * 
+   * @description
+   * 软删除指定报告。已删除的报告无法恢复。
+   * 
+   * @param id - 报告ID
+   * 
+   * @returns Promise<void>
+   * 
+   * @throws {PlolinkError} 报告不存在或 API 调用失败
+   * 
+   * @example
+   * ```typescript
+   * await client.reportWriter.delete('report-123');
+   * console.log('报告已删除');
+   * ```
+   */
+  async delete(id) {
+    this.client.logger.debug("Deleting report", { id });
+    if (!id?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: id is required", "VALIDATION_ERROR");
+    }
+    try {
+      await this.client.axiosInstance.delete(
+        `/api/v1/report-writer/reports/${id}`
+      );
+      this.client.logger.info("Report deleted successfully", { id });
+    } catch (error) {
+      this.client.logger.error("Failed to delete report", { error, id });
+      throw error;
+    }
+  }
+  /**
+   * 获取 Markdown 格式
+   * 
+   * @description
+   * 将报告内容渲染为 Markdown 格式。
+   * 只有状态为 COMPLETED 的报告才能导出 Markdown。
+   * 
+   * @param id - 报告ID
+   * 
+   * @returns Markdown 内容
+   * 
+   * @throws {PlolinkError} 报告不存在、未完成或 API 调用失败
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.reportWriter.getMarkdown('report-123');
+   * console.log(result.markdown);
+   * 
+   * // 保存为文件
+   * const fs = require('fs');
+   * fs.writeFileSync('report.md', result.markdown, 'utf-8');
+   * ```
+   */
+  async getMarkdown(id) {
+    this.client.logger.debug("Getting report markdown", { id });
+    if (!id?.trim()) {
+      throw new chunkY3UJVC2L_cjs.PlolinkError("Parameter validation failed: id is required", "VALIDATION_ERROR");
+    }
+    try {
+      const response = await this.client.axiosInstance.get(
+        `/api/v1/report-writer/reports/${id}/markdown`
+      );
+      this.client.logger.info("Report markdown retrieved", {
+        id,
+        markdownLength: response.markdown.length
+      });
+      return response;
+    } catch (error) {
+      this.client.logger.error("Failed to get report markdown", { error, id });
+      throw error;
+    }
+  }
+};
+
+exports.ReportWriter = ReportWriter;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/modules/report-writer/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/report-writer/index.ts"],"names":["PlolinkError"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Report Writer 模块\n * \n * @description\n * 提供 AI 自动报告写作功能，支持：\n * - 创建报告任务\n * - 查询报告列表和详情\n * - 删除报告\n * - 导出 Markdown 格式\n * \n * @example\n * ```typescript\n * import { PlolinkClient } from '@plolink/sdk';\n * \n * const client = new PlolinkClient({\n *   token: 'sk-your-api-key'\n * });\n * \n * // 创建报告\n * const createResult = await client.reportWriter.create({\n *   name: '2024年度总结报告',\n *   instruction: '请根据提供的材料，撰写一份年度工作总结报告',\n *   businessCode: 'annual-report',\n *   externalId: '2024-001',\n *   articleLevel: 3,\n *   materials: [\n *     {\n *       type: 'text',\n *       content: '2024年完成了10个项目，总营收增长30%...'\n *     }\n *   ]\n * });\n * console.log(`报告创建成功: ${createResult.id}`);\n * \n * // 查询报告详情（轮询检查状态）\n * let detail = await client.reportWriter.getDetail(createResult.id);\n * while (detail.status !== 'COMPLETED' && detail.status !== 'FAILED') {\n *   await new Promise(resolve => setTimeout(resolve, 5000));\n *   detail = await client.reportWriter.getDetail(createResult.id);\n *   console.log(`当前状态: ${detail.status}`);\n * }\n * \n * // 获取 Markdown 格式\n * if (detail.status === 'COMPLETED') {\n *   const markdown = await client.reportWriter.getMarkdown(createResult.id);\n *   console.log('报告内容:', markdown.markdown);\n * }\n * ```\n * \n * @module report-writer\n */\n\nimport { PlolinkClient } from '../../core/client';\nimport { PlolinkError } from '../../core/error';\nimport type {\n  CreateReportParams,\n  CreateReportResponse,\n  ListReportsParams,\n  ListReportsResponse,\n  ReportDetail,\n  GetMarkdownResponse,\n} from '../../types/report-writer';\n\nexport type {\n  ReportStatus,\n  MaterialType,\n  MaterialItem,\n  MaterialsSummary,\n  ArticleStyle,\n  ReviewSuggestion,\n  ArticleNode,\n  CreateReportParams,\n  CreateReportResponse,\n  ListReportsParams,\n  ReportSummary,\n  ListReportsResponse,\n  ReportDetail,\n  GetMarkdownResponse,\n  ReportWebhookData,\n} from '../../types/report-writer';\n\n/**\n * Report Writer 模块类\n * \n * @description\n * 提供 AI 报告写作相关功能的封装，包括创建报告、查询状态、导出结果等。\n * \n * 报告生成流程：\n * 1. 调用 create() 创建报告，返回 reportId\n * 2. 后端异步处理，经历多个阶段（STYLE_GENERATING → ... → COMPLETED）\n * 3. 使用 getDetail() 轮询检查状态\n * 4. 完成后调用 getMarkdown() 获取最终结果\n * \n * Webhook 通知：\n * - REPORT_COMPLETED - 报告生成完成\n * - REPORT_FAILED - 报告生成失败\n */\nexport class ReportWriter {\n  private client: PlolinkClient;\n\n  constructor(client: PlolinkClient) {\n    this.client = client;\n  }\n\n  /**\n   * 创建报告\n   * \n   * @description\n   * 创建一个新的报告任务，系统会自动加入队列进行处理。\n   * 报告生成过程是异步的，需要通过 getDetail() 方法轮询检查状态。\n   * \n   * @param params - 创建报告参数\n   * @param params.name - 报告名称\n   * @param params.instruction - 写作指令，描述要生成的文章内容\n   * @param params.businessCode - 业务代号，用于后续处理策略分发\n   * @param params.externalId - 外部ID，关联外部业务系统\n   * @param params.materials - 参考材料数组（可选）\n   * @param params.articleLevel - 文章层级，1-3，默认 3（可选）\n   * \n   * @returns 创建结果，包含报告ID\n   * \n   * @throws {PlolinkError} 参数验证失败或 API 调用失败\n   * \n   * @example\n   * ```typescript\n   * const result = await client.reportWriter.create({\n   *   name: '2024年度总结报告',\n   *   instruction: '请根据提供的材料，撰写一份年度工作总结报告',\n   *   businessCode: 'annual-report',\n   *   externalId: '2024-001',\n   *   articleLevel: 3,\n   *   materials: [\n   *     {\n   *       type: 'text',\n   *       content: '2024年完成了10个项目，总营收增长30%...'\n   *     }\n   *   ]\n   * });\n   * console.log(`报告ID: ${result.id}`);\n   * ```\n   */\n  public async create(params: CreateReportParams): Promise<CreateReportResponse> {\n    this.client.logger.debug('Creating report', { params });\n\n    // 参数验证\n    if (!params.name?.trim()) {\n      throw new PlolinkError('Parameter validation failed: name is required', 'VALIDATION_ERROR');\n    }\n    if (!params.instruction?.trim()) {\n      throw new PlolinkError('Parameter validation failed: instruction is required', 'VALIDATION_ERROR');\n    }\n    if (!params.businessCode?.trim()) {\n      throw new PlolinkError('Parameter validation failed: businessCode is required', 'VALIDATION_ERROR');\n    }\n    if (!params.externalId?.trim()) {\n      throw new PlolinkError('Parameter validation failed: externalId is required', 'VALIDATION_ERROR');\n    }\n    if (params.articleLevel !== undefined && (params.articleLevel < 1 || params.articleLevel > 3)) {\n      throw new PlolinkError('Parameter validation failed: articleLevel must be between 1 and 3', 'VALIDATION_ERROR');\n    }\n\n    try {\n      const response = await this.client.axiosInstance.post<CreateReportResponse>(\n        '/api/v1/report-writer/reports',\n        params\n      );\n\n      this.client.logger.info('Report created successfully', { reportId: response.id });\n      return response;\n    } catch (error) {\n      this.client.logger.error('Failed to create report', { error, params });\n      throw error;\n    }\n  }\n\n  /**\n   * 获取报告列表\n   * \n   * @description\n   * 分页获取报告列表，支持按状态、业务代号、关键词筛选。\n   * \n   * @param params - 查询参数（可选）\n   * @param params.page - 页码，默认 1（可选）\n   * @param params.pageSize - 每页数量，默认 20（可选）\n   * @param params.keyword - 搜索关键词（报告名称、业务代号）（可选）\n   * @param params.status - 状态筛选（可选）\n   * @param params.businessCode - 业务代号筛选（可选）\n   * \n   * @returns 分页列表结果\n   * \n   * @throws {PlolinkError} API 调用失败\n   * \n   * @example\n   * ```typescript\n   * // 获取所有报告\n   * const allReports = await client.reportWriter.list();\n   * \n   * // 分页查询\n   * const page2 = await client.reportWriter.list({\n   *   page: 2,\n   *   pageSize: 10\n   * });\n   * \n   * // 按状态筛选\n   * const completedReports = await client.reportWriter.list({\n   *   status: 'COMPLETED'\n   * });\n   * \n   * // 按业务代号和关键词筛选\n   * const filtered = await client.reportWriter.list({\n   *   businessCode: 'annual-report',\n   *   keyword: '2024'\n   * });\n   * ```\n   */\n  public async list(params?: ListReportsParams): Promise<ListReportsResponse> {\n    this.client.logger.debug('Listing reports', { params });\n\n    try {\n      const queryParams: Record<string, string> = {};\n      \n      if (params?.page !== undefined) {\n        queryParams.page = params.page.toString();\n      }\n      if (params?.pageSize !== undefined) {\n        queryParams.pageSize = params.pageSize.toString();\n      }\n      if (params?.keyword) {\n        queryParams.keyword = params.keyword;\n      }\n      if (params?.status) {\n        queryParams.status = params.status;\n      }\n      if (params?.businessCode) {\n        queryParams.businessCode = params.businessCode;\n      }\n\n      const response = await this.client.axiosInstance.get<ListReportsResponse>(\n        '/api/v1/report-writer/reports',\n        { params: queryParams }\n      );\n\n      this.client.logger.info('Reports listed successfully', { \n        total: response.total,\n        page: response.page,\n        pageSize: response.pageSize\n      });\n      return response;\n    } catch (error) {\n      this.client.logger.error('Failed to list reports', { error, params });\n      throw error;\n    }\n  }\n\n  /**\n   * 获取报告详情\n   * \n   * @description\n   * 获取单个报告的完整详情，包括文章风格、结构化内容和生成状态。\n   * 可用于轮询检查报告生成进度。\n   * \n   * @param id - 报告ID\n   * \n   * @returns 报告详情\n   * \n   * @throws {PlolinkError} 报告不存在或 API 调用失败\n   * \n   * @example\n   * ```typescript\n   * // 获取报告详情\n   * const detail = await client.reportWriter.getDetail('report-123');\n   * console.log(`状态: ${detail.status}`);\n   * \n   * // 轮询检查状态\n   * let report = await client.reportWriter.getDetail('report-123');\n   * while (report.status !== 'COMPLETED' && report.status !== 'FAILED') {\n   *   await new Promise(resolve => setTimeout(resolve, 5000)); // 等待5秒\n   *   report = await client.reportWriter.getDetail('report-123');\n   *   console.log(`当前状态: ${report.status}`);\n   * }\n   * \n   * if (report.status === 'COMPLETED') {\n   *   console.log('报告生成完成');\n   * } else {\n   *   console.error('报告生成失败:', report.errorMessage);\n   * }\n   * ```\n   */\n  public async getDetail(id: string): Promise<ReportDetail> {\n    this.client.logger.debug('Getting report detail', { id });\n\n    if (!id?.trim()) {\n      throw new PlolinkError('Parameter validation failed: id is required', 'VALIDATION_ERROR');\n    }\n\n    try {\n      const response = await this.client.axiosInstance.get<ReportDetail>(\n        `/api/v1/report-writer/reports/${id}`\n      );\n\n      this.client.logger.info('Report detail retrieved', { \n        id: response.id,\n        status: response.status\n      });\n      return response;\n    } catch (error) {\n      this.client.logger.error('Failed to get report detail', { error, id });\n      throw error;\n    }\n  }\n\n  /**\n   * 删除报告\n   * \n   * @description\n   * 软删除指定报告。已删除的报告无法恢复。\n   * \n   * @param id - 报告ID\n   * \n   * @returns Promise<void>\n   * \n   * @throws {PlolinkError} 报告不存在或 API 调用失败\n   * \n   * @example\n   * ```typescript\n   * await client.reportWriter.delete('report-123');\n   * console.log('报告已删除');\n   * ```\n   */\n  public async delete(id: string): Promise<void> {\n    this.client.logger.debug('Deleting report', { id });\n\n    if (!id?.trim()) {\n      throw new PlolinkError('Parameter validation failed: id is required', 'VALIDATION_ERROR');\n    }\n\n    try {\n      await this.client.axiosInstance.delete<{ message: string }>(\n        `/api/v1/report-writer/reports/${id}`\n      );\n\n      this.client.logger.info('Report deleted successfully', { id });\n    } catch (error) {\n      this.client.logger.error('Failed to delete report', { error, id });\n      throw error;\n    }\n  }\n\n  /**\n   * 获取 Markdown 格式\n   * \n   * @description\n   * 将报告内容渲染为 Markdown 格式。\n   * 只有状态为 COMPLETED 的报告才能导出 Markdown。\n   * \n   * @param id - 报告ID\n   * \n   * @returns Markdown 内容\n   * \n   * @throws {PlolinkError} 报告不存在、未完成或 API 调用失败\n   * \n   * @example\n   * ```typescript\n   * const result = await client.reportWriter.getMarkdown('report-123');\n   * console.log(result.markdown);\n   * \n   * // 保存为文件\n   * const fs = require('fs');\n   * fs.writeFileSync('report.md', result.markdown, 'utf-8');\n   * ```\n   */\n  public async getMarkdown(id: string): Promise<GetMarkdownResponse> {\n    this.client.logger.debug('Getting report markdown', { id });\n\n    if (!id?.trim()) {\n      throw new PlolinkError('Parameter validation failed: id is required', 'VALIDATION_ERROR');\n    }\n\n    try {\n      const response = await this.client.axiosInstance.get<GetMarkdownResponse>(\n        `/api/v1/report-writer/reports/${id}/markdown`\n      );\n\n      this.client.logger.info('Report markdown retrieved', { \n        id,\n        markdownLength: response.markdown.length\n      });\n      return response;\n    } catch (error) {\n      this.client.logger.error('Failed to get report markdown', { error, id });\n      throw error;\n    }\n  }\n}\n"]}