@devizovaburza/mdm-sdk 1.3.0 → 1.4.0

package/dist/v1/index.mjs

@@ -194,6 +194,19 @@ const ID_DOC_STATUS = [
   "REVOKED"
 ];
 const CUSTOMER_STATUS = ["NEW", "ACTIVE", "CLOSED", "BLOCKED"];
+const BLOCK_REASON = [
+  "MISSING_OWNERSHIP_STRUCTURE",
+  "REMOVED_FROM_REGISTRY",
+  "INSOLVENCY",
+  "EXECUTION",
+  "INACTIVE_FROM_START",
+  "INACTIVE_OVER_2_YEARS",
+  "COMPANY_SOLD",
+  "UNINTERESTING",
+  "OUTDATED_ID_DOCUMENTS",
+  "OTHER",
+  "BLOCKED_BY_CLIENT"
+];
 const PARTY_TYPE = [
   "INDIVIDUAL",
   "SELF_EMPLOYED",
@@ -310,6 +323,38 @@ const RISK_BUSINESS_AREA = [
   "VIRTUAL_ASSET_SERVICES"
 ];
 
+function logAuditEvent(context, input) {
+  const identity = context.get("identity");
+  const sourceIp = context.req.header("CF-Connecting-IP");
+  const correlationId = input.correlationId ?? context.get("correlationId");
+  if (!correlationId) {
+    throw new Error(
+      "logAuditEvent: missing correlationId \u2014 auditLog() middleware must be mounted before handlers that call logAuditEvent"
+    );
+  }
+  context.executionCtx.waitUntil(
+    context.env.ACTIVITY_SERVICE.logAuditEvent({
+      logType: "event",
+      service: "gateway",
+      eventType: input.eventType,
+      correlationId,
+      actorUserId: input.actorUserId ?? identity?.user?.id,
+      actorEmail: input.actorEmail ?? identity?.user?.email ?? "not-authorized@system.internal",
+      actorOrganizationId: input.actorOrganizationId ?? identity?.user?.organizationId,
+      targetType: input.targetType,
+      targetId: input.targetId,
+      outcome: input.outcome,
+      description: input.description,
+      severity: input.severity ?? "low",
+      details: input.details,
+      userAgent: context.req.header("User-Agent"),
+      ...sourceIp && { sourceIp }
+    }).catch((error) => {
+      console.error(`Failed to log audit event "${input.eventType}":`, error);
+    })
+  );
+}
+
 z.object({
   message: z.string(),
   data: z.null(),
@@ -350,7 +395,10 @@ const partySchema$1 = z.object({
   id: z.uuid(),
   internalId: z.string().optional(),
   note: z.string().optional(),
-  countryCode: z.enum(COUNTRY_CODES).optional()
+  countryCode: z.enum(COUNTRY_CODES).optional(),
+  customerStatus: z.enum(CUSTOMER_STATUS).optional(),
+  blockReason: z.enum(BLOCK_REASON).nullable().optional(),
+  blockReasonNote: z.string().trim().min(1).nullable().optional()
 });
 const idDocumentInputSchema$1 = z.object({
   idDocType: z.enum(ID_DOC_TYPE),
@@ -583,6 +631,21 @@ const createPartyInputSchema = z.object({
   recipients: z.array(bankAccountInputSchema),
   products: productsInputSchema$1.optional(),
   traderIds: z.array(z.uuid()).optional()
+}).refine(
+  (b) => b.party.customerStatus !== "BLOCKED" || !!b.party.blockReason,
+  {
+    message: "blockReason is required when customerStatus is BLOCKED",
+    path: ["party", "blockReason"]
+  }
+).refine(
+  (b) => b.party.customerStatus === "BLOCKED" || !b.party.blockReason && !b.party.blockReasonNote,
+  {
+    message: "blockReason and blockReasonNote must be null when customerStatus is not BLOCKED",
+    path: ["party", "blockReason"]
+  }
+).refine((b) => b.party.blockReason !== "OTHER" || !!b.party.blockReasonNote, {
+  message: "blockReasonNote is required when blockReason is OTHER",
+  path: ["party", "blockReasonNote"]
 });
 const partyCreateOutputSchema = z.object({
   customerStatus: z.enum(CUSTOMER_STATUS),
@@ -627,101 +690,211 @@ const createPartyRoute = createRoute({
     ...errorResponse("Party", "Creation")
   }
 });
-new OpenAPIHono().openapi(
-  createPartyRoute,
-  async (context) => {
-    const { owners, legalRepresentatives, ...partyInput } = context.req.valid("json");
-    const disponentsWithDocs = (partyInput.disponents ?? []).filter(
-      (d) => d.partyType === "INDIVIDUAL" && !!d.data.identityDocuments?.length
-    );
-    const disponentsForBatch = (partyInput.disponents ?? []).filter(
-      (d) => !(d.partyType === "INDIVIDUAL" && !!d.data.identityDocuments?.length)
+new OpenAPIHono().openapi(createPartyRoute, async (context) => {
+  const { owners, legalRepresentatives, ...partyInput } = context.req.valid("json");
+  const disponentsWithDocs = (partyInput.disponents ?? []).filter(
+    (d) => d.partyType === "INDIVIDUAL" && !!d.data.identityDocuments?.length
+  );
+  const disponentsForBatch = (partyInput.disponents ?? []).filter(
+    (d) => !(d.partyType === "INDIVIDUAL" && !!d.data.identityDocuments?.length)
+  );
+  const { data: partyData, error } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.createParty({
+    ...partyInput,
+    disponents: disponentsForBatch,
+    party: { ...partyInput.party, isRoot: true }
+  });
+  if (!partyData || error) {
+    logAuditEvent(context, {
+      eventType: "party.created",
+      targetType: "party",
+      outcome: "failure",
+      severity: "medium",
+      description: "Failed to create party",
+      details: { partyType: partyInput.party.partyType }
+    });
+    return context.json(
+      {
+        message: "Could not create a party"
+      },
+      500
     );
-    const { data: partyData, error } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.createParty({
-      ...partyInput,
-      disponents: disponentsForBatch,
-      party: { ...partyInput.party, isRoot: true }
+  }
+  const mdm = context.env.MASTER_DATA_MANAGEMENT_SERVICE;
+  const docService = context.env.DOCUMENT_SERVICE;
+  if (partyInput.organizationData?.registerUri) {
+    await docService.acknowledgeDocument({
+      storageUrl: partyInput.organizationData.registerUri,
+      entityId: partyData.id
     });
-    if (!partyData || error) {
-      return context.json(
-        {
-          message: "Could not create a party"
-        },
-        500
-      );
-    }
-    const mdm = context.env.MASTER_DATA_MANAGEMENT_SERVICE;
-    const docService = context.env.DOCUMENT_SERVICE;
-    if (partyInput.organizationData?.registerUri) {
+  }
+  for (const ba of partyInput.bankAccounts ?? []) {
+    if (ba.statementUri) {
       await docService.acknowledgeDocument({
-        storageUrl: partyInput.organizationData.registerUri,
+        storageUrl: ba.statementUri,
         entityId: partyData.id
       });
     }
-    for (const ba of partyInput.bankAccounts ?? []) {
-      if (ba.statementUri) {
-        await docService.acknowledgeDocument({
-          storageUrl: ba.statementUri,
-          entityId: partyData.id
-        });
-      }
+  }
+  for (const [i, doc] of (partyInput.personalData?.identityDocuments ?? []).entries()) {
+    const idDocId = partyData.personalIdDocIds?.[i] ?? partyData.id;
+    if (doc.frontImageUri) {
+      await docService.acknowledgeDocument({
+        storageUrl: doc.frontImageUri,
+        entityId: idDocId
+      });
+    }
+    if (doc.backImageUri) {
+      await docService.acknowledgeDocument({
+        storageUrl: doc.backImageUri,
+        entityId: idDocId
+      });
+    }
+  }
+  for (const disponent of disponentsWithDocs) {
+    const { identityDocuments, ...individualData } = disponent.data;
+    const { data: disponentParty, error: disponentError } = await mdm.createParty({
+      party: {
+        partyType: "INDIVIDUAL",
+        language: partyInput.party.language,
+        customerStatus: "NEW"
+      },
+      personalData: individualData,
+      organizationData: null,
+      bankAccounts: null,
+      recipients: null,
+      disponents: null,
+      addresses: [],
+      aml: null
+    });
+    if (!disponentParty || disponentError) {
+      return context.json({ message: "Could not create disponent party" }, 500);
+    }
+    const { error: linkDisponentError } = await mdm.linkPartyToParty({
+      fromPartyId: disponentParty.id,
+      toPartyId: partyData.id,
+      relationshipType: "AUTHORIZED_SIGNATORY"
+    });
+    if (linkDisponentError) {
+      return context.json({ message: "Could not link disponent to party" }, 500);
     }
-    for (const [i, doc] of (partyInput.personalData?.identityDocuments ?? []).entries()) {
-      const idDocId = partyData.personalIdDocIds?.[i] ?? partyData.id;
+    for (const doc of identityDocuments ?? []) {
+      const { data: createdIdDoc, error: idDocError } = await mdm.createIdDocument({
+        partyId: disponentParty.id,
+        idDocument: {
+          partyId: disponentParty.id,
+          idDocType: doc.idDocType,
+          idDocNumber: doc.idDocNumber,
+          idDocHolderName: `${individualData.name} ${individualData.surname}`,
+          issueDate: doc.issueDate,
+          expirationDate: doc.expirationDate,
+          issuer: doc.issuer,
+          frontImageUri: doc.frontImageUri,
+          backImageUri: doc.backImageUri
+        }
+      });
+      if (!createdIdDoc || idDocError) {
+        return context.json(
+          { message: "Could not create disponent identity document" },
+          500
+        );
+      }
       if (doc.frontImageUri) {
         await docService.acknowledgeDocument({
           storageUrl: doc.frontImageUri,
-          entityId: idDocId
+          entityId: createdIdDoc.id
         });
       }
       if (doc.backImageUri) {
         await docService.acknowledgeDocument({
           storageUrl: doc.backImageUri,
-          entityId: idDocId
+          entityId: createdIdDoc.id
         });
       }
     }
-    for (const disponent of disponentsWithDocs) {
-      const { identityDocuments, ...individualData } = disponent.data;
-      const { data: disponentParty, error: disponentError } = await mdm.createParty({
+  }
+  if (owners?.length) {
+    for (const owner of owners) {
+      const { address, sharePercentage, shareEstablishedAt, ...individual } = owner;
+      const { data: ownerParty, error: ownerError } = await mdm.createParty({
         party: {
           partyType: "INDIVIDUAL",
           language: partyInput.party.language,
           customerStatus: "NEW"
         },
-        personalData: individualData,
+        personalData: { ...individual, email: individual.email ?? "" },
         organizationData: null,
         bankAccounts: null,
         recipients: null,
         disponents: null,
-        addresses: [],
+        addresses: [
+          {
+            ...address,
+            district: address.district ?? "",
+            region: address.region ?? ""
+          }
+        ],
         aml: null
       });
-      if (!disponentParty || disponentError) {
+      if (ownerParty && !ownerError) {
+        await mdm.linkPartyToParty({
+          fromPartyId: ownerParty.id,
+          toPartyId: partyData.id,
+          relationshipType: "UBO",
+          sharePercentage,
+          fromDate: new Date(shareEstablishedAt)
+        });
+      }
+    }
+  }
+  if (legalRepresentatives?.length) {
+    for (const rep of legalRepresentatives) {
+      const { address, identityDocuments, dateOfEstablishment, ...individual } = rep;
+      const { data: repParty, error: repError } = await mdm.createParty({
+        party: {
+          partyType: "INDIVIDUAL",
+          language: partyInput.party.language,
+          customerStatus: "NEW"
+        },
+        personalData: individual,
+        organizationData: null,
+        bankAccounts: null,
+        recipients: null,
+        disponents: null,
+        addresses: [
+          {
+            ...address,
+            district: address.district ?? "",
+            region: address.region ?? ""
+          }
+        ],
+        aml: null
+      });
+      if (!repParty || repError) {
         return context.json(
-          { message: "Could not create disponent party" },
+          { message: "Could not create legal representative party" },
           500
         );
       }
-      const { error: linkDisponentError } = await mdm.linkPartyToParty({
-        fromPartyId: disponentParty.id,
+      const { error: linkRepError } = await mdm.linkPartyToParty({
+        fromPartyId: repParty.id,
         toPartyId: partyData.id,
-        relationshipType: "AUTHORIZED_SIGNATORY"
+        relationshipType: "BOARD_MEMBER",
+        fromDate: new Date(dateOfEstablishment)
       });
-      if (linkDisponentError) {
+      if (linkRepError) {
         return context.json(
-          { message: "Could not link disponent to party" },
+          { message: "Could not link legal representative to party" },
           500
         );
       }
       for (const doc of identityDocuments ?? []) {
         const { data: createdIdDoc, error: idDocError } = await mdm.createIdDocument({
-          partyId: disponentParty.id,
+          partyId: repParty.id,
           idDocument: {
-            partyId: disponentParty.id,
+            partyId: repParty.id,
             idDocType: doc.idDocType,
             idDocNumber: doc.idDocNumber,
-            idDocHolderName: `${individualData.name} ${individualData.surname}`,
+            idDocHolderName: `${individual.name} ${individual.surname}`,
             issueDate: doc.issueDate,
             expirationDate: doc.expirationDate,
             issuer: doc.issuer,
@@ -731,7 +904,9 @@ new OpenAPIHono().openapi(
         });
         if (!createdIdDoc || idDocError) {
           return context.json(
-            { message: "Could not create disponent identity document" },
+            {
+              message: "Could not create legal representative identity document"
+            },
             500
           );
         }
@@ -749,133 +924,30 @@ new OpenAPIHono().openapi(
         }
       }
     }
-    if (owners?.length) {
-      for (const owner of owners) {
-        const { address, sharePercentage, shareEstablishedAt, ...individual } = owner;
-        const { data: ownerParty, error: ownerError } = await mdm.createParty({
-          party: {
-            partyType: "INDIVIDUAL",
-            language: partyInput.party.language,
-            customerStatus: "NEW"
-          },
-          personalData: { ...individual, email: individual.email ?? "" },
-          organizationData: null,
-          bankAccounts: null,
-          recipients: null,
-          disponents: null,
-          addresses: [
-            {
-              ...address,
-              district: address.district ?? "",
-              region: address.region ?? ""
-            }
-          ],
-          aml: null
-        });
-        if (ownerParty && !ownerError) {
-          await mdm.linkPartyToParty({
-            fromPartyId: ownerParty.id,
-            toPartyId: partyData.id,
-            relationshipType: "UBO",
-            sharePercentage,
-            fromDate: new Date(shareEstablishedAt)
-          });
-        }
-      }
-    }
-    if (legalRepresentatives?.length) {
-      for (const rep of legalRepresentatives) {
-        const {
-          address,
-          identityDocuments,
-          dateOfEstablishment,
-          ...individual
-        } = rep;
-        const { data: repParty, error: repError } = await mdm.createParty({
-          party: {
-            partyType: "INDIVIDUAL",
-            language: partyInput.party.language,
-            customerStatus: "NEW"
-          },
-          personalData: individual,
-          organizationData: null,
-          bankAccounts: null,
-          recipients: null,
-          disponents: null,
-          addresses: [
-            {
-              ...address,
-              district: address.district ?? "",
-              region: address.region ?? ""
-            }
-          ],
-          aml: null
-        });
-        if (!repParty || repError) {
-          return context.json(
-            { message: "Could not create legal representative party" },
-            500
-          );
-        }
-        const { error: linkRepError } = await mdm.linkPartyToParty({
-          fromPartyId: repParty.id,
-          toPartyId: partyData.id,
-          relationshipType: "BOARD_MEMBER",
-          fromDate: new Date(dateOfEstablishment)
-        });
-        if (linkRepError) {
-          return context.json(
-            { message: "Could not link legal representative to party" },
-            500
-          );
-        }
-        for (const doc of identityDocuments ?? []) {
-          const { data: createdIdDoc, error: idDocError } = await mdm.createIdDocument({
-            partyId: repParty.id,
-            idDocument: {
-              partyId: repParty.id,
-              idDocType: doc.idDocType,
-              idDocNumber: doc.idDocNumber,
-              idDocHolderName: `${individual.name} ${individual.surname}`,
-              issueDate: doc.issueDate,
-              expirationDate: doc.expirationDate,
-              issuer: doc.issuer,
-              frontImageUri: doc.frontImageUri,
-              backImageUri: doc.backImageUri
-            }
-          });
-          if (!createdIdDoc || idDocError) {
-            return context.json(
-              {
-                message: "Could not create legal representative identity document"
-              },
-              500
-            );
-          }
-          if (doc.frontImageUri) {
-            await docService.acknowledgeDocument({
-              storageUrl: doc.frontImageUri,
-              entityId: createdIdDoc.id
-            });
-          }
-          if (doc.backImageUri) {
-            await docService.acknowledgeDocument({
-              storageUrl: doc.backImageUri,
-              entityId: createdIdDoc.id
-            });
-          }
-        }
-      }
-    }
-    return context.json(
-      {
-        message: "party created",
-        party: partyData
-      },
-      200
-    );
   }
-);
+  logAuditEvent(context, {
+    eventType: "party.created",
+    targetType: "party",
+    targetId: partyData.id,
+    outcome: "success",
+    severity: "medium",
+    description: `Party ${partyData.id} created`,
+    details: {
+      partyType: partyInput.party.partyType,
+      disponentCount: partyInput.disponents?.length ?? 0,
+      bankAccountCount: partyInput.bankAccounts?.length ?? 0,
+      ownerCount: owners?.length ?? 0,
+      legalRepresentativeCount: legalRepresentatives?.length ?? 0
+    }
+  });
+  return context.json(
+    {
+      message: "party created",
+      party: partyData
+    },
+    200
+  );
+});
 
 const partySchema = z.object({
   partyType: z.enum(PARTY_TYPE),
@@ -883,7 +955,10 @@ const partySchema = z.object({
   id: z.uuid(),
   internalId: z.string().optional(),
   note: z.string().optional(),
-  countryCode: z.enum(COUNTRY_CODES).optional()
+  countryCode: z.enum(COUNTRY_CODES).optional(),
+  customerStatus: z.enum(CUSTOMER_STATUS).optional(),
+  blockReason: z.enum(BLOCK_REASON).nullable().optional(),
+  blockReasonNote: z.string().trim().min(1).nullable().optional()
 });
 const idDocumentInputSchema = z.object({
   id: z.uuid().optional(),
@@ -1134,6 +1209,21 @@ const partyUpdateInputSchema = z.object({
   aml: updateAmlInputSchema.optional(),
   products: productsInputSchema.optional(),
   traderIds: z.array(z.uuid()).optional()
+}).refine(
+  (b) => b.party.customerStatus !== "BLOCKED" || !!b.party.blockReason,
+  {
+    message: "blockReason is required when customerStatus is BLOCKED",
+    path: ["party", "blockReason"]
+  }
+).refine(
+  (b) => b.party.customerStatus === "BLOCKED" || b.party.customerStatus === void 0 || !b.party.blockReason && !b.party.blockReasonNote,
+  {
+    message: "blockReason and blockReasonNote must be null when customerStatus is not BLOCKED",
+    path: ["party", "blockReason"]
+  }
+).refine((b) => b.party.blockReason !== "OTHER" || !!b.party.blockReasonNote, {
+  message: "blockReasonNote is required when blockReason is OTHER",
+  path: ["party", "blockReasonNote"]
 });
 const updatePartyOuputSchema = z.object({
   id: z.uuid(),
@@ -1181,48 +1271,75 @@ const updatePartyRoute = createRoute({
     ...errorResponse("Party", "Update")
   }
 });
-new OpenAPIHono().openapi(
-  updatePartyRoute,
-  async (context) => {
-    const party = context.req.valid("json");
-    const { partyId } = context.req.valid("param");
-    const { data: updatedParty, error: partyError } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.updateParty({
-      partyId,
-      party: party.party,
-      personalData: party.personalData ?? void 0,
-      organizationData: party.organizationData ?? void 0,
-      bankAccounts: party.bankAccounts ?? void 0,
-      disponents: party.disponents ?? void 0,
-      addresses: party.addresses ?? void 0,
-      recipients: party.recipients ?? void 0,
-      aml: party.aml ?? void 0,
-      products: party.products ?? void 0,
-      traderIds: party.traderIds ?? void 0,
-      legalRepresentatives: party.legalRepresentatives ?? void 0,
-      owners: party.owners ?? void 0
+new OpenAPIHono().openapi(updatePartyRoute, async (context) => {
+  const party = context.req.valid("json");
+  const { partyId } = context.req.valid("param");
+  const { data: updatedParty, error: partyError } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.updateParty({
+    partyId,
+    party: party.party,
+    personalData: party.personalData ?? void 0,
+    organizationData: party.organizationData ?? void 0,
+    bankAccounts: party.bankAccounts ?? void 0,
+    disponents: party.disponents ?? void 0,
+    addresses: party.addresses ?? void 0,
+    recipients: party.recipients ?? void 0,
+    aml: party.aml ?? void 0,
+    products: party.products ?? void 0,
+    traderIds: party.traderIds ?? void 0,
+    legalRepresentatives: party.legalRepresentatives ?? void 0,
+    owners: party.owners ?? void 0
+  });
+  if (!updatedParty || partyError) {
+    logAuditEvent(context, {
+      eventType: "party.updated",
+      targetType: "party",
+      targetId: partyId,
+      outcome: "failure",
+      severity: "medium",
+      description: `Failed to update party ${partyId}`,
+      details: { partyType: party.party.partyType }
     });
-    if (!updatedParty || partyError) {
-      return context.json({ message: "Could not update a Party" }, 404);
-    }
-    const docService = context.env.DOCUMENT_SERVICE;
-    if (party.organizationData?.registerUri) {
+    return context.json({ message: "Could not update a Party" }, 404);
+  }
+  const docService = context.env.DOCUMENT_SERVICE;
+  if (party.organizationData?.registerUri) {
+    await docService.acknowledgeDocument({
+      storageUrl: party.organizationData.registerUri,
+      entityId: partyId
+    });
+  }
+  for (const ba of party.bankAccounts ?? []) {
+    if (ba.statementUri) {
       await docService.acknowledgeDocument({
-        storageUrl: party.organizationData.registerUri,
+        storageUrl: ba.statementUri,
         entityId: partyId
       });
     }
-    for (const ba of party.bankAccounts ?? []) {
-      if (ba.statementUri) {
+  }
+  if (party.personalData?.identityDocuments?.length) {
+    let newDocIdx = 0;
+    for (const doc of party.personalData.identityDocuments) {
+      const idDocEntityId = doc.id ? doc.id : updatedParty.newPersonalIdDocIds?.[newDocIdx++] ?? partyId;
+      if (doc.frontImageUri) {
         await docService.acknowledgeDocument({
-          storageUrl: ba.statementUri,
-          entityId: partyId
+          storageUrl: doc.frontImageUri,
+          entityId: idDocEntityId
+        });
+      }
+      if (doc.backImageUri) {
+        await docService.acknowledgeDocument({
+          storageUrl: doc.backImageUri,
+          entityId: idDocEntityId
         });
       }
     }
-    if (party.personalData?.identityDocuments?.length) {
-      let newDocIdx = 0;
-      for (const doc of party.personalData.identityDocuments) {
-        const idDocEntityId = doc.id ? doc.id : updatedParty.newPersonalIdDocIds?.[newDocIdx++] ?? partyId;
+  }
+  if (party.legalRepresentatives?.length) {
+    let newBmDocIdx = 0;
+    for (const rep of party.legalRepresentatives) {
+      if (rep.id) continue;
+      for (const doc of rep.identityDocuments ?? []) {
+        const idDocEntityId = updatedParty.newBoardMemberIdDocIds?.[newBmDocIdx++] ?? partyId;
         if (doc.frontImageUri) {
           await docService.acknowledgeDocument({
             storageUrl: doc.frontImageUri,
@@ -1237,54 +1354,45 @@ new OpenAPIHono().openapi(
         }
       }
     }
-    if (party.legalRepresentatives?.length) {
-      let newBmDocIdx = 0;
-      for (const rep of party.legalRepresentatives) {
-        if (rep.id) continue;
-        for (const doc of rep.identityDocuments ?? []) {
-          const idDocEntityId = updatedParty.newBoardMemberIdDocIds?.[newBmDocIdx++] ?? partyId;
-          if (doc.frontImageUri) {
-            await docService.acknowledgeDocument({
-              storageUrl: doc.frontImageUri,
-              entityId: idDocEntityId
-            });
-          }
-          if (doc.backImageUri) {
-            await docService.acknowledgeDocument({
-              storageUrl: doc.backImageUri,
-              entityId: idDocEntityId
-            });
-          }
+    for (const rep of party.legalRepresentatives) {
+      if (!rep.id) continue;
+      for (const doc of rep.identityDocuments ?? []) {
+        const idDocEntityId = doc.id ? doc.id : updatedParty.newBoardMemberIdDocIds?.[newBmDocIdx++] ?? partyId;
+        if (doc.frontImageUri) {
+          await docService.acknowledgeDocument({
+            storageUrl: doc.frontImageUri,
+            entityId: idDocEntityId
+          });
         }
-      }
-      for (const rep of party.legalRepresentatives) {
-        if (!rep.id) continue;
-        for (const doc of rep.identityDocuments ?? []) {
-          const idDocEntityId = doc.id ? doc.id : updatedParty.newBoardMemberIdDocIds?.[newBmDocIdx++] ?? partyId;
-          if (doc.frontImageUri) {
-            await docService.acknowledgeDocument({
-              storageUrl: doc.frontImageUri,
-              entityId: idDocEntityId
-            });
-          }
-          if (doc.backImageUri) {
-            await docService.acknowledgeDocument({
-              storageUrl: doc.backImageUri,
-              entityId: idDocEntityId
-            });
-          }
+        if (doc.backImageUri) {
+          await docService.acknowledgeDocument({
+            storageUrl: doc.backImageUri,
+            entityId: idDocEntityId
+          });
         }
       }
     }
-    return context.json(
-      {
-        message: "Party updated successfully",
-        party: updatedParty
-      },
-      200
-    );
   }
-);
+  logAuditEvent(context, {
+    eventType: "party.updated",
+    targetType: "party",
+    targetId: partyId,
+    outcome: "success",
+    severity: "medium",
+    description: `Party ${partyId} updated`,
+    details: {
+      partyType: party.party.partyType,
+      customerStatus: updatedParty.customerStatus
+    }
+  });
+  return context.json(
+    {
+      message: "Party updated successfully",
+      party: updatedParty
+    },
+    200
+  );
+});
 
 const DOCUMENT_SIDE = ["front", "back"];
 const paramsSchema$2 = z.object({
@@ -1388,64 +1496,91 @@ const createDocumentRoute = createRoute({
     }
   }
 });
-new OpenAPIHono().openapi(
-  createDocumentRoute,
-  async (context) => {
-    const rawBody = await context.req.parseBody();
-    const { partyId } = context.req.valid("param");
-    const idDocumentRaw = rawBody.idDocument;
-    const documentSide = rawBody.documentSide;
-    const file = rawBody.file;
-    if (typeof idDocumentRaw !== "string" || !DOCUMENT_SIDE.includes(documentSide) || !(file instanceof File)) {
-      return context.json({ message: "Invalid multipart payload" }, 400);
-    }
-    const idDocumentJson = JSON.parse(JSON.parse(idDocumentRaw));
-    const idDocumentResult = idDocumentCreateInputSchema.safeParse(idDocumentJson);
-    if (!idDocumentResult.success) {
-      console.error(idDocumentResult.error);
-      return context.json({ message: "Could not parse IdDocument" }, 400);
-    }
-    const {
-      data: createdIdDocument,
-      error: createError,
-      message
-    } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.createIdDocument({
-      idDocument: idDocumentResult.data,
-      partyId
+new OpenAPIHono().openapi(createDocumentRoute, async (context) => {
+  const rawBody = await context.req.parseBody();
+  const { partyId } = context.req.valid("param");
+  const idDocumentRaw = rawBody.idDocument;
+  const documentSide = rawBody.documentSide;
+  const file = rawBody.file;
+  if (typeof idDocumentRaw !== "string" || !DOCUMENT_SIDE.includes(documentSide) || !(file instanceof File)) {
+    return context.json({ message: "Invalid multipart payload" }, 400);
+  }
+  const idDocumentJson = JSON.parse(JSON.parse(idDocumentRaw));
+  const idDocumentResult = idDocumentCreateInputSchema.safeParse(idDocumentJson);
+  if (!idDocumentResult.success) {
+    console.error(idDocumentResult.error);
+    return context.json({ message: "Could not parse IdDocument" }, 400);
+  }
+  const {
+    data: createdIdDocument,
+    error: createError,
+    message
+  } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.createIdDocument({
+    idDocument: idDocumentResult.data,
+    partyId
+  });
+  if (!createdIdDocument || createError) {
+    console.error(message);
+    logAuditEvent(context, {
+      eventType: "id-document.created",
+      targetType: "id-document",
+      outcome: "failure",
+      severity: "medium",
+      description: `Failed to create ID document for party ${partyId}`,
+      details: { partyId, idDocType: idDocumentResult.data.idDocType }
     });
-    if (!createdIdDocument || createError) {
-      console.error(message);
-      return context.json({ message: "Could not create IdDocument" }, 500);
+    return context.json({ message: "Could not create IdDocument" }, 500);
+  }
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  const { data: uploadResult, error: uploadError } = await context.env.DOCUMENT_SERVICE.uploadDocument({
+    entityType: "client",
+    entityId: createdIdDocument.id,
+    type: "kyc",
+    metadata: {},
+    file: {
+      bytes,
+      type: file.type,
+      name: file.name,
+      size: file.size
     }
-    const bytes = new Uint8Array(await file.arrayBuffer());
-    const { data: uploadResult, error: uploadError } = await context.env.DOCUMENT_SERVICE.uploadDocument({
-      entityType: "client",
-      entityId: createdIdDocument.id,
-      type: "kyc",
-      metadata: {},
-      file: {
-        bytes,
-        type: file.type,
-        name: file.name,
-        size: file.size
-      }
+  });
+  if (!uploadResult || uploadError) {
+    logAuditEvent(context, {
+      eventType: "id-document.created",
+      targetType: "id-document",
+      targetId: createdIdDocument.id,
+      outcome: "error",
+      severity: "medium",
+      description: `ID document ${createdIdDocument.id} created but file upload failed`,
+      details: { partyId, documentSide }
     });
-    if (!uploadResult || uploadError) {
-      return context.json({ message: "File upload failed" }, 500);
-    }
-    return context.json(
-      {
-        message: "IdDocument created successfully",
-        idDocument: {
-          ...createdIdDocument,
-          frontImageUri: documentSide === "front" ? uploadResult.storageUrl : createdIdDocument.frontImageUri,
-          backImageUri: documentSide === "back" ? uploadResult.storageUrl : createdIdDocument.backImageUri
-        }
-      },
-      200
-    );
+    return context.json({ message: "File upload failed" }, 500);
   }
-);
+  logAuditEvent(context, {
+    eventType: "id-document.created",
+    targetType: "id-document",
+    targetId: createdIdDocument.id,
+    outcome: "success",
+    severity: "medium",
+    description: `ID document ${createdIdDocument.id} created for party ${partyId}`,
+    details: {
+      partyId,
+      idDocType: createdIdDocument.idDocType,
+      documentSide
+    }
+  });
+  return context.json(
+    {
+      message: "IdDocument created successfully",
+      idDocument: {
+        ...createdIdDocument,
+        frontImageUri: documentSide === "front" ? uploadResult.storageUrl : createdIdDocument.frontImageUri,
+        backImageUri: documentSide === "back" ? uploadResult.storageUrl : createdIdDocument.backImageUri
+      }
+    },
+    200
+  );
+});
 
 const partyBaseOutputSchema = z.object({
   customerStatus: z.enum(CUSTOMER_STATUS),
@@ -1960,35 +2095,57 @@ const updateIdDocumentRoute = createRoute({
     }
   }
 });
-new OpenAPIHono().openapi(
-  updateIdDocumentRoute,
-  async (context) => {
-    const { id } = context.req.valid("param");
-    const patch = context.req.valid("json");
-    const { data: existingDocument, error: fetchError } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.getIdDocument({ id });
-    if (!existingDocument || fetchError) {
-      return context.json({ message: "ID document not found" }, 404);
-    }
-    const fullIdDocument = {
-      ...existingDocument,
-      ...patch,
-      id
-    };
-    const { data: updatedIdDocument, error: updateError } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.updateIdDocument({
-      idDocument: fullIdDocument
+new OpenAPIHono().openapi(updateIdDocumentRoute, async (context) => {
+  const { id } = context.req.valid("param");
+  const patch = context.req.valid("json");
+  const { data: existingDocument, error: fetchError } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.getIdDocument({ id });
+  if (!existingDocument || fetchError) {
+    logAuditEvent(context, {
+      eventType: "id-document.updated",
+      targetType: "id-document",
+      targetId: id,
+      outcome: "failure",
+      severity: "medium",
+      description: `Failed to update ID document ${id}: not found`
     });
-    if (!updatedIdDocument || updateError) {
-      return context.json({ message: "Could not update ID document" }, 500);
-    }
-    return context.json(
-      {
-        message: "ID document updated successfully",
-        idDocument: updatedIdDocument
-      },
-      200
-    );
+    return context.json({ message: "ID document not found" }, 404);
   }
-);
+  const fullIdDocument = {
+    ...existingDocument,
+    ...patch,
+    id
+  };
+  const { data: updatedIdDocument, error: updateError } = await context.env.MASTER_DATA_MANAGEMENT_SERVICE.updateIdDocument({
+    idDocument: fullIdDocument
+  });
+  if (!updatedIdDocument || updateError) {
+    logAuditEvent(context, {
+      eventType: "id-document.updated",
+      targetType: "id-document",
+      targetId: id,
+      outcome: "failure",
+      severity: "medium",
+      description: `Failed to update ID document ${id}`
+    });
+    return context.json({ message: "Could not update ID document" }, 500);
+  }
+  logAuditEvent(context, {
+    eventType: "id-document.updated",
+    targetType: "id-document",
+    targetId: id,
+    outcome: "success",
+    severity: "medium",
+    description: `ID document ${id} updated`,
+    details: { partyId: updatedIdDocument.partyId }
+  });
+  return context.json(
+    {
+      message: "ID document updated successfully",
+      idDocument: updatedIdDocument
+    },
+    200
+  );
+});
 
 const messageResponseSchema = z.object({
   message: z.string()