@artu-ai/compliance-sdk 0.4.1 → 0.4.2

package/src/resources/mex/addresses.ts

@@ -1,493 +0,0 @@
-/**
- * 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);
-  }
-}