mindsim 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "mindsim",
+  "version": "0.1.0",
+  "description": "The official MindSim typescript SDK allows you to programmatically create digital minds, populate them with conversational data, and run powerful simulations to get an accurate preview of how the person will think, feel, say, and act in any scenario.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mindsim": "./dist/cli.js"
+  },
+  "scripts": {
+    "start": "node ./dist/cli.js",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build",
+    "lint": "biome check --write .",
+    "lint:check": "biome check .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "type-check": "tsc --noEmit",
+    "test": "npm run test:unit",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindsimulator/mindsim-sdk-typescript.git"
+  },
+  "keywords": [
+    "mindsim",
+    "digital mind",
+    "simulation",
+    "psychometrics",
+    "sdk",
+    "typescript"
+  ],
+  "author": "reasoner-developer",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mindsimulator/mindsim-sdk-typescript/issues"
+  },
+  "homepage": "https://github.com/mindsimulator/mindsim-sdk-typescript#readme",
+  "devDependencies": {
+    "@biomejs/biome": "2.3.6",
+    "@types/node": "^24.10.1",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "commander": "^14.0.2",
+    "open": "^11.0.0",
+    "semver": "^7.6.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,131 @@
+import http from "node:http";
+import url from "node:url";
+import open from "open";
+import { getAuthConfig, saveApiKey } from "./config";
+import type { AuthResponse } from "./types";
+
+// CONFIGURATION
+const authConfig = getAuthConfig();
+
+/**
+ * Starts the login flow
+ */
+export async function login(): Promise<void> {
+  console.log("Initiating authentication...");
+
+  // 1. Create a Promise that resolves when the local server receives the code
+  const apiKey = await listenForCallback();
+
+  console.log("Authorization succeeded.");
+
+  // 2. Exchange authorization code for access token
+  try {
+    // 3. Save credentials to disk
+    saveApiKey(apiKey);
+
+    console.log("✅ Successfully logged in! Credentials saved.");
+  } catch (error) {
+    console.error("❌ Authentication failed:", error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Spins up a temporary local server to catch the redirect
+ */
+function listenForCallback(): Promise<string> {
+  const callbackPath = new URL(authConfig.authRedirectPath).pathname;
+
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      if (!req.url) return;
+
+      const parsedUrl = url.parse(req.url, true);
+
+      const headers = {
+        "Access-Control-Allow-Origin": new URL(authConfig.authServerUrl).origin,
+        "Access-Control-Allow-Methods": "OPTIONS, POST, GET",
+        "Access-Control-Max-Age": 2592000, // 30 days
+        "Access-Control-Allow-Headers": "Content-Type,Authorization",
+        "Access-Control-Allow-Credentials": "true",
+      };
+
+      // Check if the request is for the callback path
+      if (parsedUrl.pathname === callbackPath) {
+        if (req.method === "OPTIONS") {
+          res.writeHead(204, headers);
+          res.end();
+          return;
+        }
+
+        if (req.method === "POST") {
+          let body = "";
+
+          req.on("data", (chunk) => {
+            body += chunk.toString(); // Collect data chunks
+          });
+
+          req.on("end", () => {
+            let authResponseData: AuthResponse | null = null;
+
+            try {
+              authResponseData = JSON.parse(body);
+            } catch (err) {
+              console.error(`Got an invalid response: ${body}. Reason: ${err}`);
+              reject(err);
+            }
+
+            if (!authResponseData) {
+              res.end("No api key found");
+              return;
+            }
+
+            const apiKey = authResponseData?.apiKey?.key;
+
+            if (!apiKey) {
+              res.writeHead(400, { "Content-Type": "text/html" });
+              res.end(`<h1>Authentication Error</h1><p>API Key Not Found</p>`);
+              server.close();
+              reject(new Error("API Key Not Found"));
+              return;
+            }
+
+            if (apiKey) {
+              // Send a nice "Close this window" message to the user
+              res.writeHead(200, { "Content-Type": "text/html", ...headers });
+              res.end(`
+                <h1>Authentication Successful</h1>
+                <p>You can close this window and return to your terminal.</p>
+                <script>window.close()</script>
+              `);
+
+              server.close();
+              resolve(apiKey);
+            } else {
+              res.end("No code found");
+            }
+          });
+        }
+      }
+    });
+
+    server.listen(authConfig.listenPort, async () => {
+      const state = JSON.stringify({
+        redirect: `${authConfig.authServerLandingPath}?initCallbackUrl=${encodeURIComponent(authConfig.authRedirectPath)}`,
+      });
+
+      const encodedState = btoa(state);
+
+      const loginUrl = `${authConfig.authServerUrl}?state=${encodedState}`;
+
+      console.log(`Listening on port ${authConfig.listenPort}...`);
+      console.log(`Opening browser to: ${loginUrl}`);
+
+      await open(loginUrl);
+    });
+
+    server.on("error", (err) => {
+      reject(err);
+    });
+  });
+}

