@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/sdk/types.ts

@@ -0,0 +1,304 @@
+/**
+ * SDK Core Types
+ *
+ * Base types for SDK configuration that are shared across all jurisdictions.
+ * Jurisdiction-specific types (like MexicoSDKOptions) are defined in their
+ * respective namespace modules.
+ */
+
+import { Jurisdiction, type CodigoActividad } from "@artu-ai/shared";
+import type { APIVersion } from "../utils/trpc-client";
+import type {
+  SDKSessionOptions,
+  SDKSessionOptionsWithReturnTo,
+  SessionResultWithRedirect,
+  SessionResultWithoutRedirect,
+} from "../utils/session";
+
+// ===========================
+// Environment Types
+// ===========================
+
+/**
+ * SDK environment mode
+ * - "test": Uses test data, no real regulatory submissions
+ * - "live": Uses production data, real regulatory submissions
+ */
+export type Environment = "test" | "live";
+
+// ===========================
+// Base SDK Options
+// ===========================
+
+/**
+ * Base SDK configuration options (common to all scopes)
+ */
+/**
+ * Authentication configuration.
+ *
+ * - apiKey (default): use WorkOS API key (header)
+ * - cookie: rely on browser/forwarded cookies (no auth header, credentials include)
+ */
+export type ComplianceAuthMode = "apiKey" | "cookie";
+
+export interface ComplianceAPIKeyAuth {
+  /**
+   * Authentication mode
+   * - "apiKey": use WorkOS API key (header)
+   * - "cookie": rely on browser/forwarded cookies (no auth header, credentials include)
+   */
+  mode?: "apiKey";
+  /**
+   * API key for authentication.
+   * Obtained from WorkOS dashboard.
+   *
+   * If not provided, falls back to the `ARTU_API_KEY` environment variable.
+   *
+   * @example "ak_test_abc123..."
+   */
+  apiKey?: string;
+}
+
+export type FetchCredentials = "include" | "omit" | "same-origin";
+
+export interface ComplianceCookieAuth {
+  /**
+   * Authentication mode
+   * - "apiKey": use WorkOS API key (header)
+   * - "cookie": rely on browser/forwarded cookies (no auth header, credentials include)
+   */
+  mode?: "cookie";
+  /**
+   * Optional fetch credentials policy override.
+   * Defaults to "include" when using cookie mode.
+   */
+  credentials?: FetchCredentials;
+  /**
+   * Custom headers to include with each request.
+   * Useful for server-side cookie forwarding in Next.js.
+   *
+   * @example
+   * ```typescript
+   * // Forward cookies in Next.js server component
+   * const cookieStore = await cookies();
+   * const sdk = new ComplianceSDK({
+   *   mode: "cookie",
+   *   environment: "test",
+   *   headers: { Cookie: cookieStore.toString() },
+   * });
+   * ```
+   */
+  headers?: Record<string, string>;
+}
+
+export type ComplianceAuthOptions = ComplianceAPIKeyAuth | ComplianceCookieAuth;
+
+export type ComplianceSDKOptionsBase = ComplianceAuthOptions & {
+  /**
+   * Target environment for data isolation.
+   * - "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;
+
+  /**
+   * Base URL for the API.
+   *
+   * Priority order:
+   * 1. Explicit baseUrl option
+   * 2. `ARTU_BASE_URL` environment variable
+   * 3. Default production URL: https://api.artu.ai
+   *
+   * Override for local development or custom deployments.
+   *
+   * @example "http://localhost:3001"
+   */
+  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.
+   *
+   * @default "v1"
+   */
+  apiVersion?: APIVersion;
+
+  /**
+   * Request timeout in milliseconds.
+   *
+   * @default 30000 (30 seconds)
+   */
+  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
+// ===========================
+
+/**
+ * SDK scope configuration - base (unscoped or non-Mexico)
+ */
+export interface SDKScopeBase {
+  jurisdiction?: Jurisdiction;
+}
+
+/**
+ * SDK scope configuration - Mexico with optional Actividad Vulnerable
+ */
+export interface SDKScopeMexico {
+  jurisdiction: typeof Jurisdiction.Mexico;
+  actividadVulnerable?: CodigoActividad;
+}
+
+/**
+ * SDK scope configuration
+ */
+export type SDKScope = SDKScopeBase | SDKScopeMexico;
+
+/**
+ * Type guard to check if scope is Mexico-scoped
+ */
+export function isMexicoScope(scope: SDKScope): scope is SDKScopeMexico {
+  return scope.jurisdiction === Jurisdiction.Mexico;
+}
+
+/**
+ * Builds an SDKScope from jurisdiction and actividadVulnerable options.
+ *
+ * @param jurisdiction - Target jurisdiction (optional)
+ * @param actividadVulnerable - Target activity code (only for Mexico)
+ * @returns Properly typed SDKScope
+ *
+ * @example
+ * ```typescript
+ * const scope = buildScope("MX", "AVI");
+ * // { jurisdiction: "MX", actividadVulnerable: "AVI" }
+ *
+ * const unscopedScope = buildScope();
+ * // {}
+ * ```
+ */
+export function buildScope(
+  jurisdiction?: Jurisdiction | "MX" | "US",
+  actividadVulnerable?: CodigoActividad | "AVI" | "JYS" | "TSC"
+): SDKScope {
+  if (jurisdiction === Jurisdiction.Mexico) {
+    return {
+      jurisdiction: Jurisdiction.Mexico,
+      actividadVulnerable: actividadVulnerable as CodigoActividad | undefined,
+    };
+  }
+
+  if (jurisdiction) {
+    return { jurisdiction: jurisdiction as Jurisdiction };
+  }
+
+  return {};
+}
+
+// ===========================
+// Unscoped SDK Options
+// ===========================
+
+/**
+ * SDK options - unscoped or non-Mexico jurisdiction
+ */
+export type ComplianceSDKOptionsUnscoped = ComplianceSDKOptionsBase & {
+  jurisdiction?: Jurisdiction | "MX" | "US";
+};
+
+/**
+ * Options for creating an unscoped SDK (no jurisdiction)
+ */
+export type UnscopedSDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction?: undefined;
+};
+
+/**
+ * Options for creating an SDK with a non-Mexico jurisdiction.
+ * Returns an unscoped SDK since only Mexico has specialized resources.
+ */
+export type OtherJurisdictionSDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction: typeof Jurisdiction.UnitedStates | "US";
+};
+
+// ===========================
+// Base SDK Interface
+// ===========================
+
+/**
+ * Base SDK properties shared across all SDK scopes.
+ * Contains environment info, scope helpers, and supporting resources.
+ */
+export interface BaseComplianceSDK {
+  // Environment getters
+  readonly environment: Environment;
+  readonly apiVersion: APIVersion;
+  readonly isTest: boolean;
+  readonly isLive: boolean;
+
+  // Scope getters
+  readonly jurisdiction: Jurisdiction | undefined;
+  readonly actividadVulnerable: CodigoActividad | undefined;
+  readonly scope: Readonly<SDKScope>;
+  readonly isScoped: boolean;
+  readonly isMexico: boolean;
+  readonly isUnitedStates: boolean;
+  readonly isActividadVulnerable: boolean;
+
+  /**
+   * Fetches current session info from the API (/auth/me).
+   * Only available in cookie auth mode.
+   *
+   * @example Basic usage (session can be null)
+   * ```typescript
+   * const result = await sdk.session();
+   * if (result.isAuthenticated) {
+   *   console.log("User:", result.session.userId);
+   * }
+   * ```
+   *
+   * @example With returnTo (strongly typed - redirectUrl is present when not authenticated)
+   * ```typescript
+   * const result = await sdk.session({ returnTo: "https://..." });
+   * if (result.redirectUrl) {
+   *   redirect(result.redirectUrl);
+   * }
+   * // result.session is guaranteed here (TypeScript knows it's not null)
+   * console.log("User:", result.session.userId);
+   * ```
+   */
+  session(
+    options: SDKSessionOptionsWithReturnTo
+  ): Promise<SessionResultWithRedirect>;
+  session(options?: SDKSessionOptions): Promise<SessionResultWithoutRedirect>;
+}

