@artu-ai/compliance-sdk 0.2.0 → 0.3.0

package/src/sdk/mex/actividad-vulnerable/avi/types.ts

@@ -5,7 +5,10 @@
  */
 
 import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
-import type { ComplianceSDKOptionsBase } from "../../../types";
+import type {
+  ComplianceSDKOptionsBase,
+  DistributiveOmit,
+} from "../../../types";
 import type { MexicoComplianceSDK } from "../../types";
 import {
   AVIClientsResource,
@@ -15,7 +18,11 @@ import {
   MexAddressesResource,
 } from "../../../../resources";
 import { registerScope } from "../../../resource-registry";
+import type { ClientsResource } from "../../../../resources/clients";
+import type { TransactionsResource } from "../../../../resources/transactions";
 import type { ReportsResource } from "../../../../resources/reports";
+import type { BankAccountsResource } from "../../../../resources/bank-accounts";
+import type { AddressesResource } from "../../../../resources/addresses";
 import type { EBRResource } from "../../../../resources/mex/ebr";
 
 // ===========================
@@ -33,7 +40,7 @@ export type AVISDKOptions = ComplianceSDKOptionsBase & {
 /**
  * Options for AVI-scoped SDK (without jurisdiction/activity - pre-configured)
  */
-export type AVIScopedSDKOptions = Omit<
+export type AVIScopedSDKOptions = DistributiveOmit<
   ComplianceSDKOptionsBase,
   "jurisdiction" | "actividadVulnerable"
 >;
@@ -46,8 +53,10 @@ export type AVIScopedSDKOptions = Omit<
  * Mexico AVI-scoped SDK - uses AVI resource types
  * Extends MexicoComplianceSDK with AVI-specific overrides
  */
-export interface AVIComplianceSDK
-  extends Omit<MexicoComplianceSDK, "clients" | "transactions" | "reports"> {
+export interface AVIComplianceSDK extends Omit<
+  MexicoComplianceSDK,
+  "clients" | "transactions" | "reports"
+> {
   readonly clients: AVIClientsResource;
   readonly transactions: AVITransactionsResource;
   readonly reports: AVIReportsResource;
@@ -61,12 +70,17 @@ export interface AVIComplianceSDK
 // ===========================
 
 export function registerAVIScope(): void {
+  // Note: Casts needed due to sort type parameter variance between scoped and base resources
   registerScope("MX:AVI", {
-    clients: (config) => new AVIClientsResource(config),
-    transactions: (config) => new AVITransactionsResource(config),
+    clients: (config) =>
+      new AVIClientsResource(config) as unknown as ClientsResource,
+    transactions: (config) =>
+      new AVITransactionsResource(config) as unknown as TransactionsResource,
     reports: (config) =>
       new AVIReportsResource(config) as unknown as ReportsResource,
-    bankAccounts: (config) => new MexBankAccountsResource(config),
-    addresses: (config) => new MexAddressesResource(config),
+    bankAccounts: (config) =>
+      new MexBankAccountsResource(config) as unknown as BankAccountsResource,
+    addresses: (config) =>
+      new MexAddressesResource(config) as unknown as AddressesResource,
   });
 }

package/src/sdk/mex/actividad-vulnerable/jys/ComplianceSDK.ts

@@ -40,8 +40,11 @@ import type { JYSReportsResource } from "../../../../resources/mex/actividad-vul
 export class JYSComplianceSDKScoped extends MexicoComplianceSDKScoped {
   // Override resource types with JYS-specific types
   // The registry creates these at runtime, we just need correct types
+  // Note: @ts-expect-error is needed for some overrides due to sort type parameter variance
   declare public readonly clients: JYSClientsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly transactions: JYSTransactionsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly reports: JYSReportsResource;
   // addresses and bankAccounts inherited from MexicoComplianceSDKImpl (MexAddressesResource, MexBankAccountsResource)
 

package/src/sdk/mex/actividad-vulnerable/jys/types.ts

@@ -5,7 +5,10 @@
  */
 
 import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
-import type { ComplianceSDKOptionsBase } from "../../../types";
+import type {
+  ComplianceSDKOptionsBase,
+  DistributiveOmit,
+} from "../../../types";
 import type { MexicoComplianceSDK } from "../../types";
 import {
   JYSClientsResource,
@@ -15,7 +18,11 @@ import {
   MexAddressesResource,
 } from "../../../../resources";
 import { registerScope } from "../../../resource-registry";
+import type { ClientsResource } from "../../../../resources/clients";
+import type { TransactionsResource } from "../../../../resources/transactions";
 import type { ReportsResource } from "../../../../resources/reports";
+import type { BankAccountsResource } from "../../../../resources/bank-accounts";
+import type { AddressesResource } from "../../../../resources/addresses";
 import type { EBRResource } from "../../../../resources/mex/ebr";
 
 // ===========================
@@ -33,7 +40,7 @@ export type JYSSDKOptions = ComplianceSDKOptionsBase & {
 /**
  * Options for JYS-scoped SDK (without jurisdiction/activity - pre-configured)
  */
-export type JYSScopedSDKOptions = Omit<
+export type JYSScopedSDKOptions = DistributiveOmit<
   ComplianceSDKOptionsBase,
   "jurisdiction" | "actividadVulnerable"
 >;
@@ -46,8 +53,10 @@ export type JYSScopedSDKOptions = Omit<
  * Mexico JYS-scoped SDK - uses JYS resource types
  * Extends MexicoComplianceSDK with JYS-specific overrides
  */
-export interface JYSComplianceSDK
-  extends Omit<MexicoComplianceSDK, "clients" | "transactions" | "reports"> {
+export interface JYSComplianceSDK extends Omit<
+  MexicoComplianceSDK,
+  "clients" | "transactions" | "reports"
+> {
   readonly clients: JYSClientsResource;
   readonly transactions: JYSTransactionsResource;
   readonly reports: JYSReportsResource;
@@ -61,12 +70,17 @@ export interface JYSComplianceSDK
 // ===========================
 
 export function registerJYSScope(): void {
+  // Note: Casts needed due to sort type parameter variance between scoped and base resources
   registerScope("MX:JYS", {
-    clients: (config) => new JYSClientsResource(config),
-    transactions: (config) => new JYSTransactionsResource(config),
+    clients: (config) =>
+      new JYSClientsResource(config) as unknown as ClientsResource,
+    transactions: (config) =>
+      new JYSTransactionsResource(config) as unknown as TransactionsResource,
     reports: (config) =>
       new JYSReportsResource(config) as unknown as ReportsResource,
-    bankAccounts: (config) => new MexBankAccountsResource(config),
-    addresses: (config) => new MexAddressesResource(config),
+    bankAccounts: (config) =>
+      new MexBankAccountsResource(config) as unknown as BankAccountsResource,
+    addresses: (config) =>
+      new MexAddressesResource(config) as unknown as AddressesResource,
   });
 }

package/src/sdk/mex/actividad-vulnerable/tsc/ComplianceSDK.ts

@@ -40,8 +40,11 @@ import type { TSCReportsResource } from "../../../../resources/mex/actividad-vul
 export class TSCComplianceSDKScoped extends MexicoComplianceSDKScoped {
   // Override resource types with TSC-specific types
   // The registry creates these at runtime, we just need correct types
+  // Note: @ts-expect-error is needed for some overrides due to sort type parameter variance
   declare public readonly clients: TSCClientsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly transactions: TSCTransactionsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly reports: TSCReportsResource;
   // addresses and bankAccounts inherited from MexicoComplianceSDKImpl (MexAddressesResource, MexBankAccountsResource)
 

package/src/sdk/mex/actividad-vulnerable/tsc/types.ts

@@ -5,7 +5,10 @@
  */
 
 import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
-import type { ComplianceSDKOptionsBase } from "../../../types";
+import type {
+  ComplianceSDKOptionsBase,
+  DistributiveOmit,
+} from "../../../types";
 import type { MexicoComplianceSDK } from "../../types";
 import {
   TSCClientsResource,
@@ -15,7 +18,11 @@ import {
   MexAddressesResource,
 } from "../../../../resources";
 import { registerScope } from "../../../resource-registry";
+import type { ClientsResource } from "../../../../resources/clients";
+import type { TransactionsResource } from "../../../../resources/transactions";
 import type { ReportsResource } from "../../../../resources/reports";
+import type { BankAccountsResource } from "../../../../resources/bank-accounts";
+import type { AddressesResource } from "../../../../resources/addresses";
 import type { EBRResource } from "../../../../resources/mex/ebr";
 
 // ===========================
@@ -33,7 +40,7 @@ export type TSCSDKOptions = ComplianceSDKOptionsBase & {
 /**
  * Options for TSC-scoped SDK (without jurisdiction/activity - pre-configured)
  */
-export type TSCScopedSDKOptions = Omit<
+export type TSCScopedSDKOptions = DistributiveOmit<
   ComplianceSDKOptionsBase,
   "jurisdiction" | "actividadVulnerable"
 >;
@@ -46,8 +53,10 @@ export type TSCScopedSDKOptions = Omit<
  * Mexico TSC-scoped SDK - uses TSC resource types
  * Extends MexicoComplianceSDK with TSC-specific overrides
  */
-export interface TSCComplianceSDK
-  extends Omit<MexicoComplianceSDK, "clients" | "transactions" | "reports"> {
+export interface TSCComplianceSDK extends Omit<
+  MexicoComplianceSDK,
+  "clients" | "transactions" | "reports"
+> {
   readonly clients: TSCClientsResource;
   readonly transactions: TSCTransactionsResource;
   readonly reports: TSCReportsResource;
@@ -61,12 +70,17 @@ export interface TSCComplianceSDK
 // ===========================
 
 export function registerTSCScope(): void {
+  // Note: Casts needed due to sort type parameter variance between scoped and base resources
   registerScope("MX:TSC", {
-    clients: (config) => new TSCClientsResource(config),
-    transactions: (config) => new TSCTransactionsResource(config),
+    clients: (config) =>
+      new TSCClientsResource(config) as unknown as ClientsResource,
+    transactions: (config) =>
+      new TSCTransactionsResource(config) as unknown as TransactionsResource,
     reports: (config) =>
       new TSCReportsResource(config) as unknown as ReportsResource,
-    bankAccounts: (config) => new MexBankAccountsResource(config),
-    addresses: (config) => new MexAddressesResource(config),
+    bankAccounts: (config) =>
+      new MexBankAccountsResource(config) as unknown as BankAccountsResource,
+    addresses: (config) =>
+      new MexAddressesResource(config) as unknown as AddressesResource,
   });
 }

package/src/sdk/mex/types.ts

@@ -6,7 +6,11 @@
  */
 
 import { Jurisdiction, type CodigoActividad } from "@artu-ai/shared";
-import type { ComplianceSDKOptionsBase, BaseComplianceSDK } from "../types";
+import type {
+  ComplianceSDKOptionsBase,
+  BaseComplianceSDK,
+  DistributiveOmit,
+} from "../types";
 import type {
   MexClientsResource,
   MexTransactionsResource,
@@ -49,7 +53,7 @@ export type MexicoSDKOptions = ComplianceSDKOptionsBase & {
 /**
  * Options for Mexico-scoped SDK (without jurisdiction - pre-configured)
  */
-export type MexicoScopedSDKOptions = Omit<
+export type MexicoScopedSDKOptions = DistributiveOmit<
   ComplianceSDKOptionsBase,
   "jurisdiction"
 > & {

package/src/sdk/types.ts

@@ -99,9 +99,14 @@ export type ComplianceSDKOptionsBase = ComplianceAuthOptions & {
    * - "test": Uses test data, no real regulatory submissions
    * - "live": Uses production data, real regulatory submissions
    *
+   * Priority order:
+   * 1. Explicit environment option
+   * 2. `ARTU_ENVIRONMENT` environment variable
+   * 3. Default: "test"
+   *
    * The API key must have permissions for the requested environment.
    */
-  environment: Environment;
+  environment?: Environment;
 
   /**
    * Base URL for the API.
@@ -117,6 +122,18 @@ export type ComplianceSDKOptionsBase = ComplianceAuthOptions & {
    */
   baseUrl?: string;
 
+  /**
+   * Organization ID for cookie authentication.
+   *
+   * When using cookie auth mode, this restricts login to a specific organization.
+   * Useful for custom apps to prevent users from logging into the wrong organization.
+   *
+   * Priority order:
+   * 1. Explicit organizationId option
+   * 2. `ARTU_ORGANIZATION_ID` environment variable
+   */
+  organizationId?: string;
+
   /**
    * API version to use.
    * Defaults to latest stable version.
@@ -133,6 +150,16 @@ export type ComplianceSDKOptionsBase = ComplianceAuthOptions & {
   timeout?: number;
 };
 
+/**
+ * Distributive version of Omit that preserves union members.
+ *
+ * Important when omitting keys from option types that include unions (like auth modes),
+ * otherwise `Omit` can erase mode-specific keys (e.g. `apiKey`) due to `keyof` behavior on unions.
+ */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
+  ? Omit<T, K>
+  : never;
+
 // ===========================
 // Scope Types
 // ===========================
@@ -270,6 +297,8 @@ export interface BaseComplianceSDK {
    * console.log("User:", result.session.userId);
    * ```
    */
-  session(options: SDKSessionOptionsWithReturnTo): Promise<SessionResultWithRedirect>;
+  session(
+    options: SDKSessionOptionsWithReturnTo
+  ): Promise<SessionResultWithRedirect>;
   session(options?: SDKSessionOptions): Promise<SessionResultWithoutRedirect>;
 }

package/src/utils/environment.ts

@@ -143,3 +143,45 @@ export function resolveBaseUrl(config: SDKEnvironmentConfig): string {
   // 3. Default to production URL
   return getDefaultBaseUrl();
 }
+
+/**
+ * Resolves the environment - uses explicit value if provided, falls back to env var
+ *
+ * Priority order:
+ * 1. Explicit environment option
+ * 2. ARTU_ENVIRONMENT environment variable
+ * 3. Default to "test"
+ *
+ * @param environment - Optional explicit environment
+ * @returns Resolved environment
+ *
+ * @example
+ * ```typescript
+ * resolveEnvironment("live"); // "live"
+ * resolveEnvironment(); // ARTU_ENVIRONMENT or "test"
+ * ```
+ */
+export function resolveEnvironment(environment?: string): Environment {
+  // 1. Explicit environment takes priority
+  if (environment) {
+    return validateEnvironment(environment);
+  }
+
+  // 2. Fall back to ARTU_ENVIRONMENT environment variable
+  const envEnvironment = process.env.ARTU_ENVIRONMENT;
+  if (envEnvironment) {
+    return validateEnvironment(envEnvironment);
+  }
+
+  // 3. Default to test
+  return "test";
+}
+
+/**
+ * Resolves the organization ID from environment variable
+ *
+ * @returns Organization ID from ARTU_ORGANIZATION_ID or undefined
+ */
+export function resolveOrganizationId(): string | undefined {
+  return process.env.ARTU_ORGANIZATION_ID;
+}

package/src/utils/index.ts

@@ -113,3 +113,22 @@ export {
   isNull,
   isNotNull,
 } from "./filters";
+
+// ===========================
+// Upload Utilities
+// ===========================
+
+export {
+  uploadToS3,
+  normalizeFile,
+  validateFileSize,
+  MAX_FILE_SIZE_BYTES,
+  DEFAULT_UPLOAD_TIMEOUT_MS,
+} from "./upload";
+
+export type {
+  UploadableFile,
+  ProgressCallback,
+  UploadToS3Options,
+  UploadToS3Result,
+} from "./upload";

package/src/utils/session.ts

@@ -43,6 +43,13 @@ interface SessionOptionsBase {
    * Custom fetch implementation (optional).
    */
   fetchImpl?: typeof fetch;
+
+  /**
+   * Optional organization ID to lock the login to a specific organization.
+   * When provided, users will only be able to log in to this organization.
+   * Useful for custom apps to prevent users from logging into the wrong organization.
+   */
+  organizationId?: string;
 }
 
 /**
@@ -75,11 +82,23 @@ export type SessionOptions =
 // (Used by sdk.session() - doesn't require baseUrl/environment)
 // ===========================
 
+/**
+ * Base SDK session options shared across all variants.
+ */
+interface SDKSessionOptionsBase {
+  /**
+   * Optional organization ID to lock the login to a specific organization.
+   * When provided, users will only be able to log in to this organization.
+   * Useful for custom apps to prevent users from logging into the wrong organization.
+   */
+  organizationId?: string;
+}
+
 /**
  * Options for sdk.session() when returnTo is provided.
  * Result will include redirectUrl when not authenticated.
  */
-export interface SDKSessionOptionsWithReturnTo {
+export interface SDKSessionOptionsWithReturnTo extends SDKSessionOptionsBase {
   /**
    * Full URL to return to after authentication.
    * When provided, redirectUrl will be included in the result when not authenticated.
@@ -90,7 +109,7 @@ export interface SDKSessionOptionsWithReturnTo {
 /**
  * Options for sdk.session() when returnTo is not provided.
  */
-export interface SDKSessionOptionsWithoutReturnTo {
+export interface SDKSessionOptionsWithoutReturnTo extends SDKSessionOptionsBase {
   returnTo?: never;
 }
 
@@ -163,10 +182,14 @@ export type SessionResult =
 export function createAuthLoginUrl(options: {
   apiBaseUrl: string;
   returnTo: string;
+  organizationId?: string;
 }): string {
-  const { apiBaseUrl, returnTo } = options;
+  const { apiBaseUrl, returnTo, organizationId } = options;
   const loginUrl = new URL("/auth/login", apiBaseUrl);
   loginUrl.searchParams.set("return_to", returnTo);
+  if (organizationId) {
+    loginUrl.searchParams.set("organization_id", organizationId);
+  }
   return loginUrl.toString();
 }
 
@@ -225,6 +248,12 @@ export async function fetchSession(
     returnTo,
   } = options;
 
+  // Extract organizationId only when returnTo is provided
+  const organizationId =
+    "organizationId" in options
+      ? (options as SessionOptionsWithReturnTo).organizationId
+      : undefined;
+
   const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
 
   const handleUnauthenticated = ():
@@ -237,6 +266,7 @@ export async function fetchSession(
         redirectUrl: createAuthLoginUrl({
           apiBaseUrl: normalizedBaseUrl,
           returnTo,
+          organizationId,
         }),
       };
     }

package/src/utils/trpc-client.ts

@@ -79,6 +79,13 @@ export type TRPCClientConfig = TRPCAuthConfig & {
    * @default 30000
    */
   timeout?: number;
+
+  /**
+   * Organization ID for request validation.
+   * When provided, the API validates that the authenticated
+   * user/API key belongs to this organization.
+   */
+  organizationId?: string;
 };
 
 /**
@@ -129,6 +136,7 @@ export function createAPIClient(config: TRPCClientConfig) {
     environment,
     apiVersion = LATEST_API_VERSION,
     timeout = DEFAULT_TIMEOUT,
+    organizationId,
   } = config;
 
   const mode: TRPCAuthMode = rawMode ?? "apiKey";
@@ -150,11 +158,12 @@ export function createAPIClient(config: TRPCClientConfig) {
     customHeaders = cookieConfig.headers ?? {};
   }
 
-  const baseHeaders = {
+  const baseHeaders: Record<string, string> = {
     ...customHeaders,
     ...authHeaders,
     "X-Environment": environment,
     "X-Request-ID": generateRequestId(),
+    ...(organizationId ? { "X-Organization-ID": organizationId } : {}),
   };
 
   // Normalize baseUrl (remove trailing slash)