@hed-hog/contact 0.0.299 → 0.0.301

package/src/proposal/dto/proposal.dto.ts

@@ -0,0 +1,341 @@
+import { getLocaleText } from '@hed-hog/api-locale';
+import { PartialType } from '@nestjs/mapped-types';
+import { Type } from 'class-transformer';
+import {
+    IsArray,
+    IsBoolean,
+    IsDateString,
+    IsEnum,
+    IsInt,
+    IsNotEmpty,
+    IsNumber,
+    IsObject,
+    IsOptional,
+    IsString,
+    MaxLength,
+    Min,
+    ValidateNested,
+} from 'class-validator';
+
+export enum ProposalStatus {
+  DRAFT = 'draft',
+  PENDING_APPROVAL = 'pending_approval',
+  APPROVED = 'approved',
+  REJECTED = 'rejected',
+  CANCELLED = 'cancelled',
+  EXPIRED = 'expired',
+  CONTRACT_GENERATED = 'contract_generated',
+}
+
+export enum ProposalContractCategory {
+  EMPLOYEE = 'employee',
+  CONTRACTOR = 'contractor',
+  CLIENT = 'client',
+  SUPPLIER = 'supplier',
+  VENDOR = 'vendor',
+  PARTNER = 'partner',
+  INTERNAL = 'internal',
+  OTHER = 'other',
+}
+
+export enum ProposalContractType {
+  CLT = 'clt',
+  PJ = 'pj',
+  FREELANCER_AGREEMENT = 'freelancer_agreement',
+  SERVICE_AGREEMENT = 'service_agreement',
+  FIXED_TERM = 'fixed_term',
+  RECURRING_SERVICE = 'recurring_service',
+  NDA = 'nda',
+  AMENDMENT = 'amendment',
+  ADDENDUM = 'addendum',
+  OTHER = 'other',
+}
+
+export enum ProposalBillingModel {
+  TIME_AND_MATERIAL = 'time_and_material',
+  MONTHLY_RETAINER = 'monthly_retainer',
+  FIXED_PRICE = 'fixed_price',
+}
+
+export enum ProposalGenerationMode {
+  MANUAL = 'manual',
+  AI_ASSISTED = 'ai_assisted',
+  DUPLICATED = 'duplicated',
+  IMPORTED = 'imported',
+}
+
+export enum ProposalItemType {
+  SERVICE = 'service',
+  PRODUCT = 'product',
+  FEE = 'fee',
+  DISCOUNT = 'discount',
+  NOTE = 'note',
+  OTHER = 'other',
+}
+
+export enum ProposalTermType {
+  VALUE = 'value',
+  PAYMENT = 'payment',
+  REVENUE = 'revenue',
+  FINE = 'fine',
+  OTHER = 'other',
+}
+
+export enum ProposalRecurrence {
+  ONE_TIME = 'one_time',
+  MONTHLY = 'monthly',
+  QUARTERLY = 'quarterly',
+  YEARLY = 'yearly',
+  OTHER = 'other',
+}
+
+export enum ProposalDocumentType {
+  SOURCE_UPLOAD = 'source_upload',
+  GENERATED_PDF = 'generated_pdf',
+  APPROVAL_ATTACHMENT = 'approval_attachment',
+  SIGNED_COPY = 'signed_copy',
+  ATTACHMENT = 'attachment',
+  OTHER = 'other',
+}
+
+export enum ProposalDocumentSourceKind {
+  MANUAL = 'manual',
+  GENERATED = 'generated',
+  IMPORTED = 'imported',
+  AI_ASSISTED = 'ai_assisted',
+}
+
+export enum ProposalDocumentExtractionStatus {
+  PENDING = 'pending',
+  PROCESSING = 'processing',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  SKIPPED = 'skipped',
+}
+
+export class ProposalItemDto {
+  @IsOptional()
+  @IsEnum(ProposalItemType)
+  item_type?: ProposalItemType;
+
+  @IsOptional()
+  @IsEnum(ProposalTermType)
+  term_type?: ProposalTermType;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(180)
+  name: string;
+
+  @IsOptional()
+  @IsString()
+  description?: string | null;
+
+  @IsOptional()
+  @IsNumber()
+  quantity?: number;
+
+  @IsOptional()
+  @IsInt()
+  unit_amount_cents?: number;
+
+  @IsOptional()
+  @IsInt()
+  total_amount_cents?: number;
+
+  @IsOptional()
+  @IsEnum(ProposalRecurrence)
+  recurrence?: ProposalRecurrence;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  due_day?: number | null;
+
+  @IsOptional()
+  @IsDateString()
+  start_date?: string | null;
+
+  @IsOptional()
+  @IsDateString()
+  end_date?: string | null;
+
+  @IsOptional()
+  @IsObject()
+  metadata_json?: Record<string, any> | null;
+}
+
+export class ProposalDocumentDto {
+  @IsOptional()
+  @IsEnum(ProposalDocumentType)
+  document_type?: ProposalDocumentType;
+
+  @IsOptional()
+  @IsInt()
+  file_id?: number | null;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(200)
+  file_name: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(120)
+  mime_type: string;
+
+  @IsOptional()
+  @IsString()
+  file_content_base64?: string | null;
+
+  @IsOptional()
+  @IsEnum(ProposalDocumentSourceKind)
+  source_kind?: ProposalDocumentSourceKind;
+
+  @IsOptional()
+  @IsEnum(ProposalDocumentExtractionStatus)
+  extraction_status?: ProposalDocumentExtractionStatus;
+
+  @IsOptional()
+  @IsString()
+  extraction_summary?: string | null;
+
+  @IsOptional()
+  @IsString()
+  notes?: string | null;
+}
+
+export class CreateProposalDto {
+  @IsInt({
+    message: (args) =>
+      getLocaleText('validation.personIdMustBeNumber', args.value),
+  })
+  person_id: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(40)
+  code?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(180)
+  title: string;
+
+  @IsOptional()
+  @IsEnum(ProposalStatus)
+  status?: ProposalStatus;
+
+  @IsOptional()
+  @IsEnum(ProposalContractCategory)
+  contract_category?: ProposalContractCategory;
+
+  @IsOptional()
+  @IsEnum(ProposalContractType)
+  contract_type?: ProposalContractType;
+
+  @IsOptional()
+  @IsEnum(ProposalBillingModel)
+  billing_model?: ProposalBillingModel;
+
+  @IsOptional()
+  @IsString()
+  currency_code?: string;
+
+  @IsOptional()
+  @IsDateString()
+  valid_from?: string | null;
+
+  @IsOptional()
+  @IsDateString()
+  valid_until?: string | null;
+
+  @IsOptional()
+  @IsInt()
+  subtotal_amount_cents?: number;
+
+  @IsOptional()
+  @IsInt()
+  discount_amount_cents?: number;
+
+  @IsOptional()
+  @IsInt()
+  tax_amount_cents?: number;
+
+  @IsOptional()
+  @IsInt()
+  total_amount_cents?: number;
+
+  @IsOptional()
+  @IsString()
+  notes?: string | null;
+
+  @IsOptional()
+  @IsInt()
+  owner_user_id?: number | null;
+
+  @IsOptional()
+  @IsEnum(ProposalGenerationMode)
+  generation_mode?: ProposalGenerationMode;
+
+  @IsOptional()
+  @IsString()
+  summary?: string | null;
+
+  @IsOptional()
+  @IsString()
+  content_html?: string | null;
+
+  @IsOptional()
+  @IsObject()
+  snapshot_json?: Record<string, any> | null;
+
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ProposalItemDto)
+  items?: ProposalItemDto[];
+
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ProposalDocumentDto)
+  documents?: ProposalDocumentDto[];
+}
+
+export class UpdateProposalDto extends PartialType(CreateProposalDto) {
+  @IsOptional()
+  @IsBoolean()
+  create_new_revision?: boolean;
+}
+
+export class SubmitProposalDto {
+  @IsOptional()
+  @IsInt()
+  approver_user_id?: number | null;
+
+  @IsOptional()
+  @IsString()
+  note?: string | null;
+}
+
+export class ProposalDecisionDto {
+  @IsOptional()
+  @IsString()
+  note?: string | null;
+}
+
+export class ProposalListQueryDto {
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  @IsOptional()
+  @IsEnum(ProposalStatus)
+  status?: ProposalStatus;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  person_id?: number;
+}

