mindsim 0.1.6 → 0.1.8

package/src/index.ts

@@ -1,5 +1,5 @@
 import axios, { type AxiosInstance } from "axios";
-import { getApiBaseUrl, loadApiKey } from "./config";
+import { getApiBaseUrl, loadApiKey, loadServiceJson, validateServiceJson } from "./config";
 import { ArtifactsResource } from "./resources/artifacts";
 import { MindTopicsResource } from "./resources/mind-topics";
 import { MindsResource } from "./resources/minds";
@@ -7,10 +7,60 @@ import { PsychometricsResource } from "./resources/psychometrics";
 import { SimulationsResource } from "./resources/simulations";
 import { SnapshotsResource } from "./resources/snapshots";
 import { TagsResource } from "./resources/tags";
+import type { MindsimServiceJson } from "./types";
 import { checkForUpdates, getPackageVersion } from "./version";
 
+// =============================================================================
+// Gap 15 Fix: Browser Compatibility Check
+// =============================================================================
+
+/**
+ * Check if the SDK is running in a Node.js environment.
+ * Some features (like file-based service JSON loading) only work in Node.js.
+ */
+export function isNodeEnvironment(): boolean {
+  return (
+    typeof process !== "undefined" && process.versions != null && process.versions.node != null
+  );
+}
+
+/**
+ * Check if the SDK is running in a browser environment.
+ */
+export function isBrowserEnvironment(): boolean {
+  // Use typeof checks to avoid ReferenceError in Node.js
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return typeof globalThis !== "undefined" && "window" in globalThis && "document" in globalThis;
+}
+
+// =============================================================================
+// Gap 14 Fix: Auth Method Detection
+// =============================================================================
+
+/**
+ * Authentication method used by the MindSim client.
+ */
+export type AuthMethod =
+  | "service_json" // Service JSON credentials (file or base64)
+  | "api_key_env" // MINDSIM_API_KEY environment variable
+  | "api_key_constructor" // API key passed to constructor
+  | "config_file"; // ~/.mindsim/config file
+
+/**
+ * Options for initializing the MindSim client.
+ */
+export interface MindSimOptions {
+  /** Custom API base URL (overrides default and service JSON) */
+  apiBaseUrl?: string;
+  /** Service JSON credentials (alternative to API key) */
+  serviceJson?: MindsimServiceJson;
+}
+
 export class MindSim {
   private client: AxiosInstance;
+  private serviceJson: MindsimServiceJson | null = null;
+  // Gap 14 Fix: Track which auth method was used
+  private authMethod: AuthMethod = "config_file";
 
   public artifacts: ArtifactsResource;
   public minds: MindsResource;
@@ -20,20 +70,72 @@ export class MindSim {
   public simulations: SimulationsResource;
   public tags: TagsResource;
 
-  constructor(apiKey?: string, options?: { apiBaseUrl?: string }) {
+  constructor(apiKey?: string, options?: MindSimOptions) {
     // 1. Trigger the auto-update check (Fire and forget, do not await)
     checkForUpdates().catch(() => {
       // Catching here ensures no unhandled promise rejections in the user's console
       // if the check fails completely.
     });
 
-    const token = apiKey || loadApiKey();
     const sdkVersion = getPackageVersion();
-    const apiBaseUrl = options?.apiBaseUrl || getApiBaseUrl();
+
+    // Priority for credentials:
+    // 1. Constructor apiKey parameter
+    // 2. Constructor serviceJson option
+    // 3. Environment service JSON (MINDSIM_SERVICE_JSON or MINDSIM_SERVICE_JSON_BASE64)
+    // 4. Environment API key (MINDSIM_API_KEY)
+    // 5. Config file (~/.mindsim/config)
+
+    let token: string | null = apiKey || null;
+    let apiBaseUrl = options?.apiBaseUrl || getApiBaseUrl();
+
+    // Track auth method for Gap 14 fix
+    if (apiKey) {
+      this.authMethod = "api_key_constructor";
+    }
+
+    // Check for service JSON if no direct API key provided
+    if (!token) {
+      let serviceJson: MindsimServiceJson | null = null;
+
+      // Gap 3 Fix: Validate serviceJson when passed via constructor options
+      if (options?.serviceJson) {
+        const validation = validateServiceJson(options.serviceJson);
+        if (!validation.valid) {
+          throw new Error(`Invalid serviceJson: ${validation.errors.join(", ")}`);
+        }
+        serviceJson = validation.serviceJson as MindsimServiceJson;
+      } else {
+        // loadServiceJson() already validates internally
+        serviceJson = loadServiceJson();
+      }
+
+      if (serviceJson) {
+        this.serviceJson = serviceJson;
+        this.authMethod = "service_json";
+        token = serviceJson.api_key;
+        // Use API base URL from service JSON if not explicitly overridden
+        if (!options?.apiBaseUrl && serviceJson.api_base_url) {
+          apiBaseUrl = serviceJson.api_base_url;
+        }
+      }
+    }
+
+    // Fallback to traditional loading
+    if (!token) {
+      // Gap 7 Fix: Check if MINDSIM_API_KEY is set (only in Node environment)
+      const hasEnvApiKey = isNodeEnvironment() && process.env.MINDSIM_API_KEY;
+      if (hasEnvApiKey) {
+        this.authMethod = "api_key_env";
+      } else {
+        this.authMethod = "config_file";
+      }
+      token = loadApiKey();
+    }
 
     if (!token) {
       throw new Error(
-        "API Key not found. Please run `mindsim auth` or pass the key to the constructor.",
+        "API Key not found. Please run `mindsim auth`, set MINDSIM_SERVICE_JSON/MINDSIM_SERVICE_JSON_BASE64, or pass credentials to the constructor.",
       );
     }
 
@@ -45,6 +147,10 @@ export class MindSim {
         "x-reasoner-source": "sdk",
         "x-reasoner-sdk": "mindsim/mindsim-sdk-typescript",
         "x-reasoner-sdk-version": sdkVersion,
+        // Include project ID from service JSON for better request tracing
+        ...(this.serviceJson && {
+          "x-mindsim-project-id": this.serviceJson.project_id,
+        }),
       },
     });
 
@@ -56,7 +162,73 @@ export class MindSim {
     this.simulations = new SimulationsResource(this.client);
     this.tags = new TagsResource(this.client);
   }
+
+  /**
+   * Get the loaded service JSON (if any).
+   * Useful for debugging or accessing project metadata.
+   *
+   * @returns The service JSON object or null if not using service JSON auth
+   */
+  public getServiceJson(): MindsimServiceJson | null {
+    return this.serviceJson;
+  }
+
+  // ==========================================================================
+  // Gap 14 Fix: Auth Method Detection Helpers
+  // ==========================================================================
+
+  /**
+   * Check if the client is using service JSON authentication.
+   *
+   * @returns true if using service JSON, false otherwise
+   */
+  public isUsingServiceJsonAuth(): boolean {
+    return this.serviceJson !== null;
+  }
+
+  /**
+   * Get the authentication method used by this client.
+   *
+   * @returns The auth method: 'service_json', 'api_key_env', 'api_key_constructor', or 'config_file'
+   */
+  public getAuthMethod(): AuthMethod {
+    return this.authMethod;
+  }
+
+  /**
+   * Get authentication info for debugging.
+   * Does NOT expose the actual API key.
+   *
+   * @returns Object with auth details (method, project info if service JSON)
+   */
+  public getAuthInfo(): {
+    method: AuthMethod;
+    isServiceJson: boolean;
+    projectId: string | null;
+    projectName: string | null;
+    environment: string | null;
+  } {
+    return {
+      method: this.authMethod,
+      isServiceJson: this.serviceJson !== null,
+      projectId: this.serviceJson?.project_id ?? null,
+      projectName: this.serviceJson?.project_name ?? null,
+      environment: this.serviceJson?.environment ?? null,
+    };
+  }
 }
 
+// Export validation utilities from config
+export { type ServiceJsonValidationResult, validateServiceJson } from "./config";
+
+// Export logger interface (Gap 8 Fix)
+export {
+  createSilentLogger,
+  createVerboseLogger,
+  defaultLogger,
+  getLogger,
+  type MindSimLogger,
+  setLogger,
+} from "./logger";
 // Export types for consumer use
 export * from "./types";

package/src/logger.ts

@@ -0,0 +1,111 @@
+/**
+ * MindSim SDK Logger Interface
+ *
+ * Provides a configurable logging interface so users can control
+ * how SDK messages are logged (or suppressed).
+ *
+ * Gap 8 Fix: Replaces hardcoded console.error with configurable interface.
+ *
+ * Usage:
+ *   import { setLogger, createSilentLogger } from 'mindsim';
+ *
+ *   // Use silent logger to suppress all SDK logs
+ *   setLogger(createSilentLogger());
+ *
+ *   // Use custom logger
+ *   setLogger({
+ *     debug: (msg) => myLogger.debug(`[MindSim] ${msg}`),
+ *     info: (msg) => myLogger.info(`[MindSim] ${msg}`),
+ *     warn: (msg) => myLogger.warn(`[MindSim] ${msg}`),
+ *     error: (msg) => myLogger.error(`[MindSim] ${msg}`),
+ *   });
+ */
+
+/**
+ * Logger interface for the MindSim SDK.
+ * Implement this interface to customize SDK logging behavior.
+ */
+export interface MindSimLogger {
+  /** Debug-level messages (not shown by default) */
+  debug: (message: string, ...args: unknown[]) => void;
+  /** Informational messages */
+  info: (message: string, ...args: unknown[]) => void;
+  /** Warning messages */
+  warn: (message: string, ...args: unknown[]) => void;
+  /** Error messages */
+  error: (message: string, ...args: unknown[]) => void;
+}
+
+/**
+ * Default logger that uses console methods.
+ * Debug is disabled by default.
+ */
+export const defaultLogger: MindSimLogger = {
+  debug: () => {
+    // Debug disabled by default
+  },
+  info: (message: string, ...args: unknown[]) => {
+    console.info(`[MindSim] ${message}`, ...args);
+  },
+  warn: (message: string, ...args: unknown[]) => {
+    console.warn(`[MindSim] ${message}`, ...args);
+  },
+  error: (message: string, ...args: unknown[]) => {
+    console.error(`[MindSim] ${message}`, ...args);
+  },
+};
+
+/**
+ * Create a silent logger that suppresses all SDK logs.
+ * Useful for production environments where you want no SDK output.
+ */
+export function createSilentLogger(): MindSimLogger {
+  const noop = () => {};
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+  };
+}
+
+/**
+ * Create a logger with all levels enabled (including debug).
+ * Useful for development and debugging.
+ */
+export function createVerboseLogger(): MindSimLogger {
+  return {
+    debug: (message: string, ...args: unknown[]) => {
+      console.debug(`[MindSim:DEBUG] ${message}`, ...args);
+    },
+    info: (message: string, ...args: unknown[]) => {
+      console.info(`[MindSim] ${message}`, ...args);
+    },
+    warn: (message: string, ...args: unknown[]) => {
+      console.warn(`[MindSim] ${message}`, ...args);
+    },
+    error: (message: string, ...args: unknown[]) => {
+      console.error(`[MindSim] ${message}`, ...args);
+    },
+  };
+}
+
+// Global logger instance
+let currentLogger: MindSimLogger = defaultLogger;
+
+/**
+ * Set the global logger for the SDK.
+ *
+ * @param logger - The logger implementation to use
+ */
+export function setLogger(logger: MindSimLogger): void {
+  currentLogger = logger;
+}
+
+/**
+ * Get the current logger.
+ * Used internally by the SDK.
+ */
+export function getLogger(): MindSimLogger {
+  return currentLogger;
+}

