@plolink/sdk 0.0.6 → 0.0.9

package/dist/modules/info-sync/index.d.cts

@@ -0,0 +1,431 @@
+import { P as PlolinkClient } from '../../client-CAjIQKPm.cjs';
+export { I as InfoSyncSignature } from '../../signature-B5LL3Zij.cjs';
+import '../../core-77EbLgbp.cjs';
+import 'axios';
+
+/**
+ * 信息同步模块类型定义
+ */
+/**
+ * 同步类型枚举
+ */
+declare enum InfoSyncType {
+    /** 内部同步 */
+    INTERNAL = "INTERNAL",
+    /** Webhook 同步 */
+    WEBHOOK = "WEBHOOK"
+}
+/**
+ * 同步状态枚举
+ */
+declare enum InfoSyncStatus {
+    /** 待同步 */
+    PENDING = "PENDING",
+    /** 同步中 */
+    SYNCING = "SYNCING",
+    /** 已完成 */
+    COMPLETED = "COMPLETED",
+    /** 同步失败 */
+    FAILED = "FAILED"
+}
+/**
+ * Webhook Payload 结构
+ *
+ * 这是外部系统接收 Webhook 时的请求体结构
+ */
+interface InfoSyncPayload {
+    /** 业务模块标识 */
+    businessModule: string;
+    /** 业务 ID */
+    businessId: string;
+    /** 业务代码 */
+    businessCode: string;
+    /** 业务数据 */
+    data: Record<string, unknown>;
+    /** 团队 ID */
+    teamId: string;
+    /** 用户 ID */
+    userId: string;
+}
+/**
+ * 历史记录项
+ */
+interface InfoSyncHistoryItem {
+    /** 时间戳（毫秒） */
+    time: number;
+    /** 状态 */
+    status: InfoSyncStatus;
+    /** 消息 */
+    message?: string;
+    /** 下次重试时间（毫秒） */
+    nextRetryTime?: number;
+}
+/**
+ * 同步记录
+ */
+interface InfoSyncRecord {
+    /** 记录 ID */
+    id: string;
+    /** 业务模块 */
+    businessModule: string;
+    /** 业务 ID */
+    businessId: string;
+    /** 业务代码 */
+    businessCode: string;
+    /** 业务数据 */
+    data: Record<string, unknown>;
+    /** 同步类型 */
+    type: InfoSyncType;
+    /** 同步状态 */
+    status: InfoSyncStatus;
+    /** Webhook URL（仅 type=WEBHOOK 时有值） */
+    webhookUrl?: string | null;
+    /** Webhook 配置 ID（仅 type=WEBHOOK 时有值） */
+    webhookConfigId?: string | null;
+    /** 历史记录 */
+    history: InfoSyncHistoryItem[];
+    /** 创建者 ID */
+    creatorId: string;
+    /** 团队 ID */
+    teamId: string;
+    /** 备注 */
+    comment?: string | null;
+    /** 创建时间（ISO 格式） */
+    createdAt: string;
+    /** 更新时间（ISO 格式） */
+    updatedAt: string;
+}
+/**
+ * Webhook 配置
+ */
+interface WebhookConfig {
+    /** 配置 ID */
+    id: string;
+    /** 团队 ID */
+    teamId: string;
+    /** 配置名称 */
+    name: string;
+    /** Webhook URL */
+    url: string;
+    /** 订阅的模块列表（空数组表示订阅所有模块） */
+    modules: string[];
+    /** 是否启用 */
+    enabled: boolean;
+    /** 创建者 ID */
+    creatorId: string;
+    /** 创建时间（ISO 格式） */
+    createdAt: string;
+    /** 更新时间（ISO 格式） */
+    updatedAt: string;
+}
+/**
+ * 创建 Webhook 配置参数
+ */
+interface CreateWebhookConfigParams {
+    /** 配置名称 */
+    name: string;
+    /** Webhook URL */
+    url: string;
+    /** 订阅的模块列表（空数组表示订阅所有模块） */
+    modules: string[];
+}
+/**
+ * 创建 Webhook 配置响应
+ */
+interface CreateWebhookConfigResponse {
+    /** 配置 ID */
+    id: string;
+    /** 密钥（仅在创建时返回一次） */
+    secretKey: string;
+}
+/**
+ * 更新 Webhook 配置参数
+ */
+interface UpdateWebhookConfigParams {
+    /** 配置名称 */
+    name?: string;
+    /** Webhook URL */
+    url?: string;
+    /** 订阅的模块列表 */
+    modules?: string[];
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * 同步记录查询参数
+ */
+interface InfoSyncQueryParams {
+    /** 业务模块（可选，用于过滤） */
+    businessModule?: string;
+    /** 同步状态（可选，用于过滤） */
+    status?: InfoSyncStatus;
+    /** 同步类型（可选，用于过滤） */
+    type?: InfoSyncType;
+    /** 页码（默认 1） */
+    page?: number;
+    /** 每页数量（默认 20） */
+    pageSize?: number;
+}
+/**
+ * 同步记录列表响应
+ */
+interface InfoSyncListResponse {
+    /** 记录列表 */
+    list: InfoSyncRecord[];
+    /** 总数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+
+/**
+ * 信息同步模块
+ *
+ * @description
+ * 提供信息同步功能，包括:
+ * - Webhook 配置管理（创建/查询/更新/删除）
+ * - 同步记录查询
+ * - 手动重试
+ * - 签名验证工具（用于验证 Webhook 请求）
+ *
+ * @example
+ * ```typescript
+ * import { PlolinkClient } from '@plolink/sdk';
+ *
+ * const client = new PlolinkClient({
+ *   token: 'your-session-id-or-api-key'
+ * });
+ *
+ * // 创建 Webhook 配置
+ * const result = await client.infoSync.createWebhookConfig({
+ *   name: 'Production Webhook',
+ *   url: 'https://example.com/webhook/plolink',
+ *   modules: ['report-writer', 'video-psych-analysis']
+ * });
+ * console.log(`SecretKey (仅展示一次): ${result.secretKey}`);
+ *
+ * // 查询同步记录
+ * const records = await client.infoSync.listSyncRecords({
+ *   businessModule: 'report-writer',
+ *   status: 'FAILED'
+ * });
+ * console.log(`找到 ${records.total} 条失败记录`);
+ * ```
+ *
+ * @module info-sync
+ */
+
+/**
+ * 信息同步模块
+ */
+declare class InfoSync {
+    private client;
+    constructor(client: PlolinkClient);
+    /**
+     * 创建 Webhook 配置
+     *
+     * @description
+     * 为当前团队创建一个新的 Webhook 配置。
+     * 返回的 secretKey 仅在创建时返回一次，请立即保存。
+     *
+     * 每个团队最多可以创建 10 个 Webhook 配置。
+     *
+     * ⚠️ 重要: secretKey 仅在创建时返回，后续无法再次获取，请妥善保存
+     *
+     * @param params - 创建参数
+     * @returns 创建结果，包含配置 ID 和密钥
+     * @throws {PlolinkError} 当参数无效、配置数量超限或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await infoSync.createWebhookConfig({
+     *   name: 'Production Webhook',
+     *   url: 'https://example.com/webhook/plolink',
+     *   modules: ['report-writer', 'video-psych-analysis']
+     * });
+     *
+     * console.log(`配置 ID: ${result.id}`);
+     * console.log(`SecretKey: ${result.secretKey}`);
+     * // 请立即保存 secretKey，后续无法再次获取
+     * ```
+     */
+    createWebhookConfig(params: CreateWebhookConfigParams): Promise<CreateWebhookConfigResponse>;
+    /**
+     * 获取 Webhook 配置列表
+     *
+     * @description
+     * 获取当前团队的所有 Webhook 配置。
+     * 注意：列表中不包含 secretKey。
+     *
+     * @returns Webhook 配置列表
+     * @throws {PlolinkError} 当权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * const configs = await infoSync.listWebhookConfigs();
+     * configs.forEach(config => {
+     *   console.log(`${config.name}: ${config.url}`);
+     *   console.log(`订阅模块: ${config.modules.join(', ')}`);
+     *   console.log(`状态: ${config.enabled ? '启用' : '禁用'}`);
+     * });
+     * ```
+     */
+    listWebhookConfigs(): Promise<WebhookConfig[]>;
+    /**
+     * 获取 Webhook 配置详情
+     *
+     * @description
+     * 获取指定 Webhook 配置的详细信息。
+     * 注意：不包含 secretKey。
+     *
+     * @param id - 配置 ID
+     * @returns Webhook 配置详情
+     * @throws {PlolinkError} 当配置不存在或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * const config = await infoSync.getWebhookConfig('config-123');
+     * console.log(`名称: ${config.name}`);
+     * console.log(`URL: ${config.url}`);
+     * console.log(`订阅模块: ${config.modules.join(', ')}`);
+     * ```
+     */
+    getWebhookConfig(id: string): Promise<WebhookConfig>;
+    /**
+     * 更新 Webhook 配置
+     *
+     * @description
+     * 更新指定 Webhook 配置的信息。
+     * 注意：不能更新 secretKey，如需更换密钥请删除后重新创建。
+     *
+     * @param id - 配置 ID
+     * @param params - 更新参数
+     * @throws {PlolinkError} 当参数无效、配置不存在或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * // 禁用配置
+     * await infoSync.updateWebhookConfig('config-123', {
+     *   enabled: false
+     * });
+     *
+     * // 更新订阅模块
+     * await infoSync.updateWebhookConfig('config-123', {
+     *   modules: ['report-writer']
+     * });
+     *
+     * // 更新 URL
+     * await infoSync.updateWebhookConfig('config-123', {
+     *   url: 'https://new-url.example.com/webhook'
+     * });
+     * ```
+     */
+    updateWebhookConfig(id: string, params: UpdateWebhookConfigParams): Promise<void>;
+    /**
+     * 删除 Webhook 配置
+     *
+     * @description
+     * 永久删除指定的 Webhook 配置（软删除）。
+     * 删除后该配置将不再接收 Webhook 通知。
+     *
+     * ⚠️ 警告: 此操作不可逆，请确认后再执行
+     *
+     * @param id - 配置 ID
+     * @throws {PlolinkError} 当配置不存在或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * await infoSync.deleteWebhookConfig('config-123');
+     * console.log('Webhook 配置已删除');
+     * ```
+     */
+    deleteWebhookConfig(id: string): Promise<void>;
+    /**
+     * 查询同步记录列表
+     *
+     * @description
+     * 查询当前团队的同步记录，支持多种过滤条件和分页。
+     *
+     * @param params - 查询参数
+     * @returns 分页的同步记录列表
+     * @throws {PlolinkError} 当参数无效或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * // 查询所有记录
+     * const result = await infoSync.listSyncRecords();
+     * console.log(`共 ${result.total} 条记录`);
+     *
+     * // 查询失败的 Webhook 同步记录
+     * const failed = await infoSync.listSyncRecords({
+     *   type: 'WEBHOOK',
+     *   status: 'FAILED'
+     * });
+     * console.log(`${failed.total} 条 Webhook 同步失败`);
+     *
+     * // 查询报告写作模块的记录
+     * const reports = await infoSync.listSyncRecords({
+     *   businessModule: 'report-writer',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     * ```
+     */
+    listSyncRecords(params?: InfoSyncQueryParams): Promise<InfoSyncListResponse>;
+    /**
+     * 获取同步记录详情
+     *
+     * @description
+     * 获取指定同步记录的详细信息，包括完整的历史记录。
+     *
+     * @param id - 记录 ID
+     * @returns 同步记录详情
+     * @throws {PlolinkError} 当记录不存在或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * const record = await infoSync.getSyncRecord('record-123');
+     * console.log(`业务模块: ${record.businessModule}`);
+     * console.log(`业务代码: ${record.businessCode}`);
+     * console.log(`状态: ${record.status}`);
+     * console.log(`历史记录:`);
+     * record.history.forEach(item => {
+     *   console.log(`  ${new Date(item.time).toLocaleString()}: ${item.status} - ${item.message || ''}`);
+     * });
+     * ```
+     */
+    getSyncRecord(id: string): Promise<InfoSyncRecord>;
+    /**
+     * 手动重试同步任务
+     *
+     * @description
+     * 手动重试失败的同步任务。
+     * 只能重试状态为 FAILED 的记录。
+     *
+     * 重试后记录状态将变为 PENDING，并重新提交到队列处理。
+     *
+     * @param id - 记录 ID
+     * @throws {PlolinkError} 当记录不存在、状态不是 FAILED 或权限不足时抛出
+     *
+     * @example
+     * ```typescript
+     * // 查询失败记录
+     * const failed = await infoSync.listSyncRecords({ status: 'FAILED' });
+     *
+     * // 重试所有失败记录
+     * for (const record of failed.list) {
+     *   try {
+     *     await infoSync.retrySyncRecord(record.id);
+     *     console.log(`已重试: ${record.id}`);
+     *   } catch (error) {
+     *     console.error(`重试失败: ${record.id}`, error);
+     *   }
+     * }
+     * ```
+     */
+    retrySyncRecord(id: string): Promise<void>;
+}
+
+export { type CreateWebhookConfigParams, type CreateWebhookConfigResponse, InfoSync, type InfoSyncHistoryItem, type InfoSyncListResponse, type InfoSyncPayload, type InfoSyncQueryParams, type InfoSyncRecord, InfoSyncStatus, InfoSyncType, type UpdateWebhookConfigParams, type WebhookConfig };