@fiado/type-kit 3.615.0 → 3.617.0

package/src/reconciliation/enums/ReconciliationItemStateEnum.ts

@@ -0,0 +1,23 @@
+/** Estado calculado de una partida; la resolución vive aparte y la corrida nunca la pisa. */
+export enum ReconciliationItemStateEnum {
+    /** OK: ambos lados cuadran al centavo. */
+    MATCHED = 'MATCHED',
+    /** Espera: sin contraparte dentro de los días hábiles de la definición. */
+    PENDING = 'PENDING',
+    /** Falta en el lado esperado; el nombre del lado sale de la definición. */
+    MISSING_IN_EXPECTED = 'MISSING_IN_EXPECTED',
+    /** Falta en el lado ejecutado; el nombre del lado sale de la definición. */
+    MISSING_IN_EXECUTED = 'MISSING_IN_EXECUTED',
+    /** Diff en PAIRWISE; monto distinto del SPEI en SETTLEMENT. */
+    AMOUNT_MISMATCH = 'AMOUNT_MISMATCH',
+    /** Falta en EdC: movimiento de FSA o SPEI de nota sin línea en el estado de cuenta. */
+    MISSING_IN_BANK_STATEMENT = 'MISSING_IN_BANK_STATEMENT',
+    /** Lo que las partidas de la semana no explican del agregado. */
+    UNEXPLAINED_DIFFERENCE = 'UNEXPLAINED_DIFFERENCE',
+    OUT_OF_WINDOW = 'OUT_OF_WINDOW',
+    ACCOUNT_MISMATCH = 'ACCOUNT_MISMATCH',
+    COMPLETE = 'COMPLETE',
+    INCOMPLETE = 'INCOMPLETE',
+    /** Registro de sandbox: fuera de la matriz, solo en su lista. */
+    TEST = 'TEST',
+}

package/src/reconciliation/enums/ReconciliationLayerEnum.ts

@@ -0,0 +1,8 @@
+/** Capa de una partida: 1 ITEM, 2 AGGREGATE, 3 SETTLEMENT, 4 BANK_STATEMENT, y la completitud del ciclo. */
+export enum ReconciliationLayerEnum {
+    ITEM = 'ITEM',
+    AGGREGATE = 'AGGREGATE',
+    SETTLEMENT = 'SETTLEMENT',
+    BANK_STATEMENT = 'BANK_STATEMENT',
+    COMPLETENESS = 'COMPLETENESS',
+}

package/src/reconciliation/enums/ReconciliationPeriodEnum.ts

@@ -0,0 +1,6 @@
+/** Periodo de corrida o de agregado de una definición. */
+export enum ReconciliationPeriodEnum {
+    DAILY = 'DAILY',
+    WEEKLY = 'WEEKLY',
+    MONTHLY = 'MONTHLY',
+}

package/src/reconciliation/enums/ReconciliationResolutionArchiveReasonEnum.ts

@@ -0,0 +1,6 @@
+/** Por qué una resolución pasó al historial de la partida. */
+export enum ReconciliationResolutionArchiveReasonEnum {
+    REACTIVATED = 'REACTIVATED',
+    /** La corrida encontró que ambos lados ya cuadran. */
+    MATCHED_ON_RECALCULATION = 'MATCHED_ON_RECALCULATION',
+}

package/src/reconciliation/enums/ReconciliationResolutionStatusEnum.ts

@@ -0,0 +1,9 @@
+/** En qué va la resolución: ADJUSTING se reserva antes de llamar al processor y ADJUSTED se cierra al final. */
+export enum ReconciliationResolutionStatusEnum {
+    /** Solo marca; la partida sigue abierta. */
+    INVESTIGATING = 'INVESTIGATING',
+    /** Cerrada sin mover dinero. */
+    CLOSED = 'CLOSED',
+    ADJUSTING = 'ADJUSTING',
+    ADJUSTED = 'ADJUSTED',
+}