package/src/cli.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { login } from "./auth";
+import { checkForUpdates, getPackageVersion, updateSdk } from "./version";
+
+const program = new Command();
+
+const main = async () => {
+  program.name("mindsim").description("CLI for Mindsim SDK").version(getPackageVersion()); // Use the reusable extractor
+
+  program
+    .command("version")
+    .description("Output your current MindSim CLI version and check for updates")
+    .action(async () => {
+      // When explicitly asking for version, be verbose about update status
+      console.log(getPackageVersion());
+      await checkForUpdates(true);
+    });
+
+  // The Auth Command
+  program
+    .command("auth")
+    .description("Login to Mindsim via browser")
+    .action(async () => {
+      await checkForUpdates(false);
+      await login();
+    });
+
+  // NEW: The Update Command
+  program
+    .command("update")
+    .description("Auto-update the MindSim SDK to the latest version")
+    .action(async () => {
+      await updateSdk();
+    });
+
+  program.parse(process.argv);
+};
+
+main();

package/src/config.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { AuthConfig } from "./types";
+
+const API_BASE_URL = "https://app.mindsim.com/api/public/v1";
+const AUTH_SERVER_URL = "https://app.mindsim.com/sdk/authorize";
+const AUTH_SERVER_LANDING_PATH = "/sdk-success";
+const AUTH_REDIRECT_URI = "http://localhost:4242/callback";
+const AUTH_PORT = "4242";
+
+export function getConfigDir() {
+  return path.join(os.homedir(), ".mindsim");
+}
+
+export function getConfigFile() {
+  return path.join(getConfigDir(), "config");
+}
+
+export const loadApiKey = (): string | null => {
+  try {
+    if (process.env.MINDSIM_API_KEY) {
+      return process.env.MINDSIM_API_KEY;
+    }
+
+    const configFile = getConfigFile();
+
+    if (fs.existsSync(configFile)) {
+      const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      return config.apiKey || null;
+    }
+  } catch (error) {
+    // TODO: define logging interface so users can control where they are written to
+    console.error(error);
+  }
+  return null;
+};
+
+export const saveApiKey = (apiKey: string): void => {
+  const configDir = getConfigDir();
+  const configFile = getConfigFile();
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+  fs.writeFileSync(configFile, JSON.stringify({ apiKey }, null, 2));
+};
+
+export const getAuthConfig = (): AuthConfig => {
+  return {
+    authServerUrl: process.env.MINDSIM_AUTH_SERVER_URL || AUTH_SERVER_URL,
+    authServerLandingPath: AUTH_SERVER_LANDING_PATH,
+    authRedirectPath: process.env.MINDSIM_AUTH_REDIRECT_URI || AUTH_REDIRECT_URI,
+    listenPort: process.env.MINDSIM_AUTH_PORT || AUTH_PORT,
+  };
+};
+
+export const getApiBaseUrl = () => {
+  return process.env.MIND_SIM_API_BASE_URL || API_BASE_URL;
+};

