@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/resources/base.ts

@@ -0,0 +1,322 @@
+/**
+ * Base Resource Class
+ *
+ * Abstract base class for all resource managers.
+ * Provides common patterns: validation, error mapping, pagination.
+ */
+
+import type { ZodType } from "zod";
+import { TRPCClientError } from "@trpc/client";
+import type {
+  PaginatedResponse,
+  ListOptions,
+  IterateOptions,
+} from "@artu-ai/shared";
+import { Jurisdiction, type CodigoActividad } from "@artu-ai/shared";
+import type { TRPCClient } from "../utils/trpc-client";
+import { mapTRPCError, ValidationError } from "../errors";
+import { createPaginatedIterator } from "../utils/pagination";
+
+import { type SDKScope, type Environment, isMexicoScope } from "../sdk/types";
+
+/**
+ * Type guard for tRPC client errors
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isTRPCError(error: unknown): error is TRPCClientError<any> {
+  return error instanceof TRPCClientError;
+}
+
+/**
+ * Configuration for creating a resource manager
+ */
+export interface ResourceConfig {
+  /**
+   * tRPC client instance for API communication
+   */
+  trpc: TRPCClient;
+
+  /**
+   * Optional SDK scope for jurisdiction/activity scoping
+   */
+  scope?: SDKScope;
+
+  /**
+   * SDK environment (test or live)
+   */
+  environment?: Environment;
+}
+// ===========================
+// Base Resource Class
+// ===========================
+
+/**
+ * Abstract base class for all resource managers.
+ *
+ * Provides:
+ * - Input validation with Zod schemas
+ * - Automatic error mapping from tRPC to SDK errors
+ * - Pagination iterator factory
+ *
+ * @typeParam TModel - The model type returned by this resource
+ * @typeParam TCreateInput - Input type for create operations
+ * @typeParam TUpdateInput - Input type for update operations
+ * @typeParam TFilter - Filter type for list operations
+ *
+ * @example
+ * ```typescript
+ * class ClientsResource extends BaseResource<
+ *   Client,
+ *   CreateClientInput,
+ *   UpdateClientInput,
+ *   ClientFilter
+ * > {
+ *   async create(data: CreateClientInput): Promise<Client> {
+ *     const validated = this.validate(createClientInputSchema, data);
+ *     return this.execute(() =>
+ *       this.trpc.clients.create.mutate(validated)
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export abstract class BaseResource<
+  TModel,
+  TCreateInput,
+  TUpdateInput,
+  TFilter = Record<string, unknown>,
+  TCreateResult = TModel,
+> {
+  /**
+   * tRPC client for API communication
+   */
+  protected readonly trpc: TRPCClient;
+
+  /**
+   * SDK scope (jurisdiction and actividadVulnerable)
+   */
+  protected readonly scope: SDKScope;
+
+  constructor(config: ResourceConfig) {
+    this.trpc = config.trpc;
+    this.scope = config.scope ?? {};
+  }
+
+  /**
+   * Whether this resource is scoped to a jurisdiction
+   */
+  protected get isScoped(): boolean {
+    return this.scope.jurisdiction !== undefined;
+  }
+
+  /**
+   * Whether this resource is scoped to Mexico
+   */
+  protected get isMexicoScoped(): boolean {
+    return this.scope.jurisdiction === Jurisdiction.Mexico;
+  }
+
+  /**
+   * Whether this resource is scoped to an Actividad Vulnerable activity
+   */
+  protected get isActivityScoped(): boolean {
+    return (
+      isMexicoScope(this.scope) && this.scope.actividadVulnerable !== undefined
+    );
+  }
+
+  /**
+   * Gets the actividadVulnerable code if scoped, undefined otherwise
+   */
+  protected get scopedActivity(): CodigoActividad | undefined {
+    return isMexicoScope(this.scope)
+      ? this.scope.actividadVulnerable
+      : undefined;
+  }
+
+  // ===========================
+  // Abstract Methods
+  // ===========================
+
+  /**
+   * Creates a new resource
+   * @param data - Creation data
+   * @returns The created model (or custom result type)
+   */
+  abstract create(data: TCreateInput): Promise<TCreateResult>;
+
+  /**
+   * Retrieves a resource by ID
+   * @param id - Resource ID
+   * @returns The retrieved model
+   */
+  abstract retrieve(id: string): Promise<TModel>;
+
+  /**
+   * Updates an existing resource
+   * @param id - Resource ID
+   * @param data - Update data
+   * @returns The updated model
+   */
+  abstract update(id: string, data: TUpdateInput): Promise<TModel>;
+
+  /**
+   * Deletes a resource by ID
+   * @param id - Resource ID
+   */
+  abstract delete(id: string): Promise<void>;
+
+  /**
+   * Lists resources with optional filtering and pagination
+   * @param options - List options
+   * @returns Paginated response
+   */
+  abstract list(
+    options?: ListOptions<TFilter>
+  ): Promise<PaginatedResponse<TModel>>;
+
+  // ===========================
+  // Protected Helpers
+  // ===========================
+
+  /**
+   * Validates input against a Zod schema.
+   * Throws ValidationError if validation fails.
+   *
+   * @param schema - Zod schema to validate against
+   * @param data - Data to validate
+   * @returns Validated and typed data
+   * @throws ValidationError if validation fails
+   *
+   * @example
+   * ```typescript
+   * const validated = this.validate(createClientSchema, data);
+   * // validated is now typed as CreateClientInput
+   * ```
+   */
+  protected validate<T>(schema: ZodType<T>, data: unknown): T {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+      throw ValidationError.fromZodError(result.error);
+    }
+    return result.data;
+  }
+
+  /**
+   * Wraps a tRPC operation with error mapping.
+   * Converts tRPC errors to SDK-specific errors.
+   *
+   * @param operation - Async operation to execute
+   * @returns Result of the operation
+   * @throws SDK-specific error if operation fails
+   *
+   * @example
+   * ```typescript
+   * const result = await this.execute(() =>
+   *   this.trpc.clients.create.mutate(data)
+   * );
+   * ```
+   */
+  protected async execute<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      if (isTRPCError(error)) {
+        throw mapTRPCError(error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Creates an async iterator for paginated results.
+   * Automatically fetches subsequent pages as you iterate.
+   *
+   * @typeParam T - The model type to return (defaults to TModel, can be overridden by subclasses)
+   * @param options - Iterator options
+   * @returns Async generator yielding individual items
+   *
+   * @example
+   * ```typescript
+   * for await (const client of this.iterate({ filter: { type: "individual" } })) {
+   *   console.log(client.name);
+   * }
+   * ```
+   */
+  protected createIterator<T = TModel>(
+    options?: IterateOptions<TFilter>
+  ): AsyncGenerator<T, void, undefined> {
+    return createPaginatedIterator<T>(
+      (pagination) =>
+        this.list({
+          filter: options?.filter,
+          ...pagination,
+        }) as unknown as Promise<PaginatedResponse<T>>,
+      { limit: options?.pageSize }
+    );
+  }
+}
+
+// ===========================
+// Read-Only Resource Base
+// ===========================
+
+/**
+ * Base class for read-only resources (no create/update/delete).
+ * Useful for resources that are managed elsewhere.
+ *
+ * @typeParam TModel - The model type returned by this resource
+ * @typeParam TFilter - Filter type for list operations
+ */
+export abstract class ReadOnlyResource<
+  TModel,
+  TFilter = Record<string, unknown>,
+> {
+  protected readonly trpc: TRPCClient;
+
+  constructor(config: ResourceConfig) {
+    this.trpc = config.trpc;
+  }
+
+  /**
+   * Retrieves a resource by ID
+   */
+  abstract retrieve(id: string): Promise<TModel>;
+
+  /**
+   * Lists resources with optional filtering and pagination
+   */
+  abstract list(
+    options?: ListOptions<TFilter>
+  ): Promise<PaginatedResponse<TModel>>;
+
+  /**
+   * Wraps a tRPC operation with error mapping
+   */
+  protected async execute<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      if (isTRPCError(error)) {
+        throw mapTRPCError(error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Creates an async iterator for paginated results
+   */
+  protected createIterator<T = TModel>(
+    options?: IterateOptions<TFilter>
+  ): AsyncGenerator<T, void, undefined> {
+    return createPaginatedIterator<T>(
+      (pagination) =>
+        this.list({
+          filter: options?.filter,
+          ...pagination,
+        }) as unknown as Promise<PaginatedResponse<T>>,
+      { limit: options?.pageSize }
+    );
+  }
+}