package/src/reconciliation/enums/ReconciliationResolutionTypeEnum.ts

@@ -0,0 +1,7 @@
+/** Lo que pidió el operador; ADJUST solo mueve dinero en definiciones con `moneyMovement`. */
+export enum ReconciliationResolutionTypeEnum {
+    ACCEPT = 'ACCEPT',
+    INVESTIGATE = 'INVESTIGATE',
+    EXCLUDE = 'EXCLUDE',
+    ADJUST = 'ADJUST',
+}

package/src/reconciliation/enums/ReconciliationRuleTypeEnum.ts

@@ -0,0 +1,7 @@
+/** Regla de una definición; el agregado semanal o mensual es la capa AGGREGATE de una PAIRWISE, no una regla. */
+export enum ReconciliationRuleTypeEnum {
+    PAIRWISE = 'PAIRWISE',
+    COMPLETENESS = 'COMPLETENESS',
+    SETTLEMENT = 'SETTLEMENT',
+    BANK_STATEMENT = 'BANK_STATEMENT',
+}

package/src/reconciliation/enums/ReconciliationRunStatusEnum.ts

@@ -0,0 +1,6 @@
+/** Un feed caído deja la corrida en FAILED con el concepto en `failedFeeds`. */
+export enum ReconciliationRunStatusEnum {
+    RUNNING = 'RUNNING',
+    COMPLETED = 'COMPLETED',
+    FAILED = 'FAILED',
+}

package/src/reconciliation/enums/ReconciliationSourceRoleEnum.ts

@@ -0,0 +1,6 @@
+/** Papel de un feed en una definición; PART es una pieza de completitud. */
+export enum ReconciliationSourceRoleEnum {
+    EXPECTED = 'EXPECTED',
+    EXECUTED = 'EXECUTED',
+    PART = 'PART',
+}

package/src/reconciliation/events/ReconciliationItemMatchedEventDetail.ts

@@ -0,0 +1,25 @@
+import { ReconciliationFeedRefs } from '../dtos/ReconciliationFeedRecord';
+import { ReconciliationRuleTypeEnum } from '../enums/ReconciliationRuleTypeEnum';
+
+// Origen de los eventos de EventBridge que publica reconciliation-engine-business.
+export const RECONCILIATION_EVENTS_SOURCE = 'fiado.reconciliation';
+
+export enum ReconciliationEventDetailTypeEnum {
+    /** Una partida BANK_STATEMENT con `refs.noteId` quedó en OK; sale una vez por partida. */
+    RECONCILIATION_ITEM_MATCHED = 'reconciliation.ReconciliationItemMatched',
+}
+
+// `detail` de ReconciliationItemMatched; transfer-note llena con él la confirmación de FSA.
+export class ReconciliationItemMatchedEventDetail {
+    /** Fijo por partida: un reenvío llega con el mismo id y el consumidor lo descarta. */
+    eventId!: string;
+    tenantId!: string;
+    definitionId!: string;
+    itemKey!: string;
+    ruleType!: ReconciliationRuleTypeEnum;
+    periodKey!: string;
+    amountCents!: number;
+    /** ISO 8601 del momento en que la partida quedó en OK. */
+    matchedAt!: string;
+    refs!: ReconciliationFeedRefs & { noteId: string };
+}

package/src/reconciliation/index.ts

