@maximem/synap-js-sdk 0.1.1

package/src/bridge-manager.js

@@ -0,0 +1,262 @@
+const { spawn, spawnSync } = require('child_process');
+const readline = require('readline');
+const fs = require('fs');
+const {
+  resolveBridgeScriptPath,
+  resolvePythonBin,
+  resolveInstanceId,
+  setupPythonRuntime,
+} = require('./runtime');
+
+class BridgeManager {
+  constructor(options = {}) {
+    this.options = {
+      requestTimeoutMs: 30_000,
+      initTimeoutMs: 45_000,
+      ingestTimeoutMs: 120_000,
+      autoSetup: false,
+      ...options,
+    };
+
+    this.child = null;
+    this.stdoutReader = null;
+    this.stderrReader = null;
+    this.pending = new Map();
+    this.nextId = 1;
+    this.initPromise = null;
+  }
+
+  async ensureStarted() {
+    if (this.initPromise) return this.initPromise;
+
+    this.initPromise = (async () => {
+      const bridgeScript = resolveBridgeScriptPath(this.options.bridgeScriptPath);
+      const pythonBin = await this.#resolvePythonBinary();
+      this.#preflightPythonImport(pythonBin);
+
+      if (!fs.existsSync(bridgeScript)) {
+        throw new Error(`Bridge script not found at ${bridgeScript}`);
+      }
+
+      const bridgeEnv = {
+        ...process.env,
+        PYTHONUNBUFFERED: '1',
+        ...(this.options.pythonEnv || {}),
+      };
+
+      this.child = spawn(pythonBin, [bridgeScript], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: bridgeEnv,
+      });
+
+      this.#attachReaders();
+      this.#attachLifecycle();
+
+      const instanceId = resolveInstanceId(this.options.instanceId);
+
+      await this.sendCommand(
+        'init',
+        {
+          instance_id: instanceId,
+          bootstrap_token: this.options.bootstrapToken
+            || process.env.SYNAP_BOOTSTRAP_TOKEN
+            || process.env.SYNAP_BOOTSTRAP_KEY,
+          base_url: this.options.baseUrl || process.env.SYNAP_BASE_URL,
+          grpc_host: this.options.grpcHost || process.env.SYNAP_GRPC_HOST,
+          grpc_port: Number(this.options.grpcPort || process.env.SYNAP_GRPC_PORT || 50051),
+          grpc_use_tls: this.options.grpcUseTls ?? (process.env.SYNAP_GRPC_TLS === 'true'),
+        },
+        this.options.initTimeoutMs
+      );
+    })()
+      .catch((error) => {
+        this.initPromise = null;
+        throw error;
+      });
+
+    return this.initPromise;
+  }
+
+  async sendCommand(method, params = {}, timeoutMs = this.options.requestTimeoutMs) {
+    if (!this.child || !this.child.stdin || !this.child.stdin.writable) {
+      throw new Error('Synap bridge process is not running');
+    }
+
+    const id = this.nextId++;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Bridge command '${method}' timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      try {
+        this.child.stdin.write(`${JSON.stringify({ id, method, params })}\n`);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  async call(method, params = {}, timeoutMs) {
+    await this.ensureStarted();
+    return this.sendCommand(method, params, timeoutMs);
+  }
+
+  async shutdown() {
+    if (!this.child) return;
+
+    try {
+      await this.sendCommand('shutdown', {}, 10_000);
+    } catch (_) {
+      // Ignore shutdown RPC errors and continue with forced process stop.
+    }
+
+    const proc = this.child;
+    this.child = null;
+
+    setTimeout(() => {
+      if (proc && !proc.killed) proc.kill();
+    }, 1_500);
+
+    this.#resetState();
+  }
+
+  #attachReaders() {
+    this.stdoutReader = readline.createInterface({ input: this.child.stdout });
+    this.stderrReader = readline.createInterface({ input: this.child.stderr });
+
+    this.stdoutReader.on('line', (line) => {
+      let payload;
+
+      try {
+        payload = JSON.parse(line);
+      } catch (_) {
+        if (this.options.onLog) this.options.onLog('error', `Bad bridge JSON: ${line}`);
+        return;
+      }
+
+      const pending = this.pending.get(payload.id);
+      if (!pending) return;
+
+      clearTimeout(pending.timer);
+      this.pending.delete(payload.id);
+
+      if (payload.error) {
+        pending.reject(new Error(payload.error));
+      } else {
+        pending.resolve(payload.result);
+      }
+    });
+
+    this.stderrReader.on('line', (line) => {
+      if (this.options.onLog) this.options.onLog('debug', line);
+    });
+  }
+
+  #attachLifecycle() {
+    this.child.on('exit', (code) => {
+      const err = new Error(`Synap bridge exited with code ${code}`);
+      for (const [, pending] of this.pending) {
+        clearTimeout(pending.timer);
+        pending.reject(err);
+      }
+      this.#resetState();
+      if (this.options.onLog) this.options.onLog('error', err.message);
+    });
+
+    this.child.on('error', (error) => {
+      for (const [, pending] of this.pending) {
+        clearTimeout(pending.timer);
+        pending.reject(error);
+      }
+      this.#resetState();
+      if (this.options.onLog) this.options.onLog('error', error.message);
+    });
+  }
+
+  #resetState() {
+    this.pending.clear();
+    this.initPromise = null;
+
+    if (this.stdoutReader) {
+      this.stdoutReader.close();
+      this.stdoutReader = null;
+    }
+    if (this.stderrReader) {
+      this.stderrReader.close();
+      this.stderrReader = null;
+    }
+  }
+
+  async #resolvePythonBinary() {
+    const candidates = resolvePythonBin(this.options);
+
+    for (const candidate of candidates) {
+      if (!candidate) continue;
+      if (candidate.includes('/') || candidate.includes('\\')) {
+        if (fs.existsSync(candidate)) return candidate;
+        continue;
+      }
+
+      // Command-style candidate (python3/python).
+      return candidate;
+    }
+
+    if (this.options.autoSetup) {
+      const setupResult = await setupPythonRuntime({
+        sdkHome: this.options.sdkHome,
+        venvPath: this.options.venvPath,
+        pythonBootstrap: this.options.pythonBootstrap,
+        pythonPackage: this.options.pythonPackage,
+        pythonSdkVersion: this.options.pythonSdkVersion,
+        noDeps: this.options.noDeps,
+        noBuildIsolation: this.options.noBuildIsolation,
+        upgrade: this.options.upgrade,
+        forceRecreateVenv: this.options.forceRecreateVenv,
+      });
+      return setupResult.pythonBin;
+    }
+
+    throw new Error(
+      'No usable Python runtime found. Run `npx synap-js-sdk setup` or pass `pythonBin` in SynapClient options.'
+    );
+  }
+
+  #preflightPythonImport(pythonBin) {
+    const envBase = {
+      ...process.env,
+      ...(this.options.pythonEnv || {}),
+    };
+
+    const checkImport = (envExtra = {}) => {
+      const env = { ...envBase, ...envExtra };
+      return spawnSync(
+        pythonBin,
+        ['-c', 'import maximem_synap,sys; print(maximem_synap.__file__)'],
+        { env, encoding: 'utf8' }
+      );
+    };
+
+    const noPath = checkImport();
+    if (noPath.status !== 0) {
+      const details = [
+        `Python SDK import failed.`,
+        `pythonBin=${pythonBin}`,
+        `error=${(noPath.stderr || noPath.stdout || '').trim()}`,
+        `Hint: run 'synap-js-sdk setup --sdk-version <version>' to install maximem-synap from PyPI.`,
+      ].join('\n');
+      throw new Error(details);
+    }
+
+    if (this.options.onLog) {
+      this.options.onLog('debug', 'Python SDK import OK from installed package');
+    }
+  }
+}
+
+module.exports = { BridgeManager };

