@hangox/pm-cli 1.1.6 → 1.2.0

package/dist/api.d.ts

@@ -0,0 +1,462 @@
+/**
+ * API 响应类型
+ */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    message?: string;
+    msg?: string;
+    api_error_msg?: string;
+    post_error_msg?: string;
+}
+/**
+ * 工时条目
+ */
+interface TimeEntry {
+    id: number;
+    project: {
+        id: number;
+        name: string;
+    };
+    issue?: {
+        id: number;
+    };
+    user: {
+        id: number;
+        name: string;
+    };
+    activity: {
+        id: number;
+        name: string;
+    };
+    hours: number;
+    comments: string;
+    spent_on: string;
+    created_on: string;
+    updated_on: string;
+}
+/**
+ * 工时查询参数
+ */
+interface TimeEntryQueryParams {
+    token: string;
+    host: string;
+    project: string;
+    from_date?: string;
+    to_date?: string;
+    user_id?: number;
+    activity_id?: number;
+    member_of_group_id?: number;
+    tracker_id?: number;
+    version_id?: number;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * 问题详情
+ */
+interface Issue {
+    id: number;
+    project: {
+        id: number;
+        name: string;
+    };
+    tracker: {
+        id: number;
+        name: string;
+    };
+    status: {
+        id: number;
+        name: string;
+    };
+    priority: {
+        id: number;
+        name: string;
+    };
+    author: {
+        id: number;
+        name: string;
+    };
+    assigned_to?: {
+        id: number;
+        name: string;
+    };
+    parent?: {
+        id: number;
+    };
+    subject: string;
+    description: string;
+    start_date?: string;
+    due_date?: string;
+    done_ratio: number;
+    estimated_hours?: number;
+    spent_hours?: number;
+    created_on: string;
+    updated_on: string;
+    closed_on?: string;
+}
+/**
+ * 带子单的问题详情（递归结构）
+ */
+interface IssueWithChildren extends Issue {
+    children?: IssueWithChildren[];
+    level: number;
+}
+/**
+ * 用户信息
+ */
+interface User {
+    id: number;
+    login: string;
+    firstname: string;
+    lastname: string;
+    mail: string;
+    created_on: string;
+    last_login_on?: string;
+}
+/**
+ * 项目信息
+ */
+interface Project {
+    id: number;
+    name: string;
+    identifier: string;
+    description: string;
+    status: number;
+    is_public: boolean;
+    created_on: string;
+    updated_on: string;
+}
+/**
+ * CLI 配置
+ */
+interface CliConfig {
+    default: {
+        token?: string;
+        host?: string;
+        project?: string;
+        userId?: string;
+        userName?: string;
+        userMail?: string;
+    };
+    profiles: Record<string, {
+        host?: string;
+        project?: string;
+        token?: string;
+        userId?: string;
+        userName?: string;
+        userMail?: string;
+    }>;
+}
+/**
+ * 凭据信息（合并后的配置）
+ */
+interface Credentials {
+    token: string;
+    host: string;
+    project: string;
+}
+/**
+ * PM 链接解析结果
+ */
+interface PmLinkInfo {
+    host: string;
+    issueId: string;
+}
+/**
+ * 同步子单结果
+ */
+interface SyncResult {
+    /** 源单子任务总数 */
+    totalTasks: number;
+    /** 成功创建的数量 */
+    totalCreated: number;
+    /** 跳过的数量（同名任务） */
+    totalSkipped: number;
+    /** 失败的数量 */
+    totalFailed: number;
+    /** 创建成功的详情 */
+    created: Array<{
+        sourceId: number;
+        newId: number;
+        subject: string;
+        parentId: number;
+    }>;
+    /** 跳过的详情 */
+    skipped: Array<{
+        sourceId: number;
+        subject: string;
+        reason: string;
+    }>;
+    /** 失败的详情 */
+    failed: Array<{
+        sourceId: number;
+        subject: string;
+        error: string;
+    }>;
+}
+/**
+ * 批量创建结果
+ */
+interface BatchCreateResult {
+    /** 成功创建的数量 */
+    totalCreated: number;
+    /** 失败的数量 */
+    totalFailed: number;
+    /** 任务总数 */
+    totalTasks: number;
+    /** 总工时（天） */
+    totalEstimatedHours: number;
+    /** 创建成功的详情 */
+    created: Array<{
+        newId: number;
+        subject: string;
+        parentId: number;
+        estimatedHours?: number;
+    }>;
+    /** 失败的详情 */
+    failed: Array<{
+        subject: string;
+        parentId: number;
+        error: string;
+    }>;
+}
+
+/**
+ * 问题服务
+ */
+declare class IssueService {
+    /**
+     * 获取问题详情
+     */
+    getIssue(token: string, host: string, project: string, issueId: number, includeChildren?: boolean, includeRelations?: boolean): Promise<ApiResponse<Issue>>;
+    /**
+     * 创建问题
+     */
+    createIssue(params: Record<string, unknown>): Promise<ApiResponse<Issue>>;
+    /**
+     * 更新问题
+     */
+    updateIssue(params: Record<string, unknown>): Promise<ApiResponse<Issue>>;
+    /**
+     * 获取问题附件
+     */
+    getIssueAttachments(token: string, host: string, project: string, issueId: number): Promise<ApiResponse<unknown>>;
+    /**
+     * 获取问题字段选项
+     */
+    getIssueFieldOptions(token: string, host: string, project: string): Promise<ApiResponse<unknown>>;
+    /**
+     * 自定义查询
+     */
+    customQuery(token: string, host: string, project: string, queryId: number, limit?: number, offset?: number): Promise<ApiResponse<Issue[]>>;
+    /**
+     * V6 过滤器查询
+     */
+    filterQueryV6(token: string, host: string, project: string, mode: 'normal' | 'simple' | 'advanced', filterParams: Record<string, unknown>): Promise<ApiResponse<Issue[]>>;
+    /**
+     * 递归获取问题及其子单（包含完整详情）
+     * @param depth 递归深度，默认 10
+     * @param currentLevel 当前层级（内部使用）
+     *
+     * 实现逻辑：
+     * 1. 调用 getIssue(includeChildren=true) 获取当前问题详情
+     * 2. API 返回的 children 字段只包含简略信息（status 是字符串，缺少 assigned_to 等）
+     * 3. 从 children 中提取子单 ID，递归调用 getIssue 获取每个子单的完整详情
+     * 4. 用完整详情替换原始的简略 children
+     */
+    getIssueWithChildren(token: string, host: string, project: string, issueId: number, depth?: number, currentLevel?: number): Promise<ApiResponse<IssueWithChildren>>;
+    /**
+     * 获取直接子单的 ID 列表
+     */
+    getDirectChildren(token: string, host: string, project: string, parentId: number): Promise<ApiResponse<number[]>>;
+    /**
+     * 查询子任务（按根任务和负责人过滤）
+     * 使用两步查询：先过滤获取 ID 列表，再批量获取详情
+     */
+    queryChildren(token: string, host: string, project: string, rootId: number, assignedToId?: number, perPage?: number): Promise<ApiResponse<unknown>>;
+    /**
+     * 批量获取多个问题详情
+     * @param issueIds 问题 ID 数组
+     * @param options 可选参数
+     * @returns 返回所有问题的详情数组（包含成功和失败的结果）
+     */
+    getMultipleIssues(token: string, host: string, project: string, issueIds: number[], options?: {
+        includeChildren?: boolean;
+        includeRelations?: boolean;
+        depth?: number;
+    }): Promise<ApiResponse<Array<{
+        id: number;
+        success: boolean;
+        data?: Issue | IssueWithChildren;
+        error?: string;
+    }>>>;
+    /**
+     * 同步子单：从源父单复制子单到目标父单
+     * @param sourceParentId 源父单 ID
+     * @param targetParentId 目标父单 ID
+     * @param assignedToMail 新子单的指派人邮箱
+     * @param options 选项
+     */
+    syncChildIssues(token: string, host: string, project: string, sourceParentId: number, targetParentId: number, assignedToMail: string, options?: {
+        dryRun?: boolean;
+        depth?: number;
+        skipExisting?: boolean;
+    }): Promise<ApiResponse<SyncResult>>;
+    /**
+     * 计算所有子任务数量（递归）
+     */
+    private countAllChildren;
+    /**
+     * 收集所有任务名称（递归）
+     */
+    private collectAllTaskNames;
+    /**
+     * 递归同步子单
+     */
+    private syncChildrenRecursive;
+    /**
+     * 从 Markdown 批量创建子单
+     * @param parentId 父单 ID
+     * @param markdown Markdown 文本
+     * @param assignedToMail 指派人邮箱
+     * @param options 选项
+     */
+    batchCreateFromMarkdown(token: string, host: string, project: string, parentId: number, markdown: string, assignedToMail: string, options?: {
+        dryRun?: boolean;
+        interval?: number;
+        extraCustomFields?: Record<number, string>;
+    }): Promise<ApiResponse<BatchCreateResult>>;
+    /**
+     * 递归批量创建子单
+     */
+    private batchCreateRecursive;
+}
+declare const issueService: IssueService;
+
+/**
+ * 工时条目服务
+ */
+declare class TimeEntryService {
+    /**
+     * 查询工时条目
+     */
+    queryTimeEntries(params: TimeEntryQueryParams): Promise<ApiResponse<TimeEntry[]>>;
+    /**
+     * 获取工时条目选项（活动类型列表等）
+     * 使用 time_entry GET API
+     */
+    getTimeEntryOptions(token: string, host: string, project: string, issueId?: number): Promise<ApiResponse<unknown>>;
+    /**
+     * 创建工时条目
+     * 使用 time_entry API（非 save_time_entry）
+     */
+    createTimeEntry(params: Record<string, unknown>): Promise<ApiResponse<TimeEntry>>;
+    /**
+     * 更新工时条目
+     */
+    updateTimeEntry(params: Record<string, unknown>): Promise<ApiResponse<TimeEntry>>;
+    /**
+     * 删除工时条目
+     */
+    deleteTimeEntry(token: string, host: string, timeEntryId: number): Promise<ApiResponse<unknown>>;
+}
+declare const timeEntryService: TimeEntryService;
+
+/**
+ * 用户服务
+ */
+declare class UserService {
+    /**
+     * 测试连接 (通过获取项目列表来验证)
+     */
+    testConnection(token: string, host: string, project: string): Promise<ApiResponse<unknown>>;
+    /**
+     * 获取项目列表
+     */
+    getProjects(token: string, host: string): Promise<ApiResponse<Project[]>>;
+    /**
+     * 获取项目用户
+     */
+    getProjectUsers(token: string, host: string, project: string): Promise<ApiResponse<User[]>>;
+    /**
+     * 获取主机信息
+     */
+    getHostInfo(token: string, host: string): Promise<ApiResponse<unknown>>;
+}
+declare const userService: UserService;
+
+/**
+ * 网易易协作 API 客户端
+ */
+declare class ApiClient {
+    private static readonly BASE_URL;
+    private static readonly DEFAULT_TIMEOUT;
+    /**
+     * 发送 GET 请求
+     */
+    get<T>(endpoint: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * 发送 POST 请求
+     */
+    post<T>(endpoint: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * 处理错误
+     */
+    private handleError;
+    /**
+     * 构建查询字符串
+     */
+    private buildQueryString;
+    /**
+     * 构建表单数据
+     */
+    private buildFormData;
+}
+declare const apiClient: ApiClient;
+
+/**
+ * 合并凭据（按优先级）
+ * 优先级: 命令行参数 > 环境变量 > profile 配置 > 默认配置
+ */
+declare function resolveCredentials(options: {
+    token?: string;
+    host?: string;
+    project?: string;
+    profile?: string;
+    config?: string;
+}): Partial<Credentials>;
+/**
+ * 验证凭据是否完整
+ */
+declare function validateCredentials(creds: Partial<Credentials>, requiredFields?: (keyof Credentials)[]): {
+    valid: boolean;
+    missing: string[];
+};
+
+/**
+ * 解析 PM 链接
+ * 支持两种格式:
+ * 1. 路径格式: https://a19.pm.netease.com/v6/issues/213112
+ * 2. 查询参数格式: https://a19.pm.netease.com/v6/issues?project_id=7&issue_id=254946
+ *
+ * @param url PM 链接
+ * @returns 解析结果，包含 host 和 issueId；如果解析失败返回 null
+ */
+declare function parsePmLink(url: string): PmLinkInfo | null;
+/**
+ * 检查字符串是否是 PM 链接
+ */
+declare function isPmLink(str: string): boolean;
+/**
+ * 从文本中提取所有 PM 链接
+ */
+declare function extractPmLinks(text: string): PmLinkInfo[];
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * 设置日志级别（供第三方调用时按需开启）
+ */
+declare function setLogLevel(level: LogLevel): void;
+
+export { ApiClient, type ApiResponse, type BatchCreateResult, type CliConfig, type Credentials, type Issue, IssueService, type IssueWithChildren, type LogLevel, type PmLinkInfo, type Project, type SyncResult, type TimeEntry, type TimeEntryQueryParams, TimeEntryService, type User, UserService, apiClient, extractPmLinks, isPmLink, issueService, parsePmLink, resolveCredentials, setLogLevel, timeEntryService, userService, validateCredentials };