@@ -0,0 +1,40 @@
+// Enums
+export * from './enums/ReconciliationRuleTypeEnum';
+export * from './enums/ReconciliationDefinitionStatusEnum';
+export * from './enums/ReconciliationItemStateEnum';
+export * from './enums/ReconciliationResolutionTypeEnum';
+export * from './enums/ReconciliationResolutionStatusEnum';
+export * from './enums/ReconciliationResolutionArchiveReasonEnum';
+export * from './enums/ReconciliationRunStatusEnum';
+export * from './enums/ReconciliationLayerEnum';
+export * from './enums/ReconciliationPeriodEnum';
+export * from './enums/ReconciliationSourceRoleEnum';
+export * from './enums/ReconciliationExportFormatEnum';
+export * from './enums/ReconciliationFeedConceptEnum';
+export * from './enums/ReconciliationErrorCodeEnum';
+export * from './enums/ReconciliationFeedErrorCodeEnum';
+export * from './enums/ReconciliationFeedOwnerEnum';
+
+// Constantes
+export * from './constants/reconciliationErrorHttpStatus';
+export * from './constants/reconciliationValidation';
+
+// Entidades del dominio
+export * from './dtos/ReconciliationFeedRecord';
+export * from './dtos/ReconciliationDefinition';
+export * from './dtos/ReconciliationRun';
+export * from './dtos/ReconciliationItem';
+
+// Request DTOs
+export * from './dtos/requests/ReconciliationActionRequests';
+export * from './dtos/requests/ReconciliationQueries';
+export * from './dtos/requests/PrivateReconciliationRequests';
+export * from './dtos/requests/ReconciliationFeedRequests';
+
+// Response DTOs
+export * from './dtos/responses/ReconciliationResponses';
+export * from './dtos/responses/PrivateReconciliationResponses';
+export * from './dtos/responses/ReconciliationFeedResponses';
+
+// Eventos
+export * from './events/ReconciliationItemMatchedEventDetail';

package/src/retailWizard/catalog/privateSaleDetailFields.ts

@@ -0,0 +1,15 @@
+import type { PrivateGetSaleResponse } from '../dtos/responses/PrivateGetSaleResponse';
+
+/** Lista cerrada de campos que privateGetSale puede devolver; nada fuera de ella sale del lambda. */
+export const PRIVATE_SALE_DETAIL_FIELDS: readonly (keyof PrivateGetSaleResponse)[] = [
+  'saleId',
+  'retailerId',
+  'sellerRetailUserId',
+  'retailCustomerId',
+  'creditId',
+  'customerName',
+  'customerPhone',
+  'amountCents',
+  'productModel',
+  'sellerName',
+] as const;

package/src/retailWizard/constants/retailWizardValidation.ts

@@ -0,0 +1,2 @@
+/** Nombre de lambda en kebab-case, p. ej. `reconciliation-engine-business`. */
+export const RETAIL_WIZARD_CALLER_SERVICE_PATTERN = /^[a-z0-9-]{1,64}$/;

package/src/retailWizard/dtos/requests/PrivateGetSaleRequest.ts

@@ -0,0 +1,26 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsString, Matches } from 'class-validator';
+import { RETAIL_WIZARD_CALLER_SERVICE_PATTERN } from '../../constants/retailWizardValidation';
+
+/** Path y query de GET /private/sales/{saleId} (privateGetSale); actor y callerService van al registro de acceso PII. */
+export class PrivateGetSaleRequest {
+  @Expose()
+  @IsString()
+  @IsNotEmpty()
+  saleId!: string;
+
+  @Expose()
+  @IsString()
+  @IsNotEmpty()
+  tenantId!: string;
+
+  /** Operador que abrió el detalle, reenviado por quien llama. */
+  @Expose()
+  @IsString()
+  @IsNotEmpty()
+  actor!: string;
+
+  @Expose()
+  @Matches(RETAIL_WIZARD_CALLER_SERVICE_PATTERN, { message: 'callerService debe ser el nombre del lambda (kebab-case)' })
+  callerService!: string;
+}

package/src/retailWizard/dtos/responses/PrivateGetSaleResponse.ts

