mindsim 0.1.0

package/src/types.ts

@@ -0,0 +1,185 @@
+export interface AuthConfig {
+  authServerUrl: string;
+  authServerLandingPath: string;
+  authRedirectPath: string;
+  listenPort: string;
+}
+
+export interface AuthResponse {
+  apiKey?: {
+    id: string;
+    key: string;
+  };
+}
+
+export interface Tag {
+  id: string;
+  name: string;
+  organizationId?: string | null;
+  createdAt?: string;
+  updatedAt?: string;
+  mindCount?: number;
+}
+
+export interface Mind {
+  id: string;
+  name: string;
+  slug?: string | null;
+  email?: string | null;
+  imageUrl?: string | null;
+  socialMedia?: Record<string, any> | null;
+  scope: string;
+  isSelf: boolean;
+  organizationId?: string | null;
+  createdAt?: string;
+  updatedAt?: string;
+  tags: Tag[];
+}
+
+export interface CreateMindRequest {
+  name: string;
+  email?: string;
+  imageUrl?: string;
+  socialMedia?: Record<string, any>;
+  tags?: string[];
+}
+
+export interface UpdateMindRequest {
+  name?: string;
+  email?: string;
+  socialMedia?: Record<string, any>;
+  tags?: string[]; // SDK converts this array to a comma-separated string
+}
+
+export interface SearchMindsParams {
+  query: string;
+}
+
+export interface ListMindsParams {
+  tags?: string[]; // SDK converts this array to a comma-separated string
+}
+
+export interface SimulationScenario {
+  message: string;
+}
+
+export interface RunSimulationRequest {
+  mindId: string;
+  scenario: SimulationScenario;
+  runInBackground?: boolean;
+}
+
+export interface SimulationResponse {
+  message: string;
+}
+
+export interface SimulationMessage {
+  id: string;
+  role: "assistant" | "user" | "system";
+  content: { text: string } | any;
+  status: string;
+  createdAt?: string;
+}
+
+export interface Simulation {
+  id: string;
+  userId: string;
+  title: string;
+  mindId?: string | null;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface GetSimulationResponse {
+  simulation: Simulation;
+  messages: SimulationMessage[];
+}
+
+export interface ListSimulationsParams {
+  offset?: number;
+  limit?: number;
+}
+
+export interface ListSimulationsResponse {
+  simulations: Simulation[];
+  count: number;
+}
+
+export interface GetSignedUrlParams {
+  fileName?: string;
+  contentType?: string;
+}
+
+export interface GetSignedUrlResponse {
+  signedUrl: string;
+  fileName: string;
+  artifactId: string;
+  contentType: string;
+}
+
+export interface CreateSnapshotParams {
+  file: Buffer | any; // Buffer (Node) or Blob/File (Browser)
+  fileName: string;
+  contentType: string;
+  mindsetDate?: string;
+}
+
+export interface CreateSnapshotFromFileParams {
+  file?: Buffer | any; // Buffer for Node, File for Browser
+  fileName?: string; // Required if passing a Buffer
+  artifactId?: string;
+  mindsetDate?: string;
+}
+
+export interface CreateSnapshotResponse {
+  message: string;
+  mindAssessmentId: string;
+  artifactId: string;
+}
+
+export interface SnapshotStatus {
+  id: string;
+  mindId: string;
+  status: string;
+  startedAt?: string;
+  completedAt?: string;
+}
+
+export interface MindAssessment {
+  id: string;
+  mindId: string;
+  artifactId?: string | null;
+  mindsetDate?: string | null;
+  status: string;
+  startedAt?: string | null;
+  completedAt?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+  psychometricCount?: number | null;
+  keyTopicCount?: number | null;
+  findingCount?: number | null;
+}
+
+export interface ListSnapshotsResponse {
+  snapshots: MindAssessment[];
+  count: number;
+}
+
+// -- Psychometrics --
+
+export interface PersonDetails {
+  id: string;
+  slug?: string | null;
+  name: string;
+  imageUrl?: string | null;
+  mindDate: string;
+  mindAssesssmentId: string;
+}
+
+export interface GetPsychometricsResponse {
+  personDetails: PersonDetails;
+  dimensionAnalysis?: Record<string, any> | null;
+  metaAnalysis?: Record<string, any> | null;
+  topicsSentimentSummary?: Record<string, any> | null;
+  mindReasonerStopError?: any | null;
+}

package/src/version.ts

@@ -0,0 +1,111 @@
+import { exec } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import axios from "axios";
+import semver from "semver";
+
+const execAsync = promisify(exec);
+
+const PACKAGE_NAME = "@mindsim/mindsim-sdk-typescript";
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}`;
+
+/**
+ * REUSABLE VERSION EXTRACTOR
+ * Reads the version directly from the SDK's package.json
+ */
+export const getPackageVersion = (): string => {
+  try {
+    // Determine path based on whether we are in ./src or ./dist
+    // __dirname is usually ./dist in production
+    const packagePath = path.resolve(__dirname, "../package.json");
+
+    // Fallback if structure differs slightly in dev vs prod
+    if (!fs.existsSync(packagePath)) {
+      const altPath = path.resolve(__dirname, "../../package.json");
+      if (fs.existsSync(altPath)) {
+        return JSON.parse(fs.readFileSync(altPath, "utf-8")).version;
+      }
+    }
+
+    const content = fs.readFileSync(packagePath, "utf-8");
+    const pkg = JSON.parse(content);
+    return pkg.version;
+  } catch (error) {
+    console.warn("MindSim SDK: Unable to determine current package version.", error);
+    return "0.0.0";
+  }
+};
+
+/**
+ * Checks NPM registry for updates and logs a warning if outdated.
+ * @param verbose If true, logs when the version is up to date (useful for CLI 'version' command)
+ */
+export const checkForUpdates = async (verbose = false): Promise<void> => {
+  try {
+    const currentVersion = getPackageVersion();
+
+    // Fetch latest version data from NPM
+    // Set a short timeout so we don't block application boot significantly
+    const { data } = await axios.get(REGISTRY_URL, { timeout: 1500 });
+    const latestVersion = data["dist-tags"].latest;
+
+    if (semver.gt(latestVersion, currentVersion)) {
+      const changelogUrl = `https://www.npmjs.com/package/${PACKAGE_NAME}/v/${latestVersion}`;
+
+      console.warn("\n" + "=".repeat(60));
+      console.warn(`⚠️  UPDATE AVAILABLE: @mindsim/mindsim-sdk-typescript`);
+      console.warn("=".repeat(60));
+      console.warn(`   Current Version: ${currentVersion}`);
+      console.warn(`   Latest Version:  ${latestVersion}`);
+      console.warn("-".repeat(60));
+      console.warn(`   Changelog: ${changelogUrl}`);
+      console.warn(`   Run 'mindsim update' to install the latest version.`);
+      console.warn("=".repeat(60) + "\n");
+    } else if (verbose) {
+      console.log(`MindSim SDK is up to date (v${currentVersion})`);
+    }
+  } catch (error) {
+    // Fail silently on network errors so we don't break the user's workflow
+    if (verbose) {
+      console.error(
+        "Failed to check for updates:",
+        error instanceof Error ? error.message : "Unknown error",
+      );
+    }
+  }
+};
+
+/**
+ * Auto-updates the SDK using npm
+ */
+export const updateSdk = async (): Promise<void> => {
+  console.log(`Checking for updates for ${PACKAGE_NAME}...`);
+
+  try {
+    const currentVersion = getPackageVersion();
+    const { data } = await axios.get(REGISTRY_URL);
+    const latestVersion = data["dist-tags"].latest;
+
+    if (!semver.gt(latestVersion, currentVersion)) {
+      console.log(`You are already on the latest version (${currentVersion}).`);
+      return;
+    }
+
+    console.log(`Updating from ${currentVersion} to ${latestVersion}...`);
+    console.log(`Running: npm install ${PACKAGE_NAME}@latest --save`);
+
+    // We use npm install --save to ensure it updates package.json
+    await execAsync(`npm install ${PACKAGE_NAME}@latest --save`);
+
+    console.log("✅ Update complete! Please restart your application.");
+  } catch (error) {
+    console.error("❌ Failed to update MindSim SDK.");
+    if (error instanceof Error) {
+      console.error(error.message);
+    }
+    console.error(
+      "Please try running manually: npm install @mindsim/mindsim-sdk-typescript@latest",
+    );
+  }
+};