package/src/proposal/proposal-contract.subscriber.ts

@@ -0,0 +1,43 @@
+import { IntegrationDeveloperApiService } from '@hed-hog/core';
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { ProposalService } from './proposal.service';
+
+@Injectable()
+export class ProposalContractSubscriber implements OnModuleInit {
+  private readonly logger = new Logger(ProposalContractSubscriber.name);
+
+  constructor(
+    private readonly integrationApi: IntegrationDeveloperApiService,
+    private readonly proposalService: ProposalService,
+  ) {}
+
+  onModuleInit(): void {
+    this.integrationApi.subscribe({
+      eventName: 'operations.contract.created',
+      consumerName: 'contact.proposal-conversion-tracker',
+      priority: 10,
+      handler: async (event) => {
+        const payload = (event.payload || {}) as any;
+        const proposalId = Number(
+          payload.proposalId || payload.contract?.originId || 0,
+        );
+
+        if (!Number.isInteger(proposalId) || proposalId <= 0) {
+          this.logger.warn(
+            `Ignoring ${event.eventName} because no proposalId was provided.`,
+          );
+          return;
+        }
+
+        if (String(payload.contract?.originType || '') !== 'crm_proposal') {
+          this.logger.debug(
+            `Ignoring ${event.eventName} for proposal ${proposalId} because originType is ${payload.contract?.originType || 'unknown'}.`,
+          );
+          return;
+        }
+
+        await this.proposalService.markConvertedFromIntegration(payload);
+      },
+    });
+  }
+}

