zentao-api 0.1.0 → 0.2.0-beta.1

package/src/types.ts

@@ -1,88 +0,0 @@
-import {Method} from 'axios';
-
-/**
- * 支持的禅道请求方式，影响 API 请求 URL 构建方式
- */
-export type ZentaoRequestType = 'PATH_INFO' | 'GET';
-
-/**
- * 禅道请求参数键值对
- */
-export type ZentaoRequestParamPair = any[]; // [name: string, value: string]
-
-/**
- * 禅道请求参数
- */
-export type ZentaoRequestParams =
-    | Array<ZentaoRequestParamPair>
-    | string[]
-    | string
-    | Record<string, any>;
-
-/**
- * 禅道 API 请求方式
- */
-export type ZentaoRequestMethod = Method;
-
-/**
- * 禅道 API 返回结果
- */
-export interface ZentaoApiResult {
-    /**
-     * 状态
-     *
-     * @remarks
-     * 如果为 `0` 则表示操作请求失败，如果为 `1`，表示操作请求成功
-     */
-    status: 0 | 1;
-
-    /**
-     * 服务器返回的描述结果的文本
-     */
-    msg?: any;
-
-    /**
-     * 请求结果数据
-     */
-    result?: any;
-}
-
-/**
- * 禅道 API 初始化选项
- */
-export interface ZentaoOptions {
-    /**
-     * 禅道服务器地址
-     */
-    readonly url: string;
-
-    /**
-     * 登录账号
-     */
-    readonly account: string;
-
-    /**
-     * 登录密码
-     */
-    readonly password: string;
-
-    /**
-     * 请求形式
-     */
-    readonly accessMode?: ZentaoRequestType;
-
-    /**
-     * 是否将 token 存储到本地，如果设置为 `false`，则每次创建新的 `Zentao` 实例都会在首次调用 API 之前重新获取 Token
-     */
-    readonly preserveToken?: boolean;
-
-    /**
-     * 当前 `Zentao` 实例名称
-     */
-    readonly sessionName?: string;
-
-    /**
-     * 如果设置为 `true`，则会在控制台输出详细日志
-     */
-    readonly debug?: boolean;
-}

package/src/utils.ts