@@ -0,0 +1,16 @@
+/** Respuesta de privateGetSale: solo los campos del detalle de una partida más ids; los ausentes se omiten. */
+export interface PrivateGetSaleResponse {
+  saleId: string;
+  retailerId: string;
+  sellerRetailUserId: string;
+  retailCustomerId?: string;
+  creditId?: string;
+  /** PII: nunca loguear. */
+  customerName?: string;
+  /** PII: nunca loguear. */
+  customerPhone?: string;
+  /** Lo cobrado al cerrar la venta, en centavos. */
+  amountCents?: number;
+  productModel?: string;
+  sellerName?: string;
+}

package/src/retailWizard/index.ts

@@ -227,3 +227,9 @@ export * from './dtos/responses/SetAnchorGiftsResponse';
 export * from './catalog/backofficeSessionSummaries';
 export * from './dtos/requests/BackofficeSessionSummariesRequest';
 export * from './dtos/responses/BackofficeSessionSummariesResponse';
+
+// Lectura privada de la venta para el detalle de una partida del motor (GET /private/sales/{saleId})
+export * from './catalog/privateSaleDetailFields';
+export * from './constants/retailWizardValidation';
+export * from './dtos/requests/PrivateGetSaleRequest';
+export * from './dtos/responses/PrivateGetSaleResponse';

package/src/transaction/dtos/TransactionCreateRequest.ts

@@ -166,4 +166,16 @@ export class TransactionCreateRequest {
     @IsString()
     @IsOptional()
     domFolio?: string;
+
+    /** Intento del motor de cobro que originó el cargo; en cobranza es igual al `attemptId`. */
+    @IsString()
+    @IsNotEmpty()
+    @IsOptional()
+    executionId?: string;
+
+    /** Tenant SOFOM dueño del cobro; `tenantId` del ledger sigue siendo `FIADO`. */
+    @IsString()
+    @IsNotEmpty()
+    @IsOptional()
+    sofomTenantId?: string;
 }

package/src/transactionProcessor/dtos/PrivateAuthorizeReconciliationAdjustmentRequest.ts

@@ -0,0 +1,101 @@
+import { Expose, Transform, Type } from 'class-transformer';
+import {
+    IsEmail,
+    IsEnum,
+    IsInt,
+    IsNotEmpty,
+    IsOptional,
+    IsString,
+    Matches,
+    Min,
+    ValidateNested,
+    ValidationArguments,
+    Validate,
+    ValidatorConstraint,
+    ValidatorConstraintInterface,
+} from 'class-validator';
+import { regexUuidV4 } from '../../helpers/constans/regex';
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { OperationEnum } from '../../transaction/enums/OperationEnum';
+import { ReconciliationAdjustmentReference } from './ReconciliationAdjustmentReference';
+
+/** La llave `{tenantId}#{definitionId}#{itemKey}#{resolutionVersion}` debe empezar con el tenant del body. */
+@ValidatorConstraint({ name: 'adjustmentKeyOfTenant' })
+export class AdjustmentKeyOfTenantConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const { tenantId } = args.object as { tenantId?: unknown };
+        return typeof value === 'string' && typeof tenantId === 'string' && tenantId.length > 0
+            && value.startsWith(`${tenantId}#`) && value.split('#').length >= 4;
+    }
+
+    defaultMessage(): string {
+        return 'adjustmentKey debe ser {tenantId}#{definitionId}#{itemKey}#{resolutionVersion}';
+    }
+}
+
+/** Body de privateAuthorizeReconciliationAdjustment: ajuste al cliente idempotente por `adjustmentKey`. */
+export class PrivateAuthorizeReconciliationAdjustmentRequest {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    tenantId!: string;
+
+    @Expose()
+    @Validate(AdjustmentKeyOfTenantConstraint)
+    adjustmentKey!: string;
+
+    /** El processor resuelve `peopleId` desde aquí. */
+    @Expose()
+    @Matches(regexUuidV4, { message: 'directoryId must be a valid UUID v4' })
+    directoryId!: string;
+
+    /** ADD abona al cliente; SUBSTRACT le carga. */
+    @Expose()
+    @IsEnum(OperationEnum)
+    operation!: OperationEnum;
+
+    @Expose()
+    @Type(() => Number)
+    @IsInt()
+    @Min(1)
+    amountCents!: number;
+
+    @Expose()
+    @IsEnum(CurrencyId)
+    currencyId!: CurrencyId;
+
+    /** Transacción del ledger que se corrige. */
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    originalTransactionId!: string;
+
+    /** Intento del cobro original, si lo hubo. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @IsNotEmpty()
+    executionId?: string;
+
+    @Expose()
+    @ValidateNested()
+    @Type(() => ReconciliationAdjustmentReference)
+    reference!: ReconciliationAdjustmentReference;
+
+    @Expose()
+    @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+    @IsString()
+    @IsNotEmpty()
+    reason!: string;
+
+    /** Email del operador que resolvió la partida. */
+    @Expose()
+    @IsEmail()
+    actor!: string;
+
+    /** Servicio que llama, validado contra la lista permitida del processor. */
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    author!: string;
+}