package/src/index.js

@@ -0,0 +1,11 @@
+const { SynapClient } = require('./synap-client');
+const { setupPythonRuntime, resolveInstanceId } = require('./runtime');
+const { setupTypeScriptExtension } = require('./setup-typescript');
+
+module.exports = {
+  SynapClient,
+  createClient: (options = {}) => new SynapClient(options),
+  setupPythonRuntime,
+  setupTypeScriptExtension,
+  resolveInstanceId,
+};

package/src/runtime.js

@@ -0,0 +1,161 @@
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+function isWindows() {
+  return process.platform === 'win32';
+}
+
+function getSdkHome(customHome) {
+  if (customHome) return customHome;
+  if (process.env.SYNAP_JS_SDK_HOME) return process.env.SYNAP_JS_SDK_HOME;
+  return path.join(os.homedir(), '.synap-js-sdk');
+}
+
+function getVenvPythonPath(venvPath) {
+  if (isWindows()) return path.join(venvPath, 'Scripts', 'python.exe');
+  return path.join(venvPath, 'bin', 'python');
+}
+
+function resolveBridgeScriptPath(customBridgeScriptPath) {
+  if (customBridgeScriptPath) return customBridgeScriptPath;
+  return path.join(__dirname, '..', 'bridge', 'synap_bridge.py');
+}
+
+function resolvePythonBin(options = {}) {
+  const candidates = [];
+
+  if (options.pythonBin) candidates.push(options.pythonBin);
+  if (process.env.SYNAP_PYTHON_BIN) candidates.push(process.env.SYNAP_PYTHON_BIN);
+
+  const sdkHome = getSdkHome(options.sdkHome);
+  const venvPath = options.venvPath || path.join(sdkHome, '.venv');
+  candidates.push(getVenvPythonPath(venvPath));
+
+  if (isWindows()) {
+    candidates.push('python.exe');
+    candidates.push('python');
+  } else {
+    candidates.push('python3');
+    candidates.push('python');
+  }
+
+  return candidates;
+}
+
+function resolveInstanceId(explicitInstanceId) {
+  if (explicitInstanceId) return explicitInstanceId;
+  if (process.env.SYNAP_INSTANCE_ID) return process.env.SYNAP_INSTANCE_ID;
+
+  try {
+    const instancesDir = path.join(os.homedir(), '.synap', 'instances');
+    if (!fs.existsSync(instancesDir)) return '';
+
+    const now = new Date();
+    let best = null;
+
+    for (const entry of fs.readdirSync(instancesDir)) {
+      const metadataPath = path.join(instancesDir, entry, 'metadata.json');
+      if (!fs.existsSync(metadataPath)) continue;
+
+      try {
+        const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+        const expiresAt = new Date(metadata.expires_at);
+        const issuedAt = new Date(metadata.issued_at);
+
+        if (Number.isNaN(expiresAt.getTime()) || Number.isNaN(issuedAt.getTime())) continue;
+        if (expiresAt <= now) continue;
+
+        if (!best || issuedAt > new Date(best.issued_at)) best = metadata;
+      } catch (_) {
+        // Ignore malformed metadata and continue scanning.
+      }
+    }
+
+    return best ? best.instance_id || '' : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+function runCommand(command, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...opts,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve({ code, stdout, stderr });
+      } else {
+        const err = new Error(`Command failed: ${command} ${args.join(' ')} (exit ${code})\n${stderr || stdout}`);
+        err.code = code;
+        err.stdout = stdout;
+        err.stderr = stderr;
+        reject(err);
+      }
+    });
+  });
+}
+
+async function setupPythonRuntime(options = {}) {
+  const sdkHome = getSdkHome(options.sdkHome);
+  const venvPath = options.venvPath || path.join(sdkHome, '.venv');
+  const pythonBootstrap = options.pythonBootstrap || process.env.SYNAP_PYTHON_BOOTSTRAP || (isWindows() ? 'python' : 'python3');
+  const pythonPackage = options.pythonPackage || process.env.SYNAP_PY_SDK_PACKAGE || 'maximem-synap';
+  const pythonSdkVersion = options.pythonSdkVersion || process.env.SYNAP_PY_SDK_VERSION || '';
+  const packageSpec = pythonSdkVersion ? `${pythonPackage}==${pythonSdkVersion}` : pythonPackage;
+  const pythonBin = getVenvPythonPath(venvPath);
+
+  fs.mkdirSync(sdkHome, { recursive: true });
+
+  if (!fs.existsSync(pythonBin) || options.forceRecreateVenv) {
+    await runCommand(pythonBootstrap, ['-m', 'venv', venvPath], { env: process.env });
+  }
+
+  await runCommand(pythonBin, ['-m', 'pip', 'install', '--upgrade', 'pip'], { env: process.env });
+
+  const installArgs = ['-m', 'pip', 'install'];
+  if (options.upgrade) installArgs.push('--upgrade');
+  if (options.noDeps) installArgs.push('--no-deps');
+  if (options.noBuildIsolation) installArgs.push('--no-build-isolation');
+  installArgs.push(packageSpec);
+
+  await runCommand(pythonBin, installArgs, { env: process.env });
+
+  return {
+    sdkHome,
+    venvPath,
+    pythonBin,
+    pythonPackage,
+    pythonSdkVersion: pythonSdkVersion || null,
+    installTarget: packageSpec,
+  };
+}
+
+module.exports = {
+  getSdkHome,
+  getVenvPythonPath,
+  resolveBridgeScriptPath,
+  resolvePythonBin,
+  resolveInstanceId,
+  setupPythonRuntime,
+  runCommand,
+};

