@artu-ai/compliance-sdk 0.4.1 → 0.4.3

package/src/utils/session.ts

@@ -1,303 +0,0 @@
-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

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