@artu-ai/compliance-sdk 0.4.0 → 0.4.2

package/src/resources/base.ts

@@ -1,327 +0,0 @@
-/**
- * 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>,
-  TSort = 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, TSort>
-  ): 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, TSort>
-  ): AsyncGenerator<T, void, undefined> {
-    return createPaginatedIterator<T>(
-      (pagination) =>
-        this.list({
-          filter: options?.filter,
-          sort: options?.sort,
-          ...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
- * @typeParam TSort - Sort type for list operations
- */
-export abstract class ReadOnlyResource<
-  TModel,
-  TFilter = Record<string, unknown>,
-  TSort = 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, TSort>
-  ): 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, TSort>
-  ): AsyncGenerator<T, void, undefined> {
-    return createPaginatedIterator<T>(
-      (pagination) =>
-        this.list({
-          filter: options?.filter,
-          sort: options?.sort,
-          ...pagination,
-        }) as unknown as Promise<PaginatedResponse<T>>,
-      { limit: options?.pageSize }
-    );
-  }
-}