mindsim 0.1.0

package/tests/resources/simulation.test.ts

@@ -0,0 +1,94 @@
+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 Simulations Resource", () => {
+  let mindsim: MindSim;
+  const MIND_ID = "368fcac9-27d8-4cc1-b479-5b9601110086";
+  const SIM_ID = "123e4567-e89b-12d3-a456-426614174000";
+
+  const mockApiClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+    delete: 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("run() should post payload to simulations endpoint", async () => {
+    const mockResponse = { message: "I would use Python." };
+    mockApiClient.post.mockResolvedValue({ data: mockResponse });
+
+    const payload = {
+      mindId: MIND_ID,
+      scenario: { message: "Hello" },
+    };
+
+    const result = await mindsim.simulations.run(payload);
+
+    expect(mockApiClient.post).toHaveBeenCalledWith(expect.stringContaining("/simulate"), payload);
+    expect(result.message).toBe(mockResponse.message);
+  });
+
+  it("run() with background flag", async () => {
+    mockApiClient.post.mockResolvedValue({
+      data: { message: "Queued" },
+    });
+
+    const payload = {
+      mindId: MIND_ID,
+      scenario: { message: "Analyze this" },
+      runInBackground: true,
+    };
+
+    const result = await mindsim.simulations.run(payload);
+
+    expect(mockApiClient.post).toHaveBeenCalledWith(
+      expect.stringContaining("/simulate"),
+      expect.objectContaining({ runInBackground: true }),
+    );
+    expect(result.message).toBe("Queued");
+  });
+
+  it("list() should get simulations with pagination params", async () => {
+    mockApiClient.get.mockResolvedValue({
+      data: { simulations: [], count: 0 },
+    });
+
+    await mindsim.simulations.list({ offset: 10, limit: 5 });
+
+    expect(mockApiClient.get).toHaveBeenCalledWith("/simulations", {
+      params: { offset: 10, limit: 5 },
+    });
+  });
+
+  it("get() should retrieve specific simulation details", async () => {
+    mockApiClient.get.mockResolvedValue({
+      data: { simulation: { id: SIM_ID }, messages: [] },
+    });
+
+    const result = await mindsim.simulations.get(SIM_ID);
+
+    expect(mockApiClient.get).toHaveBeenCalledWith(`/simulations/${SIM_ID}`);
+    expect(result.simulation.id).toBe(SIM_ID);
+  });
+
+  it("delete() should remove simulation", async () => {
+    mockApiClient.delete.mockResolvedValue({
+      data: { message: "Deleted", simulationId: SIM_ID },
+    });
+
+    const result = await mindsim.simulations.delete(SIM_ID);
+
+    expect(mockApiClient.delete).toHaveBeenCalledWith(`/simulations/${SIM_ID}`);
+    expect(result.simulationId).toBe(SIM_ID);
+  });
+});

package/tests/resources/snapshots.test.ts

