Alerts - Artu Compliance SDK

Alerts aggregate client and transaction data for regulatory reporting.

Alert Workflow

Create an alert with the reporting period
Add items (transactions) to the alert
Validate the alert for completeness
Generate the output (e.g., XML for Mexico)

Creating Alerts

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

With the base SDK, use nested scopeData format:

const alert = await sdk.alerts.create({
  scopeData: {
    MX: {
      actividadVulnerable: {
        AVI: {
          mesReportado: "202401", // January 2024
        },
      },
    },
  },
});

console.log(alert.id);
console.log(alert.status); // "draft"

With a Mexico-scoped SDK, specify the activity type:

const alert = await sdk.alerts.create({
  actividadVulnerable: {
    AVI: {
      mesReportado: "202401",
    },
  },
});

With an AVI-scoped SDK, input is fully flattened:

const alert = await sdk.alerts.create({
  mesReportado: "202401",
});

console.log(alert.mesReportado); // "202401"
console.log(alert.formattedPeriod); // "January 2024"

With a JYS-scoped SDK:

const alert = await sdk.alerts.create({
  mesReportado: "202401",
});

console.log(alert.mesReportado);
console.log(alert.formattedPeriod);

With a TSC-scoped SDK:

const alert = await sdk.alerts.create({
  mesReportado: "202401",
});

console.log(alert.mesReportado);
console.log(alert.formattedPeriod);

Adding Alert Items

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

// Add a single item
const item = await sdk.alerts.addItem(alert.id, {
  transactionId: "txn_abc123",
});

// Add multiple items
const { added, items } = await sdk.alerts.addItems(alert.id, [
  { transactionId: "txn_abc123" },
  { transactionId: "txn_def456" },
]);

console.log(`Added ${added} items`);

Same as Base. Returns MexAlertItem models.

const item = await sdk.alerts.addItem(alert.id, {
  transactionId: "txn_abc123",
});

console.log(item.isActividadVulnerable);

AVI items support additional fields for alerts and amendments:

import { Enums } from "@artu-ai/compliance-sdk/mx/av/avi";
const { TipoAlerta } = Enums;

const item = await sdk.alerts.addItem(alert.id, {
  transactionId: "txn_abc123",
  alertType: TipoAlerta.NoAlert, // "100" - Monthly alert (no alert)
  // Or for suspicious activity:
  // alertType: TipoAlerta.RapidMovement, // "4101"
  // alertType: TipoAlerta.PEP, // "4119"
  alertDescription: "Unusual activity detected",
  amendment: { originalFolio: "ABC123", reason: "correction" },
});

// item is MexAVIAlertItem
console.log(item.alertType);
console.log(item.isAmendment);

JYS items support additional fields for alerts and amendments:

import { Enums } from "@artu-ai/compliance-sdk/mx/av/jys";
const { TipoAlerta } = Enums;

const item = await sdk.alerts.addItem(alert.id, {
  transactionId: "txn_abc123",
  alertType: TipoAlerta.NoAlert, // "100" - No alert
  // Or for suspicious activity:
  // alertType: TipoAlerta.FrequentHighValuePrizeClaims, // "2113"
  // alertType: TipoAlerta.ChipPurchaseWithLittlePlay, // "2106"
  alertDescription: "High-value prize claim",
});

// item is MexJYSAlertItem
console.log(item.alertType);

TSC items support additional fields for alerts and amendments:

import { Enums } from "@artu-ai/compliance-sdk/mx/av/tsc";
const { TipoAlerta } = Enums;

const item = await sdk.alerts.addItem(alert.id, {
  transactionId: "txn_abc123",
  alertType: TipoAlerta.NoAlert, // "100" - No alert
  // Or for suspicious activity:
  // alertType: TipoAlerta.OutOfTransactionalProfile, // "2201"
  // alertType: TipoAlerta.RecurrentHighCashPayments, // "2202"
});

// item is MexTSCAlertItem
console.log(item.alertType);

Managing Alert Items

Get an Item

const item = await sdk.alerts.getItem(alert.id, "item_xyz");

Update an Item

const updated = await sdk.alerts.updateItem(alert.id, "item_xyz", {
  metadata: { reviewed: true },
});