package/src/index.ts

@@ -0,0 +1,59 @@
+import axios, { type AxiosInstance } from "axios";
+import { getApiBaseUrl, loadApiKey } from "./config";
+import { ArtifactsResource } from "./resources/artifacts";
+import { MindsResource } from "./resources/minds";
+import { PsychometricsResource } from "./resources/psychometrics";
+import { SimulationsResource } from "./resources/simulations";
+import { SnapshotsResource } from "./resources/snapshots";
+import { TagsResource } from "./resources/tags";
+import { checkForUpdates, getPackageVersion } from "./version";
+
+export class MindSim {
+  private client: AxiosInstance;
+
+  public artifacts: ArtifactsResource;
+  public minds: MindsResource;
+  public psychometrics: PsychometricsResource;
+  public snapshots: SnapshotsResource;
+  public simulations: SimulationsResource;
+  public tags: TagsResource;
+
+  constructor(apiKey?: string, options?: { apiBaseUrl?: string }) {
+    // 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();
+
+    if (!token) {
+      throw new Error(
+        "API Key not found. Please run `mindsim auth` or pass the key to the constructor.",
+      );
+    }
+
+    this.client = axios.create({
+      baseURL: apiBaseUrl,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        "x-reasoner-source": "sdk",
+        "x-reasoner-sdk": "mindsim/mindsim-sdk-typescript",
+        "x-reasoner-sdk-version": sdkVersion,
+      },
+    });
+
+    this.artifacts = new ArtifactsResource(this.client);
+    this.minds = new MindsResource(this.client);
+    this.psychometrics = new PsychometricsResource(this.client);
+    this.snapshots = new SnapshotsResource(this.client);
+    this.simulations = new SimulationsResource(this.client);
+    this.tags = new TagsResource(this.client);
+  }
+}
+
+// Export types for consumer use
+export * from "./types";

package/src/resources/artifacts.ts

@@ -0,0 +1,13 @@
+import type { AxiosInstance } from "axios";
+import type { GetSignedUrlParams, GetSignedUrlResponse } from "../types";
+
+export class ArtifactsResource {
+  constructor(private client: AxiosInstance) {}
+
+  async getSignedUrl(mindId: string, params?: GetSignedUrlParams): Promise<GetSignedUrlResponse> {
+    const response = await this.client.get<GetSignedUrlResponse>(`/minds/${mindId}/signed-url`, {
+      params,
+    });
+    return response.data;
+  }
+}

package/src/resources/minds.ts