package/src/proposal/proposal-event.types.ts

@@ -0,0 +1,130 @@
+export const PROPOSAL_EVENT_NAMES = {
+  CREATED: 'contact.proposal.created',
+  SENT: 'contact.proposal.sent',
+  APPROVED: 'contact.proposal.approved',
+  REJECTED: 'contact.proposal.rejected',
+  CANCELLED: 'contact.proposal.cancelled',
+  CONVERT_REQUESTED: 'contact.proposal.convert_requested',
+  CONVERTED: 'contact.proposal.converted',
+} as const;
+
+export type ProposalLifecycleEventName =
+  (typeof PROPOSAL_EVENT_NAMES)[keyof typeof PROPOSAL_EVENT_NAMES];
+
+export interface ProposalSourceReference {
+  sourceModule: 'contact';
+  sourceEntity: 'proposal';
+  sourceId: string;
+  source_module: 'contact';
+  source_entity: 'proposal';
+  source_id: string;
+}
+
+export interface ProposalCommercialTermsSnapshot {
+  contractCategory: string | null;
+  contractType: string | null;
+  billingModel: string | null;
+  validFrom: string | null;
+  validUntil: string | null;
+  summary: string | null;
+  notes: string | null;
+}
+
+export interface ProposalItemSummary {
+  id: number | null;
+  name: string;
+  description: string | null;
+  itemType: string | null;
+  termType: string | null;
+  quantity: number;
+  unitAmountCents: number;
+  totalAmountCents: number;
+  amount: number;
+  recurrence: string | null;
+  dueDay: number | null;
+}
+
+export interface ProposalPartySnapshot {
+  id: number | null;
+  name: string | null;
+  tradeName: string | null;
+  email: string | null;
+  phone: string | null;
+  document: string | null;
+  type: string | null;
+}
+
+export interface ProposalRevisionSnapshot {
+  id: number | null;
+  revisionNumber: number;
+  title: string | null;
+  summary: string | null;
+  contentHtml: string | null;
+  submittedAt: string | null;
+  approvedAt: string | null;
+}
+
+export interface ProposalContractSnapshot {
+  contractId: number | null;
+  code: string | null;
+  name: string | null;
+  status: string | null;
+  url: string | null;
+}
+
+export interface ProposalLifecycleEventPayload extends ProposalSourceReference {
+  eventName: ProposalLifecycleEventName;
+  eventKey: string;
+  correlationId: string;
+  proposalId: number;
+  proposalRevisionId: number | null;
+  approvedByUserId: number | null;
+  dealId: number | null;
+  personId: number | null;
+  companyId: number | null;
+  customerIds: {
+    personId: number | null;
+    companyId: number | null;
+  };
+  code: string | null;
+  title: string | null;
+  version: number;
+  status: string | null;
+  approvedAt: string | null;
+  validUntil: string | null;
+  currency: string;
+  proposal: {
+    code: string | null;
+    title: string | null;
+    status: string | null;
+    contractCategory: string | null;
+    contractType: string | null;
+    billingModel: string | null;
+    currencyCode: string | null;
+    validFrom: string | null;
+    validUntil: string | null;
+    subtotalAmountCents: number;
+    discountAmountCents: number;
+    taxAmountCents: number;
+    totalAmountCents: number;
+    totalAmount: number;
+    notes: string | null;
+  };
+  subtotal: number;
+  subtotalCents: number;
+  discount: number;
+  discountCents: number;
+  tax: number;
+  taxCents: number;
+  total: number;
+  totalCents: number;
+  commercialTerms: ProposalCommercialTermsSnapshot;
+  itemsSummary: ProposalItemSummary[];
+  items: ProposalItemSummary[];
+  person: ProposalPartySnapshot | null;
+  revision: ProposalRevisionSnapshot | null;
+  contract: ProposalContractSnapshot | null;
+  triggeredByUserId: number | null;
+  emittedAt: string;
+  locale: string | null;
+}