Remove Items

// Remove one item
await sdk.alerts.removeItem(alert.id, "item_xyz");

// Remove multiple items
const { removed } = await sdk.alerts.removeItems(alert.id, [
  "item_a",
  "item_b",
]);

List Items

const { data, pagination } = await sdk.alerts.listItems(alert.id, {
  limit: 50,
});

for (const item of data) {
  console.log(item.id, item.transactionId);
}

Validating Alerts

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

const validation = await sdk.alerts.validateReport({
  alertId: alert.id,
  scope: "MX",
  actividadVulnerable: "AVI",
  defaults: {
    rfc: "EMP200101XXX",
    platformDomain: "https://example.com",
  },
});

if (validation.valid) {
  console.log("Alert is valid!");
} else {
  for (const error of validation.errors) {
    console.log(`- ${error.path}: ${error.message}`);
  }
}

const validation = await sdk.alerts.validateReport({
  alertId: alert.id,
  actividadVulnerable: "AVI",
  defaults: {
    rfc: "EMP200101XXX",
    platformDomain: "https://example.com",
  },
});

// Scope and activity are implicit
const validation = await sdk.alerts.validateReport({
  alertId: alert.id,
  defaults: {
    rfc: "EMP200101XXX",
    platformDomain: "https://example.com",
  },
});

const validation = await sdk.alerts.validateReport({
  alertId: alert.id,
  defaults: {
    rfc: "EMP200101XXX",
  },
});

const validation = await sdk.alerts.validateReport({
  alertId: alert.id,
  defaults: {
    rfc: "EMP200101XXX",
  },
});

Generating Alerts

Generate the output file (e.g., XML for Mexico):

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

const result = await sdk.alerts.generate({
  alertId: alert.id,
  scope: "MX",
  actividadVulnerable: "AVI",
  defaults: {
    rfc: "EMP200101XXX",
    platformDomain: "https://example.com",
  },
});

if (result.success) {
  console.log("Generated:", result.filename);
  // result.content contains the XML
}

const result = await sdk.alerts.generateReport({
  alertId: alert.id,
  actividadVulnerable: "AVI",
  defaults: {
    rfc: "EMP200101XXX",
    platformDomain: "https://example.com",
  },
});

const result = await sdk.alerts.generateReport({
  alertId: alert.id,
  defaults: {
    rfc: "EMP200101XXX",
    platformDomain: "https://example.com",
  },
});

console.log(result.xml);

const result = await sdk.alerts.generateReport({
  alertId: alert.id,
  defaults: {
    rfc: "EMP200101XXX",
  },
});

const result = await sdk.alerts.generateReport({
  alertId: alert.id,
  defaults: {
    rfc: "EMP200101XXX",
  },
});

Alert Status

Status	Description
`draft`	Alert is being prepared
`validating`	Validation in progress
`valid`	Alert passed validation
`invalid`	Alert has validation errors
`notApplicable`	No reportable items for period

Retrieving Alerts

const alert = await sdk.alerts.retrieve("alert_abc123");

console.log(alert.id);
console.log(alert.status);
console.log(alert.createdAt);

You can also retrieve by externalId or metadata with retrieveByExternalId / retrieveByMetadata (see SDK reference).

Listing Alerts

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

const { data } = await sdk.alerts.list({
  filter: { status: "draft" },
  limit: 20,
});

for await (const alert of sdk.alerts.iterate()) {
  console.log(alert.id, alert.status);
}

// Automatically filtered to Mexico alerts
for await (const alert of sdk.alerts.iterate()) {
  // alert is MexAlert
  console.log(alert.activityCodes);
}

for await (const alert of sdk.alerts.iterate()) {
  // alert is MexAVIAlert
  console.log(alert.mesReportado);
}

for await (const alert of sdk.alerts.iterate()) {
  // alert is MexJYSAlert
  console.log(alert.mesReportado);
}

for await (const alert of sdk.alerts.iterate()) {
  // alert is MexTSCAlert
  console.log(alert.mesReportado);
}

Updating Alerts

const updated = await sdk.alerts.update("alert_abc123", {
  metadata: {
    preparedBy: "admin@example.com",
  },
});