package/src/transactionProcessor/dtos/PrivateAuthorizeReconciliationAdjustmentResponse.ts

@@ -0,0 +1,7 @@
+/** Respuesta de privateAuthorizeReconciliationAdjustment; un `adjustmentKey` repetido devuelve el primer movimiento. */
+export interface PrivateAuthorizeReconciliationAdjustmentResponse {
+    adjustmentKey: string;
+    transactionId: string;
+    /** `true` si la llave ya existía y no se movió dinero otra vez. */
+    replayed: boolean;
+}

package/src/transactionProcessor/dtos/ReconciliationAdjustmentReference.ts

@@ -0,0 +1,15 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+/** Partida del motor que pidió el ajuste. */
+export class ReconciliationAdjustmentReference {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    definitionId!: string;
+
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    itemKey!: string;
+}

package/src/transactionProcessor/index.ts

@@ -42,6 +42,9 @@ export * from './dtos/AuthorizeRenewalPreAuthRequest';
 export * from './dtos/AuthorizeRenewalPreAuthResponse';
 export * from './dtos/PublishFiadoTxRequest';
 export * from './dtos/PublishFiadoTxResponse';
+export * from './dtos/ReconciliationAdjustmentReference';
+export * from './dtos/PrivateAuthorizeReconciliationAdjustmentRequest';
+export * from './dtos/PrivateAuthorizeReconciliationAdjustmentResponse';
 
 export * from './enums/TransactionProcessorCodesEnum';
 export * from './enums/AsyncTxStatusEnum';

package/src/transferNote/constants/transferNoteDefaultFees.ts

@@ -0,0 +1,7 @@
+import { TransferNoteConceptEnum } from '../enums/TransferNoteConceptEnum';
+
+/** Tarifa por omisión en centavos por crédito firmado (REQ-52), si el tenant no configura otra. */
+export const TRANSFER_NOTE_DEFAULT_FEE_CENTS = {
+    [TransferNoteConceptEnum.ORIGINATION_BONUS]: 5000,
+    [TransferNoteConceptEnum.ACCOUNT_OPENING]: 2500,
+} as const satisfies Readonly<Partial<Record<TransferNoteConceptEnum, number>>>;

package/src/transferNote/constants/transferNoteErrorHttpStatus.ts