package/src/setup-typescript.js

@@ -0,0 +1,141 @@
+const fs = require('fs');
+const path = require('path');
+const { runCommand } = require('./runtime');
+
+function detectPackageManager(projectDir, explicitPackageManager) {
+  if (explicitPackageManager) return explicitPackageManager;
+
+  if (fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(projectDir, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(projectDir, 'bun.lockb')) || fs.existsSync(path.join(projectDir, 'bun.lock'))) {
+    return 'bun';
+  }
+
+  return 'npm';
+}
+
+function getInstallArgs(packageManager) {
+  switch (packageManager) {
+    case 'pnpm':
+      return { command: 'pnpm', args: ['add', '-D', 'typescript', '@types/node'] };
+    case 'yarn':
+      return { command: 'yarn', args: ['add', '-D', 'typescript', '@types/node'] };
+    case 'bun':
+      return { command: 'bun', args: ['add', '-d', 'typescript', '@types/node'] };
+    case 'npm':
+      return { command: 'npm', args: ['install', '-D', 'typescript', '@types/node'] };
+    default:
+      throw new Error(`Unsupported package manager '${packageManager}'. Use npm, pnpm, yarn, or bun.`);
+  }
+}
+
+function writeFileIfNeeded(filePath, contents, force) {
+  if (fs.existsSync(filePath) && !force) {
+    return false;
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents, 'utf8');
+  return true;
+}
+
+function getTsconfigTemplate() {
+  return `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "types/**/*.d.ts"]
+}
+`;
+}
+
+function getWrapperTemplate() {
+  return `import {
+  createClient,
+  type SynapClient,
+  type SynapClientOptions,
+  type AddMemoryInput,
+  type SearchMemoryInput,
+  type GetMemoriesInput,
+  type DeleteMemoryInput,
+} from '@maximem/synap-js-sdk';
+
+export class SynapTsClient {
+  private readonly client: SynapClient;
+
+  constructor(options: SynapClientOptions = {}) {
+    this.client = createClient(options);
+  }
+
+  init() {
+    return this.client.init();
+  }
+
+  addMemory(input: AddMemoryInput) {
+    return this.client.addMemory(input);
+  }
+
+  searchMemory(input: SearchMemoryInput) {
+    return this.client.searchMemory(input);
+  }
+
+  getMemories(input: GetMemoriesInput) {
+    return this.client.getMemories(input);
+  }
+
+  deleteMemory(input: DeleteMemoryInput) {
+    return this.client.deleteMemory(input);
+  }
+
+  shutdown() {
+    return this.client.shutdown();
+  }
+}
+
+export const createTsClient = (options: SynapClientOptions = {}) => new SynapTsClient(options);
+`;
+}
+
+async function setupTypeScriptExtension(options = {}) {
+  const projectDir = path.resolve(options.projectDir || process.cwd());
+  const packageJsonPath = path.join(projectDir, 'package.json');
+
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`No package.json found in ${projectDir}. Run setup-ts inside a Node project.`);
+  }
+
+  const packageManager = detectPackageManager(projectDir, options.packageManager);
+  const tsconfigPath = path.resolve(projectDir, options.tsconfigPath || 'tsconfig.json');
+  const wrapperPath = path.resolve(projectDir, options.wrapperPath || path.join('src', 'synap.ts'));
+
+  if (!options.skipInstall) {
+    const install = getInstallArgs(packageManager);
+    await runCommand(install.command, install.args, { env: process.env, cwd: projectDir });
+  }
+
+  const tsconfigCreated = writeFileIfNeeded(tsconfigPath, getTsconfigTemplate(), options.force);
+  const wrapperCreated = options.noWrapper
+    ? false
+    : writeFileIfNeeded(wrapperPath, getWrapperTemplate(), options.force);
+
+  return {
+    projectDir,
+    packageManager,
+    installedDevDependencies: !options.skipInstall,
+    tsconfigPath,
+    tsconfigCreated,
+    wrapperPath: options.noWrapper ? null : wrapperPath,
+    wrapperCreated,
+  };
+}
+
+module.exports = {
+  setupTypeScriptExtension,
+};

