@artu-ai/compliance-sdk 0.14.0 → 0.17.0

package/dist/resources/mx/av/veh/alerts.js

@@ -0,0 +1,442 @@
+/**
+ * VEH (Vehículos) Alerts Resource
+ *
+ * Extends MexAlertsResource with VEH-specific behavior:
+ * - Accepts flattened CreateVEHAlertInput (VEH fields at root level)
+ * - Returns MexVEHAlert models
+ */
+import { CodigoActividad, createVEHAlertInputSchema, createVEHAlertItemInputSchema, ReportType, transformSort, updateVEHAlertInputSchema, updateVEHAlertItemInputSchema, upsertVEHAlertInputSchema, vehAlertSortingFieldMapping, vehDefaultsInputSchema, } from "@artu-ai/shared";
+import { z } from "zod";
+import { MexVEHAlert, MexVEHAlertClientItem, MexVEHAlertItem, MexVEHAlertTransactionItem, } from "../../../../models";
+import { AlertItemsResource } from "../../../alert-items";
+import { AVAlertsResource } from "../alerts";
+// ===========================
+// VEHAlertsResource
+// ===========================
+/**
+ * VEH (Vehículos) scoped alerts resource.
+ *
+ * @example
+ * ```typescript
+ * const vehSdk = new ComplianceSDK({
+ *   apiKey,
+ *   scope: "MX:AV:VEH",
+ * });
+ *
+ * const alert = await vehSdk.alerts.create({
+ *   mesReportado: "202401",
+ * });
+ *
+ * // Returns MexVEHAlert
+ * console.log(alert.mesReportado);
+ * ```
+ */
+export class VEHAlertsResource extends AVAlertsResource {
+    // ─────────────────────────────────────────────────────────────────
+    // Alert CRUD
+    // ─────────────────────────────────────────────────────────────────
+    async create(data) {
+        const validated = this.validate(createVEHAlertInputSchema, data);
+        const nestedData = this.transformToNested(validated);
+        const response = await this.execute(() => this.trpc.alerts.create.mutate(nestedData));
+        return this.instantiate(response);
+    }
+    async retrieve(id, opts) {
+        const response = await this.execute(() => this.trpc.alerts.retrieve.query({
+            id,
+            requireScope: this.buildRequireScope(opts?.crossScope),
+        }));
+        return this.instantiate(response);
+    }
+    async retrieveByMetadata(key, value, opts) {
+        const response = await this.execute(() => this.trpc.alerts.retrieveByMetadata.query({
+            key,
+            value,
+            requireScope: this.buildRequireScope(opts?.crossScope),
+        }));
+        return this.instantiate(response);
+    }
+    async retrieveByExternalId(externalId, opts) {
+        const response = await this.execute(() => this.trpc.alerts.retrieveByExternalId.query({
+            externalId,
+            requireScope: this.buildRequireScope(opts?.crossScope),
+        }));
+        return this.instantiate(response);
+    }
+    async update(id, data) {
+        const validated = this.validate(updateVEHAlertInputSchema, data);
+        const nestedData = this.transformUpdateToNested(validated);
+        const response = await this.execute(() => this.trpc.alerts.update.mutate({ id, data: nestedData }));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // List & Pagination
+    // ─────────────────────────────────────────────────────────────────
+    async list(options) {
+        const { crossScope, ...rest } = options ?? {};
+        const scopedFilter = this.applyAutoScope(this.applyScopeToFilter(rest.filter), crossScope);
+        const scopedSort = this.applyScopeToSort(rest.sort);
+        const response = await this.execute(() => this.trpc.alerts.list.query({
+            ...rest,
+            filter: scopedFilter,
+            sort: scopedSort,
+        }));
+        return {
+            data: response.data.map((r) => this.instantiate(r)),
+            pagination: response.pagination,
+        };
+    }
+    iterate(options) {
+        // Do NOT apply scope here — createIterator calls this.list(), which
+        // applies the flatten transform AND auto-scope exactly once.
+        return this.createIterator({
+            filter: options?.filter,
+            sort: options?.sort,
+            pageSize: options?.pageSize,
+            crossScope: options?.crossScope,
+        });
+    }
+    async count(filter, options) {
+        const scopedFilter = this.applyAutoScope(this.applyScopeToFilter(filter), options?.crossScope);
+        const response = await this.execute(() => this.trpc.alerts.count.query({ filter: scopedFilter }));
+        return response.count;
+    }
+    async createMany(alerts, options = {}) {
+        const atomic = options.atomic ?? true;
+        const validated = this.validate(z.array(createVEHAlertInputSchema), alerts);
+        const nestedItems = validated.map((r) => this.transformToNested(r));
+        const response = await this.execute(() => this.trpc.alerts.createMany.mutate({ items: nestedItems, atomic }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((r) => this.instantiate(r)),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: this.instantiate(item.data),
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    async updateMany(updates, options = {}) {
+        const atomic = options.atomic ?? true;
+        const updateItemSchema = z.object({
+            id: z.uuid(),
+            data: updateVEHAlertInputSchema,
+        });
+        const validated = this.validate(z.array(updateItemSchema), updates);
+        const nestedUpdates = validated.map((u) => ({
+            id: u.id,
+            data: this.transformUpdateToNested(u.data),
+        }));
+        const response = await this.execute(() => this.trpc.alerts.updateMany.mutate({ items: nestedUpdates, atomic }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((r) => this.instantiate(r)),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: this.instantiate(item.data),
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Upsert Operations
+    // ─────────────────────────────────────────────────────────────────
+    async upsertByExternalId(data) {
+        const validated = this.validate(upsertVEHAlertInputSchema, data);
+        const nestedData = this.transformToNested(validated);
+        const response = await this.execute(() => this.trpc.alerts.upsertByExternalId.mutate(nestedData));
+        return {
+            data: this.instantiate(response.data),
+            action: response.action,
+        };
+    }
+    async upsertManyByExternalId(alerts, options = {}) {
+        const atomic = options.atomic ?? true;
+        const validated = this.validate(z.array(upsertVEHAlertInputSchema), alerts);
+        const nestedItems = validated.map((r) => this.transformToNested(r));
+        const response = await this.execute(() => this.trpc.alerts.upsertManyByExternalId.mutate({
+            items: nestedItems,
+            atomic,
+        }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((item) => ({
+                    data: this.instantiate(item.data),
+                    action: item.action,
+                })),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: {
+                        data: this.instantiate(item.data.data),
+                        action: item.data.action,
+                    },
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Alert Items
+    // ─────────────────────────────────────────────────────────────────
+    async addItem(alertId, data) {
+        const validated = this.validate(createVEHAlertItemInputSchema, data);
+        const nestedData = this.transformItemToNested(validated);
+        const response = await this.execute(() => this.trpc.alerts.addItem.mutate({ alertId, data: nestedData }));
+        return this.instantiateItem(response);
+    }
+    async getItem(alertId, itemId) {
+        const response = await this.execute(() => this.trpc.alerts.getItem.query({ alertId, itemId }));
+        return this.instantiateItem(response);
+    }
+    async updateItem(alertId, itemId, data) {
+        const validated = this.validate(updateVEHAlertItemInputSchema, data);
+        const nestedData = this.transformItemUpdateToNested(validated);
+        const response = await this.execute(() => this.trpc.alerts.updateItem.mutate({
+            alertId,
+            itemId,
+            data: nestedData,
+        }));
+        return this.instantiateItem(response);
+    }
+    async listItems(alertId, options) {
+        const scopedFilter = this.applyScopeToItemFilter(options?.filter);
+        const response = await this.execute(() => this.trpc.alerts.listItems.query({
+            alertId,
+            ...options,
+            filter: scopedFilter,
+        }));
+        return {
+            data: response.data.map((i) => this.instantiateItem(i)),
+            pagination: response.pagination,
+        };
+    }
+    applyScopeToItemFilter(filter) {
+        if (!filter)
+            return undefined;
+        const { alertType, alertDescription, ...baseFields } = filter;
+        if (alertType === undefined && alertDescription === undefined) {
+            return baseFields;
+        }
+        // alertType stays at subcategory level
+        const subcategoryFilter = {};
+        if (alertType !== undefined)
+            subcategoryFilter.alertType = alertType;
+        // alertDescription lives at AV level
+        const avFilter = {};
+        if (alertDescription !== undefined)
+            avFilter.alertDescription = alertDescription;
+        return {
+            ...baseFields,
+            scopeData: {
+                MX: {
+                    actividadVulnerable: {
+                        ...avFilter,
+                        ...(Object.keys(subcategoryFilter).length > 0
+                            ? { [CodigoActividad.VEH]: subcategoryFilter }
+                            : {}),
+                    },
+                },
+            },
+        };
+    }
+    async addItems(alertId, items) {
+        const validated = this.validate(z.array(createVEHAlertItemInputSchema), items);
+        const nestedItems = validated.map((i) => this.transformItemToNested(i));
+        const response = await this.execute(() => this.trpc.alerts.addItems.mutate({ alertId, items: nestedItems }));
+        return {
+            added: response.added,
+            items: response.items.map((i) => this.instantiateItem(i)),
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Sub-resource Factory
+    // ─────────────────────────────────────────────────────────────────
+    createItemsResource() {
+        return new AlertItemsResource(this.trpc, (data) => this.instantiateItem(data), (filter) => this.applyScopeToItemFilter(filter));
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Validation & Generation
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Validates a VEH alert.
+     *
+     * @param alertId - The alert ID to validate
+     * @param defaults - VEH alert defaults including rfc, alertType, etc.
+     */
+    async validateReport(alertId, defaults) {
+        const validated = defaults
+            ? this.validate(vehDefaultsInputSchema, defaults)
+            : undefined;
+        const nestedInput = this.transformVehDefaultsToNested(alertId, validated);
+        return this.execute(() => this.trpc.alerts.validateReport.mutate(nestedInput));
+    }
+    /**
+     * Generates XML for a VEH alert.
+     *
+     * @param alertId - The alert ID to generate XML for
+     * @param defaults - VEH alert defaults including rfc, alertType, etc.
+     */
+    async generateReport(alertId, defaults) {
+        const validated = defaults
+            ? this.validate(vehDefaultsInputSchema, defaults)
+            : undefined;
+        const nestedInput = this.transformVehDefaultsToNested(alertId, validated);
+        return this.execute(() => this.trpc.alerts.generateReport.mutate(nestedInput));
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Protected Helpers
+    // ─────────────────────────────────────────────────────────────────
+    transformToNested(data) {
+        const { mesReportado, ...baseFields } = data;
+        return {
+            ...baseFields,
+            scope: "MX:AV:VEH",
+            scopeData: {
+                MX: {
+                    actividadVulnerable: {
+                        // mesReportado lives at AV level (not subcategory)
+                        mesReportado,
+                        // Empty VEH marker for scope filtering
+                        [CodigoActividad.VEH]: {},
+                    },
+                },
+            },
+        };
+    }
+    transformUpdateToNested(data) {
+        return {
+            ...data,
+            scope: "MX:AV:VEH",
+            scopeData: {
+                MX: {
+                    actividadVulnerable: {
+                        [CodigoActividad.VEH]: {},
+                    },
+                },
+            },
+        };
+    }
+    instantiate(data) {
+        return new MexVEHAlert(data);
+    }
+    /** Materializes a raw payload into a {@link MexVEHAlert} (return type narrowed via the `instantiate` override). */
+    materialize(data) {
+        return this.instantiate(data);
+    }
+    instantiateItem(data) {
+        return new MexVEHAlertItem(data);
+    }
+    instantiateTransactionItem(data) {
+        return new MexVEHAlertTransactionItem(data);
+    }
+    instantiateClientItem(data) {
+        return new MexVEHAlertClientItem(data);
+    }
+    transformItemToNested(data) {
+        const { alertType, alertDescription, amendment, ...baseFields } = data;
+        // alertType stays at subcategory level
+        const vehData = {};
+        if (alertType !== undefined)
+            vehData.alertType = alertType;
+        // alertDescription and amendment live at the AV level
+        const avData = {};
+        if (alertDescription !== undefined)
+            avData.alertDescription = alertDescription;
+        if (amendment !== undefined)
+            avData.amendment = amendment;
+        return {
+            ...baseFields,
+            scopeData: {
+                MX: {
+                    actividadVulnerable: {
+                        ...avData,
+                        ...(Object.keys(vehData).length > 0
+                            ? { [CodigoActividad.VEH]: vehData }
+                            : {}),
+                    },
+                },
+            },
+        };
+    }
+    transformItemUpdateToNested(data) {
+        const { alertType, alertDescription, amendment, ...baseFields } = data;
+        // alertType stays at subcategory level
+        const vehData = {};
+        if (alertType !== undefined)
+            vehData.alertType = alertType;
+        // alertDescription and amendment live at the AV level
+        const avData = {};
+        if (alertDescription !== undefined)
+            avData.alertDescription = alertDescription;
+        if (amendment !== undefined)
+            avData.amendment = amendment;
+        if (Object.keys(vehData).length === 0 && Object.keys(avData).length === 0) {
+            return baseFields;
+        }
+        return {
+            ...baseFields,
+            scopeData: {
+                MX: {
+                    actividadVulnerable: {
+                        ...avData,
+                        ...(Object.keys(vehData).length > 0
+                            ? { [CodigoActividad.VEH]: vehData }
+                            : {}),
+                    },
+                },
+            },
+        };
+    }
+    applyScopeToSort(sort) {
+        if (!sort || sort.length === 0) {
+            return undefined;
+        }
+        return transformSort(sort, vehAlertSortingFieldMapping);
+    }
+    transformVehDefaultsToNested(alertId, defaults) {
+        if (!defaults) {
+            return {
+                alertId,
+                reportType: ReportType.MexActividadVulnerableVEH,
+            };
+        }
+        const { rfc, collegiateEntityCode, exempt, priority, ...vehFields } = defaults;
+        return {
+            alertId,
+            reportType: ReportType.MexActividadVulnerableVEH,
+            defaults: {
+                scopeData: {
+                    MX: {
+                        actividadVulnerable: {
+                            rfc,
+                            collegiateEntityCode,
+                            exempt,
+                            priority,
+                            [CodigoActividad.VEH]: vehFields,
+                        },
+                    },
+                },
+            },
+        };
+    }
+}

package/dist/resources/mx/av/veh/clients.d.ts

@@ -0,0 +1,144 @@
+/**
+ * VEH (Vehículos) Clients Resource
+ *
+ * Extends MexClientsResource with VEH-specific behavior.
+ * VEH clients support Individual, Company, and Trust discriminated union types.
+ * Returns MexVEHClient models.
+ */
+import type { AtomicBatchResult, ClientRelationshipType, ClientSort, CreateBankAccountInput, CreateClientInput, CreateContactMethodInput, CreateMexAddressInput, CreateVEHClientInput, LinkedClient as LinkedClientInput, ListOptions, PaginatedResponse, PartialBatchResult, SyncCreateDocumentInput, SyncItem, SyncResult, SyncUpdateDocumentInput, UpdateBankAccountInput, UpdateClientInput, UpdateContactMethodInput, UpdateMexAddressInput, UpdateVEHClientInput, UpsertResult, UpsertVEHClientInput, VEHClientFilter, VEHClientSort } from "@artu-ai/shared";
+import { type ClientData, ContactMethod, Document, LinkedClient, MexAddress, MexBankAccount, MexVEHClient } from "../../../../models";
+import { type ClientIncludeMap } from "../../../clients";
+import type { RelatedPartyParent, RelatedPartySubresource } from "../../../related-parties/base";
+import { AVClientsResource } from "../clients";
+/**
+ * VEH (Vehículos) scoped clients resource.
+ *
+ * @example
+ * ```typescript
+ * const vehSdk = new ComplianceSDK({
+ *   apiKey,
+ *   environment: "test",
+ *   scope: "MX:AV:VEH",
+ * });
+ *
+ * const client = await vehSdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ *   rfc: "GAJL850101ABC",
+ * });
+ *
+ * // Returns MexVEHClient
+ * ```
+ */
+export declare class VEHClientsResource extends AVClientsResource {
+    readonly legalRepresentatives: RelatedPartySubresource<MexVEHClient, CreateVEHClientInput>;
+    readonly controllingBeneficiaries: RelatedPartySubresource<MexVEHClient, CreateVEHClientInput>;
+    protected relatedPartyParent(): RelatedPartyParent<MexVEHClient, CreateVEHClientInput>;
+    create(data: CreateVEHClientInput): Promise<MexVEHClient>;
+    retrieve(id: string, options?: {
+        include?: ClientIncludeMap;
+        crossScope?: boolean;
+    }): Promise<MexVEHClient>;
+    retrieveByExternalId(externalId: string, opts?: {
+        crossScope?: boolean;
+    }): Promise<MexVEHClient>;
+    update(id: string, data: UpdateVEHClientInput): Promise<MexVEHClient>;
+    list(options?: ListOptions<VEHClientFilter, VEHClientSort> & {
+        includePrimaryContacts?: boolean;
+        includeNonPrimary?: boolean;
+        crossScope?: boolean;
+    }): Promise<PaginatedResponse<MexVEHClient>>;
+    iterate(options?: {
+        filter?: VEHClientFilter;
+        sort?: VEHClientSort;
+        pageSize?: number;
+        crossScope?: boolean;
+    }): AsyncGenerator<MexVEHClient, void, undefined>;
+    count(filter?: VEHClientFilter, options?: {
+        includeNonPrimary?: boolean;
+        crossScope?: boolean;
+    }): Promise<number>;
+    createMany(clients: CreateVEHClientInput[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<MexVEHClient>>;
+    createMany(clients: CreateVEHClientInput[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<MexVEHClient>>;
+    updateMany(updates: {
+        id: string;
+        data: UpdateVEHClientInput;
+    }[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<MexVEHClient>>;
+    updateMany(updates: {
+        id: string;
+        data: UpdateVEHClientInput;
+    }[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<MexVEHClient>>;
+    upsertByExternalId(data: UpsertVEHClientInput): Promise<UpsertResult<MexVEHClient>>;
+    upsertManyByExternalId(clients: UpsertVEHClientInput[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<UpsertResult<MexVEHClient>>>;
+    upsertManyByExternalId(clients: UpsertVEHClientInput[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<UpsertResult<MexVEHClient>>>;
+    linkClient(parentClientId: string, childClientId: string, relationshipType: ClientRelationshipType, metadata?: Record<string, unknown>): Promise<MexVEHClient>;
+    unlinkClient(parentClientId: string, childClientId: string, relationshipType: ClientRelationshipType): Promise<MexVEHClient>;
+    listLinkedClients(parentClientId: string, relationshipType?: ClientRelationshipType): Promise<LinkedClient[]>;
+    setLinkedClients(parentClientId: string, linkedClients: LinkedClientInput[]): Promise<MexVEHClient>;
+    syncAll(clientId: undefined, data: {
+        client: CreateVEHClientInput;
+        addresses?: SyncItem<CreateMexAddressInput>[];
+        contactMethods?: SyncItem<CreateContactMethodInput>[];
+        bankAccounts?: SyncItem<CreateBankAccountInput>[];
+        documents?: SyncItem<SyncCreateDocumentInput>[];
+        linkedClients?: LinkedClientInput[];
+    }, options?: {
+        replaceMode?: boolean;
+    }): Promise<{
+        client: MexVEHClient;
+        addresses: SyncResult<MexAddress>;
+        contactMethods: SyncResult<ContactMethod>;
+        bankAccounts: SyncResult<MexBankAccount>;
+        documents: SyncResult<Document>;
+    }>;
+    syncAll(clientId: string, data: {
+        client?: UpdateVEHClientInput;
+        addresses?: SyncItem<CreateMexAddressInput>[];
+        contactMethods?: SyncItem<CreateContactMethodInput>[];
+        bankAccounts?: SyncItem<CreateBankAccountInput>[];
+        documents?: SyncItem<SyncCreateDocumentInput>[];
+        linkedClients?: LinkedClientInput[];
+    }, options: {
+        replaceMode: true;
+    }): Promise<{
+        client: MexVEHClient;
+        addresses: SyncResult<MexAddress>;
+        contactMethods: SyncResult<ContactMethod>;
+        bankAccounts: SyncResult<MexBankAccount>;
+        documents: SyncResult<Document>;
+    }>;
+    syncAll(clientId: string, data: {
+        client?: UpdateVEHClientInput;
+        addresses?: SyncItem<UpdateMexAddressInput>[];
+        contactMethods?: SyncItem<UpdateContactMethodInput>[];
+        bankAccounts?: SyncItem<UpdateBankAccountInput>[];
+        documents?: SyncItem<SyncUpdateDocumentInput>[];
+        linkedClients?: LinkedClientInput[];
+    }, options?: {
+        replaceMode?: boolean;
+    }): Promise<{
+        client: MexVEHClient;
+        addresses: SyncResult<MexAddress>;
+        contactMethods: SyncResult<ContactMethod>;
+        bankAccounts: SyncResult<MexBankAccount>;
+        documents: SyncResult<Document>;
+    }>;
+    protected transformToNested(data: CreateVEHClientInput): CreateClientInput;
+    protected transformUpdateToNested(data: UpdateVEHClientInput): UpdateClientInput;
+    protected instantiate(data: ClientData): MexVEHClient;
+    /** Materializes a raw payload into a {@link MexVEHClient} (return type narrowed via the `instantiate` override). */
+    materialize(data: ClientData): MexVEHClient;
+    protected applyScopeToSort(sort?: VEHClientSort): ClientSort | undefined;
+}