@@ -0,0 +1,28 @@
+import { RECONCILIATION_FEED_ERROR_HTTP_STATUS } from '../../reconciliation/constants/reconciliationErrorHttpStatus';
+import { ReconciliationFeedErrorCodeEnum } from '../../reconciliation/enums/ReconciliationFeedErrorCodeEnum';
+import { TransferNoteErrorCodeEnum as C } from '../enums/TransferNoteErrorCodeEnum';
+
+/** Status HTTP de cada code: 400 request inválido · 404 no existe · 409 conflicto de estado · 422 regla de negocio. */
+export const TRANSFER_NOTE_ERROR_HTTP_STATUS: Readonly<Record<C, 400 | 404 | 409 | 422>> = {
+    [C.TRANSFER_NOTE_NOT_FOUND]: 404,
+    [C.NOTE_NOT_DISPUTABLE]: 409,
+    [C.NET_NOT_POSITIVE]: 422,
+    [C.NOT_NOTE_CONTROLLER]: 422,
+    [C.PAYEE_ACCOUNT_NOT_REGISTERED]: 422,
+    [C.ITEM_ALREADY_INCLUDED]: 409,
+    [C.WEEK_ALREADY_CUT]: 409,
+    [C.NOTE_NOT_ISSUED]: 409,
+    [C.NOTE_DISPUTED]: 409,
+    [C.NOT_NOTE_PAYER]: 422,
+    [C.NOTE_NOT_SENT]: 409,
+    [C.NOT_NOTE_PAYEE]: 422,
+    [C.NOTE_NOT_DISPUTED]: 409,
+    [C.CONTACT_EMAIL_MISSING]: 422,
+    [C.INVALID_CONFIG_RECORD_TYPE]: 400,
+    [C.AUTHOR_NOT_ALLOWED]: 422,
+    [C.SETTLEMENT_NOT_REQUIRED]: 422,
+    [C.RUN_IN_PROGRESS]: 409,
+    [C.SOURCE_ITEM_NOT_FOUND]: 404,
+    [C.TRANSFER_NOTE_ITEM_NOT_FOUND]: 404,
+    [C.FEED_RECORD_NOT_FOUND]: RECONCILIATION_FEED_ERROR_HTTP_STATUS[ReconciliationFeedErrorCodeEnum.FEED_RECORD_NOT_FOUND],
+};

package/src/transferNote/constants/transferNoteValidation.ts

@@ -0,0 +1,10 @@
+/** Largo mínimo de la razón de una emisión manual y de una objeción. */
+export const TRANSFER_NOTE_MIN_REASON_LENGTH = 20;
+
+/** Semana ISO `YYYY-Www`, p. ej. `2026-W43`. */
+export const TRANSFER_NOTE_ISO_WEEK_PATTERN = /^\d{4}-W(0[1-9]|[1-4]\d|5[0-3])$/;
+
+/** CLABE interbancaria de 18 dígitos. */
+export const TRANSFER_NOTE_CLABE_PATTERN = /^\d{18}$/;
+
+export const TRANSFER_NOTE_MAX_PAGE_SIZE = 100;

package/src/transferNote/dtos/TransferNote.ts