@@ -1,216 +0,0 @@
-import querystring from 'querystring';
-import {ZentaoRequestParamPair, ZentaoRequestParams} from './types';
-
-/**
- * 创建一个 Date 对象
- * @param {Date|number|String} [date=null] 用于创建 Date 对象的日期时间表达值，如果留空则创建当前系统时间对象
- * @return {Date} 日期时间对象
- * @function
- */
-export const createDate = (date: Date | number | string) => {
-    if (!date) {
-        return new Date();
-    }
-    if (!(date instanceof Date)) {
-        if (typeof date === 'string') {
-            date = date.trim();
-            if (/^\d+$/.test(date)) {
-                date = Number.parseInt(date, 10);
-            }
-        }
-        if (typeof date === 'number' && date < 10000000000) {
-            date *= 1000;
-        }
-        date = new Date(date);
-    }
-    return date;
-};
-
-/**
- * 格式化日期时间值为字符串
- * @remarks
- * 所有可用的格式化参数有：
- * - `yyyy`，例如：'2018'，表示四位数字表示的年份
- * - `yy`，例如：'18'，表示两位数字表示的年份
- * - `MM`，例如：'07'，表示两位数字表示的月份，不足两位在起始用 0 填充
- * - `M`，例如：'10'，表示一位或两位数字表示的月份
- * - `dd`，例如：'05'，表示两位数字表示的日期，不足两位在起始用 0 填充
- * - `d`，例如：'5'，表示一位或两位数字表示的日期
- * - `hh`，例如：'08'，表示两位数字表示的小时，不足两位在起始用 0 填充
- * - `h`，例如：'8'，表示一位或两位数字表示的小时
- * - `mm`，例如：'3'，表示两位数字表示的分钟，不足两位在起始用 0 填充
- * - `m`，例如：'03'，表示一位或两位数字表示的分钟
- * - `ss`，例如：'5'，表示两位数字表示的秒数，不足两位在起始用 0 填充
- * - `s`，例如：'05'，表示一位或两位数字表示的秒数
- * - `S`，例如：'236'，表示毫秒数
- * - `SSS`，例如：'036'，表示毫秒数，不足3位在起始用 0 填充
- * @summary 格式化日期时间值为字符串
- * @param {Date|number|string} date 要格式化的日期时间表达值
- * @param {string} [format='yyyy-MM-dd hh:ss'] 格式化字符串
- * @return {string} 日期时间格式化文本
- * @function
- */
-export const formatDate = (
-    date: Date | number | string,
-    format: string = 'yyyy-MM-dd hh:mm'
-) => {
-    date = createDate(date);
-
-    const dateInfo: Record<string, any> = {
-        'M+': date.getMonth() + 1,
-        'd+': date.getDate(),
-        'h+': date.getHours(),
-        'H+': date.getHours() % 12,
-        'm+': date.getMinutes(),
-        's+': date.getSeconds(),
-        // 'q+': Math.floor((date.getMonth() + 3) / 3),
-        'S+': date.getMilliseconds(),
-    };
-    if (/(y+)/i.test(format)) {
-        format = format.replace(
-            RegExp.$1,
-            `${date.getFullYear()}`.substr(4 - RegExp.$1.length)
-        );
-    }
-    Object.keys(dateInfo).forEach(k => {
-        if (new RegExp(`(${k})`).test(format)) {
-            const str = `${dateInfo[k]}`;
-            format = format.replace(
-                RegExp.$1,
-                RegExp.$1.length === 1
-                    ? str
-                    : `00${str}`.substr(str.length + 2 - RegExp.$1.length)
-            );
-        }
-    });
-    return format;
-};
-
-/**
- * 格式化禅道地址
- * @param url 禅道地址
- * @returns 格式化后的禅道地址
- * @example
- * // 以下例子都返回 `http://demo.zentao.net/`
- * formatZentaoUrl('http://demo.zentao.net');
- * formatZentaoUrl('http://demo.zentao.net');
- * formatZentaoUrl('http://demo.zentao.net/index.php');
- * formatZentaoUrl('demo.zentao.net');
- */
-export function formatZentaoUrl(url: string) {
-    if (url.endsWith('/index.php')) {
-        url = url.substr(0, url.length - 9);
-    } else if (!url.endsWith('/')) {
-        url = `${url}/`;
-    }
-    if (!url.startsWith('https://') && !url.startsWith('http://')) {
-        url = `http://${url}`;
-    }
-    return url;
-}
-
-/**
- * 创建一个新的对象，仅保留给定的原始对象上给定的属性
- * @param object 给定的原始对象
- * @param fields 要保留属性名称列表
- * @returns 新的对象
- * @example
- * const obj = {a: 1, b: 2, c: 3, d: 4};
- * slimmingObject(obj, ['b', 'c']); // 返回 `{b: 2, c: 3}`
- */
-export function slimmingObject(object: any, fields: string[]): any {
-    if (!object || typeof object !== 'object' || object === null) {
-        return object;
-    }
-    let newObject: Record<string, any> = {};
-    for (const field of fields) {
-        newObject[field] = object[field];
-    }
-    return newObject;
-}
-
-/**
- * 格式化请求参数定义
- * @param params 要格式化的参数定义
- * @returns 格式化后的参数列表
- * @example
- * // 下面返回：`[['foo', 'bar'], ['hello', 'world']]`
- * normalizeRequestParams([['foo', 'bar'], ['hello', 'world']]);
- *
- * // 下面返回：`[['foo', 'bar'], ['hello', 'world']]`
- * normalizeRequestParams('foo=bar&hello=world');
- *
- * // 下面返回：`[['foo', 'bar'], ['hello', 'world']]`
- * normalizeRequestParams({foo: 'bar', hello: 'world'});
- *
- * // 下面返回：`[['', 'bar'], ['', 'world']]`
- * normalizeRequestParams(['foo', 'bar']);
- *
- * // 下面返回：`[['foo', 'bar'], ['', 'world']]`
- * normalizeRequestParams([['foo', 'bar'], 'bar']);
- */
-export function normalizeRequestParams(
-    params?: ZentaoRequestParams
-): ZentaoRequestParamPair[] {
-    let normalizedParams: ZentaoRequestParamPair[] = [];
-    if (typeof params === 'string') {
-        params = querystring.parse(params);
-    }
-    if (params && typeof params === 'object') {
-        if (Array.isArray(params)) {
-            for (const param of params) {
-                normalizedParams.push(
-                    typeof param === 'string' ? ['', param] : param
-                );
-            }
-        } else if (params as Record<string, any>) {
-            for (const key of Object.keys(params).sort()) {
-                normalizedParams.push([key, params[key]]);
-            }
-        }
-    }
-    return normalizedParams;
-}
-
-/**
- * 合并两个请求参数定义，并返回合并且格式化后的定义
- * @param params 参数定义
- * @param otherParams 要合并的其他参数定义
- * @returns 合并后的参数列表
- * @example
- * const params1 = {foo: 'bar', hello: 'world'};
- * const params2 = 'answer='42'';
- * const params3 = [['foo', 'ter'], ['say', 'hi']];
- *
- * // 以下返回 `[['foo', 'bar'], ['answer', '42']]`
- * mergeRequestParams(params1, params2);
- *
- * // 以下返回 `[['foo', ['bar', 'ter']], ['answer', '42'], ['hello', 'world'], ['say', 'hi']]`
- * mergeRequestParams(params1, params2, params3);
- */
-export function mergeRequestParams(
-    params: ZentaoRequestParams,
-    ...otherParams: ZentaoRequestParams[]
-): ZentaoRequestParamPair[] {
-    const normalizedParams = normalizeRequestParams(params);
-    for (const otherParam of otherParams) {
-        const otherNormalizedParams = normalizeRequestParams(otherParam);
-        for (const param of otherNormalizedParams) {
-            if (typeof param[0] === 'string' && param[0].length) {
-                const existsParam = normalizedParams.find(
-                    x => x[0] === param[0]
-                );
-                if (existsParam) {
-                    if (Array.isArray(existsParam[1])) {
-                        existsParam[1].push(param[1]);
-                    } else {
-                        existsParam[1] = [existsParam[1], param[1]];
-                    }
-                    continue;
-                }
-            }
-            normalizedParams.push(param);
-        }
-    }
-    return normalizedParams;
-}