package/src/synap-client.js

@@ -0,0 +1,83 @@
+const { BridgeManager } = require('./bridge-manager');
+
+class SynapClient {
+  constructor(options = {}) {
+    this.bridge = new BridgeManager(options);
+    this.options = {
+      ingestTimeoutMs: options.ingestTimeoutMs || 120_000,
+    };
+
+    this.#registerShutdownHooks();
+  }
+
+  async init() {
+    await this.bridge.ensureStarted();
+  }
+
+  async addMemory({ userId, messages }) {
+    this.#assert(userId, 'userId is required');
+    this.#assert(Array.isArray(messages), 'messages must be an array');
+
+    return this.bridge.call(
+      'add_memory',
+      { user_id: userId, messages },
+      this.options.ingestTimeoutMs
+    );
+  }
+
+  async searchMemory({ userId, query, maxResults = 10 }) {
+    this.#assert(userId, 'userId is required');
+    this.#assert(query, 'query is required');
+
+    return this.bridge.call('search_memory', {
+      user_id: userId,
+      query,
+      max_results: maxResults,
+    });
+  }
+
+  async getMemories({ userId }) {
+    this.#assert(userId, 'userId is required');
+
+    return this.bridge.call('get_memories', { user_id: userId });
+  }
+
+  async deleteMemory({ userId, memoryId = null }) {
+    this.#assert(userId, 'userId is required');
+
+    return this.bridge.call('delete_memory', {
+      user_id: userId,
+      memory_id: memoryId,
+    });
+  }
+
+  async shutdown() {
+    await this.bridge.shutdown();
+  }
+
+  #assert(value, message) {
+    if (!value) throw new Error(message);
+  }
+
+  #registerShutdownHooks() {
+    const close = async () => {
+      try {
+        await this.shutdown();
+      } catch (_) {
+        // Best-effort shutdown.
+      }
+    };
+
+    process.once('beforeExit', close);
+    process.once('SIGINT', async () => {
+      await close();
+      process.exit(0);
+    });
+    process.once('SIGTERM', async () => {
+      await close();
+      process.exit(0);
+    });
+  }
+}
+
+module.exports = { SynapClient };