@@ -0,0 +1,89 @@
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { TransferNoteConceptEnum } from '../enums/TransferNoteConceptEnum';
+import { TransferNoteConfirmationSourceEnum } from '../enums/TransferNoteConfirmationSourceEnum';
+import { TransferNoteConfirmationTypeEnum } from '../enums/TransferNoteConfirmationTypeEnum';
+import { TransferNoteDisputeCategoryEnum } from '../enums/TransferNoteDisputeCategoryEnum';
+import { TransferNoteIssueOriginEnum } from '../enums/TransferNoteIssueOriginEnum';
+import { TransferNotePartyTypeEnum } from '../enums/TransferNotePartyTypeEnum';
+import { TransferNoteStatusEnum } from '../enums/TransferNoteStatusEnum';
+
+/** Parte de una nota, sin datos de contacto ni de cuenta. */
+export interface TransferNoteParty {
+    partyId: string;
+    partyType: TransferNotePartyTypeEnum;
+    /** Solo en partes RETAILER. */
+    retailerId?: string;
+}
+
+export interface TransferNoteSubtotal {
+    concept: TransferNoteConceptEnum;
+    amountCents: number;
+    itemCount: number;
+}
+
+export interface TransferNoteSpeiPayment {
+    trackingKey: string;
+    paidAt: string;
+    amountCents: number;
+    capturedBy: string;
+    capturedAt: string;
+    receiptUploaded: boolean;
+}
+
+export interface TransferNoteConfirmation {
+    type: TransferNoteConfirmationTypeEnum;
+    source: TransferNoteConfirmationSourceEnum;
+    confirmedBy: string;
+    confirmedAt: string;
+}
+
+export interface TransferNoteDispute {
+    category: TransferNoteDisputeCategoryEnum;
+    reason: string;
+    disputedBy: string;
+    disputedAt: string;
+    /** Estado al que vuelve la nota si se rechaza la objeción. */
+    previousStatus: TransferNoteStatusEnum;
+}
+
+/** Fila de los listados de notas. */
+export interface TransferNoteSummary {
+    noteId: string;
+    tenantId: string;
+    pairKey: string;
+    isoWeek: string;
+    payer: TransferNoteParty;
+    payee: TransferNoteParty;
+    /** Calculado de pagador y receptor; no se guarda. */
+    controllerPartyType: TransferNotePartyTypeEnum;
+    status: TransferNoteStatusEnum;
+    issueOrigin: TransferNoteIssueOriginEnum;
+    netAmountCents: number;
+    currency: CurrencyId;
+    itemCount: number;
+    issuedAt?: string;
+    dueAt?: string;
+}
+
+/** Detalle de una nota. */
+export interface TransferNote extends TransferNoteSummary {
+    subtotals: TransferNoteSubtotal[];
+    requiredConfirmations: TransferNoteConfirmationTypeEnum[];
+    confirmations: TransferNoteConfirmation[];
+    /** Razón de la emisión manual. */
+    issueReason?: string;
+    speiPayment?: TransferNoteSpeiPayment;
+    dispute?: TransferNoteDispute;
+    /** Nota cancelada de la que nace esta, o la regenerada que la reemplaza. */
+    regeneratedFromNoteId?: string;
+    regeneratedNoteId?: string;
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy?: string;
+}
+
+export interface TransferNoteStatusCount {
+    status: TransferNoteStatusEnum;
+    count: number;
+}

package/src/transferNote/dtos/TransferNoteConfigRecords.ts

@@ -0,0 +1,55 @@
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { TransferNoteConceptEnum } from '../enums/TransferNoteConceptEnum';
+import { TransferNoteConceptSignEnum } from '../enums/TransferNoteConceptSignEnum';
+import { TransferNoteConfigRecordTypeEnum } from '../enums/TransferNoteConfigRecordTypeEnum';
+import { TransferNotePartyTypeEnum } from '../enums/TransferNotePartyTypeEnum';
+
+/** Registro TENANT. */
+export interface TransferNoteTenantSettings {
+    activeFrom: string;
+    currency: CurrencyId;
+}
+
+/** Registro PARTY#partyId: la cuenta destino y el correo de contacto de una parte. */
+export interface TransferNotePartySettings {
+    partyId: string;
+    partyType: TransferNotePartyTypeEnum;
+    displayName: string;
+    retailerId?: string;
+    clabe?: string;
+    contactEmail?: string;
+}
+
+/** Registro CONCEPT#concept: a qué tipo de par va, con qué signo y desde cuándo. */
+export interface TransferNoteConceptSettings {
+    concept: TransferNoteConceptEnum;
+    payerPartyType: TransferNotePartyTypeEnum;
+    payeePartyType: TransferNotePartyTypeEnum;
+    sign: TransferNoteConceptSignEnum;
+    activeFrom: string;
+    /** Tarifa por crédito firmado, solo en conceptos derivados. */
+    rateCents?: number;
+}
+
+/** Registro PAIR#pairKey con su contador de cortes sin emitir. */
+export interface TransferNotePairSettings {
+    pairKey: string;
+    payerPartyId: string;
+    payeePartyId: string;
+    activeFrom: string;
+    consecutiveUnissuedCutoffs: number;
+    /** Se llena al 4.º corte seguido sin emitir. */
+    discrepancyOpenedAt?: string;
+}
+
+/** Un registro de configuración; trae solo el sub-shape de su `recordType`. */
+export interface TransferNoteConfigRecord {
+    recordKey: string;
+    recordType: TransferNoteConfigRecordTypeEnum;
+    tenant?: TransferNoteTenantSettings;
+    party?: TransferNotePartySettings;
+    concept?: TransferNoteConceptSettings;
+    pair?: TransferNotePairSettings;
+    updatedAt: string;
+    updatedBy: string;
+}