@@ -0,0 +1,135 @@
+import axios from "axios";
+import FormData from "form-data";
+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 Snapshots Resource", () => {
+  let mindsim: MindSim;
+
+  const MIND_ID = "ac8ac8c4-05e9-4046-a919-4cbae2f49f22";
+  const ARTIFACT_ID = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
+  const ASSESSMENT_ID = "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11";
+
+  const mockApiClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+    put: 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("list() should retrieve snapshots for a mind", async () => {
+    const mockList = {
+      snapshots: [{ id: ASSESSMENT_ID, status: "completed" }],
+      count: 1,
+    };
+    mockApiClient.get.mockResolvedValue({ data: mockList });
+
+    const result = await mindsim.snapshots.list(MIND_ID);
+
+    expect(mockApiClient.get).toHaveBeenCalledWith(`/minds/${MIND_ID}/snapshots`);
+    expect(result.count).toBe(1);
+    expect(result.snapshots[0].id).toBe(ASSESSMENT_ID);
+  });
+
+  it("create() should execute the 3-step signed URL flow", async () => {
+    const fileBuffer = Buffer.from("fake-pdf-content");
+    const fileName = "test.pdf";
+
+    // 1. Mock Get Signed URL response
+    mockApiClient.get.mockResolvedValueOnce({
+      data: {
+        signedUrl: "https://s3.fake/upload",
+        artifactId: ARTIFACT_ID,
+        fileName: "test.pdf",
+        contentType: "application/pdf",
+      },
+    });
+
+    // 2. Mock the direct axios PUT to the signed URL
+    mockedAxios.put.mockResolvedValue({ status: 200 } as any);
+
+    // 3. Mock the final POST to create snapshot record
+    mockApiClient.post.mockResolvedValue({
+      data: {
+        message: "Success",
+        mindAssessmentId: ASSESSMENT_ID,
+        artifactId: ARTIFACT_ID,
+      },
+    });
+
+    const result = await mindsim.snapshots.create(MIND_ID, {
+      file: fileBuffer,
+      fileName: fileName,
+      contentType: "application/pdf",
+      mindsetDate: "2023-01-01",
+    });
+
+    // Verifications
+    expect(mockApiClient.get).toHaveBeenCalledWith(`/minds/${MIND_ID}/signed-url`, {
+      params: { fileName, contentType: "application/pdf" },
+    });
+
+    // Check global axios PUT was called for file upload
+    expect(mockedAxios.put).toHaveBeenCalledWith(
+      "https://s3.fake/upload",
+      fileBuffer,
+      expect.objectContaining({
+        headers: { "Content-Type": "application/pdf" },
+      }),
+    );
+
+    // Check final POST
+    expect(mockApiClient.post).toHaveBeenCalledWith(
+      `/minds/${MIND_ID}/snapshots`,
+      expect.any(FormData),
+      expect.objectContaining({
+        headers: expect.anything(), // FormData headers
+      }),
+    );
+
+    expect(result.mindAssessmentId).toBe(ASSESSMENT_ID);
+  });
+
+  it("createFromFile() should use FormData and return artifacts", async () => {
+    mockApiClient.post.mockResolvedValue({
+      data: { artifactId: ARTIFACT_ID },
+    });
+
+    await mindsim.snapshots.createFromFile(MIND_ID, {
+      file: Buffer.from("abc"),
+      fileName: "chat.txt",
+    });
+
+    expect(mockApiClient.post).toHaveBeenCalledWith(
+      `/minds/${MIND_ID}/snapshots`,
+      expect.any(FormData),
+      expect.objectContaining({ headers: expect.anything() }),
+    );
+  });
+
+  it("getStatus() should return status object with correct IDs", async () => {
+    mockApiClient.get.mockResolvedValue({
+      data: {
+        id: ASSESSMENT_ID,
+        mindId: MIND_ID,
+        status: "processing",
+      },
+    });
+
+    const status = await mindsim.snapshots.getStatus(MIND_ID, ASSESSMENT_ID);
+    expect(status.status).toBe("processing");
+    expect(status.id).toBe(ASSESSMENT_ID);
+    expect(mockApiClient.get).toHaveBeenCalledWith(
+      `/minds/${MIND_ID}/snapshots/${ASSESSMENT_ID}/status`,
+    );
+  });
+});

package/tests/resources/tags.test.ts