package/src/utils/environment.ts

@@ -0,0 +1,187 @@
+/**
+ * Environment utilities
+ *
+ * Handles environment validation and base URL resolution.
+ * API keys are generated via WorkOS and do not encode the environment.
+ * The environment is user-specified and validated by the API.
+ */
+
+import { z } from "zod";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * SDK environment schema
+ */
+export const environmentSchema = z.enum(["test", "live"]);
+
+/**
+ * SDK environment type
+ */
+export type Environment = z.infer<typeof environmentSchema>;
+
+/**
+ * SDK environment configuration
+ */
+export interface SDKEnvironmentConfig {
+  /**
+   * The environment to operate in.
+   * - "test": Uses test data, no real regulatory submissions
+   * - "live": Uses production data, real regulatory submissions
+   */
+  environment: Environment;
+
+  /**
+   * Optional custom base URL (overrides default).
+   * Useful for local development or custom deployments.
+   */
+  baseUrl?: string;
+}
+
+// ===========================
+// Constants
+// ===========================
+
+/**
+ * Default production API base URL.
+ * Both test and live environments use the same server.
+ * Environment isolation is handled via the X-Environment header.
+ */
+export const DEFAULT_BASE_URL = "https://api.artu.ai";
+
+// ===========================
+// Functions
+// ===========================
+
+/**
+ * Validates that the environment is valid
+ *
+ * @param env - Environment string to validate
+ * @returns Validated environment
+ * @throws Error if environment is invalid
+ *
+ * @example
+ * ```typescript
+ * const env = validateEnvironment("test"); // "test"
+ * validateEnvironment("staging"); // throws: Invalid environment
+ * ```
+ */
+export function validateEnvironment(env: string): Environment {
+  const result = environmentSchema.safeParse(env);
+  if (!result.success) {
+    throw new Error(`Invalid environment: "${env}". Must be "test" or "live".`);
+  }
+  return result.data;
+}
+
+/**
+ * Checks if a string is a valid environment
+ *
+ * @param env - Environment string to check
+ * @returns True if valid environment
+ *
+ * @example
+ * ```typescript
+ * isValidEnvironment("test"); // true
+ * isValidEnvironment("staging"); // false
+ * ```
+ */
+export function isValidEnvironment(env: string): env is Environment {
+  return environmentSchema.safeParse(env).success;
+}
+
+/**
+ * Gets the default base URL.
+ * Both test and live environments use the same server.
+ *
+ * @returns Default production base URL
+ *
+ * @example
+ * ```typescript
+ * getDefaultBaseUrl(); // "https://api.artu.ai"
+ * ```
+ */
+export function getDefaultBaseUrl(): string {
+  return DEFAULT_BASE_URL;
+}
+
+/**
+ * Resolves the base URL - uses custom if provided, falls back to env var, then default
+ *
+ * Priority order:
+ * 1. Explicit baseUrl option
+ * 2. ARTU_BASE_URL environment variable
+ * 3. Default production URL
+ *
+ * @param config - SDK environment configuration
+ * @returns Resolved base URL
+ *
+ * @example
+ * ```typescript
+ * resolveBaseUrl({ environment: "test" });
+ * // "https://api.artu.ai" (or ARTU_BASE_URL if set)
+ *
+ * resolveBaseUrl({ environment: "test", baseUrl: "http://localhost:3001" });
+ * // "http://localhost:3001"
+ * ```
+ */
+export function resolveBaseUrl(config: SDKEnvironmentConfig): string {
+  // 1. Explicit baseUrl takes priority
+  if (config.baseUrl) {
+    // Normalize: remove trailing slash
+    return config.baseUrl.replace(/\/$/, "");
+  }
+
+  // 2. Fall back to ARTU_BASE_URL environment variable
+  const envBaseUrl = process.env.ARTU_BASE_URL;
+  if (envBaseUrl) {
+    return envBaseUrl.replace(/\/$/, "");
+  }
+
+  // 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;
+}