@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/resources/contact-methods.ts

@@ -0,0 +1,410 @@
+/**
+ * Contact Methods Resource
+ *
+ * Manages communication channels (email, phone, etc.) for clients.
+ */
+
+import { z } from "zod";
+import type {
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  ContactMethodType,
+  ContactMethodFilter,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  SyncItem,
+  SyncResult,
+} from "@artu-ai/shared";
+import {
+  createContactMethodInputSchema,
+  updateContactMethodInputSchema,
+  replaceSyncItemSchema,
+} from "@artu-ai/shared";
+import { BaseResource } from "./base";
+import { ContactMethod, type ContactMethodData } from "../models/ContactMethod";
+import type { BatchOptions } from "./clients";
+
+// ===========================
+// ContactMethodsResource
+// ===========================
+
+/**
+ * Resource for managing client contact methods.
+ *
+ * @example
+ * ```typescript
+ * // Create an email contact for a client
+ * const email = await sdk.contactMethods.create({
+ *   clientId: "client_123",
+ *   type: "email",
+ *   value: "juan@example.com",
+ *   label: "Personal",
+ *   isPrimary: true,
+ * });
+ *
+ * // Get the primary email for a client
+ * const primary = await sdk.contactMethods.getPrimary("client_123", "email");
+ * ```
+ */
+export class ContactMethodsResource extends BaseResource<
+  ContactMethod,
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  ContactMethodFilter
+> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a contact method for a client
+   *
+   * @param data - Contact method data including clientId
+   * @returns The created ContactMethod
+   */
+  async create(data: CreateContactMethodInput): Promise<ContactMethod> {
+    const validated = this.validate(createContactMethodInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.create.mutate(validated)
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a contact method by ID
+   *
+   * @param id - The contact method ID
+   * @returns The ContactMethod
+   */
+  async retrieve(id: string): Promise<ContactMethod> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a contact method by metadata key/value.
+   */
+  async retrieveByMetadata(key: string, value: string): Promise<ContactMethod> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a contact method by externalId.
+   */
+  async retrieveByExternalId(externalId: string): Promise<ContactMethod> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a contact method
+   *
+   * @param id - The contact method ID
+   * @param data - Fields to update
+   * @returns The updated ContactMethod
+   */
+  async update(
+    id: string,
+    data: UpdateContactMethodInput
+  ): Promise<ContactMethod> {
+    const validated = this.validate(updateContactMethodInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.update.mutate({ id, data: validated })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Deletes a contact method
+   *
+   * @param id - The contact method ID
+   */
+  async delete(id: string): Promise<void> {
+    await this.execute(() => this.trpc.contactMethods.delete.mutate({ id }));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists contact methods with optional filtering
+   *
+   * @param options - Filtering and pagination options
+   * @returns Paginated list of ContactMethods
+   */
+  async list(
+    options?: ListOptions<ContactMethodFilter>
+  ): Promise<PaginatedResponse<ContactMethod>> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.list.query(options)
+    );
+    return {
+      data: response.data.map((c) => this.instantiate(c)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Lists all contact methods for a specific client
+   *
+   * @param clientId - The client ID
+   * @param options - Optional pagination options
+   * @returns Paginated list of ContactMethods
+   */
+  async listByClient(
+    clientId: string,
+    options?: { cursor?: string; limit?: number }
+  ): Promise<PaginatedResponse<ContactMethod>> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.listByClient.query({ clientId, ...options })
+    );
+    return {
+      data: response.data.map((c) => this.instantiate(c)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Returns an async iterator over all contact methods matching the filter.
+   */
+  iterate(
+    filter?: ContactMethodFilter
+  ): AsyncGenerator<ContactMethod, void, undefined> {
+    return this.createIterator({ filter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple contact methods in a single request.
+   *
+   * @param contacts - Array of contact method data (each includes clientId)
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async createMany(
+    contacts: CreateContactMethodInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<ContactMethod>>;
+  async createMany(
+    contacts: CreateContactMethodInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<ContactMethod>>;
+  async createMany(
+    contacts: CreateContactMethodInput[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<ContactMethod> | PartialBatchResult<ContactMethod>
+  > {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createContactMethodInputSchema),
+      contacts
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.createMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((c) => this.instantiate(c)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  /**
+   * Updates multiple contact methods in a single request.
+   *
+   * @param updates - Array of { id, data } updates
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateContactMethodInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<ContactMethod>>;
+  async updateMany(
+    updates: { id: string; data: UpdateContactMethodInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<ContactMethod>>;
+  async updateMany(
+    updates: { id: string; data: UpdateContactMethodInput }[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<ContactMethod> | PartialBatchResult<ContactMethod>
+  > {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateContactMethodInputSchema,
+    });
+
+    const validated = this.validate(z.array(updateItemSchema), updates);
+
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.updateMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((c) => this.instantiate(c)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Sync Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Syncs contact methods for a client - handles create, update, and delete in bulk.
+   *
+   * This is the most efficient way to reconcile a set of contact methods for a client.
+   * Primary contact methods are handled per-type (e.g., one primary email, one primary phone).
+   *
+   * @param clientId - The client ID
+   * @param items - Array of sync items:
+   *   - Without `id`: create new contact method
+   *   - With `id` and `_delete: true`: delete existing contact method
+   *   - With `id` (no `_delete`): update existing contact method
+   * @param options - Sync options
+   * @param options.replaceMode - When true, items not in the array are deleted (default: false)
+   * @returns Sync result with created, updated, and deleted arrays
+   *
+   * @example
+   * ```typescript
+   * // Patch mode (default) - only mentioned items are affected
+   * const result = await sdk.contactMethods.sync("client_123", [
+   *   // Create new email (no id)
+   *   { type: "email", value: "new@example.com", isPrimary: true },
+   *   // Update existing phone (has id)
+   *   { id: "cm_456", value: "+52 555 123 4567" },
+   *   // Delete contact method (has id and _delete: true)
+   *   { id: "cm_789", _delete: true },
+   * ]);
+   *
+   * // Replace mode - provided array becomes the complete set (requires full create input for new items)
+   * const result = await sdk.contactMethods.sync("client_123", methods, { replaceMode: true });
+   *
+   * console.log(result.created);  // newly created contact methods
+   * console.log(result.updated);  // updated contact methods
+   * console.log(result.deleted);  // array of deleted IDs
+   * ```
+   */
+  async sync(
+    clientId: string,
+    items: SyncItem<CreateContactMethodInput>[],
+    options: { replaceMode: true }
+  ): Promise<SyncResult<ContactMethod>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateContactMethodInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<ContactMethod>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateContactMethodInput | CreateContactMethodInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<ContactMethod>> {
+    const validated = this.validate(
+      z.array(
+        replaceSyncItemSchema(
+          createContactMethodInputSchema,
+          updateContactMethodInputSchema
+        )
+      ),
+      items
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.sync.mutate({
+        clientId,
+        items: validated,
+        replaceMode: options?.replaceMode,
+      })
+    );
+
+    return {
+      created: response.created.map((c) => this.instantiate(c)),
+      updated: response.updated.map((c) => this.instantiate(c)),
+      deleted: response.deleted,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Specialized Methods
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Gets the primary contact method of a specific type for a client
+   *
+   * @param clientId - The client ID
+   * @param type - The contact method type
+   * @returns The primary ContactMethod or null
+   */
+  async getPrimary(
+    clientId: string,
+    type: ContactMethodType
+  ): Promise<ContactMethod | null> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.getPrimary.query({ clientId, type })
+    );
+    return response ? this.instantiate(response) : null;
+  }
+
+  /**
+   * Marks a contact method as verified
+   *
+   * @param id - The contact method ID
+   * @returns The updated ContactMethod
+   */
+  async markVerified(id: string): Promise<ContactMethod> {
+    const response = await this.execute(() =>
+      this.trpc.contactMethods.markVerified.mutate({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Instantiation
+  // ─────────────────────────────────────────────────────────────────
+
+  protected instantiate(data: ContactMethodData): ContactMethod {
+    return new ContactMethod(data);
+  }
+}