Deleting Alerts

await sdk.alerts.delete("alert_abc123");

Alert Model Properties

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

Property	Type	Description
`id`	`string`	Unique identifier
`status`	`AlertStatus`	Current status
`scopeData`	`object`	Scope-specific data
`itemCount`	`number`	Number of items
`isDraft`	`boolean`	True if status is draft
`isValid`	`boolean`	True if status is valid
`canEdit`	`boolean`	True if alert is editable
`canGenerate`	`boolean`	True if can be generated
`metadata`	`object \| undefined`	Custom metadata
`createdAt`	`Date`	Creation timestamp
`updatedAt`	`Date`	Last update timestamp

Includes all Base properties plus:

Property	Type	Description
`isActividadVulnerable`	`boolean`	True if for an Actividad Vulnerable
`activityCodes`	`string[]`	Activity codes (e.g., `["AVI"]`)

Includes all Mexico properties plus:

Property	Type	Description
`mesReportado`	`string \| undefined`	Reporting period (YYYYMM)
`formattedPeriod`	`string \| undefined`	Formatted period (e.g., “January 2024”)

Includes all Mexico properties plus:

Property	Type	Description
`mesReportado`	`string \| undefined`	Reporting period (YYYYMM)
`formattedPeriod`	`string \| undefined`	Formatted period (e.g., “January 2024”)

Includes all Mexico properties plus:

Property	Type	Description
`mesReportado`	`string \| undefined`	Reporting period (YYYYMM)
`formattedPeriod`	`string \| undefined`	Formatted period (e.g., “January 2024”)

Alert Item Model Properties

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

Property	Type	Description
`id`	`string`	Unique identifier
`alertId`	`string`	Parent alert ID
`transactionId`	`string \| undefined`	Transaction ID
`clientId`	`string \| undefined`	Client ID
`clientName`	`string \| undefined`	Client name (denormalized)
`transactionAmount`	`number \| undefined`	Amount (denormalized)
`transactionCurrency`	`string \| undefined`	Currency (denormalized)
`transactionDate`	`string \| undefined`	Date (denormalized)
`isTransactionBased`	`boolean`	True if based on transaction
`isClientOnly`	`boolean`	True if client-only item
`hasErrors`	`boolean`	True if has validation errors
`hasWarnings`	`boolean`	True if has warnings
`validationErrors`	`array`	Validation errors
`createdAt`	`Date`	Creation timestamp
`updatedAt`	`Date`	Last update timestamp

Includes all Base properties plus:

Property	Type	Description
`isActividadVulnerable`	`boolean`	True if has activity-specific data

Includes all Mexico properties plus:

Property	Type	Description
`alertType`	`TipoAlerta`	Alert type code
`alertDescription`	`string \| undefined`	Alert description
`amendment`	`object \| undefined`	Amendment data
`isAmendment`	`boolean`	True if this is an amendment

Includes all Mexico properties plus:

Property	Type	Description
`alertType`	`TipoAlerta`	Alert type code
`alertDescription`	`string \| undefined`	Alert description
`amendment`	`object \| undefined`	Amendment data
`isAmendment`	`boolean`	True if this is an amendment

Includes all Mexico properties plus:

Property	Type	Description
`alertType`	`TipoAlerta`	Alert type code
`alertDescription`	`string \| undefined`	Alert description
`amendment`	`object \| undefined`	Amendment data
`isAmendment`	`boolean`	True if this is an amendment

​Alert Workflow

​Creating Alerts

​Adding Alert Items

​Managing Alert Items

​Get an Item

​Update an Item

​Remove Items

​List Items

​Validating Alerts

​Generating Alerts

​Alert Status

​Retrieving Alerts

​Listing Alerts

​Updating Alerts

​Deleting Alerts

​Alert Model Properties

​Alert Item Model Properties

Alert Workflow

Creating Alerts

Adding Alert Items

Managing Alert Items

Get an Item

Update an Item

Remove Items

List Items

Validating Alerts

Generating Alerts

Alert Status

Retrieving Alerts

Listing Alerts

Updating Alerts

Deleting Alerts

Alert Model Properties

Alert Item Model Properties