@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/utils/session.ts

@@ -0,0 +1,273 @@
+import type { Environment } from "./environment";
+
+export type SessionType = "session" | "apiKey";
+
+export interface SessionInfo {
+  organizationId: string;
+  permissions: string[];
+  environment: Environment;
+  userId: string;
+  type: SessionType;
+}
+
+// ===========================
+// Session Options
+// ===========================
+
+/**
+ * Base options for fetchSession.
+ */
+interface SessionOptionsBase {
+  /**
+   * Base URL for the API (e.g. https://api.artu.ai)
+   */
+  baseUrl: string;
+
+  /**
+   * Environment header value ("test" | "live")
+   */
+  environment: Environment;
+
+  /**
+   * Credentials policy for fetch. Defaults to "include".
+   */
+  credentials?: "include" | "omit" | "same-origin";
+
+  /**
+   * Custom headers to include with the request.
+   * Useful for server-side cookie forwarding.
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Custom fetch implementation (optional).
+   */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Options for fetchSession when returnTo is provided.
+ */
+export interface SessionOptionsWithReturnTo extends SessionOptionsBase {
+  /**
+   * Full URL to return to after authentication.
+   * When provided, redirectUrl will be included in the result when not authenticated.
+   */
+  returnTo: string;
+}
+
+/**
+ * Options for fetchSession when returnTo is not provided.
+ */
+export interface SessionOptionsWithoutReturnTo extends SessionOptionsBase {
+  returnTo?: never;
+}
+
+/**
+ * Combined session options type.
+ */
+export type SessionOptions =
+  | SessionOptionsWithReturnTo
+  | SessionOptionsWithoutReturnTo;
+
+// ===========================
+// SDK Session Method Options
+// (Used by sdk.session() - doesn't require baseUrl/environment)
+// ===========================
+
+/**
+ * Options for sdk.session() when returnTo is provided.
+ * Result will include redirectUrl when not authenticated.
+ */
+export interface SDKSessionOptionsWithReturnTo {
+  /**
+   * Full URL to return to after authentication.
+   * When provided, redirectUrl will be included in the result when not authenticated.
+   */
+  returnTo: string;
+}
+
+/**
+ * Options for sdk.session() when returnTo is not provided.
+ */
+export interface SDKSessionOptionsWithoutReturnTo {
+  returnTo?: never;
+}
+
+/**
+ * Combined SDK session options type.
+ */
+export type SDKSessionOptions =
+  | SDKSessionOptionsWithReturnTo
+  | SDKSessionOptionsWithoutReturnTo;
+
+// ===========================
+// Session Results
+// ===========================
+
+/**
+ * Result when user is authenticated.
+ */
+export interface SessionResultAuthenticated {
+  session: SessionInfo;
+  isAuthenticated: true;
+  redirectUrl?: never;
+}
+
+/**
+ * Result when user is NOT authenticated and returnTo was provided.
+ */
+export interface SessionResultUnauthenticatedWithRedirect {
+  session: null;
+  isAuthenticated: false;
+  redirectUrl: string;
+}
+
+/**
+ * Result when user is NOT authenticated and returnTo was NOT provided.
+ */
+export interface SessionResultUnauthenticatedNoRedirect {
+  session: null;
+  isAuthenticated: false;
+  redirectUrl?: never;
+}
+
+/**
+ * Session result when returnTo is provided.
+ * Either authenticated (session present, no redirect) or unauthenticated (no session, redirect present).
+ * This allows TypeScript to narrow: if redirectUrl exists, session is null; otherwise session is present.
+ */
+export type SessionResultWithRedirect =
+  | SessionResultAuthenticated
+  | SessionResultUnauthenticatedWithRedirect;
+
+/**
+ * Session result when returnTo is NOT provided.
+ */
+export type SessionResultWithoutRedirect =
+  | SessionResultAuthenticated
+  | SessionResultUnauthenticatedNoRedirect;
+
+/**
+ * Generic session result type.
+ */
+export type SessionResult =
+  | SessionResultAuthenticated
+  | SessionResultUnauthenticatedWithRedirect
+  | SessionResultUnauthenticatedNoRedirect;
+
+// ===========================
+// Helper
+// ===========================
+
+export function createAuthLoginUrl(options: {
+  apiBaseUrl: string;
+  returnTo: string;
+}): string {
+  const { apiBaseUrl, returnTo } = options;
+  const loginUrl = new URL("/auth/login", apiBaseUrl);
+  loginUrl.searchParams.set("return_to", returnTo);
+  return loginUrl.toString();
+}
+
+// ===========================
+// Fetch Session
+// ===========================
+
+/**
+ * Fetches session from /auth/me.
+ * Returns a result object with session info if authenticated,
+ * or null session with optional redirectUrl if not.
+ *
+ * @example With returnTo (includes redirectUrl when not authenticated)
+ * ```typescript
+ * const result = await fetchSession({
+ *   baseUrl: "https://api.artu.ai",
+ *   environment: "test",
+ *   returnTo: "https://dashboard.artu.ai/env/test/dashboard",
+ * });
+ *
+ * if (result.redirectUrl) {
+ *   redirect(result.redirectUrl);
+ * }
+ *
+ * // TypeScript knows session is guaranteed here
+ * console.log("User:", result.session.userId);
+ * ```
+ *
+ * @example Without returnTo (just check if authenticated)
+ * ```typescript
+ * const result = await fetchSession({
+ *   baseUrl: "https://api.artu.ai",
+ *   environment: "test",
+ * });
+ *
+ * if (result.isAuthenticated) {
+ *   console.log("User:", result.session.userId);
+ * }
+ * ```
+ */
+export function fetchSession(
+  options: SessionOptionsWithReturnTo
+): Promise<SessionResultWithRedirect>;
+export function fetchSession(
+  options: SessionOptionsWithoutReturnTo
+): Promise<SessionResultWithoutRedirect>;
+export async function fetchSession(
+  options: SessionOptions
+): Promise<SessionResult> {
+  const {
+    baseUrl,
+    environment,
+    credentials = "include",
+    headers: customHeaders = {},
+    fetchImpl = fetch,
+    returnTo,
+  } = options;
+
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+  const handleUnauthenticated = ():
+    | SessionResultUnauthenticatedWithRedirect
+    | SessionResultUnauthenticatedNoRedirect => {
+    if (returnTo) {
+      return {
+        session: null,
+        isAuthenticated: false,
+        redirectUrl: createAuthLoginUrl({
+          apiBaseUrl: normalizedBaseUrl,
+          returnTo,
+        }),
+      };
+    }
+
+    return {
+      session: null,
+      isAuthenticated: false,
+    };
+  };
+
+  try {
+    const res = await fetchImpl(`${normalizedBaseUrl}/auth/me`, {
+      headers: {
+        ...customHeaders,
+        "X-Environment": environment,
+      },
+      credentials,
+    });
+
+    if (res.status === 401 || !res.ok) {
+      return handleUnauthenticated();
+    }
+
+    const session = (await res.json()) as SessionInfo;
+
+    return {
+      session,
+      isAuthenticated: true,
+    };
+  } catch {
+    // Network error or other failure - treat as not authenticated
+    return handleUnauthenticated();
+  }
+}

package/src/utils/trpc-client.ts

@@ -0,0 +1,233 @@
+/**
+ * tRPC Client Factory
+ *
+ * Creates a type-safe tRPC client for communicating with the Compliance API.
+ * Uses httpBatchLink for efficient request batching.
+ */
+
+import { createTRPCClient, httpBatchLink, TRPCClientError } from "@trpc/client";
+
+// Type-only import from API (no runtime dependency)
+import type { AppRouter } from "api";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Supported API versions
+ */
+export type APIVersion = "v1";
+
+/**
+ * SDK Environment - determines data isolation
+ */
+export type SDKEnvironment = "test" | "live";
+
+/**
+ * Configuration for creating a tRPC client
+ */
+export type TRPCAuthMode = "apiKey" | "cookie";
+
+export interface TRPCAPIKeyAuthConfig {
+  mode?: "apiKey";
+  apiKey: string;
+}
+
+export interface TRPCCookieAuthConfig {
+  mode: "cookie";
+  credentials?: "include" | "omit" | "same-origin";
+  /**
+   * 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",
+   *   headers: { Cookie: cookieStore.toString() },
+   * });
+   * ```
+   */
+  headers?: Record<string, string>;
+}
+
+export type TRPCAuthConfig = TRPCAPIKeyAuthConfig | TRPCCookieAuthConfig;
+
+export type TRPCClientConfig = TRPCAuthConfig & {
+  /**
+   * Base URL for the API
+   * @example "https://api.compliance.artu.com"
+   */
+  baseUrl: string;
+
+  /**
+   * Target environment for data isolation
+   */
+  environment: SDKEnvironment;
+
+  /**
+   * API version to use. Defaults to latest stable version.
+   * @default "v1"
+   */
+  apiVersion?: APIVersion;
+
+  /**
+   * Request timeout in milliseconds
+   * @default 30000
+   */
+  timeout?: number;
+};
+
+/**
+ * tRPC client type - inferred from AppRouter
+ */
+export type TRPCClient = ReturnType<typeof createTRPCClient<AppRouter>>;
+
+// ===========================
+// Constants
+// ===========================
+
+/**
+ * Current stable API version
+ */
+export const LATEST_API_VERSION: APIVersion = "v1";
+
+/**
+ * Default request timeout in milliseconds
+ */
+export const DEFAULT_TIMEOUT = 30000;
+
+// ===========================
+// Client Factory
+// ===========================
+
+/**
+ * Creates a tRPC client configured for the Compliance API
+ *
+ * @param config - Client configuration
+ * @returns Configured tRPC client
+ *
+ * @example
+ * ```typescript
+ * const client = createAPIClient({
+ *   apiKey: "sk_test_org123_abc123...",
+ *   baseUrl: "https://api.compliance.artu.com",
+ *   environment: "test",
+ * });
+ *
+ * // Make type-safe API calls
+ * const health = await client.health.check.query();
+ * ```
+ */
+export function createAPIClient(config: TRPCClientConfig) {
+  const {
+    mode: rawMode,
+    baseUrl,
+    environment,
+    apiVersion = LATEST_API_VERSION,
+    timeout = DEFAULT_TIMEOUT,
+  } = config;
+
+  const mode: TRPCAuthMode = rawMode ?? "apiKey";
+
+  let authHeaders: Record<string, string> = {};
+  let resolvedCredentials: TRPCCookieAuthConfig["credentials"] | undefined;
+
+  let customHeaders: Record<string, string> = {};
+
+  if (mode === "apiKey") {
+    const apiKey = (config as TRPCAPIKeyAuthConfig).apiKey;
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new Error("API key is required when auth mode is apiKey.");
+    }
+    authHeaders = { Authorization: `Bearer ${apiKey}` };
+  } else {
+    const cookieConfig = config as TRPCCookieAuthConfig;
+    resolvedCredentials = cookieConfig.credentials ?? "include";
+    customHeaders = cookieConfig.headers ?? {};
+  }
+
+  const baseHeaders = {
+    ...customHeaders,
+    ...authHeaders,
+    "X-Environment": environment,
+    "X-Request-ID": generateRequestId(),
+  };
+
+  // Normalize baseUrl (remove trailing slash)
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+  return createTRPCClient<AppRouter>({
+    links: [
+      httpBatchLink({
+        url: `${normalizedBaseUrl}/${apiVersion}/trpc`,
+        headers: () => baseHeaders,
+        fetch: (url, options) => {
+          return fetch(url, {
+            ...options,
+            signal: AbortSignal.timeout(timeout),
+            ...(resolvedCredentials
+              ? { credentials: resolvedCredentials }
+              : {}),
+          });
+        },
+      }),
+    ],
+  });
+}
+
+// ===========================
+// Helpers
+// ===========================
+
+/**
+ * Generates a unique request ID for tracing and debugging
+ *
+ * Format: req_{timestamp}_{random}
+ * @example "req_m1abc23_xk9z4w2"
+ */
+export function generateRequestId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 9);
+  return `req_${timestamp}_${random}`;
+}
+
+/**
+ * Type guard for tRPC client errors
+ *
+ * @param error - Unknown error value
+ * @returns True if error is a TRPCClientError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.clients.create.mutate({ name: "Test" });
+ * } catch (error) {
+ *   if (isTRPCError(error)) {
+ *     console.log("tRPC error code:", error.data?.code);
+ *   }
+ * }
+ * ```
+ */
+export function isTRPCError(
+  error: unknown
+): error is TRPCClientError<AppRouter> {
+  return error instanceof TRPCClientError;
+}
+
+/**
+ * Extracts the request ID from a tRPC error if available
+ *
+ * @param error - tRPC client error
+ * @returns Request ID or undefined
+ */
+export function getRequestIdFromError(
+  error: TRPCClientError<AppRouter>
+): string | undefined {
+  // The request ID may be in the error meta or headers
+  // This will be populated when the API returns it
+  return error.meta?.requestId as string | undefined;
+}

