@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/resources/mex/addresses.ts

@@ -0,0 +1,493 @@
+/**
+ * Mexico Addresses Resource
+ *
+ * Extends AddressesResource with Mexico-specific behavior:
+ * - Accepts flattened CreateMexAddressInput (MX fields at root level)
+ * - Returns MexAddress models with Mexico-specific accessors
+ *
+ * Note: Mexican address format can be used for addresses in any country.
+ */
+
+import { z } from "zod";
+import type {
+  CreateAddressInput,
+  UpdateAddressInput,
+  AddressFilter,
+  AddressSort,
+  AddressType,
+  ListOptions,
+  PaginatedResponse,
+  CreateMexAddressInput,
+  UpdateMexAddressInput,
+  AtomicBatchResult,
+  PartialBatchResult,
+  SyncItem,
+  SyncResult,
+  MexAddressFilter,
+  MexAddressSort,
+} from "@artu-ai/shared";
+import {
+  createMexAddressInputSchema,
+  updateMexAddressInputSchema,
+  replaceSyncItemSchema,
+  transformSort,
+  mexAddressFieldMapping,
+} from "@artu-ai/shared";
+import { AddressesResource } from "../addresses";
+import { type BatchOptions } from "../clients";
+import { MexAddress, type AddressData } from "../../models";
+
+// ===========================
+// MexAddressesResource
+// ===========================
+
+/**
+ * Mexico-scoped addresses resource.
+ *
+ * Provides the same operations as AddressesResource but with:
+ * - Flattened input types (MX fields like exteriorNumber, neighborhood at root level)
+ * - MexAddress model return type with Mexico-specific accessors
+ *
+ * @example
+ * ```typescript
+ * const mexSdk = new ComplianceSDK({
+ *   apiKey,
+ *   environment: "test",
+ *   jurisdiction: Jurisdiction.Mexico,
+ * });
+ *
+ * // Create with flattened input
+ * const address = await mexSdk.addresses.create({
+ *   clientId: "client_123",
+ *   street: "Paseo de la Reforma",
+ *   exteriorNumber: "222",
+ *   interiorNumber: "Piso 5",
+ *   neighborhood: "Juárez",
+ *   city: "Ciudad de México",
+ *   state: "CDMX",
+ *   postalCode: "06600",
+ *   country: "MX",
+ *   type: "home",
+ * });
+ *
+ * // Returns MexAddress
+ * console.log(address.exteriorNumber);
+ * console.log(address.formattedMexican);
+ * ```
+ */
+export class MexAddressesResource<
+  TSort = MexAddressSort,
+> extends AddressesResource<TSort> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations (override with flattened input types)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new address with Mexico-format fields.
+   */
+  async create(data: CreateMexAddressInput): Promise<MexAddress> {
+    const validated = this.validate(createMexAddressInputSchema, data);
+    const nestedData = this.transformToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.create.mutate(nestedData)
+    );
+
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves an address by ID.
+   */
+  async retrieve(id: string): Promise<MexAddress> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByMetadata(key: string, value: string): Promise<MexAddress> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByExternalId(externalId: string): Promise<MexAddress> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates an address with Mexico-format fields.
+   */
+  async update(id: string, data: UpdateMexAddressInput): Promise<MexAddress> {
+    const validated = this.validate(updateMexAddressInputSchema, data);
+    const nestedData = this.transformUpdateToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.update.mutate({ id, data: nestedData })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List & Pagination
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists addresses with optional filtering.
+   *
+   * Accepts flattened MX filter (MX-specific fields at root level).
+   */
+  async list(
+    options?: ListOptions<MexAddressFilter, TSort>
+  ): Promise<PaginatedResponse<MexAddress>> {
+    const scopedFilter = this.applyScopeToFilter(options?.filter);
+    const scopedSort = this.applyScopeToSort(options?.sort);
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.list.query({
+        ...options,
+        filter: scopedFilter,
+        sort: scopedSort,
+      })
+    );
+
+    return {
+      data: response.data.map((a) => this.instantiate(a)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Lists all addresses for a specific client.
+   */
+  async listByClient(
+    clientId: string,
+    options?: { cursor?: string; limit?: number }
+  ): Promise<PaginatedResponse<MexAddress>> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.listByClient.query({ clientId, ...options })
+    );
+
+    return {
+      data: response.data.map((a) => this.instantiate(a)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Gets the primary address for a client.
+   */
+  async getPrimary(
+    clientId: string,
+    type?: AddressType
+  ): Promise<MexAddress | null> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.getPrimary.query({ clientId, type })
+    );
+    return response ? this.instantiate(response) : null;
+  }
+
+  /**
+   * Iterates over addresses.
+   *
+   * Accepts flattened MX filter (MX-specific fields at root level).
+   */
+  iterate(filter?: MexAddressFilter): AsyncGenerator<MexAddress, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexAddress>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async createMany(
+    addresses: CreateMexAddressInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAddress>>;
+  async createMany(
+    addresses: CreateMexAddressInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAddress>>;
+  async createMany(
+    addresses: CreateMexAddressInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<MexAddress> | PartialBatchResult<MexAddress>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createMexAddressInputSchema),
+      addresses
+    );
+    const nestedItems = validated.map((a) => this.transformToNested(a));
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.createMany.mutate({ items: nestedItems, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((a) => this.instantiate(a)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  async updateMany(
+    updates: { id: string; data: UpdateMexAddressInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAddress>>;
+  async updateMany(
+    updates: { id: string; data: UpdateMexAddressInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAddress>>;
+  async updateMany(
+    updates: { id: string; data: UpdateMexAddressInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<MexAddress> | PartialBatchResult<MexAddress>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateMexAddressInputSchema,
+    });
+
+    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.addresses.updateMany.mutate({ items: nestedUpdates, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((a) => this.instantiate(a)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Sync Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Syncs addresses for a client with Mexico-format flattened input.
+   */
+  async sync(
+    clientId: string,
+    items: SyncItem<CreateMexAddressInput>[],
+    options: { replaceMode: true }
+  ): Promise<SyncResult<MexAddress>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateMexAddressInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<MexAddress>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateMexAddressInput | CreateMexAddressInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<MexAddress>> {
+    const validated = this.validate(
+      z.array(
+        replaceSyncItemSchema(
+          createMexAddressInputSchema,
+          updateMexAddressInputSchema
+        )
+      ),
+      items
+    );
+
+    // Transform each item to nested format
+    const nestedItems: SyncItem<UpdateAddressInput | CreateAddressInput>[] = [];
+    for (const item of validated) {
+      if ("_delete" in item && item._delete) {
+        // Delete items pass through unchanged
+        nestedItems.push(item as SyncItem<UpdateAddressInput>);
+      } else if ("id" in item && item.id) {
+        // Update items - transform the data fields
+        const { id, ...data } = item;
+        const transformed = this.transformUpdateToNested(
+          data as UpdateMexAddressInput
+        );
+        nestedItems.push({
+          id,
+          ...transformed,
+        } as SyncItem<UpdateAddressInput>);
+      } else {
+        // Create items - transform full item
+        const transformed = this.transformToNested(
+          item as CreateMexAddressInput
+        );
+        nestedItems.push(transformed as SyncItem<CreateAddressInput>);
+      }
+    }
+
+    // Call parent sync with transformed items
+    // Parent already uses our overridden instantiate(), so result contains MexAddress
+    const result = await super.sync(
+      clientId,
+      nestedItems,
+      options as { replaceMode?: boolean }
+    );
+
+    return result as SyncResult<MexAddress>;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transforms flattened MX filter to nested API format.
+   *
+   * Mexico-specific filter fields (neighborhood, municipality) are stored
+   * in `jurisdictions.MX`. Base fields pass through unchanged.
+   */
+  protected applyScopeToFilter(filter?: MexAddressFilter): AddressFilter {
+    if (!filter) return {};
+
+    const { neighborhood, municipality, ...baseFields } = filter;
+
+    const hasMexFields = neighborhood !== undefined || municipality !== undefined;
+
+    if (!hasMexFields) {
+      return baseFields as AddressFilter;
+    }
+
+    const mexData: Record<string, unknown> = {};
+    if (neighborhood !== undefined) mexData.neighborhood = neighborhood;
+    if (municipality !== undefined) mexData.municipality = municipality;
+
+    return {
+      ...baseFields,
+      jurisdictions: { MX: mexData },
+    } as AddressFilter;
+  }
+
+  /**
+   * Transforms a flattened MexAddressSort to nested AddressSort format.
+   *
+   * Maps flattened field names to their full API paths.
+   *
+   * Note: Uses unknown parameter to allow derived classes to override with their own sort types.
+   */
+  protected applyScopeToSort(sort?: TSort): AddressSort | undefined {
+    if (!sort || !Array.isArray(sort) || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort as MexAddressSort, mexAddressFieldMapping);
+  }
+
+  /**
+   * Transforms flattened MX input to nested API format.
+   *
+   * Mexico-specific fields (exteriorNumber, interiorNumber, neighborhood, etc.)
+   * are stored in `jurisdictions.MX`. The base `street` field is passed through.
+   */
+  protected transformToNested(data: CreateMexAddressInput): CreateAddressInput {
+    const {
+      // Mexico-specific fields go into `jurisdictions.MX`
+      exteriorNumber,
+      interiorNumber,
+      neighborhood,
+      municipality,
+      betweenStreets,
+      reference,
+      // Base fields pass through
+      ...baseFields
+    } = data;
+
+    // Build Mexico-specific data for the `jurisdictions.MX` column
+    // exteriorNumber and neighborhood are required by schema validation
+    const mexData: Record<string, unknown> = {
+      exteriorNumber,
+      neighborhood,
+    };
+    if (interiorNumber !== undefined) mexData.interiorNumber = interiorNumber;
+    if (municipality !== undefined) mexData.municipality = municipality;
+    if (betweenStreets !== undefined) mexData.betweenStreets = betweenStreets;
+    if (reference !== undefined) mexData.reference = reference;
+
+    return {
+      ...baseFields,
+      jurisdictions: { MX: mexData },
+    } as CreateAddressInput;
+  }
+
+  /**
+   * Transforms flattened MX update input to nested API format.
+   */
+  protected transformUpdateToNested(
+    data: UpdateMexAddressInput
+  ): UpdateAddressInput {
+    const {
+      // Mexico-specific fields go into `jurisdictions.MX`
+      exteriorNumber,
+      interiorNumber,
+      neighborhood,
+      municipality,
+      betweenStreets,
+      reference,
+      // Base fields pass through
+      ...baseFields
+    } = data;
+
+    const hasMexFields =
+      exteriorNumber !== undefined ||
+      interiorNumber !== undefined ||
+      neighborhood !== undefined ||
+      municipality !== undefined ||
+      betweenStreets !== undefined ||
+      reference !== undefined;
+
+    if (!hasMexFields) {
+      return baseFields as UpdateAddressInput;
+    }
+
+    const mexData: Record<string, unknown> = {};
+    if (exteriorNumber !== undefined) mexData.exteriorNumber = exteriorNumber;
+    if (interiorNumber !== undefined) mexData.interiorNumber = interiorNumber;
+    if (neighborhood !== undefined) mexData.neighborhood = neighborhood;
+    if (municipality !== undefined) mexData.municipality = municipality;
+    if (betweenStreets !== undefined) mexData.betweenStreets = betweenStreets;
+    if (reference !== undefined) mexData.reference = reference;
+
+    return {
+      ...baseFields,
+      jurisdictions: { MX: mexData },
+    } as UpdateAddressInput;
+  }
+
+  /**
+   * Instantiates a MexAddress model.
+   */
+  protected override instantiate(data: AddressData): MexAddress {
+    return new MexAddress(data);
+  }
+}