@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/utils/session.ts

@@ -0,0 +1,303 @@
+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;
+
+  /**
+   * 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 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)
+// ===========================
+
+/**
+ * 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 extends SDKSessionOptionsBase {
+  /**
+   * 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 extends SDKSessionOptionsBase {
+  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;
+  organizationId?: string;
+}): string {
+  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();
+}
+
+// ===========================
+// 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;
+
+  // Extract organizationId only when returnTo is provided
+  const organizationId =
+    "organizationId" in options
+      ? (options as SessionOptionsWithReturnTo).organizationId
+      : undefined;
+
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+  const handleUnauthenticated = ():
+    | SessionResultUnauthenticatedWithRedirect
+    | SessionResultUnauthenticatedNoRedirect => {
+    if (returnTo) {
+      return {
+        session: null,
+        isAuthenticated: false,
+        redirectUrl: createAuthLoginUrl({
+          apiBaseUrl: normalizedBaseUrl,
+          returnTo,
+          organizationId,
+        }),
+      };
+    }
+
+    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,242 @@
+/**
+ * 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;
+
+  /**
+   * Organization ID for request validation.
+   * When provided, the API validates that the authenticated
+   * user/API key belongs to this organization.
+   */
+  organizationId?: string;
+};
+
+/**
+ * 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,
+    organizationId,
+  } = 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: Record<string, string> = {
+    ...customHeaders,
+    ...authHeaders,
+    "X-Environment": environment,
+    "X-Request-ID": generateRequestId(),
+    ...(organizationId ? { "X-Organization-ID": organizationId } : {}),
+  };
+
+  // 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;
+}