@hed-hog/finance 0.0.350 → 0.0.353

package/src/mcp-tools/finance-installments.mcp-tools.ts

@@ -0,0 +1,560 @@
+import { McpContext, McpTool } from '@hed-hog/core';
+import { BadRequestException, Injectable } from '@nestjs/common';
+import { FinanceService } from '../finance.service';
+
+@Injectable()
+export class FinanceInstallmentsMcpTools {
+  constructor(private readonly financeService: FinanceService) {}
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.list',
+    description: 'Lists accounts payable installments.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        pageSize: { type: 'number', description: 'Items per page (default: 20)' },
+        status: { type: 'string', description: 'Status filter' },
+        from: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        to: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+      },
+    },
+    readOnly: true,
+  })
+  async listAccountsPayableInstallments(args: Record<string, any>, _context: McpContext): Promise<any> {
+    const { page, pageSize, status, from, to } = args;
+    return this.financeService.listAccountsPayableInstallments(
+      { page, pageSize } as any,
+      status,
+      { from, to },
+    );
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.get',
+    description: 'Returns accounts payable installment details.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+    readOnly: true,
+  })
+  async getAccountsPayableInstallment(args: { id: number }, context: McpContext): Promise<any> {
+    return this.financeService.getAccountsPayableInstallment(args.id, context.locale);
+  }
+
+  @McpTool({
+    name: 'finance.titles.settlements-history.get',
+    description: 'Returns settlement history for a financial title.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Title ID' },
+      },
+      required: ['id'],
+    },
+    readOnly: true,
+  })
+  async getTitleSettlementsHistory(args: { id: number }, context: McpContext): Promise<any> {
+    return this.financeService.getTitleSettlementsHistory(args.id, context.locale);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.create',
+    description: 'Creates an accounts payable title/installment. For recurring titles, use recurrence_rule instead of installments array.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        person_id: { type: 'number', description: 'Supplier/person ID' },
+        document_number: { type: 'string', description: 'Document/invoice number' },
+        total_amount: { type: 'number', description: 'Total amount (or amount per period for recurring titles)' },
+        due_date: { type: 'string', description: 'Due date / first occurrence date (YYYY-MM-DD)' },
+        finance_category_id: { type: 'number', description: 'Category ID' },
+        cost_center_id: { type: 'number', description: 'Cost center ID' },
+        payment_channel: { type: 'string', description: 'Payment channel' },
+        description: { type: 'string', description: 'Description' },
+        competence_date: { type: 'string', description: 'Competence date (YYYY-MM-DD)' },
+        installments: {
+          type: 'array',
+          description: 'Installments array (for non-recurring split titles)',
+          items: {
+            type: 'object',
+            properties: {
+              due_date: { type: 'string' },
+              amount: { type: 'number' },
+            },
+          },
+        },
+        recurrence_rule: {
+          type: 'object',
+          description: 'Recurrence rule. When provided, creates a recurring title (same amount each period) instead of a split installment title.',
+          properties: {
+            frequency: {
+              type: 'string',
+              enum: ['weekly', 'biweekly', 'monthly', 'bimonthly', 'quarterly', 'semiannual', 'annual'],
+              description: 'Repetition frequency (default: monthly)',
+            },
+            end_date: { type: 'string', description: 'End date (YYYY-MM-DD) — stop generating after this date' },
+            max_occurrences: { type: 'number', description: 'Maximum number of repetitions' },
+          },
+          required: ['frequency'],
+        },
+      },
+      required: ['person_id', 'document_number', 'total_amount', 'due_date'],
+    },
+  })
+  async createAccountsPayableTitle(args: Record<string, any>, context: McpContext): Promise<any> {
+    return this.financeService.createAccountsPayableTitle(args as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.update',
+    description: 'Updates an accounts payable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async updateAccountsPayableTitle(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.updateAccountsPayableTitle(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.approve',
+    description: 'Approves an accounts payable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async approveAccountsPayableTitle(args: { id: number }, context: McpContext): Promise<any> {
+    return this.financeService.approveAccountsPayableTitle(args.id, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.reject',
+    description: 'Rejects an accounts payable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        reason: { type: 'string', description: 'Rejection reason' },
+      },
+      required: ['id'],
+    },
+  })
+  async rejectAccountsPayableTitle(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.rejectAccountsPayableTitle(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.cancel',
+    description: 'Cancels an accounts payable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        reason: { type: 'string', description: 'Cancellation reason' },
+      },
+      required: ['id'],
+    },
+  })
+  async cancelAccountsPayableTitle(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.cancelAccountsPayableTitle(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.settle',
+    description: 'Settles an accounts payable installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async settleAccountsPayableInstallment(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.settleAccountsPayableInstallment(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.settlements.reverse',
+    description: 'Reverses a settlement for accounts payable installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        settlementId: { type: 'number', description: 'Settlement ID' },
+      },
+      required: ['id', 'settlementId'],
+    },
+  })
+  async reverseAccountsPayableSettlement(
+    args: { id: number; settlementId: number; [key: string]: any },
+    context: McpContext,
+  ): Promise<any> {
+    const { id, settlementId, ...data } = args;
+    return this.financeService.reverseAccountsPayableSettlement(id, settlementId, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.settlements.reverse',
+    description: 'Reverses settlement by settlement ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Settlement ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async reverseSettlement(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.reverseSettlementById(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.bank-reconciliations.delete',
+    description: 'Unreconciles a bank reconciliation by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Bank reconciliation ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async unreconcileBankReconciliation(args: { id: number }, context: McpContext): Promise<any> {
+    return this.financeService.unreconcileBankReconciliation(args.id, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.tags.update',
+    description: 'Updates tags for an accounts payable installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        tag_ids: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Tag IDs',
+        },
+      },
+      required: ['id'],
+    },
+  })
+  async updateAccountsPayableInstallmentTags(
+    args: { id: number; tag_ids?: number[] },
+    context: McpContext,
+  ): Promise<any> {
+    return this.financeService.updateAccountsPayableInstallmentTags(
+      args.id,
+      args.tag_ids || [],
+      context.locale,
+    );
+  }
+
+  @McpTool({
+    name: 'finance.accounts-payable.installments.extract-from-file',
+    description: 'Extracts payable title data from a base64 file payload using AI.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fileBase64: { type: 'string', description: 'Base64-encoded file content' },
+        fileName: { type: 'string', description: 'Original file name' },
+        mimeType: { type: 'string', description: 'File MIME type' },
+        file_id: { type: 'number', description: 'Existing file ID (optional)' },
+      },
+    },
+  })
+  async extractAccountsPayableInfoFromFile(
+    args: { fileBase64?: string; fileName?: string; mimeType?: string; file_id?: number },
+    _context: McpContext,
+  ): Promise<any> {
+    const file = this.tryToMulterFile(args.fileBase64, args.fileName, args.mimeType);
+    return this.financeService.getAgentExtractInfoFromFile(file, args.file_id);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.list',
+    description: 'Lists accounts receivable installments.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        pageSize: { type: 'number', description: 'Items per page (default: 20)' },
+        status: { type: 'string', description: 'Status filter' },
+        from: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        to: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+      },
+    },
+    readOnly: true,
+  })
+  async listAccountsReceivableInstallments(args: Record<string, any>, _context: McpContext): Promise<any> {
+    const { page, pageSize, status, from, to } = args;
+    return this.financeService.listAccountsReceivableInstallments(
+      { page, pageSize } as any,
+      status,
+      { from, to },
+    );
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.get',
+    description: 'Returns accounts receivable installment details.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+    readOnly: true,
+  })
+  async getAccountsReceivableInstallment(args: { id: number }, context: McpContext): Promise<any> {
+    return this.financeService.getAccountsReceivableInstallment(args.id, context.locale);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.create',
+    description: 'Creates an accounts receivable title/installment. For recurring titles, use recurrence_rule instead of installments array.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        person_id: { type: 'number', description: 'Client/person ID' },
+        document_number: { type: 'string', description: 'Document/invoice number' },
+        total_amount: { type: 'number', description: 'Total amount (or amount per period for recurring titles)' },
+        due_date: { type: 'string', description: 'Due date / first occurrence date (YYYY-MM-DD)' },
+        finance_category_id: { type: 'number', description: 'Category ID' },
+        cost_center_id: { type: 'number', description: 'Cost center ID' },
+        payment_channel: { type: 'string', description: 'Payment channel' },
+        description: { type: 'string', description: 'Description' },
+        competence_date: { type: 'string', description: 'Competence date (YYYY-MM-DD)' },
+        installments: {
+          type: 'array',
+          description: 'Installments array (for non-recurring split titles)',
+          items: {
+            type: 'object',
+            properties: {
+              due_date: { type: 'string' },
+              amount: { type: 'number' },
+            },
+          },
+        },
+        recurrence_rule: {
+          type: 'object',
+          description: 'Recurrence rule. When provided, creates a recurring title (same amount each period) instead of a split installment title.',
+          properties: {
+            frequency: {
+              type: 'string',
+              enum: ['weekly', 'biweekly', 'monthly', 'bimonthly', 'quarterly', 'semiannual', 'annual'],
+              description: 'Repetition frequency (default: monthly)',
+            },
+            end_date: { type: 'string', description: 'End date (YYYY-MM-DD) — stop generating after this date' },
+            max_occurrences: { type: 'number', description: 'Maximum number of repetitions' },
+          },
+          required: ['frequency'],
+        },
+      },
+      required: ['person_id', 'document_number', 'total_amount', 'due_date'],
+    },
+  })
+  async createAccountsReceivableTitle(args: Record<string, any>, context: McpContext): Promise<any> {
+    return this.financeService.createAccountsReceivableTitle(args as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.update',
+    description: 'Updates an accounts receivable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async updateAccountsReceivableTitle(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.updateAccountsReceivableTitle(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.approve',
+    description: 'Approves an accounts receivable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async approveAccountsReceivableTitle(args: { id: number }, context: McpContext): Promise<any> {
+    return this.financeService.approveAccountsReceivableTitle(args.id, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.cancel',
+    description: 'Cancels an accounts receivable title/installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        reason: { type: 'string', description: 'Cancellation reason' },
+      },
+      required: ['id'],
+    },
+  })
+  async cancelAccountsReceivableTitle(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.cancelAccountsReceivableTitle(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.settle',
+    description: 'Settles an accounts receivable installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async settleAccountsReceivableInstallment(args: { id: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { id, ...data } = args;
+    return this.financeService.settleAccountsReceivableInstallment(id, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.settlements.reverse',
+    description: 'Reverses a settlement for accounts receivable installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        settlementId: { type: 'number', description: 'Settlement ID' },
+      },
+      required: ['id', 'settlementId'],
+    },
+  })
+  async reverseAccountsReceivableSettlement(
+    args: { id: number; settlementId: number; [key: string]: any },
+    context: McpContext,
+  ): Promise<any> {
+    const { id, settlementId, ...data } = args;
+    return this.financeService.reverseAccountsReceivableSettlement(id, settlementId, data as any, context.locale, context.userId);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.tags.update',
+    description: 'Updates tags for an accounts receivable installment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Installment ID' },
+        tag_ids: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Tag IDs',
+        },
+      },
+      required: ['id'],
+    },
+  })
+  async updateAccountsReceivableInstallmentTags(
+    args: { id: number; tag_ids?: number[] },
+    context: McpContext,
+  ): Promise<any> {
+    return this.financeService.updateAccountsReceivableInstallmentTags(
+      args.id,
+      args.tag_ids || [],
+      context.locale,
+    );
+  }
+
+  @McpTool({
+    name: 'finance.tags.create',
+    description: 'Creates a finance tag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Tag name' },
+        color: { type: 'string', description: 'Tag color' },
+      },
+      required: ['name'],
+    },
+  })
+  async createTag(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.financeService.createTag(args as any);
+  }
+
+  @McpTool({
+    name: 'finance.accounts-receivable.installments.extract-from-file',
+    description: 'Extracts receivable title data from a base64 file payload using AI.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fileBase64: { type: 'string', description: 'Base64-encoded file content' },
+        fileName: { type: 'string', description: 'Original file name' },
+        mimeType: { type: 'string', description: 'File MIME type' },
+        file_id: { type: 'number', description: 'Existing file ID (optional)' },
+      },
+    },
+  })
+  async extractAccountsReceivableInfoFromFile(
+    args: { fileBase64?: string; fileName?: string; mimeType?: string; file_id?: number },
+    _context: McpContext,
+  ): Promise<any> {
+    const file = this.tryToMulterFile(args.fileBase64, args.fileName, args.mimeType);
+    return this.financeService.getAgentExtractInfoFromFile(file, args.file_id, 'receivable');
+  }
+
+  private tryToMulterFile(
+    fileBase64?: string,
+    fileName?: string,
+    mimeType?: string,
+  ): MulterFile | undefined {
+    if (!fileBase64 && !fileName && !mimeType) {
+      return undefined;
+    }
+
+    if (!fileBase64 || !fileName || !mimeType) {
+      throw new BadRequestException('fileBase64, fileName and mimeType must be provided together');
+    }
+
+    const buffer = Buffer.from(fileBase64, 'base64');
+
+    if (!buffer.length) {
+      throw new BadRequestException('Invalid fileBase64 payload');
+    }
+
+    return {
+      fieldname: 'file',
+      originalname: fileName,
+      encoding: '7bit',
+      mimetype: mimeType,
+      size: buffer.length,
+      destination: '',
+      filename: fileName,
+      path: '',
+      buffer,
+    };
+  }
+}