@@ -0,0 +1,98 @@
+import type { AxiosInstance } from "axios";
+import type {
+  CreateMindRequest,
+  ListMindsParams,
+  Mind,
+  SearchMindsParams,
+  UpdateMindRequest,
+} from "../types";
+
+export class MindsResource {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * List all minds
+   */
+  async list(params: ListMindsParams): Promise<Mind[]> {
+    const query: { [key: string]: string } = {};
+
+    if (params?.tags && params.tags?.length > 0) {
+      query.tagNames = params.tags.join(",");
+    }
+
+    const response = await this.client.get<{ minds: Mind[] }>("/minds", {
+      params: query,
+    });
+    return response.data.minds;
+  }
+
+  /**
+   * Create a new mind
+   */
+  async create(data: CreateMindRequest): Promise<Mind> {
+    let createTags: string | undefined;
+
+    if (data?.tags && data?.tags?.length > 0) {
+      createTags = data.tags.join(",");
+    }
+    const response = await this.client.post<{ mind: Mind }>("/minds", {
+      ...data,
+      tags: createTags,
+    });
+    return response.data.mind;
+  }
+
+  /**
+   * Get a specific mind by ID
+   */
+  async get(mindId: string): Promise<Mind> {
+    const response = await this.client.get<{ id: string } & Mind>(`/minds/${mindId}`);
+    return response.data;
+  }
+
+  /**
+   * Update a specific mind by ID
+   */
+  async update(mindId: string, data: UpdateMindRequest): Promise<Mind> {
+    let updateTags: string | undefined;
+
+    // The API expects tags as a comma-separated string
+    if (data?.tags) {
+      updateTags = data.tags.join(",");
+    }
+
+    const response = await this.client.put<{ mind: Mind }>(`/minds/${mindId}`, {
+      ...data,
+      tags: updateTags,
+    });
+    return response.data.mind;
+  }
+
+  /**
+   * Delete a mind by ID
+   */
+  async delete(mindId: string): Promise<{ success: boolean }> {
+    const response = await this.client.delete<{ success: boolean }>(`/minds/${mindId}`);
+    return response.data;
+  }
+
+  /**
+   * Search minds
+   */
+  async search(params: SearchMindsParams): Promise<Mind[]> {
+    const response = await this.client.get<{ minds: Mind[] }>("/minds/search", {
+      params,
+    });
+    return response.data.minds;
+  }
+
+  /**
+   * Set tags for a mind (Replace existing)
+   */
+  async setTags(mindId: string, data: { tags: string[] }): Promise<Mind> {
+    const response = await this.client.put<{ mind: Mind }>(`/minds/${mindId}/tags`, {
+      tagNames: data.tags,
+    });
+    return response.data.mind;
+  }
+}

package/src/resources/psychometrics.ts

@@ -0,0 +1,16 @@
+import type { AxiosInstance } from "axios";
+import type { GetPsychometricsResponse } from "../types";
+
+export class PsychometricsResource {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * Get psychometrics for a specific snapshot
+   */
+  async get(snapshotId: string): Promise<GetPsychometricsResponse> {
+    const response = await this.client.get<GetPsychometricsResponse>(
+      `/snapshots/${snapshotId}/psychometrics`,
+    );
+    return response.data;
+  }
+}

package/src/resources/simulations.ts

@@ -0,0 +1,49 @@
+import type { AxiosInstance } from "axios";
+import type {
+  GetSimulationResponse,
+  ListSimulationsParams,
+  ListSimulationsResponse,
+  RunSimulationRequest,
+  SimulationResponse,
+} from "../types";
+
+export class SimulationsResource {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * Run simulation
+   */
+  async run(data: RunSimulationRequest): Promise<SimulationResponse> {
+    const response = await this.client.post<SimulationResponse>("/simulate", data);
+    return response.data;
+  }
+
+  /**
+   * List historical simulations
+   */
+  async list(params?: ListSimulationsParams): Promise<ListSimulationsResponse> {
+    const response = await this.client.get<ListSimulationsResponse>("/simulations", {
+      params,
+    });
+    return response.data;
+  }
+
+  /**
+   * Get a specific simulation by ID
+   */
+  async get(simulationId: string): Promise<GetSimulationResponse> {
+    const response = await this.client.get<GetSimulationResponse>(`/simulations/${simulationId}`);
+    return response.data;
+  }
+
+  /**
+   * Delete a specific simulation by ID
+   */
+  async delete(simulationId: string): Promise<{ message: string; simulationId: string }> {
+    const response = await this.client.delete<{
+      message: string;
+      simulationId: string;
+    }>(`/simulations/${simulationId}`);
+    return response.data;
+  }
+}

package/src/resources/snapshots.ts