package/tests/auth.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as configModule from "../src/config";
+import { MindSim } from "../src/index";
+
+// Mock the config loader specifically
+vi.mock("../src/config", async (importOriginal) => {
+  const actual = await importOriginal<typeof configModule>();
+  return {
+    ...actual,
+    loadApiKey: vi.fn(),
+  };
+});
+
+describe("MindSim Authentication", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.mocked(configModule.loadApiKey).mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("should instantiate successfully when API key is passed to constructor", () => {
+    const mindsim = new MindSim("test-api-key-const");
+    expect(mindsim).toBeInstanceOf(MindSim);
+    expect(mindsim.minds).toBeDefined();
+  });
+
+  it("should instantiate successfully when API key is in config/env (via loadApiKey)", () => {
+    vi.mocked(configModule.loadApiKey).mockReturnValue("test-api-key-env");
+    const mindsim = new MindSim();
+    expect(mindsim).toBeInstanceOf(MindSim);
+  });
+
+  it("should throw error if no API key is provided or found in env", () => {
+    expect(() => {
+      new MindSim();
+    }).toThrow("API Key not found");
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
+import { getApiBaseUrl, getAuthConfig, loadApiKey, saveApiKey } from "../src/config";
+
+// Mock Node built-ins
+vi.mock("node:fs");
+vi.mock("node:os");
+
+const mockedFs = fs as Mocked<typeof fs>;
+const mockedOs = os as Mocked<typeof os>;
+
+describe("Config Module", () => {
+  const MOCK_HOME_DIR = "/mock/home";
+  const EXPECTED_CONFIG_DIR = path.join(MOCK_HOME_DIR, ".mindsim");
+  const EXPECTED_CONFIG_FILE = path.join(EXPECTED_CONFIG_DIR, "config");
+
+  beforeEach(() => {
+    vi.resetModules();
+    mockedOs.homedir.mockReturnValue(MOCK_HOME_DIR);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.clearAllMocks();
+  });
+
+  describe("loadApiKey", () => {
+    it("should prioritize API key from process.env", () => {
+      vi.stubEnv("MINDSIM_API_KEY", "env-key-123");
+
+      // Even if file exists, env should win
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockReturnValue(JSON.stringify({ apiKey: "file-key-456" }));
+
+      const key = loadApiKey();
+      expect(key).toBe("env-key-123");
+    });
+
+    it("should load from config file if env var is missing", () => {
+      vi.stubEnv("MINDSIM_API_KEY", ""); // Ensure env is empty
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockReturnValue(JSON.stringify({ apiKey: "file-key-456" }));
+
+      const key = loadApiKey();
+      expect(key).toBe("file-key-456");
+      expect(mockedFs.readFileSync).toHaveBeenCalledWith(EXPECTED_CONFIG_FILE, "utf-8");
+    });
+
+    it("should return null if neither env var nor file exists", () => {
+      vi.stubEnv("MINDSIM_API_KEY", "");
+      mockedFs.existsSync.mockReturnValue(false);
+
+      const key = loadApiKey();
+      expect(key).toBeNull();
+    });
+
+    it("should return null and log error if file read fails", () => {
+      vi.stubEnv("MINDSIM_API_KEY", "");
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockImplementation(() => {
+        throw new Error("File permission denied");
+      });
+
+      // Spy on console.error to suppress output during test
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      const key = loadApiKey();
+      expect(key).toBeNull();
+      expect(consoleSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe("saveApiKey", () => {
+    it("should create directory and write config file", () => {
+      const NEW_KEY = "new-api-key-789";
+      mockedFs.existsSync.mockReturnValue(false); // Dir doesn't exist
+
+      saveApiKey(NEW_KEY);
+
+      expect(mockedFs.mkdirSync).toHaveBeenCalledWith(EXPECTED_CONFIG_DIR, { recursive: true });
+      expect(mockedFs.writeFileSync).toHaveBeenCalledWith(
+        EXPECTED_CONFIG_FILE,
+        JSON.stringify({ apiKey: NEW_KEY }, null, 2),
+      );
+    });
+
+    it("should write config file without creating dir if dir exists", () => {
+      mockedFs.existsSync.mockReturnValue(true); // Dir exists
+
+      saveApiKey("key");
+
+      expect(mockedFs.mkdirSync).not.toHaveBeenCalled();
+      expect(mockedFs.writeFileSync).toHaveBeenCalled();
+    });
+  });
+
+  describe("getAuthConfig", () => {
+    it("should return default values when env vars are not set", () => {
+      const config = getAuthConfig();
+      expect(config.authServerUrl).toBe("https://app.mindsim.com/sdk/authorize");
+      expect(config.authRedirectPath).toBe("http://localhost:4242/callback");
+      expect(config.listenPort).toBe("4242");
+    });
+
+    it("should return env overrides when set", () => {
+      vi.stubEnv("MINDSIM_AUTH_SERVER_URL", "https://dev.mindsim.com/auth");
+      vi.stubEnv("MINDSIM_AUTH_REDIRECT_URI", "http://custom-callback");
+      vi.stubEnv("MINDSIM_AUTH_PORT", "8080");
+
+      const config = getAuthConfig();
+      expect(config.authServerUrl).toBe("https://dev.mindsim.com/auth");
+      expect(config.authRedirectPath).toBe("http://custom-callback");
+      expect(config.listenPort).toBe("8080");
+    });
+  });
+
+  describe("getApiBaseUrl", () => {
+    it("should return default URL", () => {
+      expect(getApiBaseUrl()).toBe("https://app.mindsim.com/api/public/v1");
+    });
+
+    it("should return override from environment", () => {
+      vi.stubEnv("MIND_SIM_API_BASE_URL", "https://staging.api.mindsim.com");
+      expect(getApiBaseUrl()).toBe("https://staging.api.mindsim.com");
+    });
+  });
+});

package/tests/resources/minds.test.ts

@@ -0,0 +1,119 @@
+import axios from "axios";
+import { beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
+import { MindSim } from "../../src/index";
+import type { Mind } from "../../src/types";
+
+vi.mock("axios");
+const mockedAxios = axios as Mocked<typeof axios>;
+
+describe("MindSim Minds Resource", () => {
+  let mindsim: MindSim;
+
+  const MIND_ID = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+  const TAG_ID_1 = "56255954-189f-4a1e-a355-08a1704af943";
+
+  const mockClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    delete: vi.fn(),
+    defaults: { headers: { common: {} } },
+    interceptors: { request: { use: vi.fn() }, response: { use: vi.fn() } },
+  };
+
+  beforeEach(() => {
+    // Mock axios.create to return our mockClient
+    mockedAxios.create.mockReturnValue(mockClient as any);
+    mindsim = new MindSim("fake-key");
+  });
+
+  it("create() should transform tag array to comma-separated string", async () => {
+    const mockResponse: Mind = {
+      id: MIND_ID,
+      name: "Bobby",
+      scope: "private",
+      isSelf: false,
+      tags: [],
+    };
+
+    mockClient.post.mockResolvedValue({ data: { mind: mockResponse } });
+
+    const result = await mindsim.minds.create({
+      name: "Bobby",
+      tags: ["dev", "ts"],
+    });
+
+    expect(mockClient.post).toHaveBeenCalledWith("/minds", {
+      name: "Bobby",
+      tags: "dev,ts", // Verify transformation
+    });
+    expect(result).toEqual(mockResponse);
+    expect(result.id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+  });
+
+  it("update() should PUT with transformed tags", async () => {
+    const mockResponse: Mind = {
+      id: MIND_ID,
+      name: "Bobby Updated",
+      scope: "private",
+      isSelf: false,
+      tags: [],
+    };
+
+    mockClient.put.mockResolvedValue({ data: { mind: mockResponse } });
+
+    const result = await mindsim.minds.update(MIND_ID, {
+      name: "Bobby Updated",
+      tags: ["lead", "admin"],
+    });
+
+    expect(mockClient.put).toHaveBeenCalledWith(`/minds/${MIND_ID}`, {
+      name: "Bobby Updated",
+      tags: "lead,admin", // Verify transformation to string
+    });
+    expect(result.name).toBe("Bobby Updated");
+  });
+
+  it("delete() should DELETE mind", async () => {
+    mockClient.delete.mockResolvedValue({ data: { success: true } });
+
+    const result = await mindsim.minds.delete(MIND_ID);
+
+    expect(mockClient.delete).toHaveBeenCalledWith(`/minds/${MIND_ID}`);
+    expect(result.success).toBe(true);
+  });
+
+  it("list() should handle tag filtering", async () => {
+    const mockMinds = [{ id: MIND_ID, name: "A" }];
+    mockClient.get.mockResolvedValue({ data: { minds: mockMinds } });
+
+    await mindsim.minds.list({ tags: ["hero"] });
+
+    expect(mockClient.get).toHaveBeenCalledWith("/minds", {
+      params: { tagNames: "hero" },
+    });
+  });
+
+  it("get() should retrieve a mind by ID", async () => {
+    const mockMind = { id: MIND_ID, name: "Sarah" };
+    mockClient.get.mockResolvedValue({ data: mockMind });
+
+    const result = await mindsim.minds.get(MIND_ID);
+    expect(mockClient.get).toHaveBeenCalledWith(`/minds/${MIND_ID}`);
+    expect(result.id).toBe(MIND_ID);
+  });
+
+  it("setTags() should PUT to correct endpoint", async () => {
+    mockClient.put.mockResolvedValue({
+      data: { mind: { id: MIND_ID, tags: [{ id: TAG_ID_1, name: "one" }] } },
+    });
+
+    await mindsim.minds.setTags(MIND_ID, { tags: ["one", "two"] });
+
+    expect(mockClient.put).toHaveBeenCalledWith(`/minds/${MIND_ID}/tags`, {
+      tagNames: ["one", "two"],
+    });
+  });
+});

package/tests/resources/psychometrics.test.ts

@@ -0,0 +1,38 @@
+import axios from "axios";
+import { beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
+import { MindSim } from "../../src/index";
+
+vi.mock("axios");
+const mockedAxios = axios as Mocked<typeof axios>;
+
+describe("MindSim Psychometrics Resource", () => {
+  let mindsim: MindSim;
+  const SNAPSHOT_ID = "123e4567-e89b-12d3-a456-426614174003";
+
+  const mockApiClient = {
+    get: vi.fn(),
+    defaults: { headers: { common: {} } },
+    interceptors: { request: { use: vi.fn() }, response: { use: vi.fn() } },
+  };
+
+  beforeEach(() => {
+    mockedAxios.create.mockReturnValue(mockApiClient as any);
+    mindsim = new MindSim("fake-key");
+  });
+
+  it("get() should fetch psychometrics for a specific snapshot", async () => {
+    const mockResponse = {
+      personDetails: { name: "John Doe", mindAssesssmentId: SNAPSHOT_ID },
+      dimensionAnalysis: { openness: 0.8 },
+    };
+
+    mockApiClient.get.mockResolvedValue({ data: mockResponse });
+
+    const result = await mindsim.psychometrics.get(SNAPSHOT_ID);
+
+    // Note: Endpoint is /snapshots/{id}/psychometrics, not /minds/...
+    expect(mockApiClient.get).toHaveBeenCalledWith(`/snapshots/${SNAPSHOT_ID}/psychometrics`);
+    expect(result.personDetails.name).toBe("John Doe");
+    expect(result.dimensionAnalysis?.openness).toBe(0.8);
+  });
+});