package/src/types.ts

@@ -55,6 +55,65 @@ export interface SdkKeyDetailResponse {
   };
 }
 
+/**
+ * Valid MindSim scopes for API access.
+ * Matches rainmaker's MindsimScope type (lib/types/developer-portal.ts).
+ */
+export type MindsimScope =
+  | "minds:read" // List/read digital twins
+  | "minds:write" // Create/update digital twins
+  | "simulate:run" // Run simulations
+  | "simulate:read" // Read simulation history
+  | "users:read" // Read org users
+  | "users:write" // Manage org users
+  | "org:admin"; // Full org administration
+
+/**
+ * Valid use cases for developer apps.
+ * Matches rainmaker's DeveloperUseCase type.
+ */
+export type DeveloperUseCase = "internal-workflow" | "customer-facing" | "agentic-ai";
+
+/**
+ * MindSim Service JSON credential format.
+ * Google Cloud-style service account JSON for production deployments.
+ */
+export interface MindsimServiceJson {
+  /** Must be "mindsim_service_account" to identify this as a service JSON */
+  type: "mindsim_service_account";
+  /** Service JSON schema version */
+  version: string;
+  /** App slug (human-readable identifier) */
+  project_id: string;
+  /** App display name */
+  project_name: string;
+  /** Environment (always "production" for service JSON) */
+  environment: "production";
+  /** Service account email (service@{slug}.mindsim.io) */
+  client_email: string;
+  /** API key UUID */
+  client_id: string;
+  /** The actual API key secret */
+  api_key: string;
+  /** API endpoint base URL */
+  api_base_url: string;
+  /** Granted API scopes */
+  scopes: MindsimScope[];
+  /** Application metadata */
+  app_metadata: {
+    app_id: string;
+    workspace_id: string;
+    mindsim_org_id: string;
+    use_case: DeveloperUseCase;
+  };
+  /** ISO 8601 timestamp when credentials were created */
+  created_at: string;
+  /** Optional: ISO 8601 timestamp when credentials expire */
+  expires_at?: string;
+  /** Optional: ISO 8601 timestamp when credentials were issued (same as created_at for new keys) */
+  issued_at?: string;
+}
+
 export interface Tag {
   id: string;
   name: string;

package/src/version.ts

@@ -4,39 +4,96 @@ import path from "node:path";
 import { promisify } from "node:util";
 import axios from "axios";
 import semver from "semver";
+import { getLogger } from "./logger";
 
 const execAsync = promisify(exec);
 
+type PackageManager = "pnpm" | "yarn" | "npm";
+
+interface InstallContext {
+  isGlobal: boolean;
+  packageManager: PackageManager;
+}
+
 /**
- * Detects the package manager used in the current project
+ * Detects the installation context (global vs local, and which package manager)
  */
-const detectPackageManager = (): "pnpm" | "yarn" | "npm" => {
-  const cwd = process.cwd();
-
-  // Check for lockfiles in order of preference
-  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
-    return "pnpm";
+const detectInstallContext = (): InstallContext => {
+  const home = process.env.HOME || "";
+  const appData = process.env.APPDATA || "";
+
+  // Global path patterns mapped to their package managers
+  const globalPatterns: Array<{ pattern: string; pm: PackageManager }> = [
+    // pnpm global paths
+    { pattern: path.join(home, "Library/pnpm"), pm: "pnpm" },
+    { pattern: path.join(home, ".local/share/pnpm"), pm: "pnpm" },
+    { pattern: path.join(appData, "pnpm"), pm: "pnpm" },
+    // yarn global paths
+    { pattern: path.join(home, ".yarn"), pm: "yarn" },
+    { pattern: path.join(home, ".config/yarn"), pm: "yarn" },
+    { pattern: path.join(appData, "Yarn"), pm: "yarn" },
+    // npm global paths (including nvm)
+    { pattern: "/usr/local/lib/node_modules", pm: "npm" },
+    { pattern: "/usr/lib/node_modules", pm: "npm" },
+    { pattern: path.join(home, ".nvm"), pm: "npm" },
+    { pattern: path.join(home, ".npm-global"), pm: "npm" },
+    { pattern: path.join(appData, "npm"), pm: "npm" },
+  ];
+
+  // Check if we're in a global installation path
+  for (const { pattern, pm } of globalPatterns) {
+    if (pattern && __dirname.startsWith(pattern)) {
+      return { isGlobal: true, packageManager: pm };
+    }
   }
-  if (fs.existsSync(path.join(cwd, "yarn.lock"))) {
-    return "yarn";
+
+  // Check if we're in a local project's node_modules
+  if (__dirname.includes("/node_modules/mindsim/")) {
+    // Detect local package manager from lockfiles
+    const cwd = process.cwd();
+    let pm: PackageManager = "npm";
+    if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+      pm = "pnpm";
+    } else if (fs.existsSync(path.join(cwd, "yarn.lock"))) {
+      pm = "yarn";
+    }
+    return { isGlobal: false, packageManager: pm };
   }
-  return "npm";
+
+  // Default: assume global npm (safest default for CLI tools)
+  return { isGlobal: true, packageManager: "npm" };
 };
 
 /**
- * Gets the install command for a specific package manager
+ * Gets the update command for a specific package manager.
+ * Uses install/add with @latest to ensure we get the absolute latest version,
+ * not constrained by semver ranges in package.json.
  */
-const getInstallCommand = (
-  packageManager: "pnpm" | "yarn" | "npm",
+const getUpdateCommand = (
+  packageManager: PackageManager,
   packageName: string,
+  global: boolean,
 ): string => {
+  if (global) {
+    switch (packageManager) {
+      case "pnpm":
+        // pnpm add -g with @latest ensures latest version
+        return `pnpm add -g ${packageName}@latest`;
+      case "yarn":
+        // yarn global add with @latest ensures latest version
+        return `yarn global add ${packageName}@latest`;
+      case "npm":
+        // npm install -g with @latest is more reliable than npm update -g
+        return `npm install -g ${packageName}@latest`;
+    }
+  }
   switch (packageManager) {
     case "pnpm":
       return `pnpm add ${packageName}@latest`;
     case "yarn":
       return `yarn add ${packageName}@latest`;
     case "npm":
-      return `npm install ${packageName}@latest --save`;
+      return `npm install ${packageName}@latest`;
   }
 };
 
@@ -65,7 +122,7 @@ export const getPackageVersion = (): string => {
     const pkg = JSON.parse(content);
     return pkg.version;
   } catch (error) {
-    console.warn("MindSim SDK: Unable to determine current package version.", error);
+    getLogger().warn("Unable to determine current package version.", error);
     return "0.0.0";
   }
 };
@@ -115,7 +172,7 @@ export const checkForUpdates = async (verbose = false): Promise<void> => {
 export const updateSdk = async (): Promise<void> => {
   console.log(`Checking for updates for ${PACKAGE_NAME}...`);
 
-  const packageManager = detectPackageManager();
+  const { isGlobal, packageManager } = detectInstallContext();
 
   try {
     const currentVersion = getPackageVersion();
@@ -127,17 +184,18 @@ export const updateSdk = async (): Promise<void> => {
       return;
     }
 
-    const installCommand = getInstallCommand(packageManager, PACKAGE_NAME);
+    const updateCommand = getUpdateCommand(packageManager, PACKAGE_NAME, isGlobal);
 
     console.log(`Updating from ${currentVersion} to ${latestVersion}...`);
+    console.log(`Installation type: ${isGlobal ? "global" : "local"}`);
     console.log(`Detected package manager: ${packageManager}`);
-    console.log(`Running: ${installCommand}`);
+    console.log(`Running: ${updateCommand}`);
 
-    await execAsync(installCommand);
+    await execAsync(updateCommand);
 
     console.log("✅ Update complete! Please restart your application.");
   } catch (error) {
-    const manualCommand = getInstallCommand(packageManager, PACKAGE_NAME);
+    const manualCommand = getUpdateCommand(packageManager, PACKAGE_NAME, isGlobal);
     console.error("❌ Failed to update MindSim SDK.");
     if (error instanceof Error) {
       console.error(error.message);