@@ -0,0 +1,126 @@
+import path from "node:path"; // Import path
+import axios, { type AxiosInstance } from "axios";
+import FormData from "form-data";
+import type {
+  CreateSnapshotFromFileParams,
+  CreateSnapshotParams,
+  CreateSnapshotResponse,
+  GetSignedUrlResponse,
+  ListSnapshotsResponse,
+  SnapshotStatus,
+} from "../types";
+
+export class SnapshotsResource {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * Helper to infer content type from file extension
+   */
+  private getContentType(fileName: string): string {
+    const ext = path.extname(fileName).toLowerCase();
+    const mimeTypes: Record<string, string> = {
+      ".html": "text/html",
+      ".js": "text/javascript",
+      ".css": "text/css",
+      ".json": "application/json",
+      ".pdf": "application/pdf",
+      ".txt": "text/plain",
+      ".vtt": "text/vtt",
+      ".md": "text/markdown",
+      ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    };
+
+    return mimeTypes[ext] || "application/octet-stream";
+  }
+
+  /**
+   * List all snapshots for a mind
+   */
+  async list(mindId: string): Promise<ListSnapshotsResponse> {
+    const response = await this.client.get<ListSnapshotsResponse>(`/minds/${mindId}/snapshots`);
+    return response.data;
+  }
+
+  /**
+   * Create a snapshot via a signed url. Recommended for large files.
+   */
+  async create(mindId: string, params: CreateSnapshotParams): Promise<CreateSnapshotResponse> {
+    const finalContentType = params.contentType || this.getContentType(params.fileName);
+
+    const signedUrlRes = await this.client.get<GetSignedUrlResponse>(
+      `/minds/${mindId}/signed-url`,
+      {
+        params: {
+          fileName: params.fileName,
+          contentType: finalContentType,
+        },
+      },
+    );
+
+    const { signedUrl, artifactId } = signedUrlRes.data;
+
+    await axios.put(signedUrl, params.file, {
+      headers: {
+        "Content-Type": finalContentType,
+      },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    });
+
+    const form = new FormData();
+    form.append("artifactId", artifactId);
+
+    if (params.mindsetDate) {
+      form.append("mindsetDate", params.mindsetDate);
+    }
+
+    const snapshotRes = await this.client.post<CreateSnapshotResponse>(
+      `/minds/${mindId}/snapshots`,
+      form,
+      {
+        headers: {
+          ...form.getHeaders(),
+        },
+      },
+    );
+
+    return snapshotRes.data;
+  }
+
+  /**
+   * Create snapshot from uploaded file
+   */
+  async createFromFile(mindId: string, params: CreateSnapshotFromFileParams) {
+    const form = new FormData();
+
+    if (params.file) {
+      form.append("file", params.file, params.fileName || "upload.txt");
+    }
+
+    if (params.artifactId) {
+      form.append("artifactId", params.artifactId);
+    }
+
+    if (params.mindsetDate) {
+      form.append("mindsetDate", params.mindsetDate);
+    }
+
+    const response = await this.client.post(`/minds/${mindId}/snapshots`, form, {
+      headers: {
+        ...form.getHeaders(), // Crucial for multipart/form-data in Node
+      },
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Check snapshot status
+   */
+  async getStatus(mindId: string, snapshotId: string): Promise<SnapshotStatus> {
+    const response = await this.client.get<SnapshotStatus>(
+      `/minds/${mindId}/snapshots/${snapshotId}/status`,
+    );
+    return response.data;
+  }
+}

package/src/resources/tags.ts

@@ -0,0 +1,30 @@
+import type { AxiosInstance } from "axios";
+import type { Tag } from "../types";
+
+export class TagsResource {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * List all tags
+   */
+  async list(): Promise<Tag[]> {
+    const response = await this.client.get<{ tags: Tag[] }>("/tags");
+    return response.data.tags;
+  }
+
+  /**
+   * Update tag
+   */
+  async update(tagId: string, data: { name: string }): Promise<Tag> {
+    const response = await this.client.put<{ tag: Tag }>(`/tags/${tagId}`, data);
+    return response.data.tag;
+  }
+
+  /**
+   * Delete tag
+   */
+  async delete(tagId: string): Promise<{ deleted: boolean }> {
+    const response = await this.client.delete<{ deleted: boolean }>(`/tags/${tagId}`);
+    return response.data;
+  }
+}