package/src/zentao-config.ts

@@ -1,150 +0,0 @@
-import {ZentaoRequestType} from './types';
-
-/**
- * 禅道配置存储对象
- */
-export default class ZentaoConfig {
-    /**
-     * 禅道版本，例如："12.4.3"
-     */
-    readonly version: string;
-
-    /**
-     * 请求方式，包括 "GET" 和 "PATH_INFO"
-     */
-    readonly requestType: ZentaoRequestType;
-
-    /**
-     * 当请求方式为 PATH_INFO 时的参数连接字符，例如 "-"
-     */
-    readonly requestFix: string;
-
-    /**
-     * 当请求方式为 GET 时，模块参数名，例如 "m"
-     */
-    readonly moduleVar: string;
-
-    /**
-     * 当请求方式为 GET 时，方法参数名，例如 "f"
-     */
-    readonly methodVar: string;
-
-    /**
-     * 当请求方式为 GET 时，视图参数名，例如 "t"
-     */
-    readonly viewVar: string;
-
-    /**
-     * Session 变量名称，例如 "zentaosid"
-     */
-    readonly sessionVar: string;
-
-    /**
-     * Session 名称，例如 "zentaosid"
-     */
-    readonly sessionName: string;
-
-    /**
-     * Session ID，例如 "inge21mp04h95m8lo64tpp6h4c"
-     */
-    readonly sessionID: string;
-
-    /**
-     * Session 随机数，例如 7795
-     */
-    readonly random: number;
-
-    /**
-     * Session 过期时间，例如 1440
-     */
-    readonly expiredTime: number;
-
-    /**
-     * 服务器时间
-     */
-    readonly serverTime: number;
-
-    /**
-     * 创建时间
-     */
-    protected readonly _createTime: number;
-
-    /**
-     * Token 字符串
-     */
-    protected _token?: string;
-
-    /**
-     * 上次更新 Token 的时间
-     */
-    protected _tokenUpdateTime?: number;
-
-    /**
-     * 创建一个 ZentaoConfig 实例
-     * @param config 配置对象
-     * @example
-     * const config = new ZentaoConfig({version: 'pro9.0.3', requestType: 'PATH_INFO', requestFix: '-', moduleVar: 'm', methodVar: 'f', viewVar: 't', sessionVar: 'zentaosid', sessionName: 'zentaosid', sessionID: '6fudr187np6d82rj23srkqt1r6', random: 5337, expiredTime: '1440', serverTime: 1615098427});
-     */
-    constructor(config: Record<string, any>) {
-        this.version = config['version'];
-        this.requestType =
-            config['requestType'] === 'GET' ? 'GET' : 'PATH_INFO';
-        this.requestFix = config['requestFix'] ?? '-';
-        this.moduleVar = config['moduleVar'] ?? 'm';
-        this.methodVar = config['methodVar'] ?? 'f';
-        this.viewVar = config['viewVar'] ?? 't';
-        this.sessionVar = config['sessionVar'] ?? 'zentaosid';
-        this.sessionName = config['sessionName'] ?? 'zentaosid"';
-        this.sessionID = config['sessionID'];
-        this.random = config['random'];
-        this.serverTime = config['serverTime'];
-        this.expiredTime =
-            typeof config['expiredTime'] === 'string'
-                ? Number.parseInt(config['expiredTime'], 10)
-                : config['expiredTime'];
-        this._tokenUpdateTime = config['_tokenUpdateTime'];
-        this._token = config['_token'];
-        this._createTime = Date.now();
-    }
-
-    /**
-     * 获取 Token 字符串
-     */
-    get token(): string {
-        return this._token ?? '';
-    }
-
-    /**
-     * Token 验证字符串
-     */
-    get tokenAuth(): string {
-        return `${this?.sessionName ?? ''}=${this?.sessionID ?? ''}`;
-    }
-
-    /**
-     * 禅道主版本
-     */
-    get mainVersion(): number {
-        return Number.parseInt(this.version.split('.')[0]);
-    }
-
-    /**
-     * 将 Token 验证字符串更新为当前 Token
-     */
-    renewToken(): void {
-        this._token = this.tokenAuth;
-        this._tokenUpdateTime = Date.now();
-    }
-
-    /**
-     * 检查当前 Token 字符串是否过期
-     */
-    get isTokenExpired(): boolean {
-        if (!this._tokenUpdateTime) {
-            return true;
-        }
-        return (
-            Date.now() - this._tokenUpdateTime >= (this.expiredTime - 30) * 1000
-        );
-    }
-}