package/dist/chunk-C4Y56E4V.js

@@ -1,23 +0,0 @@
-import { MexicoComplianceSDKScoped, registerScope, MexAddressesResource, MexBankAccountsResource, AVIReportsResource, AVITransactionsResource, AVIClientsResource } from './chunk-E36XEOE2.js';
-
-// src/sdk/mex/actividad-vulnerable/avi/ComplianceSDK.ts
-var AVIComplianceSDKScoped = class extends MexicoComplianceSDKScoped {
-  constructor(options) {
-    super({ ...options, actividadVulnerable: "AVI" });
-  }
-};
-
-// src/sdk/mex/actividad-vulnerable/avi/types.ts
-function registerAVIScope() {
-  registerScope("MX:AVI", {
-    clients: (config) => new AVIClientsResource(config),
-    transactions: (config) => new AVITransactionsResource(config),
-    reports: (config) => new AVIReportsResource(config),
-    bankAccounts: (config) => new MexBankAccountsResource(config),
-    addresses: (config) => new MexAddressesResource(config)
-  });
-}
-
-export { AVIComplianceSDKScoped, registerAVIScope };
-//# sourceMappingURL=chunk-C4Y56E4V.js.map
-//# sourceMappingURL=chunk-C4Y56E4V.js.map

package/dist/chunk-C4Y56E4V.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/sdk/mex/actividad-vulnerable/avi/ComplianceSDK.ts","../src/sdk/mex/actividad-vulnerable/avi/types.ts"],"names":[],"mappings":";;;AAoCO,IAAM,sBAAA,GAAN,cAAqC,yBAAA,CAA0B;AAAA,EACpE,YAAY,OAAA,EAA8B;AACxC,IAAA,KAAA,CAAM,EAAE,GAAG,OAAA,EAAS,mBAAA,EAAqB,OAAO,CAAA;AAAA,EAClD;AACF;;;ACsBO,SAAS,gBAAA,GAAyB;AACvC,EAAA,aAAA,CAAc,QAAA,EAAU;AAAA,IACtB,OAAA,EAAS,CAAC,MAAA,KAAW,IAAI,mBAAmB,MAAM,CAAA;AAAA,IAClD,YAAA,EAAc,CAAC,MAAA,KAAW,IAAI,wBAAwB,MAAM,CAAA;AAAA,IAC5D,OAAA,EAAS,CAAC,MAAA,KACR,IAAI,mBAAmB,MAAM,CAAA;AAAA,IAC/B,YAAA,EAAc,CAAC,MAAA,KAAW,IAAI,wBAAwB,MAAM,CAAA;AAAA,IAC5D,SAAA,EAAW,CAAC,MAAA,KAAW,IAAI,qBAAqB,MAAM;AAAA,GACvD,CAAA;AACH","file":"chunk-C4Y56E4V.js","sourcesContent":["/**\n * AVI-scoped ComplianceSDK\n *\n * Pre-configured SDK for Mexico jurisdiction and Activos Virtuales (AVI) activity.\n * Extends MexicoComplianceSDKScoped to inherit Mexico-specific resources like EBR.\n */\n\nimport { MexicoComplianceSDKScoped } from \"../../ComplianceSDK\";\nimport type { AVIScopedSDKOptions } from \"./types\";\n\n/**\n * AVI-scoped ComplianceSDK.\n * Pre-configured for Mexico jurisdiction and Activos Virtuales (AVI) activity.\n *\n * Inherits Mexico-specific resources:\n * - `ebr` - EBR (Evaluación Basada en Riesgos) for AML/KYC risk evaluation\n *\n * @example\n * ```typescript\n * import { ComplianceSDK } from \"@artu/compliance-sdk/mexico/actividad-vulnerable/avi\";\n *\n * const sdk = new ComplianceSDK({\n *   apiKey: process.env.API_KEY!,\n *   environment: \"test\",\n * });\n *\n * // Already scoped - no need to specify jurisdiction/activity\n * const client = await sdk.clients.create({\n *   type: ClientType.Person,\n *   name: \"Juan García\",\n * });\n *\n * // Access inherited EBR resource\n * const weights = sdk.ebr.presets.suggested();\n * ```\n */\nexport class AVIComplianceSDKScoped extends MexicoComplianceSDKScoped {\n  constructor(options: AVIScopedSDKOptions) {\n    super({ ...options, actividadVulnerable: \"AVI\" });\n  }\n}\n","/**\n * AVI SDK Types & Registration\n *\n * Activos Virtuales (Virtual Assets) - cryptocurrency exchanges, wallets, etc.\n */\n\nimport { Jurisdiction, CodigoActividad } from \"@artu-ai/shared\";\nimport type { ComplianceSDKOptionsBase } from \"../../../types\";\nimport type { MexicoComplianceSDK } from \"../../types\";\nimport {\n  AVIClientsResource,\n  AVITransactionsResource,\n  AVIReportsResource,\n  MexBankAccountsResource,\n  MexAddressesResource,\n} from \"../../../../resources\";\nimport { registerScope } from \"../../../resource-registry\";\nimport type { ReportsResource } from \"../../../../resources/reports\";\nimport type { EBRResource } from \"../../../../resources/mex/ebr\";\n\n// ===========================\n// SDK Options\n// ===========================\n\n/**\n * Options for creating an AVI-scoped SDK\n */\nexport interface AVISDKOptions extends ComplianceSDKOptionsBase {\n  jurisdiction: typeof Jurisdiction.Mexico | \"MX\";\n  actividadVulnerable: typeof CodigoActividad.AVI | \"AVI\";\n}\n\n/**\n * Options for AVI-scoped SDK (without jurisdiction/activity - pre-configured)\n */\nexport type AVIScopedSDKOptions = Omit<\n  ComplianceSDKOptionsBase,\n  \"jurisdiction\" | \"actividadVulnerable\"\n>;\n\n// ===========================\n// Typed SDK Interface\n// ===========================\n\n/**\n * Mexico AVI-scoped SDK - uses AVI resource types\n * Extends MexicoComplianceSDK with AVI-specific overrides\n */\nexport interface AVIComplianceSDK\n  extends Omit<MexicoComplianceSDK, \"clients\" | \"transactions\" | \"reports\"> {\n  readonly clients: AVIClientsResource;\n  readonly transactions: AVITransactionsResource;\n  readonly reports: AVIReportsResource;\n  readonly bankAccounts: MexBankAccountsResource;\n  /** EBR resource for risk-based evaluation */\n  readonly ebr: EBRResource;\n}\n\n// ===========================\n// Registration\n// ===========================\n\nexport function registerAVIScope(): void {\n  registerScope(\"MX:AVI\", {\n    clients: (config) => new AVIClientsResource(config),\n    transactions: (config) => new AVITransactionsResource(config),\n    reports: (config) =>\n      new AVIReportsResource(config) as unknown as ReportsResource,\n    bankAccounts: (config) => new MexBankAccountsResource(config),\n    addresses: (config) => new MexAddressesResource(config),\n  });\n}\n"]}