@artu-ai/compliance-sdk 0.0.6 → 0.2.0

package/dist/sdk/types.d.ts

@@ -0,0 +1,209 @@
+/**
+ * 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";
+/**
+ * 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 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
+     *
+     * 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;
+    /**
+     * API version to use.
+     * Defaults to latest stable version.
+     *
+     * @default "v1"
+     */
+    apiVersion?: APIVersion;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+};
+/**
+ * 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 declare function isMexicoScope(scope: SDKScope): scope is SDKScopeMexico;
+/**
+ * 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 declare function buildScope(jurisdiction?: Jurisdiction | "MX" | "US", actividadVulnerable?: CodigoActividad | "AVI" | "JYS" | "TSC"): SDKScope;
+/**
+ * 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 properties shared across all SDK scopes.
+ * Contains environment info, scope helpers, and supporting resources.
+ */
+export interface BaseComplianceSDK {
+    readonly environment: Environment;
+    readonly apiVersion: APIVersion;
+    readonly isTest: boolean;
+    readonly isLive: boolean;
+    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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sdk/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sdk/types.ts"],"names":[],"mappings":"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"}

package/dist/sdk/types.js

@@ -0,0 +1,42 @@
+/**
+ * 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 } from "@artu-ai/shared";
+/**
+ * Type guard to check if scope is Mexico-scoped
+ */
+export function isMexicoScope(scope) {
+    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, actividadVulnerable) {
+    if (jurisdiction === Jurisdiction.Mexico) {
+        return {
+            jurisdiction: Jurisdiction.Mexico,
+            actividadVulnerable: actividadVulnerable,
+        };
+    }
+    if (jurisdiction) {
+        return { jurisdiction: jurisdiction };
+    }
+    return {};
+}

package/dist/utils/environment.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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";
+/**
+ * SDK environment schema
+ */
+export declare const environmentSchema: z.ZodEnum<{
+    test: "test";
+    live: "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;
+}
+/**
+ * Default production API base URL.
+ * Both test and live environments use the same server.
+ * Environment isolation is handled via the X-Environment header.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.artu.ai";
+/**
+ * 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 declare function validateEnvironment(env: string): Environment;
+/**
+ * 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 declare function isValidEnvironment(env: string): env is Environment;
+/**
+ * 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 declare function getDefaultBaseUrl(): string;
+/**
+ * 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 declare function resolveBaseUrl(config: SDKEnvironmentConfig): string;
+//# sourceMappingURL=environment.d.ts.map

package/dist/utils/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/utils/environment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;EAA2B,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAMtD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAM5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,WAAW,CAElE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAenE"}

package/dist/utils/environment.js

@@ -0,0 +1,110 @@
+/**
+ * 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"]);
+// ===========================
+// 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) {
+    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) {
+    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() {
+    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) {
+    // 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();
+}