package/src/mcp-tools/finance-period-close.mcp-tools.ts

@@ -0,0 +1,53 @@
+import { McpContext, McpTool } from '@hed-hog/core';
+import { Injectable } from '@nestjs/common';
+import { FinanceService } from '../finance.service';
+
+@Injectable()
+export class FinancePeriodCloseMcpTools {
+  constructor(private readonly financeService: FinanceService) {}
+
+  @McpTool({
+    name: 'finance.period-close.list',
+    description: 'Lists period close records with filters and pagination.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        pageSize: { type: 'number', description: 'Items per page (default: 20)' },
+        search: { type: 'string', description: 'Search term' },
+        status: { type: 'string', description: 'Status filter' },
+        user: { type: 'string', description: 'User filter' },
+        from: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        to: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+      },
+    },
+    readOnly: true,
+  })
+  async list(args: Record<string, any>, _context: McpContext): Promise<any> {
+    const { page, pageSize, search, status, user, from, to } = args;
+    return this.financeService.listPeriodClose({ page, pageSize } as any, {
+      search,
+      status,
+      user,
+      from,
+      to,
+    });
+  }
+
+  @McpTool({
+    name: 'finance.period-close.create',
+    description: 'Creates a period close record.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        period_start: { type: 'string', description: 'Period start date (YYYY-MM-DD)' },
+        period_end: { type: 'string', description: 'Period end date (YYYY-MM-DD)' },
+        notes: { type: 'string', description: 'Optional notes' },
+      },
+      required: ['period_start', 'period_end'],
+    },
+  })
+  async create(args: Record<string, any>, context: McpContext): Promise<any> {
+    return this.financeService.createPeriodClose(args as any, context.userId);
+  }
+}

