> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Generate regulatory alerts

Alerts aggregate client and transaction data for regulatory reporting.

## Alert Workflow

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

## Creating Alerts

<Tabs>
  <Tab title="Base">
    With the base SDK, use nested `scopeData` format:

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

    console.log(alert.id);
    console.log(alert.status); // "draft"
    ```
  </Tab>

  <Tab title="Mexico">
    With a Mexico-scoped SDK, specify the activity type:

    ```typescript theme={null}
    const alert = await sdk.alerts.create({
      actividadVulnerable: {
        AVI: {
          mesReportado: "202401",
        },
      },
    });
    ```
  </Tab>

  <Tab title="Mexico AVI">
    With an AVI-scoped SDK, input is fully flattened:

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

    console.log(alert.mesReportado); // "202401"
    console.log(alert.formattedPeriod); // "January 2024"
    ```
  </Tab>

  <Tab title="Mexico JYS">
    With a JYS-scoped SDK:

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

    console.log(alert.mesReportado);
    console.log(alert.formattedPeriod);
    ```
  </Tab>

  <Tab title="Mexico TSC">
    With a TSC-scoped SDK:

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

    console.log(alert.mesReportado);
    console.log(alert.formattedPeriod);
    ```
  </Tab>
</Tabs>

## Adding Alert Items

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    // 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`);
    ```
  </Tab>

  <Tab title="Mexico">
    Same as Base. Returns `MexAlertItem` models.

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

    console.log(item.isActividadVulnerable);
    ```
  </Tab>

  <Tab title="Mexico AVI">
    AVI items support additional fields for alerts and amendments:

    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Mexico JYS">
    JYS items support additional fields for alerts and amendments:

    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Mexico TSC">
    TSC items support additional fields for alerts and amendments:

    ```typescript theme={null}
    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);
    ```
  </Tab>
</Tabs>

## Managing Alert Items

### Get an Item

```typescript theme={null}
const item = await sdk.alerts.getItem(alert.id, "item_xyz");
```

### Update an Item

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

### Remove Items

```typescript theme={null}
// 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

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

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

## Validating Alerts

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    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}`);
      }
    }
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    const validation = await sdk.alerts.validateReport({
      alertId: alert.id,
      actividadVulnerable: "AVI",
      defaults: {
        rfc: "EMP200101XXX",
        platformDomain: "https://example.com",
      },
    });
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    // Scope and activity are implicit
    const validation = await sdk.alerts.validateReport({
      alertId: alert.id,
      defaults: {
        rfc: "EMP200101XXX",
        platformDomain: "https://example.com",
      },
    });
    ```
  </Tab>

  <Tab title="Mexico JYS">
    ```typescript theme={null}
    const validation = await sdk.alerts.validateReport({
      alertId: alert.id,
      defaults: {
        rfc: "EMP200101XXX",
      },
    });
    ```
  </Tab>

  <Tab title="Mexico TSC">
    ```typescript theme={null}
    const validation = await sdk.alerts.validateReport({
      alertId: alert.id,
      defaults: {
        rfc: "EMP200101XXX",
      },
    });
    ```
  </Tab>
</Tabs>

## Generating Alerts

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

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    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
    }
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    const result = await sdk.alerts.generateReport({
      alertId: alert.id,
      actividadVulnerable: "AVI",
      defaults: {
        rfc: "EMP200101XXX",
        platformDomain: "https://example.com",
      },
    });
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    const result = await sdk.alerts.generateReport({
      alertId: alert.id,
      defaults: {
        rfc: "EMP200101XXX",
        platformDomain: "https://example.com",
      },
    });

    console.log(result.xml);
    ```
  </Tab>

  <Tab title="Mexico JYS">
    ```typescript theme={null}
    const result = await sdk.alerts.generateReport({
      alertId: alert.id,
      defaults: {
        rfc: "EMP200101XXX",
      },
    });
    ```
  </Tab>

  <Tab title="Mexico TSC">
    ```typescript theme={null}
    const result = await sdk.alerts.generateReport({
      alertId: alert.id,
      defaults: {
        rfc: "EMP200101XXX",
      },
    });
    ```
  </Tab>
</Tabs>

## 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

```typescript theme={null}
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](/sdk/resources)).

## Listing Alerts

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    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);
    }
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    // Automatically filtered to Mexico alerts
    for await (const alert of sdk.alerts.iterate()) {
      // alert is MexAlert
      console.log(alert.activityCodes);
    }
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    for await (const alert of sdk.alerts.iterate()) {
      // alert is MexAVIAlert
      console.log(alert.mesReportado);
    }
    ```
  </Tab>

  <Tab title="Mexico JYS">
    ```typescript theme={null}
    for await (const alert of sdk.alerts.iterate()) {
      // alert is MexJYSAlert
      console.log(alert.mesReportado);
    }
    ```
  </Tab>

  <Tab title="Mexico TSC">
    ```typescript theme={null}
    for await (const alert of sdk.alerts.iterate()) {
      // alert is MexTSCAlert
      console.log(alert.mesReportado);
    }
    ```
  </Tab>
</Tabs>

## Updating Alerts

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

## Deleting Alerts

```typescript theme={null}
await sdk.alerts.delete("alert_abc123");
```

## Alert Model Properties

<Tabs>
  <Tab title="Base">
    | 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     |
  </Tab>

  <Tab title="Mexico">
    Includes all Base properties plus:

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

  <Tab title="Mexico AVI">
    Includes all Mexico properties plus:

    | Property          | Type                  | Description                             |
    | ----------------- | --------------------- | --------------------------------------- |
    | `mesReportado`    | `string \| undefined` | Reporting period (YYYYMM)               |
    | `formattedPeriod` | `string \| undefined` | Formatted period (e.g., "January 2024") |
  </Tab>

  <Tab title="Mexico JYS">
    Includes all Mexico properties plus:

    | Property          | Type                  | Description                             |
    | ----------------- | --------------------- | --------------------------------------- |
    | `mesReportado`    | `string \| undefined` | Reporting period (YYYYMM)               |
    | `formattedPeriod` | `string \| undefined` | Formatted period (e.g., "January 2024") |
  </Tab>

  <Tab title="Mexico TSC">
    Includes all Mexico properties plus:

    | Property          | Type                  | Description                             |
    | ----------------- | --------------------- | --------------------------------------- |
    | `mesReportado`    | `string \| undefined` | Reporting period (YYYYMM)               |
    | `formattedPeriod` | `string \| undefined` | Formatted period (e.g., "January 2024") |
  </Tab>
</Tabs>

## Alert Item Model Properties

<Tabs>
  <Tab title="Base">
    | 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         |
  </Tab>

  <Tab title="Mexico">
    Includes all Base properties plus:

    | Property                | Type      | Description                        |
    | ----------------------- | --------- | ---------------------------------- |
    | `isActividadVulnerable` | `boolean` | True if has activity-specific data |
  </Tab>

  <Tab title="Mexico AVI">
    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 |
  </Tab>

  <Tab title="Mexico JYS">
    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 |
  </Tab>

  <Tab title="Mexico TSC">
    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 |
  </Tab>
</Tabs>