package/src/transferNote/dtos/TransferNoteFeedRecords.ts

@@ -0,0 +1,35 @@
+import type { ReconciliationFeedRecord, ReconciliationFeedRefs } from '../../reconciliation/dtos/ReconciliationFeedRecord';
+import type { ReconciliationFeedConceptEnum } from '../../reconciliation/enums/ReconciliationFeedConceptEnum';
+import { TransferNoteConceptEnum } from '../enums/TransferNoteConceptEnum';
+import { TransferNotePartyTypeEnum } from '../enums/TransferNotePartyTypeEnum';
+import { TransferNoteStatusEnum } from '../enums/TransferNoteStatusEnum';
+
+/** Registro del feed TRANSFER_NOTE_ITEM: un item ya incluido en una nota; `recordId` es su itemId. */
+export interface TransferNoteItemFeedRecord extends ReconciliationFeedRecord {
+    concept: ReconciliationFeedConceptEnum.TRANSFER_NOTE_ITEM;
+    /** `matchKey` del registro de origen; `feedDay` es el día CDMX de `includedAt`. */
+    refs: ReconciliationFeedRefs & { noteId: string; itemId: string };
+    itemConcept: TransferNoteConceptEnum;
+    pairKey: string;
+    /** `recordId` en el feed del dueño del que salió el item. */
+    sourceRecordId: string;
+    includedAt: string;
+}
+
+/** Registro del feed TRANSFER_NOTE_SETTLEMENT: lo que una nota debe pagar y lo capturado; `recordId` y `matchKey` son el noteId. */
+export interface TransferNoteSettlementFeedRecord extends ReconciliationFeedRecord {
+    concept: ReconciliationFeedConceptEnum.TRANSFER_NOTE_SETTLEMENT;
+    /** `amountCents` es el neto de la nota; `occurredAt` su emisión. */
+    refs: ReconciliationFeedRefs & { noteId: string };
+    pairKey: string;
+    payerPartyType: TransferNotePartyTypeEnum;
+    payerPartyId: string;
+    payeePartyType: TransferNotePartyTypeEnum;
+    payeePartyId: string;
+    status: TransferNoteStatusEnum;
+    dueAt: string;
+    /** Cuenta registrada del receptor al emitir. */
+    payeeClabe: string;
+    paidAt?: string;
+    paidAmountCents?: number;
+}

package/src/transferNote/dtos/TransferNoteHistoryEntry.ts

@@ -0,0 +1,17 @@
+import { TransferNoteHistoryActionEnum } from '../enums/TransferNoteHistoryActionEnum';
+import { TransferNoteStatusEnum } from '../enums/TransferNoteStatusEnum';
+import { TransferNoteConfirmation } from './TransferNote';
+
+/** Una acción del historial de la nota. */
+export interface TransferNoteHistoryEntry {
+    action: TransferNoteHistoryActionEnum;
+    actor: string;
+    occurredAt: string;
+    reason?: string;
+    fromStatus?: TransferNoteStatusEnum;
+    toStatus?: TransferNoteStatusEnum;
+    /** Items que volvieron al pool al cancelar. */
+    itemIds?: string[];
+    /** Confirmaciones anuladas al revertir el SPEI. */
+    annulledConfirmations?: TransferNoteConfirmation[];
+}