package/src/mcp-tools/finance-reports.mcp-tools.ts

@@ -0,0 +1,59 @@
+import { McpContext, McpTool } from '@hed-hog/core';
+import { Injectable } from '@nestjs/common';
+import { FinanceService } from '../finance.service';
+
+@Injectable()
+export class FinanceReportsMcpTools {
+  constructor(private readonly financeService: FinanceService) {}
+
+  @McpTool({
+    name: 'finance.reports.overview-results',
+    description: 'Returns the finance overview results report.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        period_start: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        period_end: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+        groupBy: { type: 'string', description: 'Grouping (day|week|month|year)' },
+      },
+    },
+    readOnly: true,
+  })
+  async overviewResults(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.financeService.getOverviewResultsReport(args as any);
+  }
+
+  @McpTool({
+    name: 'finance.reports.top-customers',
+    description: 'Returns top customers report.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        period_start: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        period_end: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+        limit: { type: 'number', description: 'Top ranking limit' },
+      },
+    },
+    readOnly: true,
+  })
+  async topCustomers(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.financeService.getTopCustomersReport(args as any);
+  }
+
+  @McpTool({
+    name: 'finance.reports.top-operational-expenses',
+    description: 'Returns top operational expenses report.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        period_start: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+        period_end: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+        limit: { type: 'number', description: 'Top ranking limit' },
+      },
+    },
+    readOnly: true,
+  })
+  async topOperationalExpenses(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.financeService.getTopOperationalExpensesReport(args as any);
+  }
+}