@artu-ai/compliance-sdk 0.4.1 → 0.4.2

package/src/sdk/types.ts

@@ -1,304 +0,0 @@
-/**
- * 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

@@ -1,187 +0,0 @@
-/**
- * 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;
-}