package/src/zentao-request-builder.ts

@@ -1,227 +0,0 @@
-import {Method} from 'axios';
-import {ZentaoApiResult, ZentaoRequestParams} from './types';
-import {mergeRequestParams} from './utils';
-import Zentao from './zentao';
-
-/**
- * 禅道请求构建类
- * @internal
- */
-export default class ZentaoRequestBuilder {
-    /**
-     * 禅道请求实例
-     */
-    readonly zentao: Zentao;
-
-    /**
-     * 模块名
-     */
-    readonly moduleName: string;
-
-    _methodName: string;
-    _params?: ZentaoRequestParams;
-    _data?: string | Record<string, any>;
-    _fields?: string[];
-    _resultConvertor?: (
-        remoteData: any,
-        result: ZentaoApiResult
-    ) => ZentaoApiResult;
-    _url?: string;
-    _name?: string;
-
-    /**
-     * 创建一个禅道请求构建实例
-     * @param zentao 禅道请求实例
-     * @param moduleName 方法名
-     * @param methodName 模块名
-     * @param params 请求参数
-     */
-    constructor(
-        zentao: Zentao,
-        moduleName: string,
-        methodName?: string,
-        params?: ZentaoRequestParams
-    ) {
-        this.zentao = zentao;
-        this.moduleName = moduleName;
-        this._methodName = methodName ?? 'index';
-        this._params = params;
-    }
-
-    /**
-     * 获取方法名
-     */
-    get methodName() {
-        return this._methodName;
-    }
-
-    /**
-     * 获取请求参数
-     */
-    get params() {
-        return this._params;
-    }
-
-    /**
-     * 获取请求数据
-     */
-    get data() {
-        return this._data;
-    }
-
-    /**
-     * 获取结果属性过滤列表
-     */
-    get fields() {
-        return this._fields;
-    }
-
-    /**
-     * 获取请求名称
-     */
-    get name() {
-        return this._name;
-    }
-
-    /**
-     * 获取自定义请求地址
-     */
-    get url() {
-        return this._url;
-    }
-
-    /**
-     * 获取结果转换函数
-     */
-    get resultConvertor() {
-        return this._resultConvertor;
-    }
-
-    /**
-     * 设置方法名
-     * @param name 方法名
-     * @returns 禅道请求构建实例自身
-     */
-    method(name: string): ZentaoRequestBuilder {
-        this._methodName = name;
-        return this;
-    }
-
-    /**
-     * 设置方法名，是方法 `method(name)` 的别名
-     * @param name 方法名
-     * @returns 禅道请求构建实例自身
-     * @alias method
-     */
-    f(name: string): ZentaoRequestBuilder {
-        return this.method(name);
-    }
-
-    /**
-     * 设置请求参数
-     * @param params 要设置的参数
-     * @returns 禅道请求构建实例自身
-     */
-    withParams(params: ZentaoRequestParams): ZentaoRequestBuilder {
-        this._params = params;
-        return this;
-    }
-
-    /**
-     * 追加请求参数
-     * @param params 要追加的参数
-     * @returns 禅道请求构建实例自身
-     */
-    appendParams(params: ZentaoRequestParams): ZentaoRequestBuilder {
-        if (this._params) {
-            this._params = mergeRequestParams(this._params, params);
-        } else {
-            this._params = params;
-        }
-        return this;
-    }
-
-    /**
-     * 设置请求名称
-     * @param name 名称
-     * @returns 禅道请求构建实例自身
-     */
-    named(name: string): ZentaoRequestBuilder {
-        this._name = name;
-        return this;
-    }
-
-    /**
-     * 设置结果转换函数
-     * @param converter 结果转换函数
-     * @returns 禅道请求构建实例自身
-     */
-    useConverter(
-        converter: (remoteData: any, result: ZentaoApiResult) => ZentaoApiResult
-    ): ZentaoRequestBuilder {
-        this._resultConvertor = converter;
-        return this;
-    }
-
-    /**
-     * 过滤需要返回的属性列表
-     * @param fields 设置仅返回的属性名称列表
-     * @returns 禅道请求构建实例自身
-     */
-    filterFields(
-        ...fields: Array<string | string[] | undefined>
-    ): ZentaoRequestBuilder {
-        this._fields = fields.flat().filter(x => x !== undefined) as string[];
-        return this;
-    }
-
-    /**
-     * 发起 GET 请求
-     * @returns 请求结果
-     */
-    get(): Promise<ZentaoApiResult> {
-        return this.zentao.request(this.moduleName, this._methodName, {
-            method: 'GET',
-            params: this._params,
-            data: this._data,
-            fields: this._fields,
-            resultConvertor: this._resultConvertor,
-            name: this._name,
-            url: this._url,
-        });
-    }
-
-    /**
-     * 发起 POST 请求
-     * @param data 要提交的数据
-     * @returns 请求结果
-     */
-    post(data?: string | Record<string, any>): Promise<ZentaoApiResult> {
-        return this.zentao.request(this.moduleName, this._methodName, {
-            method: 'POST',
-            params: this._params,
-            data: data ?? this._data,
-            fields: this._fields,
-            resultConvertor: this._resultConvertor,
-            name: this._name,
-            url: this._url,
-        });
-    }
-
-    /**
-     * 发起 HTTP 请求，可以指定请求方式
-     * @param method 请求方式，默认为 GET
-     * @returns 请求结果
-     */
-    request(method?: Method) {
-        return this.zentao.request(this.moduleName, this._methodName, {
-            method,
-            params: this._params,
-            data: this._data,
-            fields: this._fields,
-            resultConvertor: this._resultConvertor,
-            name: this._name,
-            url: this._url,
-        });
-    }
-}