package/src/proposal/proposal.controller.ts

@@ -0,0 +1,168 @@
+import { DeleteDTO, Role, User } from '@hed-hog/api';
+import { Locale } from '@hed-hog/api-locale';
+import { Pagination } from '@hed-hog/api-pagination';
+import {
+    Body,
+    Controller,
+    Delete,
+    Get,
+    Param,
+    ParseIntPipe,
+    Patch,
+    Post,
+    Query,
+} from '@nestjs/common';
+import {
+    CreateProposalDto,
+    ProposalDecisionDto,
+    ProposalListQueryDto,
+    SubmitProposalDto,
+    UpdateProposalDto,
+} from './dto/proposal.dto';
+import { ProposalService } from './proposal.service';
+
+@Role()
+@Controller('proposal')
+export class ProposalController {
+  constructor(private readonly proposalService: ProposalService) {}
+
+  @Get()
+  async list(
+    @Pagination() paginationParams,
+    @Query() query: ProposalListQueryDto,
+  ) {
+    return this.proposalService.list({
+      ...paginationParams,
+      ...query,
+    });
+  }
+
+  @Get('stats')
+  async getStats() {
+    return this.proposalService.getStats();
+  }
+
+  @Get(':id')
+  async getById(
+    @Param('id', ParseIntPipe) id: number,
+    @Locale() locale: string,
+  ) {
+    return this.proposalService.getById(id, locale);
+  }
+
+  @Post(':id/generate-pdf')
+  async generateDocument(
+    @Param('id', ParseIntPipe) id: number,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.generateDocument(
+      id,
+      locale,
+      Number(user?.id || 0),
+    );
+  }
+
+  @Post()
+  async create(
+    @Body() body: CreateProposalDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.create(body, locale, Number(user?.id || 0));
+  }
+
+  @Patch(':id')
+  async update(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: UpdateProposalDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.update(id, body, locale, Number(user?.id || 0));
+  }
+
+  @Post(':id/submit')
+  async submitForApproval(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: SubmitProposalDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.submitForApproval(
+      id,
+      body,
+      locale,
+      Number(user?.id || 0),
+    );
+  }
+
+  @Post(':id/send')
+  async send(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: SubmitProposalDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.submitForApproval(
+      id,
+      body,
+      locale,
+      Number(user?.id || 0),
+    );
+  }
+
+  @Post(':id/approve')
+  async approve(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: ProposalDecisionDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.approve(id, body, locale, Number(user?.id || 0));
+  }
+
+  @Post(':id/reject')
+  async reject(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: ProposalDecisionDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.reject(id, body, locale, Number(user?.id || 0));
+  }
+
+  @Post(':id/cancel')
+  async cancel(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: ProposalDecisionDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.cancel(id, body, locale, Number(user?.id || 0));
+  }
+
+  @Post(':id/convert')
+  async requestConversion(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: ProposalDecisionDto,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.requestConversion(
+      id,
+      body,
+      locale,
+      Number(user?.id || 0),
+    );
+  }
+
+  @Delete()
+  async remove(
+    @Body() body: DeleteDTO,
+    @Locale() locale: string,
+    @User() user,
+  ) {
+    return this.proposalService.remove(body, locale, Number(user?.id || 0));
+  }
+}

package/src/proposal/proposal.module.ts

@@ -0,0 +1,19 @@
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { CoreModule } from '@hed-hog/core';
+import { forwardRef, Module } from '@nestjs/common';
+import { ProposalContractSubscriber } from './proposal-contract.subscriber';
+import { ProposalController } from './proposal.controller';
+import { ProposalService } from './proposal.service';
+
+@Module({
+  imports: [
+    forwardRef(() => CoreModule),
+    forwardRef(() => PrismaModule),
+    forwardRef(() => PaginationModule),
+  ],
+  controllers: [ProposalController],
+  providers: [ProposalService, ProposalContractSubscriber],
+  exports: [ProposalService],
+})
+export class ProposalModule {}