@@ -0,0 +1,87 @@
+import axios from "axios";
+import { beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
+import { MindSim } from "../../src/index";
+import type { Tag } from "../../src/types";
+
+vi.mock("axios");
+const mockedAxios = axios as Mocked<typeof axios>;
+
+describe("MindSim Tags Resource", () => {
+  let mindsim: MindSim;
+
+  const TAG_ID_1 = "47a09167-3b9f-442c-a19c-96398cf238fb";
+  const TAG_ID_2 = "a1ca5e66-6f3a-4d92-ab25-8a86fdb111c1";
+
+  const mockClient = {
+    get: vi.fn(),
+    put: vi.fn(),
+    delete: vi.fn(),
+    post: vi.fn(),
+    defaults: { headers: { common: {} } },
+    interceptors: { request: { use: vi.fn() }, response: { use: vi.fn() } },
+  };
+
+  beforeEach(() => {
+    // setup axios.create to return our mock client
+    mockedAxios.create.mockReturnValue(mockClient as any);
+
+    mindsim = new MindSim("test-api-key");
+  });
+
+  describe("list", () => {
+    it("should fetch and return a list of tags via mindsim.tags.list()", async () => {
+      const mockData: Tag[] = [
+        { id: TAG_ID_1, name: "hero", mindCount: 5 },
+        { id: TAG_ID_2, name: "villain", mindCount: 2 },
+      ];
+
+      // Mock the API response
+      mockClient.get.mockResolvedValue({
+        data: { tags: mockData },
+      });
+
+      // Call via the main SDK instance
+      const result = await mindsim.tags.list();
+
+      // Assertions
+      expect(mockClient.get).toHaveBeenCalledWith("/tags");
+      expect(result).toEqual(mockData);
+      expect(result).toHaveLength(2);
+      expect(result?.[0]?.id).toBe(TAG_ID_1);
+    });
+  });
+
+  describe("update", () => {
+    it("should update a tag and return the updated object via mindsim.tags.update()", async () => {
+      const updatePayload = { name: "superhero" };
+      const mockResponseTag: Tag = {
+        id: TAG_ID_1,
+        name: "superhero",
+        mindCount: 5,
+      };
+
+      mockClient.put.mockResolvedValue({
+        data: { tag: mockResponseTag },
+      });
+
+      const result = await mindsim.tags.update(TAG_ID_1, updatePayload);
+
+      expect(mockClient.put).toHaveBeenCalledWith(`/tags/${TAG_ID_1}`, updatePayload);
+      expect(result).toEqual(mockResponseTag);
+      expect(result.name).toBe("superhero");
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete a tag and return status via mindsim.tags.delete()", async () => {
+      mockClient.delete.mockResolvedValue({
+        data: { deleted: true },
+      });
+
+      const result = await mindsim.tags.delete(TAG_ID_2);
+
+      expect(mockClient.delete).toHaveBeenCalledWith(`/tags/${TAG_ID_2}`);
+      expect(result).toEqual({ deleted: true });
+    });
+  });
+});

package/tests/use-cases/quickstart.test.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import axios from "axios";
+import { beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
+import { MindSim } from "../../src/index";
+
+vi.mock("axios");
+vi.mock("node:fs");
+
+// Mock the version module to prevent file system access during instantiation
+vi.mock("../../src/version", () => ({
+  getPackageVersion: () => "1.0.0",
+  checkForUpdates: vi.fn().mockResolvedValue(undefined),
+}));
+
+const mockedAxios = axios as Mocked<typeof axios>;
+const mockedFs = fs as Mocked<typeof fs>;
+
+describe("Quick Start Workflow Integration", () => {
+  let mindsim: MindSim;
+
+  const BOBBY_ID = "779e640c-67c2-44e5-bc91-b3b43eeaead8";
+  const ARTIFACT_ID = "c56a4180-65aa-42ec-a945-5fd21dec0538";
+  const ASSESSMENT_ID = "550e8400-e29b-41d4-a716-446655440000";
+
+  const mockApiClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    defaults: { headers: { common: {} } },
+    interceptors: { request: { use: vi.fn() }, response: { use: vi.fn() } },
+  };
+
+  beforeEach(() => {
+    mockedAxios.create.mockReturnValue(mockApiClient as any);
+    mockedAxios.put.mockResolvedValue({ status: 200 } as any); // For signed URL upload
+    mindsim = new MindSim("valid-key");
+  });
+
+  it("should execute the full Bobby Tables workflow", async () => {
+    // --- Step 1: Create Mind ---
+    mockApiClient.post.mockResolvedValueOnce({
+      data: {
+        mind: { id: BOBBY_ID, name: "Bobby Tables", email: "bobby@test.com", tags: [] },
+      },
+    });
+
+    const bobby = await mindsim.minds.create({
+      name: "Bobby Tables",
+      email: "bobby@test.com",
+      tags: ["developer"],
+    });
+
+    expect(bobby.id).toBe(BOBBY_ID);
+
+    // --- Step 2: Create Snapshot (Mocking File Read) ---
+    mockedFs.readFileSync.mockReturnValue(Buffer.from("fake-pdf"));
+
+    // Mocks for Snapshot creation flow
+    mockApiClient.get.mockResolvedValueOnce({
+      data: { signedUrl: "http://s3", artifactId: ARTIFACT_ID },
+    }); // signed-url
+
+    mockApiClient.post.mockResolvedValueOnce({
+      data: { mindAssessmentId: ASSESSMENT_ID, artifactId: ARTIFACT_ID },
+    }); // create snapshot record
+
+    const snapshotRes = await mindsim.snapshots.create(bobby.id, {
+      file: fs.readFileSync("dummy.pdf"), // Reads from mock
+      fileName: "dummy.pdf",
+      contentType: "application/pdf",
+    });
+
+    expect(snapshotRes.mindAssessmentId).toBe(ASSESSMENT_ID);
+
+    // --- Step 3: Check Status ---
+    mockApiClient.get.mockResolvedValueOnce({
+      data: { id: ASSESSMENT_ID, mindId: BOBBY_ID, status: "completed" },
+    });
+
+    const status = await mindsim.snapshots.getStatus(bobby.id, snapshotRes.mindAssessmentId);
+    expect(status.status).toBe("completed");
+    expect(status.mindId).toBe(BOBBY_ID);
+  });
+});

package/tests/version.test.ts

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import path from "node:path";
+import axios from "axios";
+import { afterEach, beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
+import { checkForUpdates, getPackageVersion, updateSdk } from "../src/version";
+
+// 1. Define the mock function using vi.hoisted so it's available to the mock factory
+const { mockExecAsync } = vi.hoisted(() => {
+  return { mockExecAsync: vi.fn() };
+});
+
+// 2. Mock node:util to return our hoisted mock function
+vi.mock("node:util", async () => {
+  return {
+    promisify: () => mockExecAsync,
+  };
+});
+
+// 3. Mock other dependencies
+vi.mock("node:fs");
+vi.mock("node:path");
+vi.mock("axios");
+
+const mockedFs = fs as Mocked<typeof fs>;
+const mockedPath = path as Mocked<typeof path>;
+const mockedAxios = axios as Mocked<typeof axios>;
+
+describe("Version Module", () => {
+  const MOCK_PACKAGE_PATH = "/mock/project/package.json";
+  const MOCK_ALT_PATH = "/mock/package.json";
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+
+    // Reset the hoisted mock implementation
+    mockExecAsync.mockReset();
+
+    // Setup standard path mocks
+    mockedPath.resolve.mockReturnValue(MOCK_PACKAGE_PATH);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  describe("getPackageVersion", () => {
+    it("should return version from package.json if it exists at primary path", () => {
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockReturnValue(JSON.stringify({ version: "1.0.0" }));
+
+      const version = getPackageVersion();
+
+      expect(mockedPath.resolve).toHaveBeenCalled();
+      expect(mockedFs.readFileSync).toHaveBeenCalledWith(MOCK_PACKAGE_PATH, "utf-8");
+      expect(version).toBe("1.0.0");
+    });
+
+    it("should try fallback path if primary path is missing", () => {
+      // First check returns false (primary path)
+      // Second check returns true (alt path)
+      mockedFs.existsSync.mockReturnValueOnce(false).mockReturnValueOnce(true);
+      mockedFs.readFileSync.mockReturnValue(JSON.stringify({ version: "1.0.1" }));
+
+      mockedPath.resolve.mockReturnValueOnce(MOCK_PACKAGE_PATH).mockReturnValueOnce(MOCK_ALT_PATH);
+
+      const version = getPackageVersion();
+
+      expect(mockedFs.readFileSync).toHaveBeenCalledWith(MOCK_ALT_PATH, "utf-8");
+      expect(version).toBe("1.0.1");
+    });
+
+    it("should return '0.0.0' and log warning if file read fails", () => {
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockImplementation(() => {
+        throw new Error("Permission denied");
+      });
+
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const version = getPackageVersion();
+
+      expect(version).toBe("0.0.0");
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Unable to determine current package version"),
+        expect.any(Error),
+      );
+    });
+
+    it("should return '0.0.0' if JSON is invalid", () => {
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockReturnValue("INVALID_JSON");
+
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const version = getPackageVersion();
+      expect(version).toBe("0.0.0");
+    });
+  });
+
+  describe("checkForUpdates", () => {
+    beforeEach(() => {
+      // Default local version
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockReturnValue(JSON.stringify({ version: "1.0.0" }));
+    });
+
+    it("should log warning if remote version is greater than local", async () => {
+      mockedAxios.get.mockResolvedValue({
+        data: { "dist-tags": { latest: "1.1.0" } },
+      });
+
+      const consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      await checkForUpdates();
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining("UPDATE AVAILABLE"));
+    });
+
+    it("should not log if versions match", async () => {
+      mockedAxios.get.mockResolvedValue({
+        data: { "dist-tags": { latest: "1.0.0" } },
+      });
+
+      const consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await checkForUpdates(); // verbose defaults to false
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it("should log confirmation if verbose is true and versions match", async () => {
+      mockedAxios.get.mockResolvedValue({
+        data: { "dist-tags": { latest: "1.0.0" } },
+      });
+
+      const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await checkForUpdates(true);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("MindSim SDK is up to date"),
+      );
+    });
+
+    it("should fail silently on network error (non-verbose)", async () => {
+      mockedAxios.get.mockRejectedValue(new Error("Network Error"));
+      const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      await checkForUpdates(false);
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it("should log error on failure if verbose is true", async () => {
+      mockedAxios.get.mockRejectedValue(new Error("Network Error"));
+      const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      await checkForUpdates(true);
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith("Failed to check for updates:", "Network Error");
+    });
+  });
+
+  describe("updateSdk", () => {
+    beforeEach(() => {
+      // Default local version
+      mockedFs.existsSync.mockReturnValue(true);
+      mockedFs.readFileSync.mockReturnValue(JSON.stringify({ version: "1.0.0" }));
+    });
+
+    it("should run npm install if update available", async () => {
+      mockedAxios.get.mockResolvedValue({
+        data: { "dist-tags": { latest: "2.0.0" } },
+      });
+      // Mock the execAsync resolution
+      mockExecAsync.mockResolvedValue({ stdout: "ok", stderr: "" });
+
+      const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await updateSdk();
+
+      expect(mockExecAsync).toHaveBeenCalledWith(
+        "npm install @mindsim/mindsim-sdk-typescript@latest --save",
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining("Update complete"));
+    });
+
+    it("should do nothing if already on latest", async () => {
+      mockedAxios.get.mockResolvedValue({
+        data: { "dist-tags": { latest: "1.0.0" } },
+      });
+
+      const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await updateSdk();
+
+      expect(mockExecAsync).not.toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("already on the latest version"),
+      );
+    });
+
+    it("should handle exec errors", async () => {
+      mockedAxios.get.mockResolvedValue({
+        data: { "dist-tags": { latest: "2.0.0" } },
+      });
+      // Mock execAsync rejection
+      mockExecAsync.mockRejectedValue(new Error("Permission denied"));
+
+      const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      await updateSdk();
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith("❌ Failed to update MindSim SDK.");
+      expect(consoleErrorSpy).toHaveBeenCalledWith("Permission denied");
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "target": "esnext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": false,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests/**/*.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true, // Allows using describe, expect, it without imports
+    environment: "node",
+    clearMocks: true,
+    include: ["tests", "**/*.test.ts", "**/*.spec.ts"],
+    exclude: ["node_modules", "dist"],
+  },
+});